86 lines
6.0 KiB
Markdown
86 lines
6.0 KiB
Markdown
# 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.
|
|
|