@sammati/server-sdk

Official enterprise TypeScript SDK for the Sammati Developer Platform integrator API.

Types are generated from openapi/openapi.yaml at build time. The OpenAPI contract is the single source of truth for request and response models.

Install

npm install @sammati/server-sdk

Package remains private: true until Phase 3G publication.
Partner first mile: docs/start-here-5-min.md · CHANGELOG.md

Quickstart

import { SammatiClient } from "@sammati/server-sdk";

const client = new SammatiClient({
  apiKey: process.env.SAMMATI_API_KEY!,
  environment: "test", // or "live"
  baseUrl: "http://localhost:3000",
});

const result = await client.consents.grant({
  external_user_id: "user-123",
  purpose_code: "marketing",
  policy_ref: "privacy-policy",
  occurred_at: new Date().toISOString(),
});

Services

| Service | Coverage | |---------|----------| | client.consents | grant, update, revoke, decline, renew, recordDecisions (C1), status, applicability, receipt, timeline, records, feed, metrics, listEvents, reconcileStatus | | client.policies | create draft, publish, get version, list versions | | client.proofs | event proof, consent proofs, batch, receipts, verify, verify-evidence | | client.evidencePackages | create, get, download, verify, liveAssurance, issueJwt / verifyJwt (EP-1 + ADR-013 + P7) | | client.anchors | meta, ledger anchor, ledger history | | client.audit | batch anchor audit | | client.webhooks | CRUD, rotate secret, test delivery | | client.assertionKeys | create, list active, revoke (no get-by-id / delete) | | client.widget | sessions, runtime bootstrap, hosted HTML | | client.subjects | subject / CustomerRef helpers (feed-safe) |

Portal BFF (/v1/portal/*, including Portal JWT auth) is a private contract (openapi/portal.openapi.yaml) and is intentionally excluded from this SDK (Production Hardening D1). Use the Public Company API + API keys here; do not call Portal session endpoints from integrator integrations.

Customer reference (Phase 6)

import { toStoredCustomerRef, validateCustomerRef } from "@sammati/server-sdk";

validateCustomerRef("cust_91ABCDEF", { profile: "opaque_strict" });
// Under hmac_v1 prefer server-side hashing (CUSTOMER_REF_HMAC_SECRET).
// If hashing locally, never log the raw CRM id.

Company setting customerRefPolicy.profile: legacy_compatible (default) | opaque_strict | hmac_v1.
New mappings only; see docs/runbooks/CUSTOMER-REF-HMAC.md.

Evidence JWT (P7)

import { verifyEvidenceJwtLocal } from "@sammati/server-sdk";

const issued = await client.evidencePackages.issueJwt({ packageId });
const claims = verifyEvidenceJwtLocal(issued.token, process.env.EVIDENCE_JWT_HMAC_SECRET!);
// Online recheck (signature + stored package_hash / anchor binding):
await client.evidencePackages.verifyJwt({ token: issued.token });

Not sole trust — still use EP-1 verify and/or liveAssurance for Fabric. See docs/architecture/EVIDENCE-JWT-AND-ANCHOR.md.

Principal assertion (server-side only)

import { SammatiClient, withPrincipalAssertion } from "@sammati/server-sdk";

// Manage signing keys (company backend only — secret returned once on create)
const created = await client.assertionKeys.create();
const { items } = await client.assertionKeys.list();
await client.assertionKeys.revoke({ keyId: created.keyId });

await client.consents.grant(body, withPrincipalAssertion({}, assertionJwt));

Company Backend signs the assertion; the browser must never hold API keys or assertion signing secrets.

Webhook helpers

import { parseWebhookEvent, verifyWebhookSignature } from "@sammati/server-sdk";

const event = parseWebhookEvent(rawBody);
const result = verifyWebhookSignature({
  signatureHeader: req.headers["sammati-signature"],
  rawBody,
  secrets: [signingSecret],
});

Reuses @sammati/webhook-utils — no duplicate crypto logic.

Test vs live delivery

| Ledger | Automatic consent.recorded | Verify endpoint | |--------|------------------------------|-----------------| | environment: "test" | No on grant/update/revoke | client.webhooks.testEndpoint() | | environment: "live" | Yes when subscribed | Same test method + production events |

Test-plane consent writes return proofStatus: "NOT_APPLICABLE" and do not enqueue webhook deliveries. See Webhooks.

Errors

Typed errors: AuthenticationError, ValidationError, RateLimitError, ConflictError, NotFoundError, ServerError, NetworkError, TimeoutError.

Development

npm run codegen   # regenerate types from ../../openapi/openapi.yaml
npm run build
npm test
npm run examples:check

Versioning

SDK 0.2.x tracks OpenAPI spec 1.0.0 (info.version).