@lgriffin/esi.ts 2.0.0 → 4.0.0

package/dist/core/errors/ApiError.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorHandler = exports.ApiError = exports.ApiErrorType = void 0;
+var ApiErrorType;
+(function (ApiErrorType) {
+    ApiErrorType["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ApiErrorType["AUTHENTICATION_ERROR"] = "AUTHENTICATION_ERROR";
+    ApiErrorType["AUTHORIZATION_ERROR"] = "AUTHORIZATION_ERROR";
+    ApiErrorType["RATE_LIMIT_ERROR"] = "RATE_LIMIT_ERROR";
+    ApiErrorType["SERVER_ERROR"] = "SERVER_ERROR";
+    ApiErrorType["CLIENT_ERROR"] = "CLIENT_ERROR";
+    ApiErrorType["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    ApiErrorType["NOT_FOUND_ERROR"] = "NOT_FOUND_ERROR";
+    ApiErrorType["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
+    ApiErrorType["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(ApiErrorType || (exports.ApiErrorType = ApiErrorType = {}));
+class ApiError extends Error {
+    constructor(message, type = ApiErrorType.UNKNOWN_ERROR, statusCode, details, requestId) {
+        super(message);
+        this.name = 'ApiError';
+        this.type = type;
+        this.statusCode = statusCode;
+        this.details = details;
+        this.timestamp = new Date();
+        this.requestId = requestId;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ApiError);
+        }
+    }
+    static fromHttpStatus(statusCode, message, details, requestId) {
+        let type;
+        switch (Math.floor(statusCode / 100)) {
+            case 4:
+                if (statusCode === 401) {
+                    type = ApiErrorType.AUTHENTICATION_ERROR;
+                }
+                else if (statusCode === 403) {
+                    type = ApiErrorType.AUTHORIZATION_ERROR;
+                }
+                else if (statusCode === 404) {
+                    type = ApiErrorType.NOT_FOUND_ERROR;
+                }
+                else if (statusCode === 429) {
+                    type = ApiErrorType.RATE_LIMIT_ERROR;
+                }
+                else {
+                    type = ApiErrorType.CLIENT_ERROR;
+                }
+                break;
+            case 5:
+                type = ApiErrorType.SERVER_ERROR;
+                break;
+            default:
+                type = ApiErrorType.UNKNOWN_ERROR;
+        }
+        return new ApiError(message, type, statusCode, details, requestId);
+    }
+    static networkError(message = 'Network connection failed', details) {
+        return new ApiError(message, ApiErrorType.NETWORK_ERROR, undefined, details);
+    }
+    static timeoutError(message = 'Request timeout', details) {
+        return new ApiError(message, ApiErrorType.TIMEOUT_ERROR, undefined, details);
+    }
+    static validationError(message, details) {
+        return new ApiError(message, ApiErrorType.VALIDATION_ERROR, 400, details);
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            type: this.type,
+            statusCode: this.statusCode,
+            details: this.details,
+            timestamp: this.timestamp.toISOString(),
+            requestId: this.requestId,
+            stack: this.stack
+        };
+    }
+}
+exports.ApiError = ApiError;
+class ErrorHandler {
+    static handle(error, requestId) {
+        var _a, _b, _c;
+        if (error instanceof ApiError) {
+            throw error;
+        }
+        // Handle Axios/HTTP errors
+        if (error.response) {
+            const statusCode = error.response.status;
+            const message = ((_a = error.response.data) === null || _a === void 0 ? void 0 : _a.error) ||
+                ((_b = error.response.data) === null || _b === void 0 ? void 0 : _b.message) ||
+                error.message ||
+                `HTTP ${statusCode} Error`;
+            throw ApiError.fromHttpStatus(statusCode, message, error.response.data, requestId);
+        }
+        // Handle network errors
+        if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND' || error.code === 'ECONNRESET') {
+            throw ApiError.networkError(`Network error: ${error.message}`, { code: error.code });
+        }
+        // Handle timeout errors
+        if (error.code === 'ECONNABORTED' || ((_c = error.message) === null || _c === void 0 ? void 0 : _c.includes('timeout'))) {
+            throw ApiError.timeoutError(`Request timeout: ${error.message}`);
+        }
+        // Default to unknown error
+        throw new ApiError(error.message || 'An unknown error occurred', ApiErrorType.UNKNOWN_ERROR, undefined, error, requestId);
+    }
+    static isRetryable(error) {
+        return [
+            ApiErrorType.NETWORK_ERROR,
+            ApiErrorType.TIMEOUT_ERROR,
+            ApiErrorType.SERVER_ERROR,
+            ApiErrorType.RATE_LIMIT_ERROR
+        ].includes(error.type);
+    }
+    static getRetryDelay(error, attempt) {
+        var _a, _b;
+        if (error.type === ApiErrorType.RATE_LIMIT_ERROR) {
+            // Check for Retry-After header in details
+            const retryAfter = (_b = (_a = error.details) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? void 0 : _b['retry-after'];
+            if (retryAfter) {
+                return parseInt(retryAfter) * 1000; // Convert to milliseconds
+            }
+        }
+        // Exponential backoff: 1s, 2s, 4s, 8s, etc.
+        return Math.min(1000 * Math.pow(2, attempt - 1), 30000); // Max 30 seconds
+    }
+}
+exports.ErrorHandler = ErrorHandler;

package/dist/core/factory/ApiFactory.js

@@ -0,0 +1,170 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiFactory = exports.ApiFactory = exports.ApiModule = void 0;
+const ApiClient_1 = require("../ApiClient");
+const Container_1 = require("../container/Container");
+const ApiError_1 = require("../errors/ApiError");
+const logger_1 = __importDefault(require("../logger/logger"));
+class ApiModule {
+    constructor(client, container) {
+        this.client = client;
+        this.container = container;
+    }
+}
+exports.ApiModule = ApiModule;
+class ApiFactory {
+    constructor() {
+        this.clients = new Map();
+        this.modules = new Map();
+        this.container = new Container_1.Container({
+            enableLogging: process.env.NODE_ENV === 'development',
+            enableCircularDependencyDetection: true
+        });
+        this.registerCoreServices();
+    }
+    static getInstance() {
+        if (!this.instance) {
+            this.instance = new ApiFactory();
+        }
+        return this.instance;
+    }
+    /**
+     * Register core services in the container
+     */
+    registerCoreServices() {
+        this.container.registerInstance('logger', logger_1.default);
+        this.container.registerInstance('errorHandler', ApiError_1.ErrorHandler);
+    }
+    /**
+     * Create and register an API client
+     */
+    createClient(name, config) {
+        try {
+            const client = new ApiClient_1.ApiClient(config.clientId, config.baseUrl, config.accessToken);
+            this.clients.set(name, client);
+            this.container.registerInstance(`client:${name}`, client);
+            logger_1.default.info(`API client '${name}' created and registered`);
+            return client;
+        }
+        catch (error) {
+            logger_1.default.error(`Failed to create API client '${name}':`, error);
+            throw ApiError_1.ErrorHandler.handle(error);
+        }
+    }
+    /**
+     * Get an existing API client
+     */
+    getClient(name) {
+        const client = this.clients.get(name);
+        if (!client) {
+            throw new ApiError_1.ApiError(`API client '${name}' not found. Available clients: ${Array.from(this.clients.keys()).join(', ')}`, ApiError_1.ApiErrorType.CLIENT_ERROR);
+        }
+        return client;
+    }
+    /**
+     * Register an API module
+     */
+    registerModule(module) {
+        try {
+            // Check dependencies
+            if (module.config.dependencies) {
+                for (const dependency of module.config.dependencies) {
+                    if (!this.container.has(dependency)) {
+                        throw new ApiError_1.ApiError(`Module '${module.config.name}' requires dependency '${dependency}' which is not registered`, ApiError_1.ApiErrorType.VALIDATION_ERROR);
+                    }
+                }
+            }
+            // Register the module
+            module.register();
+            this.modules.set(module.config.name, module);
+            this.container.registerInstance(`module:${module.config.name}`, module);
+            logger_1.default.info(`API module '${module.config.name}' v${module.config.version} registered`);
+        }
+        catch (error) {
+            logger_1.default.error(`Failed to register module '${module.config.name}':`, error);
+            throw ApiError_1.ErrorHandler.handle(error);
+        }
+    }
+    /**
+     * Get a service from the container
+     */
+    getService(token) {
+        try {
+            return this.container.resolve(token);
+        }
+        catch (error) {
+            logger_1.default.error(`Failed to resolve service '${token}':`, error);
+            throw ApiError_1.ErrorHandler.handle(error);
+        }
+    }
+    /**
+     * Register a service in the container
+     */
+    registerService(token, factory, singleton = false) {
+        try {
+            this.container.register(token, factory, singleton);
+            logger_1.default.debug(`Service '${token}' registered (singleton: ${singleton})`);
+        }
+        catch (error) {
+            logger_1.default.error(`Failed to register service '${token}':`, error);
+            throw ApiError_1.ErrorHandler.handle(error);
+        }
+    }
+    /**
+     * Get all registered clients
+     */
+    getRegisteredClients() {
+        return Array.from(this.clients.keys());
+    }
+    /**
+     * Get all registered modules
+     */
+    getRegisteredModules() {
+        return Array.from(this.modules.keys());
+    }
+    /**
+     * Health check for all registered clients
+     */
+    async healthCheck() {
+        const results = {};
+        for (const [name, client] of this.clients) {
+            try {
+                // Perform a simple health check (this would need to be implemented in ApiClient)
+                // For now, just check if client exists and has required properties
+                results[name] = !!(client && client.getLink());
+            }
+            catch (error) {
+                logger_1.default.warn(`Health check failed for client '${name}':`, error);
+                results[name] = false;
+            }
+        }
+        return results;
+    }
+    /**
+     * Shutdown factory and cleanup resources
+     */
+    async shutdown() {
+        try {
+            // Cleanup modules
+            for (const [name, module] of this.modules) {
+                logger_1.default.debug(`Shutting down module: ${name}`);
+                // If modules have cleanup methods, call them here
+            }
+            // Clear containers
+            this.container.clear();
+            this.clients.clear();
+            this.modules.clear();
+            logger_1.default.info('ApiFactory shutdown completed');
+        }
+        catch (error) {
+            logger_1.default.error('Error during ApiFactory shutdown:', error);
+            throw ApiError_1.ErrorHandler.handle(error);
+        }
+    }
+}
+exports.ApiFactory = ApiFactory;
+// Export singleton instance
+exports.apiFactory = ApiFactory.getInstance();

package/dist/core/logger/ILogger.d.ts

@@ -0,0 +1,7 @@
+export interface ILogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}
+//# sourceMappingURL=ILogger.d.ts.map

package/dist/core/logger/ILogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILogger.d.ts","sourceRoot":"","sources":["../../../src/core/logger/ILogger.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B"}

package/dist/core/logger/ILogger.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/logger/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './logger';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/logger/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}

package/dist/core/logger/index.js

@@ -0,0 +1,8 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(logger_1).default; } });

