@d19n/youfibre-odin-sdk 1.0.292 → 1.0.294

package/README.md

@@ -52,11 +52,18 @@ await cboRec
   })
   .execute();
 
-// Create a new record with links
+// Create a new record with generic links
 const note = odin.notes.new();
 await note
   .link({ id: orderId, entity: "OrderModule:Order" })
   .createNote({ Body: "Customer called about billing" });
+
+// Create a record with typed associations (builder pattern)
+await odin.referrals.new()
+  .createOrderReferral({})
+  .linkCampaignReferrals(campaign)       // Typed association method
+  .linkOrderReferral({ id: orderId, entity: "OrderModule:Order" })
+  .execute();
 ```
 
 ### DB Client (Backend Services)
@@ -146,7 +153,7 @@ const order = await odin.orders.get(orderId);
 // Access typed properties
 console.log(order.id);           // string
 console.log(order.properties);   // OrderProperties
-console.log(order.raw);          // Full OdinRecord
+console.log(order.record);       // Full OdinRecord
 
 // Check if record is new (unsaved)
 if (order.isNew) {
@@ -160,6 +167,8 @@ if (order.isNew) {
 
 ### Link Management
 
+#### Generic Links (.link())
+
 ```typescript
 // Queue links to be sent with next action
 const note = odin.notes.new();
@@ -172,6 +181,19 @@ await note
 await order.unlink(contactId);
 ```
 
+#### Named Associations (Builder Pattern)
+
+Actions with association fields generate typed `.link*()` methods:
+
+```typescript
+// IDE autocomplete shows available association methods
+await odin.referrals.new()
+  .createOrderReferral({})
+  .linkCampaignReferrals({ id: campaignId, entity: "CrmModule:Campaign" })
+  .linkOrderReferral(order)  // Pass OdinRecord directly
+  .execute();
+```
+
 ### STEP_FLOW Actions (Multi-Step Workflows)
 
 STEP_FLOW actions allow executing multiple steps in a single transaction using a FlowBuilder pattern.
@@ -232,14 +254,14 @@ await workOrderRec
   .execute();
 ```
 
-#### With Associations
+#### With Associations (Generic .link())
 
 ```typescript
-// Link records during flow execution
+// Queue generic links to be sent with next action
 const invoiceRec = await odin.invoices.get(invoiceId);
 
 await invoiceRec
-  .link({ id: contactId, entity: "CrmModule:Contact" })  // Queue link
+  .link({ id: contactId, entity: "CrmModule:Contact" })  // Generic link
   .processInvoiceFlow({ journeyId: orderId })
   .approveInvoice(invoiceRec.id, {
     ApprovedBy: userId,
@@ -248,25 +270,94 @@ await invoiceRec
   .execute();  // Links are sent with the action
 ```
 
+#### With Named Associations (Builder Pattern)
+
+Actions with association fields generate typed `.link*()` methods:
+
+```typescript
+// Typed association methods - IDE autocomplete shows available links
+await odin.referrals.new()
+  .createOrderReferral({})
+  .linkCampaignReferrals({ id: campaignId, entity: "CrmModule:Campaign" })
+  .linkOrderReferral(order)  // Can pass OdinRecord directly
+  .execute();
+
+// Mix generic .link() with named associations
+await odin.referrals.new()
+  .link({ id: accountId, entity: "CrmModule:Account" })  // Generic link
+  .createOrderReferral({})
+  .linkCampaignReferrals(campaign)  // Named association
+  .execute();
+
+// Inspect payload before executing
+const builder = odin.referrals.new()
+  .createOrderReferral({})
+  .linkCampaignReferrals({ id: campaignId, entity: "CrmModule:Campaign" });
+
+console.log(builder.getData());  // View what will be sent
+await builder.execute();         // Then execute
+```
+
 ## Events
 
