TypeScript / JavaScript SDK — Post-Seed Plan¶
Status: Deferred from v0.1. Planned post-seed. Scope owner: Developer Experience. Source of truth: scope-90-day.md:38, PRD §commercialization.
v0.1 ships a Python SDK because the Python SDK doubles as the internal library for the Risk Engine and CLI. A TS/JS SDK is purely a distribution surface: it does not unlock any control behavior the Python SDK does not already cover. Post-seed it becomes worth building because Node.js providers and in-browser verifiers (badge service, dashboard) are the next two integration targets.
Why it is deferred¶
The marginal value of a second SDK before the first SDK has design-partner pull is negative — it doubles the surface to maintain without adding capability. The reasonable signal to start is one of: (a) >=3 design partners ask for a Node.js SDK in writing, or (b) the SaaS premium dashboard reaches C0 and needs in-browser signature verification.
Architectural preconditions v0.1 must preserve¶
| Precondition | Owner phase | Why it matters |
|---|---|---|
| The gateway-api is OpenAPI-first; the spec is the contract, not the Python SDK | Phase 9 | The TS SDK is generated from the same OpenAPI spec, not back-derived from Python |
| Signed status artifact and dossier metadata schemas are JSON Schema files in the repo | Phase 9–12 | The TS SDK consumes the same schemas; no parallel schema definitions |
| Signature format is a documented public spec (algorithm, encoding, canonicalization) | Phase 9 | In-browser verifier in the TS SDK must reproduce signature checks without reading Python source |
| Error envelope (canonical error codes, retryability semantics) is in the OpenAPI spec | Phase 9 | Error handling is symmetric across SDKs |
If a v0.1 PR adds an API behavior to the Python SDK without first updating the OpenAPI spec, raise it — that pattern would force a TS SDK rewrite later.
Scope when it ships¶
In scope:
@opencomplai/sdkfor Node.js (server-side): manifest validation, scan triggering, status artifact ingestion, evidence ledger reads.@opencomplai/verifierfor browsers and Node.js: standalone signature and Merkle-proof verification with no other dependencies. This is the package the badge service embeds.- TypeScript types generated from the canonical OpenAPI spec; published with the SDK.
- ESM and CJS dual publish; Node.js LTS support matrix tracked alongside Python's matrix.
- Example: GitHub Actions workflow consuming the SDK to gate a release without invoking the CLI.
Out of scope (intentional):
- Frontend framework adapters (React hooks, Vue composables). Out of charter; community can layer if they want.
- Reimplementation of the Risk Engine in JS. The engine is canonical in Python; the TS SDK is a client.
- An "SDK for the dashboard" that talks to anything but the OSS API. The dashboard has its own internal client; the public TS SDK is for OSS core only.
Milestones (indicative, post-seed)¶
- T0 —
@opencomplai/verifierpublished; in-browser signature verification works against a real signed artifact from the OSS core. - T1 —
@opencomplai/sdkpublished with parity to the Python SDK for: manifest validation, scan, status artifact read. - T2 — Generated TS types tracked in CI; type drift fails the build.
Exit gate for "GA": at least one design partner runs a Node.js CI pipeline through the SDK end-to-end without falling back to the CLI.
Open questions¶
- Whether the verifier package is MIT or Apache-2.0 (likely matches the OSS core license; verify before publish).
- Browser support floor (last two evergreen versions, or wider for procurement?).
- Whether to publish to GitHub Packages as well as npm for enterprise customers behind a mirror.