@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 rebuilding the dashboards that ship in apps/web/app/_workspace/.

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/rights              /v1/proof               │
        │  /v1/offers              /v1/compliance/{dsar,…} │
        │  /v1/challenges          /v1/billing/{invoices…} │
        │  /v1/consent             /v1/pacing/health       │
        │                          /v1/pilot/enrolment     │
        └──────────────────────────────────────────────────┘

The SDK has no compile-time dependency on apps/api, apps/web, 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.

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({
  apiBaseUrl: "https://api.enfinitos.com",
  orgId: "org_acme",
  authToken: () => fetchYourJwt(),   // sync or async
  // optional:
  timeoutMs: 10_000,
  retries: 3,
});

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.

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://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
});

Sub-API surface:

client.rights      → list / get / issue / suspend / resume / revoke /
                     statusCounts / family / provenance / listBases
client.offers      → listInbox / get / propose / accept / reject /
                     counter / withdraw
client.challenges  → listOpen / get / open / resolve / withdraw
client.proof       → list / get / chain / verify / exportSigned
client.consent     → list / get / issue / revoke / check
client.compliance  → listDsar / getDsar / fileDsar / listErasure /
                     fileErasure
client.billing     → listInvoices / getInvoice / listSettlements /
                     getSettlement / listMeters
client.pacing      → listHealth / getHealth
client.pilot       → getEnrolment / enrol / listCohorts

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.

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

Components that render signed evidence (proof records, signed exports) 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} />

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

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