{"slug":"connectors/CONNECTOR_LAYERS","title":"IntegrateWise Connector Layers","section":"connectors","sectionLabel":"Connectors","status":"unclassified","type":"document","path":"connectors/CONNECTOR_LAYERS.mdx","bytes":9322,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nThis document defines the five-layer connector model and what is published vs kept internal.\n\n---\n\n## Layer Overview\n\n````\n                   Connector Ecosystem\n                ```\n                Public Developer Surface\n                ┌──────────────────────────────────────────────────┐\n                │ @integratewise/sdk                                │\n                │ @integratewise/contracts                          │\n                │ @integratewise/types                              │\n                │ @integratewise/events                             │\n                │ @integratewise/capabilities                       │\n                │ @integratewise/projections                        │\n                │ @integratewise/platform-api                       │\n                │ @integratewise/spine-schema-provider              │\n                │ @integratewise/connectors                         │\n                │ @integratewise/connector-types                    │\n                │ @integratewise/connector-sdk (optional)           │\n                │ @integratewise/mcp-client                         │\n                └──────────────────────────────────────────────────┘\n                      │\n                      ▼\n┌──────────────────────────────────────────────────┐\n│ Connector Runtime (Platform)                     │\n│ OAuth / Sync / Webhooks / Scheduling / State      │\n└──────────────────────────────────────────────────┘\n                      │\n                      ▼\n┌──────────────────────────────────────────────────┐\n│ Individual Connector Implementations             │\n│ Salesforce / HubSpot / Slack / Gmail / Jira      │\n└──────────────────────────────────────────────────┘\n````\n\n---\n\n## Layer 1: Public Developer Surface\n\n**Purpose:** What external developers, Customer Zero, and partner apps consume.\n\n### 1.1 `@integratewise/connectors`\n\n**Status:** Publish to npm\n\n**Exports:**\n\n```ts\nregisterConnector();\nlistConnectors();\ngetConnectorMetadata();\nvalidateConfiguration();\ncreateConnection();\ntestConnection();\n```\n\n**Contents:**\n\n- Connector registry\n- Connector catalog\n- Connection lifecycle\n- OAuth flow initiation\n- Metadata and capability declarations\n\n**Does NOT contain:**\n\n- Provider-specific implementations\n- Sync logic\n- Webhook handlers\n- OAuth token storage\n\n---\n\n### 1.2 `@integratewise/connector-types`\n\n**Status:** Publish to npm\n\n**Exports:**\n\n```ts\nConnectorManifest;\nConnectorCapability;\nOAuthConfig;\nWebhookDefinition;\nSyncDefinition;\nEntityMapping;\nRateLimitPolicy;\nConnectorStatus;\n```\n\n**Contents:**\n\n- Pure TypeScript types and interfaces\n- Zod schemas for validation\n- Constants and enums\n\n**Does NOT contain:**\n\n- Business logic\n- HTTP clients\n- Provider adapters\n\n---\n\n### 1.3 `@integratewise/connector-sdk` (optional)\n\n**Status:** Publish to npm\n\n**Purpose:** Enable external developers to build connectors.\n\n**Example:**\n\n```ts\n\n  id: \"my-crm\",\n  name: \"My CRM\",\n  description: \"Custom CRM integration\",\n  version: \"1.0.0\",\n  auth: {\n    type: \"oauth\",\n    scopes: [\"read:accounts\", \"write:contacts\"],\n    authorizationUrl: \"https://example.com/oauth/authorize\",\n    tokenUrl: \"https://example.com/oauth/token\",\n  },\n  capabilities: [\n    { id: \"crm.accounts.read\", name: \"Read Accounts\", requires: [\"read:accounts\"] },\n    { id: \"crm.contacts.write\", name: \"Write Contacts\", requires: [\"write:contacts\"] },\n  ],\n  sync: {\n    frequency: \"hourly\",\n    entities: [\"account\", \"contact\"],\n    webhooks: true,\n  },\n  webhooks: {\n    events: [\"account.created\", \"contact.updated\"],\n    verification: \"signature\",\n  },\n  entities: {\n    account: {\n      fields: [\n        { name: \"id\", type: \"string\", primary: true },\n        { name: \"name\", type: \"string\" },\n        { name: \"industry\", type: \"string\" },\n      ],\n    },\n  },\n});\n```\n\n**Contents:**\n\n- `defineConnector()` helper\n- Validation utilities\n- Connector manifest builder\n- Lifecycle hooks\n\n---\n\n## Layer 2: Connector Runtime (Platform)\n\n**Status:** Do NOT publish to npm\n\n**Contents:**\n\n- `services/connector` — Connector manager\n- `services/connector-sync` — Sync engine\n- `services/connector-webhook` — Webhook ingestion\n- `services/oauth-service` — OAuth flow handler\n- `services/scheduler` — Sync scheduling\n\n**Deployment:**\n\n- Cloudflare Workers\n- Durable Objects for state\n- Queues for async processing\n\n**Consumers:**\n\n- Internal platform services only\n- Accessed via Gateway service bindings\n- Never imported by external packages\n\n---\n\n## Layer 3: Individual Connector Implementations\n\n**Status:** Deploy as Cloudflare Workers or include in connector-runtime\n\n**Option A: Independent packages (recommended)**\n\n```\npackages/connectors/salesforce/\npackages/connectors/hubspot/\npackages/connectors/slack/\npackages/connectors/gmail/\npackages/connectors/jira/\n```\n\nEach with its own:\n\n- `package.json` with independent version\n- `src/sync.ts` — data extraction\n- `src/transform.ts` — entity mapping\n- `src/webhooks.ts` — event handling\n- `src/oauth.ts` — provider-specific OAuth\n\n**Option B: Bundle everything**\n\n- Single `@integratewise/connectors` package\n- Not recommended for 30+ connectors\n\n---\n\n## Connector as Capability Provider\n\nConnectors should declare capabilities, not just APIs:\n\n```yaml\nconnector: salesforce\nprovides:\n  - crm.accounts.read\n  - crm.contacts.read\n  - crm.opportunities.read\n  - crm.tasks.write\n  - crm.notes.write\n```\n\nThe platform resolves capabilities to connector implementations.\n\n```\nCustomer Zero → SDK → Gateway → Capability Resolver → Connector Runtime → Salesforce\n```\n\nThis means:\n\n- Customer Zero invokes `crm.accounts.read`\n- Platform routes to Salesforce connector\n- Salesforce connector can be swapped without changing Customer Zero\n\n---\n\n## Migration Guide\n\n### From `@integratewise/connector-contracts` to `@integratewise/connector-types`\n\n**Before:**\n\n```ts\n```\n\n**After:**\n\n```ts\n```\n\n### From `packages/projection-engine` to `@integratewise/projections`\n\n**Before:**\n\n```ts\n```\n\n**After:**\n\n```ts\n```\n\nEngine implementation stays private.\n\n---\n\n## Package Boundaries\n\n| Package                          | Contains                                 | Does NOT contain                           |\n| -------------------------------- | ---------------------------------------- | ------------------------------------------ |\n| `@integratewise/connectors`      | Registry, catalog, connection lifecycle  | Provider implementations, sync logic       |\n| `@integratewise/connector-types` | Types, schemas, constants                | Business logic, HTTP clients               |\n| `@integratewise/connector-sdk`   | `defineConnector()`, validation, builder | Runtime, deployment, OAuth service         |\n| `connector-runtime`              | OAuth, sync, webhooks, scheduler         | Public types (use `connector-types`)       |\n| `connector-salesforce`           | Salesforce sync, transform, webhooks     | Generic connector logic (use `connectors`) |\n\n---\n\n## Versioning Strategy\n\n- **Public packages:** Coordinated semver via Changesets\n- **Individual connectors:** Independent semver\n- **Services:** Deployed version, not npm version\n\nExample:\n\n```\n@integratewise/sdk                   2.1.0\n@integratewise/connectors            1.5.0\n@integratewise/connector-types       1.5.0\n@integratewise/connector-sdk         1.0.0\n@integratewise/connector-salesforce  1.4.2\n@integratewise/connector-hubspot     3.0.0\n@integratewise/connector-slack       2.7.1\n```\n\n---\n\n## Security Considerations\n\n- OAuth tokens never leave the Connector Runtime\n- Refresh tokens stored in Cloudflare KV (encrypted)\n- Webhook signatures verified at ingress\n- Rate limiting enforced per connector\n- Connector Runtime never exposes raw tokens to Gateway\n\n---\n\n## Future: Connector Marketplace\n\nWhen external developers publish connectors:\n\n```bash\nnpm install @third-party/connector-notion\n```\n\nThe platform validates:\n\n- Connector manifest\n- Capability declarations\n- Security review\n- Rate limits\n- Data handling\n\nThen registers it:\n\n```ts\n\nregisterConnector(notionConnector);\n```\n"}