JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 30
  • Score
    100M100P100Q45788F
  • License PROPRIETARY

Node.js SDK for the Dominus Orchestrator Platform

Package Exports

  • dominus-sdk-nodejs-dev
  • dominus-sdk-nodejs-dev/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (dominus-sdk-nodejs-dev) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

CB Dominus SDK for Node.js

TypeScript SDK for the Dominus Orchestrator Platform

A unified, async-first TypeScript SDK providing seamless access to all Dominus backend services including secrets management, database operations, caching, file storage, authentication, schema management, and structured logging.

Features

  • Namespace-based API - Intuitive access via dominus.db, dominus.redis, dominus.files, etc.
  • Async/Await - Built for modern async TypeScript/JavaScript applications
  • Automatic JWT Management - Token minting, caching, and refresh handled transparently
  • Resilience Built-in - Circuit breaker, exponential backoff with jitter, retry logic
  • Cold Start Handling - Special retry logic for orchestrator cold starts
  • Typed Errors - 9 specific error classes for different failure modes
  • Secure by Default - Client-side password hashing, audit trail support
  • Server-Side Only - Designed for Next.js API routes, Express, and Node.js backends

Quick Start

import { dominus } from 'dominus-sdk-nodejs';

// Set your token (or use DOMINUS_TOKEN environment variable)
process.env.DOMINUS_TOKEN = "your-psk-token";

// Secrets
const dbUrl = await dominus.secrets.get("DATABASE_URL");

// Database queries
const users = await dominus.db.query("users", { filters: { status: "active" } });

// Redis caching
await dominus.redis.set("session:123", { user: "john" }, { ttl: 3600 });

// File storage
const result = await dominus.files.upload(buffer, "report.pdf", { category: "reports" });

// Structured logging
await dominus.logs.info("User logged in", { user_id: "123" });

Installation

npm install dominus-sdk-nodejs

Or add directly from GitHub:

npm install github:carebridgesystems/cb-dominus-sdk-nodejs

Requirements

  • Node.js 18+ (uses native fetch)
  • TypeScript 5.0+ (optional, but recommended)

Namespaces

Namespace Service Purpose
dominus.secrets Warden Secrets management
dominus.db Scribe Database CRUD operations
dominus.secure Scribe Secure table access with audit logging
dominus.redis Whisperer Redis caching & distributed locks
dominus.files Archivist Object storage (Backblaze B2)
dominus.auth Guardian Users, roles, scopes, tenants, pages, navigation
dominus.ddl Smith Schema DDL & migrations
dominus.logs Herald Structured logging (BetterStack)
dominus.portal Portal User auth, sessions, profiles, navigation
dominus.courier Courier Email delivery (Postmark)
dominus.open Scribe Direct database access
dominus.health Health Service health checks

Usage Examples

Secrets Management

// Get a secret
const value = await dominus.secrets.get("API_KEY");

// Create or update
await dominus.secrets.upsert("API_KEY", "new-value", "Updated API key");

// List secrets with prefix
const secrets = await dominus.secrets.list("DB_");

// Delete
await dominus.secrets.delete("OLD_KEY");

// Root-level shortcuts
const dbUrl = await dominus.get("DATABASE_URL");
await dominus.upsert("KEY", "value");

Database Operations

// List tables
const tables = await dominus.db.tables();
const tenantTables = await dominus.db.tables("tenant_acme");

// Query with filters and pagination
const users = await dominus.db.query("users", {
  filters: { status: "active", role: ["admin", "manager"] },
  sortBy: "created_at",
  sortOrder: "DESC",
  limit: 50,
  offset: 0
});

// Insert
const user = await dominus.db.insert("users", {
  email: "john@example.com",
  name: "John Doe"
});

// Update
await dominus.db.update("users", { status: "inactive" }, { id: userId });

// Delete
await dominus.db.delete("users", { id: userId });

// Bulk insert
await dominus.db.bulkInsert("events", [
  { type: "login", user_id: "123" },
  { type: "login", user_id: "456" }
]);

