example_complete.py

#!/usr/bin/env python3
"""
Comprehensive example demonstrating all Dotloop API endpoints.

This example shows how to use every implemented endpoint in the Dotloop API wrapper.
Make sure to set your DOTLOOP_API_KEY environment variable or pass it directly.
"""

import os
from typing import Any, Dict, List

from dotloop import AuthClient, DotloopClient
from dotloop.enums import (
    LoopStatus,
    ParticipantRole,
    ProfileType,
    TransactionType,
    WebhookEventType,
)


def main() -> None:
    """Demonstrate all Dotloop API functionality."""

    # Initialize the main client
    # Option 1: Use environment variable DOTLOOP_API_KEY
    client = DotloopClient()

    # Option 2: Pass API key directly
    # client = DotloopClient(api_key="your_api_key_here")

    print("🚀 Dotloop API Wrapper - Complete Example")
    print("=" * 50)

    try:
        # 1. ACCOUNT ENDPOINTS
        print("\n📋 1. ACCOUNT INFORMATION")
        print("-" * 30)
        account = client.account.get_account()
        print(f"Account ID: {account['data']['id']}")
        print(f"Account Name: {account['data']['name']}")

        # 2. PROFILE ENDPOINTS
        print("\n👤 2. PROFILE MANAGEMENT")
        print("-" * 30)

        # List all profiles
        profiles = client.profile.list_profiles()
        print(f"Found {len(profiles['data'])} profiles")

        if profiles["data"]:
            profile_id = profiles["data"][0]["id"]
            print(f"Using profile ID: {profile_id}")

            # Get specific profile
            profile = client.profile.get_profile(profile_id=profile_id)
            print(f"Profile: {profile['data']['name']}")

            # Create a new profile (commented out to avoid creating test data)
            # new_profile = client.profile.create_profile(
            #     name="Test Profile",
            #     company="Test Company",
            #     phone="+1 (555) 123-4567"
            # )

            # Update profile (commented out)
            # updated_profile = client.profile.update_profile(
            #     profile_id=profile_id,
            #     phone="+1 (555) 999-8888"
            # )

        # 3. LOOP ENDPOINTS
        print("\n🔄 3. LOOP MANAGEMENT")
        print("-" * 30)

        if profiles["data"]:
            # List loops
            loops = client.loop.list_loops(profile_id=profile_id)
            print(f"Found {len(loops['data'])} loops")

            if loops["data"]:
                loop_id = loops["data"][0]["id"]
                print(f"Using loop ID: {loop_id}")

                # Get specific loop
                loop = client.loop.get_loop(profile_id=profile_id, loop_id=loop_id)
                print(f"Loop: {loop['data']['name']}")
                print(f"Status: {loop['data']['status']}")
                print(f"Transaction Type: {loop['data']['transactionType']}")

            # Create a new loop (commented out)
            # new_loop = client.loop.create_loop(
            #     profile_id=profile_id,
            #     name="Example Transaction",
            #     transaction_type=TransactionType.PURCHASE_OFFER,
            #     status=LoopStatus.PRE_OFFER
            # )

        # 4. LOOP-IT ENDPOINT (Create loop from template)
        print("\n⚡ 4. LOOP-IT (Template-based Loop Creation)")
        print("-" * 30)

        # Create loop with Loop-It (commented out)
        # loop_it_result = client.loop_it.create_loop(
        #     name="Quick Transaction",
        #     transaction_type=TransactionType.PURCHASE_OFFER,
        #     status=LoopStatus.PRE_OFFER,
        #     profile_id=profile_id,
        #     street_number="123",
        #     street_name="Main Street",
        #     city="San Francisco",
        #     state="CA",
        #     zip_code="94105"
        # )
        print("Loop-It endpoint available for quick loop creation from templates")

        # 5. CONTACT ENDPOINTS
        print("\n📞 5. CONTACT MANAGEMENT")
        print("-" * 30)

        # List contacts
        contacts = client.contact.list_contacts()
        print(f"Found {len(contacts['data'])} contacts")

        if contacts["data"]:
            contact_id = contacts["data"][0]["id"]

            # Get specific contact
            contact = client.contact.get_contact(contact_id=contact_id)
            print(
                f"Contact: {contact['data']['firstName']} {contact['data']['lastName']}"
            )

        # Create a new contact (commented out)
        # new_contact = client.contact.create_contact(
        #     first_name="John",
        #     last_name="Doe",
        #     email="john.doe@example.com",
        #     phone="+1 (555) 123-4567"
        # )

        # 6. LOOP DETAILS
        print("\n📝 6. LOOP DETAILS")
        print("-" * 30)

        if profiles["data"] and loops["data"]:
            # Get loop details
            details = client.loop_detail.get_loop_details(
                profile_id=profile_id, loop_id=loop_id
            )
            print("Loop details retrieved successfully")

            # Update loop details (commented out)
            # updated_details = client.loop_detail.update_loop_details(
            #     profile_id=profile_id,
            #     loop_id=loop_id,
            #     purchase_price=500000,
            #     listing_price=525000
            # )

        # 7. FOLDER MANAGEMENT
        print("\n📁 7. FOLDER MANAGEMENT")
        print("-" * 30)

        if profiles["data"] and loops["data"]:
            # List folders
            folders = client.folder.list_folders(profile_id=profile_id, loop_id=loop_id)
            print(f"Found {len(folders['data'])} folders")

            if folders["data"]:
                folder_id = folders["data"][0]["id"]

                # Get specific folder
                folder = client.folder.get_folder(
                    profile_id=profile_id, loop_id=loop_id, folder_id=folder_id
                )
                print(f"Folder: {folder['data']['name']}")

        # 8. DOCUMENT MANAGEMENT
        print("\n📄 8. DOCUMENT MANAGEMENT")
        print("-" * 30)

        if profiles["data"] and loops["data"]:
            # List documents
            documents = client.document.list_documents(
                profile_id=profile_id, loop_id=loop_id
            )
            print(f"Found {len(documents['data'])} documents")

            if documents["data"]:
                document_id = documents["data"][0]["id"]

                # Get specific document
                document = client.document.get_document(
                    profile_id=profile_id, loop_id=loop_id, document_id=document_id
                )
                print(f"Document: {document['data']['name']}")
                print(f"Size: {document['data']['size']} bytes")

        # 9. PARTICIPANT MANAGEMENT
        print("\n👥 9. PARTICIPANT MANAGEMENT")
        print("-" * 30)

        if profiles["data"] and loops["data"]:
            # List participants
            participants = client.participant.list_participants(
                profile_id=profile_id, loop_id=loop_id
            )
            print(f"Found {len(participants['data'])} participants")

            if participants["data"]:
                participant_id = participants["data"][0]["id"]

                # Get specific participant
                participant = client.participant.get_participant(
                    profile_id=profile_id,
                    loop_id=loop_id,
                    participant_id=participant_id,
                )
                print(f"Participant: {participant['data']['fullName']}")
                print(f"Role: {participant['data']['role']}")

        # 10. TASK MANAGEMENT
        print("\n✅ 10. TASK MANAGEMENT")
        print("-" * 30)

        if profiles["data"] and loops["data"]:
            # List task lists
            task_lists = client.task.list_task_lists(
                profile_id=profile_id, loop_id=loop_id
            )
            print(f"Found {len(task_lists['data'])} task lists")

            if task_lists["data"]:
                tasklist_id = task_lists["data"][0]["id"]

                # Get specific task list
                task_list = client.task.get_task_list(
                    profile_id=profile_id, loop_id=loop_id, tasklist_id=tasklist_id
                )
                print(f"Task List: {task_list['data']['name']}")

                # List tasks in the task list
                tasks = client.task.list_tasks(
                    profile_id=profile_id, loop_id=loop_id, tasklist_id=tasklist_id
                )
                print(f"Found {len(tasks['data'])} tasks in list")

        # 11. ACTIVITY FEED
        print("\n📊 11. ACTIVITY FEED")
        print("-" * 30)

        if profiles["data"] and loops["data"]:
            # List loop activity
            activities = client.activity.list_loop_activity(
                profile_id=profile_id, loop_id=loop_id
            )
            print(f"Found {len(activities['data'])} activities")

            # Get activity summary
            summary = client.activity.get_activity_summary(
                profile_id=profile_id, loop_id=loop_id
            )
            print(f"Total activities: {summary['total_activities']}")
            print(f"Unique users: {summary['unique_users']}")

        # 12. TEMPLATE MANAGEMENT
        print("\n📋 12. TEMPLATE MANAGEMENT")
        print("-" * 30)

        if profiles["data"]:
            # List loop templates
            templates = client.template.list_loop_templates(profile_id=profile_id)
            print(f"Found {len(templates['data'])} templates")

            if templates["data"]:
                template_id = templates["data"][0]["id"]

                # Get specific template
                template = client.template.get_loop_template(
                    profile_id=profile_id, template_id=template_id
                )
                print(f"Template: {template['data']['name']}")
                print(f"Type: {template['data']['type']}")
                print(f"Default: {template['data']['isDefault']}")

        # 13. WEBHOOK MANAGEMENT
        print("\n🔗 13. WEBHOOK MANAGEMENT")
        print("-" * 30)

        # List webhook subscriptions
        subscriptions = client.webhook.list_subscriptions()
        print(f"Found {len(subscriptions['data'])} webhook subscriptions")

        if subscriptions["data"]:
            subscription_id = subscriptions["data"][0]["id"]

            # Get specific subscription
            subscription = client.webhook.get_subscription(
                subscription_id=subscription_id
            )
            print(f"Webhook: {subscription['data']['url']}")
            print(f"Enabled: {subscription['data'].get('enabled')}")

            # List events for subscription
            events = client.webhook.list_events(subscription_id=subscription_id)
            print(f"Found {len(events['data'])} webhook events")

        # Create a new webhook subscription (commented out)
        # new_webhook = client.webhook.create_subscription(
        #     url="https://your-app.com/webhook",
        #     target_type="PROFILE",
        #     target_id=15637525,
        #     event_types=[WebhookEventType.LOOP_CREATED, WebhookEventType.CONTACT_CREATED],
        #     enabled=True,
        # )

        print("\n✅ All endpoint demonstrations completed successfully!")

    except Exception as e:
        print(f"❌ Error: {e}")
        print("Make sure you have set your DOTLOOP_API_KEY environment variable")


