{"slug":"developers/PACKAGES","title":"IntegrateWise Developer Platform","section":"developers","sectionLabel":"Developers","status":"unclassified","type":"document","path":"developers/PACKAGES.mdx","bytes":8958,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nCanonical package surface for external developers, AI agents, and partner apps.\n\n---\n\n## Publishable Packages (current release)\n\n| Package                       | Purpose                                                                            | Consumers                                    |\n| ----------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- |\n| `@integratewise/sdk`          | Governed Gateway client: resolve → prepare → explicit approval                     | Customer Zero, web, mobile, third-party apps |\n| `@integratewise/spine-schema` | Declarative Spine v1 fields, entities, workbench definitions, and registry helpers | Frontends, schema tooling, partner apps      |\n\nBoth packages produce ESM, CommonJS, and type declarations and are validated\nwith `pnpm --filter <package> pack:check` before publication.\n\n## Planned Public Packages\n\nThese names describe the intended platform surface. They are not yet publishable\nartifacts and must not be referenced by external consumers until they have a\nversioned package, generated declarations, and contract tests.\n\n| Package                                | Purpose                                                        | Consumers                                        |\n| -------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------ |\n| `@integratewise/contracts`             | Shared API contracts and schemas                               | All consumers                                    |\n| `@integratewise/types`                 | Shared TypeScript types                                        | All consumers                                    |\n| `@integratewise/events`                | Event contracts and streaming types                            | Integrations, webhooks, real-time apps           |\n| `@integratewise/capabilities`          | Capability definitions and resolver contracts                  | SDK, MCP Pool, governance                        |\n| `@integratewise/projections`           | Projection DTOs, contracts, and client                         | Workbench, dashboards, SharedWorkbench consumers |\n| `@integratewise/platform-api`          | Gateway API client and request/response contracts              | Frontends, mobile, third-party apps              |\n| `@integratewise/spine-schema-provider` | Resolved spine schema contracts/helpers per category+connector | Runtime, generators, SDK                         |\n| `@integratewise/connectors`            | Connector registry, metadata, OAuth definitions                | Marketplace, onboarding, runtime                 |\n| `@integratewise/connector-types`       | Pure types: manifests, capabilities, webhooks, sync            | SDK, runtime, external connector builders        |\n| `@integratewise/connector-sdk`         | Plugin SDK for building connectors                             | External developers                              |\n| `@integratewise/mcp-client`            | MCP Pool client for AI agents                                  | Claude Code, Cursor, Codex, Twin                 |\n\n---\n\n## Internal / Not Published\n\n| Package                        | Reason                                                 |\n| ------------------------------ | ------------------------------------------------------ |\n| `packages/projection-engine`   | Implementation detail; public surface is `projections` |\n| `packages/connector-contracts` | Superseded by `connector-types` and `connectors`       |\n| `packages/adk`                 | Internal agent toolkit                                 |\n| `packages/schema-ai`           | Internal AI schema tooling                             |\n| `packages/core-engine`         | Internal runtime                                       |\n| `services/*`                   | Deployment units, not npm packages                     |\n\n---\n\n## Connector Ecosystem\n\n```text\nPublic Developer Surface\n┌──────────────────────────────────────────────────┐\n│ @integratewise/connectors                        │\n│ @integratewise/connector-types                   │\n│ @integratewise/connector-sdk (optional)          │\n└──────────────────────────────────────────────────┘\n                      │\n                      ▼\nConnector Runtime (Platform)\nOAuth / Sync / Webhooks / Scheduling / State Machine\n                      │\n                      ▼\nIndividual Connector Implementations\nSalesforce / HubSpot / Slack / Gmail / Jira / ...\n```\n\n### Layer 1: Public Developer Surface\n\n**`@integratewise/connectors`** — What Customer Zero and third-party developers use:\n\n- `registerConnector()`\n- `listConnectors()`\n- `getConnectorMetadata()`\n- `validateConfiguration()`\n- `createConnection()`\n- `testConnection()`\n\n**`@integratewise/connector-types`** — Shared definitions:\n\n- `ConnectorManifest`\n- `ConnectorCapability`\n- `OAuthConfig`\n- `WebhookDefinition`\n- `SyncDefinition`\n- `EntityMapping`\n- `RateLimitPolicy`\n- `ConnectorStatus`\n\n**`@integratewise/connector-sdk`** — Optional SDK for external connector builders:\n\n```ts\n  id: \"my-crm\",\n  auth,\n  capabilities,\n  sync,\n  webhooks,\n});\n```\n\n### Layer 2: Connector Runtime (Platform)\n\n**Do NOT publish:**\n\n- `connector-manager`\n- `connector-sync`\n- `connector-webhook`\n- `connector-worker`\n- `oauth-service`\n- `scheduler`\n\nDeployed as Cloudflare Workers / services.\n\n### Layer 3: Individual Connector Implementations\n\n**Option A (recommended):** Independent packages\n\n```\n@integratewise/connector-salesforce\n@integratewise/connector-slack\n@integratewise/connector-gmail\n@integratewise/connector-jira\n```\n\n**Option B:** Bundle everything in `@integratewise/connectors`\n\n- Not recommended once you have 30–50 connectors\n\n---\n\n## Relationship with Platform\n\n```\nCustomer Zero / Third-party App\n        │\n        ▼\n   SDK + Contracts\n        │\n        ▼\n     Gateway\n        │\n        ▼\nConnector Runtime\n        │\n        ▼\nSalesforce Connector\n```\n\nCustomer Zero never imports connector implementations directly.\n\n---\n\n## Relationship with MCP\n\n```\nClaude Code / Cursor / Codex / Twin\n        │\n        ▼\nIntegrateWise MCP Pool\n        │\n        ▼\nGoverned Tools\nsearchCRM() / syncConnector() / refreshConnection()\n        │\n        ▼\nConnector Runtime\n        │\n        ▼\nSalesforce\n```\n\nMCP Pool exposes governed tools, not raw connector APIs.\n\n---\n\n## Versioning\n\n- SDK, contracts, types: coordinated semver via Changesets\n- Individual connectors: independent semver\n- Services: deployed via CI/CD, versioned in Cloudflare\n\nExample:\n\n```\nSDK                     2.1.0\nSalesforce Connector    1.4.2\nHubSpot Connector       3.0.0\nSlack Connector         2.7.1\n```\n\n---\n\n## Registry\n\n| Artifact                                        | Registry                            |\n| ----------------------------------------------- | ----------------------------------- |\n| Current public packages (`sdk`, `spine-schema`) | npm                                 |\n| Private/internal packages                       | GitHub Packages                     |\n| Cloudflare Workers                              | CF Deploy                           |\n| MCP Pool                                        | Deployed service with versioned API |\n\n---\n\n## Migration from Current Packages\n\n| Current                                       | Target                                            |\n| --------------------------------------------- | ------------------------------------------------- |\n| `packages/sdk`                                | `@integratewise/sdk`                              |\n| `packages/types`                              | `@integratewise/types`                            |\n| `packages/connectors`                         | `@integratewise/connectors`                       |\n| `packages/connector-contracts`                | `@integratewise/connector-types`                  |\n| `packages/projection-engine`                  | `@integratewise/projections` (public DTOs/client) |\n| `packages/webhooks`                           | `@integratewise/events`                           |\n| `packages/core`                               | `@integratewise/capabilities`                     |\n| `packages/gateway-sdk`                        | `@integratewise/platform-api`                     |\n| `packages/types/src/spine-schema-provider.ts` | `@integratewise/spine-schema-provider`            |\n| `packages/projection-engine`                  | Keep private; engine stays internal               |\n"}