@fluentcommerce/fc-connect-sdk 0.1.48 → 0.1.52

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/modules/api-reference-12-partial-responses.md

@@ -0,0 +1,212 @@
+# GraphQL Partial Response Support
+
+> **Version:** 0.1.51+
+> **Status:** Stable
+
+## Overview
+
+By default, the SDK throws a `GraphQLExecutionError` when a GraphQL response contains any errors. This "fail-fast" behavior is intentional for data integration scenarios where partial data could lead to inconsistencies.
+
+However, GraphQL allows responses to contain **both** `data` AND `errors` simultaneously (partial responses). This feature allows you to opt-in to receiving partial data when appropriate for your use case.
+
+## Default Behavior (Backward Compatible)
+
+```typescript
+// Default: throws on ANY GraphQL errors
+const result = await client.graphql({
+  query: `
+    mutation {
+      product1: createProduct(input: { ref: "SKU1" }) { id }
+      product2: createProduct(input: { ref: "SKU2" }) { id }
+    }
+  `
+});
+// If product2 fails, throws GraphQLExecutionError
+// Data from product1 is lost
+```
+
+## Opt-In Partial Response Mode
+
+```typescript
+// Partial mode: returns both data and errors
+const result = await client.graphql({
+  query: `
+    mutation {
+      product1: createProduct(input: { ref: "SKU1" }) { id }
+      product2: createProduct(input: { ref: "SKU2" }) { id }
+    }
+  `,
+  errorHandling: 'partial'  // <-- Opt-in
+});
+
+// Check for partial success
+if (result.hasPartialData) {
+  console.log('Partial success:', {
+    data: result.data,           // { product1: { id: '123' }, product2: null }
+    errors: result.errors,       // [{ message: 'SKU2 already exists', path: ['product2'] }]
+    errorCount: result.errors?.length,
+  });
+
+  // Process successful items
+  if (result.data?.product1) {
+    console.log('Product 1 created:', result.data.product1.id);
+  }
+
+  // Log failed items for retry or investigation
+  for (const error of result.errors || []) {
+    console.warn('Failed mutation:', error.path?.[0], error.message);
+  }
+}
+```
+
+## API Reference
+
+### GraphQLPayload Options
+
+```typescript
+interface GraphQLPayload {
+  query: string;
+  variables?: Record<string, any>;
+  operationName?: string;
+  pagination?: PaginationConfig;
+
+  /**
+   * How to handle GraphQL errors in the response.
+   * @default 'throw' - Throws GraphQLExecutionError on any errors
+   * @since 0.1.51 Set to 'partial' to receive both data and errors
+   */
+  errorHandling?: 'throw' | 'partial';
+}
+```
+
+### GraphQLResponse Extensions
+
+```typescript
+interface GraphQLResponse<T> {
+  data?: T;
+  errors?: GraphQLError[];
+  extensions?: Record<string, unknown>;
+
+  /**
+   * True when response contains both data AND errors.
+   * Only present when errorHandling: 'partial' is used and errors occurred.
+   * @since 0.1.51
+   */
+  hasPartialData?: boolean;
+}
+```
+
+## With Pagination
+
+Partial response mode works with auto-pagination. Errors from all pages are accumulated:
+
+```typescript
+const result = await client.graphql({
+  query: PAGINATED_QUERY,
+  variables: { first: 100 },
+  errorHandling: 'partial'
+});
+
+// Errors from all pages are collected
+if (result.hasPartialData) {
+  console.log(`Fetched data with ${result.errors?.length} errors across pages`);
+}
+```
+
+## With ExtractionOrchestrator
+
+The ExtractionOrchestrator also supports partial responses:
+
+```typescript
+const orchestrator = new ExtractionOrchestrator(client, logger);
+
+const result = await orchestrator.extract({
+  query: PRODUCTS_QUERY,
+  resultPath: 'products.edges.node',
+  errorHandling: 'partial',  // Continue extraction even with errors
+});
+
+// Check for partial errors in stats
+if (result.stats.partialErrors) {
+  logger.warn('Extraction completed with errors', {
+    recordsExtracted: result.data.length,
+    errorCount: result.stats.partialErrors.length,
+  });
+}
+```
+
+### Edge Case: Null Data with Errors
+
+When GraphQL returns errors with `data: null` or `data: undefined`, the ExtractionOrchestrator handles this gracefully in partial mode:
+
+```typescript
+// GraphQL response: { data: null, errors: [{ message: 'Order item not found' }] }
+const result = await orchestrator.extract({
+  query: ORDERS_QUERY,
+  resultPath: 'orders.edges.node',
+  errorHandling: 'partial',
+});
+
+// Returns empty array with errors in stats
+expect(result.data).toEqual([]);
+expect(result.stats.partialErrors).toHaveLength(1);
+```
+
+**Behavior:**
+- **Partial mode**: Returns empty array `[]`, accumulates errors in `stats.partialErrors`, stops pagination if no data
+- **Throw mode** (default): Throws `GraphQLExecutionError` immediately (backward compatible)
+
+This ensures that partial mode never throws due to null data - it always returns available data (even if empty) along with accumulated errors.
+
+## When to Use Partial Responses
+
+| Scenario | Recommendation |
+|----------|----------------|
+| Single record operations | Use default `'throw'` |
+| Batch mutations where failures are independent | Consider `'partial'` |
+| Read-only queries where partial data is useful | Consider `'partial'` |
+| Critical data where consistency matters | Use default `'throw'` |
+| Reporting/analytics where some data is better than none | Consider `'partial'` |
+
+## Error Classification
+
+When using partial mode, you can classify errors for better handling:
+
+```typescript
+import { classifyErrors } from '@fluentcommerce/fc-connect-sdk';
+
+const result = await client.graphql({
+  query: batchMutation,
+  errorHandling: 'partial'
+});
+
+if (result.hasPartialData && result.errors) {
+  const classified = classifyErrors(result.errors);
+
+  // Handle retryable errors
+  if (classified.retryable.length > 0) {
+    console.log('Retryable errors:', classified.retryable);
+  }
+
+  // Handle permanent failures
+  if (classified.permanent.length > 0) {
+    console.log('Permanent failures:', classified.permanent);
+  }
+}
+```
+
+## Migration Guide
+
+No migration needed - the default behavior remains unchanged. To adopt partial responses:
+
+1. Add `errorHandling: 'partial'` to your GraphQL calls
+2. Check `result.hasPartialData` to detect partial success
+3. Handle `result.errors` array for failed operations
+4. Update your logging and monitoring to track partial successes
+
+## Best Practices
+
+1. **Always check `hasPartialData`**: Don't assume success just because no exception was thrown
+2. **Log partial errors**: Even in partial mode, errors should be logged for investigation
+3. **Consider retry logic**: Partial failures may benefit from retrying failed items
+4. **Monitor partial success rates**: Track how often partial responses occur in your workflows

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/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md

