@fluentcommerce/fc-connect-sdk 0.1.48 → 0.1.52

package/dist/cjs/services/extraction/extraction-orchestrator.js

@@ -20,13 +20,17 @@ class ExtractionOrchestrator {
         const pageSize = options.pageSize || this.DEFAULT_PAGE_SIZE;
         const timeout = options.timeout || this.DEFAULT_TIMEOUT;
         const direction = options.direction || 'forward';
+        const errorHandling = options.errorHandling || 'throw';
+        const accumulatedGraphQLErrors = [];
         this.logger.info('Starting data extraction', {
+            operationName: options.operationName || 'unnamed',
             resultPath: options.resultPath,
             pageSize,
             maxRecords: options.maxRecords,
             maxPages: options.maxPages,
             timeout,
             direction,
+            errorHandling,
         });
         try {
             const variables = {
@@ -36,16 +40,39 @@ class ExtractionOrchestrator {
             const response = await this.executeWithTimeout(this.client.graphql({
                 query: options.query,
                 variables,
+                ...(options.operationName && { operationName: options.operationName }),
+                errorHandling,
             }), timeout);
             if (response.errors && response.errors.length > 0) {
-                const graphqlError = new Error(`GraphQL errors: ${response.errors.map((e) => e.message).join(', ')}`);
-                this.logger.error('GraphQL query returned errors', graphqlError, {
-                    errors: response.errors,
+                if (errorHandling === 'partial') {
+                    this.logger.warn('GraphQL query returned partial data with errors (page 1)', {
+                        errors: response.errors,
+                        errorCount: response.errors.length,
+                        hasData: !!response.data,
+                    });
+                    accumulatedGraphQLErrors.push(...response.errors);
+                }
+                else {
+                    const graphqlError = new Error(`GraphQL errors: ${response.errors.map((e) => e.message).join(', ')}`);
+                    this.logger.error('GraphQL query returned errors', graphqlError, {
+                        errors: response.errors,
+                        errorCount: response.errors.length,
+                    });
+                    throw graphqlError;
+                }
+            }
+            let records = [];
+            if (response.data) {
+                records = this.extractFromPath(response.data, options.resultPath);
+            }
+            else if (errorHandling === 'partial' && response.errors && response.errors.length > 0) {
+                this.logger.warn('GraphQL response has errors but no data (page 1), returning empty records', {
                     errorCount: response.errors.length,
                 });
-                throw graphqlError;
             }
-            let records = this.extractFromPath(response.data, options.resultPath);
+            else if (!response.data) {
+                records = this.extractFromPath(response.data, options.resultPath);
+            }
             if (options.maxRecords && records.length > options.maxRecords) {
                 records = records.slice(0, options.maxRecords);
             }
@@ -59,14 +86,21 @@ class ExtractionOrchestrator {
             const rootPath = edgesIdx >= 0 ? pathParts.slice(0, edgesIdx).join('.') : pathParts.slice(0, -1).join('.');
             const pageInfoPath = rootPath ? `${rootPath}.pageInfo` : 'pageInfo';
             const edgesPath = edgesIdx >= 0 ? `${rootPath}.edges` : options.resultPath;
-            const firstPageInfo = this.safeGet(response.data, pageInfoPath) || {};
+            const firstPageInfo = response.data ? this.safeGet(response.data, pageInfoPath) || {} : {};
             let hasMore = direction === 'forward'
                 ? Boolean(firstPageInfo?.hasNextPage)
                 : Boolean(firstPageInfo?.hasPreviousPage);
-            if (direction === 'backward' && firstPageInfo?.hasPreviousPage === undefined) {
+            if (direction === 'backward' &&
+                response.data &&
+                firstPageInfo?.hasPreviousPage === undefined) {
                 throw new Error('Backward pagination requested but pageInfo.hasPreviousPage is missing from query response');
             }
-            let cursor = this.pickCursor(response.data, edgesPath, direction);
+            if (!response.data && errorHandling === 'partial' && accumulatedGraphQLErrors.length > 0) {
+                hasMore = false;
+            }
+            let cursor = response.data
+                ? this.pickCursor(response.data, edgesPath, direction)
+                : undefined;
             while (hasMore) {
                 if (options.maxPages && totalPages >= options.maxPages) {
                     truncated = true;
@@ -90,11 +124,40 @@ class ExtractionOrchestrator {
                 const nextPage = await this.executeWithTimeout(this.client.graphql({
                     query: options.query,
                     variables: nextVariables,
+                    ...(options.operationName && { operationName: options.operationName }),
+                    errorHandling,
                 }), timeout);
-                if (!nextPage || nextPage.errors) {
-                    throw new Error(`GraphQL extraction failed on subsequent page${nextPage?.errors ? `: ${JSON.stringify(nextPage.errors)}` : ''}`);
+                if (nextPage?.errors && nextPage.errors.length > 0) {
+                    if (errorHandling === 'partial') {
+                        this.logger.warn(`GraphQL query returned partial data with errors (page ${totalPages + 1})`, {
+                            errors: nextPage.errors,
+                            errorCount: nextPage.errors.length,
+                            hasData: !!nextPage.data,
+                        });
+                        accumulatedGraphQLErrors.push(...nextPage.errors);
+                    }
+                    else {
+                        throw new Error(`GraphQL extraction failed on subsequent page: ${JSON.stringify(nextPage.errors)}`);
+                    }
+                }
+                if (!nextPage) {
+                    throw new Error('GraphQL extraction failed on subsequent page: no response');
+                }
+                let pageRecords = [];
+                if (nextPage.data) {
+                    pageRecords = this.extractFromPath(nextPage.data, options.resultPath);
+                }
+                else if (errorHandling === 'partial' && nextPage.errors && nextPage.errors.length > 0) {
+                    this.logger.warn(`GraphQL response has errors but no data (page ${totalPages + 1}), stopping pagination`, {
+                        errorCount: nextPage.errors.length,
+                    });
+                    hasMore = false;
+                    cursor = undefined;
+                    continue;
+                }
+                else if (!nextPage.data) {
+                    pageRecords = this.extractFromPath(nextPage.data, options.resultPath);
                 }
-                let pageRecords = this.extractFromPath(nextPage.data, options.resultPath);
                 this.validateRecords(pageRecords, options.validateItem);
                 if (options.maxRecords && records.length + pageRecords.length > options.maxRecords) {
                     const remaining = options.maxRecords - records.length;
@@ -128,6 +191,7 @@ class ExtractionOrchestrator {
                 validRecords: finalValidation.validRecords,
                 invalidRecords: finalValidation.invalidRecords,
                 direction,
+                ...(accumulatedGraphQLErrors.length > 0 && { partialErrors: accumulatedGraphQLErrors }),
             };
             this.logger.info('Data extraction completed', {
                 totalRecords: stats.totalRecords,
@@ -136,7 +200,16 @@ class ExtractionOrchestrator {
                 truncated: stats.truncated,
                 truncationReason: stats.truncationReason,
                 direction,
+                hasPartialErrors: accumulatedGraphQLErrors.length > 0,
+                partialErrorCount: accumulatedGraphQLErrors.length,
             });
+            if (accumulatedGraphQLErrors.length > 0) {
+                this.logger.warn('Extraction completed with partial errors', {
+                    errorCount: accumulatedGraphQLErrors.length,
+                    recordsExtracted: stats.totalRecords,
+                    message: 'Some GraphQL errors occurred but extraction continued with available data.',
+                });
+            }
             if (stats.truncated) {
                 this.logger.warn('Extraction was truncated', {
                     reason: stats.truncationReason,

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

@@ -95,23 +95,91 @@ 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: string;
+    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;
     variables?: T;
     operationName?: string;
     pagination?: PaginationConfig;
+    errorHandling?: GraphQLErrorMode;
+}
+export interface GraphQLError {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: (string | number)[];
+    extensions?: Record<string, JsonValue>;
+    [key: string]: unknown;
 }
 export interface GraphQLResponse<T = JsonValue> {
     data?: T;
-    errors?: Array<{
-        message: string;
-        locations?: Array<{
-            line: number;
-            column: number;
-        }>;
-        path?: (string | number)[];
-        extensions?: Record<string, JsonValue>;
-    }>;
+    errors?: GraphQLError[];
     extensions?: Record<string, unknown> & {
         autoPagination?: {
             totalPages: number;
@@ -121,6 +189,7 @@ export interface GraphQLResponse<T = JsonValue> {
             direction?: 'forward' | 'backward';
         };
     };
+    hasPartialData?: boolean;
 }
 export interface FluentInventoryBatchEntity {
     locationRef: string;
@@ -359,7 +428,7 @@ export interface Logger {
     debug(message: string, meta?: Record<string, unknown> | undefined): void;
     info(message: string, meta?: Record<string, unknown> | undefined): void;
     warn(message: string, meta?: Record<string, unknown> | undefined): void;
-    error(message: string, error?: Error, meta?: Record<string, unknown> | undefined): void;
+    error(message: string, errorOrMeta?: unknown, meta?: Record<string, unknown>): void;
 }
 export interface LogContext {
     [key: string]: MetadataValue;

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

@@ -83,8 +83,9 @@ class FluentVersoriClient {
         });
         const paginationVars = (0, pagination_helpers_1.detectPaginationVariables)(payload.query);
         const paginationEnabled = !isMutation && (payload.pagination?.enabled ?? paginationVars.hasPagination);
+        const errorHandling = payload.errorHandling ?? 'throw';
         if (!paginationEnabled) {
-            return this.executeSinglePage(payload);
+            return this.executeSinglePage(payload, errorHandling);
         }
         const direction = payload.pagination?.direction ??
             paginationVars.direction ??
@@ -100,10 +101,11 @@ class FluentVersoriClient {
             abortSignal: payload.pagination?.abortSignal,
             onProgress: payload.pagination?.onProgress ?? (() => { }),
             onWarning: payload.pagination?.onWarning ?? ((msg) => this.ctx.log?.warn?.(msg)),
+            errorHandling,
         };
         return this.executeWithAutoPagination(payload, paginationVars, config);
     }
-    async executeSinglePage(payload) {
+    async executeSinglePage(payload, errorHandling = 'throw') {
         const operationName = payload.operationName || 'unnamed';
         try {
             const apiPayload = {
@@ -142,6 +144,18 @@ class FluentVersoriClient {
                 throw new Error('Failed to parse GraphQL response');
             }
             if (parsedResponse.errors && parsedResponse.errors.length > 0) {
+                if (errorHandling === 'partial') {
+                    this.ctx.log.warn(`[fc-connect-sdk:graphql] GraphQL operation "${operationName}" returned partial data with ${parsedResponse.errors.length} error(s)`, {
+                        operationName,
+                        errors: parsedResponse.errors,
+                        errorCount: parsedResponse.errors.length,
+                        hasData: !!parsedResponse.data,
+                    });
+                    return {
+                        ...parsedResponse,
+                        hasPartialData: true,
+                    };
+                }
                 this.ctx.log.error(`[fc-connect-sdk:graphql] GraphQL operation "${operationName}" returned ${parsedResponse.errors.length} error(s)`, {
                     operationName,
                     errors: parsedResponse.errors,
@@ -178,6 +192,7 @@ class FluentVersoriClient {
         let currentVariables = { ...(payload.variables || {}) };
         let lastCursor = null;
         let emptyPageCount = 0;
+        const accumulatedErrors = [];
         while (true) {
             if (config.abortSignal?.aborted) {
                 truncated = true;
@@ -200,17 +215,29 @@ class FluentVersoriClient {
             const response = await this.executeSinglePage({
                 query: payload.query,
                 variables: currentVariables,
-            });
+            }, 'partial');
             lastExtensions = response.extensions;
             if (response.errors && response.errors.length > 0) {
-                this.ctx.log.error(`[fc-connect-sdk: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.ctx.log.warn(`[fc-connect-sdk:pagination] Page ${pageNumber + 1} returned partial data with ${response.errors.length} error(s)`, {
+                        errors: response.errors,
+                        pagesCompleted: pageNumber,
+                        totalRecordsSoFar: totalRecords,
+                        errorCount: response.errors.length,
+                        hasData: !!response.data,
+                    });
+                    accumulatedErrors.push(...response.errors);
+                }
+                else {
+                    this.ctx.log.error(`[fc-connect-sdk: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);
+                }
             }
             pageNumber++;
             const connection = (0, pagination_helpers_1.extractConnection)(response.data, config.connectionPath);
@@ -313,14 +340,17 @@ class FluentVersoriClient {
                 await new Promise(resolve => setTimeout(resolve, config.delayMs));
             }
         }
-        this.ctx.log?.info?.(`[fc-connect-sdk:pagination] Pagination complete (${pageNumber} pages, ${totalRecords} records${truncated ? `, truncated: ${truncationReason}` : ''})`, {
+        const hasPartialErrors = accumulatedErrors.length > 0;
+        this.ctx.log?.info?.(`[fc-connect-sdk: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 || {}),
@@ -333,6 +363,11 @@ class FluentVersoriClient {
                 },
             },
         };
+        if (hasPartialErrors) {
+            response.errors = accumulatedErrors;
+            response.hasPartialData = true;
+        }
+        return response;
     }
     async sendEvent(event, mode = 'async') {
         this.ctx.log.info(`[fc-connect-sdk:event] Sending event "${event.name}" (${event.entityType}:${event.entityRef}, mode: ${mode})`, {
@@ -392,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,
@@ -539,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 });