{"slug":"platform/08-connector-framework","title":"08 — Connector Framework","section":"platform","sectionLabel":"Platform","status":"unclassified","type":"document","path":"platform/08-connector-framework.mdx","bytes":3315,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **EXTRACTED / NOT CANONICAL.** Descope-authority and other conflicting claims\n> below are superseded. Use\n> [`../architecture/IMPLEMENTATION_CONTRACT_v1.1.md`](../architecture/IMPLEMENTATION_CONTRACT_v1.1.md).\n\n> **Extracted from:** IntegrateWise Platform Specification Suite\n> **Region:** first_pass\n> **Original line:** 929\n> **Lines:** 69 | **Chars:** 2,572\n> **Status:** Raw extraction — requires review and canonicalization\n\n08 — Connector Framework\n8.1 Responsibilities\nOwn connector lifecycle (declared → registered → healthy → degraded → retired).\nManage authentication, refresh, sync policy, retry, conflict, health.\n8.2 Lifecycle\nCopydeclared ──▶ sandboxed ──▶ certified ──▶ active ──▶ degraded ──▶ retired\n│ │ │\n▼ ▼ ▼\nrevoked recovering archived\n8.3 Adapter interface (canonical contract)\nCopyinterface ConnectorAdapter {\nid: string; // e.g., “salesforce”\nversion: string;\nscopes: string[];\n\n// discovery\ncapabilities(): CapabilityDescriptor[];\n\n// lifecycle\ninstall(ctx): Promise;\nuninstall(ctx): Promise;\nrefresh(ctx): Promise;\nhealth(): Promise;\n\n// data plane\npull(since): AsyncIterable;\npush(intent): Promise;\nrevert(intent, reason): Promise;\n\n// error model\nclassify(err): ErrorClass; // transient|permission|schema|rate|fatal\n}\n8.4 Authentication lifecycle\nOutbound connection authorization via **Descope** (canonical authorization authority where supported). IntegrateWise owns the connection binding and references Descope-managed authorization state; Descope owns the credential/token lifecycle and external authorization resource identity. Nango remains classified as legacy/dormant compatibility for providers Descope outbound does not yet support; it is not the default architecture.\n8.5 Sync policies\nSoft sync (default for sensitive industries), Real sync (default for high-volume mutations), Propose→Approve (default for high risk).\nConflict resolution deferred to Spine (02) by emitting a Connector Delta.\n8.6 Retry policy\nTransient: 5 attempts, exponential w/ jitter.\nPermission: 0 retry, surface via Workbench banner requiring admin action.\nSchema: 0 retry, dataclass outlier → admin queue.\nRate: token-bucket per vendor (Cloudflare Queue throttle).\nFatal: connector retired and HealthChanged emitted.\n8.7 Health monitoring\nHealthSnapshot { status: healthy|degraded|down, latency_ms, error_rate, last_sync_at, breaker_state }.\n\n8.8 Inputs\nVendor API events (webhooks), Connector Deltas.\nAdmin actions (install/uninstall/revoke).\n8.9 Outputs\nConnector Deltas → Spine (02).\nConnectorHealthyChanged events → Workflows, Signals.\n8.10 Events\nProduced: ConnectorInstalled, ConnectorSynced, ConnectorHealthyChanged, ConnectorDeltaReceived, ConnectorRefreshed, ConnectorRetired.\nConsumed: UserRoleChanged, WorkspaceArchived, TenantMerged.\n8.11 APIs\nPOST /connectors, DELETE /connectors/{conn_id}, POST /connectors/{conn_id}/sync, GET /connectors/{conn_id}/health.\n8.12 State transitions\nPer state machine in 8.2, with breaker transitions on health.\n\n8.13 Failure handling\nConsecutive failures > N → degraded then down, emit ConnectorHealthyChanged.\nBackoff + dead-letter queue (Cloudflare Queue).\n8.14 Extension points\nNew connectors authored against SDK (17).\nCustom retry policy per vendor.\n"}