@enfinitos/sdk-operator-web

EnfinitOS Operator Web SDK — a React component library that tenants embed in their own admin UIs to surface the EnfinitOS operator surfaces (rights registry, proof centre, compliance flows, billing, pacing, pilots) without building those dashboards from scratch.

Who should use this. Any tenant who: - already has an admin UI (Cloudflare-style, AWS-Console-style, or a custom React-based shell) and wants to drop EnfinitOS panels inside their chrome rather than iframe a third-party dashboard; - has their own identity/SSO and wants to issue short-lived JWTs to the SDK without going through the platform's login flow; - prefers a small, themeable, white-label-ready component library over a hosted Workspace experience.

Architecture

        ┌──────────────────────────────────────────────────┐
        │                Tenant Admin UI                   │
        │       (React/Next.js/Remix/Vite — host's choice) │
        │                                                  │
        │  ┌────────────────────────────────────────────┐  │
        │  │           <OperatorProvider>               │  │
        │  │  client = new EnfinitOSOperatorClient(…)   │  │
        │  │                                            │  │
        │  │   ┌────────────────────────────────────┐   │  │
        │  │   │  ThemeProvider (CSS variables,     │   │  │
        │  │   │  tenant-overridable tokens)        │   │  │
        │  │   │                                    │   │  │
        │  │   │   <RightsRegistryPanel/>           │   │  │
        │  │   │   <ProofExplorer/>                 │   │  │
        │  │   │   <ProofVerifier                   │   │  │
        │  │   │      auditorVerify={…}/>           │   │  │
        │  │   │   <PacingDashboard/>               │   │  │
        │  │   │   <UsageMeter/>                    │   │  │
        │  │   │   <DsarRequestForm/>               │   │  │
        │  │   │   <PilotEnrolmentFlow/>            │   │  │
        │  │   └────────────────────────────────────┘   │  │
        │  └────────────────────────────────────────────┘  │
        │                       │                          │
        └───────────────────────┼──────────────────────────┘
                                │  HTTPS, JWT auth
                                │  X-Org-Id, Accept-Version
                                ▼
        ┌──────────────────────────────────────────────────┐
        │             EnfinitOS Platform API (/v1)         │
        │                                                  │
        │  LIVE today (Cloudflare sandbox + Apr-2027 prod) │
        │  /v1/rights (+ /issue)   /v1/proof-packs (+seal) │
        │  /v1/offers (+ /propose) /v1/challenges (+open)  │
        │  /v1/compliance/dsar (DSAR job pipeline)         │
        │                                                  │
        │  LAUNCH surface (April 2027, gated by default)   │
        │  /v1/proof (ledger)      /v1/compliance/erasure  │
        │  /v1/consent             /v1/billing/{invoices…} │
        │  /v1/pacing/health       /v1/pilot/enrolment     │
        └──────────────────────────────────────────────────┘

The SDK has no compile-time dependency on the platform's backend or any other EnfinitOS package. It speaks the public REST contract via Accept-Version negotiation and re-states the contract types in src/types.ts so tenants can install the SDK without dragging in the platform's internal schemas. The public /v1 contract is defined once, in docs/openapi-v1.yaml; a conformance test in this package (src/__tests__/contract-conformance.test.ts) pins every URL the SDK can construct to that spec.

Live sandbox surface vs launch surface

The same client serves two tiers of the /v1 contract:

• Live surface — exists on the public contract today (sandbox.api.enfinitos.com/v1/*, identically api.enfinitos.com/v1/* at the April 2027 launch). Works with zero configuration.
• Launch surface — operator resources that ship with the April 2027 AWS backend and have no live /v1 equivalent. Calling one with the default configuration throws a descriptive OperatorLaunchSurfaceError instead of firing a request that can only 404. Opt in with launchSurface: true (mock backends, staging, tests), or override that resource's path template via the paths option (e.g. BACKEND_PATHS_DIRECT for a local Fastify).

Two collapses worth knowing about on the live sandbox:

• Resolve → POST /v1/delivery. There is no standalone runtime resolve/world-model endpoint on /v1: the Cloudflare sandbox collapses the resolve step into the delivery observation itself — POST /v1/delivery runs the substrate constraint gate against the right and emits the signed receipt in one call (constraint violations come back 412). Pacing telemetry rolls up through GET /v1/metering.
• Verification → client-side. There is no server-side verify endpoint. Fetch a pack with proof.getPack() and verify it offline with @enfinitos/sdk-auditor — that independence is the point of the trust model.

The machine-readable inventory behind this table is exported as OPERATOR_WEB_PATH_MANIFEST (plus LIVE_V1_PATH_KEYS / LAUNCH_SURFACE_PATH_KEYS), and the conformance test cross-checks it against docs/openapi-v1.yaml on every run.

Installation

pnpm add @enfinitos/sdk-operator-web
# or: npm install @enfinitos/sdk-operator-web

Peer dependencies (provided by the host):

• react ^18.0.0 || ^19.0.0
• react-dom ^18.0.0 || ^19.0.0

The SDK pulls in zero runtime UI libraries — no MUI, no Chakra, no Ant Design, no Tailwind. Components ship with inline styles driven by CSS variables; tenants override those variables to brand the SDK to their own chrome.

5-minute getting started

import {
  EnfinitOSOperatorClient,
  OperatorProvider,
  RightsRegistryPanel,
} from "@enfinitos/sdk-operator-web";

const client = new EnfinitOSOperatorClient({
  // Today: the live sandbox. April 2027: https://api.enfinitos.com —
  // the contract is identical, only the base URL changes.
  apiBaseUrl: "https://sandbox.api.enfinitos.com",
  orgId: "org_acme",
  authToken: () => fetchYourJwt(),   // sync or async
  // optional:
  timeoutMs: 10_000,
  retries: 3,
  // launchSurface: true,  // opt in to April-2027 resources — see
  //                       // "Live sandbox surface vs launch surface"
});

export function AdminRightsPage() {
  return (
    <OperatorProvider client={client}>
      <RightsRegistryPanel />
    </OperatorProvider>
  );
}

That's it. The panel paginates, filters by status / substrate, opens a detail card on click, and exposes lifecycle actions (suspend / resume / revoke) inline.

Issue a right, observe deliveries, seal + verify a proof pack

The core live loop against the public contract (docs/openapi-v1.yaml):

import { verifyAll } from "@enfinitos/sdk-auditor";

// 1. Issue a root right — POST /v1/rights/issue. `basisId` travels
//    in the BODY (not the path); `scope` is the free-form label and
//    effectiveFrom/effectiveUntil bound the validity window.
const right = await client.rights.issue({
  basisId: "bas_8f2c1a9b4e7d0c63",
  substrate: "DOOH",
  scope: "DOOH retail estate, Greater London",
  effectiveFrom: new Date().toISOString(),
});

// 2. (Deliveries are observed by your runtime via POST /v1/delivery —
//    the constraint gate runs in that call; see the API reference.)

// 3. Seal everything observed since the last seal — POST
//    /v1/proof-packs/seal. `sealed: false` means nothing new.
const { pack, sealed } = await client.proof.seal();

// 4. List / fetch signed proof packs — GET /v1/proof-packs[/{packId}].
const packs = await client.proof.listPacks({ limit: 20 });
const fetched = await client.proof.getPack(packs.items[0]!.packId);

// 5. Verify CLIENT-side with the open-source auditor SDK. There is
//    deliberately no server-side verify endpoint — a verification you
//    have to ask the platform for proves nothing.
const report = await verifyAll({ pack: fetched });
// report.status === "VALID"

Theming

The SDK reads a flat dictionary of CSS variables prefixed with --enfinitos-. Override any subset via the tokens prop on <OperatorProvider> or <ThemeProvider>:

<OperatorProvider
  client={client}
  tokens={{
    "--enfinitos-color-brand": "#0066cc",
    "--enfinitos-color-brand-fg": "#ffffff",
    "--enfinitos-color-text": "#1a1a1a",
    "--enfinitos-color-surface": "#ffffff",
    "--enfinitos-color-surface-alt": "#f4f6f8",
    "--enfinitos-color-border": "#e2e8f0",
    "--enfinitos-font-family": "Inter, sans-serif",
  }}
>
  …
</OperatorProvider>

CSS-variable reference

Tenants who already use design tokens (Tailwind, Radix Colors, a custom system) typically write a one-liner mapping their token names onto --enfinitos-* and inherit their brand automatically.

Component catalogue

Rights Registry

Proof Centre

Verification Centre

Compliance

Pacing

Billing

Pilot

Shared building blocks (composable on their own)

API client reference

Top-level construction:

const client = new EnfinitOSOperatorClient({
  apiBaseUrl: "https://sandbox.api.enfinitos.com",
  orgId: "org_acme",
  authToken: "ey…",                   // or () => Promise<string>
  timeoutMs: 10_000,
  retries: 3,
  fetchImpl: customFetch,             // optional override
  userAgentTag: "acme-admin/1.2.3",   // optional, appended to X-Operator-Web-SDK
  launchSurface: false,               // default; true unlocks April-2027 resources
  // paths: BACKEND_PATHS_DIRECT,     // optional — un-prefixed Fastify dev layout
});

Sub-API surface (entries marked ⏳ are launch surface — gated by default, see the table above):

client.rights      → list / get / getWithProvenance / issue / suspend /
                     resume / revoke / listBases /
                     ⏳statusCounts / ⏳family / ⏳provenance
client.offers      → listInbox / propose / accept / reject /
                     counter / withdraw / ⏳get
client.challenges  → listOpen / open / resolve / withdraw / ⏳get
client.proof       → listPacks / getPack / seal /
                     ⏳list / ⏳get / ⏳chain / ⏳verify / ⏳exportSigned
client.tenant      → get
client.events      → list
client.metering    → summary
client.settlement  → summary
client.consent     → ⏳list / ⏳get / ⏳issue / ⏳revoke / ⏳check
client.compliance  → createDsarJob / listDsarJobs / listDsarJobsDetailed /
                     getDsarJob / getDsarJobWithReport / runDsarJob /
                     downloadDsarJob / cancelDsarJob   (DSAR jobs — LIVE)
                     ⏳listErasure / ⏳getErasure / ⏳fileErasure  (erasure)
client.billing     → ⏳listInvoices / ⏳getInvoice / ⏳listSettlements /
                     ⏳getSettlement / ⏳listMeters
client.pacing      → ⏳listHealth / ⏳getHealth
client.pilot       → ⏳getEnrolment / ⏳enrol / ⏳listCohorts

rights.get returns the flat Right; rights.getWithProvenance returns { right, provenance } (the live read ships the provenance chain inline). offers.counter returns { original, counter } (the spec's two-sided counter response). tenant / events / metering / settlement are LIVE reads — no launchSurface opt-in needed.

Every method returns the unwrapped data from the platform's envelope; non-2xx responses throw an OperatorApiError carrying the platform's RFC-7807-ish code/message/details triple. A launch-surface method called without opting in rejects with an OperatorLaunchSurfaceError before any request leaves the client — the message names the resource, the live alternative where one exists, and the two opt-in routes (launchSurface: true or a paths override).

Retry policy

• 5xx and 429 responses retry up to retries times (default 3).
• 4xx responses (other than 429) are fatal — they throw immediately.
• Backoff is exponential with a small jitter to spread retry storms.
• A network/timeout error is treated as retryable.

Auth

authToken accepts either a static string or a callable returning a string | Promise<string>. The callable form is invoked on every request so a tenant can rotate tokens without reconstructing the client (and it slots cleanly into OAuth-refresh flows).

Cancellation

Every request races an AbortSignal against the configured timeoutMs. The hook layer (useAsync) also wires an abort signal so deps-changes cancel in-flight calls.

Hooks

For tenants that want the SDK's React-flavoured data layer rather than rolling their own:

useRightsList(filter)        // → AsyncResult<Page<Right>>
useRight(rightId)            // → AsyncResult<{ right, provenance } | null>
useRightFamily(rightId)      // → AsyncResult<{ ancestors, descendants } | null>
useRightsStatusCounts()      // → AsyncResult<Record<RightStatus, number>>
useProofList(opts)           // → AsyncResult<Page<ProofRecord>>
useProofChain(headProofId)   // → AsyncResult<ProofChain | null>
useConsentList(subjectRef)   // → AsyncResult<Page<ConsentRecord>>
useConsentCheck(input)       // → AsyncResult<{ granted, consentId }>
useInvoices(opts)            // → AsyncResult<Page<Invoice>>
useSettlements(opts)         // → AsyncResult<Page<Settlement>>
useUsageMeters()             // → AsyncResult<Page<UsageMeter>>
usePacingHealth(opts)        // → AsyncResult<DeliveryHealth[]>

Every hook returns { data, error, loading, refreshing, refetch }, shaped to plug into <AsyncBoundary state={…}> without ceremony.

Tenants who want raw control reach for useOperatorClient() and hit the typed client directly.

Sample integration — minimal viable operator dashboard

A complete, copy-pasteable 30-line dashboard:

import {
  EnfinitOSOperatorClient,
  OperatorProvider,
  RightsRegistryPanel,
  ProofExplorer,
  PacingDashboard,
  UsageMeter,
  InvoiceList,
  DsarRequestForm,
} from "@enfinitos/sdk-operator-web";

const client = new EnfinitOSOperatorClient({
  apiBaseUrl: process.env.NEXT_PUBLIC_ENFINITOS_API!,
  orgId: process.env.NEXT_PUBLIC_ENFINITOS_ORG!,
  authToken: async () => (await fetch("/api/jwt")).text(),
});

export default function OperatorDashboard() {
  return (
    <OperatorProvider client={client} tokens={{ "--enfinitos-color-brand": "#0066cc" }}>
      <div style={{ display: "grid", gap: 24, padding: 24 }}>
        <RightsRegistryPanel />
        <PacingDashboard refreshIntervalMs={30_000} />
        <UsageMeter />
        <InvoiceList />
        <ProofExplorer />
        <DsarRequestForm />
      </div>
    </OperatorProvider>
  );
}

Verification gate

Verification of the live proof artefact (the SignedProofPack from /v1/proof-packs) is CLIENT-side, on purpose: fetch the pack with client.proof.getPack(packId) and pass it to @enfinitos/sdk-auditor's verifyProofPack / verifyAll. A verification you have to ask the platform for proves nothing — the auditor SDK re-derives signatures, hashes, chain links, metering and settlement from first principles, offline.

Components that render signed evidence accept an optional auditorVerify prop typed against @enfinitos/sdk-auditor. The SDK does NOT pull the auditor as a hard dep — tenants on edge-runtime hosts (Cloudflare Workers, Vercel Edge) opt-in only when they have the crypto primitives available.

import { verifyChain } from "@enfinitos/sdk-auditor";

<ProofVerifier headProofId="p_abc123" auditorVerify={verifyChain} />

(<ProofVerifier/>'s server-side second opinion calls proof.verify() — a launch-surface endpoint; see the surface table.)

What's SDK-side vs platform-side

Accessibility

• Every interactive element has an explicit aria-label or visible label.
• All clickable rows are keyboard-activatable (Enter / Space) with tabIndex=0 and role="button".
• Status badges use role="status" with a sensible aria-label.
• Focus rings honour --enfinitos-focus-ring so tenants can keep brand contrast.
• Async boundaries announce loading + error states via role="status" and role="alert" so screen readers track state changes.

Versioning

• The SDK ships SDK_VERSION (semver) and CONTRACT_VERSION (an ISO date matching the platform's accepted contract). Every REST call sends both as headers (X-Operator-Web-SDK, Accept-Version).
• The platform pins responses to the negotiated contract version — a newer platform never returns shapes the SDK can't parse.

See also

• the auditor-ts SDK (@enfinitos/sdk-auditor) — independent signature verifier you can wire into <ProofVerifier auditorVerify={…}/>.
• the robotics-ts SDK — the reference SDK for the ROBOTICS substrate (this Operator SDK speaks the same BehaviourRule union).
• the platform's first-party operator Workspace — a dashboard rendered against the same API surface; useful as a worked example.
• docs/launch/substrate-readiness-matrix.md — per-substrate readiness status.