-Subscribe to RabbitMQ events using the exported routing keys:
+Subscribe to RabbitMQ events using `@RabbitSubscribe` with SDK routing keys:
 
 ```typescript
-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';
+import { 
+  WORK_ORDER,
+  SUB_DB_RECORD_UPDATED,
+  SUB_DB_RECORD_CREATED,
+} from '@d19n/youfibre-odin-sdk/entities';
+import { IDbRecordUpdated, IDbRecordCreated } from '@d19n/odin-types/dist/core';
+import { LogsConstants } from '@d19n/logs/dist/constants';
+
+// Subscribe to record updated events
+@RabbitSubscribe({
+  exchange: process.env.ODIN_ORG_ID,
+  routingKey: `FieldServiceModule.${WORK_ORDER}.${SUB_DB_RECORD_UPDATED}`,
+  queue: `${process.env.DOMAIN}.WorkOrderHandler.handleRecordUpdatedEvent`,
+  errorHandler: SubscriberErrorHandler.handleError,
+})
+private async handleRecordUpdatedEvent(msg: IDbRecordUpdated) {
+  try {
+    // Check for stage changes
+    if (msg.event === LogsConstants.DB_RECORD_STAGE_UPDATED) {
+      const { id, entity, properties, stage } = msg;
+      // Handle stage transition
+    }
+  } catch (e) {
+    // Error handling
+  }
+}
 
-// Entity events
-await channel.consume(ROUTING_KEY_ORDER_CREATED, (msg) => {
-  const event: OrderCreatedEvent = JSON.parse(msg.content.toString());
-  // Handle event
-});
+// Subscribe to record created events
+@RabbitSubscribe({
+  exchange: process.env.ODIN_ORG_ID,
+  routingKey: `FieldServiceModule.${WORK_ORDER}.${SUB_DB_RECORD_CREATED}`,
+  queue: `${process.env.DOMAIN}.WorkOrderHandler.handleRecordCreatedEvent`,
+  errorHandler: SubscriberErrorHandler.handleError,
+})
+private async handleRecordCreatedEvent(msg: IDbRecordCreated) {
+  try {
+    const { id, entity, properties } = msg;
+    // Handle new record
+  } catch (e) {
+    // Error handling
+  }
+}
+```
 
-// Action events
-await channel.consume(ROUTING_KEY_ACTIVATE_ORDER, (msg) => {
-  const event: ActivateOrderMessage = JSON.parse(msg.content.toString());
-  // Handle action completion
-});
+### Common Event Constants
+
+```typescript
+// Record lifecycle events
+SUB_DB_RECORD_CREATED    // New record created
+SUB_DB_RECORD_UPDATED    // Record updated (includes stage changes)
+SUB_DB_RECORD_DELETED    // Record deleted
+
+// Check event type in handler
+if (msg.event === LogsConstants.DB_RECORD_STAGE_UPDATED) { ... }
+if (msg.event === LogsConstants.DB_RECORD_UPDATED) { ... }
 ```
 
 ## Migration Guide

package/dist/runner.js

