@d19n/youfibre-odin-sdk 1.0.200 → 1.0.201-beta.2

package/README.md

@@ -1,11 +1,209 @@
-# youfibre-odin-sdk
+# ODIN SDK for [Organization]
 
-#### Setup
+Type-safe SDK for interacting with your ODIN platform. Auto-generated from your schema with full TypeScript support.
 
-1. Ensure you have a .npmrc file with your npm auth credential in the root folder.
-    - run `npm install`
-2. Create a .env file and add the following credentials (get the client and sec)
-    - ODIN_HOST_URL=youfibre.api.sandbox.odinfusion.com
-    - ODIN_OAUTH_CLIENT_ID=XXXXXXX
-    - ODIN_OAUTH_CLIENT_SECRET=XXXXXXXXXX
-3. Run `make release-beta`
+## Installation
+
+```bash
+npm install @your-org/odin-sdk
+```
+
+## Quick Start
+
+```typescript
+import { OdinApiClient } from '@your-org/odin-sdk';
+
+const odin = new OdinApiClient();
+
+// Get a record (returns wrapped record with action methods)
+const order = await odin.orders.get('ORD-123');
+
+// Execute a typed action directly on the record
+await order.activateOrder({
+  ActiveDate: '2025-01-15',
+  BillingStartDate: '2025-02-01',
+}, { journeyId: accountId });
+```
+
+## Authentication
+
+```typescript
+// Environment variables (recommended)
+// Set ODIN_API_URL and ODIN_API_TOKEN
+const odin = new OdinApiClient();
+
+// Explicit token
+const odin = new OdinApiClient(undefined, 'your-api-token');
+
+// OAuth
+const odin = new OdinApiClient({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+});
+```
+
+## Actions
+
+Actions are executed directly on record objects with full type safety.
+
+### Typed Action Methods
+
+```typescript
+const order = await odin.orders.get('ORD-123');
+
+// Actions with required properties
+await order.activateOrder({
+  ActiveDate: '2025-01-15',      // ✓ Required - TypeScript enforces
+  BillingStartDate: '2025-02-01', // ✓ Required
+  DesiredBillingDay: 15,          // ✓ Optional
+}, { journeyId: accountId });
+
+// Actions without required properties
+await order.deactivateOrderDunning({ journeyId: accountId });
+
+// Actions with optional properties
+await order.clearDeactivateOnDate({ DeactivateOnDate: null }, { journeyId: accountId });
+```
+
+### Link Accumulation
+
+Links are accumulated and sent with the next action:
+
+```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');
+
+// Accumulate links (chainable)
+order.link(address).link(contact);
+
+// 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
+```
+
+### Unlinking Records
+
+Unlink is an immediate API call:
+
+```typescript
+// Unlink by record
+await order.unlink(oldAddress);
+
+// Unlink by ID
+await order.unlink('ADDR-123');
+```
+
+### Bulk Actions
+
+For bulk operations across multiple records:
+
+```typescript
+await odin.actions.applyToMany(
+  'OrderModule:Order',
+  ['ORD-123', 'ORD-456', 'ORD-789'],
+  'BulkApprove',
+  { ApprovedBy: 'admin@company.com' }
+);
+```
+
+## Reading Records
+
+### Get Records
+
+```typescript
+// Single record (returns wrapped record)
+const order = await odin.orders.get('ORD-123');
+
+// Access properties
+console.log(order.id);
+console.log(order.properties.Status);
+console.log(order.properties.TotalAmount);
+
+// Multiple records
+const orders = await odin.orders.getMany(['ORD-123', 'ORD-456']);
+```
+
+### Listing Records
+
+```typescript
+// Simple filtering
+const results = await odin.orders.list({
+  where: {
+    Status: 'Active',
+    TotalAmount: { gte: 1000 },
+  },
+  limit: 100,
+  sort: [{ TotalAmount: 'desc' }],
+});
+
+// Returns wrapped records
+for (const order of results.data) {
+  await order.sendNotification({ ... });
+}
+```
+
+### Auto-Pagination
+
+```typescript
+for await (const batch of odin.orders.listAll({ where: { Status: 'Active' } })) {
+  for (const order of batch) {
+    await order.processOrder({ ... });
+  }
+}
+```
+
+### Full Search
+
+```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,
+  },
+});
+```
+
+## TypeScript Support
+
+All entities, actions, and properties are fully typed:
+
+```typescript
+import { OrderRecord, ActivateOrderProperties } from '@your-org/odin-sdk';
+
+const order = await odin.orders.get('ORD-123');
+
+// IDE autocomplete for record properties
+console.log(order.properties.Status);      // ✓ Autocomplete
+console.log(order.properties.TotalAmount); // ✓ Autocomplete
+
+// Type-safe action parameters
+await order.activateOrder({
+  ActiveDate: '2025-01-15',
+  BillingStartDate: '2025-02-01',
+});
+```
+
+## Environment Variables
+
+| 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 |
+
+## Regenerating the SDK
+
+```bash
+npm run generate
+```
+
+---
+
+*Auto-generated by [odin-sdk-generator](https://github.com/d19n-llc/odin-sdk-generator)*