@fluentcommerce/fc-connect-sdk 0.1.51 → 0.1.53

package/docs/02-CORE-GUIDES/api-reference/event-api-input-output-reference.md

@@ -5,9 +5,10 @@
 ## Table of Contents
 
 1. [Success Response Structure](#success-response-structure)
-2. [Error Response Structure](#error-response-structure)
-3. [Live Examples](#live-examples)
-4. [HTTP Status Codes](#http-status-codes)
+2. [Event Log Query (GET)](#event-log-query-get)
+3. [Error Response Structure](#error-response-structure)
+4. [Live Examples](#live-examples)
+5. [HTTP Status Codes](#http-status-codes)
 
 ---
 
@@ -91,6 +92,228 @@ interface EventResponse {
 
 ---
 
+## Event Log Query (GET)
+
+Use `client.getEvents()` for Event API log search (`GET /api/v4.1/event`).
+
+### Input: FluentEventQueryParams
+
+```typescript
+interface FluentEventQueryParams {
+  start?: number;
+  count?: number;
+  from?: string;
+  to?: string;
+  name?: string;
+  category?: string;
+  retailerId?: string | number;
+  eventType?: string;
+  eventStatus?: string;
+  'context.rootEntityType'?: string;
+  'context.rootEntityId'?: string | number;
+  'context.rootEntityRef'?: string;
+  'context.entityType'?: string;
+  'context.entityId'?: string | number;
+  'context.entityRef'?: string;
+}
+```
+
+> **Note:** Context parameters use dot-notation (`context.rootEntityType`). In JavaScript/TypeScript, keys with dots **must be quoted**:
+> ```typescript
+> // ✅ Correct - quotes required for dot-notation keys
+> { 'context.rootEntityType': 'ORDER', eventType: 'ORCHESTRATION_AUDIT' }
+>
+> // ❌ Wrong - will cause syntax error
+> { context.rootEntityType: 'ORDER' }
+> ```
+
+### Output: FluentEventLogResponse (SUCCESS)
+
+```typescript
+interface FluentEventLogResponse {
+  start: number;
+  count: number;
+  hasMore: boolean;
+  results: FluentEventLogItem[];
+}
+```
+
+### When to use `getEvents()`
+
+- Search historical events across a time window
+- Investigate failed or delayed orchestration flows
+- Filter by entity context to trace a specific order/job/product
+- Collect event IDs for deeper inspection with `getEventById()`
+
+### `getEvents()` limitations and behavior
+
+- Read-only endpoint: does not trigger workflows or mutate data
+- `count` is capped by Fluent API (max `5000` per call)
+- Time window constraints apply to `from` and `to`
+- Empty `results` is a valid response for non-matching filters
+- For large datasets, iterate with pagination (`start`, `count`)
+
+### Live Example: Orchestration Audit Query
+
+**SDK Code:**
+```typescript
+const result = await client.getEvents({
+  'context.rootEntityType': 'JOB',
+  eventType: 'ORCHESTRATION_AUDIT',
+  start: 1,
+  count: 1000,
+});
+```
+
+**Output (HTTP 200):**
+```json
+{
+  "start": 1,
+  "count": 1000,
+  "hasMore": false,
+  "results": [
+    {
+      "id": "e2cc5040-360b-43e9-b3c0-07bbc1934f82",
+      "name": "BATCH_COMPLETE",
+      "type": "ORCHESTRATION_AUDIT",
+      "accountId": "HMDEV",
+      "retailerId": "5",
+      "category": "BATCH",
+      "context": {
+        "sourceEvents": ["babc5f37-0a53-4d8e-85f2-dfab813d1e87"],
+        "entityType": "BATCH",
+        "entityId": "12",
+        "entityRef": "12",
+        "rootEntityType": "JOB",
+        "rootEntityId": "13",
+        "rootEntityRef": "13"
+      },
+      "eventStatus": "COMPLETE",
+      "attributes": null,
+      "source": null,
+      "generatedBy": "Rubix User",
+      "generatedOn": "2026-02-05T06:31:56.895+00:00"
+    }
+  ]
+}
+```
+
+---
+
+## Get Event By ID (GET)
+
+Use `client.getEventById(eventId)` to retrieve a single event by its unique identifier (`GET /api/v4.1/event/{eventId}`).
+
+### Input
+
+```typescript
+// Single string parameter - the event's unique ID
+const eventId = '05838ba2-7025-11eb-b493-0f90922e985a';
+const event = await client.getEventById(eventId);
+```
+
+### Output: FluentEventLogItem
+
+```typescript
+interface FluentEventLogItem {
+  id: string;                              // Unique event identifier
+  name: string;                            // Event name (e.g., "DeactivateProduct")
+  type?: string;                           // ORCHESTRATION, ORCHESTRATION_AUDIT, API, GENERAL
+  accountId?: string;                      // Account identifier
+  retailerId?: string;                     // Retailer identifier
+  category?: string;                       // ruleSet, snapshot, ACTION, exception, etc.
+  context?: FluentEventLogContext;         // Entity context information
+  eventStatus?: string;                    // SUCCESS, FAILED, PENDING, NO_MATCH, COMPLETE
+  attributes?: FluentEventLogAttribute[] | Record<string, AttributeValue> | null;
+  source?: string | null;                  // Event source
+  generatedBy?: string;                    // Who/what generated the event
+  generatedOn?: string;                    // ISO timestamp when event was generated
+}
+
+interface FluentEventLogContext {
+  sourceEvents?: string[];                 // Parent event IDs (for tracing)
+  entityType?: string;                     // Entity type (ORDER, FULFILMENT, etc.)
+  entityId?: string;                       // Entity ID
+  entityRef?: string;                      // Entity reference
+  rootEntityType?: string;                 // Root entity type
+  rootEntityId?: string;                   // Root entity ID
+  rootEntityRef?: string;                  // Root entity reference
+}
+```
+
+> Note: `attributes` shape varies by event type. Some events return a key/value object, while orchestration events may return arrays or `null`.
+
+### Live Example: Get Event Details
+
+**SDK Code:**
+```typescript
+// Get specific event by ID
+const event = await client.getEventById('e2cc5040-360b-43e9-b3c0-07bbc1934f82');
+
+console.log(`Event: ${event.name}`);
+console.log(`Status: ${event.eventStatus}`);
+console.log(`Entity: ${event.context?.entityType}:${event.context?.entityRef}`);
+
+// Trace parent events
+if (event.context?.sourceEvents?.length) {
+  for (const parentId of event.context.sourceEvents) {
+    const parent = await client.getEventById(parentId);
+    console.log(`  └─ Parent: ${parent.name} (${parent.eventStatus})`);
+  }
+}
+
+// Extract timing attributes (if available)
+const attrs = event.attributes as Record<string, any> | null;
+if (attrs) {
+  const startTimer = attrs['startTimer'];
+  const stopTimer = attrs['stopTimer'];
+  if (startTimer && stopTimer) {
+    const durationMs = parseInt(stopTimer) - parseInt(startTimer);
+    console.log(`  Duration: ${durationMs}ms`);
+  }
+}
+```
+
+**Output (HTTP 200):**
+```json
+{
+  "id": "e2cc5040-360b-43e9-b3c0-07bbc1934f82",
+  "name": "BATCH_COMPLETE",
+  "type": "ORCHESTRATION_AUDIT",
+  "accountId": "HMDEV",
+  "retailerId": "5",
+  "category": "BATCH",
+  "context": {
+    "sourceEvents": ["babc5f37-0a53-4d8e-85f2-dfab813d1e87"],
+    "entityType": "BATCH",
+    "entityId": "12",
+    "entityRef": "12",
+    "rootEntityType": "JOB",
+    "rootEntityId": "13",
+    "rootEntityRef": "13"
+  },
+  "eventStatus": "COMPLETE",
+  "attributes": null,
+  "source": null,
+  "generatedBy": "Rubix User",
+  "generatedOn": "2026-02-05T06:31:56.895+00:00"
+}
+```
+
+### Error: Event Not Found (404)
+
+```typescript
+try {
+  const event = await client.getEventById('non-existent-id');
+} catch (error) {
+  if (error instanceof FluentAPIError && error.statusCode === 404) {
+    console.log('Event not found');
+  }
+}
+```
+
+---
+
 ## Error Response Structure
 
 ### Output: FluentAPIError (THROWN)
@@ -101,7 +324,7 @@ When events fail, the SDK throws structured error objects:
 class FluentAPIError extends Error {
   name: 'FluentAPIError';
   message: string;              // Error description (e.g., "Request failed: 400")
-  status: number;               // HTTP status code (400, 404, 500, etc.)
+  statusCode: number;           // HTTP status code (400, 404, 500, etc.)
   details?: any;                // Additional error context
   errors?: Array<any>;          // Validation errors (if applicable)
 }
@@ -124,7 +347,7 @@ class FluentAPIError extends Error {
 FluentAPIError {
   name: "FluentAPIError",
   message: "Request failed: 404",
-  status: 404,
+  statusCode: 404,
   details: "No workflow rule matched this event"
 }
 ```
@@ -152,7 +375,7 @@ FluentAPIError {
 FluentAPIError {
   name: "FluentAPIError",
   message: "Request failed: 400",
-  status: 400,
+  statusCode: 400,
   details: "Bad Request - Invalid event configuration"
 }
 ```
@@ -285,7 +508,7 @@ POST /api/v4.1/event/sync
 
 # Output (HTTP 404) - THROWS FluentAPIError
 FluentAPIError: Request failed: 404
-  status: 404
+  statusCode: 404
   message: "No workflow rule matched this event"
 ```
 
@@ -300,7 +523,7 @@ try {
   }, 'sync'); // ← Sync mode waits for workflow
 } catch (error) {
   if (error instanceof FluentAPIError) {
-    console.error(`❌ HTTP ${error.status}: ${error.message}`);
+    console.error(`❌ HTTP ${error.statusCode}: ${error.message}`);
     // Output: ❌ HTTP 404: Request failed: 404
   }
 }
@@ -363,7 +586,7 @@ POST /api/v4.1/event/async
 
 # Output (HTTP 400) - THROWS FluentAPIError
 FluentAPIError: Request failed: 400
-  status: 400
+  statusCode: 400
   message: "Bad Request"
 ```
 
@@ -378,7 +601,7 @@ try {
   }, 'async');
 } catch (error) {
   if (error instanceof FluentAPIError) {
-    console.error(`❌ HTTP ${error.status}: ${error.message}`);
+    console.error(`❌ HTTP ${error.statusCode}: ${error.message}`);
     // Output: ❌ HTTP 400: Request failed: 400
     // SDK does NOT retry 4xx errors (client error, not transient)
   }
@@ -483,7 +706,7 @@ try {
 {
   name: "FluentAPIError",
   message: "Request failed: 404",
-  status: 404,
+  statusCode: 404,
   details: "No workflow rule matched"
 }
 ```
@@ -563,7 +786,7 @@ try {
   await client.sendEvent({ name: 'InvalidEvent', ... });
 } catch (error) {
   // Throws immediately, NO retries
-  console.error(error.status); // 400
+  console.error(error.statusCode); // 400
 }
 ```
 
@@ -593,8 +816,8 @@ for (const record of records) {
 
     if (error instanceof FluentAPIError) {
       // SDK already retried 401/5xx - this is non-retryable
-      console.error(`❌ ${record.sku} - HTTP ${error.status}: ${error.message}`);
-      results.errors.push({ sku: record.sku, status: error.status, error: error.message });
+      console.error(`❌ ${record.sku} - HTTP ${error.statusCode}: ${error.message}`);
+      results.errors.push({ sku: record.sku, statusCode: error.statusCode, error: error.message });
     } else if (error instanceof AuthenticationError) {
       // Auth failed after 3 retries - credentials issue
       console.error(`❌ Auth failure: ${error.message}`);
@@ -641,7 +864,7 @@ async function processBatch(products: Product[]): Promise<EventResult[]> {
         results.push({
           sku: product.sku,
           success: false,
-          error: `HTTP ${error.status}: ${error.message}`
+          error: `HTTP ${error.statusCode}: ${error.message}`
         });
       } else {
         results.push({
@@ -689,6 +912,252 @@ async function processBatch(products: Product[]): Promise<EventResult[]> {
 
 ---
 
+## Event Log Query by ID (GET /api/v4.1/event/{eventId})
+
+Use `client.getEventById(eventId)` to retrieve a single event by its unique identifier.
+
+### Input
+
+```typescript
+const event = await client.getEventById('05838ba2-7025-11eb-b493-0f90922e985a');
+```
+
+### Output: FluentEventLogItem
+
+```typescript
+interface FluentEventLogItem {
+  id: string;
+  name: string;                  // Event name (e.g., "BATCH_COMPLETE") — can be null
+  type?: string;                 // ORCHESTRATION_AUDIT, ORCHESTRATION, API, etc.
+  accountId?: string;
+  retailerId?: string;           // String in API response
+  category?: string;
+  context?: FluentEventLogContext;
+  eventStatus?: string;          // PENDING, SUCCESS, FAILED, COMPLETE, etc.
+  attributes?: FluentEventLogAttribute[] | null;  // Can be null
+  source?: string | null;
+  generatedBy?: string;
+  generatedOn?: string;          // ISO timestamp
+}
+```
+
+### Live Example: Get Event by ID
+
+**SDK Code:**
+```typescript
+const event = await client.getEventById('e2cc5040-360b-43e9-b3c0-07bbc1934f82');
+console.log(`Event: ${event.name} - Status: ${event.eventStatus}`);
+
+// Trace parent events
+if (event.context?.sourceEvents?.length) {
+  for (const parentId of event.context.sourceEvents) {
+    const parent = await client.getEventById(parentId);
+    console.log(`Parent: ${parent.name} (${parent.eventStatus})`);
+  }
+}
+
+// Extract timing from attributes
+if (Array.isArray(event.attributes)) {
+  const startTimer = event.attributes.find(a => a.name === 'startTimer')?.value;
+  const stopTimer = event.attributes.find(a => a.name === 'stopTimer')?.value;
+  if (startTimer && stopTimer) {
+    console.log(`Duration: ${Number(stopTimer) - Number(startTimer)}ms`);
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  const event = await client.getEventById('nonexistent-id');
+} catch (error) {
+  if (error instanceof FluentAPIError && error.statusCode === 404) {
+    console.log('Event not found');
+  }
+}
+```
+
+---
+
+## Event Type / Status / Category Reference
+
+### Event Types (`eventType` parameter)
+
+| Value | Description |
+|-------|-------------|
+| `ORCHESTRATION` | Trigger part or whole of a workflow |
+| `ORCHESTRATION_AUDIT` | Audit of what happened during workflow execution |
+| `API` | API interactions and system events |
+| `INTEGRATION` | Integration-related events |
+| `SECURITY` | Security events |
+| `GENERAL` | General system events and notifications |
+
+### Event Statuses (`eventStatus` parameter)
+
+| Value | Description |
+|-------|-------------|
+| `PENDING` | Event is pending processing |
+| `SCHEDULED` | Event is scheduled for processing |
+| `NO_MATCH` | No matching ruleset found for this event |
+| `SUCCESS` | Event processed successfully |
+| `FAILED` | Event processing failed |
+| `COMPLETE` | Event completed |
+
+### Event Categories (`category` parameter)
+
+| Value | Description |
+|-------|-------------|
+| `snapshot` | State snapshots |
+| `ruleSet` | Ruleset execution events |
+| `rule` | Individual rule execution events |
+| `ACTION` | User/system actions |
+| `CUSTOM` | Custom log actions |
+| `exception` | Error/exception events |
+| `ORDER_WORKFLOW` | Order-specific workflow events |
+| `BATCH` | Batch processing events |
+
+### Root Entity Types (`context.rootEntityType` parameter)
+
+| Value | Description |
+|-------|-------------|
+| `ORDER` | Customer orders |
+| `LOCATION` | Physical locations and warehouses |
+| `FULFILMENT_OPTIONS` | Fulfillment configuration |
+| `PRODUCT_CATALOGUE` | Product definitions and catalogs |
+| `INVENTORY_CATALOGUE` | Inventory management |
+| `VIRTUAL_CATALOGUE` | Virtual inventory positions |
+| `CONTROL_GROUP` | Control and governance |
+| `RETURN_ORDER` | Return processing |
+| `BILLING_ACCOUNT` | Billing and payments |
+| `JOB` | Background jobs and batch processes |
+
+### Entity Types (`context.entityType` parameter)
+
+| Value | Description |
+|-------|-------------|
+| `ORDER` | Customer orders |
+| `FULFILMENT` | Fulfillment operations |
+| `ARTICLE` | Articles within fulfillments |
+| `CONSIGNMENT` | Shipping consignments |
+| `WAVE` | Wave picking operations |
+| `BATCH` | Batch processing |
+| `LOCATION` | Location operations |
+| `PRODUCT` | Product records |
+| `CATEGORY` | Product categories |
+| `INVENTORY_POSITION` | Inventory positions |
+| `INVENTORY_QUANTITY` | Inventory quantities |
+| `VIRTUAL_POSITION` | Virtual inventory positions |
+| `CONTROL` | Individual controls |
+| `RETURN_FULFILMENT` | Return processing |
+| `CREDIT_MEMO` | Financial adjustments |
+
+---
+
+## Common Use Cases
+
+### 1. Track Batch Ingestion Results
+
+```typescript
+// Find all events for a specific job
+const events = await client.getEvents({
+  'context.rootEntityType': 'JOB',
+  'context.rootEntityId': '13',
+  eventType: 'ORCHESTRATION_AUDIT',
+  count: 1000,
+});
+
+console.log(`Found ${events.results.length} events`);
+for (const event of events.results) {
+  console.log(`  ${event.name} (${event.context?.entityType}) - ${event.eventStatus}`);
+}
+```
+
+### 2. Find Failed Workflow Events
+
+```typescript
+const failed = await client.getEvents({
+  eventStatus: 'FAILED',
+  eventType: 'ORCHESTRATION_AUDIT',
+  from: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+  to: new Date().toISOString(),
+  count: 1000,
+});
+
+for (const event of failed.results) {
+  console.log(`FAILED: ${event.name} on ${event.context?.entityType}:${event.context?.entityRef}`);
+}
+```
+
+### 3. Paginate Through Large Result Sets
+
+```typescript
+let start = 0;
+const pageSize = 1000;
+let allEvents: FluentEventLogItem[] = [];
+
+let hasMore = true;
+while (hasMore) {
+  const page = await client.getEvents({
+    'context.rootEntityType': 'ORDER',
+    eventType: 'ORCHESTRATION_AUDIT',
+    start,
+    count: pageSize,
+  });
+
+  allEvents.push(...page.results);
+  hasMore = page.hasMore;
+  start += page.count;
+}
+
+console.log(`Total events: ${allEvents.length}`);
+```
+
+### 4. Extract Performance Timing
+
+```typescript
+const events = await client.getEvents({
+  category: 'ruleSet',
+  eventType: 'ORCHESTRATION_AUDIT',
+  from: '2026-02-01T00:00:00.000Z',
+  to: '2026-02-15T00:00:00.000Z',
+  count: 5000,
+});
+
+for (const event of events.results) {
+  if (Array.isArray(event.attributes)) {
+    const startTimer = event.attributes.find(a => a.name === 'startTimer')?.value;
+    const stopTimer = event.attributes.find(a => a.name === 'stopTimer')?.value;
+    if (startTimer && stopTimer) {
+      const duration = Number(stopTimer) - Number(startTimer);
+      console.log(`${event.name}: ${duration}ms (${event.eventStatus})`);
+    }
+  }
+}
+```
+
+### 5. API Time Range Limits
+
+The Event API enforces time range constraints:
+- **`from`**: Must be within **4 months back** from current date
+- **`to`**: Must be within **1 month forward** from current date
+- **Default**: If `from` is not specified, searches the **past 30 days**
+- **Max `count`**: 5000 events per request (recommended to avoid timeouts)
+- **Date format**: `YYYY-MM-DDTHH:mm:ss.SSSZ` (UTC ISO string)
+
+```typescript
+// This will fail - too far in the past
+try {
+  const tooOld = await client.getEvents({
+    from: '2020-01-01T00:00:00.000Z', // More than 4 months ago
+  });
+} catch (error) {
+  // API Error: "'from' and 'to' must be within 4 months back and 1 months forward"
+}
+```
+
+---
+
 ## Related Documentation
 
 - **Event API Guide**: [fc-connect-sdk/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/event-api-guide.md](../docs/01-TEMPLATES/versori/workflows/ingestion/event-api/event-api-guide.md)
@@ -697,6 +1166,6 @@ async function processBatch(products: Product[]): Promise<EventResult[]> {
 
 ---
 
-**Generated from live test environment**: sagirish.test.api.fluentretail.com
-**SDK Version**: 0.1.46
-**Test Date**: 2025-01-19
+**Generated from live test environments**: sagirish.test.api.fluentretail.com, hmdev.sandbox.api.fluentretail.com
+**SDK Version**: 0.1.51
+**Last Updated**: 2026-02-15

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-01-client-api.md

@@ -310,6 +310,89 @@ const event = await client.sendEvent(
 );
 ```
 
+#### getEvents Method
+
+Search event logs and orchestration audit events using Event API filters.
+
+```typescript
+async getEvents(params?: FluentEventQueryParams): Promise<FluentEventLogResponse>
+```
+
+**Key Filters:**
+
+- `eventType` - `ORCHESTRATION`, `ORCHESTRATION_AUDIT`, `API`, `GENERAL`
+- `eventStatus` - `PENDING`, `SCHEDULED`, `SUCCESS`, `FAILED`, `COMPLETE`, `NO_MATCH`
+- `context.rootEntityType`, `context.rootEntityId`, `context.rootEntityRef`
+- `context.entityType`, `context.entityId`, `context.entityRef`
+- `from`, `to`, `start`, `count`
+
+**Example:**
+
+```typescript
+const auditEvents = await client.getEvents({
+  'context.rootEntityType': 'JOB',
+  eventType: 'ORCHESTRATION_AUDIT',
+  start: 1,
+  count: 1000,
+});
+
+console.log(auditEvents.hasMore);
+console.log(auditEvents.results[0]?.name);
+```
+
+**Response Shape:**
+
+```typescript
+interface FluentEventLogResponse {
+  start: number;
+  count: number;
+  hasMore: boolean;
+  results: FluentEventLogItem[];
+}
+```
+
+**When to use `getEvents()`:**
+
+- Investigate failed orchestration runs (`eventStatus: 'FAILED'`)
+- Trace execution for jobs/orders/products using context filters
+- Build operational dashboards and lightweight audit reports
+- Find candidate event IDs before calling `getEventById()`
+
+**Limitations / behavior notes:**
+
+- Read-only API: does not trigger workflows or mutate entities
+- `count` is capped by Fluent API (max `5000` per request)
+- Time window constraints apply to `from`/`to` on the backend API
+- Empty `results` for a valid query is normal and not treated as an error
+- Use bounded time ranges and pagination (`start` + `count`) for large searches
+
+#### getEventById Method
+
+Fetch a single event by ID from Event API.
+
+```typescript
+async getEventById(eventId: string): Promise<FluentEventLogItem>
+```
+
+**Example:**
+
+```typescript
+const event = await client.getEventById('e2cc5040-360b-43e9-b3c0-07bbc1934f82');
+console.log(event.name, event.eventStatus);
+```
+
+**When to use `getEventById()`:**
+
+- Drill into a known event from logs, alerts, or trace tooling
+- Inspect full context (`sourceEvents`, `entityRef`, `rootEntityRef`)
+- Correlate parent/child orchestration events for root-cause analysis
+
+**Limitations / behavior notes:**
+
+- Requires a concrete event ID (it does not support filtering)
+- Throws `FluentValidationError` for empty IDs
+- Returns HTTP `404` (as `FluentAPIError`) when the event does not exist
+
 ### Job & Batch Operations
 
 #### createJob Method