SDK Overview

@hybridb/sdk is the TypeScript/JavaScript SDK for Stellrai. It is the conformance surface — the only integration point between your application and the Stellrai runtime.

Installation

@hybridb/sdk on npm

npm install @hybridb/sdk

Client constructor

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

const hdb = new HybriDBClient({
  baseUrl:     'https://hybridb.stellrai.com',  // required
  apiKey:      process.env.HDB_API_KEY!,         // required
  timeout:     10_000,                           // ms, default 10000
  retries:     3,                                // default 3
  retryDelay:  500,                              // ms between retries, default 500
});

Method index

Decisions

Method	Description
hdb.requestDecision()	Request a policy decision before execution
hdb.getDecision()	Retrieve a decision by ID

Pipelines

Method	Description
hdb.triggerPipelineByName()	Trigger a pipeline by its registered name
hdb.triggerPipeline()	Trigger a pipeline by ID
hdb.getPipelineExecution()	Get execution status and step trace
hdb.pipelines.create()	Register a new pipeline definition

Reversibility

Method	Description
hdb.reversibility.rollback()	Roll back a completed execution
hdb.reversibility.replay()	Replay from a checkpoint
hdb.reversibility.getCheckpoints()	List checkpoints for an execution
hdb.reversibility.getCheckpoint()	Get a specific checkpoint
hdb.reversibility.getRollbackLog()	Get rollback history for an execution
hdb.reversibility.getCircuitBreaker()	Get circuit breaker state for a pipeline
hdb.reversibility.setCircuitBreaker()	Configure a pipeline circuit breaker

Audit

Method	Description
hdb.queryAuditLog()	Query the immutable audit trail

Events

Method	Description
hdb.publishEvent()	Publish a typed event to the event bus

Utility

Method	Description
hdb.health()	Check API connectivity and version

TypeScript types

All input and return types are exported from the SDK:

import type {
  DecisionInput,
  DecisionResponse,
  TriggerPipelineInput,
  PipelineExecution,
  TriggerByNameInput,
  AuditQueryParams,
  AuditEntry,
  HybriDBErrorCode,
} from '@hybridb/sdk';

Error handling

All SDK methods throw HybriDBError on failure:

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

try {
  const decision = await hdb.requestDecision({ ... });
} catch (err) {
  if (err instanceof HybriDBError) {
    console.log(err.code);    // 'POLICY_DENIED' | 'RATE_LIMITED' | ...
    console.log(err.message);
    console.log(err.status);  // HTTP status
  }
}

See Errors for the full error code reference.