@fluentcommerce/fc-connect-sdk 0.1.51 → 0.1.53

package/README.md

@@ -147,6 +147,7 @@ Choose the right Fluent Commerce API for your use case:
 | **Location setup** (stores, warehouses) | **Event API** | `sendEvent()` | Requires workflow orchestration |
 | **Order creation** (one-time orders) | **GraphQL** | `client.graphql()` with `createOrder` mutation | Triggers Order CREATED event, full control |
 | **Order updates/events** (status changes) | **Event API** | `sendEvent()` | Triggers workflows for order state changes |
+| **Audit/search event history** (trace flows, investigate failures) | **Event API (GET)** | `getEvents()` + `getEventById()` | Read-only event/audit retrieval with filters and pagination |
 | **Customer data** (registration, profiles) | **GraphQL** | `client.graphql()` with mutations | No Rubix workflow support for customers |
 | **Data extraction** (export to S3/SFTP) | **GraphQL** | `client.graphql()` + `ExtractionOrchestrator` | Query with auto-pagination, extract thousands of records |
 | **Single operations** (create one product, update one location) | **GraphQL** | `client.graphql()` | Direct control, immediate feedback |
@@ -1217,6 +1218,232 @@ console.log('✅ Event sent successfully');
 - **Event API Templates:** `docs/01-TEMPLATES/versori/workflows/ingestion/event-api/` (8 templates for S3/SFTP with CSV, XML, JSON, Parquet)
 - **Batch API Guide:** `docs/02-CORE-GUIDES/ingestion/modules/02-CORE-GUIDES-ingestion-06-batch-api.md`
 
