Skip to main content

SDK Reference

CNS ships one real SDK today — TypeScript, as an npm workspace (sdk/ts/) with four packages. Go and Python are placeholders; see Other languages.

PackageRoleReference
@amphoze/cns-coreShared envelope types, render-token mint/verify, multi-carrier read/inject helpers, the POST /v1/events HTTP client. Depended on by all three below.This page
@amphoze/cns-clientFrontend SDK: emit(), markViewed(), subscribe().TS Client
@amphoze/cns-serverBackend SDK: emit() (server-derived actor), serveWithProof().TS Server
@amphoze/cns-edgeSupabase Edge Function (Deno) helper — mints and injects a render-token as the "witness" for apps with no custom backend.This page

:::caution Not yet published to a registry All four packages are at workspace version 0.1.0 and depend on each other via npm workspace links ("@amphoze/cns-core": "*"), not a published semver range. Until they're published, consume them from within the sdk/ts workspace, or build (npm run build in sdk/ts/) and reference the resulting dist/ directly. :::

Install / build / test (within the workspace)​

cd sdk/ts
npm install                 # installs the whole workspace
npm run typecheck           # builds core (for its .d.ts), then tsc --noEmit on client/server/edge
npm run build                # tsc -p per package, in dependency order (core first)
npx vitest run                # unit tests

@amphoze/cns-core​

Every other package re-exports this one's surface (export * from "@amphoze/cns-core"), so you rarely import it directly — it's documented here because TS Client and TS Server both build on it.

  • Envelope types — CNSEvent, EmitEventInput, Source, Actor, Target, PageResult, FeedQuery — mirroring internal/core/event.Event and api/ROUTES.md. See the caution on PageResult's actual wire casing in API Reference.
  • Render-tokens — mintRenderToken, verifyRenderToken, decodeRenderTokenUnsafe, importEd25519PrivateKey/PublicKey, the RenderTokenClaims shape. See Trust & render-tokens.
  • Multi-carrier read/inject — readRenderToken, readFrom{Headers,JSON,Document,Global}, inject{Header,Meta,GlobalScript,JSON}.
  • HTTP — postEvent (the shared POST /v1/events client both CNSClient and CNSServer call through) and CNSApiError.

Only non-dev dependency: jose (works unmodified in Node, browsers, and Deno — why @amphoze/cns-edge can reuse this package as-is).

@amphoze/cns-edge (Supabase Edge Function helper)​

The "witness" toolkit for apps with no custom backend — a browser reading directly via PostgREST/RLS can't carry a render-token proof on its own, so a Supabase Edge Function mints and embeds one instead (see Trust & render-tokens).

import { mintAndJSON, mintAndHeaders, mintAndMeta } from "@amphoze/cns-edge";

const body = await mintAndJSON(
  { app: "docs-edge", tenant: "acme", subject: subjectId, docId, keyVersion, privateKey },
  { document: row },
);
// -> { document: row, _proof: "<render-token>" }

mintAndHeaders returns a ready-to-use Headers object (X-Notify-Proof set, CORS exposed, Cache-Control: no-store); mintAndMeta embeds a <meta name="notify-proof"> tag into an HTML fragment.

:::note Deno deployment Within this repo, @amphoze/cns-edge resolves @amphoze/cns-core via the npm workspace link (for local tsc type-checking). To actually deploy on Supabase Edge Functions, swap that import for npm:@amphoze/cns-core@^0.1 (Deno supports npm: specifiers since 1.28) once @amphoze/cns-core is published — see the comment block at the top of packages/edge/src/index.ts. :::