JSPM – @hybridb/sdk@0.1.2

Package Exports

@hybridb/sdk
@hybridb/sdk/react

Readme

Official TypeScript SDK for the Stellrai governed execution runtime.

Stellrai doesn't care how you built your app. It governs how it executes.

Use @hybridb/sdk for anything that must be:
  - decided   (policy-governed before execution)
  - audited   (immutable record, always)
  - reversible (rollback or replay, by default)

What this SDK does

When your app needs to perform a governed action — an AI decision, a payment, identity resolution, an external provider call, or any audit-required state change — you route it through this SDK. Everything else in your app stays exactly as it was.

Governed (use SDK)	Not governed (use any tool)
AI decisions and inferences	UI rendering
Payments and financial operations	Local database reads/writes
Identity resolution and auth	In-memory computation
External provider calls (Stripe, KYC, etc.)	Draft content and UI state
Audit-required state changes	Application configuration

Pipelines represent governed execution steps. Your application defines the business logic; Stellrai governs, records, and enables reversibility for every step.

Installation

npm install @hybridb/sdk
# or
pnpm add @hybridb/sdk
# or
yarn add @hybridb/sdk

Quick start

1. Get an API key

2. Initialise the client

import { HybriDBClient } from '@hybridb/sdk';

const hdb = new HybriDBClient({
  baseUrl: 'https://hybridb.stellrai.com',
  apiKey:  process.env.HYBRIDB_API_KEY!,
});

3. Define a pipeline

Before you can trigger a pipeline, you register its definition. This tells Stellrai what steps exist and how to govern, checkpoint, and reverse them.

const pipeline = await hdb.pipelines.create({
  name:        'process-payment',
  description: 'Governed payment execution with full reversibility',
  steps: [
    {
      id:               'reserve-funds',
      name:             'Reserve Funds',
      type:             'provider_call',
      config:           { provider: 'stripe', action: 'authorize' },
      compensationStep: 'release-reserve',
      timeout:          10_000,
    },
    {
      id:               'charge-account',
      name:             'Charge Account',
      type:             'provider_call',
      config:           { provider: 'stripe', action: 'capture' },
      compensationStep: 'issue-refund',
      dependsOn:        ['reserve-funds'],
    },
    {
      id:        'notify-user',
      name:      'Send Confirmation',
      type:      'notification',
      config:    { channel: 'email', template: 'payment-success' },
      dependsOn: ['charge-account'],
    },
  ],
});

console.log(pipeline.id); // save this — used to trigger executions

4. Request a governance decision

Every governed execution must be authorized by the policy engine before it runs.

const decision = await hdb.requestDecision({
  action:   'PAYMENT_EXECUTE',
  resource: { amount: 15000, currency: 'USD', recipientId: 'acc_7k2m' },
});

// Fail closed — never execute without a decision
if (decision.result !== 'ALLOW') {
  throw new Error(`Blocked by policy: ${decision.reason}`);
}

5. Execute the governed pipeline

Link the decision to the execution. Executions without a valid decisionId may be rejected or flagged.

const execution = await hdb.triggerPipeline({
  pipelineId:     pipeline.id,          // UUID from step 3
  input:          { userId: 'u_123', amount: 15000, currency: 'USD' },
  decisionId:     decision.id,          // required — binds execution to governance decision
  idempotencyKey: crypto.randomUUID(),  // ensures safe retries — prevents duplicate execution
});

console.log(execution.id);     // exec_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
console.log(execution.status); // 'completed'

6. Rollback a failed execution

if (execution.status === 'failed') {
  const result = await hdb.reversibility.rollback(execution.id, {
    rollbackType: 'full',
    reason:       'Payment processor returned 422',
  });

  console.log(result.outcome);         // 'success'
  console.log(result.stepsRolledBack); // ['charge-account', 'reserve-funds']
  console.log(result.durationMs);      // 2840
}

7. Replay from a checkpoint

const checkpoints = await hdb.reversibility.getCheckpoints(execution.id);

const replay = await hdb.reversibility.replay(execution.id, {
  fromCheckpoint: checkpoints[1].id,  // resume after step 2 — not from step zero
  reason:         'Retry notification step after rate limit',
});

console.log(replay.newExecutionId);    // new child execution
console.log(replay.parentExecutionId); // original execution

Core concepts

Decision binding

Every governed execution must be linked to a prior policy decision via decisionId. This ensures no pipeline runs without a policy clearance and audit record.

// ✅ Correct — execution is governance-bound
await hdb.triggerPipeline({ pipelineId, input, decisionId: decision.id, idempotencyKey });

// ⚠️ Without decisionId — execution may proceed but will be flagged as ungoverned
await hdb.triggerPipeline({ pipelineId, input, idempotencyKey });

Fail-closed pattern