package/dist/core/logger/logger.d.ts

@@ -0,0 +1,3 @@
+declare const logger: import("winston").Logger;
+export default logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/core/logger/logger.ts"],"names":[],"mappings":"AAWA,QAAA,MAAM,MAAM,0BAIV,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/core/logger/logger.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const winston_1 = require("winston");
+const { combine, timestamp, printf, colorize } = winston_1.format;
+// Define custom log format
+const logFormat = printf(({ level, message, timestamp }) => {
+    return `${String(timestamp)} [${String(level)}]: ${String(message)}`;
+});
+// Create Winston logger instance — console only by default.
+// Libraries should not write to files; the consuming application controls logging.
+const logger = (0, winston_1.createLogger)({
+    level: process.env.ESI_LOG_LEVEL || 'warn',
+    format: combine(colorize(), timestamp(), logFormat),
+    transports: [new winston_1.transports.Console()],
+});
+exports.default = logger;

package/dist/core/logger/loggerUtil.d.ts

@@ -0,0 +1,9 @@
+import { ILogger } from './ILogger';
+export type { ILogger } from './ILogger';
+export declare const setLogger: (customLogger: ILogger) => void;
+export declare const getLogger: () => ILogger;
+export declare const logInfo: (message: string) => void;
+export declare const logError: (message: string) => void;
+export declare const logWarn: (message: string) => void;
+export declare const logDebug: (message: string) => void;
+//# sourceMappingURL=loggerUtil.d.ts.map

