SDK & Types Alignment

Coverage certification — every PlatformXe API endpoint is reachable from every official SDK and documented in this site.

SDK & Types Alignment Certification

Every public /api/v1/* endpoint shipped by PlatformXe is reachable from every official SDK (TypeScript, Python, Go) with strongly-typed request/response shapes and is documented in this site. This page is the canonical certification of that coverage and is updated on every release that adds an API domain.

The Terraform provider covers the subset of the surface that's infrastructure-shaped — declarative state of permissions, webhooks, workflows, processors, threads, fraud rules, screening lists. Runtime-only endpoints (audit log dispatch, federated search query, unauthenticated registration, key whoami) deliberately have no Terraform resource because they describe transient calls, not infrastructure state.

Coverage matrix

API domain	Types	TypeScript SDK	Python SDK	Go SDK	Terraform
audit	✅	✅ `client.audit`	✅ `client.audit`	✅ `client.Audit`	n/a (runtime-only)
domains	✅	✅ `client.domains`	✅ `client.domains`	✅ `client.Domains`	✅ `platformxe_domains_sending`
event-log	✅	✅ `client.events.log`	✅ `client.events.log`	✅ `client.Events.Log`	n/a (read-only)
event-subscriptions	✅	✅ `client.events`	✅ `client.events`	✅ `client.Events`	✅ `platformxe_events_subscription`
events ingestion	✅	✅ `client.events.ingest`	✅ `client.events.ingest`	✅ `client.Events.Ingest`	n/a
events.custom (new in 9A)	✅ 2.4.0	✅ 1.2.0 `client.events.custom`	✅ `client.events.custom`	✅ `client.Events.Custom`	✅ `platformxe_custom_event`
events.custom.marketplace (new in 9C)	✅ 2.5.0	✅ 1.3.0 `client.events.custom.marketplace`	✅ `client.events.custom.marketplace`	✅ `client.Events.Custom.Marketplace`	✅ `platformxe_marketplace_listing`
events.custom.federation (9D + Pattern 3 in 1.5.0, ENTERPRISE)	✅ 2.7.0	✅ 1.5.0 `client.events.custom.federation`	✅ 1.5.0 `client.events.custom.federation`	✅ v1.5.0 `client.Events.Custom.Federation`	✅ `platformxe_event_federation_group`, `platformxe_event_federation_push`, `platformxe_event_federation_external_peer`
exports	✅	✅ `client.exports`	✅ `client.exports`	✅ `client.Exports`	✅ `platformxe_exports_processor`
fraud	✅	✅ `client.fraud` (6 sub-namespaces)	✅ `client.fraud`	✅ `client.Fraud`	✅ `platformxe_fraud_rule`, `platformxe_fraud_screening_list`
identity	✅	✅ `client.identity`	✅ `client.identity`	✅ `client.Identity`	✅ `platformxe_identity_processor` + `data.platformxe_identity_providers`
issues	✅	✅ `client.issues`	✅ `client.issues`	✅ `client.Issues`	n/a (runtime-only)
messaging	✅	✅ `client.messaging`	✅ `client.messaging`	✅ `client.Messaging`	✅ `platformxe_messaging_processor`
ocr	✅	✅ `client.ocr`	✅ `client.ocr`	✅ `client.Ocr`	✅ `platformxe_ocr_processor`
pdf	✅	✅ `client.pdf`	✅ `client.pdf`	✅ `client.Pdf`	✅ `platformxe_pdf_processor`
permissions	✅	✅ `client.permissions`	✅ `client.permissions`	✅ `client.Permissions`	✅ ×5 resources + 1 datasource
qr	✅ (in `pdf.ts`)	✅ `client.qr`	✅ `client.qr`	✅ `client.Qr`	✅ `platformxe_qr_processor`
register	✅	✅ standalone `register()`	✅ module-level `register()`	✅ package-level `Register()`	n/a (one-time bootstrap)
search	✅	✅ `client.search`	✅ `client.search`	✅ `client.Search`	n/a (runtime-only)
storage	✅ ×2 (media + fixed)	✅ `client.storage` + `client.documents`	✅ ditto	✅ ditto	✅ `platformxe_storage_processor`
telemetry	✅	utility on client	utility on client	utility on client	n/a (SDK self-instrumentation)
templates	✅	✅ `client.templates`	✅ `client.templates`	✅ `client.Templates`	✅ `platformxe_templates_template`
threads	✅	✅ `client.threads`	✅ `client.threads`	✅ `client.Threads`	✅ `platformxe_threads_channel` + 1 datasource
usage	✅	✅ `client.usage`	✅ `client.usage`	✅ `client.Usage`	n/a (read-only billing)
webhooks	✅	✅ `client.webhooks`	✅ `client.webhooks`	✅ `client.Webhooks`	✅ `platformxe_webhooks_endpoint`
whoami	✅	✅ `client.whoami`	✅ `client.whoami`	✅ `client.Whoami`	n/a (runtime-only)
workflows	✅	✅ `client.workflows`	✅ `client.workflows`	✅ `client.Workflows`	✅ `platformxe_workflows_trigger`

Bold rows = added in the most recent alignment sweep.

Released versions

Package	Latest version	Source of truth
`@caldera/platformxe-types`	2.7.0	`caldera-platformxe-types`
`@caldera/platformxe-sdk` (TypeScript)	1.5.0	`caldera-platformxe-sdk`
`platformxe` (Python — PyPI)	1.5.0	`caldera-platformxe/packages/sdk-python`
Go SDK (GitHub-hosted module)	v1.5.0 (via tag `sdk-go/v1.5.0`)	`caldera-platformxe/packages/sdk-go`
Terraform provider `calderax/platformxe`	1.5.0 (via tag `terraform-provider/v1.5.0`)	`caldera-platformxe/packages/terraform-provider`
`@caldera/events` (bus catalog)	1.25.0	`caldera-events`

The TypeScript types package is the canonical schema source. Each SDK consumes it for its request / response shapes.

What "alignment" means

A domain is considered aligned only when all four of the following are present:

Types — request/response interfaces in @caldera/platformxe-types
Runtime SDK coverage — TypeScript, Python, Go all expose a typed method per endpoint
Reference docs — an SDK reference page on this site (/sdk/<domain>) and either a service overview or a platform/auth/authorization page
Terraform — only when the domain is infrastructure-shaped. Runtime-only endpoints are explicitly marked n/a rather than promised-and-missing

Domains marked n/a for Terraform are intentional — audit.log, issues.create, search.query, register, whoami, and usage.summary describe transient calls, not declarable state.

Maintaining alignment — NO DRIFT POLICY

Any change to PlatformXe's public /api/v1/* surface MUST be accompanied — in the same merge train — by corresponding updates to all three downstream artefacts:

@caldera/platformxe-types — the schema source of truth
All runtime SDKs that the change applies to (TypeScript, Python, Go; Terraform if infrastructure-shaped)
This documentation site — both the SDK reference (/sdk/<domain>) and the relevant service / platform / auth page

A merge request touching src/app/api/v1/** without these accompanying updates should be rejected at review. Code reviewers and CI guards both enforce this — see caldera-platformxe/CLAUDE.md § SDK & Types Alignment Certification for the contributor-facing version of this rule.

Concrete checklist when adding a new endpoint

Add the request/response interfaces to @caldera/platformxe-types. Cut a new minor release.
Bump consumers (@caldera/platformxe-sdk, the Python and Go SDKs in the monorepo) to the new types version.
Add the SDK method in all three runtime SDKs, mirroring the existing namespace structure.
If the endpoint manages declarable state, add a Terraform resource. Otherwise mark it n/a in the matrix above.
Add an SDK reference page at /sdk/<domain> and either a service overview at /services/<domain>/overview or extend the relevant platform / auth / authorization page.
Update the coverage matrix on this page.

The CI guards on each SDK repo enforce typecheck-plus-test before publish; the GitLab mirror:tag job in this monorepo handles version-tag mirroring to GitHub for the Python, Go, and Terraform SDKs. The platform's prerelease checks include a coverage diff that flags any new route handler not paired with a types-pkg + SDK + docs update.

Why this rule exists

In May 2026, a 9-domain drift between the live API and the type / SDK / docs surface was discovered and remediated as a multi-session sweep — fraud detection (19 endpoints across 6 sub-namespaces), audit, issues, search, register, whoami, usage, event-log, and event-subscriptions extensions. The remediation was substantial. This page exists so that drift never accumulates again: every change ships aligned, or it doesn't ship.

Last certified

The most recent end-to-end alignment sweep — covering all 24 domains across all four artefacts — confirmed full coverage. See caldera-platformxe/CLAUDE.md (§ "SDK & Types Alignment Certification") for the contributor-facing copy of this matrix and the maintenance contract.

Phase 9A — Tenant Custom Events (full alignment, certified)

Commits 9f97cd8 through d81fad3 on feature/tenant-custom-events shipped a complete cross-artefact alignment for the new domain:

✅ @caldera/platformxe-types v2.4.0 — 15 new request/response interfaces
✅ @caldera/platformxe-sdk v1.2.0 — client.events.custom.{register, list, get, archive, emit, dryRun, health, subscribe}
✅ Python SDK: client.events.custom.{register, list, get, archive, emit, dry_run, health, subscribe}
✅ Go SDK: client.Events.Custom.{Register, List, Get, Archive, Emit, DryRun, Health, Subscribe}
✅ Terraform provider: platformxe_custom_event resource
✅ Docs reference page: /sdk/custom-events
✅ Live commissioning report: docs/platformxe-tenant-custom-events-smoke-test-results.md

Phase 9B.1 (subscriber dispatch unblock — 88df973), 9B.3 (delivery lifecycle hooks — ff4c4fb), and 9B.4 (SDK subscribe helper + @* wildcard — a7cdde9) round out the runtime; subscribers now reliably receive tenant custom emits with HMAC-signed deliveries.

Phase 9C — Marketplace (full alignment, certified)

Released 2026-05-05 via merge 7dfcb77:

✅ @caldera/platformxe-types v2.5.0 — marketplace request/response interfaces
✅ @caldera/platformxe-sdk v1.3.0 — client.events.custom.marketplace.{publish, list, get, unpublish, republish, fork}
✅ Python SDK: client.events.custom.marketplace.{publish, list, get, unpublish, republish, fork}
✅ Go SDK: client.Events.Custom.Marketplace.{Publish, List, Get, Unpublish, Republish, Fork}
✅ Terraform provider: platformxe_marketplace_listing resource
✅ Docs reference page: /sdk/marketplace

Phase 9D — Federation Push (full alignment, certified)

Released 2026-05-06 via merge d6455fe. ENTERPRISE-only on both sides.

✅ @caldera/platformxe-types v2.6.0 — federation request/response interfaces (groups, members, pushes)
✅ @caldera/platformxe-sdk v1.4.0 — client.events.custom.federation.{createGroup, listGroups, getGroup, archiveGroup, invite, accept, leave, declarePush, listPushes, undeclarePush}
✅ Python SDK v1.4.0: client.events.custom.federation.{create_group, list_groups, get_group, archive_group, invite, accept, leave, declare_push, list_pushes, undeclare_push} (class EventFederationService)
✅ Go SDK v1.4.0: client.Events.Custom.Federation.{CreateGroup, ListGroups, GetGroup, ArchiveGroup, Invite, Accept, Leave, DeclarePush, ListPushes, UndeclarePush} (EventFederation* types disambiguate from the v1.x.x permission federation surface)
✅ Terraform provider v1.4.0: platformxe_event_federation_group + platformxe_event_federation_push resources
✅ Docs reference page: /sdk/federation
✅ Smoke runbook: docs/platformxe-tenant-custom-events-federation-smoke-test-runbook.md
✅ Migration 0022_numerous_human_fly applied to dev + prod (journals at 23/23)

The runtime path: a tenant emits → bus listener (workflow-bridge step-3) consults lookupActivePushesFor() → one Inngest event per (push × accepted-member) pair → relay worker re-emits on the peer's canonical name + writes a per-attempt audit row in custom_event_federation_relay_log.

Naming clarity: the new "Custom Event Federation" (/api/v1/events/custom/federation/*, CUSTOM_EVENT_FEDERATION_* bus types, EventFederation* Go types) is intentionally distinct from the v1.x.x "Permission Federation" (/api/v1/permissions/federation/*, FEDERATION_* bus types, Federation* Go types) at client.permissions.federation.

Pattern 3 — External Webhook Peers (full alignment, certified)

Released 2026-05-06 on feature/external-webhook-peers. ENTERPRISE-only on the owner side; receiving endpoint can be anyone.

Pattern 3 lets a federation owner add an arbitrary HTTPS endpoint as a member of a group, addressed by URL rather than by tenant org id. Relays are POSTed with an HMAC-SHA256 X-Platformxe-Signature header signed with a one-time whsec_… secret returned at create time. Optional static headers (e.g. an Authorization bearer) are stored encrypted (KMS envelope, external_webhook_secret_encrypted column added in migration 0029) and replayed on every relay; only the header NAMES are echoed back on read.

✅ @caldera/platformxe-types v2.7.0 — FederationPeerType discriminator, AddExternalWebhookPeerRequest/Response, FederationMemberSummary extended with peerType, externalWebhookUrl, externalWebhookLabel, externalWebhookHeaderNames (with memberOrganizationId now nullable)
✅ @caldera/platformxe-sdk v1.5.0 — client.events.custom.federation.{addExternalPeer, removeExternalPeer}
✅ Python SDK v1.5.0 — client.events.custom.federation.{add_external_peer, remove_external_peer}
✅ Go SDK v1.5.0 — client.Events.Custom.Federation.{AddExternalPeer, RemoveExternalPeer} plus EventFederationPeerType{TenantOrg, ExternalWebhook} constants and AddEventFederationExternalPeer{Input, Result} types
✅ Terraform provider v1.5.0 — platformxe_event_federation_external_peer resource. The secret attribute is marked sensitive; encrypt your state at rest. Rotate by destroying and re-creating the resource.
✅ Migration 0029_federation_webhook_secret_encrypted applied to dev + prod (journals at 30/30)

The runtime path is unchanged from Phase 9D: tenant emits → bus listener consults lookupActivePushesFor() → one Inngest event per (push × accepted-member) pair → for external_webhook members the relay worker decrypts the secret, signs the canonical body, and POSTs it to the peer's URL with the static headers replayed; the per-attempt audit row in custom_event_federation_relay_log records the outbound delivery.