@d19n/youfibre-odin-sdk 1.0.201-beta.6 → 1.0.202

package/README.md

@@ -1,209 +1,624 @@
-# ODIN SDK for [Organization]
+# YouFibre ODIN SDK
 
-Type-safe SDK for interacting with your ODIN platform. Auto-generated from your schema with full TypeScript support.
+Typed SDK for the ODIN platform providing full type safety for records, actions, and properties.
+
+## 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)
+
+---
 
 ## Installation
 
 ```bash
-npm install @your-org/odin-sdk
+npm install @d19n/youfibre-odin-sdk
 ```
 
+---
+
 ## Quick Start
 
+### API Access (Scripts, External Clients)
+
 ```typescript
-import { OdinApiClient } from '@your-org/odin-sdk';
+import { OdinApiClient } from '@d19n/youfibre-odin-sdk';
 
-const odin = new OdinApiClient();
+const odin = new OdinApiClient({
+  host: 'api.youfibre.com',
+  clientId: process.env.ODIN_CLIENT_ID!,
+  clientSecret: process.env.ODIN_CLIENT_SECRET!,
+});
 
-// Get a record (returns wrapped record with action methods)
+// Get an order and execute an action
 const order = await odin.orders.get('ORD-123');
+console.log(order.properties.Status);
 
-// Execute a typed action directly on the record
-await order.activateOrder({
-  ActiveDate: '2025-01-15',
-  BillingStartDate: '2025-02-01',
-}, { journeyId: accountId });
+await order.activateOrder({ ActiveDate: '2025-01-15' });
 ```
 
-## Authentication
+### DB Access (Backend Services)
 
 ```typescript
-// Environment variables (recommended)
-// Set ODIN_API_URL and ODIN_API_TOKEN
-const odin = new OdinApiClient();
+import { OdinDbClient } from '@d19n/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() });
+  }
+}
+```
+
+---
 
-// Explicit token
-const odin = new OdinApiClient(undefined, 'your-api-token');
+## API Client (External Access)
 
-// OAuth
+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);
 ```
 
-## Actions
+### Available Accessors
 
-Actions are executed directly on record objects with full type safety.
+All entity accessors are lazy-loaded on first access:
 
-### Typed Action Methods
+```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 order = await odin.orders.get('ORD-123');
+const odin = new OdinDbClient(principal, dbService);
+```
 
-// Actions with required properties
-await order.activateOrder({
-  ActiveDate: '2025-01-15',      // ✓ Required - TypeScript enforces
-  BillingStartDate: '2025-02-01', // ✓ Required
-  DesiredBillingDay: 15,          // ✓ Optional
-}, { journeyId: accountId });
+- `principal`: The authenticated user context
+- `dbService`: The database service instance (typically injected)
 
-// Actions without required properties
-await order.deactivateOrderDunning({ journeyId: accountId });
+### Example: NestJS Service
 
-// Actions with optional properties
-await order.clearDeactivateOnDate({ DeactivateOnDate: null }, { journeyId: accountId });
+```typescript
+import { Injectable } from '@nestjs/common';
+import { OdinDbClient } from '@d19n/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',
+    });
+  }
+}
 ```
 
-### Link Accumulation
+---
+
+## Working with Records
 
-Links are accumulated and sent with the next action:
+### Getting Records
 
 ```typescript
-const order = await odin.orders.get('ORD-123');
-const address = await odin.addresses.get('ADDR-1');
-const contact = await odin.contacts.get('CONTACT-1');
+// 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']);
+```
 
-// Accumulate links (chainable)
-order.link(address).link(contact);
+### Record Properties
 
-// Execute action - links are sent with the action DTO
-await order.activateOrder({ ActiveDate: '2025-01-15' }, { journeyId: accountId });
-// Links are automatically cleared after action executes
+Records are wrapped with typed access to all properties:
+
+```typescript
+const order = await odin.orders.get(orderId);
+
+// 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>
 ```
 
-### Unlinking Records
+---
+
+## Executing Actions
 
-Unlink is an immediate API call:
+Actions are typed methods directly on the record wrapper:
 
 ```typescript
-// Unlink by record
-await order.unlink(oldAddress);
+const order = await odin.orders.get(orderId);
 
-// Unlink by ID
-await order.unlink('ADDR-123');
+// 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' }
+);
 ```
 
-### Bulk Actions
+### Action Results
 
-For bulk operations across multiple records:
+All actions return `ActionResult[]`:
 
 ```typescript
-await odin.actions.applyToMany(
-  'OrderModule:Order',
-  ['ORD-123', 'ORD-456', 'ORD-789'],
-  'BulkApprove',
-  { ApprovedBy: 'admin@company.com' }
-);
+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
+}
 ```
 
-## Reading Records
+---
+
+## Searching Records
 
-### Get Records
+### Basic Search
 
 ```typescript
-// Single record (returns wrapped record)
-const order = await odin.orders.get('ORD-123');
+const result = await odin.orders.search({
+  query: {
+    terms: 'ACTIVE',
+    pageSize: 50,
+  },
+});
 
-// Access properties
-console.log(order.id);
-console.log(order.properties.Status);
-console.log(order.properties.TotalAmount);
+console.log(result.records);      // OrderRecord[]
+console.log(result.totalRecords); // number
+console.log(result.hasMore);      // boolean
+```
 
-// Multiple records
-const orders = await odin.orders.getMany(['ORD-123', 'ORD-456']);
+### Search with Filters
+
+```typescript
+const result = await odin.orders.search({
+  query: {
+    must: [
+      { field: 'properties.Status', value: 'Active' },
+      { field: 'properties.ContractType', value: 'Residential' },
+    ],
+    sort: [{ field: 'createdAt', order: 'desc' }],
+    pageSize: 100,
+  },
+});
 ```
 
-### Listing Records
+### Search All (Auto-Pagination)
 
 ```typescript
