@fluentcommerce/fc-connect-sdk 0.1.48 → 0.1.52

package/README.md

@@ -32,6 +32,7 @@ TypeScript SDK for building **Fluent Commerce** integrations across Node.js, Den
 - [Core Services](#core-services) - API reference
 - [CLI Tools](#cli-tooling) - Command-line utilities
 - [Authentication & Webhooks](#authentication-webhooks) - Security
+- [Security & Compliance](#security--compliance) - Security audits, SOC 2, vulnerability management 🆕
 - [Common Pitfalls](#common-pitfalls-and-fixes) - Troubleshooting
 - [Support](#additional-resources) - Help & resources
 
@@ -146,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 |
@@ -1114,6 +1116,27 @@ console.log(
 // result.stats = { totalPages: 9, totalRecords: 847, truncated: false }
 ```
 
+**Handling Partial Responses (Errors with Data):**
+
+```typescript
+// When GraphQL returns errors but some data is available
+const result = await orchestrator.extract({
+  query: ORDERS_QUERY,
+  resultPath: 'orders.edges.node',
+  errorHandling: 'partial', // Continue extraction even with errors
+});
+
+// Check for partial errors
+if (result.stats.partialErrors) {
+  console.warn(`Extraction completed with ${result.stats.partialErrors.length} errors`);
+  console.log(`Still extracted ${result.data.length} records`);
+  // Errors are in result.stats.partialErrors
+}
+
+// Edge case: If GraphQL returns errors with null data, result.data will be []
+// but errors are still available in result.stats.partialErrors
+```
+
 **Alternative: Using FluentClient (For Custom Response Handling)**
 
 ```typescript
@@ -1195,6 +1218,222 @@ 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 flat dot-notation keys:
+
+| 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 (falls back to client config) | `'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 fallback** | Client config | If not in params, uses `client.config.retailerId` |
+| **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
@@ -1386,6 +1625,110 @@ const validation = await authService.validateApiKey(
 
 ---
 
+## 🚀 Standalone Usage (Outside Versori)
+
+**Use the SDK in your own TypeScript/Node.js applications** - not just in Versori workflows.
+
+### Quick Example: Custom REST API Calls
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Create client with OAuth2 authentication
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: 'FLUENT_INTEGRATION',
+    clientSecret: 'your-client-secret',
+    username: 'your-username',
+    password: 'your-password',
+    retailerId: 'your-retailer-id',
+  },
+});
+
+// Call any REST endpoint (authentication handled automatically)
+const response = await client.request('/orchestration/rest/v1/plugin', {
+  method: 'GET',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+});
+
+console.log('Status:', response.status);
+console.log('Data:', response.data);
+```
+
+### What's Handled Automatically
+
+- ✅ **OAuth2 Authentication** - Token fetched and cached automatically
+- ✅ **Token Refresh** - Uses refresh_token when available, falls back to full auth
+- ✅ **401 Retry** - Automatically retries on 401 errors with fresh token
+- ✅ **Error Handling** - Retries 5xx errors with exponential backoff
+- ✅ **Any REST Endpoint** - Call any Fluent Commerce API endpoint
+
+### Complete Examples
+
+- **📄 Full Example:** `examples/standalone-rest-api-call.ts` - Complete working example with GET, POST, query parameters
+- **📚 Documentation:** `examples/README-standalone-usage.md` - Detailed guide with all options
+- **✅ Verification:** `examples/VERIFICATION.md` - SDK implementation verification
+
+### Use Cases
+
+- Custom admin tools and dashboards
+- Standalone scripts and automation
+- Integration with other systems
+- Testing and development tools
+- Any TypeScript/Node.js application
+
+**📚 Learn More:** See `examples/README-standalone-usage.md` for complete documentation
+
+---
+
+## Security & Compliance
+
+The SDK includes comprehensive security audit tools and SOC 2 compliance documentation.
+
+### Quick Security Check
+
+```bash
+# Run comprehensive security audit
+npm run security:check
+
+# Fix vulnerabilities safely (with tests)
+npm run security:fix
+
+# Advanced scanning with Snyk
+npm run security:snyk
+```
+
+### Security Tools
+
+- **Security Audit Script** - Automated vulnerability scanning (`security-audit/security-audit.cjs`)
+- **Safe Fix Script** - Fix vulnerabilities with automatic testing (`security-audit/safe-fix.cjs`)
+- **Snyk Integration** - Advanced vulnerability scanning with detailed reports
+- **GitHub Actions** - Automated weekly security scans
+- **Dependabot** - Automated dependency updates
+
+### Documentation
+
+- **[Security Audit Quick Start](security-audit/QUICK-START.md)** - Get started with security checks
+- **[SOC 2 Compliance Guide](security-audit/SOC2-COMPLIANCE-GUIDE.md)** - Complete SOC 2 compliance requirements
+- **[Vulnerability Checking Guide](security-audit/VULNERABILITY-CHECKING.md)** - Detailed vulnerability management
+- **[Safe Fixing Guide](security-audit/SAFE-FIXING-GUIDE.md)** - How to fix vulnerabilities without breaking code
+- **[Advanced Scanning](security-audit/ADVANCED-SCANNING.md)** - Snyk and advanced security tools
+- **[What is the Audit?](security-audit/WHAT-IS-THE-AUDIT.md)** - Understanding security audits and risks
+
+### Current Security Status
+
+✅ **Production Code:** Secure - All production dependencies are secure  
+⚠️ **Remaining:** 3 moderate vulnerabilities in transitive dependencies (monitoring)  
+✅ **Tests:** All 3420 tests passing  
+✅ **Build:** Successful
+
+See [security-audit/FIXES-APPLIED.md](security-audit/FIXES-APPLIED.md) for detailed security status.
+
+---
+
 ## Common Pitfalls (and fixes)
 
 ### ⚠️ Critical Anti-Patterns

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

@@ -78,8 +78,9 @@ class FluentClient {
             paginationEnabled,
             direction: paginationVars.direction,
         });
+        const errorHandling = payload.errorHandling ?? 'throw';
         if (!paginationEnabled) {
-            return this.executeSinglePage(payload);
+            return this.executeSinglePage(payload, errorHandling);
         }
         let direction = payload.pagination?.direction ?? paginationVars.direction;
         if (paginationVars.direction === 'none' && !payload.pagination?.direction) {
@@ -99,16 +100,18 @@ class FluentClient {
             abortSignal: payload.pagination?.abortSignal,
             onProgress: payload.pagination?.onProgress ?? (() => { }),
             onWarning: payload.pagination?.onWarning ?? ((msg) => this.log('warn', msg)),
+            errorHandling,
         };
         this.log('info', '[FluentClient:graphql] Auto-pagination enabled', {
             maxPages: config.maxPages,
             maxRecords: config.maxRecords,
             timeoutMs: config.timeoutMs,
             direction: config.direction,
+            errorHandling: config.errorHandling,
         });
         return this.executeWithAutoPagination(payload, paginationVars, config);
     }
-    async executeSinglePage(payload) {
+    async executeSinglePage(payload, errorHandling = 'throw') {
         const operationName = payload.operationName || 'unnamed';
         try {
             const apiPayload = {
@@ -125,9 +128,21 @@ class FluentClient {
                 body: apiPayload,
             });
             if (response.data.errors?.length) {
+                if (errorHandling === 'partial') {
+                    this.log('warn', `[FluentClient:graphql] GraphQL operation "${operationName}" returned partial data with ${response.data.errors.length} error(s)`, {
+                        operationName,
+                        errorMessages: response.data.errors.map(e => e.message),
+                        errorCount: response.data.errors.length,
+                        hasData: !!response.data.data,
+                    });
+                    return {
+                        ...response.data,
+                        hasPartialData: true,
+                    };
+                }
                 this.log('error', `[FluentClient:graphql] GraphQL operation "${operationName}" returned ${response.data.errors.length} error(s)`, {
                     operationName,
-                    errors: response.data.errors,
+                    errorMessages: response.data.errors.map(e => e.message),
                     errorCount: response.data.errors.length,
                 });
                 const firstError = response.data.errors[0];
@@ -152,6 +167,7 @@ class FluentClient {
         let lastCursor = null;
         let emptyPageCount = 0;
         const MAX_EMPTY_PAGES = FluentClient.DEFAULT_PAGINATION_CONFIG.maxEmptyPages;
+        const accumulatedErrors = [];
         while (true) {
             if (config.abortSignal?.aborted) {
                 truncated = true;
@@ -172,17 +188,29 @@ class FluentClient {
             const response = await this.executeSinglePage({
                 query: payload.query,
                 variables: currentVariables,
-            });
+            }, 'partial');
             lastExtensions = response.extensions;
             if (response.errors && response.errors.length > 0) {
-                this.log('error', `[FluentClient:pagination] GraphQL errors during pagination (page ${pageNumber + 1}, ${totalRecords} records fetched so far)`, {
-                    errors: response.errors,
-                    pagesCompleted: pageNumber,
-                    totalRecordsBeforeError: totalRecords,
-                    errorCount: response.errors.length,
-                });
-                const firstError = response.errors[0];
-                throw new ingestion_errors_1.GraphQLExecutionError(`GraphQL error during pagination (page ${pageNumber}): ${firstError.message || 'Unknown error'}`, response.errors, payload.query, currentVariables);
+                if (config.errorHandling === 'partial') {
+                    this.log('warn', `[FluentClient:pagination] Page ${pageNumber + 1} returned partial data with ${response.errors.length} error(s)`, {
+                        errorMessages: response.errors.map(e => e.message),
+                        pagesCompleted: pageNumber,
+                        totalRecordsSoFar: totalRecords,
+                        errorCount: response.errors.length,
+                        hasData: !!response.data,
+                    });
+                    accumulatedErrors.push(...response.errors);
+                }
+                else {
+                    this.log('error', `[FluentClient:pagination] GraphQL errors during pagination (page ${pageNumber + 1}, ${totalRecords} records fetched so far)`, {
+                        errorMessages: response.errors.map(e => e.message),
+                        pagesCompleted: pageNumber,
+                        totalRecordsBeforeError: totalRecords,
+                        errorCount: response.errors.length,
+                    });
+                    const firstError = response.errors[0];
+                    throw new ingestion_errors_1.GraphQLExecutionError(`GraphQL error during pagination (page ${pageNumber}): ${firstError.message || 'Unknown error'}`, response.errors, payload.query, currentVariables);
+                }
             }
             pageNumber++;
             const connection = (0, pagination_helpers_1.extractConnection)(response.data, config.connectionPath);
@@ -260,14 +288,17 @@ class FluentClient {
                 await new Promise(resolve => setTimeout(resolve, config.delayMs));
             }
         }
-        this.log('info', `[FluentClient:pagination] Pagination complete (${pageNumber} pages, ${totalRecords} records${truncated ? `, truncated: ${truncationReason}` : ''})`, {
+        const hasPartialErrors = accumulatedErrors.length > 0;
+        this.log('info', `[FluentClient:pagination] Pagination complete (${pageNumber} pages, ${totalRecords} records${truncated ? `, truncated: ${truncationReason}` : ''}${hasPartialErrors ? `, ${accumulatedErrors.length} errors` : ''})`, {
             totalPages: pageNumber,
             totalRecords,
             truncated,
             truncationReason,
             duration: Date.now() - startTime,
+            hasPartialErrors,
+            errorCount: accumulatedErrors.length,
         });
-        return {
+        const response = {
             data: allData,
             extensions: {
                 ...(lastExtensions || {}),
@@ -280,6 +311,11 @@ class FluentClient {
                 },
             },
         };
+        if (hasPartialErrors) {
+            response.errors = accumulatedErrors;
+            response.hasPartialData = true;
+        }
+        return response;
     }
     mergeConnectionData(allData, newData, connection, direction) {
         const allConnection = (0, pagination_helpers_1.extractConnection)(allData);
@@ -477,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,
@@ -556,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/data-sources/s3-data-source.js

@@ -378,7 +378,7 @@ class S3DataSource extends abstract_data_source_1.AbstractDataSource {
             return Buffer.from('PAR1\x00\x00\x00\x00PAR1', 'ascii');
         }
         try {
-            const parquet = await Promise.resolve().then(() => __importStar(require('parquetjs')));
+            const parquet = await Promise.resolve().then(() => __importStar(require('@dsnp/parquetjs')));
             const ParquetWriter = parquet.ParquetWriter;
             const ParquetSchema = parquet.ParquetSchema;
             const fs = await Promise.resolve().then(() => __importStar(require('fs')));

package/dist/cjs/data-sources/sftp-data-source.js

@@ -361,7 +361,7 @@ class SftpDataSource extends abstract_data_source_1.AbstractDataSource {
             return Buffer.from('PAR1\x00\x00\x00\x00PAR1', 'ascii');
         }
         try {
-            const parquet = await Promise.resolve().then(() => __importStar(require('parquetjs')));
+            const parquet = await Promise.resolve().then(() => __importStar(require('@dsnp/parquetjs')));
             const ParquetWriter = parquet.ParquetWriter;
             const ParquetSchema = parquet.ParquetSchema;
             const fs = await Promise.resolve().then(() => __importStar(require('fs')));

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, 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/services/extraction/extraction-orchestrator.d.ts

@@ -1,5 +1,5 @@
 import type { FluentClient } from '../../clients/fluent-client';
-import type { Logger } from '../../types';
+import type { Logger, GraphQLErrorMode, GraphQLError } from '../../types';
 export interface ExtractionOptions<T = any> {
     query: string;
     resultPath: string;
@@ -10,6 +10,8 @@ export interface ExtractionOptions<T = any> {
     direction?: 'forward' | 'backward';
     timeout?: number;
     validateItem?: (item: T) => boolean;
+    operationName?: string;
+    errorHandling?: GraphQLErrorMode;
 }
 export interface ExtractionStats {
     totalRecords: number;
@@ -20,6 +22,7 @@ export interface ExtractionStats {
     validRecords?: number;
     invalidRecords?: number;
     direction?: 'forward' | 'backward';
+    partialErrors?: GraphQLError[];
 }
 export interface ExtractionError {
     type: 'graphql' | 'network' | 'validation' | 'parsing';