@d19n/youfibre-odin-sdk 1.0.244 → 1.0.246

package/README.md

@@ -1,1197 +1,320 @@
-# YouFibre ODIN SDK
+# ODIN SDK
 
-Typed SDK for the ODIN platform providing full type safety for records, actions, and properties.
+Type-safe SDK for the ODIN platform with comprehensive entity and action support.
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [API Client (External Access)](#api-client-external-access)
-- [DB Client (Backend Services)](#db-client-backend-services)
-- [Working with Records](#working-with-records)
-- [Executing Actions](#executing-actions)
-- [Searching Records](#searching-records)
-- [Linking Records](#linking-records)
-- [Migration Guide](#migration-guide)
 - [Architecture](#architecture)
-
----
+- [API Client](#api-client)
+- [DB Client](#db-client)
+- [Entities](#entities)
+- [Actions](#actions)
+- [Record Wrappers](#record-wrappers)
+- [Events](#events)
+- [Migration Guide](#migration-guide)
 
 ## Installation
 
 ```bash
-npm install @youfibre/odin-sdk
+npm install @d19n/youfibre-odin-sdk
 ```
 
----
-
 ## Quick Start
 
-### API Access (Scripts, External Clients)
+### API Client (Frontend/External Services)
 
 ```typescript
-import { OdinApiClient } from '@youfibre/odin-sdk';
+import { OdinApiClient } from '@d19n/youfibre-odin-sdk';
 
+// Initialize with OAuth credentials
 const odin = new OdinApiClient({
-  host: 'api.youfibre.com',
-  clientId: process.env.ODIN_CLIENT_ID!,
-  clientSecret: process.env.ODIN_CLIENT_SECRET!,
+  host: process.env.ODIN_HOST_URL,
+  clientId: process.env.ODIN_CLIENT_ID,
+  clientSecret: process.env.ODIN_CLIENT_SECRET,
 });
 
-// Get an order and execute an action
-const order = await odin.orders.get('ORD-123');
-console.log(order.properties.Status);
-
-await order.activateOrder({ ActiveDate: '2025-01-15' });
-```
-
-### DB Access (Backend Services)
-
-```typescript
-import { OdinDbClient } from '@youfibre/odin-sdk';
-
-// In a NestJS service
-@Injectable()
-export class OrderService {
-  constructor(private readonly dbService: DbService) {}
-
-  async activateOrder(principal: any, orderId: string) {
-    const odin = new OdinDbClient(principal, this.dbService);
-    
-    const order = await odin.orders.get(orderId);
-    await order.activateOrder({ ActiveDate: new Date().toISOString() });
-  }
-}
-```
-
----
-
-## API Client (External Access)
-
-Use `OdinApiClient` for external API access from scripts, CLIs, or external services.
-
-### Constructor Options
-
-```typescript
-// Option 1: OAuth credentials
-const odin = new OdinApiClient({
-  host: 'api.youfibre.com',
-  clientId: 'your-client-id',
-  clientSecret: 'your-client-secret',
-});
-
-// Option 2: Existing JWT token
-const odin = OdinApiClient.withToken('eyJhbG...', 'api.youfibre.com');
-
-// Option 3: Existing ApiProvider
-import { ApiProvider } from '@d19n/odin-sdk-generator';
-const provider = new ApiProvider({ host, clientId, clientSecret });
-const odin = new OdinApiClient(provider);
-```
-
-### Available Accessors
-
-All entity accessors are lazy-loaded on first access:
-
-```typescript
-odin.orders          // OrderAccessor
-odin.contacts        // ContactAccessor
-odin.addresses       // AddressAccessor
-odin.accounts        // AccountAccessor
-odin.invoices        // InvoiceAccessor
-odin.workOrders      // WorkOrderAccessor
-odin.visits          // VisitAccessor
-// ... and all other entities
-```
-
----
-
-## DB Client (Backend Services)
-
-Use `OdinDbClient` for direct database access in backend services (NestJS, etc.).
-
-### Constructor
-
-```typescript
-const odin = new OdinDbClient(principal, dbService);
-```
-
-- `principal`: The authenticated user context
-- `dbService`: The database service instance (typically injected)
-
-### Example: NestJS Service
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { OdinDbClient } from '@youfibre/odin-sdk';
-import { DbService } from '@d19n/schema-manager/dist/db/db.service';
-
-@Injectable()
-export class WorkOrderService {
-  constructor(private readonly dbService: DbService) {}
-
-  async completeWorkOrder(principal: any, workOrderId: string) {
-    const odin = new OdinDbClient(principal, this.dbService);
-    
-    const workOrder = await odin.workOrders.get(workOrderId);
-    
-    await workOrder.completeWorkOrder({
-      CompletedDate: new Date().toISOString(),
-      Notes: 'Work completed successfully',
-    });
-  }
-}
-```
-
----
-
-## Working with Records
-
-### Getting Records
-
-```typescript
-// Get single record by ID
-const order = await odin.orders.get('uuid-here');
-
-// Get multiple records by IDs
-const orders = await odin.orders.getMany(['uuid-1', 'uuid-2', 'uuid-3']);
-```
-
-### Record Properties
-
-Records are wrapped with typed access to all properties:
-
-```typescript
+// Get a record with typed properties
 const order = await odin.orders.get(orderId);
+console.log(order.properties?.Status);
+
+// Execute a simple action
+await order.activateOrder({ ActivationDate: "2025-01-01" });
+
+// Execute a multi-step flow action
+const cboRec = await odin.contractBuyOuts.get(cboId);
+await cboRec
+  .moveCboToApproved({ journeyId: order.id })
+  .approveCbo(cboRec.id, {
+    Amount: cboRec.properties.Amount,
+    FinalBillVerified: cboRec.properties.FinalBillVerified,
+  })
+  .execute();
 
-// Core properties
-order.id            // string
-order.entity        // string (e.g., 'OrderModule:Order')
-order.type          // string | undefined
-order.title         // string | undefined
-order.recordNumber  // string | undefined
-order.stage         // PipelineStageEntity | undefined
-order.createdAt     // string | undefined
-order.updatedAt     // string | undefined
-
-// Entity-specific properties (fully typed)
-order.properties.Status           // string
-order.properties.ActiveDate       // string
-order.properties.ContractType     // string
-// ... all properties are typed
-
-// Access raw OdinRecord if needed
-order.raw           // OdinRecord<OrderProperties>
-```
-
----
-
-## Executing Actions
-
-Actions are typed methods directly on the record wrapper:
-
-```typescript
-const order = await odin.orders.get(orderId);
-
-// Actions with required properties
-await order.activateOrder({
-  ActiveDate: '2025-01-15',
-});
-
-// Actions with optional properties
-await order.updateOrder({
-  Status: 'Active',
-  Notes: 'Updated via SDK',
-});
-
-// Actions with journey/stage options
-await order.activateOrder(
-  { ActiveDate: '2025-01-15' },
-  { journeyId: 'journey-uuid', stageKey: 'StageActive' }
-);
-```
-
-### Action Results
-
-All actions return `ActionResult[]`:
-
-```typescript
-const results = await order.activateOrder({ ActiveDate: '2025-01-15' });
-
-for (const result of results) {
-  console.log(result.id);       // Record ID
-  console.log(result.entity);   // Entity name
-  console.log(result.type);     // Action type
-}
-```
-
----
-
-## Searching Records
-
-ODIN uses a structured query format with `OdinQuery` and `OdinFilter` types.
-
-### Query Structure
-
-```typescript
-interface OdinFilter {
-  columnName: string;      // Property name (e.g., 'Status', 'Contractor')
-  operator: OdinOperator;  // 'eq', 'in', 'not in', 'gte', 'lte', 'gt', 'lt', etc.
-  value: any;              // Filter value(s)
-  // Optional:
-  linkedEntity?: string;           // For filtering on linked records
-  linkedRelationType?: string;     // 'child' | 'parent'
-  caseSensitive?: boolean;         // Default: false
-}
-
-interface OdinQuery {
-  entity: string;                  // Use 'infer' to auto-detect from accessor
-  type: 'and';                     // Currently only 'and' is supported
-  value: OdinFilter[];             // Array of filters (AND'd together)
-  pageSize: number;                // Max 1000 per request
-  pageNumber: number;              // 0-indexed
-  sort?: Record<string, { order: 'asc' | 'desc' }>;
-  returnProperties?: string[];     // Fields to return
-  searchAfter?: any[];             // For cursor-based pagination
-  includeDeleted?: boolean;
-  includeArchived?: boolean;
-}
-
-// Available operators
-type OdinOperator =
-  | 'eq'       // Equals
-  | 'in'       // In array
-  | 'not in'   // Not in array
-  | 'gte'      // Greater than or equal
-  | 'lte'      // Less than or equal
-  | 'gt'       // Greater than
-  | 'lt'       // Less than
-  | 'isNull'   // Is null
-  | 'notNull'  // Is not null
-  | 'anyTerm'  // Contains any term (text search)
-  | 'allTerm'  // Contains all terms (text search)
-  | 'phrase'   // Exact phrase match
-  | 'nested';  // Nested object query
-```
-
-### Basic Search
-
-```typescript
-const result = await odin.orders.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      {
-        columnName: 'Status',
-        operator: 'eq',
-        value: 'Active',
-      },
-    ],
-    returnProperties: ['id', 'title', 'type', 'properties.*'],
-    pageSize: 100,
-    pageNumber: 0,
-  },
-});
-
-console.log(result.records);      // OrderRecord[]
-console.log(result.totalRecords); // number
-console.log(result.hasMore);      // boolean
-```
-
-### Search with Multiple Filters
-
-Filters are AND'd together:
-
-```typescript
-const result = await odin.orders.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      {
-        columnName: 'Status',
-        operator: 'in',
-        value: ['Active', 'Pending'],
-      },
-      {
-        columnName: 'ContractType',
-        operator: 'eq',
-        value: 'Residential',
-      },
-      {
-        columnName: 'ActiveDate',
-        operator: 'gte',
-        value: '2025-01-01',
-      },
-    ],
-    returnProperties: ['id', 'title', 'type', 'properties.*', 'stage'],
-    sort: {
-      createdAt: { order: 'desc' },
-    },
-    pageSize: 100,
-    pageNumber: 0,
-  },
-});
-```
-
-### Excluding Values (NOT IN)
-
-```typescript
-const result = await odin.workOrders.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      {
-        columnName: 'EntityType',
-        operator: 'not in',
-        value: ['COLLECTION', 'DISPATCH'],
-      },
-      {
-        columnName: 'Contractor',
-        operator: 'not in',
-        value: ['INTERNAL'],
-      },
-    ],
-    pageSize: 1000,
-    pageNumber: 0,
-  },
-});
-```
-
-### Date Range Queries
-
-```typescript
-const result = await odin.visits.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      {
-        columnName: 'ScheduledDate',
-        operator: 'gte',
-        value: '2025-01-01',
-      },
-      {
-        columnName: 'ScheduledDate',
-        operator: 'lte',
-        value: '2025-01-31',
-      },
-    ],
-    sort: {
-      ScheduledDate: { order: 'asc' },
-    },
-    pageSize: 500,
-    pageNumber: 0,
-  },
-});
-```
-
-### Text Search
-
-```typescript
-// Match any term
-const result = await odin.contacts.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      {
-        columnName: 'FirstName',
-        operator: 'anyTerm',
-        value: 'john smith',  // Matches 'john' OR 'smith'
-      },
-    ],
-    pageSize: 50,
-    pageNumber: 0,
-  },
-});
-
-// Match exact phrase
-const result = await odin.contacts.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      {
-        columnName: 'FullName',
-        operator: 'phrase',
-        value: 'John Smith',  // Matches exact phrase
-      },
-    ],
-    pageSize: 50,
-    pageNumber: 0,
-  },
-});
+// Create a new record with links
+const note = odin.notes.new();
+await note
+  .link({ id: orderId, entity: "OrderModule:Order" })
+  .createNote({ Body: "Customer called about billing" });
 ```
 
-### Null Checks
+### DB Client (Backend Services)
 
 ```typescript