-// Simple filtering
-const results = await odin.orders.list({
-  where: {
-    Status: 'Active',
-    TotalAmount: { gte: 1000 },
+// Returns ALL matching records (handles pagination internally)
+const allOrders = await odin.orders.searchAll({
+  query: {
+    must: [{ field: 'properties.Status', value: 'Active' }],
   },
-  limit: 100,
-  sort: [{ TotalAmount: 'desc' }],
 });
 
-// Returns wrapped records
-for (const order of results.data) {
-  await order.sendNotification({ ... });
-}
+console.log(allOrders.length); // Could be thousands
 ```
 
-### Auto-Pagination
+### Paginate (Generator)
+
+For memory-efficient processing of large datasets:
 
 ```typescript
-for await (const batch of odin.orders.listAll({ where: { Status: 'Active' } })) {
+for await (const batch of odin.orders.paginate({
+  query: {
+    must: [{ field: 'properties.Status', value: 'Active' }],
+    pageSize: 500,
+  },
+})) {
+  // Process batch of 500 records
   for (const order of batch) {
-    await order.processOrder({ ... });
+    await processOrder(order);
   }
 }
 ```
 
-### Full Search
+---
+
+## Linking Records
+
+### Queue Links (Sent with Next Action)
 
 ```typescript
-const results = await odin.orders.search({
-  query: {
-    entity: 'OrderModule:Order',
-    type: 'and',
-    value: [
-      { columnName: 'Status', operator: 'eq', value: 'Active' },
-      { columnName: 'TotalAmount', operator: 'gte', value: 1000 },
-    ],
-    pageSize: 100,
-  },
+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
+```
+
+---
+
+## Migration Guide
+
+### From Legacy API SDK (v1)
+
+#### Before (Legacy)
+
+```typescript
+import { OrderApi } from '@d19n/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 '@d19n/youfibre-odin-sdk';
+
+const odin = new OdinApiClient({
+  host: 'api.youfibre.com',
+  clientId,
+  clientSecret,
 });
+
+// Get record
+const order = await odin.orders.get(orderId);
+
+// Execute action (typed!)
+await order.activateOrder({ ActiveDate: '2025-01-15' });
 ```
 
-## TypeScript Support
+### From Legacy DB SDK (v1)
 
-All entities, actions, and properties are fully typed:
+#### Before (Legacy)
 
 ```typescript
-import { OrderRecord, ActivateOrderProperties } from '@your-org/odin-sdk';
+import { OrderDb } from '@d19n/youfibre-odin-sdk/db-sdk-v2';
 
-const order = await odin.orders.get('ORD-123');
+const db = new OrderDb(principal, dbService);
 
-// IDE autocomplete for record properties
-console.log(order.properties.Status);      // ✓ Autocomplete
-console.log(order.properties.TotalAmount); // ✓ Autocomplete
+// Get record
+const order = await db.getByPrimaryKey(orderId);
 
-// Type-safe action parameters
-await order.activateOrder({
-  ActiveDate: '2025-01-15',
-  BillingStartDate: '2025-02-01',
+// Execute action
+await db.applyAction({
+  id: order.id,
+  entity: order.entity,
+  type: order.type,
+  actionKey: 'ActivateOrder',
+  properties: { ActiveDate: '2025-01-15' },
 });
 ```
 
-## Environment Variables
+#### After (New SDK)
+
+```typescript
+import { OdinDbClient } from '@d19n/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 '@d19n/youfibre-odin-sdk/api-sdk-v2';
+   
+   // After
+   import { OdinApiClient } from '@d19n/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: { ... } });
+   ```
 
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `ODIN_API_URL` | ODIN API base URL | Yes |
-| `ODIN_API_TOKEN` | API authentication token | Yes* |
-| `ODIN_CLIENT_ID` | OAuth client ID | For OAuth |
-| `ODIN_CLIENT_SECRET` | OAuth client secret | For OAuth |
+---
+
+## Architecture
 
-## Regenerating the SDK
+```
+@d19n/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 '@d19n/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);
+```
+
+### 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 '@d19n/youfibre-odin-sdk/entities-v2/Order';
+import { ContactProperties } from '@d19n/youfibre-odin-sdk/entities-v2/Contact';
+
+// Import action property types
+import { ActivateOrderProperties } from '@d19n/youfibre-odin-sdk/actions-v2/ActivateOrderDto';
+
+// Import record types
+import { OrderRecord } from '@d19n/youfibre-odin-sdk/records-v2/OrderRecord';
+```
+
+---
+
+## Troubleshooting
+
+### "Cannot find module" Errors
+
+Ensure you're importing from the correct paths:
+
+```typescript
+// ✅ Correct
+import { OdinApiClient } from '@d19n/youfibre-odin-sdk';
+
+// ❌ Wrong
+import { OdinApiClient } from '@d19n/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 run generate
+npm update @d19n/youfibre-odin-sdk
+```
+
+### Action Not Found
+
+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.
+
+---
+
+## Contributing
+
+To regenerate the SDK after schema changes:
+
+```bash
+cd packages/youfibre-odin-sdk
+npx ts-node src/runner.ts
+npm run build
 ```
 
 ---
 
-*Auto-generated by [odin-sdk-generator](https://github.com/d19n-llc/odin-sdk-generator)*
+## License
+
+Proprietary - YouFibre Ltd.