@fjell/client-api 4.4.17 → 4.4.19

package/dist/ClientApiOptions.d.ts

@@ -1,6 +1,7 @@
 import { Item } from "@fjell/core";
 import { ClientApi } from "./ClientApi";
 import { DeleteMethodOptions, GetMethodOptions, PostMethodOptions, PutMethodOptions } from "@fjell/http-api";
+import { RetryConfig } from "./http/HttpWrapper";
 export interface ClientApiOptions {
     readAuthenticated?: boolean;
     allAuthenticated?: boolean;
@@ -10,4 +11,10 @@ export interface ClientApiOptions {
     postOptions?: Partial<PostMethodOptions>;
     putOptions?: Partial<PutMethodOptions>;
     deleteOptions?: Partial<DeleteMethodOptions>;
+    /** Configuration for HTTP request retry behavior */
+    retryConfig?: RetryConfig;
+    /** Whether to enable comprehensive error handling and logging (default: true) */
+    enableErrorHandling?: boolean;
+    /** Custom error handler for additional error processing */
+    errorHandler?: (error: any, context?: Record<string, any>) => void;
 }

package/dist/errors/index.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Base class for all Client API errors
+ */
+export declare abstract class ClientApiError extends Error {
+    abstract readonly code: string;
+    abstract readonly isRetryable: boolean;
+    readonly timestamp: Date;
+    readonly context?: Record<string, any>;
+    constructor(message: string, context?: Record<string, any>);
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        isRetryable: boolean;
+        timestamp: Date;
+        context: Record<string, any> | undefined;
+        stack: string | undefined;
+    };
+}
+/**
+ * Network-related errors (connection issues, timeouts)
+ */
+export declare class NetworkError extends ClientApiError {
+    readonly code = "NETWORK_ERROR";
+    readonly isRetryable = true;
+    constructor(message: string, context?: Record<string, any>);
+}
+/**
+ * HTTP timeout errors
+ */
+export declare class TimeoutError extends ClientApiError {
+    readonly code = "TIMEOUT_ERROR";
+    readonly isRetryable = true;
+    constructor(timeout: number, context?: Record<string, any>);
+}
+/**
+ * Authentication errors (401 Unauthorized)
+ */
+export declare class AuthenticationError extends ClientApiError {
+    readonly code = "AUTHENTICATION_ERROR";
+    readonly isRetryable = false;
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Authorization errors (403 Forbidden)
+ */
+export declare class AuthorizationError extends ClientApiError {
+    readonly code = "AUTHORIZATION_ERROR";
+    readonly isRetryable = false;
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Resource not found errors (404 Not Found)
+ */
+export declare class NotFoundError extends ClientApiError {
+    readonly code = "NOT_FOUND_ERROR";
+    readonly isRetryable = false;
+    constructor(resource: string, identifier?: string, context?: Record<string, any>);
+}
+/**
+ * Request validation errors (400 Bad Request)
+ */
+export declare class ValidationError extends ClientApiError {
+    readonly code = "VALIDATION_ERROR";
+    readonly isRetryable = false;
+    readonly validationErrors?: Array<{
+        field: string;
+        message: string;
+    }>;
+    constructor(message: string, validationErrors?: Array<{
+        field: string;
+        message: string;
+    }>, context?: Record<string, any>);
+}
+/**
+ * Conflict errors (409 Conflict)
+ */
+export declare class ConflictError extends ClientApiError {
+    readonly code = "CONFLICT_ERROR";
+    readonly isRetryable = false;
+    constructor(message: string, context?: Record<string, any>);
+}
+/**
+ * Rate limiting errors (429 Too Many Requests)
+ */
+export declare class RateLimitError extends ClientApiError {
+    readonly code = "RATE_LIMIT_ERROR";
+    readonly isRetryable = true;
+    readonly retryAfter?: number;
+    constructor(retryAfter?: number, context?: Record<string, any>);
+}
+/**
+ * Server errors (5xx status codes)
+ */
+export declare class ServerError extends ClientApiError {
+    readonly code = "SERVER_ERROR";
+    readonly isRetryable = true;
+    readonly statusCode: number;
+    constructor(statusCode: number, message?: string, context?: Record<string, any>);
+}
+/**
+ * Request payload too large errors (413)
+ */
+export declare class PayloadTooLargeError extends ClientApiError {
+    readonly code = "PAYLOAD_TOO_LARGE_ERROR";
+    readonly isRetryable = false;
+    constructor(maxSize?: string, context?: Record<string, any>);
+}
+/**
+ * Generic HTTP errors for unhandled status codes
+ */
+export declare class HttpError extends ClientApiError {
+    readonly code = "HTTP_ERROR";
+    readonly isRetryable: boolean;
+    readonly statusCode: number;
+    readonly statusText: string;
+    constructor(statusCode: number, statusText: string, message?: string, context?: Record<string, any>);
+}
+/**
+ * Configuration errors
+ */
+export declare class ConfigurationError extends ClientApiError {
+    readonly code = "CONFIGURATION_ERROR";
+    readonly isRetryable = false;
+    constructor(message: string, context?: Record<string, any>);
+}
+/**
+ * Parse/serialization errors
+ */
+export declare class ParseError extends ClientApiError {
+    readonly code = "PARSE_ERROR";
+    readonly isRetryable = false;
+    constructor(message: string, context?: Record<string, any>);
+}
+/**
+ * Create appropriate error from HTTP response
+ */
+export declare function createHttpError(statusCode: number, statusText: string, responseBody?: any, context?: Record<string, any>): ClientApiError;
+/**
+ * Create appropriate error from network/connection issues
+ */
+export declare function createNetworkError(error: any, context?: Record<string, any>): ClientApiError;
+/**
+ * Type guard to check if error is retryable
+ */
+export declare function isRetryableError(error: any): boolean;
+/**
+ * Type guard to check if error is a Client API error
+ */
+export declare function isClientApiError(error: any): error is ClientApiError;

package/dist/http/HttpWrapper.d.ts

@@ -0,0 +1,61 @@
+import { HttpApi } from '@fjell/http-api';
+import { ClientApiError } from '../errors/index';
+/**
+ * Configuration for retry behavior
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay between retries in milliseconds (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay between retries in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Whether to add jitter to retry delays (default: true) */
+    enableJitter?: boolean;
+    /** Custom function to determine if an error should be retried */
+    shouldRetry?: (error: ClientApiError, attemptNumber: number) => boolean;
+    /** Called before each retry attempt */
+    onRetry?: (error: ClientApiError, attemptNumber: number, delay: number) => void;
+}
+/**
+ * Enhanced HTTP wrapper with retry logic and comprehensive error handling
+ */
+export declare class HttpWrapper {
+    private readonly api;
+    private readonly retryConfig;
+    constructor(api: HttpApi, retryConfig?: RetryConfig);
+    /**
+     * Execute HTTP operation with retry logic and error handling
+     */
+    executeWithRetry<T>(operation: () => Promise<T>, operationName: string, context?: Record<string, any>): Promise<T>;
+    /**
+     * Convert any error to a ClientApiError
+     */
+    private convertToClientApiError;
+    /**
+     * Wrapper for HTTP GET operations
+     */
+    get<T>(url: string, options?: any, context?: Record<string, any>): Promise<T>;
+    /**
+     * Wrapper for HTTP POST operations
+     */
+    post<T>(url: string, data?: any, options?: any, context?: Record<string, any>): Promise<T>;
+    /**
+     * Wrapper for HTTP PUT operations
+     */
+    put<T>(url: string, data?: any, options?: any, context?: Record<string, any>): Promise<T>;
+    /**
+     * Wrapper for HTTP DELETE operations
+     */
+    delete<T>(url: string, options?: any, context?: Record<string, any>): Promise<T>;
+    /**
+     * Update retry configuration
+     */
+    updateRetryConfig(newConfig: Partial<RetryConfig>): void;
+    /**
+     * Get current retry configuration
+     */
+    getRetryConfig(): Required<RetryConfig>;
+}

package/dist/index.d.ts

@@ -7,3 +7,6 @@ export { createPItemApi } from "./PItemAPI";
 export * from './Instance';
 export * from './InstanceFactory';
 export * from './Registry';
+export * from './errors/index';
+export * from './ops/errorHandling';
+export * from './http/HttpWrapper';