@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

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

@@ -1,1171 +1,702 @@
-# Event API - Input/Output Reference Guide
-
-> **Complete reference** for Event API request/response structures with live examples from sagirish test environment
-
-## Table of Contents
-
-1. [Success Response Structure](#success-response-structure)
-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)
-
----
-
-## Success Response Structure
-
-### Input: FluentEvent
-
-```typescript
-interface FluentEvent {
-  retailerId: string;          // REQUIRED: Retailer ID (e.g., "2")
-  name: string;                // REQUIRED: Event name (e.g., "OrderCancel1")
-  entityRef: string;           // REQUIRED: Entity reference (e.g., "G_TEST_FC_POSTMAN_34")
-  entityType: string;          // REQUIRED: Entity type (ORDER, PRODUCT, LOCATION, etc.)
-  attributes?: Record<string, any>;  // OPTIONAL: Custom event attributes
-}
-```
-
-### Output: EventResponse (SUCCESS)
-
-```typescript
-interface EventResponse {
-  id?: string;                 // Event ID (if returned by API)
-  success: boolean;            // Always true for successful responses
-  status?: number;             // Event status from Fluent API (CREATED, COMPLETED, etc.)
-  statusCode?: number;         // HTTP status code (200, 201, 202) - Consistent with error.statusCode
-  message?: string;            // Optional message from API
-}
-```
-
-### Live Example: Async Mode Success
-
-**Input:**
-```json
-{
-  "retailerId": "2",
-  "name": "OrderCancel1",
-  "entityRef": "G_TEST_FC_POSTMAN_34",
-  "entityType": "ORDER"
-}
-```
-
-**Output:**
-```json
-{
-  "success": true,
-  "statusCode": 200
-}
-```
-
-**Log Output:**
-```
-[FluentClient:event] Sending event "OrderCancel1" (ORDER:G_TEST_FC_POSTMAN_34, mode: async)
-[FluentClient:event] Event "OrderCancel1" sent successfully (id: undefined, statusCode: 200)
-```
-
----
-
-### Live Example: Product Event Success
-
-**Input:**
-```json
-{
-  "retailerId": "2",
-  "name": "PRODUCT.UPDATE",
-  "entityRef": "SKU-1763567425",
-  "entityType": "PRODUCT",
-  "attributes": {
-    "test": true,
-    "timestamp": "2025-01-19T05:30:25.500Z"
-  }
-}
-```
-
-**Output:**
-```json
-{
-  "success": true,
-  "statusCode": 200
-}
-```
-
----
-
-## 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)
-
-When events fail, the SDK throws structured error objects:
-
-```typescript
-class FluentAPIError extends Error {
-  name: 'FluentAPIError';
-  message: string;              // Error description (e.g., "Request failed: 400")
-  statusCode: number;           // HTTP status code (400, 404, 500, etc.)
-  details?: any;                // Additional error context
-  errors?: Array<any>;          // Validation errors (if applicable)
-}
-```
-
-### Live Example: No Workflow Match (Sync Mode)
-
-**Input:**
-```json
-{
-  "retailerId": "2",
-  "name": "OrderCancel1",
-  "entityRef": "SYNC-1763567424997",
-  "entityType": "ORDER"
-}
-```
-
-**Error Thrown:**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 404",
-  statusCode: 404,
-  details: "No workflow rule matched this event"
-}
-```
-
-**Error Detection Timing:**
-- **Async Mode**: Returns `200` immediately, workflow failures NOT detected
-- **Sync Mode**: Waits for workflow, throws error if workflow fails
-
----
-
-### Live Example: Invalid Event Name
-
-**Input:**
-```json
-{
-  "retailerId": "2",
-  "name": "OrderCancel",        // ← Event name has no matching workflow
-  "entityRef": "TEST-1763567425-1",
-  "entityType": "ORDER"
-}
-```
-
-**Error Thrown:**
-```typescript
-FluentAPIError {
-  name: "FluentAPIError",
-  message: "Request failed: 400",
-  statusCode: 400,
-  details: "Bad Request - Invalid event configuration"
-}
-```
-
----
-
-### Live Example: Missing retailerId (SDK Validation)
-
-**Input:**
-```json
-{
-  "name": "TEST.NO_RETAILER",
-  "entityType": "PRODUCT",
-  "entityRef": "NO-RETAILER-TEST"
-  // ❌ Missing retailerId
-}
-```
-
-**Error Thrown:**
-```typescript
-FluentValidationError {
-  name: "FluentValidationError",
-  message: "retailerId is required for Event API. Provide it in the event payload or client config.",
-  code: "VALIDATION_ERROR",
-  statusCode: 400
-}
-```
-
-**Key Difference:**
-- ✅ **SDK catches this BEFORE API call** (no network request made)
-- ✅ **Fail-fast validation** (saves time and reduces API load)
-
----
-
-## HTTP Status Codes
-
-### Success Codes (2xx)
-
-| Code | Meaning | When | Example Response |
-|------|---------|------|------------------|
-| **200** | OK | Event accepted (async mode) | `{ success: true, statusCode: 200 }` |
-| **201** | Created | Event created (sync mode, workflow completed) | `{ success: true, id: "evt-123", status: "CREATED", statusCode: 201 }` |
-| **202** | Accepted | Event queued for processing | `{ success: true, statusCode: 202 }` |
-
-### Client Error Codes (4xx)
-
-| Code | Meaning | When | SDK Retry | Example |
-|------|---------|------|-----------|---------|
-| **400** | Bad Request | Invalid event payload, no workflow match | ❌ No | Invalid event name |
-| **401** | Unauthorized | Auth token invalid/expired | ✅ Yes (3x) | OAuth2 token refresh |
-| **403** | Forbidden | Permission denied | ❌ No | Insufficient permissions |
-| **404** | Not Found | Sync mode: No workflow matched | ❌ No | No Rubix workflow rule |
-| **422** | Unprocessable | Event validation failed | ❌ No | Invalid entity reference |
-
-### Server Error Codes (5xx)
-
-| Code | Meaning | When | SDK Retry | Example |
-|------|---------|------|-----------|---------|
-| **500** | Internal Server Error | Fluent API error | ✅ Yes (3x) | Workflow execution failure |
-| **502** | Bad Gateway | Gateway timeout | ✅ Yes (3x) | Network issue |
-| **503** | Service Unavailable | API temporarily down | ✅ Yes (3x) | Maintenance window |
-| **504** | Gateway Timeout | Request timeout | ✅ Yes (3x) | Long-running workflow |
-
----
-
-## Live Examples from Test Environment
-
-### Test Environment Details
-
-```yaml
-Base URL: https://sagirish.test.api.fluentretail.com
-Retailer ID: 2
-Account ID: SAGIRISH
-Client ID: SAGIRISH
-```
-
-### Example 1: Successful Async Event
-
-```bash
-# Input
-POST /api/v4.1/event/async
-{
-  "retailerId": "2",
-  "name": "OrderCancel1",
-  "entityRef": "G_TEST_FC_POSTMAN_34",
-  "entityType": "ORDER"
-}
-
-# Output (HTTP 200)
-{
-  "success": true,
-  "statusCode": 200
-}
-```
-
-**SDK Code:**
-```typescript
-const client = new FluentClient({
-  baseUrl: 'https://sagirish.test.api.fluentretail.com',
-  clientId: 'SAGIRISH',
-  clientSecret: '534901d2-626d-4997-aabd-7600838d83c2',
-  username: 'module_test_admin',
-  password: '89YZBN',
-  retailerId: '2'
-});
-
-const result = await client.sendEvent({
-  name: 'OrderCancel1',
-  entityRef: 'G_TEST_FC_POSTMAN_34',
-  entityType: 'ORDER',
-  retailerId: '2'
-}, 'async');
-
-// result = { success: true, statusCode: 200 }
-```
-
----
-
-### Example 2: Sync Mode - Workflow Failure
-
-```bash
-# Input
-POST /api/v4.1/event/sync
-{
-  "retailerId": "2",
-  "name": "OrderCancel1",
-  "entityRef": "SYNC-1763567424997",
-  "entityType": "ORDER"
-}
-
-# Output (HTTP 404) - THROWS FluentAPIError
-FluentAPIError: Request failed: 404
-  statusCode: 404
-  message: "No workflow rule matched this event"
-```
-
-**SDK Code:**
-```typescript
-try {
-  const result = await client.sendEvent({
-    name: 'OrderCancel1',
-    entityRef: 'SYNC-1763567424997',
-    entityType: 'ORDER',
-    retailerId: '2'
-  }, 'sync'); // ← Sync mode waits for workflow
-} catch (error) {
-  if (error instanceof FluentAPIError) {
-    console.error(`❌ HTTP ${error.statusCode}: ${error.message}`);
-    // Output: ❌ HTTP 404: Request failed: 404
-  }
-}
-```
-
----
-
-### Example 3: Product Event with Attributes
-
-```bash
-# Input
-POST /api/v4.1/event/async
-{
-  "retailerId": "2",
-  "name": "PRODUCT.UPDATE",
-  "entityRef": "SKU-1763567425",
-  "entityType": "PRODUCT",
-  "attributes": {
-    "test": true,
-    "timestamp": "2025-01-19T05:30:25.500Z"
-  }
-}
-
-# Output (HTTP 200)
-{
-  "success": true,
-  "statusCode": 200
-}
-```
-
-**SDK Code:**
-```typescript
-const result = await client.sendEvent({
-  name: 'PRODUCT.UPDATE',
-  entityRef: 'SKU-1763567425',
-  entityType: 'PRODUCT',
-  retailerId: '2',
-  attributes: {
-    test: true,
-    timestamp: new Date().toISOString()
-  }
-}, 'async');
-
-// result = { success: true, statusCode: 200 }
-```
-
----
-
-### Example 4: Invalid Event Name (400 Error)
-
-```bash
-# Input
-POST /api/v4.1/event/async
-{
-  "retailerId": "2",
-  "name": "OrderCancel",  # ← No workflow configured for this event
-  "entityRef": "TEST-1763567425-1",
-  "entityType": "ORDER"
-}
-
-# Output (HTTP 400) - THROWS FluentAPIError
-FluentAPIError: Request failed: 400
-  statusCode: 400
-  message: "Bad Request"
-```
-
-**SDK Code:**
-```typescript
-try {
-  const result = await client.sendEvent({
-    name: 'OrderCancel', // ← Invalid/unconfigured event name
-    entityRef: 'TEST-1763567425-1',
-    entityType: 'ORDER',
-    retailerId: '2'
-  }, 'async');
-} catch (error) {
-  if (error instanceof FluentAPIError) {
-    console.error(`❌ HTTP ${error.statusCode}: ${error.message}`);
-    // Output: ❌ HTTP 400: Request failed: 400
-    // SDK does NOT retry 4xx errors (client error, not transient)
-  }
-}
-```
-
----
-
-### Example 5: Missing retailerId (SDK Validation)
-
-```bash
-# No API call made! SDK validates BEFORE calling API
-
-# Input
-{
-  "name": "TEST.NO_RETAILER",
-  "entityType": "PRODUCT",
-  "entityRef": "NO-RETAILER-TEST"
-  # ❌ Missing retailerId
-}
-
-# Output - THROWS FluentValidationError (BEFORE API call)
-FluentValidationError: retailerId is required for Event API
-  code: "VALIDATION_ERROR"
-  statusCode: 400
-```
-
-**SDK Code:**
-```typescript
-// Client WITHOUT retailerId configured
-const client = new FluentClient({
-  baseUrl: 'https://sagirish.test.api.fluentretail.com',
-  clientId: 'SAGIRISH',
-  clientSecret: '...',
-  username: 'module_test_admin',
-  password: '...'
-  // retailerId: undefined ← Not set
-});
-
-try {
-  const result = await client.sendEvent({
-    name: 'TEST.NO_RETAILER',
-    entityType: 'PRODUCT',
-    entityRef: 'NO-RETAILER-TEST'
-    // retailerId: undefined ← Not provided in event
-  }, 'async');
-} catch (error) {
-  // ✅ SDK catches this BEFORE making API call
-  console.error(error.message);
-  // Output: retailerId is required for Event API. Provide it in the event payload or client config.
-}
-```
-
----
-
-## Async vs Sync Mode Comparison
-
-### Async Mode (Default, Recommended)
-
-**Characteristics:**
-- ✅ **Fast response** (event queued, returns immediately)
-- ✅ **Non-blocking** (doesn't wait for Rubix workflow)
-- ✅ **Fire-and-forget** (workflow processes asynchronously)
-- ❌ **No workflow error detection** (returns 200 even if workflow fails later)
-
-**Response Structure:**
-```json
-{
-  "success": true,
-  "statusCode": 200
-}
-```
-
-**Use Case:**
-- High-throughput ingestion (1000s of events)
-- Batch processing workflows
-- Event queueing for later processing
-
----
-
-### Sync Mode (Wait for Workflow)
-
-**Characteristics:**
-- ✅ **Waits for Rubix workflow** (blocks until workflow completes)
-- ✅ **Immediate error detection** (throws if workflow fails)
-- ✅ **Returns workflow result** (status, message)
-- ❌ **Slower response** (waits for workflow execution)
-
-**Response Structure (Success):**
-```json
-{
-  "success": true,
-  "status": "COMPLETED",
-  "statusCode": 201,
-  "message": "Workflow completed successfully"
-}
-```
-
-**Response Structure (Workflow Failure):**
-```typescript
-// THROWS FluentAPIError
-{
-  name: "FluentAPIError",
-  message: "Request failed: 404",
-  statusCode: 404,
-  details: "No workflow rule matched"
-}
-```
-
-**Use Case:**
-- Critical events requiring immediate confirmation
-- Low-volume event processing
-- Testing/debugging workflows
-
----
-
-## SDK Automatic Behaviors (v0.1.40+)
-
-### 1. retailerId Validation
-
-**Timing:** BEFORE API call
-**Behavior:** SDK checks if `event.retailerId` or `client.retailerId` is set
-**If Missing:** Throws `FluentValidationError` immediately
-**Benefit:** Fail-fast, no wasted API calls
-
-```typescript
-// ✅ GOOD: retailerId provided
-await client.sendEvent({ retailerId: '2', ... });
-
-// ✅ GOOD: retailerId configured in client
-const client = new FluentClient({ retailerId: '2', ... });
-await client.sendEvent({ ... }); // Uses client.retailerId
-
-// ❌ BAD: No retailerId anywhere
-await client.sendEvent({ ... }); // Throws BEFORE API call
-```
-
----
-
-### 2. 401 Authentication Retry
-
-**Timing:** On 401 response
-**Behavior:** SDK retries with exponential backoff (3 attempts)
-**Delay:** 1s → 2s → 4s
-**Use Case:** OAuth2 token refresh, platform token rotation
-
-```typescript
-// Scenario: OAuth2 token expired
-await client.sendEvent(event);
-// [WARN] Platform auth failure (401), retrying after 1000ms
-// [INFO] Event sent successfully after retry
-```
-
----
-
-### 3. 5xx Server Error Retry
-
-**Timing:** On 500, 502, 503, 504 responses
-**Behavior:** SDK retries with exponential backoff (3 attempts)
-**Delay:** 1s → 2s → 4s (capped at 10s)
-**Use Case:** Transient API failures, network hiccups
-
-```typescript
-// Scenario: Fluent API temporarily down (503)
-await client.sendEvent(event);
-// [WARN] Request failed, retrying (attempt 1/3)
-// [WARN] Request failed, retrying (attempt 2/3)
-// [INFO] Event sent successfully after retry
-```
-
----
-
-### 4. 4xx Client Error Behavior
-
-**Timing:** On 400, 403, 404, 422 responses (except 401)
-**Behavior:** SDK throws `FluentAPIError` immediately (NO retry)
-**Reason:** Client errors require code/data fixes, not retry
-
-```typescript
-// Scenario: Invalid event name (400)
-try {
-  await client.sendEvent({ name: 'InvalidEvent', ... });
-} catch (error) {
-  // Throws immediately, NO retries
-  console.error(error.statusCode); // 400
-}
-```
-
----
-
-## Error Handling Best Practices
-
-### Pattern 1: Per-Event Error Handling
-
-```typescript
-const results = { success: 0, failed: 0, errors: [] };
-
-for (const record of records) {
-  try {
-    const result = await client.sendEvent({
-      name: 'PRODUCT.UPDATE',
-      entityType: 'PRODUCT',
-      entityRef: record.sku,
-      retailerId: '2',
-      attributes: record
-    });
-
-    results.success++;
-    console.log(`✅ ${record.sku} - statusCode: ${result.statusCode}`);
-  } catch (error) {
-    results.failed++;
-
-    if (error instanceof FluentAPIError) {
-      // SDK already retried 401/5xx - this is non-retryable
-      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}`);
-      break; // Stop processing
-    }
-  }
-}
-
-console.log(`Results: ${results.success} success, ${results.failed} failed`);
-```
-
----
-
-### Pattern 2: Batch Processing with Error Aggregation
-
-```typescript
-interface EventResult {
-  sku: string;
-  success: boolean;
-  statusCode?: number;
-  error?: string;
-}
-
-async function processBatch(products: Product[]): Promise<EventResult[]> {
-  const results: EventResult[] = [];
-
-  for (const product of products) {
-    try {
-      const response = await client.sendEvent({
-        name: 'PRODUCT.UPSERT',
-        entityType: 'PRODUCT',
-        entityRef: product.sku,
-        retailerId: '2',
-        attributes: product
-      });
-
-      results.push({
-        sku: product.sku,
-        success: true,
-        statusCode: response.statusCode
-      });
-    } catch (error) {
-      if (error instanceof FluentAPIError) {
-        results.push({
-          sku: product.sku,
-          success: false,
-          error: `HTTP ${error.statusCode}: ${error.message}`
-        });
-      } else {
-        results.push({
-          sku: product.sku,
-          success: false,
-          error: error.message
-        });
-      }
-    }
-  }
-
-  return results;
-}
-```
-
----
-
-## Summary
-
-### Key Takeaways
-
-1. **statusCode field** (HTTP status code - consistent with error.statusCode)
-   - ✅ Available in all success responses
-   - ✅ Provides HTTP status code (200, 201, 202)
-   - ✅ Available in both FluentClient and FluentVersoriClient
-
-2. **retailerId Validation**
-   - ✅ Validated BEFORE API call (fail-fast)
-   - ✅ Accepts from event payload OR client config
-   - ✅ Clear error message with configuration hints
-
-3. **Automatic Retry**
-   - ✅ 401 errors: 3 retries (OAuth2 token refresh)
-   - ✅ 5xx errors: 3 retries (transient failures)
-   - ❌ 4xx errors: NO retry (client errors)
-
-4. **Structured Errors**
-   - ✅ FluentAPIError with HTTP status
-   - ✅ AuthenticationError for auth failures
-   - ✅ GraphQLExecutionError for GraphQL errors
-
-5. **Async vs Sync**
-   - ✅ Async: Fast, fire-and-forget (default)
-   - ✅ Sync: Waits for workflow, immediate error detection
-
----
-
-## 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)
-- **Batch API Guide**: [fc-connect-sdk/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/batch-api-guide.md](../docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/batch-api-guide.md)
-- **Connection Validation**: [fc-connect-sdk/docs/01-TEMPLATES/versori/patterns/versori-patterns-connection-validation-pattern.md](../docs/01-TEMPLATES/versori/patterns/versori-patterns-connection-validation-pattern.md)
-
----
-
-**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
+# Event API - Input/Output Reference Guide
+
+> **Complete reference** for Event API request/response structures with live examples from sagirish test environment
+
+## 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)
+
+---
+
+## Success Response Structure
+
+### Input: FluentEvent
+
+```typescript
+interface FluentEvent {
+  retailerId: string;          // REQUIRED: Retailer ID (e.g., "2")
+  name: string;                // REQUIRED: Event name (e.g., "OrderCancel1")
+  entityRef: string;           // REQUIRED: Entity reference (e.g., "G_TEST_FC_POSTMAN_34")
+  entityType: string;          // REQUIRED: Entity type (ORDER, PRODUCT, LOCATION, etc.)
+  attributes?: Record<string, any>;  // OPTIONAL: Custom event attributes
+}
+```
+
+### Output: EventResponse (SUCCESS)
+
+```typescript
+interface EventResponse {
+  id?: string;                 // Event ID (if returned by API)
+  success: boolean;            // Always true for successful responses
+  status?: number;             // Event status from Fluent API (CREATED, COMPLETED, etc.)
+  statusCode?: number;         // HTTP status code (200, 201, 202) - Consistent with error.statusCode
+  message?: string;            // Optional message from API
+}
+```
+
+### Live Example: Async Mode Success
+
+**Input:**
+```json
+{
+  "retailerId": "2",
+  "name": "OrderCancel1",
+  "entityRef": "G_TEST_FC_POSTMAN_34",
+  "entityType": "ORDER"
+}
+```
+
+**Output:**
+```json
+{
+  "success": true,
+  "statusCode": 200
+}
+```
+
+**Log Output:**
+```
+[FluentClient:event] Sending event "OrderCancel1" (ORDER:G_TEST_FC_POSTMAN_34, mode: async)
+[FluentClient:event] Event "OrderCancel1" sent successfully (id: undefined, statusCode: 200)
+```
+
+---
+
+### Live Example: Product Event Success
+
+**Input:**
+```json
+{
+  "retailerId": "2",
+  "name": "PRODUCT.UPDATE",
+  "entityRef": "SKU-1763567425",
+  "entityType": "PRODUCT",
+  "attributes": {
+    "test": true,
+    "timestamp": "2025-01-19T05:30:25.500Z"
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "success": true,
+  "statusCode": 200
+}
+```
+
+---
+
+## Error Response Structure
+
+### Output: FluentAPIError (THROWN)
+
+When events fail, the SDK throws structured error objects:
+
+```typescript
+class FluentAPIError extends Error {
+  name: 'FluentAPIError';
+  message: string;              // Error description (e.g., "Request failed: 400")
+  status: number;               // HTTP status code (400, 404, 500, etc.)
+  details?: any;                // Additional error context
+  errors?: Array<any>;          // Validation errors (if applicable)
+}
+```
+
+### Live Example: No Workflow Match (Sync Mode)
+
+**Input:**
+```json
+{
+  "retailerId": "2",
+  "name": "OrderCancel1",
+  "entityRef": "SYNC-1763567424997",
+  "entityType": "ORDER"
+}
+```
+
+**Error Thrown:**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 404",
+  status: 404,
+  details: "No workflow rule matched this event"
+}
+```
+
+**Error Detection Timing:**
+- **Async Mode**: Returns `200` immediately, workflow failures NOT detected
+- **Sync Mode**: Waits for workflow, throws error if workflow fails
+
+---
+
+### Live Example: Invalid Event Name
+
+**Input:**
+```json
+{
+  "retailerId": "2",
+  "name": "OrderCancel",        // ← Event name has no matching workflow
+  "entityRef": "TEST-1763567425-1",
+  "entityType": "ORDER"
+}
+```
+
+**Error Thrown:**
+```typescript
+FluentAPIError {
+  name: "FluentAPIError",
+  message: "Request failed: 400",
+  status: 400,
+  details: "Bad Request - Invalid event configuration"
+}
+```
+
+---
+
+### Live Example: Missing retailerId (SDK Validation)
+
+**Input:**
+```json
+{
+  "name": "TEST.NO_RETAILER",
+  "entityType": "PRODUCT",
+  "entityRef": "NO-RETAILER-TEST"
+  // ❌ Missing retailerId
+}
+```
+
+**Error Thrown:**
+```typescript
+FluentValidationError {
+  name: "FluentValidationError",
+  message: "retailerId is required for Event API. Provide it in the event payload or client config.",
+  code: "VALIDATION_ERROR",
+  statusCode: 400
+}
+```
+
+**Key Difference:**
+- ✅ **SDK catches this BEFORE API call** (no network request made)
+- ✅ **Fail-fast validation** (saves time and reduces API load)
+
+---
+
+## HTTP Status Codes
+
+### Success Codes (2xx)
+
+| Code | Meaning | When | Example Response |
+|------|---------|------|------------------|
+| **200** | OK | Event accepted (async mode) | `{ success: true, statusCode: 200 }` |
+| **201** | Created | Event created (sync mode, workflow completed) | `{ success: true, id: "evt-123", status: "CREATED", statusCode: 201 }` |
+| **202** | Accepted | Event queued for processing | `{ success: true, statusCode: 202 }` |
+
+### Client Error Codes (4xx)
+
+| Code | Meaning | When | SDK Retry | Example |
+|------|---------|------|-----------|---------|
+| **400** | Bad Request | Invalid event payload, no workflow match | ❌ No | Invalid event name |
+| **401** | Unauthorized | Auth token invalid/expired | ✅ Yes (3x) | OAuth2 token refresh |
+| **403** | Forbidden | Permission denied | ❌ No | Insufficient permissions |
+| **404** | Not Found | Sync mode: No workflow matched | ❌ No | No Rubix workflow rule |
+| **422** | Unprocessable | Event validation failed | ❌ No | Invalid entity reference |
+
+### Server Error Codes (5xx)
+
+| Code | Meaning | When | SDK Retry | Example |
+|------|---------|------|-----------|---------|
+| **500** | Internal Server Error | Fluent API error | ✅ Yes (3x) | Workflow execution failure |
+| **502** | Bad Gateway | Gateway timeout | ✅ Yes (3x) | Network issue |
+| **503** | Service Unavailable | API temporarily down | ✅ Yes (3x) | Maintenance window |
+| **504** | Gateway Timeout | Request timeout | ✅ Yes (3x) | Long-running workflow |
+
+---
+
+## Live Examples from Test Environment
+
+### Test Environment Details
+
+```yaml
+Base URL: https://sagirish.test.api.fluentretail.com
+Retailer ID: 2
+Account ID: SAGIRISH
+Client ID: SAGIRISH
+```
+
+### Example 1: Successful Async Event
+
+```bash
+# Input
+POST /api/v4.1/event/async
+{
+  "retailerId": "2",
+  "name": "OrderCancel1",
+  "entityRef": "G_TEST_FC_POSTMAN_34",
+  "entityType": "ORDER"
+}
+
+# Output (HTTP 200)
+{
+  "success": true,
+  "statusCode": 200
+}
+```
+
+**SDK Code:**
+```typescript
+const client = new FluentClient({
+  baseUrl: 'https://sagirish.test.api.fluentretail.com',
+  clientId: 'SAGIRISH',
+  clientSecret: '534901d2-626d-4997-aabd-7600838d83c2',
+  username: 'module_test_admin',
+  password: '89YZBN',
+  retailerId: '2'
+});
+
+const result = await client.sendEvent({
+  name: 'OrderCancel1',
+  entityRef: 'G_TEST_FC_POSTMAN_34',
+  entityType: 'ORDER',
+  retailerId: '2'
+}, 'async');
+
+// result = { success: true, statusCode: 200 }
+```
+
+---
+
+### Example 2: Sync Mode - Workflow Failure
+
+```bash
+# Input
+POST /api/v4.1/event/sync
+{
+  "retailerId": "2",
+  "name": "OrderCancel1",
+  "entityRef": "SYNC-1763567424997",
+  "entityType": "ORDER"
+}
+
+# Output (HTTP 404) - THROWS FluentAPIError
+FluentAPIError: Request failed: 404
+  status: 404
+  message: "No workflow rule matched this event"
+```
+
+**SDK Code:**
+```typescript
+try {
+  const result = await client.sendEvent({
+    name: 'OrderCancel1',
+    entityRef: 'SYNC-1763567424997',
+    entityType: 'ORDER',
+    retailerId: '2'
+  }, 'sync'); // ← Sync mode waits for workflow
+} catch (error) {
+  if (error instanceof FluentAPIError) {
+    console.error(`❌ HTTP ${error.status}: ${error.message}`);
+    // Output: ❌ HTTP 404: Request failed: 404
+  }
+}
+```
+
+---
+
+### Example 3: Product Event with Attributes
+
+```bash
+# Input
+POST /api/v4.1/event/async
+{
+  "retailerId": "2",
+  "name": "PRODUCT.UPDATE",
+  "entityRef": "SKU-1763567425",
+  "entityType": "PRODUCT",
+  "attributes": {
+    "test": true,
+    "timestamp": "2025-01-19T05:30:25.500Z"
+  }
+}
+
+# Output (HTTP 200)
+{
+  "success": true,
+  "statusCode": 200
+}
+```
+
+**SDK Code:**
+```typescript
+const result = await client.sendEvent({
+  name: 'PRODUCT.UPDATE',
+  entityRef: 'SKU-1763567425',
+  entityType: 'PRODUCT',
+  retailerId: '2',
+  attributes: {
+    test: true,
+    timestamp: new Date().toISOString()
+  }
+}, 'async');
+
+// result = { success: true, statusCode: 200 }
+```
+
+---
+
+### Example 4: Invalid Event Name (400 Error)
+
+```bash
+# Input
+POST /api/v4.1/event/async
+{
+  "retailerId": "2",
+  "name": "OrderCancel",  # ← No workflow configured for this event
+  "entityRef": "TEST-1763567425-1",
+  "entityType": "ORDER"
+}
+
+# Output (HTTP 400) - THROWS FluentAPIError
+FluentAPIError: Request failed: 400
+  status: 400
+  message: "Bad Request"
+```
+
+**SDK Code:**
+```typescript
+try {
+  const result = await client.sendEvent({
+    name: 'OrderCancel', // ← Invalid/unconfigured event name
+    entityRef: 'TEST-1763567425-1',
+    entityType: 'ORDER',
+    retailerId: '2'
+  }, 'async');
+} catch (error) {
+  if (error instanceof FluentAPIError) {
+    console.error(`❌ HTTP ${error.status}: ${error.message}`);
+    // Output: ❌ HTTP 400: Request failed: 400
+    // SDK does NOT retry 4xx errors (client error, not transient)
+  }
+}
+```
+
+---
+
+### Example 5: Missing retailerId (SDK Validation)
+
+```bash
+# No API call made! SDK validates BEFORE calling API
+
+# Input
+{
+  "name": "TEST.NO_RETAILER",
+  "entityType": "PRODUCT",
+  "entityRef": "NO-RETAILER-TEST"
+  # ❌ Missing retailerId
+}
+
+# Output - THROWS FluentValidationError (BEFORE API call)
+FluentValidationError: retailerId is required for Event API
+  code: "VALIDATION_ERROR"
+  statusCode: 400
+```
+
+**SDK Code:**
+```typescript
+// Client WITHOUT retailerId configured
+const client = new FluentClient({
+  baseUrl: 'https://sagirish.test.api.fluentretail.com',
+  clientId: 'SAGIRISH',
+  clientSecret: '...',
+  username: 'module_test_admin',
+  password: '...'
+  // retailerId: undefined ← Not set
+});
+
+try {
+  const result = await client.sendEvent({
+    name: 'TEST.NO_RETAILER',
+    entityType: 'PRODUCT',
+    entityRef: 'NO-RETAILER-TEST'
+    // retailerId: undefined ← Not provided in event
+  }, 'async');
+} catch (error) {
+  // ✅ SDK catches this BEFORE making API call
+  console.error(error.message);
+  // Output: retailerId is required for Event API. Provide it in the event payload or client config.
+}
+```
+
+---
+
+## Async vs Sync Mode Comparison
+
+### Async Mode (Default, Recommended)
+
+**Characteristics:**
+- ✅ **Fast response** (event queued, returns immediately)
+- ✅ **Non-blocking** (doesn't wait for Rubix workflow)
+- ✅ **Fire-and-forget** (workflow processes asynchronously)
+- ❌ **No workflow error detection** (returns 200 even if workflow fails later)
+
+**Response Structure:**
+```json
+{
+  "success": true,
+  "statusCode": 200
+}
+```
+
+**Use Case:**
+- High-throughput ingestion (1000s of events)
+- Batch processing workflows
+- Event queueing for later processing
+
+---
+
+### Sync Mode (Wait for Workflow)
+
+**Characteristics:**
+- ✅ **Waits for Rubix workflow** (blocks until workflow completes)
+- ✅ **Immediate error detection** (throws if workflow fails)
+- ✅ **Returns workflow result** (status, message)
+- ❌ **Slower response** (waits for workflow execution)
+
+**Response Structure (Success):**
+```json
+{
+  "success": true,
+  "status": "COMPLETED",
+  "statusCode": 201,
+  "message": "Workflow completed successfully"
+}
+```
+
+**Response Structure (Workflow Failure):**
+```typescript
+// THROWS FluentAPIError
+{
+  name: "FluentAPIError",
+  message: "Request failed: 404",
+  status: 404,
+  details: "No workflow rule matched"
+}
+```
+
+**Use Case:**
+- Critical events requiring immediate confirmation
+- Low-volume event processing
+- Testing/debugging workflows
+
+---
+
+## SDK Automatic Behaviors (v0.1.40+)
+
+### 1. retailerId Validation
+
+**Timing:** BEFORE API call
+**Behavior:** SDK checks if `event.retailerId` or `client.retailerId` is set
+**If Missing:** Throws `FluentValidationError` immediately
+**Benefit:** Fail-fast, no wasted API calls
+
+```typescript
+// ✅ GOOD: retailerId provided
+await client.sendEvent({ retailerId: '2', ... });
+
+// ✅ GOOD: retailerId configured in client
+const client = new FluentClient({ retailerId: '2', ... });
+await client.sendEvent({ ... }); // Uses client.retailerId
+
+// ❌ BAD: No retailerId anywhere
+await client.sendEvent({ ... }); // Throws BEFORE API call
+```
+
+---
+
+### 2. 401 Authentication Retry
+
+**Timing:** On 401 response
+**Behavior:** SDK retries with exponential backoff (3 attempts)
+**Delay:** 1s → 2s → 4s
+**Use Case:** OAuth2 token refresh, platform token rotation
+
+```typescript
+// Scenario: OAuth2 token expired
+await client.sendEvent(event);
+// [WARN] Platform auth failure (401), retrying after 1000ms
+// [INFO] Event sent successfully after retry
+```
+
+---
+
+### 3. 5xx Server Error Retry
+
+**Timing:** On 500, 502, 503, 504 responses
+**Behavior:** SDK retries with exponential backoff (3 attempts)
+**Delay:** 1s → 2s → 4s (capped at 10s)
+**Use Case:** Transient API failures, network hiccups
+
+```typescript
+// Scenario: Fluent API temporarily down (503)
+await client.sendEvent(event);
+// [WARN] Request failed, retrying (attempt 1/3)
+// [WARN] Request failed, retrying (attempt 2/3)
+// [INFO] Event sent successfully after retry
+```
+
+---
+
+### 4. 4xx Client Error Behavior
+
+**Timing:** On 400, 403, 404, 422 responses (except 401)
+**Behavior:** SDK throws `FluentAPIError` immediately (NO retry)
+**Reason:** Client errors require code/data fixes, not retry
+
+```typescript
+// Scenario: Invalid event name (400)
+try {
+  await client.sendEvent({ name: 'InvalidEvent', ... });
+} catch (error) {
+  // Throws immediately, NO retries
+  console.error(error.status); // 400
+}
+```
+
+---
+
+## Error Handling Best Practices
+
+### Pattern 1: Per-Event Error Handling
+
+```typescript
+const results = { success: 0, failed: 0, errors: [] };
+
+for (const record of records) {
+  try {
+    const result = await client.sendEvent({
+      name: 'PRODUCT.UPDATE',
+      entityType: 'PRODUCT',
+      entityRef: record.sku,
+      retailerId: '2',
+      attributes: record
+    });
+
+    results.success++;
+    console.log(`✅ ${record.sku} - statusCode: ${result.statusCode}`);
+  } catch (error) {
+    results.failed++;
+
+    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 });
+    } else if (error instanceof AuthenticationError) {
+      // Auth failed after 3 retries - credentials issue
+      console.error(`❌ Auth failure: ${error.message}`);
+      break; // Stop processing
+    }
+  }
+}
+
+console.log(`Results: ${results.success} success, ${results.failed} failed`);
+```
+
+---
+
+### Pattern 2: Batch Processing with Error Aggregation
+
+```typescript
+interface EventResult {
+  sku: string;
+  success: boolean;
+  statusCode?: number;
+  error?: string;
+}
+
+async function processBatch(products: Product[]): Promise<EventResult[]> {
+  const results: EventResult[] = [];
+
+  for (const product of products) {
+    try {
+      const response = await client.sendEvent({
+        name: 'PRODUCT.UPSERT',
+        entityType: 'PRODUCT',
+        entityRef: product.sku,
+        retailerId: '2',
+        attributes: product
+      });
+
+      results.push({
+        sku: product.sku,
+        success: true,
+        statusCode: response.statusCode
+      });
+    } catch (error) {
+      if (error instanceof FluentAPIError) {
+        results.push({
+          sku: product.sku,
+          success: false,
+          error: `HTTP ${error.status}: ${error.message}`
+        });
+      } else {
+        results.push({
+          sku: product.sku,
+          success: false,
+          error: error.message
+        });
+      }
+    }
+  }
+
+  return results;
+}
+```
+
+---
+
+## Summary
+
+### Key Takeaways
+
+1. **statusCode field** (HTTP status code - consistent with error.statusCode)
+   - ✅ Available in all success responses
+   - ✅ Provides HTTP status code (200, 201, 202)
+   - ✅ Available in both FluentClient and FluentVersoriClient
+
+2. **retailerId Validation**
+   - ✅ Validated BEFORE API call (fail-fast)
+   - ✅ Accepts from event payload OR client config
+   - ✅ Clear error message with configuration hints
+
+3. **Automatic Retry**
+   - ✅ 401 errors: 3 retries (OAuth2 token refresh)
+   - ✅ 5xx errors: 3 retries (transient failures)
+   - ❌ 4xx errors: NO retry (client errors)
+
+4. **Structured Errors**
+   - ✅ FluentAPIError with HTTP status
+   - ✅ AuthenticationError for auth failures
+   - ✅ GraphQLExecutionError for GraphQL errors
+
+5. **Async vs Sync**
+   - ✅ Async: Fast, fire-and-forget (default)
+   - ✅ Sync: Waits for workflow, immediate error detection
+
+---
+
+## 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)
+- **Batch API Guide**: [fc-connect-sdk/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/batch-api-guide.md](../docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/batch-api-guide.md)
+- **Connection Validation**: [fc-connect-sdk/docs/01-TEMPLATES/versori/patterns/versori-patterns-connection-validation-pattern.md](../docs/01-TEMPLATES/versori/patterns/versori-patterns-connection-validation-pattern.md)
+
+---
+
+**Generated from live test environment**: sagirish.test.api.fluentretail.com
+**SDK Version**: 0.1.46
+**Test Date**: 2025-01-19