-const result = await odin.orders.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      {
-        columnName: 'CancelledDate',
-        operator: 'isNull',
-        value: true,
-      },
-      {
-        columnName: 'ActiveDate',
-        operator: 'notNull',
-        value: true,
-      },
-    ],
-    pageSize: 100,
-    pageNumber: 0,
-  },
-});
-```
+import { OdinDbClient } from '@d19n/youfibre-odin-sdk';
 
-### Selecting Return Properties
+// Initialize with principal and dbService (NestJS)
+const odin = new OdinDbClient(principal, this.dbService);
 
-Control which fields are returned to reduce payload size:
-
-```typescript
-const result = await odin.orders.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      { columnName: 'Status', operator: 'eq', value: 'Active' },
-    ],
-    returnProperties: [
-      'id',
-      'title',
-      'type',
-      'entity',
-      'recordNumber',
-      'properties.*',    // All properties
-      'stage',           // Pipeline stage
-      'links.*',         // All linked records
-    ],
-    pageSize: 100,
-    pageNumber: 0,
-  },
-});
+// Same API as ApiClient
+const workOrder = await odin.workOrders.get(workOrderId);
+await workOrder.completeWorkOrder({ ... });
 ```
 
-### Sorting Results
+## Architecture
 
-```typescript
-const result = await odin.orders.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      { columnName: 'Status', operator: 'eq', value: 'Active' },
-    ],
-    sort: {
-      createdAt: { order: 'desc' },      // Primary sort
-      'properties.Priority': { order: 'asc' },  // Secondary sort
-    },
-    pageSize: 100,
-    pageNumber: 0,
-  },
-});
 ```
+┌─────────────────────────────────────────────────────────────┐
+│                     ODIN SDK                                │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─────────────────┐         ┌─────────────────┐           │
+│  │  OdinApiClient  │         │  OdinDbClient   │           │
+│  │  (HTTP/OAuth)   │         │  (Direct DB)    │           │
+│  └────────┬────────┘         └────────┬────────┘           │
+│           │                           │                     │
+│           └───────────┬───────────────┘                     │
+│                       │                                     │
+│           ┌───────────▼───────────┐                         │
+│           │   Entity Accessors    │                         │
+│           │  (orders, contacts)   │                         │
+│           └───────────┬───────────┘                         │
+│                       │                                     │
+│           ┌───────────▼───────────┐                         │
+│           │   Record Wrappers     │                         │
+│           │  (OrderRecord, etc)   │                         │
+│           └───────────┬───────────┘                         │
+│                       │                                     │
+│           ┌───────────▼───────────┐                         │
+│           │   Action Methods      │                         │
+│           │  (activateOrder...)   │                         │
+│           └───────────────────────┘                         │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+| Component | Purpose |
+|-----------|---------|
+| **OdinApiClient** | HTTP-based client for frontend/external services |
+| **OdinDbClient** | Direct database client for backend services |
+| **Accessors** | Entity-specific access (`.orders`, `.contacts`) |
+| **Record Wrappers** | Typed records with action methods |
+| **Action DTOs** | Type-safe action parameters |
+| **Properties** | Typed entity properties interfaces |
+
+## Entities
+
+This SDK includes **0** entities across **0** modules.
+
+## Actions
+
+This SDK includes **0** actions.
+
+### Action Types
+
+| Type | Description |
+|------|-------------|
+| `CREATE` | Creates a new record (no existing record required) |
+| `UPDATE` | Updates an existing record |
+| `STEP_FLOW` | Multi-step workflow with FlowBuilder pattern |
+
+### Actions by Entity
+
+## Record Wrappers
+
+Record wrappers provide typed access to record data and action methods.
 
-### Search All (Auto-Pagination)
-
-Returns ALL matching records (up to ~1M) with automatic pagination:
+### Basic Usage
 
 ```typescript
