igny8/master-docs/10-backend/integrations/THIRD-PARTY-SERVICES.md

Third-Party Services (Integrations)

Purpose

Document how site-level integrations are modeled and exposed via API, including WordPress connection testing, sync, and metadata updates.

Code Locations (exact paths)

• Models: backend/igny8_core/business/integration/models.py (SiteIntegration, SyncEvent)
• Services: backend/igny8_core/business/integration/services/integration_service.py, sync_service.py, sync_metadata_service.py, sync_health_service.py, content_sync_service.py
• API views and routing: backend/igny8_core/modules/integration/views.py, backend/igny8_core/modules/integration/urls.py
• Webhooks: backend/igny8_core/modules/integration/webhooks.py

High-Level Responsibilities

• Store per-site integration configs and credentials for platforms (WordPress, Shopify, custom).
• Provide CRUD, test-connection, sync, sync-status, and structure-update endpoints for integrations.
• Track sync events for debugging/monitoring.
• Enforce tenant/site scoping and role-based permissions on integration APIs.

Detailed Behavior

• Model behavior:
  • SiteIntegration: site+account scoped; fields for platform, platform_type, config_json (content types, sync settings), credentials_json (API keys, etc.), active/sync flags, sync status, last_sync_at, sync_error; unique per site+platform.
  • SyncEvent: per-integration/site event log with event_type/action, success flag, optional content_id/external_id, details JSON, error_message, duration, timestamps.
  • SiteIntegration.get_credentials / set_credentials currently store JSON as-is (encryption to be added).
• Service behavior (IntegrationService):
  • create_integration sets account from site and saves config/credentials with platform/platform_type.
  • update_integration updates config/credentials/is_active; delete_integration removes the record.
  • get_integration/list_integrations/get_integrations_for_site fetch active integrations by site/platform.
  • test_connection delegates to platform-specific testers (WordPress/Shopify implemented; others raise NotImplementedError).
• API (IntegrationViewSet, router /api/v1/integration/integrations/):
  • Inherits SiteSectorModelViewSet but overrides get_queryset to filter by site_id (no sector field).
  • Permissions: IsAuthenticatedAndActive + IsEditorOrAbove; throttle scope integration.
  • Serializer exposes derived api_key for WordPress; validates that WordPress integrations include an API key.
  • Actions:
    • test_connection (detail): calls IntegrationService.test_connection for the existing integration.
    • test_connection_collection (AllowAny, no throttle): accepts site_id/api_key/site_url; validates site ownership or matching Site.wp_api_key; creates WordPress integration if missing, tests via _test_wordpress_connection, deletes if test fails, returns integration_id on success.
    • sync: calls SyncService.sync (direction metadata/both/to_external/from_external); metadata-only uses SyncMetadataService.sync_wordpress_structure.
    • sync_status: returns sync status via SyncService.get_sync_status.
    • update_site_structure: updates config_json.content_types from WordPress push (post_types, taxonomies, plugin flags, timestamp).
    • get_content_types: returns content type config.
    • debug_status: uses SyncHealthService for debug data.
    • sync_wordpress_content: calls ContentSyncService.sync_from_wordpress for a specific content_id.
• Webhooks:
  • Registered under /api/v1/integration/webhooks/wordpress/status/ and /metadata/ for incoming WordPress callbacks (handling in webhooks.py).

Data Structures / Models Involved (no code)

• SiteIntegration config/credentials/sync flags/status/error.
• SyncEvent event logs.
• Site/account context from auth.models.Site and Account.

Execution Flow

• CRUD/test/sync requests → DRF auth → site-filtered queryset → service calls (integration/sync/health/content-sync) → model updates or sync actions.
• Collection-level test may create integration, run test, and delete on failure.
• Webhooks ingest external events; service handlers update integrations/sync events (implementation-specific).

Cross-Module Interactions

• Integrations reference sites and are consumed by publishing/sync flows when pushing/pulling content.
• WordPress API key path relies on Site.wp_api_key and integration credentials during connection tests.
• Sync services interact with planner/writer content when syncing content or structure.

State Transitions

• SiteIntegration.sync_status/last_sync_at update during sync; is_active/sync_enabled toggled via API.
• SyncEvent records per-action success/failure with timestamps and optional IDs.

Error Handling

• Unsupported platforms raise NotImplementedError; connection tests return structured success/message; newly created integrations are deleted if test fails in collection endpoint.
• API returns 403/404/400 for invalid site/auth/API key; sync errors surface in responses and may populate sync_error.

Tenancy Rules

• All integrations are site- and account-scoped; viewsets filter by site_id and require authenticated user with editor-or-above, or matching API key for collection-level WordPress test.

Billing Rules

• None; integration operations do not alter credits.

Background Tasks / Schedulers

• None dedicated; syncs run inline in service calls unless delegated inside sync services.

Key Design Considerations

• Unique integration per site+platform avoids duplication.
• Collection-level test supports plugin onboarding without prior authenticated session while still requiring site ownership or API key.
• Credentials are currently stored plain JSON—add encryption before production use.

How Developers Should Work With This Module

• Use IntegrationService for CRUD/test; avoid direct credential mutation outside service helpers.
• Extend platform support by adding platform-specific test logic and serializer validation.
• When adding new sync flows, use SyncService/SyncMetadataService/ContentSyncService and keep site/account scoping intact.