Connector SDK
Connectors link PRESHos Platform to external applications. The framing from the product source (docs/development/connector-sdk.md, last reviewed 2026-09-06) is exact:
Integration packages own auth, install, config, and scheduling. The Connector SDK is the reusable inbound record import layer: discover objects, map fields, create and update mapped records, record outcomes.
Packages handle how a connector plugs in; the SDK handles how records flow in. Keep that split in mind. It explains where every piece below lives.
Sources: rewritten from docs/development/connector-sdk.md (last reviewed 2026-09-06) and docs/architecture/connector-tenant-contract.md, via product-repo access. Paths are relative to the PRESHos product repo unless noted. Anything still unconfirmed is marked not in pasted sources, never guessed.
Guides
Section titled “Guides”Concepts: integration packages vs. the SDK, the inbound-import pipeline, registered adapters, and the code-is-not-connected rule.
Auth: the tenant contract. Tenant host vs. canonical host, OAuth state HMAC, callback allowlist, Tenant Vault and GCP SM secrets.
Lifecycle: from code to connected. Register, implement, register the factory, run, verify, operate. Watermarks, contract tests, retirement.
Build a connector: the add-a-connector sequence with the copy-paste factory boundary and per-stage definitions of done.
Extend a connector: bindings, destinations, and the safety rules, including what you must never do.
Examples: the factory skeleton from source, the destination example, and the adapter contract-test sequence.
Worked example: HubSpot e2e import: the Connector SDK end to end against the HubSpot registered adapter — for FDEs wiring a first connector; proves factory, bindings, authorized sync, and contract tests in one runnable pass.
Layers and entry points
Section titled “Layers and entry points”| Layer | Owns | Key entry points (product repo) |
|---|---|---|
| Integration package | Auth, install, config, scheduling | lib/integrations/packages/types.ts, /automations/connectors/[packageKey] |
| Connector SDK (server) | Inbound record import | lib/integrations/crm-sync/index.ts |
| Source contract | What an adapter must provide | lib/integrations/crm-sync/provider-types.ts |
| Adapter registry | Which adapters exist (code-owned, fail closed) | lib/integrations/crm-sync/provider.ts |
| Registered adapters | HubSpot, ConnectWise PSA | HubSpot: lib/integrations/hubspot/sync-provider.ts; ConnectWise PSA: provider under lib/integrations/connectwise/ (confirm exact filename in-repo; runbook connectwise-psa-integration-package.md) |
| Destination catalog | Where imported records can land | lib/integrations/crm-sync/target-catalog.ts |
| Client-safe contract | What the browser may see | lib/integrations/crm-sync/object-mapping-contract.ts |
| Configuration | Stored mappings | lib/integrations/crm-sync/object-mapping-store.ts |
| Shared importer | Runs the import | lib/integrations/crm-sync/object-mapping-runtime.ts |
| CRM storage | Persisting inbound records | lib/integrations/crm-sync/inbound-writer.ts, inbound-transition.ts |
| Shared UI | Mapping editor | components/integrations/package-object-mappings.tsx |
| Admin API | Mapping CRUD | /api/v1/integration-packages/[packageKey]/object-mappings |
Paths under lib/integrations/crm-sync/ unless noted.
Status notes from source
Section titled “Status notes from source”- HubSpot and ConnectWise PSA have registered adapters. HubSpot:
lib/integrations/hubspot/sync-provider.ts; ConnectWise PSA: provider underlib/integrations/connectwise/(confirm exact filename in-repo; runbookconnectwise-psa-integration-package.md). Anything else claiming adapter status needs verification againstprovider.ts. Unknown providers fail closed. - Salesforce scaffolds are not implementations. Scaffolding present in the tree must never be described, demoed, or promised as a working connector.
- Outbound HubSpot writes remain disabled. The SDK story here is inbound import; outbound writes are not available regardless of what the adapter surface suggests.
Still not in pasted sources
Section titled “Still not in pasted sources”Confirm in the product repo before documenting: credential rotation/expiry mechanics per connector type, exact retirement mechanics, test-runner/CI placement for contract tests, ai_gateway_key token-gate specifics, custom-domain DNS procedure. Pages flag these inline where they matter.