-const allOrders = await odin.orders.searchAll({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      {
-        columnName: 'Status',
-        operator: 'in',
-        value: ['Active', 'Pending'],
-      },
-      {
-        columnName: 'UpdatedAt',
-        operator: 'gte',
-        value: '2025-01-01',
-      },
-    ],
-    returnProperties: [
-      'id',
-      'title',
-      'type',
-      'entity',
-      'schemaId',
-      'recordNumber',
-      'properties.*',
-      'stage',
-    ],
-    sort: {
-      createdAt: { order: 'asc' },  // Required for consistent pagination
-    },
-    pageSize: 1000,  // Max per request
-    pageNumber: 0,
-  },
-});
-
-console.log(allOrders.length); // Could be thousands
-```
-
-### Paginate (Generator)
-
-For memory-efficient processing of large datasets:
+// Get existing record
+const order = await odin.orders.get(orderId);
 
-```typescript
-for await (const batch of odin.orders.paginate({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      { columnName: 'Status', operator: 'eq', value: 'Active' },
-    ],
-    sort: {
-      createdAt: { order: 'asc' },
-    },
-    pageSize: 500,
-    pageNumber: 0,
-  },
-})) {
-  // Process batch of 500 records
-  for (const order of batch) {
-    await processOrder(order);
-  }
+// Access typed properties
+console.log(order.id);           // string
+console.log(order.properties);   // OrderProperties
+console.log(order.raw);          // Full OdinRecord
+
+// Check if record is new (unsaved)
+if (order.isNew) {
+  // Can only call CREATE actions
+  await order.createOrder({ ... });
+} else {
+  // Can call UPDATE actions
+  await order.updateOrder({ ... });
 }
 ```
 
-### Searching Linked Records
-
-Filter by properties on linked entities:
-
-```typescript
-// Find orders linked to a specific account
-const result = await odin.orders.search({
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      {
-        columnName: 'Status',
-        operator: 'eq',
-        value: 'Active',
-      },
-      {
-        columnName: 'AccountNumber',
-        operator: 'eq',
-        value: 'ACC-12345',
-        linkedEntity: 'CrmModule:Account',
-        linkedRelationType: 'parent',
-      },
-    ],
-    pageSize: 100,
-    pageNumber: 0,
-  },
-});
-```
-
----
-
-## Fluent Query Builder
-
-For a cleaner, more readable API, use the fluent query builder:
-
-### Basic Usage
+### Link Management
 
 ```typescript
