dominus-sdk-nodejs-staging 1.2.4

package/LLM-GUIDE.md

@@ -0,0 +1,537 @@
+# CB Dominus SDK for Node.js - LLM Guide
+
+This guide provides comprehensive documentation for LLMs to understand and use the Dominus SDK effectively.
+
+## Overview
+
+The Dominus SDK is a TypeScript SDK for Node.js that provides access to the Dominus Orchestrator backend services. It uses a namespace-based API pattern with a singleton instance.
+
+## Installation & Setup
+
+```typescript
+// Import the singleton
+import { dominus } from 'dominus-sdk-nodejs';
+
+// Token is read from DOMINUS_TOKEN environment variable
+// Set it before using the SDK:
+process.env.DOMINUS_TOKEN = "your-psk-token";
+```
+
+## Namespace Reference
+
+### dominus.secrets (Warden)
+
+Secrets management operations.
+
+```typescript
+// Get secret value
+const value = await dominus.secrets.get("SECRET_KEY");
+
+// Create/update secret
+await dominus.secrets.upsert("KEY", "value", "optional comment");
+
+// List secrets (optionally with prefix)
+const secrets = await dominus.secrets.list("DB_");
+
+// Delete secret
+await dominus.secrets.delete("OLD_KEY");
+```
+
+### dominus.db (Scribe)
+
+Database CRUD operations.
+
+```typescript
+// List tables in a schema
+const tables = await dominus.db.tables("public");
+
+// List columns in a table
+const columns = await dominus.db.columns("users", "public");
+
+// Query with full options
+const result = await dominus.db.query("users", {
+  schema: "public",
+  filters: { status: "active" },
+  sortBy: "created_at",
+  sortOrder: "DESC",
+  limit: 100,
+  offset: 0,
+  reason: "optional - required for secure tables",
+  actor: "user-id - required for secure tables"
+});
+// result.rows = array of records
+// result.total = total count
+
+// Insert row
+const inserted = await dominus.db.insert("users", { name: "John" }, {
+  schema: "public",
+  reason: "optional",
+  actor: "optional"
+});
+
+// Update rows
+const updated = await dominus.db.update(
+  "users",
+  { status: "inactive" },  // data to set
+  { id: "user-123" },      // filters (WHERE)
+  { schema: "public" }
+);
+// updated.affected_rows = number
+
+// Delete rows
+const deleted = await dominus.db.delete("users", { id: "user-123" }, {
+  schema: "public"
+});
+// deleted.affected_rows = number
+
+// Bulk insert
+const bulk = await dominus.db.bulkInsert("users", [
+  { name: "John" },
+  { name: "Jane" }
+], { schema: "public" });
+// bulk.inserted_count = number
+```
+
+### dominus.redis (Whisperer)
+
+Redis caching operations. TTL is required and enforced (60-86400 seconds).
+
+```typescript
+// Set with TTL (required)
+await dominus.redis.set("key", { data: "value" }, { ttl: 3600 });
+
+// Get value
+const value = await dominus.redis.get("key");
+
+// Delete
+await dominus.redis.delete("key");
+
+// List keys by pattern
+const keys = await dominus.redis.list({ pattern: "user:*" });
+
+// Multi-get
+const values = await dominus.redis.mget(["key1", "key2"]);
+
+// Set if not exists (for locks)
+const acquired = await dominus.redis.setnx("lock:key", "value", { ttl: 60 });
+
+// Increment counter
+await dominus.redis.incr("counter", 1);
+
+// Hash operations
+await dominus.redis.hset("hash", "field", "value", { ttl: 3600 });
+const field = await dominus.redis.hget("hash", "field");
+const allFields = await dominus.redis.hgetall("hash");
+await dominus.redis.hdel("hash", "field");
+```
+
+### dominus.files (Archivist)
+
+File storage operations via B2.
+
+```typescript
+// Upload file
+const result = await dominus.files.upload(
+  buffer,        // Buffer
+  "filename.pdf",
+  {
+    contentType: "application/pdf",
+    category: "reports",
+    path: "2025/01/report.pdf",
+    tags: { department: "finance" },
+    compliance: false,
+    actor: "user-id",
+    retentionDays: 90
+  }
+);
+// result.id = file UUID
+// result.path = stored path
+// result.size = bytes
+
+// Get download URL
+const download = await dominus.files.download({
+  id: "file-uuid",
+  // OR use category + path:
+  // category: "reports",
+  // path: "2025/01/report.pdf",
+  expiresSeconds: 3600
+});
+// download.download_url = presigned URL
+// download.expires_at = expiration timestamp
+
+// Fetch content directly
+const content = await dominus.files.fetch({ id: "file-uuid" });
+// content.data = base64 encoded
+// content.filename = original name
+// content.content_type = mime type
+
+// List files
+const files = await dominus.files.list({
+  category: "reports",
+  prefix: "2025/",
+  limit: 100,
+  cursor: "optional-pagination-cursor"
+});
+// files.objects = array
+// files.cursor = next page cursor
+// files.count = number returned
+
+// Delete file
+await dominus.files.delete({ id: "file-uuid" });
+
+// Move file
+await dominus.files.move("file-uuid", {
+  newCategory: "archive",
+  newPath: "2024/report.pdf"
+});
+
+// Update metadata
+await dominus.files.updateMeta("file-uuid", {
+  tags: { status: "reviewed" },
+  description: "Annual report"
+});
+```
+
+### dominus.auth (Guardian)
+
+Authentication and authorization management.
+
+```typescript
+// Users
+const users = await dominus.auth.listUsers();
+const user = await dominus.auth.getUser("user-uuid");
+const newUser = await dominus.auth.addUser({
+  username: "john",
+  password: "secret123",  // hashed client-side
+  email: "john@example.com",
+  roleId: "role-uuid"
+});
+await dominus.auth.updateUser("user-uuid", { email: "new@email.com" });
+await dominus.auth.deleteUser("user-uuid");
+
+// Roles
+const roles = await dominus.auth.listRoles();
+const role = await dominus.auth.getRole("role-uuid");
+const newRole = await dominus.auth.addRole({
+  name: "Editor",
+  scopeSlugs: ["read", "write"],
+  description: "Can edit content"
+});
+await dominus.auth.updateRole("role-uuid", { name: "Senior Editor" });
+await dominus.auth.deleteRole("role-uuid");
+
+// Scopes
+const scopes = await dominus.auth.listScopes();
+const scope = await dominus.auth.getScope("scope-uuid");
+const newScope = await dominus.auth.addScope({
+  slug: "publish",
+  displayName: "Publish Content",
+  description: "Can publish content"
+});
+await dominus.auth.updateScope("scope-uuid", { display_name: "New Name" });
+await dominus.auth.deleteScope("scope-uuid");
+
+// Clients (service accounts)
+const clients = await dominus.auth.listClients();
+const client = await dominus.auth.getClient("client-uuid");
+const newClient = await dominus.auth.addClient({
+  label: "API Client",
+  roleId: "role-uuid"
+});
+await dominus.auth.deleteClient("client-uuid");
+
+// Tenants
+const tenants = await dominus.auth.listTenants();
+const tenant = await dominus.auth.getTenant("tenant-uuid");
+const newTenant = await dominus.auth.addTenant({
+  name: "Acme Corp",
+  slug: "acme",
+  categoryId: "category-uuid"
+});
+await dominus.auth.updateTenant("tenant-uuid", { name: "Acme Inc" });
+await dominus.auth.deleteTenant("tenant-uuid");
+
+// Tenant Categories
+const categories = await dominus.auth.listTenantCategories();
+const category = await dominus.auth.getTenantCategory("category-uuid");
+
+// Pages & Navigation
+const pages = await dominus.auth.listPages();
+const navigation = await dominus.auth.listNavigation();
+
+// Secure Tables
+const secureTables = await dominus.auth.listSecureTables();
+await dominus.auth.addSecureTable({ schema: "tenant_acme", tableName: "patients" });
+await dominus.auth.deleteSecureTable("table-uuid");
+```
+
+### dominus.ddl (Smith)
+
+Schema DDL and migration operations.
+
+```typescript
+// Schema DDL (single schema)
+await dominus.ddl.createTable("orders", [
+  { name: "id", type: "UUID", constraints: ["PRIMARY KEY", "DEFAULT gen_random_uuid()"] },
+  { name: "user_id", type: "UUID", constraints: ["NOT NULL"] },
+  { name: "total", type: "DECIMAL(10,2)" },
+  { name: "status", type: "VARCHAR(50)", default: "'pending'" }
+], "public");
+
+await dominus.ddl.dropTable("temp_table", "public");
+
+await dominus.ddl.addColumn("orders", {
+  name: "notes",
+  type: "TEXT",
+  constraints: [],
+  default: undefined
+}, "public");
+
+await dominus.ddl.dropColumn("orders", "notes", "public");
+
+await dominus.ddl.alterColumn("orders", "status", {
+  newType: "VARCHAR(100)",
+  newDefault: "'new'",
+  nullable: false
+}, "public");
+
+await dominus.ddl.createIndex("orders", "idx_orders_user", ["user_id"], {
+  unique: false,
+  schema: "public"
+});
+
+await dominus.ddl.dropIndex("idx_orders_user", "public");
+
+// Category DDL (multi-schema - all tenants in category)
+await dominus.ddl.categoryCreateTable("healthcare", "appointments", [
+  { name: "id", type: "UUID", constraints: ["PRIMARY KEY"] }
+]);
+
+await dominus.ddl.categoryAddColumn("healthcare", "appointments", {
+  name: "notes",
+  type: "TEXT"
+});
+
+// Migrations
+const migrations = await dominus.ddl.listMigrations("tenant_acme");
+const categoryMigrations = await dominus.ddl.listCategoryMigrations("healthcare");
+await dominus.ddl.applyMigration("tenant_acme", "migration-id");
+await dominus.ddl.rollbackMigration("tenant_acme", "migration-id");
+
+// Provisioning
+await dominus.ddl.provisionTenantSchema("new_tenant", "healthcare");
+await dominus.ddl.provisionTenantFromCategory("new_tenant", "healthcare");
+```
+
+### dominus.logs (Herald)
+
+Structured logging operations.
+
+```typescript
+// Log levels: debug, info, notice, warn, error, critical
+await dominus.logs.debug("Debug message", { key: "value" }, "category");
+await dominus.logs.info("Info message", { key: "value" });
+await dominus.logs.notice("Notice message", { key: "value" });
+await dominus.logs.warn("Warning message", { key: "value" });
+await dominus.logs.error("Error message", { key: "value" }, {
+  category: "errors",
+  exception: new Error("Something failed")
+});
+await dominus.logs.critical("Critical message", { key: "value" }, {
+  exception: error
+});
+
+// Query logs
+const logs = await dominus.logs.query({
+  level: "error",
+  category: "payments",
+  startTime: "2025-01-01T00:00:00Z",
+  endTime: "2025-01-31T23:59:59Z",
+  file: "payment.ts",
+  function: "processPayment",
+  search: "failed",
+  limit: 100,
+  // Admin only:
+  project: "my-project",
+  environment: "production"
+});
+
+// Batch logging
+await dominus.logs.batch([
+  { level: "info", message: "First", context: {} },
+  { level: "info", message: "Second", context: {} }
+]);
+```
+
+### dominus.portal (Portal)
+
+User authentication and session management.
+
+```typescript
+// Authentication
+const session = await dominus.portal.login("user@example.com", "password", "tenant-uuid");
+const clientSession = await dominus.portal.loginClient("client-uuid", "psk", "tenant-uuid");
+await dominus.portal.logout();
+await dominus.portal.refresh();
+const me = await dominus.portal.me();
+await dominus.portal.switchTenant("other-tenant-uuid");
+
+// Security
+await dominus.portal.changePassword("current", "new");
+await dominus.portal.requestPasswordReset("email@example.com");
+await dominus.portal.confirmPasswordReset("token", "newPassword");
+const sessions = await dominus.portal.listSessions();
+await dominus.portal.revokeSession("session-uuid");
+await dominus.portal.revokeAllSessions();
+
+// Profile
+const profile = await dominus.portal.getProfile();
+await dominus.portal.updateProfile({
+  displayName: "John Doe",
+  avatarUrl: "https://...",
+  bio: "Developer",
+  phone: "+1234567890",
+  extra: { custom: "data" }
+});
+const prefs = await dominus.portal.getPreferences();
+await dominus.portal.updatePreferences({
+  theme: "dark",
+  language: "en",
+  timezone: "America/New_York",
+  sidebarCollapsed: false,
+  notificationsEnabled: true,
+  emailNotifications: true,
+  extra: { custom: "prefs" }
+});
+
+// Navigation
+const nav = await dominus.portal.getNavigation();
+const access = await dominus.portal.checkPageAccess("/admin/users");
+// access.allowed = boolean
+// access.reason = string (if denied)
+
+// Registration
+await dominus.portal.register("username", "email@example.com", "password", "tenant-uuid");
+await dominus.portal.verifyEmail("token");
+await dominus.portal.resendVerification("email@example.com");
+await dominus.portal.acceptInvitation("token", "password");
+```
+
+### dominus.courier (Courier)
+
+Email delivery via Postmark.
+
+```typescript
+// Send with template
+const result = await dominus.courier.send(
+  "template-alias",
+  "recipient@example.com",
+  "sender@myapp.com",
+  { name: "John", product_name: "MyApp" },
+  { tag: "welcome", replyTo: "support@myapp.com" }
+);
+// result.to, result.message_id, result.submitted_at
+
+// Convenience methods
+await dominus.courier.sendWelcome(
+  "user@example.com",
+  "noreply@myapp.com",
+  { name: "John", productName: "MyApp", actionUrl: "https://..." }
+);
+
+await dominus.courier.sendPasswordReset(
+  "user@example.com",
+  "noreply@myapp.com",
+  { name: "John", resetUrl: "https://...", productName: "MyApp" }
+);
+
+await dominus.courier.sendEmailVerification(
+  "user@example.com",
+  "noreply@myapp.com",
+  { name: "John", verifyUrl: "https://...", productName: "MyApp" }
+);
+
+await dominus.courier.sendInvitation(
+  "invitee@example.com",
+  "noreply@myapp.com",
+  {
+    name: "Jane",
+    inviteUrl: "https://...",
+    inviterName: "John",
+    productName: "MyApp"
+  }
+);
+```
+
+### dominus.open (Scribe Open)
+
+Direct database access (use with caution).
+
+```typescript
+// Get PostgreSQL connection DSN
+const dsn = await dominus.open.dsn();
+
+// Execute raw SQL
+const result = await dominus.open.execute(
+  "SELECT * FROM users WHERE id = $1",
+  { "1": "user-uuid" }
+);
+```
+
+### dominus.health (Health)
+
+Service health checks.
+
+```typescript
+// Full health check with latency
+const status = await dominus.health.check();
+// status.status = "healthy" | "unhealthy"
+// status.latency_ms = number
+
+// Quick ping
+const ping = await dominus.health.ping();
+// ping.status = "ok"
+
+// Warmup (triggers cold start)
+await dominus.health.warmup();
+```
+
+## Error Handling
+
+```typescript
+import {
+  DominusError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  ServiceError,
+  ConnectionError,
+  TimeoutError,
+  SecureTableError,
+} from '@carebridge/dominus-sdk';
+
+try {
+  await dominus.db.query("secure_table");
+} catch (error) {
+  if (error instanceof SecureTableError) {
+    // Need reason and actor for secure tables
+  } else if (error instanceof NotFoundError) {
+    // Resource not found
+  } else if (error instanceof AuthorizationError) {
+    // Permission denied
+  } else if (error instanceof DominusError) {
+    // Generic error with statusCode, message, details
+  }
+}
+```
+
+## Key Patterns
+
+1. **Singleton import**: Always use `import { dominus } from '@carebridge/dominus-sdk'`
+2. **Async/await**: All methods are async
+3. **Schema parameter**: Database operations support schema parameter for multi-tenancy
+4. **Secure tables**: Require `reason` and `actor` parameters for audit trail
+5. **TTL required**: Redis operations require TTL (60-86400 seconds)
+6. **Error types**: Use specific error classes for precise error handling