@@ -290,13 +290,14 @@ interface ExtractionOptions<T = any> {
   timeout?: number; // Query timeout ms (default: 60000)
   direction?: 'forward' | 'backward'; // Pagination direction (default: 'forward')
   validateItem?: (item: T) => boolean; // Optional per-item validation
+  errorHandling?: 'throw' | 'partial'; // How to handle GraphQL errors (default: 'throw')
+  operationName?: string; // Optional operation name for logging
 }
 ```
 
-**Note on `direction`:**
-- `'forward'` (default): Uses `first/after` params, requires `pageInfo.hasNextPage`
-- `'backward'`: Uses `last/before` params, requires `pageInfo.hasPreviousPage`
-- Your GraphQL query must match the direction (don't mix `first/after` with `direction: 'backward'`)
+**Notes:**
+- `direction`: `'forward'` (default) uses `first/after` params, requires `pageInfo.hasNextPage`. `'backward'` uses `last/before` params, requires `pageInfo.hasPreviousPage`. Your GraphQL query must match the direction (don't mix `first/after` with `direction: 'backward'`)
+- `errorHandling`: `'throw'` (default) throws `GraphQLExecutionError` on any errors. `'partial'` continues extraction and accumulates errors in `stats.partialErrors`. See [Partial Response Support](../../api-reference/modules/api-reference-12-partial-responses.md) for details.
 
 ### ExtractionResult
 
@@ -316,6 +317,7 @@ interface ExtractionStats {
   validRecords?: number; // Valid records (if validation used)
   invalidRecords?: number; // Invalid records (if validation used)
   direction?: 'forward' | 'backward'; // Pagination direction used
+  partialErrors?: GraphQLError[]; // GraphQL errors (only when errorHandling: 'partial')
 }
 
 interface ExtractionError {
@@ -715,6 +717,68 @@ try {
 }
 ```
 
+### Partial Response Mode (errorHandling: 'partial')
+
+When GraphQL returns errors but some data is available, you can use partial mode to continue extraction:
+
+```typescript
+const result = await orchestrator.extract({
+  query: ORDERS_QUERY,
+  resultPath: 'orders.edges.node',
+  errorHandling: 'partial', // Continue extraction even with errors
+});
+
+// Check for partial errors in stats
+if (result.stats.partialErrors) {
+  logger.warn('Extraction completed with partial errors', {
+    recordsExtracted: result.data.length,
+    errorCount: result.stats.partialErrors.length,
+  });
+
+  // Process available data
+  console.log(`Extracted ${result.data.length} records despite errors`);
+
+  // Log errors for investigation
+  result.stats.partialErrors.forEach(err => {
+    logger.warn('GraphQL error during extraction', {
+      message: err.message,
+      path: err.path,
+    });
+  });
+}
+```
+
+**Edge Case: Null Data with Errors**
+
+When GraphQL returns errors with `data: null` or `data: undefined`:
+
+```typescript
+// GraphQL response: { data: null, errors: [{ message: 'Order item not found' }] }
+const result = await orchestrator.extract({
+  query: ORDERS_QUERY,
+  resultPath: 'orders.edges.node',
+  errorHandling: 'partial',
+});
+
+// Returns empty array with errors in stats
+expect(result.data).toEqual([]);
+expect(result.stats.partialErrors).toHaveLength(1);
+```
+
+**Behavior:**
+- **Partial mode**: Returns empty array `[]`, accumulates errors in `stats.partialErrors`, stops pagination if no data
+- **Throw mode** (default): Throws `GraphQLExecutionError` immediately (backward compatible)
+
+**When to Use Partial Mode:**
+- ✅ Batch queries where some items may fail independently
+- ✅ Reporting/analytics where partial data is better than none
+- ✅ Non-critical extractions where you want to process available data
+
+**When to Use Throw Mode (default):**
+- ✅ Critical data where consistency matters
+- ✅ Single record operations
+- ✅ When you need to fail fast on any errors
+
 ### Common Error Scenarios
 
 | Error                          | Cause                        | Solution                                          |