// Secure table access (requires audit reason)
const patients = await dominus.db.query("patients", {
  schema: "tenant_acme",
  reason: "Reviewing records for appointment #123",
  actor: "dr.smith"
});

Redis Caching

// Key-value operations
await dominus.redis.set("user:123", { name: "John" }, { ttl: 3600 });
const value = await dominus.redis.get("user:123");

// Distributed locks
const acquired = await dominus.redis.setnx("lock:job", "worker-1", { ttl: 60 });
if (acquired) {
  try {
    // Do exclusive work
  } finally {
    await dominus.redis.delete("lock:job");
  }
}

// Counters
await dominus.redis.incr("page:views", 1);

// Hash operations
await dominus.redis.hset("user:123", "email", "john@example.com", { ttl: 3600 });
const email = await dominus.redis.hget("user:123", "email");
const allFields = await dominus.redis.hgetall("user:123");

File Storage

import { readFileSync } from 'fs';

// Upload file
const data = readFileSync("report.pdf");
const result = await dominus.files.upload(data, "report.pdf", {
  category: "reports",
  contentType: "application/pdf"
});

// Get download URL
const download = await dominus.files.download({ id: result.id });
console.log(download.download_url);

// Fetch file from URL and store
const fetched = await dominus.files.fetch("https://example.com/doc.pdf", {
  filename: "external-doc.pdf",
  category: "imports"
});

// List files
const files = await dominus.files.list({ category: "reports", prefix: "2025/" });

// Delete file
await dominus.files.delete({ id: result.id });

Structured Logging

// Simple logging (auto-captures file and function)
await dominus.logs.info("User logged in", { user_id: "123" });
await dominus.logs.error("Payment failed", { order_id: "456" });

// All log levels
await dominus.logs.debug("Debug message", { data: "..." });
await dominus.logs.notice("Important notice", {});
await dominus.logs.warn("Warning message", {});
await dominus.logs.critical("Critical error", {});

// With category
await dominus.logs.info("Cache hit", { key: "user:123" }, "cache");

// With exception
try {
  riskyOperation();
} catch (error) {
  await dominus.logs.error("Operation failed", {}, { exception: error as Error });
}

// Batch logging
await dominus.logs.batch([
  { level: "info", message: "Step 1 complete", data: {} },
  { level: "info", message: "Step 2 complete", data: {} }
]);

// Query logs
const errors = await dominus.logs.query({ level: "error", limit: 100 });

Authentication & Authorization (Guardian)

// User management
const users = await dominus.auth.listUsers();
const user = await dominus.auth.getUser("user-uuid");

const newUser = await dominus.auth.addUser({
  username: "john",
  password: "secure-password",
  email: "john@example.com"
});

await dominus.auth.updateUser("user-uuid", { status: "active" });
await dominus.auth.deleteUser("user-uuid");

// Role management
const roles = await dominus.auth.listRoles();
const role = await dominus.auth.addRole({
  name: "Editor",
  scopeSlugs: ["read", "write", "publish"]
});

// Scope management
const scopes = await dominus.auth.listScopes();
await dominus.auth.addScope({ name: "publish", slug: "publish" });

// Tenant management
const tenants = await dominus.auth.listTenants();
const categories = await dominus.auth.listTenantCategories();

// Page and navigation
const pages = await dominus.auth.listPages();
const navItems = await dominus.auth.listNavigation();

// Secure tables registry
const secureTables = await dominus.auth.listSecureTables();
await dominus.auth.addSecureTable("patients", "tenant_acme");

Schema Management (DDL)

// Create table
await dominus.ddl.createTable("orders", [
  { name: "id", type: "UUID", constraints: ["PRIMARY KEY"] },
  { name: "user_id", type: "UUID", constraints: ["NOT NULL"] },
  { name: "total", type: "DECIMAL(10,2)" },
  { name: "created_at", type: "TIMESTAMPTZ", default: "NOW()" }
]);

