@d19n/youfibre-odin-sdk 1.0.202 → 1.0.203

package/README.md

@@ -20,7 +20,7 @@ Typed SDK for the ODIN platform providing full type safety for records, actions,
 ## Installation
 
 ```bash
-npm install @d19n/youfibre-odin-sdk
+npm install @youfibre/odin-sdk
 ```
 
 ---
@@ -30,7 +30,7 @@ npm install @d19n/youfibre-odin-sdk
 ### API Access (Scripts, External Clients)
 
 ```typescript
-import { OdinApiClient } from '@d19n/youfibre-odin-sdk';
+import { OdinApiClient } from '@youfibre/odin-sdk';
 
 const odin = new OdinApiClient({
   host: 'api.youfibre.com',
@@ -48,7 +48,7 @@ await order.activateOrder({ ActiveDate: '2025-01-15' });
 ### DB Access (Backend Services)
 
 ```typescript
-import { OdinDbClient } from '@d19n/youfibre-odin-sdk';
+import { OdinDbClient } from '@youfibre/odin-sdk';
 
 // In a NestJS service
 @Injectable()
@@ -123,7 +123,7 @@ const odin = new OdinDbClient(principal, dbService);
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { OdinDbClient } from '@d19n/youfibre-odin-sdk';
+import { OdinDbClient } from '@youfibre/odin-sdk';
 import { DbService } from '@d19n/schema-manager/dist/db/db.service';
 
 @Injectable()
@@ -229,13 +229,68 @@ for (const result of results) {
 
 ## 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: {
-    terms: 'ACTIVE',
-    pageSize: 50,
+    entity: 'infer',
+    type: 'and',
+    value: [
+      {
+        columnName: 'Status',
+        operator: 'eq',
+        value: 'Active',
+      },
+    ],
+    returnProperties: ['id', 'title', 'type', 'properties.*'],
+    pageSize: 100,
+    pageNumber: 0,
   },
 });
 
@@ -244,28 +299,242 @@ console.log(result.totalRecords); // number
 console.log(result.hasMore);      // boolean
 ```
 
-### Search with Filters
+### Search with Multiple Filters
+
+Filters are AND'd together:
 
 ```typescript
 const result = await odin.orders.search({
   query: {
-    must: [
-      { field: 'properties.Status', value: 'Active' },
-      { field: 'properties.ContractType', value: 'Residential' },
+    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',
+      },
     ],
-    sort: [{ field: 'createdAt', order: 'desc' }],
+    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,
+  },
+});
+```
+
+### Null Checks
+
+```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,
+  },
+});
+```
+
+### Selecting Return Properties
+
+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,
+  },
+});
+```
+
+### Sorting Results
+
+```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,
   },
 });
 ```
 
 ### Search All (Auto-Pagination)
 