-const results = await odin.orders
-  .query()
-  .where('Status', 'eq', 'Active')
-  .limit(100)
-  .execute();
+// Queue links to be sent with next action
+const note = odin.notes.new();
+await note
+  .link({ id: orderId, entity: "OrderModule:Order" })
+  .link({ id: contactId, entity: "CrmModule:Contact" })
+  .createNote({ Body: "Note content" });
 
-console.log(results.records);      // OrderRecord[]
-console.log(results.totalRecords); // number
-console.log(results.hasMore);      // boolean
+// Unlink (immediate API call)
+await order.unlink(contactId);
 ```
 
-### Chaining Filters
-
-All filters are AND'd together:
+### STEP_FLOW Actions (Multi-Step Workflows)
 
-```typescript
-const results = await odin.orders
-  .query()
-  .where('Status', 'in', ['Active', 'Pending'])
-  .where('ContractType', 'eq', 'Residential')
-  .where('ActiveDate', 'gte', '2025-01-01')
-  .whereNotIn('CancellationReason', ['Duplicate', 'Test'])
-  .select('id', 'title', 'properties.*', 'stage')
-  .sortBy('createdAt', 'desc')
-  .limit(100)
-  .execute();
-```
+STEP_FLOW actions allow executing multiple steps in a single transaction using a FlowBuilder pattern.
 
-### Available Filter Methods
+#### Basic Usage
 
 ```typescript