Never execute a governed action when the decision is missing or unavailable.

let decision;
try {
  decision = await hdb.requestDecision({ action: 'PAYMENT_EXECUTE', resource });
} catch (err) {
  // Decision service unavailable — fail closed, do not proceed
  throw new Error('Governance unavailable — execution blocked');
}

if (decision.result !== 'ALLOW') {
  throw new Error(`Policy blocked: ${decision.reason}`);
}

Idempotency

Always pass idempotencyKey when triggering pipelines. It ensures safe retries after network errors and prevents duplicate execution of the same operation.

// Use a stable key derived from your business operation
const idempotencyKey = `payment-${orderId}-${Date.now()}`;

await hdb.triggerPipeline({ pipelineId, input, decisionId, idempotencyKey });

Identity (optional)

The hdb.authenticate() and actor management methods are only required if you use Governed Identity — where Stellrai manages your user identities and sessions.

If you use your own auth system (Clerk, Auth0, Supabase Auth, custom JWT), pass identity context via API keys and token headers. You do not need to call hdb.authenticate().

// If using your own auth — just use your API key
const hdb = new HybriDBClient({ baseUrl, apiKey: process.env.HYBRIDB_API_KEY! });

// If using Governed Identity — authenticate via Stellrai
const tokens = await hdb.authenticate({ email, password });

API reference

`HybriDBClient`

const hdb = new HybriDBClient({
  baseUrl:     string,   // required — e.g. 'https://hybridb.stellrai.com'
  apiKey:      string,   // required — your Stellrai API key
  timeout?:    number,   // ms, default 10000
  retries?:    number,   // default 3
  retryDelay?: number,   // ms, default 500
});

Pipelines

hdb.pipelines.create(input)           // register a pipeline definition → returns { id, name, ... }
hdb.triggerPipeline(input)            // trigger execution by pipeline UUID
hdb.triggerPipelineByName(name, input) // trigger execution by pipeline name
hdb.getPipelineExecution(executionId) // get execution status

Decisions

hdb.requestDecision(request) // policy-governed decision → { id, result: 'ALLOW'|'DENY'|'ESCALATE' }
hdb.getDecision(decisionId)  // retrieve a past decision

Reversibility

hdb.reversibility.rollback(executionId, input)          // rollback full / selective / to checkpoint
hdb.reversibility.replay(executionId, input)            // replay from a specific checkpoint
hdb.reversibility.getCheckpoints(executionId)           // list all checkpoints
hdb.reversibility.getCheckpoint(executionId, id)        // get checkpoint (checksum-verified)
hdb.reversibility.getRollbackLog(executionId)           // audit log of rollback operations
hdb.reversibility.getCircuitBreaker(pipelineId)         // get circuit breaker status
hdb.reversibility.setCircuitBreaker(pipelineId, input)  // open / close circuit breaker

Identity & Auth

Only required when using Governed Identity mode. Not required if you manage your own user auth.

hdb.authenticate(input)         // email + password → token pair
hdb.refreshToken(refreshToken)  // refresh an access token
hdb.revokeSession()             // invalidate current session
hdb.verifyToken(token)          // local JWT verification via JWKS (requires jose)
hdb.actors.createApiKey(actorId, input)
hdb.actors.revokeApiKey(actorId, keyId)
hdb.actors.createMapping(actorId, input)
hdb.orgs.addMember(orgId, input)
hdb.orgs.updateMemberRole(orgId, actorId, role)
hdb.orgs.revokeMember(orgId, actorId)
hdb.orgs.listMembers(orgId)

Events & Audit

hdb.publishEvent(input)          // publish a business event
hdb.queryAuditLog(params)        // query the immutable audit log
hdb.health()                     // check API status

React context (optional)

import { HybriDBProvider, useHybriDBClient } from '@hybridb/sdk/react';

// Wrap at app root
<HybriDBProvider client={hdb}>
  {children}
</HybriDBProvider>

// Use in any component
const { client } = useHybriDBClient();

Error handling

All SDK methods throw HybriDBError on failure. Never swallow these — they represent governance failures, not application errors.

import { HybriDBClient, HybriDBError } from '@hybridb/sdk';

try {
  const execution = await hdb.triggerPipeline({ ... });
} catch (err) {
  if (err instanceof HybriDBError) {
    console.error(err.code);    // e.g. 'POLICY_BLOCKED', 'RATE_LIMITED'
    console.error(err.message); // human-readable description
    console.error(err.details); // structured detail object (when present)
  }
  throw err; // let errors propagate — don't hide governance failures
}

Requirements

Node.js 18+
TypeScript 5+ (optional but recommended)
jose ^5.0 (only required if you use hdb.verifyToken() — auto-installed as dependency)
React 18+ (only required for @hybridb/sdk/react — optional peer dependency)

@hybridb/sdk