package/dist/core/logger/loggerUtil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loggerUtil.d.ts","sourceRoot":"","sources":["../../../src/core/logger/loggerUtil.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,eAAO,MAAM,SAAS,GAAI,cAAc,OAAO,KAAG,IAEjD,CAAC;AAEF,eAAO,MAAM,SAAS,QAAO,OAAuB,CAAC;AAErD,eAAO,MAAM,OAAO,GAAI,SAAS,MAAM,SAEtC,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,SAEvC,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,SAAS,MAAM,SAEtC,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,SAEvC,CAAC"}

package/dist/core/logger/loggerUtil.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logDebug = exports.logWarn = exports.logError = exports.logInfo = exports.getLogger = exports.setLogger = void 0;
+const logger_1 = __importDefault(require("./logger"));
+let activeLogger = logger_1.default;
+const setLogger = (customLogger) => {
+    activeLogger = customLogger;
+};
+exports.setLogger = setLogger;
+const getLogger = () => activeLogger;
+exports.getLogger = getLogger;
+const logInfo = (message) => {
+    activeLogger.info(message);
+};
+exports.logInfo = logInfo;
+const logError = (message) => {
+    activeLogger.error(message);
+};
+exports.logError = logError;
+const logWarn = (message) => {
+    activeLogger.warn(message);
+};
+exports.logWarn = logWarn;
+const logDebug = (message) => {
+    activeLogger.debug(message);
+};
+exports.logDebug = logDebug;