-// Equality
-.where('Status', 'eq', 'Active')
-.whereEq('Status', 'Active')           // Shorthand
-
-// In / Not In
-.where('Status', 'in', ['Active', 'Pending'])
-.whereIn('Status', ['Active', 'Pending'])  // Shorthand
-.whereNotIn('Status', ['Cancelled', 'Draft'])
-
-// Comparison
-.where('Amount', 'gte', 100)
-.whereGte('Amount', 100)               // Shorthand
-.whereLte('Amount', 1000)
-.whereGt('Amount', 0)
-.whereLt('Amount', 10000)
-
-// Date Range
-.whereBetween('CreatedAt', '2025-01-01', '2025-01-31')
-
-// Null Checks
-.whereNull('CancelledDate')
-.whereNotNull('ActiveDate')
-
-// Text Search
-.whereAnyTerm('Description', 'urgent priority')  // OR match
-.whereAllTerms('Description', 'urgent priority') // AND match
-.wherePhrase('Title', 'Service Order')           // Exact phrase
-
-// Linked Entity
-.whereLinked('AccountNumber', 'eq', 'ACC-123', 'CrmModule:Account', 'parent')
-```
-
-### Projection & Sorting
+// Get the record
+const cboRec = await odin.contractBuyOuts.get(cbo.id);
 
-```typescript
-const results = await odin.orders
-  .query()
-  .where('Status', 'eq', 'Active')
-  .select('id', 'title', 'type', 'properties.*', 'stage', 'links.*')
-  .sortBy('createdAt', 'desc')
-  .sortBy('properties.Priority', 'asc')  // Secondary sort
-  .execute();
+// Execute a multi-step flow
+await cboRec
+  .moveCboToApproved({ journeyId: order.id })  // Start flow (returns FlowBuilder)
+  .approveCbo(cbo.id, {                        // UPDATE step - id required first
+    Amount: cbo.properties.Amount,
+    FinalBillVerified: cbo.properties.FinalBillVerified,
+    PreviousProvider: cbo.properties.PreviousProvider,
+  })
+  .execute();                                  // Execute the flow
 ```
 
-### Pagination
+#### Step Method Signatures
 
-```typescript
-// Limit and page
-const page1 = await odin.orders.query()
-  .where('Status', 'eq', 'Active')
-  .limit(100)
-  .page(0)
-  .execute();
-
-const page2 = await odin.orders.query()
-  .where('Status', 'eq', 'Active')
-  .limit(100)
-  .page(1)
-  .execute();
-
-// Using offset
-const results = await odin.orders.query()
-  .limit(100)
-  .offset(200)  // Skip first 200, returns 200-299
-  .execute();
-```
-
-### Convenience Methods
+Step methods have different signatures based on their action type:
 
+**UPDATE steps** - Require record `id` as first parameter:
 ```typescript
-// Get just records (no metadata)
-const records = await odin.orders
-  .query()
-  .where('Status', 'eq', 'Active')
-  .getMany();
-
-// Get single record
-const order = await odin.orders
-  .query()
-  .where('OrderNumber', 'eq', 'ORD-12345')
-  .getOne();  // Returns OrderRecord | null
-
-// Get single record or throw
-const order = await odin.orders
-  .query()
-  .where('OrderNumber', 'eq', 'ORD-12345')
-  .getOneOrFail();  // Throws if not found
-
-// Count matching records
-const count = await odin.orders
-  .query()
-  .where('Status', 'eq', 'Active')
-  .count();
-
-// Check if any match
-const hasActive = await odin.orders
-  .query()
-  .where('Status', 'eq', 'Active')
-  .exists();
+// UPDATE step signature: (id, properties, options?)
+.approveCbo(id: string, properties: ApproveCboProperties, options?)
+.updateWorkOrder(id: string, properties: UpdateWorkOrderProperties, options?)
 ```
 
-### Fetch All with Auto-Pagination
-
+**CREATE steps** - No `id` parameter (creates new record):
 ```typescript
-// WARNING: Can return up to ~1M records
-const allOrders = await odin.orders
-  .query()
-  .where('Status', 'in', ['Active', 'Pending'])
-  .where('UpdatedAt', 'gte', '2025-01-01')
-  .select('id', 'title', 'properties.*')
-  .sortBy('createdAt', 'asc')  // Required for consistent pagination
-  .limit(1000)
-  .executeAll();
-
-console.log(allOrders.length);  // Could be thousands
+// CREATE step signature: (properties, options?)
+.createFollowUp(properties: CreateFollowUpProperties, options?)
+.createNote(properties: CreateNoteProperties, options?)
 ```
 
-### Memory-Efficient Pagination
-
-For processing large datasets without loading all into memory:
+#### Complex Multi-Step Example
 
 ```typescript