+### Event Log API (Search + Audit)
+
+Query and retrieve events/audit logs from the Fluent Commerce REST Event API. Use these **read-only** methods for troubleshooting workflows, tracing event chains, monitoring orchestration, and auditing batch processing.
+
+**Methods:**
+- `getEvents(params)` → `GET /api/v4.1/event` - Search/filter events with flexible query parameters
+- `getEventById(eventId)` → `GET /api/v4.1/event/{eventId}` - Get a single event by ID
+
+**Important:** These methods query the Event Log (audit trail). They do NOT trigger workflows — use `sendEvent()` for that.
+
+#### Basic Usage
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({
+  config: { baseUrl, clientId, clientSecret, username, password },
+});
+
+// 1) Search for failed orchestration audit events on orders
+const logs = await client.getEvents({
+  'context.rootEntityType': 'ORDER',
+  eventType: 'ORCHESTRATION_AUDIT',
+  eventStatus: 'FAILED',
+  count: 100,
+});
+
+console.log(`Found ${logs.results.length} events (hasMore=${logs.hasMore})`);
+
+for (const event of logs.results) {
+  console.log(`  ${event.name} [${event.eventStatus}] on ${event.context?.entityType}:${event.context?.entityRef}`);
+}
+
+// 2) Get full details for a specific event by ID
+if (logs.results[0]?.id) {
+  const event = await client.getEventById(logs.results[0].id);
+  console.log(`Event: ${event.name} - Status: ${event.eventStatus}`);
+  console.log(`  Entity: ${event.context?.entityType}:${event.context?.entityRef}`);
+  console.log(`  Root: ${event.context?.rootEntityType}:${event.context?.rootEntityRef}`);
+  console.log(`  Generated: ${event.generatedOn} by ${event.generatedBy}`);
+
+  // Trace parent events (for debugging event chains)
+  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})`);
+    }
+  }
+}
+```
+
+#### Response Shape
+
+`getEvents()` returns `FluentEventLogResponse`:
+
+```typescript
+{
+  start: 1,                    // Pagination offset
+  count: 1000,                 // Results in this page
+  hasMore: false,              // More pages available?
+  results: [                   // Array of FluentEventLogItem
+    {
+      id: "e2cc5040-...",      // UUID
+      name: "BATCH_COMPLETE",  // Event/ruleset name (can be null)
+      type: "ORCHESTRATION_AUDIT",
+      accountId: "MYACCOUNT",
+      retailerId: "5",         // String in response (not number)
+      category: "BATCH",
+      context: {
+        sourceEvents: ["babc5f37-..."],  // Parent event IDs for tracing
+        entityType: "BATCH",
+        entityId: "12",
+        entityRef: "12",
+        rootEntityType: "JOB",
+        rootEntityId: "13",
+        rootEntityRef: "13"
+      },
+      eventStatus: "COMPLETE",
+      attributes: null,        // null OR array of { name, value, type }
+      source: null,
+      generatedBy: "Rubix User",
+      generatedOn: "2026-02-05T06:31:56.895+00:00"
+    }
+  ]
+}
+```
+
+`getEventById(id)` returns a single `FluentEventLogItem` (same shape as each item in `results`).
+
+#### Query Parameters
+
+All parameters are optional. Context filters use **dot-notation keys** which require quotes in JavaScript/TypeScript:
+
+```typescript
+// ⚠️ Dot-notation keys MUST be quoted (JavaScript syntax requirement)
+await client.getEvents({
+  'context.rootEntityType': 'ORDER',  // ✅ Quotes required (has dot)
+  'context.entityRef': 'ORD-123',     // ✅ Quotes required (has dot)
+  eventType: 'ORCHESTRATION_AUDIT',   // ✅ No quotes needed (simple key)
+  count: 100,                         // ✅ No quotes needed (simple key)
+});
+```
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `context.rootEntityType` | string | Root entity type | `'ORDER'`, `'JOB'`, `'LOCATION'` |
+| `context.rootEntityId` | string | Root entity ID | `'12345'` |
+| `context.rootEntityRef` | string | Root entity reference | `'ORD-12345'` |
+| `context.entityType` | string | Sub-entity type | `'FULFILMENT'`, `'BATCH'`, `'ARTICLE'` |
+| `context.entityId` | string | Sub-entity ID | `'67890'` |
+| `context.entityRef` | string | Sub-entity reference | `'FUL-67890'` |
+| `eventType` | string | Event type filter | `'ORCHESTRATION_AUDIT'` |
+| `eventStatus` | string | Status filter | `'FAILED'`, `'COMPLETE'` |
+| `name` | string | Event/ruleset name | `'BATCH_COMPLETE'` |
+| `category` | string | Category filter | `'ruleSet'`, `'ACTION'` |
+| `from` | string | Start date (UTC ISO 8601) | `'2026-02-01T00:00:00.000Z'` |
+| `to` | string | End date (UTC ISO 8601) | `'2026-02-15T23:59:59.999Z'` |
+| `retailerId` | string/number | Retailer filter (pass explicitly; no auto-fallback) | `'5'` |
+| `start` | number | Pagination offset (default: `0`) | `0` |
+| `count` | number | Results per page (default: `100`, max: `5000`) | `1000` |
+
+#### Valid Values Reference
+
+| Parameter | Valid Values |
+|-----------|-------------|
+| **eventType** | `ORCHESTRATION`, `ORCHESTRATION_AUDIT`, `API`, `INTEGRATION`, `SECURITY`, `GENERAL` |
+| **eventStatus** | `PENDING`, `SCHEDULED`, `NO_MATCH`, `SUCCESS`, `FAILED`, `COMPLETE` |
+| **category** | `snapshot`, `ruleSet`, `rule`, `ACTION`, `CUSTOM`, `exception`, `ORDER_WORKFLOW`, `BATCH` |
+| **rootEntityType** | `ORDER`, `LOCATION`, `FULFILMENT_OPTIONS`, `PRODUCT_CATALOGUE`, `INVENTORY_CATALOGUE`, `VIRTUAL_CATALOGUE`, `CONTROL_GROUP`, `RETURN_ORDER`, `BILLING_ACCOUNT`, `JOB` |
+| **entityType** | `ORDER`, `FULFILMENT`, `ARTICLE`, `CONSIGNMENT`, `LOCATION`, `WAVE`, `FULFILMENT_OPTIONS`, `FULFILMENT_PLAN`, `PRODUCT_CATALOGUE`, `CATEGORY`, `PRODUCT`, `INVENTORY_CATALOGUE`, `INVENTORY_POSITION`, `INVENTORY_QUANTITY`, `VIRTUAL_CATALOGUE`, `VIRTUAL_POSITION`, `CONTROL_GROUP`, `CONTROL`, `RETURN_ORDER`, `RETURN_FULFILMENT`, `BILLING_ACCOUNT`, `CREDIT_MEMO`, `BATCH` |
+
+#### Common Use Cases
+
+```typescript
+// 1. Find failed events in the last 24 hours
+const failedEvents = await client.getEvents({
+  eventStatus: 'FAILED',
+  from: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+  to: new Date().toISOString(),
+  count: 1000,
+});
+
+// 2. Track batch job processing (all events for a specific job)
+const batchEvents = await client.getEvents({
+  'context.rootEntityType': 'JOB',
+  'context.rootEntityId': '13',
+  eventType: 'ORCHESTRATION_AUDIT',
+  count: 500,
+});
+
+// 3. Paginate through large result sets
+let start = 0;
+const allEvents: any[] = [];
+let hasMore = true;
+
+while (hasMore) {
+  const page = await client.getEvents({
+    'context.rootEntityType': 'ORDER',
+    start,
+    count: 1000,
+  });
+  allEvents.push(...page.results);
+  hasMore = page.hasMore;
+  start += page.count;
+}
+console.log(`Total events collected: ${allEvents.length}`);
+
+// 4. Extract performance timing from event attributes
+const auditEvents = await client.getEvents({
+  eventType: 'ORCHESTRATION_AUDIT',
+  'context.rootEntityType': 'JOB',
+  count: 100,
+});
+
+for (const event of auditEvents.results) {
+  if (Array.isArray(event.attributes)) {
+    const startTimer = event.attributes.find(a => a.name === 'startTimer');
+    const stopTimer = event.attributes.find(a => a.name === 'stopTimer');
+    if (startTimer && stopTimer) {
+      const duration = Number(stopTimer.value) - Number(startTimer.value);
+      console.log(`${event.name}: ${duration}ms`);
+    }
+  }
+}
+
+// 5. Find events for a specific order by reference
+const orderEvents = await client.getEvents({
+  'context.rootEntityType': 'ORDER',
+  'context.rootEntityRef': 'HD_12345',
+  eventType: 'ORCHESTRATION_AUDIT',
+});
+```
+
+#### When to Use Which Method
+
+| Method | Use When | Returns | Example |
+|--------|----------|---------|---------|
+| `sendEvent()` | **Trigger** a workflow or business action | Event creation response | Product upsert, order cancel, location update |
+| `getEvents()` | **Search/filter** historical events | `{ results[], hasMore, start, count }` | Find failed events, audit batch processing |
+| `getEventById()` | **Get full details** for one event by ID | Single event object | Drill into context, attributes, trace sourceEvents |
+
+#### Limitations & Operational Notes
+
+| Constraint | Value | Notes |
+|------------|-------|-------|
+| **Max count per request** | `5000` | Use pagination (`start`/`count`/`hasMore`) for larger result sets |
+| **Time range (from)** | 4 months back max | API rejects queries older than ~4 months |
+| **Time range (to)** | 1 month forward max | API rejects future dates beyond ~1 month |
+| **Default time window** | Past 30 days | Applied when `from` is omitted |
+| **Date format** | UTC ISO 8601 | `YYYY-MM-DDTHH:mm:ss.SSSZ` |
+| **retailerId** | Pass explicitly | Unlike `sendEvent()`, no auto-fallback to client config — pass in params if needed |
+| **attributes field** | Nullable | Can be `null` (not empty array) — always check before iterating |
+| **name field** | Nullable | Can be `null` for some system events |
+| **GraphQL** | Not available | Event queries use REST only — no GraphQL `events` root field exists |
+
+**Key points:**
+- `getEvents()` and `getEventById()` are **read-only** — they do NOT trigger workflows
+- Empty `results: []` is valid (not an error) — your filter may simply match zero events
+- Always use bounded time ranges (`from`/`to`) for predictable performance
+- Use `eventType: 'ORCHESTRATION_AUDIT'` for workflow execution history
+- Use `context.sourceEvents` array on each event to trace parent event chains
+- The `attributes` field is `null` for most events; only rule/ruleset events populate it
+- `retailerId` in responses is a **string** (e.g., `"5"`) even though you can pass a number in params
+
+**📚 Detailed Guide:** `docs/02-CORE-GUIDES/api-reference/event-api-input-output-reference.md`
+
 ---
 
 ### Error Classification

