@fluentcommerce/fc-connect-sdk 0.1.51 → 0.1.52

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

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

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-08-types.md

@@ -77,6 +77,58 @@ if (result.errors) {
 }
 ```
 
+### FluentEventQueryParams
+
+Query params for Event Log/Audit search (`GET /api/v4.1/event`).
+
+```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;
+}
+```
+
+### FluentEventLogResponse
+
+Response from Event Log search (`client.getEvents()`).
+
+```typescript
+interface FluentEventLogResponse {
+  start: number;
+  count: number;
+  hasMore: boolean;
+  results: FluentEventLogItem[];
+}
+
+interface FluentEventLogItem {
+  id: string;
+  name: string;
+  type?: string;
+  accountId?: string;
+  retailerId?: string;
+  category?: string;
+  context?: FluentEventLogContext;
+  eventStatus?: string;
+  attributes?: FluentEventLogAttribute[] | Record<string, AttributeValue> | null;
+  source?: string | null;
+  generatedBy?: string;
+  generatedOn?: string;
+}
+```
+
 ## Enums
 
 ### BatchAction

package/docs/02-CORE-GUIDES/api-reference/readme.md

@@ -68,7 +68,7 @@ import {
 
 The main entry point for SDK operations. Learn how to create clients, execute GraphQL operations, send events, and manage batch jobs.
 
-**Key APIs:** `createClient()`, `FluentClient`, `graphql(payload)`, `sendEvent()`, `createJob()`, `sendBatch()`
+**Key APIs:** `createClient()`, `FluentClient`, `graphql(payload)`, `sendEvent()`, `getEvents()`, `getEventById()`, `createJob()`, `sendBatch()`
 
 [View Module →](./modules/api-reference-01-client-api.md)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentcommerce/fc-connect-sdk",
-  "version": "0.1.51",
+  "version": "0.1.52",
   "description": "Fluent Commerce SDK - Deno & Node.js Compatible",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -109,7 +109,7 @@
     "@types/ssh2-sftp-client": "^9.0.5",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
-    "@versori/run": "^0.4.4",
+    "@versori/run": "^0.4.18",
     "chalk": "^4.1.2",
     "dotenv": "^17.2.2",
     "eslint": "^8.57.0",