-for await (const batch of odin.orders
-  .query()
-  .where('Status', 'eq', 'Active')
-  .sortBy('createdAt', 'asc')
-  .limit(500)
-  .paginate()
-) {
-  // Process batch of 500 records
-  for (const order of batch) {
-    await processOrder(order);
-  }
-}
-```
-
-### Include Deleted/Archived
+// Get the work order record
+const workOrderRec = await odin.workOrders.get(workOrderId);
 
-```typescript
-const results = await odin.orders
-  .query()
-  .where('Status', 'eq', 'Cancelled')
-  .includeDeleted()
-  .includeArchived()
+// Flow with both UPDATE and CREATE steps
+await workOrderRec
+  .completeWorkOrderFlow({ journeyId: parentOrder.id })
+  .updateWorkOrder(workOrderRec.id, {         // UPDATE step - id required
+    Status: "COMPLETE",
+    CompletedAt: new Date().toISOString(),
+  })
+  .createFollowUp({                           // CREATE step - no id
+    Type: "QUALITY_CHECK",
+    Description: "Post-completion review",
+  })
+  .addGroup("QUALITY")                        // Optional: add groups
   .execute();
 ```
 
-### Clone & Reuse Queries
+#### With Associations
 
 ```typescript
-const baseQuery = odin.orders
-  .query()
-  .where('ContractType', 'eq', 'Residential')
-  .select('id', 'title', 'properties.*')
-  .sortBy('createdAt', 'desc');
-
-// Clone and add more filters
-const activeOrders = await baseQuery
-  .clone()
-  .where('Status', 'eq', 'Active')
-  .execute();
-
-const pendingOrders = await baseQuery
-  .clone()
-  .where('Status', 'eq', 'Pending')
-  .execute();
-```
-
-### Build Query Without Executing
+// Link records during flow execution
+const invoiceRec = await odin.invoices.get(invoiceId);
 
-```typescript
-// Get the raw OdinQuery object
-const query = odin.orders
-  .query()
-  .where('Status', 'eq', 'Active')
-  .limit(100)
-  .build();
-
-console.log(query);
-// {
-//   entity: 'infer',
-//   type: 'and',
-//   value: [{ columnName: 'Status', operator: 'eq', value: 'Active' }],
-//   pageSize: 100,
-//   pageNumber: 0
-// }
+await invoiceRec
+  .link({ id: contactId, entity: "CrmModule:Contact" })  // Queue link
+  .processInvoiceFlow({ journeyId: orderId })
+  .approveInvoice(invoiceRec.id, {
+    ApprovedBy: userId,
+    ApprovedAt: new Date().toISOString(),
+  })
+  .execute();  // Links are sent with the action
 ```
 
-### Debug with Query Plan
+## Events
 
-See the exact Elasticsearch query that will be executed (useful for debugging):
+Subscribe to RabbitMQ events using the exported routing keys:
 
 ```typescript
