@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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

@@ -1,520 +1,399 @@
-# Module 1: Client API
-
-**Level:** Beginner
-**Category:** Core
-
-## Overview
-
-The FluentClient is the main entry point for interacting with Fluent Commerce APIs. This module covers client creation, configuration, and all primary operations including GraphQL queries/mutations, event handling, and batch processing.
-
-## Table of Contents
-
-- [Client Creation](#client-creation)
-- [GraphQL Operations](#graphql-operations)
-- [Event Operations](#event-operations)
-- [Job & Batch Operations](#job-batch-operations)
-- [See Also](#see-also)
-
----
-
-## FluentClient
-
-The main client for interacting with Fluent Commerce APIs.
-
-### Client Creation
-
-#### createClient Function
-
-Universal factory function that auto-detects the runtime environment.
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Node.js environment with OAuth2
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: 'your-client-id',
-    clientSecret: 'your-client-secret',
-    username: 'your-username', // Optional - for password grant
-    password: 'your-password', // Optional - for password grant
-  },
-});
-
-// retailerId is optional on client config, but required in createJob payload or set via client.setRetailerId() beforehand
-client.setRetailerId('your-retailer-id');
-
-// Versori platform
-const client = await createClient(ctx);
-```
-
-**Parameters:**
-
-- `config: FluentClientConfig | VersoriContext` - Configuration object or Versori context
-
-**Returns:**
-
-- `Promise<FluentClient>` - Configured client instance
-
-#### createClientFromProfile Function (Fluent CLI Integration)
-
-Create a standalone `FluentClient` from an existing Fluent CLI profile in `~/.fluentcommerce`.
-
-```typescript
-import { createClientFromProfile } from '@fluentcommerce/fc-connect-sdk';
-
-// Simple profile
-const client = await createClientFromProfile('PROFILE_ALPHA');
-
-// Multi-retailer profile
-const retailerClient = await createClientFromProfile('PROFILE_BETA', {
-  retailer: 'RETAILER_ALPHA',
-  validateConnection: true, // Optional fail-fast auth check
-});
-```
-
-**Parameters:**
-
-- `profileName: string` - Fluent CLI profile directory name
-- `options?: FluentProfileOptions & CreateClientOptions`
-  - `profileDir?: string` - Override profile base directory (default: `~/.fluentcommerce`)
-  - `retailer?: string` - Retailer ref to load `retailer.<REF>.json` (retailer ID + user override)
-  - `timeout?: number` - Override request timeout
-  - `retryConfig?: RetryConfig` - Override retry behavior
-  - `validateConnection?: boolean` - Validate auth immediately using `query { me { ref } }`
-
-**Returns:**
-
-- `Promise<FluentClient>` - Standalone OAuth2 client built from profile credentials
-
-**Behavior Notes:**
-
-- Loads in this order: `profile.json` → optional `retailer.<REF>.json` → `user.<name>.json`
-- When `retailer` is provided, retailer-specific `user` override is respected
-- Throws explicit errors for missing profile/user/retailer files
-- For Versori runtime, use `createClient(ctx)` instead of profile-based loading
-
-#### FluentClientConfig Interface
-
-```typescript
-interface FluentClientConfig {
-  baseUrl: string; // API endpoint
-  retailerId?: string; // Optional - only required for Job/Batch operations
-  clientId?: string; // OAuth2 client ID (required)
-  clientSecret?: string; // OAuth2 client secret (required)
-  username?: string; // OAuth2 username (optional - for password grant)
-  password?: string; // OAuth2 password (optional - for password grant)
-  timeout?: number; // Request timeout (ms)
-  retryAttempts?: number; // Retry count
-  retryDelay?: number; // Retry delay (ms)
-  /**
-   * Retry configuration with sensible defaults
-   * Override specific values as needed for fine-grained control
-   */
-  retryConfig?: {
-    /** Maximum number of retry attempts for general requests (default: 3) */
-    maxRetries?: number;
-    /** Maximum number of retry attempts for authentication failures (default: 3) */
-    maxAuthRetries?: number;
-    /** Base delay in milliseconds before first retry (default: 1000) */
-    baseRetryDelayMs?: number;
-    /** Maximum delay in milliseconds for general retries (default: 10000) */
-    maxRetryDelayMs?: number;
-    /** Maximum delay in milliseconds for authentication retries (default: 5000) */
-    maxAuthRetryDelayMs?: number;
-    /** Token expiry buffer in seconds (default: 60) */
-    tokenExpiryBufferSeconds?: number;
-  };
-}
-```
-
-**Note**: Logger is passed at the context level when calling `createClient({ config, logger })`, not inside the config object.
-
-### GraphQL Operations
-
-#### graphql Method
-
-Execute a GraphQL query or mutation. Auto-detects operation type.
-
-```typescript
-async graphql<T = JsonValue>(payload: GraphQLPayload): Promise<GraphQLResponse<T>>
-
-interface GraphQLPayload<T = Record<string, JsonValue>> {
-  query: string;                      // GraphQL query or mutation string
-  variables?: T;                      // Query/mutation variables (typed)
-  operationName?: string;             // Optional operation name
-  pagination?: PaginationConfig;      // Optional auto-pagination config
-}
-```
-
-**Parameters:**
-
-- `payload.query` - GraphQL query or mutation string
-- `payload.variables` - Optional query/mutation variables
-- `payload.pagination` - Optional auto-pagination configuration
-
-**Returns:**
-
-- `GraphQLResponse<T>` with data, errors, and extensions
-
-**Example:**
-
-```typescript
-// Execute query
-const result = await client.graphql({
-  query: `
-    query GetProducts($first: Int) {
-      products(first: $first) {
-        edges { node { id ref name } }
-      }
-    }
-  `,
-  variables: { first: 10 },
-});
-
-// Execute mutation (same method)
-const result = await client.graphql({
-  query: `
-    mutation UpdateProduct($input: UpdateProductInput!) {
-      updateProduct(input: $input) {
-        id ref name
-      }
-    }
-  `,
-  variables: { input: { id: '123', name: 'Updated Product' } },
-});
-
-// With auto-pagination (forward pagination with cursor)
-const result = await client.graphql({
-  query: `
-    query Products($first: Int!, $after: String) {
-      products(first: $first, after: $after) {
-        edges {
-          node { id ref name }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-          hasPreviousPage
-        }
-      }
-    }
-  `,
-  variables: { first: 50 },  // Page size
-  pagination: {
-    enabled: true,
-    maxPages: 10,        // Fetch up to 10 pages (500 records)
-    maxRecords: 1000,    // Or stop at 1000 records
-    delayMs: 100,        // Wait 100ms between pages
-  },
-});
-```
-
-> **Pagination Notes:**
-> - Forward pagination (default): Uses `$first`/`$after` with `pageInfo.hasNextPage`
-> - Backward pagination: Uses `$last`/`$before` with `pageInfo.hasPreviousPage` (set `pagination.direction='backward'`)
-> - SDK automatically injects cursor values - do NOT include pagination variables in `variables` object
-> - Always request `cursor` in `edges` and `pageInfo { hasNextPage hasPreviousPage }` in your query
-
-#### query Helper Method
-
-Convenience method that calls `graphql()` and returns just the data field.
-
-```typescript
-async query<T = JsonValue>(
-  queryOrPayload: string | GraphQLPayload,
-  variables?: Record<string, JsonValue>
-): Promise<T | undefined>
-```
-
-**Example:**
-
-```typescript
-// Using string query
-const orders = await client.graphql<{ orders: Order[] }>({
-  query: 'query { orders { id ref } }',
-  variables: {
-    status: 'ACTIVE',
-  },
-});
-
-// Using GraphQLPayload
-const orders = await client.graphql({
-  query: 'query ($status: String) { orders(status: $status) { id ref } }',
-  variables: { status: 'ACTIVE' },
-});
-```
-
-#### mutate Helper Method
-
-Convenience method that calls `graphql()` and returns just the data field.
-
-```typescript
-async mutate<T = JsonValue>(
-  mutationOrPayload: string | GraphQLPayload,
-  variables?: Record<string, JsonValue>
-): Promise<T | undefined>
-```
-
-**Example:**
-
-```typescript
-// Using string mutation
-const result = await client.graphql<{ createOrder: { id: string } }>({
-  query: 'mutation { createOrder(input: { ref: "123" }) { id } }',
-});
-
-// Using GraphQLPayload
-const result = await client.graphql({
-  query: 'mutation ($input: CreateOrderInput!) { createOrder(input: $input) { id } }',
-  variables: { input: { ref: '123' } },
-});
-```
-
-### Event Operations
-
-#### sendEvent Method
-
-Send an event to Fluent Commerce.
-
-```typescript
-async sendEvent(event: FluentEvent, mode: FluentEventMode = 'async'): Promise<JsonValue>
-
-type FluentEventMode = 'async' | 'sync';
-```
-
-#### Webhook Signature Validation (Fluent Rubix only)
-
-> Note: This validation applies only to webhooks sent from Fluent Commerce Rubix workflows.
-
-```typescript
-import { WebhookValidationService, SignatureAlgorithm } from '@fluentcommerce/fc-connect-sdk';
-
-const validator = new WebhookValidationService(
-  { algorithm: SignatureAlgorithm.SHA512_WITH_RSA, strictValidation: true },
-  logger
-);
-
-const result = await validator.validateWebhookSignature(
-  JSON.stringify(requestBody),
-  headers['fluent-signature'],
-  process.env.FLUENT_WEBHOOK_PUBLIC_KEY!,
-  SignatureAlgorithm.SHA512_WITH_RSA
-);
-
-if (!result.isValid) throw new Error('Invalid Fluent webhook signature');
-```
-
-**Parameters:**
-
-- `event` - Event payload (FluentEvent object)
-- `mode` - Event mode: 'async' (default) or 'sync'
-
-**Returns:**
-
-- Event response data
-
-**FluentEvent Interface:**
-
-```typescript
-interface FluentEvent {
-  name: string; // Event name
-  retailerId: string; // Retailer ID
-  entityType: string; // Entity type
-  entityRef?: string; // Entity reference
-  entityId?: string; // Entity ID
-  rootEntityType?: string; // Root entity type
-  rootEntityRef?: string; // Root entity reference
-  rootEntityId?: string; // Root entity ID
-  attributes?: Record<string, any>; // Event attributes
-}
-```
-
-**Example:**
-
-```typescript
-const event = await client.sendEvent(
-  {
-    name: 'INVENTORY.UPDATED',
-    retailerId: 'retailer-123',
-    entityType: 'InventoryPosition',
-    entityRef: 'SKU-001',
-    attributes: {
-      quantity: 100,
-      location: 'DC-001',
-    },
-  },
-  'async'
-);
-```
-
-#### 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
-
-Create a new job for batch processing.
-
-```typescript
-const job = await client.createJob(
-  payload: FluentJobPayload
-): Promise<FluentJob>
-```
-
-**FluentJobPayload Interface:**
-
-```typescript
-interface FluentJobPayload {
-  name: string; // Job name
-  retailerId: string; // Retailer ID (required)
-  meta?: Record<string, any>; // Job metadata (optional)
-}
-```
-
-#### sendBatch Method
-
-Send batch data to a job.
-
-```typescript
-const batch = await client.sendBatch(
-  jobId: string,
-  payload: FluentBatchPayload
-): Promise<FluentBatch>
-```
-
-**FluentBatchPayload Interface:**
-
-```typescript
-interface FluentBatchPayload {
-  action: string;         // Batch action (typically 'UPSERT')
-  entityType: string;     // Entity type (e.g., 'INVENTORY', 'PRODUCT')
-  source?: string;        // REQUIRED: Source system identifier (e.g., 'CSV_IMPORT', 'SFTP_FEED')
-  event?: string;         // REQUIRED: Event identifier (e.g., 'INVENTORY_UPDATE', 'PRODUCT_SYNC')
-  catalogueRef?: string;  // Optional catalogue reference
-  conditions?: {          // Optional filtering conditions
-    hasRelatedInventoryQuantities?: Array<{
-      type: string;
-      status: string;
-    }>;
-  };
-  entities: any[];        // Entity data array
-}
-```
-
-**IMPORTANT:** While `source` and `event` are marked as optional in the TypeScript interface, they are **REQUIRED** by the Fluent API. Always include them in your batch payloads.
-
-**Example:**
-
-```typescript
-// Create job
-const job = await client.createJob({
-  name: 'My Job',
-  retailerId: 'your-retailer-id',
-});
-
-// Send batch - source and event are REQUIRED
-const batch = await client.sendBatch(job.id, {
-  action: BatchAction.UPSERT,
-  entityType: EntityType.INVENTORY,
-  source: 'S3_CSV_IMPORT',       // REQUIRED: Source system identifier
-  event: 'INVENTORY_UPDATE',     // REQUIRED: Event identifier
-  entities: [
-    { ref: 'SKU-001', qty: 100, locationRef: 'DC-001' },
-    { ref: 'SKU-002', qty: 50, locationRef: 'DC-001' },
-  ],
-});
-```
-
-## See Also
-
-- [Module 3: Authentication](./api-reference-03-authentication.md) - OAuth2 and auth providers
-- [Module 4: GraphQL Mapping](./api-reference-04-graphql-mapping.md) - GraphQL mutation mapping
-- [Module 5: Services](./api-reference-05-services.md) - Core SDK services
-- [Module 8: Types](./api-reference-08-types.md) - Complete type definitions
-- [Examples: Client Initialization](../examples/client-initialization.ts)
-
----
-
-**[← API Reference Home](../api-reference-readme.md)** | **[Next: Authentication →](./api-reference-03-authentication.md)**
+# Module 1: Client API
+
+**Level:** Beginner
+**Category:** Core
+
+## Overview
+
+The FluentClient is the main entry point for interacting with Fluent Commerce APIs. This module covers client creation, configuration, and all primary operations including GraphQL queries/mutations, event handling, and batch processing.
+
+## Table of Contents
+
+- [Client Creation](#client-creation)
+- [GraphQL Operations](#graphql-operations)
+- [Event Operations](#event-operations)
+- [Job & Batch Operations](#job-batch-operations)
+- [See Also](#see-also)
+
+---
+
+## FluentClient
+
+The main client for interacting with Fluent Commerce APIs.
+
+### Client Creation
+
+#### createClient Function
+
+Universal factory function that auto-detects the runtime environment.
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Node.js environment with OAuth2
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    username: 'your-username', // Optional - for password grant
+    password: 'your-password', // Optional - for password grant
+  },
+});
+
+// retailerId is optional on client config, but required in createJob payload or set via client.setRetailerId() beforehand
+client.setRetailerId('your-retailer-id');
+
+// Versori platform
+const client = await createClient(ctx);
+```
+
+**Parameters:**
+
+- `config: FluentClientConfig | VersoriContext` - Configuration object or Versori context
+
+**Returns:**
+
+- `Promise<FluentClient>` - Configured client instance
+
+#### FluentClientConfig Interface
+
+```typescript
+interface FluentClientConfig {
+  baseUrl: string; // API endpoint
+  retailerId?: string; // Optional - only required for Job/Batch operations
+  clientId?: string; // OAuth2 client ID (required)
+  clientSecret?: string; // OAuth2 client secret (required)
+  username?: string; // OAuth2 username (optional - for password grant)
+  password?: string; // OAuth2 password (optional - for password grant)
+  timeout?: number; // Request timeout (ms)
+  retryAttempts?: number; // Retry count
+  retryDelay?: number; // Retry delay (ms)
+  /**
+   * Retry configuration with sensible defaults
+   * Override specific values as needed for fine-grained control
+   */
+  retryConfig?: {
+    /** Maximum number of retry attempts for general requests (default: 3) */
+    maxRetries?: number;
+    /** Maximum number of retry attempts for authentication failures (default: 3) */
+    maxAuthRetries?: number;
+    /** Base delay in milliseconds before first retry (default: 1000) */
+    baseRetryDelayMs?: number;
+    /** Maximum delay in milliseconds for general retries (default: 10000) */
+    maxRetryDelayMs?: number;
+    /** Maximum delay in milliseconds for authentication retries (default: 5000) */
+    maxAuthRetryDelayMs?: number;
+    /** Token expiry buffer in seconds (default: 60) */
+    tokenExpiryBufferSeconds?: number;
+  };
+}
+```
+
+**Note**: Logger is passed at the context level when calling `createClient({ config, logger })`, not inside the config object.
+
+### GraphQL Operations
+
+#### graphql Method
+
+Execute a GraphQL query or mutation. Auto-detects operation type.
+
+```typescript
+async graphql<T = JsonValue>(payload: GraphQLPayload): Promise<GraphQLResponse<T>>
+
+interface GraphQLPayload<T = Record<string, JsonValue>> {
+  query: string;                      // GraphQL query or mutation string
+  variables?: T;                      // Query/mutation variables (typed)
+  operationName?: string;             // Optional operation name
+  pagination?: PaginationConfig;      // Optional auto-pagination config
+}
+```
+
+**Parameters:**
+
+- `payload.query` - GraphQL query or mutation string
+- `payload.variables` - Optional query/mutation variables
+- `payload.pagination` - Optional auto-pagination configuration
+
+**Returns:**
+
+- `GraphQLResponse<T>` with data, errors, and extensions
+
+**Example:**
+
+```typescript
+// Execute query
+const result = await client.graphql({
+  query: `
+    query GetProducts($first: Int) {
+      products(first: $first) {
+        edges { node { id ref name } }
+      }
+    }
+  `,
+  variables: { first: 10 },
+});
+
+// Execute mutation (same method)
+const result = await client.graphql({
+  query: `
+    mutation UpdateProduct($input: UpdateProductInput!) {
+      updateProduct(input: $input) {
+        id ref name
+      }
+    }
+  `,
+  variables: { input: { id: '123', name: 'Updated Product' } },
+});
+
+// With auto-pagination (forward pagination with cursor)
+const result = await client.graphql({
+  query: `
+    query Products($first: Int!, $after: String) {
+      products(first: $first, after: $after) {
+        edges {
+          node { id ref name }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+          hasPreviousPage
+        }
+      }
+    }
+  `,
+  variables: { first: 50 },  // Page size
+  pagination: {
+    enabled: true,
+    maxPages: 10,        // Fetch up to 10 pages (500 records)
+    maxRecords: 1000,    // Or stop at 1000 records
+    delayMs: 100,        // Wait 100ms between pages
+  },
+});
+```
+
+> **Pagination Notes:**
+> - Forward pagination (default): Uses `$first`/`$after` with `pageInfo.hasNextPage`
+> - Backward pagination: Uses `$last`/`$before` with `pageInfo.hasPreviousPage` (set `pagination.direction='backward'`)
+> - SDK automatically injects cursor values - do NOT include pagination variables in `variables` object
+> - Always request `cursor` in `edges` and `pageInfo { hasNextPage hasPreviousPage }` in your query
+
+#### query Helper Method
+
+Convenience method that calls `graphql()` and returns just the data field.
+
+```typescript
+async query<T = JsonValue>(
+  queryOrPayload: string | GraphQLPayload,
+  variables?: Record<string, JsonValue>
+): Promise<T | undefined>
+```
+
+**Example:**
+
+```typescript
+// Using string query
+const orders = await client.graphql<{ orders: Order[] }>({
+  query: 'query { orders { id ref } }',
+  variables: {
+    status: 'ACTIVE',
+  },
+});
+
+// Using GraphQLPayload
+const orders = await client.graphql({
+  query: 'query ($status: String) { orders(status: $status) { id ref } }',
+  variables: { status: 'ACTIVE' },
+});
+```
+
+#### mutate Helper Method
+
+Convenience method that calls `graphql()` and returns just the data field.
+
+```typescript
+async mutate<T = JsonValue>(
+  mutationOrPayload: string | GraphQLPayload,
+  variables?: Record<string, JsonValue>
+): Promise<T | undefined>
+```
+
+**Example:**
+
+```typescript
+// Using string mutation
+const result = await client.graphql<{ createOrder: { id: string } }>({
+  query: 'mutation { createOrder(input: { ref: "123" }) { id } }',
+});
+
+// Using GraphQLPayload
+const result = await client.graphql({
+  query: 'mutation ($input: CreateOrderInput!) { createOrder(input: $input) { id } }',
+  variables: { input: { ref: '123' } },
+});
+```
+
+### Event Operations
+
+#### sendEvent Method
+
+Send an event to Fluent Commerce.
+
+```typescript
+async sendEvent(event: FluentEvent, mode: FluentEventMode = 'async'): Promise<JsonValue>
+
+type FluentEventMode = 'async' | 'sync';
+```
+
+#### Webhook Signature Validation (Fluent Rubix only)
+
+> Note: This validation applies only to webhooks sent from Fluent Commerce Rubix workflows.
+
+```typescript
+import { WebhookValidationService, SignatureAlgorithm } from '@fluentcommerce/fc-connect-sdk';
+
+const validator = new WebhookValidationService(
+  { algorithm: SignatureAlgorithm.SHA512_WITH_RSA, strictValidation: true },
+  logger
+);
+
+const result = await validator.validateWebhookSignature(
+  JSON.stringify(requestBody),
+  headers['fluent-signature'],
+  process.env.FLUENT_WEBHOOK_PUBLIC_KEY!,
+  SignatureAlgorithm.SHA512_WITH_RSA
+);
+
+if (!result.isValid) throw new Error('Invalid Fluent webhook signature');
+```
+
+**Parameters:**
+
+- `event` - Event payload (FluentEvent object)
+- `mode` - Event mode: 'async' (default) or 'sync'
+
+**Returns:**
+
+- Event response data
+
+**FluentEvent Interface:**
+
+```typescript
+interface FluentEvent {
+  name: string; // Event name
+  retailerId: string; // Retailer ID
+  entityType: string; // Entity type
+  entityRef?: string; // Entity reference
+  entityId?: string; // Entity ID
+  rootEntityType?: string; // Root entity type
+  rootEntityRef?: string; // Root entity reference
+  rootEntityId?: string; // Root entity ID
+  attributes?: Record<string, any>; // Event attributes
+}
+```
+
+**Example:**
+
+```typescript
+const event = await client.sendEvent(
+  {
+    name: 'INVENTORY.UPDATED',
+    retailerId: 'retailer-123',
+    entityType: 'InventoryPosition',
+    entityRef: 'SKU-001',
+    attributes: {
+      quantity: 100,
+      location: 'DC-001',
+    },
+  },
+  'async'
+);
+```
+
+### Job & Batch Operations
+
+#### createJob Method
+
+Create a new job for batch processing.
+
+```typescript
+const job = await client.createJob(
+  payload: FluentJobPayload
+): Promise<FluentJob>
+```
+
+**FluentJobPayload Interface:**
+
+```typescript
+interface FluentJobPayload {
+  name: string; // Job name
+  retailerId: string; // Retailer ID (required)
+  meta?: Record<string, any>; // Job metadata (optional)
+}
+```
+
+#### sendBatch Method
+
+Send batch data to a job.
+
+```typescript
+const batch = await client.sendBatch(
+  jobId: string,
+  payload: FluentBatchPayload
+): Promise<FluentBatch>
+```
+
+**FluentBatchPayload Interface:**
+
+```typescript
+interface FluentBatchPayload {
+  action: string;         // Batch action (typically 'UPSERT')
+  entityType: string;     // Entity type (e.g., 'INVENTORY', 'PRODUCT')
+  source?: string;        // REQUIRED: Source system identifier (e.g., 'CSV_IMPORT', 'SFTP_FEED')
+  event?: string;         // REQUIRED: Event identifier (e.g., 'INVENTORY_UPDATE', 'PRODUCT_SYNC')
+  catalogueRef?: string;  // Optional catalogue reference
+  conditions?: {          // Optional filtering conditions
+    hasRelatedInventoryQuantities?: Array<{
+      type: string;
+      status: string;
+    }>;
+  };
+  entities: any[];        // Entity data array
+}
+```
+
+**IMPORTANT:** While `source` and `event` are marked as optional in the TypeScript interface, they are **REQUIRED** by the Fluent API. Always include them in your batch payloads.
+
+**Example:**
+
+```typescript
+// Create job
+const job = await client.createJob({
+  name: 'My Job',
+  retailerId: 'your-retailer-id',
+});
+
+// Send batch - source and event are REQUIRED
+const batch = await client.sendBatch(job.id, {
+  action: BatchAction.UPSERT,
+  entityType: EntityType.INVENTORY,
+  source: 'S3_CSV_IMPORT',       // REQUIRED: Source system identifier
+  event: 'INVENTORY_UPDATE',     // REQUIRED: Event identifier
+  entities: [
+    { ref: 'SKU-001', qty: 100, locationRef: 'DC-001' },
+    { ref: 'SKU-002', qty: 50, locationRef: 'DC-001' },
+  ],
+});
+```
+
+## See Also
+
+- [Module 3: Authentication](./api-reference-03-authentication.md) - OAuth2 and auth providers
+- [Module 4: GraphQL Mapping](./api-reference-04-graphql-mapping.md) - GraphQL mutation mapping
+- [Module 5: Services](./api-reference-05-services.md) - Core SDK services
+- [Module 8: Types](./api-reference-08-types.md) - Complete type definitions
+- [Examples: Client Initialization](../examples/client-initialization.ts)
+
+---
+
+**[← API Reference Home](../api-reference-readme.md)** | **[Next: Authentication →](./api-reference-03-authentication.md)**