TypeScript / Node.js Integration

A complete example integrating Stellrai into a Node.js payment service.

Setup

npm install @hybridb/sdk

// lib/stellrai.ts
import { HybriDBClient } from '@hybridb/sdk';

if (!process.env.HDB_API_KEY) throw new Error('HDB_API_KEY is required');

export const hdb = new HybriDBClient({
  baseUrl: process.env.HDB_BASE_URL ?? 'https://hybridb.stellrai.com',
  apiKey:  process.env.HDB_API_KEY,
});

Create the client once and export it. Do not instantiate per-request.

Register your pipeline (once, at startup)

// scripts/setup-pipelines.ts
import { hdb } from '../lib/stellrai';

async function setup() {
  await hdb.pipelines.create({
    name:  'payment.execute.standard',
    steps: [
      { id: 'validate', name: 'Validate',        type: 'action' },
      {
        id:                'charge',
        name:              'Charge',
        type:              'action',
        dependsOn:         ['validate'],
        compensationStep:  'refund',
      },
      { id: 'refund',  name: 'Refund',           type: 'action' },
      { id: 'record',  name: 'Record',           type: 'action', dependsOn: ['charge'] },
    ],
  });
  console.log('Pipeline registered');
}

setup();

Run this once. Re-running creates a new version without breaking existing executions.

Process a payment

// services/payment.service.ts
import { hdb } from '../lib/stellrai';
import { HybriDBError } from '@hybridb/sdk';

export async function processPayment(params: {
  userId:     string;
  amount:     number;
  currency:   string;
  toAccount:  string;
  orderId:    string;
}) {
  const { userId, amount, currency, toAccount, orderId } = params;

  // 1. Request decision
  const decision = await hdb.requestDecision({
    decisionType:    'payment.authorize',
    action:          'payment.initiate',
    inputData:       { actorId: `user:${userId}`, amount, currency },
    resourceType:    'payment',
    idempotencyKey:  `decision-${orderId}`,
  });

  if (decision.outcome === 'blocked') {
    return { status: 'blocked', reason: decision.rationale };
  }

  if (decision.outcome === 'escalated') {
    // Queue for manual review — do not execute
    await scheduleReview(decision.decisionId, orderId);
    return { status: 'pending_review' };
  }

  // 2. Execute pipeline
  const execution = await hdb.triggerPipelineByName('payment.execute.standard', {
    decisionId:      decision.decisionId,
    input:           { amount, currency, to: toAccount },
    idempotencyKey:  `exec-${orderId}`,
  });

  return {
    status:      'success',
    executionId: execution.id,
  };
}

Rollback a payment

export async function reversePayment(executionId: string, reason: string) {
  try {
    await hdb.reversibility.rollback(executionId, { reason });
    return { reversed: true };
  } catch (err) {
    if (err instanceof HybriDBError && err.code === 'ROLLBACK_WINDOW_EXPIRED') {
      // Fallback to manual reversal process
      await flagForManualReversal(executionId);
      return { reversed: false, reason: 'window_expired' };
    }
    throw err;
  }
}

Environment variables

# .env
HDB_API_KEY=sk-hdb-...
HDB_BASE_URL=https://hybridb.stellrai.com   # optional

Never commit .env. Use your deployment platform's secret management.