package/dist/cjs/clients/fluent-client.js

@@ -513,6 +513,56 @@ class FluentClient {
             throw error;
         }
     }
+    async getEvents(params = {}) {
+        const queryString = this.buildEventQueryString(params);
+        const endpoint = queryString ? `/api/v4.1/event?${queryString}` : '/api/v4.1/event';
+        this.log('info', '[FluentClient:event] Searching event logs', {
+            endpoint,
+            filterCount: Object.keys(params).length,
+            hasDateRange: !!(params.from || params.to),
+            entityType: params['context.entityType'],
+            rootEntityType: params['context.rootEntityType'],
+            eventStatus: params.eventStatus,
+        });
+        try {
+            const response = await this.request(endpoint, {
+                method: 'GET',
+            });
+            this.log('info', '[FluentClient:event] Event search completed', {
+                resultCount: response.data.count,
+                hasMore: response.data.hasMore,
+                start: response.data.start,
+            });
+            return response.data;
+        }
+        catch (error) {
+            this.log('error', '[FluentClient:event] Failed to search events', error);
+            throw error;
+        }
+    }
+    async getEventById(eventId) {
+        if (!eventId) {
+            throw new types_1.FluentValidationError('eventId is required');
+        }
+        this.log('info', `[FluentClient:event] Getting event by ID: ${eventId}`, { eventId });
+        try {
+            const response = await this.request(`/api/v4.1/event/${eventId}`, {
+                method: 'GET',
+            });
+            this.log('info', `[FluentClient:event] Event retrieved: ${response.data.name}`, {
+                eventId: response.data.id,
+                name: response.data.name,
+                type: response.data.type,
+                eventStatus: response.data.eventStatus,
+                entityType: response.data.context?.entityType,
+            });
+            return response.data;
+        }
+        catch (error) {
+            this.log('error', `[FluentClient:event] Failed to get event ${eventId}`, error);
+            throw error;
+        }
+    }
     async validateWebhook(payload, signature, rawPayload) {
         this.log('info', `[FluentClient:webhook] Validating webhook for event "${payload.name || 'unknown'}"`, {
             hasSignature: !!signature,
@@ -592,6 +642,16 @@ class FluentClient {
         const result = await this.graphql(payload);
         return result.data;
     }
+    buildEventQueryString(params) {
+        const searchParams = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined || value === null || value === '') {
+                continue;
+            }
+            searchParams.append(key, String(value));
+        }
+        return searchParams.toString();
+    }
     async request(endpoint, config = {}) {
         const isVersoriContext = this.context?.fetch && this.context?.fetch !== globalThis.fetch;
         this.log('debug', 'Request mode detection', {

package/dist/cjs/index.d.ts

@@ -34,7 +34,7 @@ export { GraphQLTemplateGenerator } from './services/mapping/query/graphql-templ
 export { MappingError, ResolverError } from './errors';
 export type { NodeConfig, NodesConfig, FieldConfig, FieldsConfig, NodesContext, MappingContext, ResolverFunction, ResolverHelpers, ResolverContext, ResolversMap, MapResult, MapWithNodesResult, NodeValidationResult, MappingOptions, } from './services/mapping/types';
 export { CsvDelimiter, FileEncoding, JobStrategy, FileType, BatchAction, EntityType, AwsRegion, ValidationMode, ProcessingStatus, } from './types/enums';
-export type { FluentClientConfig, FluentBatchPayload, FluentInventoryBatchEntity, FluentInventoryBatchRequest, FluentBatchResponse, FluentBatchStatus, FluentJobPayload, FluentJobResponse, FluentJobMetadata, FluentJobStatus, FluentJobResults, FluentEvent, FluentEventMode, CreateEventOptions, GraphQLPayload, GraphQLResponse, GraphQLErrorMode, GraphQLError, PaginationConfig, PageInfo, PaginatedResponse, FluentWebhookPayload, WebhookRequestContext, GraphQLValidationResult, BatchConfiguration, DataSourceConfig, FileMetadata, Logger, StructuredLogger, LogContext, LoggerConfig, PerformanceMetrics, InventoryDataRecord, ParquetDataRecord, FieldMappingConfig, FieldMappingRule, ProcessingMetadata, AttributeValue, } from './types';
+export type { FluentClientConfig, FluentBatchPayload, FluentInventoryBatchEntity, FluentInventoryBatchRequest, FluentBatchResponse, FluentBatchStatus, FluentJobPayload, FluentJobResponse, FluentJobMetadata, FluentJobStatus, FluentJobResults, FluentEvent, FluentEventMode, CreateEventOptions, FluentEventRootEntityType, FluentEventEntityType, FluentEventCategory, FluentEventType, FluentEventStatus, FluentEventQueryParamValue, FluentEventQueryParams, FluentEventLogAttribute, FluentEventLogContext, FluentEventLogItem, FluentEventLogResponse, GraphQLPayload, GraphQLResponse, GraphQLErrorMode, GraphQLError, PaginationConfig, PageInfo, PaginatedResponse, FluentWebhookPayload, WebhookRequestContext, GraphQLValidationResult, BatchConfiguration, DataSourceConfig, FileMetadata, Logger, StructuredLogger, LogContext, LoggerConfig, PerformanceMetrics, InventoryDataRecord, ParquetDataRecord, FieldMappingConfig, FieldMappingRule, ProcessingMetadata, AttributeValue, } from './types';
 export type { VersoriContext, WebhookContext, DirectContext } from './types';
 export { S3SDKTester, S3PresignedTester, S3ComparisonTester, FluentConnectionTester, type TestResult, type FluentTestConfig, type S3TestConfig, } from './testing/index';
 export { S3Service, S3ServiceError, type S3ServiceConfig, type S3Config, type S3Object, type ListOptions, type PutOptions, type CopyOptions, type S3Location, } from './services/s3/index';

package/dist/cjs/types/index.d.ts

@@ -95,6 +95,70 @@ export interface FluentEvent {
 export interface CreateEventOptions {
     mode?: FluentEventMode;
 }
+export type FluentEventRootEntityType = 'ORDER' | 'LOCATION' | 'FULFILMENT_OPTIONS' | 'PRODUCT_CATALOGUE' | 'INVENTORY_CATALOGUE' | 'VIRTUAL_CATALOGUE' | 'CONTROL_GROUP' | 'RETURN_ORDER' | 'BILLING_ACCOUNT' | 'JOB';
+export type FluentEventEntityType = 'ORDER' | 'FULFILMENT' | 'ARTICLE' | 'CONSIGNMENT' | 'LOCATION' | 'WAVE' | 'FULFILMENT_OPTIONS' | 'FULFILMENT_PLAN' | 'PRODUCT_CATALOGUE' | 'CATEGORY' | 'PRODUCT' | 'INVENTORY_CATALOGUE' | 'INVENTORY_POSITION' | 'INVENTORY_QUANTITY' | 'VIRTUAL_CATALOGUE' | 'VIRTUAL_POSITION' | 'CONTROL_GROUP' | 'CONTROL' | 'RETURN_ORDER' | 'RETURN_FULFILMENT' | 'BILLING_ACCOUNT' | 'CREDIT_MEMO' | 'BATCH';
+export type FluentEventCategory = 'snapshot' | 'ruleSet' | 'rule' | 'ACTION' | 'CUSTOM' | 'exception' | 'ORDER_WORKFLOW';
+export type FluentEventType = 'ORCHESTRATION' | 'ORCHESTRATION_AUDIT' | 'API' | 'INTEGRATION' | 'SECURITY' | 'GENERAL';
+export type FluentEventStatus = 'PENDING' | 'SCHEDULED' | 'NO_MATCH' | 'SUCCESS' | 'FAILED' | 'COMPLETE';
+export type FluentEventQueryParamValue = string | number | boolean;
+export interface FluentEventQueryParams {
+    start?: number;
+    count?: number;
+    from?: string;
+    to?: string;
+    name?: string;
+    category?: FluentEventCategory | string;
+    retailerId?: string | number;
+    eventType?: FluentEventType | string;
+    eventStatus?: FluentEventStatus | string;
+    eventId?: string;
+    'context.rootEntityType'?: FluentEventRootEntityType | string;
+    'context.rootEntityId'?: string | number;
+    'context.rootEntityRef'?: string;
+    'context.entityType'?: FluentEventEntityType | string;
+    'context.entityId'?: string | number;
+    'context.entityRef'?: string;
+    'context.sourceEvents'?: string;
+    [key: string]: FluentEventQueryParamValue | undefined;
+}
+export interface FluentEventLogContext {
+    sourceEvents?: string[];
+    entityType?: FluentEventEntityType | string;
+    entityId?: string;
+    entityRef?: string;
+    rootEntityType?: FluentEventRootEntityType | string;
+    rootEntityId?: string;
+    rootEntityRef?: string;
+    [key: string]: JsonValue | undefined;
+}
+export interface FluentEventLogAttribute {
+    name: string;
+    value: unknown;
+    type?: string;
+    [key: string]: unknown;
+}
+export interface FluentEventLogItem {
+    id: string;
+    name: string;
+    type?: FluentEventType | string;
+    accountId?: string;
+    retailerId?: string;
+    category?: FluentEventCategory | string;
+    context?: FluentEventLogContext;
+    eventStatus?: FluentEventStatus | string;
+    attributes?: FluentEventLogAttribute[] | Record<string, JsonValue> | null;
+    source?: string | null;
+    generatedBy?: string;
+    generatedOn?: string;
+    [key: string]: unknown;
+}
+export interface FluentEventLogResponse {
+    start: number;
+    count: number;
+    hasMore: boolean;
+    results: FluentEventLogItem[];
+    [key: string]: unknown;
+}
 export type GraphQLErrorMode = 'throw' | 'partial';
 export interface GraphQLPayload<T = Record<string, JsonValue>> {
     query: string;

package/dist/cjs/versori/fluent-versori-client.d.ts

@@ -1,4 +1,4 @@
-import type { FluentEvent, GraphQLPayload, GraphQLResponse, FluentEventMode, JsonValue, FluentBatchPayload, FluentBatchResponse, FluentBatchStatus, FluentJobPayload, FluentJobResponse, FluentJobStatus, FluentJobResults } from '../types';
+import type { FluentEvent, GraphQLPayload, GraphQLResponse, FluentEventMode, FluentEventLogResponse, FluentEventLogItem, FluentEventQueryParams, JsonValue, FluentBatchPayload, FluentBatchResponse, FluentBatchStatus, FluentJobPayload, FluentJobResponse, FluentJobStatus, FluentJobResults } from '../types';
 import type { FluentWebhookPayload, EventResponse } from '../types';
 export declare class FluentVersoriClient {
     private ctx;
@@ -13,6 +13,8 @@ export declare class FluentVersoriClient {
     private executeSinglePage;
     private executeWithAutoPagination;
     sendEvent(event: FluentEvent, mode?: FluentEventMode): Promise<EventResponse>;
+    getEvents(params?: FluentEventQueryParams): Promise<FluentEventLogResponse>;
+    getEventById(eventId: string): Promise<FluentEventLogItem>;
     createJob(payload: FluentJobPayload): Promise<FluentJobResponse>;
     sendBatch(jobId: string, payload: FluentBatchPayload): Promise<FluentBatchResponse>;
     getJobStatus(jobId: string): Promise<FluentJobStatus>;
@@ -20,6 +22,7 @@ export declare class FluentVersoriClient {
     getJobResults(jobId: string): Promise<FluentJobResults>;
     query<T = JsonValue>(queryOrPayload: string | GraphQLPayload, variables?: Record<string, any>): Promise<T | undefined>;
     mutate<T = JsonValue>(mutationOrPayload: string | GraphQLPayload, variables?: Record<string, any>): Promise<T | undefined>;
+    private buildEventQueryString;
     private throwApiError;
     private fetchWithRetry;
     validateWebhook(payload: FluentWebhookPayload, signature?: string, rawPayload?: string, publicKey?: string): Promise<boolean>;

package/dist/cjs/versori/fluent-versori-client.js

@@ -427,6 +427,79 @@ class FluentVersoriClient {
             return { success: true, statusCode: response.status, message: text };
         }
     }
+    async getEvents(params = {}) {
+        const query = this.buildEventQueryString(params);
+        const endpoint = query ? `/api/v4.1/event?${query}` : '/api/v4.1/event';
+        this.ctx.log.info('[fc-connect-sdk:event] Searching event logs', {
+            endpoint,
+            filterCount: Object.keys(params).length,
+            hasDateRange: !!(params.from || params.to),
+            entityType: params['context.entityType'],
+            rootEntityType: params['context.rootEntityType'],
+            eventStatus: params.eventStatus,
+        });
+        const response = await this.fetchWithRetry(endpoint, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+        const text = response.text;
+        if (!response.ok) {
+            this.ctx.log.error('[fc-connect-sdk:event] Failed to search events', {
+                status: response.status,
+                body: text,
+            });
+            this.throwApiError('Get events failed', response.status, text);
+        }
+        try {
+            const result = JSON.parse(text);
+            this.ctx.log.info('[fc-connect-sdk:event] Event search completed', {
+                resultCount: result.count,
+                hasMore: result.hasMore,
+                start: result.start,
+            });
+            return result;
+        }
+        catch {
+            throw new types_1.FluentAPIError('Failed to parse event log response', response.status, text);
+        }
+    }
+    async getEventById(eventId) {
+        if (!eventId) {
+            throw new types_1.FluentValidationError('eventId is required');
+        }
+        this.ctx.log.info(`[fc-connect-sdk:event] Getting event by ID: ${eventId}`, { eventId });
+        const response = await this.fetchWithRetry(`/api/v4.1/event/${eventId}`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+        const text = response.text;
+        if (!response.ok) {
+            this.ctx.log.error(`[fc-connect-sdk:event] Failed to get event ${eventId}`, {
+                eventId,
+                status: response.status,
+                body: text,
+            });
+            this.throwApiError(`Get event ${eventId} failed`, response.status, text);
+        }
+        try {
+            const event = JSON.parse(text);
+            this.ctx.log.info(`[fc-connect-sdk:event] Event retrieved: ${event.name}`, {
+                eventId: event.id,
+                name: event.name,
+                type: event.type,
+                eventStatus: event.eventStatus,
+                entityType: event.context?.entityType,
+            });
+            return event;
+        }
+        catch {
+            throw new types_1.FluentAPIError('Failed to parse event response', response.status, text);
+        }
+    }
     async createJob(payload) {
         this.ctx.log.info(`[fc-connect-sdk:job] Creating job "${payload.name}"`, {
             name: payload.name,
@@ -574,6 +647,16 @@ class FluentVersoriClient {
         const result = await this.graphql(payload);
         return result.data;
     }
+    buildEventQueryString(params) {
+        const searchParams = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined || value === null || value === '') {
+                continue;
+            }
+            searchParams.append(key, String(value));
+        }
+        return searchParams.toString();
+    }
     throwApiError(message, status, responseText) {
         if (status === 401) {
             throw new types_1.AuthenticationError(`${message}: ${responseText}`, { response: responseText });

package/dist/esm/clients/fluent-client.js

@@ -510,6 +510,56 @@ export class FluentClient {
             throw error;
         }
     }
+    async getEvents(params = {}) {
+        const queryString = this.buildEventQueryString(params);
+        const endpoint = queryString ? `/api/v4.1/event?${queryString}` : '/api/v4.1/event';
+        this.log('info', '[FluentClient:event] Searching event logs', {
+            endpoint,
+            filterCount: Object.keys(params).length,
+            hasDateRange: !!(params.from || params.to),
+            entityType: params['context.entityType'],
+            rootEntityType: params['context.rootEntityType'],
+            eventStatus: params.eventStatus,
+        });
+        try {
+            const response = await this.request(endpoint, {
+                method: 'GET',
+            });
+            this.log('info', '[FluentClient:event] Event search completed', {
+                resultCount: response.data.count,
+                hasMore: response.data.hasMore,
+                start: response.data.start,
+            });
+            return response.data;
+        }
+        catch (error) {
+            this.log('error', '[FluentClient:event] Failed to search events', error);
+            throw error;
+        }
+    }
+    async getEventById(eventId) {
+        if (!eventId) {
+            throw new FluentValidationError('eventId is required');
+        }
+        this.log('info', `[FluentClient:event] Getting event by ID: ${eventId}`, { eventId });
+        try {
+            const response = await this.request(`/api/v4.1/event/${eventId}`, {
+                method: 'GET',
+            });
+            this.log('info', `[FluentClient:event] Event retrieved: ${response.data.name}`, {
+                eventId: response.data.id,
+                name: response.data.name,
+                type: response.data.type,
+                eventStatus: response.data.eventStatus,
+                entityType: response.data.context?.entityType,
+            });
+            return response.data;
+        }
+        catch (error) {
+            this.log('error', `[FluentClient:event] Failed to get event ${eventId}`, error);
+            throw error;
+        }
+    }
     async validateWebhook(payload, signature, rawPayload) {
         this.log('info', `[FluentClient:webhook] Validating webhook for event "${payload.name || 'unknown'}"`, {
             hasSignature: !!signature,
@@ -589,6 +639,16 @@ export class FluentClient {
         const result = await this.graphql(payload);
         return result.data;
     }
+    buildEventQueryString(params) {
+        const searchParams = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined || value === null || value === '') {
+                continue;
+            }
+            searchParams.append(key, String(value));
+        }
+        return searchParams.toString();
+    }
     async request(endpoint, config = {}) {
         const isVersoriContext = this.context?.fetch && this.context?.fetch !== globalThis.fetch;
         this.log('debug', 'Request mode detection', {

package/dist/esm/index.d.ts

@@ -34,7 +34,7 @@ export { GraphQLTemplateGenerator } from './services/mapping/query/graphql-templ
 export { MappingError, ResolverError } from './errors/index.js';
 export type { NodeConfig, NodesConfig, FieldConfig, FieldsConfig, NodesContext, MappingContext, ResolverFunction, ResolverHelpers, ResolverContext, ResolversMap, MapResult, MapWithNodesResult, NodeValidationResult, MappingOptions, } from './services/mapping/types/index.js';
 export { CsvDelimiter, FileEncoding, JobStrategy, FileType, BatchAction, EntityType, AwsRegion, ValidationMode, ProcessingStatus, } from './types/enums.js';
-export type { FluentClientConfig, FluentBatchPayload, FluentInventoryBatchEntity, FluentInventoryBatchRequest, FluentBatchResponse, FluentBatchStatus, FluentJobPayload, FluentJobResponse, FluentJobMetadata, FluentJobStatus, FluentJobResults, FluentEvent, FluentEventMode, CreateEventOptions, GraphQLPayload, GraphQLResponse, GraphQLErrorMode, GraphQLError, PaginationConfig, PageInfo, PaginatedResponse, FluentWebhookPayload, WebhookRequestContext, GraphQLValidationResult, BatchConfiguration, DataSourceConfig, FileMetadata, Logger, StructuredLogger, LogContext, LoggerConfig, PerformanceMetrics, InventoryDataRecord, ParquetDataRecord, FieldMappingConfig, FieldMappingRule, ProcessingMetadata, AttributeValue, } from './types/index.js';
+export type { FluentClientConfig, FluentBatchPayload, FluentInventoryBatchEntity, FluentInventoryBatchRequest, FluentBatchResponse, FluentBatchStatus, FluentJobPayload, FluentJobResponse, FluentJobMetadata, FluentJobStatus, FluentJobResults, FluentEvent, FluentEventMode, CreateEventOptions, FluentEventRootEntityType, FluentEventEntityType, FluentEventCategory, FluentEventType, FluentEventStatus, FluentEventQueryParamValue, FluentEventQueryParams, FluentEventLogAttribute, FluentEventLogContext, FluentEventLogItem, FluentEventLogResponse, GraphQLPayload, GraphQLResponse, GraphQLErrorMode, GraphQLError, PaginationConfig, PageInfo, PaginatedResponse, FluentWebhookPayload, WebhookRequestContext, GraphQLValidationResult, BatchConfiguration, DataSourceConfig, FileMetadata, Logger, StructuredLogger, LogContext, LoggerConfig, PerformanceMetrics, InventoryDataRecord, ParquetDataRecord, FieldMappingConfig, FieldMappingRule, ProcessingMetadata, AttributeValue, } from './types/index.js';
 export type { VersoriContext, WebhookContext, DirectContext } from './types/index.js';
 export { S3SDKTester, S3PresignedTester, S3ComparisonTester, FluentConnectionTester, type TestResult, type FluentTestConfig, type S3TestConfig, } from './testing/index.js';
 export { S3Service, S3ServiceError, type S3ServiceConfig, type S3Config, type S3Object, type ListOptions, type PutOptions, type CopyOptions, type S3Location, } from './services/s3/index.js';