// Add column
await dominus.ddl.addColumn("orders", {
  name: "status",
  type: "VARCHAR(50)",
  default: "'pending'"
});

// Alter column
await dominus.ddl.alterColumn("orders", "status", { type: "VARCHAR(100)" });

// Create index
await dominus.ddl.createIndex("orders", "idx_orders_user", ["user_id"]);

// Migrations
const migrations = await dominus.ddl.listMigrations();
await dominus.ddl.applyMigration("20250101_add_orders");

// Provision tenant schema from category template
await dominus.ddl.provisionTenantFromCategory("customer_acme", "healthcare");

User Authentication (Portal)

// User login (tenant_id is optional)
const session = await dominus.portal.login(
  "john@example.com",
  "secret123",
  "tenant-uuid"  // optional
);

// Client login with PSK (for service-to-service)
const clientSession = await dominus.portal.loginClient("psk-token");

// Get current user
const me = await dominus.portal.me();

// Get navigation (access-filtered for current user)
const nav = await dominus.portal.getNavigation();

// Check page access
const hasAccess = await dominus.portal.checkPageAccess("/dashboard/admin/users");

// Switch tenant
await dominus.portal.switchTenant("other-tenant-uuid");

// Profile & preferences
const profile = await dominus.portal.getProfile();
await dominus.portal.updateProfile({ displayName: "John Doe" });

const prefs = await dominus.portal.getPreferences();
await dominus.portal.updatePreferences({
  theme: "dark",
  timezone: "America/New_York"
});

// Password management
await dominus.portal.changePassword("old-password", "new-password");
await dominus.portal.requestPasswordReset("john@example.com");
await dominus.portal.confirmPasswordReset("reset-token", "new-password");

// Session management
const sessions = await dominus.portal.listSessions();
await dominus.portal.revokeSession("session-id");
await dominus.portal.revokeAllSessions();

// Registration & email verification
await dominus.portal.register("newuser", "new@example.com", "password", "tenant-id");
await dominus.portal.verifyEmail("verification-token");
await dominus.portal.resendVerification("new@example.com");

// Logout
await dominus.portal.logout();

Email Delivery (Courier)

// Send email via Postmark template
const result = await dominus.courier.send(
  "welcome",
  "user@example.com",
  "noreply@myapp.com",
  { name: "John", product_name: "My App" }
);

// Convenience methods
await dominus.courier.sendWelcome(
  "user@example.com",
  "noreply@myapp.com",
  { name: "John", actionUrl: "https://myapp.com/start", productName: "My App" }
);

await dominus.courier.sendPasswordReset(
  "user@example.com",
  "noreply@myapp.com",
  { name: "John", resetUrl: "https://myapp.com/reset?token=abc", productName: "My App" }
);

await dominus.courier.sendEmailVerification(
  "user@example.com",
  "noreply@myapp.com",
  { name: "John", verifyUrl: "https://myapp.com/verify?token=xyz", productName: "My App" }
);

await dominus.courier.sendInvitation(
  "invited@example.com",
  "noreply@myapp.com",
  {
    name: "Invited User",
    inviteUrl: "https://myapp.com/invite?token=abc",
    inviterName: "John",
    productName: "My App"
  }
);

Health Checks

// Basic health check
const status = await dominus.health.check();

// Ping (lightweight)
await dominus.health.ping();

// Warmup (for cold start tolerance)
await dominus.health.warmup();

Error Handling

import {
  dominus,
  DominusError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ValidationError,
  ConflictError,
  ServiceError,
  SecureTableError,
  ConnectionError,
  TimeoutError,
} from 'dominus-sdk-nodejs';

try {
  const user = await dominus.auth.getUser("invalid-id");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`User not found: ${error.message}`);
  } else if (error instanceof SecureTableError) {
    console.log("Secure table requires 'reason' and 'actor' parameters");
  } else if (error instanceof AuthenticationError) {
    console.log("Invalid or expired token");
  } else if (error instanceof AuthorizationError) {
    console.log("Insufficient permissions");
  } else if (error instanceof ValidationError) {
    console.log(`Invalid request: ${error.message}`);
  } else if (error instanceof TimeoutError) {
    console.log("Request timed out");
  } else if (error instanceof DominusError) {
    console.log(`Error ${error.statusCode}: ${error.message}`);
    if (error.details) {
      console.log(`Details: ${JSON.stringify(error.details)}`);
    }
  }
}