-const plan = await odin.orders
-  .query()
-  .where('Status', 'in', ['Active', 'Pending'])
-  .where('UpdatedAt', 'gte', '2025-01-01')
-  .select('id', 'title', 'properties.*')
-  .sortBy('createdAt', 'asc')
-  .limit(100)
-  .returnQueryPlan();
-
-console.log(plan);
-// Shows the Elasticsearch query structure
-```
-
-This is equivalent to:
+import { ROUTING_KEY_ORDER_CREATED, ROUTING_KEY_ORDER_UPDATED } from '@d19n/youfibre-odin-sdk/entities';
+import { ROUTING_KEY_ACTIVATE_ORDER } from '@d19n/youfibre-odin-sdk/actions';
 
-```typescript
-const res = await odin.orders.search({
-  returnQueryPlan: true,
-  query: {
-    entity: 'infer',
-    type: 'and',
-    value: [
-      { columnName: 'Status', operator: 'in', value: ['Active', 'Pending'] },
-      { columnName: 'UpdatedAt', operator: 'gte', value: '2025-01-01' },
-    ],
-    returnProperties: ['id', 'title', 'properties.*'],
-    sort: { createdAt: { order: 'asc' } },
-    pageSize: 100,
-    pageNumber: 0,
-  },
+// Entity events
+await channel.consume(ROUTING_KEY_ORDER_CREATED, (msg) => {
+  const event: OrderCreatedEvent = JSON.parse(msg.content.toString());
+  // Handle event
 });
-```
-
----
-
-## Linking Records
-
-### Queue Links (Sent with Next Action)
-
-```typescript
-const order = await odin.orders.get(orderId);
-const contact = await odin.contacts.get(contactId);
-const address = await odin.addresses.get(addressId);
-
-// Queue multiple links
-order
-  .link(contact)
-  .link(address);
-
-// Links are sent with the next action
-await order.updateOrder({ Notes: 'Linked contact and address' });
-
-// Check pending links
-console.log(order.pendingLinks); // OdinRecordLinkDto[]
-
-// Clear without executing
-order.clearPendingLinks();
-```
-
-### Immediate Unlink
 
-```typescript
-// Unlink executes immediately (not queued)
-await order.unlink(contact);
-await order.unlink(contactId); // Can pass ID string directly
+// Action events
+await channel.consume(ROUTING_KEY_ACTIVATE_ORDER, (msg) => {
+  const event: ActivateOrderMessage = JSON.parse(msg.content.toString());
+  // Handle action completion
+});
 ```
 
----
-
 ## Migration Guide
 
-### From Legacy API SDK (v1)
-
-#### Before (Legacy)
+### From Legacy Entity APIs
 
 ```typescript
-import { OrderApi } from '@youfibre/odin-sdk/api-sdk-v2';
-
-const api = new OrderApi({
-  host: 'api.youfibre.com',
-  clientId,
-  clientSecret,
-});
-
-// Get record
-const order = await api.getByPrimaryKey(orderId);
-
-// Execute action
-await api.applyAction({
-  id: order.id,
-  entity: order.entity,
-  type: order.type,
-  actionKey: 'ActivateOrder',
-  properties: { ActiveDate: '2025-01-15' },
-});
-```
-
-#### After (New SDK)
-
-```typescript
-import { OdinApiClient } from '@youfibre/odin-sdk';
-
-const odin = new OdinApiClient({
-  host: 'api.youfibre.com',
-  clientId,
-  clientSecret,
-});
+// ❌ Old (deprecated)
+const orderApi = new OrderApi(authParams);
+const order = await orderApi.get(orderId);
+await orderApi.applyAction(new ActivateOrderDto(order, { ... }));
 
-// Get record
+// ✅ New (recommended)
 const order = await odin.orders.get(orderId);
-
-// Execute action (typed!)
-await order.activateOrder({ ActiveDate: '2025-01-15' });
+await order.activateOrder({ ... });
 ```
 
-### From Legacy DB SDK (v1)
-
-#### Before (Legacy)
+### STEP_FLOW Actions
 
 ```typescript
-import { OrderDb } from '@youfibre/odin-sdk/db-sdk-v2';
-
-const db = new OrderDb(principal, dbService);
-
-// Get record
-const order = await db.getByPrimaryKey(orderId);
-
-// Execute action
-await db.applyAction({
-  id: order.id,
-  entity: order.entity,
-  type: order.type,
-  actionKey: 'ActivateOrder',
-  properties: { ActiveDate: '2025-01-15' },
+// ❌ Old (manual DTO construction)
+const dto = new MoveCboToApprovedDto(record, {
+  journeyId: order.id,
+  steps: [
+    { actionName: "ApproveCBO", id: cbo.id, properties: { Amount: "100" } }
+  ]
 });
-```
-
-#### After (New SDK)
-
-```typescript
-import { OdinDbClient } from '@youfibre/odin-sdk';
-
-const odin = new OdinDbClient(principal, dbService);
-
-// Get record
-const order = await odin.orders.get(orderId);
-
-// Execute action (typed!)
-await order.activateOrder({ ActiveDate: '2025-01-15' });
-```
-
-### Key Differences
-
-| Feature | Legacy SDK | New SDK |
-|---------|-----------|---------|
-| Action execution | `api.applyAction({ actionKey, properties })` | `record.activateOrder(properties)` |
-| Type safety | Partial | Full |
-| Record properties | `record.properties.Status` (any) | `record.properties.Status` (typed) |
-| Action properties | Manual interface lookup | Auto-complete in IDE |
-| Linking | Separate API calls | `record.link(target)` fluent API |
-| Multi-entity client | Import each class separately | Single `OdinApiClient` / `OdinDbClient` |
-
-### Migration Steps
-
-1. **Update imports:**
-   ```typescript
-   // Before
-   import { OrderApi, ContactApi } from '@youfibre/odin-sdk/api-sdk-v2';
-   
-   // After
-   import { OdinApiClient } from '@youfibre/odin-sdk';
-   ```
-
-2. **Replace class instantiation:**
-   ```typescript
-   // Before
-   const orderApi = new OrderApi(authParams);
-   const contactApi = new ContactApi(authParams);
-   
-   // After
-   const odin = new OdinApiClient(authParams);
-   // Access via odin.orders, odin.contacts
-   ```
-
-3. **Update get calls:**
-   ```typescript
-   // Before
-   const order = await orderApi.getByPrimaryKey(id);
-   
-   // After
-   const order = await odin.orders.get(id);
-   ```
-
-4. **Update action calls:**
-   ```typescript
-   // Before
-   await orderApi.applyAction({
-     id: order.id,
-     entity: order.entity,
-     type: order.type,
-     actionKey: 'ActivateOrder',
-     properties: { ActiveDate: date },
-   });
-   
-   // After
-   await order.activateOrder({ ActiveDate: date });
-   ```
-
-5. **Update search calls:**
-   ```typescript
-   // Before
-   const result = await orderApi.searchRecords({ query: { ... } });
-   
-   // After
-   const result = await odin.orders.search({ query: { ... } });
-   ```
-
----
-
-## Architecture
-
-```
-@youfibre/odin-sdk/
-├── OdinApiClient.ts      # Unified API client
-├── OdinDbClient.ts       # Unified DB client
-├── EntityRegistry.ts     # Dynamic entity access
-├── index.ts              # Barrel exports
-│
-├── accessors-v2/         # API entity accessors
-│   ├── OrderAccessor.ts
-│   ├── ContactAccessor.ts
-│   └── ...
-│
-├── db-accessors-v2/      # DB entity accessors
-│   ├── OrderDbAccessor.ts
-│   ├── ContactDbAccessor.ts
-│   └── ...
-│
-├── records-v2/           # Typed record wrappers
-│   ├── OrderRecord.ts
-│   ├── ContactRecord.ts
-│   └── ...
-│
-├── entities-v2/          # Property interfaces
-│   ├── Order.ts          # OrderProperties
-│   ├── Contact.ts        # ContactProperties
-│   └── ...
-│
-├── actions-v2/           # Action DTOs
-│   ├── ActivateOrderDto.ts
-│   ├── UpdateContactDto.ts
-│   └── ...
-│
-└── [deprecated]
-    ├── api-sdk-v2/       # Legacy API classes
-    └── db-sdk-v2/        # Legacy DB classes
-```
-
-### Dependency Flow
-
-```
-OdinApiClient / OdinDbClient
-        │
-        ▼
-   *Accessor classes (accessors-v2/, db-accessors-v2/)
-        │
-        ▼
-   *Record wrappers (records-v2/)
-        │
-        ├──▶ *Properties interfaces (entities-v2/)
-        │
-        └──▶ Action methods → *Action DTOs (actions-v2/)
-```
-
----
-
-## Advanced Usage
-
-### Dynamic Entity Access
-
-```typescript
-import { EntityRegistry, getAccessor } from '@youfibre/odin-sdk';
-
-// Get accessor dynamically by entity name
-const accessor = getAccessor('Order', provider);
-const order = await accessor.get(orderId);
-
-// List available entities
-const entities = Object.keys(EntityRegistry);
-```
+await api.applyAction(dto);
 
-### Direct Provider Access
-
-```typescript
-const odin = new OdinApiClient(config);
-
-// Access underlying provider for advanced operations
-const provider = odin.provider;
-
-// Manual authentication (usually not needed)
-await odin.authenticate();
-
-// Get current user
-const principal = await odin.getPrincipal();
-```
-
-### Type Imports
-
-```typescript
-// Import property types directly
-import { OrderProperties } from '@youfibre/odin-sdk/entities-v2/Order';
-import { ContactProperties } from '@youfibre/odin-sdk/entities-v2/Contact';
-
-// Import action property types
-import { ActivateOrderProperties } from '@youfibre/odin-sdk/actions-v2/ActivateOrderDto';
-
-// Import record types
-import { OrderRecord } from '@youfibre/odin-sdk/records-v2/OrderRecord';
-```
-
----
-
-## Troubleshooting
-
-### "Cannot find module" Errors
-
-Ensure you're importing from the correct paths:
-
-```typescript
-// ✅ Correct
-import { OdinApiClient } from '@youfibre/odin-sdk';
-
-// ❌ Wrong
-import { OdinApiClient } from '@youfibre/odin-sdk/dist/src/OdinApiClient';
-```
-
-### Type Errors on Properties
-
-If TypeScript doesn't recognize properties, ensure your SDK is up to date:
-
-```bash
-npm update @youfibre/odin-sdk
+// ✅ New (fluent FlowBuilder)
+const cboRec = await odin.contractBuyOuts.get(cbo.id);
+await cboRec
+  .moveCboToApproved({ journeyId: order.id })
+  .approveCbo(cbo.id, { Amount: "100" })
+  .execute();
 ```
 
-### Action Not Found
+### Key Changes
 
-If an action method doesn't exist on a record, it means the action isn't registered for that entity in the schema. Check the ODIN admin console.
+| Old Pattern | New Pattern |
+|-------------|-------------|
+| `new OrderApi(auth).get(id)` | `odin.orders.get(id)` |
+| `api.applyAction(dto)` | `record.actionName(props)` |
+| `new ActionDto(record, props)` | `record.actionName(props)` |
+| `api.address.list(recordId)` | `record.addresses.list()` |
+| Manual pagination | `odin.orders.paginate(query)` |
+| Manual step flow DTOs | `record.flowAction().step().execute()` |
 
 ---
 
-## Contributing
-
-To regenerate the SDK after schema changes:
-
-```bash
-cd packages/youfibre-odin-sdk
-npx ts-node src/runner.ts
-npm run build
-```
-
----
-
-## License
-
-Proprietary - YouFibre Ltd.
+*This documentation was auto-generated from ODIN schema definitions.*