def demonstrate_oauth_flow() -> None:
    """Demonstrate OAuth authentication flow."""
    print("\n🔐 OAUTH AUTHENTICATION FLOW")
    print("-" * 30)

    # Initialize OAuth client
    auth_client = AuthClient(
        client_id="your_client_id",
        client_secret="your_client_secret",
        redirect_uri="https://your-app.com/callback",
        api_key="dummy_key",  # OAuth client doesn't need real API key for auth flow
    )

    # Get authorization URL
    auth_url = auth_client.get_authorization_url(
        scope=["account", "profile", "loop"], state="csrf_protection_token"
    )
    print(f"Authorization URL: {auth_url}")

    # Get OAuth flow helper
    flow_helper = auth_client.get_oauth_flow_helper(
        scope=["account", "profile"], state="csrf_token"
    )
    print("\nOAuth Flow Instructions:")
    for i, instruction in enumerate(flow_helper["instructions"], 1):
        print(f"{i}. {instruction}")

    # After user authorizes and you get the code:
    # token_response = auth_client.exchange_code_for_token("authorization_code_here")
    # access_token = token_response["access_token"]

    # Use the access token with the main client:
    # client = DotloopClient(api_key=access_token)


def demonstrate_advanced_features() -> None:
    """Demonstrate advanced features and convenience methods."""
    print("\n🚀 ADVANCED FEATURES")
    print("-" * 30)

    client = DotloopClient()

    try:
        # Get account info
        account = client.account.get_account()
        profiles = client.profile.list_profiles()

        if profiles["data"]:
            profile_id = profiles["data"][0]["id"]
            loops = client.loop.list_loops(profile_id=profile_id)

            if loops["data"]:
                loop_id = loops["data"][0]["id"]

                # Convenience methods for participants
                print("Participant convenience methods:")

                # Add different types of participants (commented out)
                # buyer = client.participant.add_buyer(
                #     profile_id=profile_id,
                #     loop_id=loop_id,
                #     full_name="John Buyer",
                #     email="buyer@example.com"
                # )

                # seller = client.participant.add_seller(
                #     profile_id=profile_id,
                #     loop_id=loop_id,
                #     full_name="Jane Seller",
                #     email="seller@example.com"
                # )

                # agent = client.participant.add_agent(
                #     profile_id=profile_id,
                #     loop_id=loop_id,
                #     full_name="Bob Agent",
                #     email="agent@realty.com",
                #     role=ParticipantRole.BUYING_AGENT
                # )

                # Template filtering
                print("Template filtering:")

                # Get templates by type
                purchase_templates = client.template.get_templates_by_type(
                    profile_id=profile_id, template_type="PURCHASE"
                )
                print(f"Found {len(purchase_templates['data'])} purchase templates")

                # Get default templates
                default_templates = client.template.get_default_templates(
                    profile_id=profile_id
                )
                print(f"Found {len(default_templates['data'])} default templates")

                # Activity filtering
                print("Activity filtering:")

                # Get recent activity
                recent_activity = client.activity.get_recent_activity(
                    profile_id=profile_id, loop_id=loop_id, limit=5
                )
                print(f"Found {len(recent_activity['data'])} recent activities")

                # Filter activity by type
                doc_activities = client.activity.get_activity_by_type(
                    profile_id=profile_id,
                    loop_id=loop_id,
                    activity_type="DOCUMENT_UPLOADED",
                )
                print(f"Found {len(doc_activities['data'])} document upload activities")

                # Task management
                print("Task management:")

                # Get all tasks in loop
                all_tasks = client.task.get_all_tasks_in_loop(
                    profile_id=profile_id, loop_id=loop_id
                )
                print(f"Found {len(all_tasks['data'])} total tasks in loop")

                # Get task summary
                task_summary = client.task.get_task_summary(
                    profile_id=profile_id, loop_id=loop_id
                )
                print(f"Task completion rate: {task_summary['completion_rate']:.1%}")

                # Webhook management
                print("Webhook management:")

                # Get webhook summary
                webhook_summary = client.webhook.get_all_subscriptions_summary()
                print(f"Total webhooks: {webhook_summary['total_subscriptions']}")
                print(f"Active webhooks: {webhook_summary['active_subscriptions']}")

        print("✅ Advanced features demonstration completed!")

    except Exception as e:
        print(f"❌ Error in advanced features: {e}")


if __name__ == "__main__":
    # Check if API key is available
    api_key = os.getenv("DOTLOOP_API_KEY")
    if not api_key:
        print("⚠️  Warning: DOTLOOP_API_KEY environment variable not set")
        print("Some examples may not work without a valid API key")
        print()

    # Run main demonstration
    main()

    # Demonstrate OAuth flow (doesn't require API key)
    demonstrate_oauth_flow()

    # Demonstrate advanced features
    if api_key:
        demonstrate_advanced_features()
    else:
        print("\n⚠️  Skipping advanced features demo - API key required")

    print("\n🎉 Complete Dotloop API demonstration finished!")
    print(
        "\nFor more information, check the documentation and individual endpoint examples."
    )