package/dist/core/middleware/Middleware.d.ts

@@ -0,0 +1,30 @@
+export interface RequestContext {
+    url: string;
+    endpoint: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: unknown;
+}
+export interface ResponseContext {
+    url: string;
+    endpoint: string;
+    method: string;
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+    durationMs: number;
+    fromCache: boolean;
+}
+export type RequestInterceptor = (context: RequestContext) => RequestContext | Promise<RequestContext>;
+export type ResponseInterceptor = (context: ResponseContext) => ResponseContext | Promise<ResponseContext>;
+export declare class MiddlewareManager {
+    private requestInterceptors;
+    private responseInterceptors;
+    addRequestInterceptor(fn: RequestInterceptor): () => void;
+    addResponseInterceptor(fn: ResponseInterceptor): () => void;
+    applyRequestInterceptors(context: RequestContext): Promise<RequestContext>;
+    applyResponseInterceptors(context: ResponseContext): Promise<ResponseContext>;
+    hasInterceptors(): boolean;
+    clear(): void;
+}
+//# sourceMappingURL=Middleware.d.ts.map

package/dist/core/middleware/Middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Middleware.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/Middleware.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,cAAc,KACpB,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAE9C,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,eAAe,KACrB,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAEhD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,mBAAmB,CAA4B;IACvD,OAAO,CAAC,oBAAoB,CAA6B;IAEzD,qBAAqB,CAAC,EAAE,EAAE,kBAAkB,GAAG,MAAM,IAAI;IASzD,sBAAsB,CAAC,EAAE,EAAE,mBAAmB,GAAG,MAAM,IAAI;IASrD,wBAAwB,CAC5B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC;IAQpB,yBAAyB,CAC7B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,eAAe,CAAC;IAQ3B,eAAe,IAAI,OAAO;IAO1B,KAAK,IAAI,IAAI;CAId"}

package/dist/core/middleware/Middleware.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiddlewareManager = void 0;
+class MiddlewareManager {
+    requestInterceptors = [];
+    responseInterceptors = [];
+    addRequestInterceptor(fn) {
+        this.requestInterceptors.push(fn);
+        return () => {
+            this.requestInterceptors = this.requestInterceptors.filter((i) => i !== fn);
+        };
+    }
+    addResponseInterceptor(fn) {
+        this.responseInterceptors.push(fn);
+        return () => {
+            this.responseInterceptors = this.responseInterceptors.filter((i) => i !== fn);
+        };
+    }
+    async applyRequestInterceptors(context) {
+        let ctx = context;
+        for (const interceptor of this.requestInterceptors) {
+            ctx = await interceptor(ctx);
+        }
+        return ctx;
+    }
+    async applyResponseInterceptors(context) {
+        let ctx = context;
+        for (const interceptor of this.responseInterceptors) {
+            ctx = await interceptor(ctx);
+        }
+        return ctx;
+    }
+    hasInterceptors() {
+        return (this.requestInterceptors.length > 0 ||
+            this.responseInterceptors.length > 0);
+    }
+    clear() {
+        this.requestInterceptors = [];
+        this.responseInterceptors = [];
+    }
+}
+exports.MiddlewareManager = MiddlewareManager;

package/dist/core/pagination/AsyncPaginationIterator.d.ts

@@ -0,0 +1,8 @@
+import { ApiClient } from '../ApiClient';
+export interface PageResult<T = unknown> {
+    data: T[];
+    page: number;
+    totalPages: number;
+}
+export declare function fetchPages<T = unknown>(client: ApiClient, endpoint: string, method: string, requiresAuth?: boolean, body?: unknown): AsyncGenerator<PageResult<T>, void, undefined>;
+//# sourceMappingURL=AsyncPaginationIterator.d.ts.map

