This directory contains Python scripts designed to integrate with the SuperOffice CRM API, primarily for data enrichment and lead generation automation.

🚀 Production Deployment (March 2026)

Status: ✅ Live & Operational Environment: online3 (Production) Tenant: Cust26720

1. Architecture & Flow

Trigger: SuperOffice sends a webhook (contact.created, contact.changed, person.created, person.changed) to https://floke-ai.duckdns.org/connector/webhook.
Reception: webhook_app.py (FastAPI) receives the event, validates the WEBHOOK_TOKEN, and pushes a job to the SQLite queue (connector_queue.db).
Processing: worker.py (v1.9) polls the queue, filters for relevance, fetches details from SuperOffice, and calls the Company Explorer for AI analysis.
Sync: Results (Vertical, Summary, hyper-personalized Openers) are patched back into SuperOffice UserDefinedFields.

2. Operational Resilience (Lessons Learned)

🛡️ A. Noise Reduction & Loop Prevention

Problem: Every data update (PATCH) triggers a new contact.changed webhook, potentially creating infinite loops (Ping-Pong effect). Also, irrelevant changes (e.g., phone numbers) waste AI processing resources.
Solution: Strict Whitelist Filtering in worker.py.
- Contacts: Only changes to name, urladdress, urls, orgnr, or userdef_id (UDFs) trigger processing.
- Persons: Only changes to jobtitle, position_id, or userdef_id trigger processing.
- All other events are instantly marked as SKIPPED (visible in Dashboard).

📊 B. Dashboard & Sync-Runs

Problem: Continuous webhooks created hundreds of messy dashboard entries for the same account.
Solution: Sync-Run Clustering.
- Jobs for the same account occurring within 15 minutes of each other are grouped into a single "Sync-Run" row.
- Status Prioritization: A row shows COMPLETED if at least one job was successful, even if subsequent "echo" webhooks were SKIPPED.

🐞 C. The "Unhashable Dict" Mystery

Incident: During deployment, a TypeError: unhashable type: 'dict' occurred. Initial suspicion was a SuperOffice API bug.
Resolution: Deep analysis of raw JSON proved the API is healthy. The error was caused by a bug in the test/dashboard scripts (creating a dictionary literal using another dictionary as a key).
Lesson: Always verify raw API output (debug_raw_response.py) before blaming the vendor.

3. Tooling & Diagnosis

Located in connector-superoffice/tools/:

verify_enrichment.py: Verifies if AI data actually landed in SuperOffice (using raw text search).
create_company.py: Creates a test company in Prod to trigger the flow.
full_discovery.py: Lists all available UDFs and Lists on the current tenant.
final_truth_check.py: Validates JSON structure of API responses.
who_am_i.py: Identifies the API user's Associate ID.

4. Open Todos

List ID Mapping: Identify the correct List ID for the "Vertical" field (ProgID SuperOffice:83). udlist331 returned 404.
Mailing Identity: Resolve 500 error on Associate/Me. Required for automated "Send As" mailing functionality.
Docker Build: Optimize connector-superoffice build time (>8 mins) using Multi-Stage Dockerfiles to avoid C-compilation on every deploy.

Authentication (Legacy)

Authentication is handled via the AuthHandler class, which uses a refresh token flow to obtain access tokens. Ensure that the .env file in the project root is correctly configured with SO_CLIENT_ID, SO_CLIENT_SECRET, SO_REFRESH_TOKEN, SO_REDIRECT_URI, SO_ENVIRONMENT, and SO_CONTEXT_IDENTIFIER.

Key SuperOffice Entities and Data Model Observations

(See full file for historical notes on Sale Entity and Product Information Storage)