Connector SDK

The contract for certified integrations: OAuth, webhook verification, pagination, rate limits, sync cursors and conflict policies — with three complete reference connectors.

Install

git clone https://github.com/ivorycom-platform/ivorycom-marketplace
cd ivorycom-marketplace && npm install
npx tsx sdk/src/scaffold.ts my-connector

The connection block

"connection": {
  "type": "oauth2",                       // oauth2 | api_key | none
  "authorizationUrl": "https://app.hubspot.com/oauth/authorize",
  "tokenUrl": "https://api.hubapi.com/oauth/v1/token",
  "scopes": ["crm.objects.contacts.read"],
  "sync": {
    "cursor": "updated_at",               // updated_at | opaque_token | none
    "direction": "bidirectional",         // inbound | outbound | bidirectional
    "conflictPolicy": "newest_wins",      // source_wins | platform_wins | newest_wins
    "rateLimitPerMinute": 110
  }
}

The Connector contract

export interface Connector {
  sync(ctx: ConnectorContext): Promise<SyncResult>;
  verifyWebhook?(event: WebhookEvent, secret: string): Promise<unknown>;
}
// ctx gives you: credentials (the TENANT's grant), cursor + setCursor,
// upsert(kind, records), log, sleep — and rateLimitedFetch handles 429/Retry-After.

The five disciplines (each demonstrated in an example)

discipline	rule	reference
OAuth	tenants connect their OWN credentials; you never ship shared keys (CI scans for it)	`examples/hubspot`
Webhook verification	HMAC + constant-time compare + replay window on everything inbound	`examples/stripe`
Pagination	page every read; never assume small datasets	Stripe `starting_after` · HubSpot `after` · Airtable `offset`
Rate limits	declare `rateLimitPerMinute`; back off on 429 via `rateLimitedFetch`	`sdk/src/types.ts`
Cursors & conflicts	`updated_at` watermarks persist once per completed window (crash → idempotent re-pull); `opaque_token` persists per page. Pick a conflict policy deliberately and document it in the listing.	HubSpot vs Stripe/Airtable

The three reference connectors

connector	auth	full demonstration
Stripe Revenue Sync `examples/stripe`	api_key	invoice mirror object + payment-failed workflow, HMAC webhook verify, opaque cursor, source-wins
HubSpot Contact Sync `examples/hubspot`	oauth2	bidirectional contacts, updated_at watermark, newest-wins, 429 pacing
Airtable Base Sync `examples/airtable`	oauth2	offset pagination, provisions a custom object with a platform-computed formula field

All three are published in the Marketplace and pass the same certification + install governance as any third-party app. Their tests (test/connectors.test.ts) show how to unit-test a connector against mocked upstreams.

Certify locally

TOKEN=$TOKEN npx tsx sdk/src/certify-cli.ts my-connector/manifest.json