package/dist/core/pagination/AsyncPaginationIterator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncPaginationIterator.d.ts","sourceRoot":"","sources":["../../../src/core/pagination/AsyncPaginationIterator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD,wBAAuB,UAAU,CAAC,CAAC,GAAG,OAAO,EAC3C,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,GAAE,OAAe,EAC7B,IAAI,CAAC,EAAE,OAAO,GACb,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAgChD"}

package/dist/core/pagination/AsyncPaginationIterator.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchPages = fetchPages;
+const ApiRequestHandler_1 = require("../ApiRequestHandler");
+const loggerUtil_1 = require("../logger/loggerUtil");
+function extractArray(body) {
+    if (Array.isArray(body))
+        return body;
+    if (body !== undefined && body !== null)
+        return [body];
+    return [];
+}
+async function* fetchPages(client, endpoint, method, requiresAuth = false, body) {
+    const firstResponse = await (0, ApiRequestHandler_1.handleRequest)(client, endpoint, method, body, requiresAuth);
+    const totalPages = parseInt(firstResponse.headers['x-pages'] || '1', 10);
+    yield { data: extractArray(firstResponse.body), page: 1, totalPages };
+    for (let page = 2; page <= totalPages; page++) {
+        const sep = endpoint.includes('?') ? '&' : '?';
+        const pagedEndpoint = `${endpoint}${sep}page=${page}`;
+        (0, loggerUtil_1.logInfo)(`Fetching page ${page}/${totalPages}: ${pagedEndpoint}`);
+        const response = await (0, ApiRequestHandler_1.handleRequest)(client, pagedEndpoint, method, body, requiresAuth);
+        const pageData = extractArray(response.body);
+        if (pageData.length === 0)
+            break;
+        yield { data: pageData, page, totalPages };
+    }
+}

package/dist/core/pagination/CursorPaginationHandler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Cursor-based Pagination Handler for ESI API calls.
+ *
+ * New ESI routes (starting with Corporation Projects) use opaque
+ * before/after cursor tokens instead of page numbers.
+ *
+ * Response headers:
+ *   x-cursor-before  – token to fetch data preceding the current batch
+ *   x-cursor-after   – token to fetch data following the current batch
+ *
+ * Query parameters:
+ *   before=<token>    – crawl backwards
+ *   after=<token>     – crawl forwards
+ *
+ * An empty result array signals the beginning/end of the dataset.
+ */
+import { ApiClient } from '../ApiClient';
+export interface CursorTokens {
+    before: string | null;
+    after: string | null;
+}
+export interface CursorPage<T = unknown> {
+    data: T[];
+    cursors: CursorTokens;
+}
+export interface CursorPaginationOptions {
+    maxPages?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+}
+export declare class CursorPaginationHandler {
+    private static readonly DEFAULT_OPTIONS;
+    /**
+     * Fetch a single cursor page, returning data + cursor tokens.
+     */
+    static fetchPage(client: ApiClient, endpoint: string, method: string, requiresAuth: boolean, cursor?: {
+        before?: string;
+        after?: string;
+    }, body?: unknown): Promise<CursorPage>;
+    /**
+     * Auto-fetch all pages by following `after` tokens until an empty
+     * response is received.  Combines the caller-supplied first page
+     * data with all subsequent pages.
+     */
+    static fetchAll(client: ApiClient, endpoint: string, method: string, requiresAuth: boolean, firstPageData: unknown[], firstCursors: CursorTokens, body?: unknown, options?: CursorPaginationOptions): Promise<unknown[]>;
+    /**
+     * Fetch a single cursor page with retry logic.
+     */
+    private static fetchPageWithRetry;
+    /**
+     * Extract cursor tokens from response headers.
+     */
+    static extractCursors(headers: Headers): CursorTokens;
+    /**
+     * Build a URL with cursor query parameters appended.
+     */
+    private static buildUrl;
+}
+//# sourceMappingURL=CursorPaginationHandler.d.ts.map

package/dist/core/pagination/CursorPaginationHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CursorPaginationHandler.d.ts","sourceRoot":"","sources":["../../../src/core/pagination/CursorPaginationHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAKzC,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAIrC;IAEF;;OAEG;WACU,SAAS,CACpB,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,OAAO,EACrB,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAC5C,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC;IAqCtB;;;;OAIG;WACU,QAAQ,CACnB,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,OAAO,EAAE,EACxB,YAAY,EAAE,YAAY,EAC1B,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,EAAE,CAAC;IAwDrB;;OAEG;mBACkB,kBAAkB;IAmCvC;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY;IAQrD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;CAmBxB"}