IntegrateWise Connector Layers

This document defines the five-layer connector model and what is published vs kept internal.

---

Layer Overview

                   Connector Ecosystem
                ```
                Public Developer Surface
                ┌──────────────────────────────────────────────────┐
                │ @integratewise/sdk                                │
                │ @integratewise/contracts                          │
                │ @integratewise/types                              │
                │ @integratewise/events                             │
                │ @integratewise/capabilities                       │
                │ @integratewise/projections                        │
                │ @integratewise/platform-api                       │
                │ @integratewise/spine-schema-provider              │
                │ @integratewise/connectors                         │
                │ @integratewise/connector-types                    │
                │ @integratewise/connector-sdk (optional)           │
                │ @integratewise/mcp-client                         │
                └──────────────────────────────────────────────────┘
                      │
                      ▼
┌──────────────────────────────────────────────────┐
│ Connector Runtime (Platform)                     │
│ OAuth / Sync / Webhooks / Scheduling / State      │
└──────────────────────────────────────────────────┘
                      │
                      ▼
┌──────────────────────────────────────────────────┐
│ Individual Connector Implementations             │
│ Salesforce / HubSpot / Slack / Gmail / Jira      │
└──────────────────────────────────────────────────┘

---

Layer 1: Public Developer Surface

Purpose: What external developers, Customer Zero, and partner apps consume.

1.1 @integratewise/connectors

Status: Publish to npm

Exports:

registerConnector();
listConnectors();
getConnectorMetadata();
validateConfiguration();
createConnection();
testConnection();

Contents:

• Connector registry
• Connector catalog
• Connection lifecycle
• OAuth flow initiation
• Metadata and capability declarations

Does NOT contain:

• Provider-specific implementations
• Sync logic
• Webhook handlers
• OAuth token storage

---

1.2 @integratewise/connector-types

Status: Publish to npm

Exports:

ConnectorManifest;
ConnectorCapability;
OAuthConfig;
WebhookDefinition;
SyncDefinition;
EntityMapping;
RateLimitPolicy;
ConnectorStatus;

Contents:

• Pure TypeScript types and interfaces
• Zod schemas for validation
• Constants and enums

Does NOT contain:

• Business logic
• HTTP clients
• Provider adapters

---

1.3 @integratewise/connector-sdk (optional)

Status: Publish to npm

Purpose: Enable external developers to build connectors.

Example:

  id: "my-crm",
  name: "My CRM",
  description: "Custom CRM integration",
  version: "1.0.0",
  auth: {
    type: "oauth",
    scopes: ["read:accounts", "write:contacts"],
    authorizationUrl: "https://example.com/oauth/authorize",
    tokenUrl: "https://example.com/oauth/token",
  },
  capabilities: [
    { id: "crm.accounts.read", name: "Read Accounts", requires: ["read:accounts"] },
    { id: "crm.contacts.write", name: "Write Contacts", requires: ["write:contacts"] },
  ],
  sync: {
    frequency: "hourly",
    entities: ["account", "contact"],
    webhooks: true,
  },
  webhooks: {
    events: ["account.created", "contact.updated"],
    verification: "signature",
  },
  entities: {
    account: {
      fields: [
        { name: "id", type: "string", primary: true },
        { name: "name", type: "string" },
        { name: "industry", type: "string" },
      ],
    },
  },
});

Contents:

• defineConnector() helper
• Validation utilities
• Connector manifest builder
• Lifecycle hooks

---

Layer 2: Connector Runtime (Platform)

Status: Do NOT publish to npm

Contents:

• services/connector — Connector manager
• services/connector-sync — Sync engine
• services/connector-webhook — Webhook ingestion
• services/oauth-service — OAuth flow handler
• services/scheduler — Sync scheduling

Deployment:

• Cloudflare Workers
• Durable Objects for state
• Queues for async processing

Consumers:

• Internal platform services only
• Accessed via Gateway service bindings
• Never imported by external packages

---

Layer 3: Individual Connector Implementations

Status: Deploy as Cloudflare Workers or include in connector-runtime

Option A: Independent packages (recommended)

packages/connectors/salesforce/
packages/connectors/hubspot/
packages/connectors/slack/
packages/connectors/gmail/
packages/connectors/jira/

Each with its own:

• package.json with independent version
• src/sync.ts — data extraction
• src/transform.ts — entity mapping
• src/webhooks.ts — event handling
• src/oauth.ts — provider-specific OAuth

Option B: Bundle everything

• Single @integratewise/connectors package
• Not recommended for 30+ connectors

---

Connector as Capability Provider

Connectors should declare capabilities, not just APIs:

connector: salesforce
provides:
  - crm.accounts.read
  - crm.contacts.read
  - crm.opportunities.read
  - crm.tasks.write
  - crm.notes.write

The platform resolves capabilities to connector implementations.

Customer Zero → SDK → Gateway → Capability Resolver → Connector Runtime → Salesforce

This means:

• Customer Zero invokes crm.accounts.read
• Platform routes to Salesforce connector
• Salesforce connector can be swapped without changing Customer Zero

---

Migration Guide

From @integratewise/connector-contracts to @integratewise/connector-types

Before:

After:

From packages/projection-engine to @integratewise/projections

Before:

After:

Engine implementation stays private.

---

Package Boundaries

Package	Contains	Does NOT contain
@integratewise/connectors	Registry, catalog, connection lifecycle	Provider implementations, sync logic
@integratewise/connector-types	Types, schemas, constants	Business logic, HTTP clients
@integratewise/connector-sdk	defineConnector(), validation, builder	Runtime, deployment, OAuth service
connector-runtime	OAuth, sync, webhooks, scheduler	Public types (use connector-types)
connector-salesforce	Salesforce sync, transform, webhooks	Generic connector logic (use connectors)

---

Versioning Strategy

• Public packages: Coordinated semver via Changesets
• Individual connectors: Independent semver
• Services: Deployed version, not npm version

Example:

@integratewise/sdk                   2.1.0
@integratewise/connectors            1.5.0
@integratewise/connector-types       1.5.0
@integratewise/connector-sdk         1.0.0
@integratewise/connector-salesforce  1.4.2
@integratewise/connector-hubspot     3.0.0
@integratewise/connector-slack       2.7.1

---

Security Considerations

• OAuth tokens never leave the Connector Runtime
• Refresh tokens stored in Cloudflare KV (encrypted)
• Webhook signatures verified at ingress
• Rate limiting enforced per connector
• Connector Runtime never exposes raw tokens to Gateway

---

Future: Connector Marketplace

When external developers publish connectors:

npm install @third-party/connector-notion

The platform validates:

• Connector manifest
• Capability declarations
• Security review
• Rate limits
• Data handling

Then registers it:

registerConnector(notionConnector);