Error Types

Error Status Description
AuthenticationError 401 Invalid or missing token
AuthorizationError 403 Insufficient permissions
NotFoundError 404 Resource not found
ValidationError 400 Invalid request data
ConflictError 409 Duplicate or version conflict
ServiceError 5xx Backend service error
SecureTableError 403 Missing reason for secure table
ConnectionError - Network connection failed
TimeoutError 504 Request timed out

Configuration

Environment Variables

# Required: PSK token for authentication
export DOMINUS_TOKEN="your-psk-token"

Resilience Configuration

The SDK includes built-in resilience features:

Feature Configuration
Request Timeout 30 seconds
Max Retries 3 with exponential backoff
Circuit Breaker Opens after 5 failures, resets after 30s
JWT Cache TTL Refreshes when <60 seconds remain
JWT Mint Retries 3 with backoff (handles cold starts)
Backoff Delays Base 1s, max 15s with jitter

Architecture

┌─────────────────┐
│  Your App       │
│  (Next.js API)  │
└────────┬────────┘
         │ await dominus.db.query(...)
         ▼
┌─────────────────┐
│  Dominus SDK    │  ← JWT caching, circuit breaker, retries
│  (this package) │
└────────┬────────┘
         │ HTTPS (base64-encoded JSON)
         ▼
┌─────────────────────────────────┐
│  Dominus Orchestrator           │
│  (Cloud Run FastAPI backend)    │
│                                 │
│  ┌─────────┬─────────┬────────┐ │
│  │ Warden  │Guardian │Archivist│ │
│  │ Scribe  │ Smith   │Whisperer│ │
│  │ Herald  │ Portal  │ Courier │ │
│  └─────────┴─────────┴────────┘ │
└─────────────────────────────────┘

Next.js Integration

// app/api/users/route.ts
import { dominus, NotFoundError } from 'dominus-sdk-nodejs';
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  try {
    const users = await dominus.db.query("users", {
      filters: { status: "active" },
      limit: 50
    });
    return NextResponse.json(users);
  } catch (error) {
    if (error instanceof NotFoundError) {
      return NextResponse.json({ error: "Not found" }, { status: 404 });
    }
    return NextResponse.json({ error: "Failed to fetch users" }, { status: 500 });
  }
}

Crypto Helpers

The SDK exports utility functions for password and token handling:

import {
  hashPassword,
  verifyPasswordLocal,
  hashPsk,
  verifyPskLocal,
  generatePskLocal,
  hashToken,
  generateToken
} from 'dominus-sdk-nodejs';

// Password hashing (bcrypt)
const hash = await hashPassword("user-password");
const isValid = await verifyPasswordLocal("user-password", hash);

// PSK generation and verification
const psk = generatePskLocal();
const pskHash = await hashPsk(psk);
const pskValid = await verifyPskLocal(psk, pskHash);

// Token generation
const token = generateToken(32);  // 32-byte random token
const tokenHash = hashToken(token);  // SHA-256 hash

Dependencies

  • bcryptjs - Password hashing

Version

v1.2.2 - Latest release with navigation routes fix and page scope methods

Changelog

  • v1.2.2 - Fix checkPageAccess to send correct parameter
  • v1.2.0 - Add navigation routes and page scope methods
  • v1.1.6 - Add user token support for user-authenticated requests
  • v1.1.5 - Make tenant_id optional in login methods
  • v1.1.3 - Add retry with backoff for JWT mint (cold start handling)
  • v1.1.0 - Fix SDK routes and improve error messaging
  • v1.0.0 - Initial release with full namespace API

License

Proprietary - CareBridge Systems