+Returns ALL matching records (up to ~1M) with automatic pagination:
+
 ```typescript
-// Returns ALL matching records (handles pagination internally)
 const allOrders = await odin.orders.searchAll({
   query: {
-    must: [{ field: 'properties.Status', value: 'Active' }],
+    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,
   },
 });
 
@@ -279,8 +548,16 @@ For memory-efficient processing of large datasets:
 ```typescript
 for await (const batch of odin.orders.paginate({
   query: {
-    must: [{ field: 'properties.Status', value: 'Active' }],
+    entity: 'infer',
+    type: 'and',
+    value: [
+      { columnName: 'Status', operator: 'eq', value: 'Active' },
+    ],
+    sort: {
+      createdAt: { order: 'asc' },
+    },
     pageSize: 500,
+    pageNumber: 0,
   },
 })) {
   // Process batch of 500 records
@@ -290,6 +567,302 @@ for await (const batch of odin.orders.paginate({
 }
 ```
 
+### 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
+
+```typescript
+const results = await odin.orders
+  .query()
+  .where('Status', 'eq', 'Active')
+  .limit(100)
+  .execute();
+
+console.log(results.records);      // OrderRecord[]
+console.log(results.totalRecords); // number
+console.log(results.hasMore);      // boolean
+```
+
+### Chaining Filters
+
+All filters are AND'd together:
+
+```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();
+```
+
+### Available Filter Methods
+
+```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
+
+```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();
+```
+
+### Pagination
+
+```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
+
+```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();
+```
+
+### Fetch All with Auto-Pagination
+
+```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
+```
+
+### Memory-Efficient Pagination
+
+For processing large datasets without loading all into memory:
+
+```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
+
+```typescript
+const results = await odin.orders
+  .query()
+  .where('Status', 'eq', 'Cancelled')
+  .includeDeleted()
+  .includeArchived()
+  .execute();
+```
+
+### Clone & Reuse Queries
+
+```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
+
+```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
+// }
+```
+
+### Debug with Query Plan
+
+See the exact Elasticsearch query that will be executed (useful for debugging):
+
+```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:
+
+```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,
+  },
+});
+```
+
 ---
 
 ## Linking Records
@@ -333,7 +906,7 @@ await order.unlink(contactId); // Can pass ID string directly
 #### Before (Legacy)
 
 ```typescript
-import { OrderApi } from '@d19n/youfibre-odin-sdk/api-sdk-v2';
+import { OrderApi } from '@youfibre/odin-sdk/api-sdk-v2';
 
 const api = new OrderApi({
   host: 'api.youfibre.com',
@@ -357,7 +930,7 @@ await api.applyAction({
 #### After (New SDK)
 
 ```typescript
-import { OdinApiClient } from '@d19n/youfibre-odin-sdk';
+import { OdinApiClient } from '@youfibre/odin-sdk';
 
 const odin = new OdinApiClient({
   host: 'api.youfibre.com',
@@ -377,7 +950,7 @@ await order.activateOrder({ ActiveDate: '2025-01-15' });
 #### Before (Legacy)
 
 ```typescript
-import { OrderDb } from '@d19n/youfibre-odin-sdk/db-sdk-v2';
+import { OrderDb } from '@youfibre/odin-sdk/db-sdk-v2';
 
 const db = new OrderDb(principal, dbService);
 
@@ -397,7 +970,7 @@ await db.applyAction({
 #### After (New SDK)
 
 ```typescript
-import { OdinDbClient } from '@d19n/youfibre-odin-sdk';
+import { OdinDbClient } from '@youfibre/odin-sdk';
 
 const odin = new OdinDbClient(principal, dbService);
 
@@ -424,10 +997,10 @@ await order.activateOrder({ ActiveDate: '2025-01-15' });
 1. **Update imports:**
    ```typescript
    // Before
-   import { OrderApi, ContactApi } from '@d19n/youfibre-odin-sdk/api-sdk-v2';
+   import { OrderApi, ContactApi } from '@youfibre/odin-sdk/api-sdk-v2';
    
    // After
-   import { OdinApiClient } from '@d19n/youfibre-odin-sdk';
+   import { OdinApiClient } from '@youfibre/odin-sdk';
    ```
 
 2. **Replace class instantiation:**
@@ -479,7 +1052,7 @@ await order.activateOrder({ ActiveDate: '2025-01-15' });
 ## Architecture
 
 ```
-@d19n/youfibre-odin-sdk/
+@youfibre/odin-sdk/
 ├── OdinApiClient.ts      # Unified API client
 ├── OdinDbClient.ts       # Unified DB client
 ├── EntityRegistry.ts     # Dynamic entity access
@@ -538,7 +1111,7 @@ OdinApiClient / OdinDbClient
 ### Dynamic Entity Access
 
 ```typescript
-import { EntityRegistry, getAccessor } from '@d19n/youfibre-odin-sdk';
+import { EntityRegistry, getAccessor } from '@youfibre/odin-sdk';
 
 // Get accessor dynamically by entity name
 const accessor = getAccessor('Order', provider);
@@ -567,14 +1140,14 @@ const principal = await odin.getPrincipal();
 
 ```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 { OrderProperties } from '@youfibre/odin-sdk/entities-v2/Order';
+import { ContactProperties } from '@youfibre/odin-sdk/entities-v2/Contact';
 
 // Import action property types
-import { ActivateOrderProperties } from '@d19n/youfibre-odin-sdk/actions-v2/ActivateOrderDto';
+import { ActivateOrderProperties } from '@youfibre/odin-sdk/actions-v2/ActivateOrderDto';
 
 // Import record types
-import { OrderRecord } from '@d19n/youfibre-odin-sdk/records-v2/OrderRecord';
+import { OrderRecord } from '@youfibre/odin-sdk/records-v2/OrderRecord';
 ```
 
 ---
@@ -587,10 +1160,10 @@ Ensure you're importing from the correct paths:
 
 ```typescript
 // ✅ Correct
-import { OdinApiClient } from '@d19n/youfibre-odin-sdk';
+import { OdinApiClient } from '@youfibre/odin-sdk';
 
 // ❌ Wrong
-import { OdinApiClient } from '@d19n/youfibre-odin-sdk/dist/src/OdinApiClient';
+import { OdinApiClient } from '@youfibre/odin-sdk/dist/src/OdinApiClient';
 ```
 
 ### Type Errors on Properties
@@ -598,7 +1171,7 @@ import { OdinApiClient } from '@d19n/youfibre-odin-sdk/dist/src/OdinApiClient';
 If TypeScript doesn't recognize properties, ensure your SDK is up to date:
 
 ```bash
-npm update @d19n/youfibre-odin-sdk
+npm update @youfibre/odin-sdk
 ```
 
 ### Action Not Found