@@ -63,6 +63,73 @@ const odin_sdk_generator_1 = require("@d19n/odin-sdk-generator");
 const dotenv = __importStar(require("dotenv"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+/**
+ * Custom error class for SDK generation failures
+ */
+class SdkGenerationError extends Error {
+    constructor(step, reason, missingPaths) {
+        super(`SDK Generation failed at step "${step}": ${reason}`);
+        this.step = step;
+        this.reason = reason;
+        this.missingPaths = missingPaths;
+        this.name = 'SdkGenerationError';
+    }
+}
+/**
+ * Verify that a directory exists and contains at least one file
+ */
+function verifyDirectoryOutput(dir, stepName, minFiles = 1) {
+    if (!fs.existsSync(dir)) {
+        throw new SdkGenerationError(stepName, `Output directory does not exist`, [dir]);
+    }
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.ts'));
+    if (files.length < minFiles) {
+        throw new SdkGenerationError(stepName, `Output directory has insufficient files (expected at least ${minFiles}, found ${files.length})`, [dir]);
+    }
+    console.log(`  ✓ Verified: ${dir} (${files.length} files)`);
+}
+/**
+ * Verify that specific files exist
+ */
+function verifyFilesExist(files, stepName) {
+    const missing = [];
+    for (const file of files) {
+        if (!fs.existsSync(file)) {
+            missing.push(file);
+        }
+    }
+    if (missing.length > 0) {
+        throw new SdkGenerationError(stepName, `Expected output files are missing`, missing);
+    }
+    for (const file of files) {
+        console.log(`  ✓ Verified: ${file}`);
+    }
+}
+/**
+ * Run a generation step with error handling and verification
+ */
+function runStep(stepNumber, totalSteps, stepName, generatorFn, verifyFn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        console.log(`\n[${stepNumber}/${totalSteps}] ${stepName}...`);
+        try {
+            const result = yield generatorFn();
+            // Run verification if provided
+            if (verifyFn) {
+                verifyFn();
+            }
+            return result;
+        }
+        catch (error) {
+            // If it's already our error type, rethrow
+            if (error instanceof SdkGenerationError) {
+                throw error;
+            }
+            // Wrap other errors
+            const message = error instanceof Error ? error.message : String(error);
+            throw new SdkGenerationError(stepName, message);
+        }
+    });
+}
 function cleanDirectory(dir) {
     if (fs.existsSync(dir)) {
         console.log(`Cleaning ${dir}...`);
@@ -77,6 +144,7 @@ const entitiesToExclude = ['Dashboard'];
 const packageName = '@d19n/youfibre-odin-sdk';
 function generate() {
     return __awaiter(this, void 0, void 0, function* () {
+        const totalSteps = 11;
         console.log('='.repeat(60));
         console.log('ODIN SDK Generation');
         console.log('='.repeat(60));
@@ -106,61 +174,47 @@ function generate() {
         // ============================================
         // STEP 1: Generate Actions (MUST be first)
         // ============================================
-        console.log('\n[1/11] Generating actions...');
-        yield (0, odin_sdk_generator_1.generateActions)();
+        yield runStep(1, totalSteps, 'Generating actions', () => (0, odin_sdk_generator_1.generateActions)(), () => verifyDirectoryOutput('./actions-v2', 'Generate Actions'));
         // ============================================
         // STEP 2: Generate Entities
         // ============================================
-        console.log('\n[2/11] Generating entities...');
-        yield (0, odin_sdk_generator_1.generateEntities)({ entitiesToExclude });
+        yield runStep(2, totalSteps, 'Generating entities', () => (0, odin_sdk_generator_1.generateEntities)({ entitiesToExclude }), () => verifyDirectoryOutput('./entities-v2', 'Generate Entities'));
         // ============================================
         // STEP 3: Generate Legacy API SDK (deprecated)
         // ============================================
-        console.log('\n[3/11] Generating legacy API SDK (deprecated)...');
-        yield (0, odin_sdk_generator_1.generateApiSdk)({ entitiesToExclude });
+        yield runStep(3, totalSteps, 'Generating legacy API SDK (deprecated)', () => (0, odin_sdk_generator_1.generateApiSdk)({ entitiesToExclude }), () => verifyDirectoryOutput('./api-sdk-v2', 'Generate API SDK'));
         // ============================================
         // STEP 4: Generate Legacy DB SDK (deprecated)
         // ============================================
-        console.log('\n[4/11] Generating legacy DB SDK (deprecated)...');
-        yield (0, odin_sdk_generator_1.generateDbSdk)({ entitiesToExclude });
+        yield runStep(4, totalSteps, 'Generating legacy DB SDK (deprecated)', () => (0, odin_sdk_generator_1.generateDbSdk)({ entitiesToExclude }), () => verifyDirectoryOutput('./db-sdk-v2', 'Generate DB SDK'));
         // ============================================
         // STEP 5: Generate Record Wrappers
         // ============================================
-        console.log('\n[5/11] Generating record wrappers...');
-        yield (0, odin_sdk_generator_1.generateRecordWrappers)({ entitiesToExclude });
+        yield runStep(5, totalSteps, 'Generating record wrappers', () => (0, odin_sdk_generator_1.generateRecordWrappers)({ entitiesToExclude }), () => verifyDirectoryOutput('./records-v2', 'Generate Record Wrappers'));
         // ============================================
         // STEP 6: Generate API Accessors
         // ============================================
-        console.log('\n[6/11] Generating API accessors...');
-        yield (0, odin_sdk_generator_1.generateEntityAccessors)({ entitiesToExclude });
+        yield runStep(6, totalSteps, 'Generating API accessors', () => (0, odin_sdk_generator_1.generateEntityAccessors)({ entitiesToExclude }), () => verifyDirectoryOutput('./accessors-v2', 'Generate API Accessors'));
         // ============================================
         // STEP 7: Generate DB Accessors
         // ============================================
-        console.log('\n[7/11] Generating DB accessors...');
-        yield (0, odin_sdk_generator_1.generateDbAccessors)({ entitiesToExclude });
+        yield runStep(7, totalSteps, 'Generating DB accessors', () => (0, odin_sdk_generator_1.generateDbAccessors)({ entitiesToExclude }), () => verifyDirectoryOutput('./db-accessors-v2', 'Generate DB Accessors'));
         // ============================================
         // STEP 8: Generate Unified Clients
         // ============================================
-        console.log('\n[8/11] Generating unified clients...');
-        yield (0, odin_sdk_generator_1.generateTypedClient)();
+        yield runStep(8, totalSteps, 'Generating unified clients', () => (0, odin_sdk_generator_1.generateTypedClient)(), () => verifyFilesExist(['./OdinApiClient.ts', './OdinDbClient.ts'], 'Generate Unified Clients'));
         // ============================================
         // STEP 9: Generate Entity Registry
         // ============================================
-        console.log('\n[9/11] Generating entity registry...');
-        yield (0, odin_sdk_generator_1.generateEntityRegistry)();
+        yield runStep(9, totalSteps, 'Generating entity registry', () => (0, odin_sdk_generator_1.generateEntityRegistry)(), () => verifyFilesExist(['./EntityRegistry.ts'], 'Generate Entity Registry'));
         // ============================================
         // STEP 10: Generate Root Barrel Exports
         // ============================================
-        console.log('\n[10/11] Generating root barrel exports...');
-        yield (0, odin_sdk_generator_1.generateBarrelExports)();
+        yield runStep(10, totalSteps, 'Generating root barrel exports', () => (0, odin_sdk_generator_1.generateBarrelExports)(), () => verifyFilesExist(['./index.ts'], 'Generate Barrel Exports'));
         // ============================================
         // STEP 11: Generate README Documentation
         // ============================================
-        console.log('\n[11/11] Generating README documentation...');
-        yield (0, odin_sdk_generator_1.generateReadme)({
-            packageName,
-            entitiesToExclude,
-        });
+        yield runStep(11, totalSteps, 'Generating README documentation', () => (0, odin_sdk_generator_1.generateReadme)({ packageName, entitiesToExclude }), () => verifyFilesExist(['./README.md'], 'Generate README'));
         // NOTE: entities-v2 and actions-v2 barrel exports are handled by
         // steps 1 and 2 (generateActions, generateEntities). They are NOT
         // re-exported from the root index.ts due to export name conflicts.
@@ -169,7 +223,7 @@ function generate() {
         // DONE
         // ============================================
         console.log('\n' + '='.repeat(60));
-        console.log('Generation complete!');
+        console.log('✓ Generation complete!');
         console.log('='.repeat(60));
         console.log(`
 Generated directories:
@@ -190,5 +244,28 @@ Generated files:
 `);
     });
 }
-// Run generation
-generate().catch(console.error);
+// Run generation with proper error handling
+generate().catch((error) => {
+    var _a;
+    console.error('\n' + '='.repeat(60));
+    console.error('✗ SDK GENERATION FAILED');
+    console.error('='.repeat(60));
+    if (error instanceof SdkGenerationError) {
+        console.error(`\nStep: ${error.step}`);
+        console.error(`Reason: ${error.reason}`);
+        if ((_a = error.missingPaths) === null || _a === void 0 ? void 0 : _a.length) {
+            console.error('\nMissing paths:');
+            for (const p of error.missingPaths) {
+                console.error(`  - ${p}`);
+            }
+        }
+    }
+    else {
+        console.error(`\nError: ${error.message || error}`);
+    }
+    console.error('\n' + '='.repeat(60));
+    console.error('Build aborted. No SDK version will be published.');
+    console.error('='.repeat(60));
+    // Exit with error code to fail CI/CD pipeline
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d19n/youfibre-odin-sdk",
-  "version": "1.0.292",
+  "version": "1.0.294",
   "description": "",
   "author": "@d19n",
   "license": "UNLICENSED",
@@ -11,7 +11,7 @@
     "typescript": "4.8.4"
   },
   "dependencies": {
-    "@d19n/odin-sdk-generator": "^3.0.186",
+    "@d19n/odin-sdk-generator": "^3.0.188",
     "@d19n/odin-types": "^3.0.18",
     "@d19n/youfibre-odin-sdk": "^1.0.219"
   },