@lgriffin/esi.ts 1.0.0 → 4.0.0

package/dist/core/pagination/CursorPaginationHandler.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CursorPaginationHandler = void 0;
+const loggerUtil_1 = require("../logger/loggerUtil");
+const constants_1 = require("../constants");
+const sleep_1 = require("../util/sleep");
+class CursorPaginationHandler {
+    static DEFAULT_OPTIONS = {
+        maxPages: 1000,
+        maxRetries: 3,
+        retryDelayMs: 1000,
+    };
+    /**
+     * Fetch a single cursor page, returning data + cursor tokens.
+     */
+    static async fetchPage(client, endpoint, method, requiresAuth, cursor, body) {
+        const url = this.buildUrl(client, endpoint, cursor);
+        (0, loggerUtil_1.logInfo)(`Cursor fetch: ${url}`);
+        const response = await fetch(url, {
+            method,
+            headers: {
+                accept: 'gzip, deflate, br',
+                'User-Agent': constants_1.USER_AGENT,
+                'X-Compatibility-Date': constants_1.COMPATIBILITY_DATE,
+                ...(requiresAuth
+                    ? { Authorization: client.getAuthorizationHeader() }
+                    : {}),
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        let data;
+        try {
+            const parsed = await response.json();
+            data = Array.isArray(parsed) ? parsed : [parsed];
+        }
+        catch (jsonError) {
+            throw new Error(`Invalid JSON response: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`);
+        }
+        const cursors = this.extractCursors(response.headers);
+        return { data, cursors };
+    }
+    /**
+     * 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 async fetchAll(client, endpoint, method, requiresAuth, firstPageData, firstCursors, body, options = {}) {
+        const opts = { ...this.DEFAULT_OPTIONS, ...options };
+        const rateLimiter = client.getRateLimiter();
+        const allData = [...firstPageData];
+        let afterToken = firstCursors.after;
+        let pageCount = 1;
+        let consecutiveFailures = 0;
+        while (afterToken && pageCount < opts.maxPages) {
+            try {
+                if (rateLimiter)
+                    await rateLimiter.checkRateLimit();
+                const page = await this.fetchPageWithRetry(client, endpoint, method, requiresAuth, { after: afterToken }, body, opts);
+                consecutiveFailures = 0;
+                pageCount++;
+                if (page.data.length === 0) {
+                    (0, loggerUtil_1.logInfo)('Cursor pagination: empty page received, dataset complete.');
+                    break;
+                }
+                allData.push(...page.data);
+                afterToken = page.cursors.after;
+                (0, loggerUtil_1.logInfo)(`Cursor page ${pageCount} fetched (${page.data.length} items)`);
+            }
+            catch (error) {
+                consecutiveFailures++;
+                (0, loggerUtil_1.logError)(`Cursor page fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+                if (consecutiveFailures >= opts.maxRetries) {
+                    (0, loggerUtil_1.logWarn)(`${consecutiveFailures} consecutive failures. Stopping cursor pagination.`);
+                    break;
+                }
+            }
+        }
+        (0, loggerUtil_1.logInfo)(`Cursor pagination complete. ${allData.length} total items from ${pageCount} pages.`);
+        return allData;
+    }
+    /**
+     * Fetch a single cursor page with retry logic.
+     */
+    static async fetchPageWithRetry(client, endpoint, method, requiresAuth, cursor, body, options) {
+        let lastError = null;
+        for (let attempt = 1; attempt <= options.maxRetries; attempt++) {
+            try {
+                return await this.fetchPage(client, endpoint, method, requiresAuth, cursor, body);
+            }
+            catch (error) {
+                lastError = error;
+                (0, loggerUtil_1.logWarn)(`Cursor fetch attempt ${attempt}/${options.maxRetries} failed: ${error instanceof Error ? error.message : String(error)}`);
+                if (attempt < options.maxRetries) {
+                    await (0, sleep_1.sleep)(options.retryDelayMs * attempt);
+                }
+            }
+        }
+        throw lastError || new Error('Cursor page fetch failed after all retries');
+    }
+    /**
+     * Extract cursor tokens from response headers.
+     */
+    static extractCursors(headers) {
+        const get = (name) => headers.get(name) || null;
+        return {
+            before: get('x-cursor-before'),
+            after: get('x-cursor-after'),
+        };
+    }
+    /**
+     * Build a URL with cursor query parameters appended.
+     */
+    static buildUrl(client, endpoint, cursor) {
+        let url = `${client.getLink()}/${endpoint}`;
+        if (!cursor)
+            return url;
+        const parts = [];
+        if (cursor.before)
+            parts.push(`before=${encodeURIComponent(cursor.before)}`);
+        if (cursor.after)
+            parts.push(`after=${encodeURIComponent(cursor.after)}`);
+        if (parts.length > 0) {
+            const separator = url.includes('?') ? '&' : '?';
+            url += separator + parts.join('&');
+        }
+        return url;
+    }
+}
+exports.CursorPaginationHandler = CursorPaginationHandler;

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

@@ -0,0 +1,30 @@
+/**
+ * Pagination Handler for ESI API calls
+ * Handles pagination with proper error handling and empty page detection
+ */
+import { ApiClient } from '../ApiClient';
+export interface PaginationOptions {
+    maxPages?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    stopOnEmptyPage?: boolean;
+}
+export type PageFetcher = (paginatedEndpoint: string) => Promise<unknown[]>;
+export declare class PaginationHandler {
+    private static readonly DEFAULT_OPTIONS;
+    /**
+     * Fetch remaining pages (2..totalPages) and combine with first page data.
+     * The caller has already fetched page 1 and knows the total page count.
+     */
+    static fetchRemainingPages(client: ApiClient, endpoint: string, method: string, requiresAuth: boolean, firstPageData: unknown[], totalPages: number, body?: unknown, options?: PaginationOptions, pageFetch?: PageFetcher): Promise<unknown[]>;
+    /**
+     * Fetch a single page with retry logic
+     */
+    private static fetchPageWithRetry;
+    /**
+     * Fetch a single page.
+     * Preserves any existing query params on the endpoint and appends page=N.
+     */
+    private static fetchSinglePage;
+}
+//# sourceMappingURL=PaginationHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PaginationHandler.d.ts","sourceRoot":"","sources":["../../../src/core/pagination/PaginationHandler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAKzC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;AAE5E,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAKrC;IAEF;;;OAGG;WACU,mBAAmB,CAC9B,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,OAAO,EAAE,EACxB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,GAAE,iBAAsB,EAC/B,SAAS,CAAC,EAAE,WAAW,GACtB,OAAO,CAAC,OAAO,EAAE,CAAC;IA8DrB;;OAEG;mBACkB,kBAAkB;IA2CvC;;;OAGG;mBACkB,eAAe;CAiDrC"}

package/dist/core/pagination/PaginationHandler.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Pagination Handler for ESI API calls
+ * Handles pagination with proper error handling and empty page detection
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginationHandler = void 0;
+const loggerUtil_1 = require("../logger/loggerUtil");
+const constants_1 = require("../constants");
+const sleep_1 = require("../util/sleep");
+class PaginationHandler {
+    static DEFAULT_OPTIONS = {
+        maxPages: 1000, // Reasonable limit to prevent infinite loops
+        maxRetries: 3,
+        retryDelayMs: 1000,
+        stopOnEmptyPage: true,
+    };
+    /**
+     * Fetch remaining pages (2..totalPages) and combine with first page data.
+     * The caller has already fetched page 1 and knows the total page count.
+     */
+    static async fetchRemainingPages(client, endpoint, method, requiresAuth, firstPageData, totalPages, body, options = {}, pageFetch) {
+        const opts = { ...this.DEFAULT_OPTIONS, ...options };
+        const rateLimiter = client.getRateLimiter();
+        const allData = [...firstPageData];
+        const effectiveMaxPage = Math.min(totalPages, opts.maxPages);
+        if (effectiveMaxPage <= 1) {
+            return allData;
+        }
+        (0, loggerUtil_1.logInfo)(`Fetching pages 2-${effectiveMaxPage} for ${endpoint}...`);
+        let consecutiveFailures = 0;
+        for (let page = 2; page <= effectiveMaxPage; page++) {
+            try {
+                if (rateLimiter)
+                    await rateLimiter.checkRateLimit();
+                const pageData = await this.fetchPageWithRetry(client, endpoint, method, page, requiresAuth, body, opts, pageFetch);
+                consecutiveFailures = 0;
+                if (opts.stopOnEmptyPage && (!pageData || pageData.length === 0)) {
+                    (0, loggerUtil_1.logWarn)(`Page ${page} is empty. Stopping pagination.`);
+                    break;
+                }
+                allData.push(...pageData);
+                (0, loggerUtil_1.logInfo)(`Fetched page ${page}/${effectiveMaxPage} (${pageData.length} items)`);
+            }
+            catch (error) {
+                consecutiveFailures++;
+                (0, loggerUtil_1.logError)(`Failed to fetch page ${page}: ${error instanceof Error ? error.message : String(error)}`);
+                if (consecutiveFailures >= opts.maxRetries) {
+                    (0, loggerUtil_1.logWarn)(`${consecutiveFailures} consecutive failures. Stopping pagination.`);
+                    break;
+                }
+            }
+        }
+        (0, loggerUtil_1.logInfo)(`Pagination complete. Fetched ${allData.length} total items from up to ${effectiveMaxPage} pages.`);
+        return allData;
+    }
+    /**
+     * Fetch a single page with retry logic
+     */
+    static async fetchPageWithRetry(client, endpoint, method, page, requiresAuth, body, options, pageFetch) {
+        let lastError = null;
+        for (let attempt = 1; attempt <= options.maxRetries; attempt++) {
+            try {
+                return await this.fetchSinglePage(client, endpoint, method, page, requiresAuth, body, pageFetch);
+            }
+            catch (error) {
+                lastError = error;
+                (0, loggerUtil_1.logWarn)(`Attempt ${attempt}/${options.maxRetries} failed for page ${page}: ${error instanceof Error ? error.message : String(error)}`);
+                if (attempt < options.maxRetries) {
+                    await (0, sleep_1.sleep)(options.retryDelayMs * attempt);
+                }
+            }
+        }
+        throw (lastError ||
+            new Error(`Failed to fetch page ${page} after ${options.maxRetries} attempts`));
+    }
+    /**
+     * Fetch a single page.
+     * Preserves any existing query params on the endpoint and appends page=N.
+     */
+    static async fetchSinglePage(client, endpoint, method, page, requiresAuth, body, pageFetch) {
+        const separator = endpoint.includes('?') ? '&' : '?';
+        const paginatedEndpoint = `${endpoint}${separator}page=${page}`;
+        if (pageFetch) {
+            (0, loggerUtil_1.logInfo)(`Fetching page ${page} via pipeline: ${paginatedEndpoint}`);
+            return pageFetch(paginatedEndpoint);
+        }
+        const url = `${client.getLink()}/${paginatedEndpoint}`;
+        (0, loggerUtil_1.logInfo)(`Fetching page ${page}: ${url}`);
+        const response = await fetch(url, {
+            method,
+            headers: {
+                accept: 'gzip, deflate, br',
+                'User-Agent': constants_1.USER_AGENT,
+                'X-Compatibility-Date': constants_1.COMPATIBILITY_DATE,
+                ...(requiresAuth
+                    ? { Authorization: client.getAuthorizationHeader() }
+                    : {}),
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        let data;
+        try {
+            data = (await response.json());
+        }
+        catch (jsonError) {
+            throw new Error(`Invalid JSON response for page ${page}: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`);
+        }
+        return Array.isArray(data) ? data : [data];
+    }
+}
+exports.PaginationHandler = PaginationHandler;

package/dist/core/rateLimiter/IRateLimiter.d.ts

@@ -0,0 +1,17 @@
+export interface IRateLimiter {
+    checkRateLimit(): Promise<void>;
+    updateFromResponse(headers: Record<string, string>, statusCode: number): void;
+    getStatus(): {
+        remaining: number;
+        limit: number;
+        used: number;
+        group: string | null;
+        errorLimitRemain: number;
+        errorLimitReset: number;
+        retryAfter: number | null;
+        blockedUntil: number;
+    };
+    isBlocked(): boolean;
+    reset(): void;
+}
+//# sourceMappingURL=IRateLimiter.d.ts.map

package/dist/core/rateLimiter/IRateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRateLimiter.d.ts","sourceRoot":"","sources":["../../../src/core/rateLimiter/IRateLimiter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9E,SAAS,IAAI;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,SAAS,IAAI,OAAO,CAAC;IACrB,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/core/rateLimiter/IRateLimiter.js

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

package/dist/core/rateLimiter/RateLimiter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Rate Limiter for ESI API calls
+ *
+ * Implements both the new floating-window rate limiting system and the legacy
+ * error-limit system per the official ESI documentation:
+ *
+ * New system (X-Ratelimit-* headers):
+ *   - Floating window with token bucket per IP+route group
+ *   - Token costs: 2xx = 2 tokens, 3xx = 1 token, 4xx = 5 tokens, 5xx = 0 tokens
+ *   - Returns 429 when bucket is empty, with Retry-After header
+ *
+ * Legacy system (x-esi-error-limit-* headers):
+ *   - 100 non-2xx/3xx errors per minute
+ *   - Returns 420 when limit exceeded, with Retry-After header
+ */
+import { IRateLimiter } from './IRateLimiter';
+export interface RateLimitInfo {
+    /** Tokens remaining in current window (new system) */
+    remaining: number;
+    /** Total token budget (new system) */
+    limit: number;
+    /** Tokens used in current window (new system) */
+    used: number;
+    /** Route group for this endpoint (new system) */
+    group: string | null;
+    /** Legacy error-limit remaining count */
+    errorLimitRemain: number;
+    /** Legacy error-limit seconds until reset */
+    errorLimitReset: number;
+    /** Retry-After value in seconds (set on 420/429) */
+    retryAfter: number | null;
+    /** Timestamp (ms) when we must stop sending requests */
+    blockedUntil: number;
+}
+export interface RateLimiterConfig {
+    minDelayMs?: number;
+    decelerationThreshold?: number;
+}
+export declare class RateLimiter implements IRateLimiter {
+    private rateLimitInfo;
+    private lastRequestTime;
+    private readonly minDelayMs;
+    private isTestMode;
+    private readonly decelerationThreshold;
+    constructor(config?: RateLimiterConfig);
+    private defaultInfo;
+    /**
+     * Update rate limit information from response headers and status code.
+     * Must be called on EVERY response, not just 2xx.
+     */
+    updateFromResponse(headers: Record<string, string>, statusCode: number): void;
+    /**
+     * Legacy method — kept for backwards compatibility.
+     * Prefer updateFromResponse() which also accepts status code.
+     */
+    updateRateLimitInfo(headers: Record<string, string>): void;
+    /**
+     * Check if we should wait before making the next request.
+     * Enforces hard blocks (420/429), proactive deceleration, and minimum delay.
+     */
+    checkRateLimit(): Promise<void>;
+    /**
+     * Enforce minimum delay between requests
+     */
+    private enforceMinDelay;
+    /** Get current rate limit status */
+    getStatus(): RateLimitInfo;
+    /** Get token cost for a given status code */
+    static getTokenCost(statusCode: number): number;
+    /** Check if currently blocked (420/429 backoff active) */
+    isBlocked(): boolean;
+    /** Set test mode (disables all delays) */
+    setTestMode(enabled: boolean): void;
+    /** Reset rate limiter state */
+    reset(): void;
+}
+//# sourceMappingURL=RateLimiter.d.ts.map

package/dist/core/rateLimiter/RateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimiter.d.ts","sourceRoot":"","sources":["../../../src/core/rateLimiter/RateLimiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAI9C,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;CACtB;AAkBD,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,UAAU,CAAkB;IAEpC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;gBAEnC,MAAM,CAAC,EAAE,iBAAiB;IAMtC,OAAO,CAAC,WAAW;IAanB;;;OAGG;IACH,kBAAkB,CAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,UAAU,EAAE,MAAM,GACjB,IAAI;IAkDP;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAI1D;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAyErC;;OAEG;YACW,eAAe;IAgB7B,oCAAoC;IACpC,SAAS,IAAI,aAAa;IAI1B,6CAA6C;IAC7C,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAI/C,0DAA0D;IAC1D,SAAS,IAAI,OAAO;IAIpB,0CAA0C;IAC1C,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAInC,+BAA+B;IAC/B,KAAK,IAAI,IAAI;CAId"}

package/dist/core/rateLimiter/RateLimiter.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Rate Limiter for ESI API calls
+ *
+ * Implements both the new floating-window rate limiting system and the legacy
+ * error-limit system per the official ESI documentation:
+ *
+ * New system (X-Ratelimit-* headers):
+ *   - Floating window with token bucket per IP+route group
+ *   - Token costs: 2xx = 2 tokens, 3xx = 1 token, 4xx = 5 tokens, 5xx = 0 tokens
+ *   - Returns 429 when bucket is empty, with Retry-After header
+ *
+ * Legacy system (x-esi-error-limit-* headers):
+ *   - 100 non-2xx/3xx errors per minute
+ *   - Returns 420 when limit exceeded, with Retry-After header
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+const loggerUtil_1 = require("../logger/loggerUtil");
+const sleep_1 = require("../util/sleep");
+/** Token costs per HTTP status code range, per ESI docs */
+const TOKEN_COSTS = {
+    '2xx': 2,
+    '3xx': 1,
+    '4xx': 5,
+    '5xx': 0,
+};
+function getTokenCost(statusCode) {
+    if (statusCode >= 200 && statusCode < 300)
+        return TOKEN_COSTS['2xx'];
+    if (statusCode >= 300 && statusCode < 400)
+        return TOKEN_COSTS['3xx'];
+    if (statusCode >= 400 && statusCode < 500)
+        return TOKEN_COSTS['4xx'];
+    if (statusCode >= 500 && statusCode < 600)
+        return TOKEN_COSTS['5xx'];
+    return 2; // default to 2xx cost
+}
+class RateLimiter {
+    rateLimitInfo;
+    lastRequestTime = 0;
+    minDelayMs;
+    isTestMode = false;
+    decelerationThreshold;
+    constructor(config) {
+        this.minDelayMs = config?.minDelayMs ?? 50;
+        this.decelerationThreshold = config?.decelerationThreshold ?? 0.2;
+        this.rateLimitInfo = this.defaultInfo();
+    }
+    defaultInfo() {
+        return {
+            remaining: -1, // -1 means "no data yet"
+            limit: 0,
+            used: 0,
+            group: null,
+            errorLimitRemain: 100,
+            errorLimitReset: 0,
+            retryAfter: null,
+            blockedUntil: 0,
+        };
+    }
+    /**
+     * Update rate limit information from response headers and status code.
+     * Must be called on EVERY response, not just 2xx.
+     */
+    updateFromResponse(headers, statusCode) {
+        if (this.isTestMode)
+            return;
+        // New rate limit headers (preferred)
+        const group = headers['x-ratelimit-group'] || null;
+        if ('x-ratelimit-remaining' in headers) {
+            this.rateLimitInfo.remaining = parseInt(headers['x-ratelimit-remaining'], 10);
+        }
+        if ('x-ratelimit-limit' in headers) {
+            this.rateLimitInfo.limit = parseInt(headers['x-ratelimit-limit'], 10);
+        }
+        if ('x-ratelimit-used' in headers) {
+            this.rateLimitInfo.used = parseInt(headers['x-ratelimit-used'], 10);
+        }
+        this.rateLimitInfo.group = group;
+        // Legacy error limit headers
+        if ('x-esi-error-limit-remain' in headers) {
+            this.rateLimitInfo.errorLimitRemain = parseInt(headers['x-esi-error-limit-remain'], 10);
+        }
+        if ('x-esi-error-limit-reset' in headers) {
+            this.rateLimitInfo.errorLimitReset = parseInt(headers['x-esi-error-limit-reset'], 10);
+        }
+        // Retry-After (present on 420 and 429 responses)
+        if ('retry-after' in headers) {
+            const retrySeconds = parseInt(headers['retry-after'], 10);
+            this.rateLimitInfo.retryAfter = retrySeconds;
+            this.rateLimitInfo.blockedUntil = Date.now() + retrySeconds * 1000;
+        }
+        // Handle 420 (legacy error limited) and 429 (new rate limited)
+        if (statusCode === 420 || statusCode === 429) {
+            if (!this.rateLimitInfo.retryAfter) {
+                // No Retry-After header — default to 60 seconds for safety
+                this.rateLimitInfo.blockedUntil = Date.now() + 60_000;
+            }
+        }
+    }
+    /**
+     * Legacy method — kept for backwards compatibility.
+     * Prefer updateFromResponse() which also accepts status code.
+     */
+    updateRateLimitInfo(headers) {
+        this.updateFromResponse(headers, 200);
+    }
+    /**
+     * Check if we should wait before making the next request.
+     * Enforces hard blocks (420/429), proactive deceleration, and minimum delay.
+     */
+    async checkRateLimit() {
+        if (this.isTestMode)
+            return;
+        const now = Date.now();
+        // Hard block: we received a 420/429 and must wait
+        if (this.rateLimitInfo.blockedUntil > now) {
+            const waitTime = this.rateLimitInfo.blockedUntil - now;
+            (0, loggerUtil_1.logWarn)(`[ESI Rate Limit] Blocked for ${Math.ceil(waitTime / 1000)}s (420/429 received)`);
+            await (0, sleep_1.sleep)(waitTime);
+            // Clear the block after waiting
+            this.rateLimitInfo.blockedUntil = 0;
+            this.rateLimitInfo.retryAfter = null;
+            return;
+        }
+        // Legacy error limit: if remaining errors are very low, slow down
+        if (this.rateLimitInfo.errorLimitRemain <= 10 &&
+            this.rateLimitInfo.errorLimitRemain > 0) {
+            const resetMs = this.rateLimitInfo.errorLimitReset * 1000;
+            const delay = Math.min(resetMs, 5000); // cap at 5s
+            if (delay > 0) {
+                (0, loggerUtil_1.logWarn)(`[ESI Rate Limit] Legacy error limit low (${this.rateLimitInfo.errorLimitRemain}), waiting ${delay}ms`);
+                await (0, sleep_1.sleep)(delay);
+                return;
+            }
+        }
+        // Legacy error limit: completely exhausted
+        if (this.rateLimitInfo.errorLimitRemain <= 0 &&
+            this.rateLimitInfo.errorLimitReset > 0) {
+            const waitTime = this.rateLimitInfo.errorLimitReset * 1000;
+            (0, loggerUtil_1.logWarn)(`[ESI Rate Limit] Legacy error limit exhausted, waiting ${Math.ceil(waitTime / 1000)}s`);
+            await (0, sleep_1.sleep)(waitTime);
+            return;
+        }
+        // Proactive deceleration: if new-system remaining is known and getting low
+        if (this.rateLimitInfo.remaining >= 0 && this.rateLimitInfo.limit > 0) {
+            const ratio = this.rateLimitInfo.remaining / this.rateLimitInfo.limit;
+            if (this.rateLimitInfo.remaining <= 0) {
+                // Bucket empty — wait before next request
+                (0, loggerUtil_1.logWarn)('[ESI Rate Limit] Token bucket empty, waiting 1s');
+                await (0, sleep_1.sleep)(1000);
+                return;
+            }
+            if (ratio <= this.decelerationThreshold) {
+                // Linearly increase delay as remaining approaches 0
+                // At 20% remaining: ~50ms extra, at 1% remaining: ~1000ms extra
+                const extraDelay = Math.ceil((1 - ratio / this.decelerationThreshold) * 1000);
+                await (0, sleep_1.sleep)(extraDelay);
+                return;
+            }
+        }
+        // Minimum delay between requests
+        await this.enforceMinDelay();
+    }
+    /**
+     * Enforce minimum delay between requests
+     */
+    async enforceMinDelay() {
+        if (this.isTestMode) {
+            this.lastRequestTime = Date.now();
+            return;
+        }
+        const now = Date.now();
+        const timeSinceLastRequest = now - this.lastRequestTime;
+        if (timeSinceLastRequest < this.minDelayMs) {
+            await (0, sleep_1.sleep)(this.minDelayMs - timeSinceLastRequest);
+        }
+        this.lastRequestTime = Date.now();
+    }
+    /** Get current rate limit status */
+    getStatus() {
+        return { ...this.rateLimitInfo };
+    }
+    /** Get token cost for a given status code */
+    static getTokenCost(statusCode) {
+        return getTokenCost(statusCode);
+    }
+    /** Check if currently blocked (420/429 backoff active) */
+    isBlocked() {
+        return this.rateLimitInfo.blockedUntil > Date.now();
+    }
+    /** Set test mode (disables all delays) */
+    setTestMode(enabled) {
+        this.isTestMode = enabled;
+    }
+    /** Reset rate limiter state */
+    reset() {
+        this.rateLimitInfo = this.defaultInfo();
+        this.lastRequestTime = 0;
+    }
+}
+exports.RateLimiter = RateLimiter;

package/dist/core/util/error.d.ts

@@ -0,0 +1,23 @@
+export declare class EsiError extends Error {
+    readonly statusCode: number;
+    readonly requestId?: string | undefined;
+    readonly url?: string;
+    constructor(statusCode: number, message: string, url?: string, requestId?: string | undefined);
+    isRateLimited(): boolean;
+    isNotFound(): boolean;
+    isUnauthorized(): boolean;
+    isForbidden(): boolean;
+    isServerError(): boolean;
+    isTimeout(): boolean;
+    get retryable(): boolean;
+}
+export declare function isEsiError(error: unknown): error is EsiError;
+export declare function isRateLimited(error: unknown): error is EsiError;
+export declare function isNotFound(error: unknown): error is EsiError;
+export declare function isUnauthorized(error: unknown): error is EsiError;
+export declare function isForbidden(error: unknown): error is EsiError;
+export declare function isServerError(error: unknown): error is EsiError;
+export declare function isTimeout(error: unknown): error is EsiError;
+export declare function isRetryable(error: unknown): error is EsiError;
+export declare const buildError: (message: string, type?: string, url?: string) => Error;
+//# sourceMappingURL=error.d.ts.map

package/dist/core/util/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/core/util/error.ts"],"names":[],"mappings":"AAiBA,qBAAa,QAAS,SAAQ,KAAK;aAIf,UAAU,EAAE,MAAM;aAGlB,SAAS,CAAC,EAAE,MAAM;IANpC,SAAgB,GAAG,CAAC,EAAE,MAAM,CAAC;gBAGX,UAAU,EAAE,MAAM,EAClC,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,EACI,SAAS,CAAC,EAAE,MAAM,YAAA;IAOpC,aAAa,IAAI,OAAO;IAIxB,UAAU,IAAI,OAAO;IAIrB,cAAc,IAAI,OAAO;IAIzB,WAAW,IAAI,OAAO;IAItB,aAAa,IAAI,OAAO;IAIxB,SAAS,IAAI,OAAO;IAIpB,IAAI,SAAS,IAAI,OAAO,CASvB;CACF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE/D;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAEhE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE7D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE/D;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE7D;AAED,eAAO,MAAM,UAAU,GACrB,SAAS,MAAM,EACf,OAAM,MAAgB,EACtB,MAAM,MAAM,KACX,KAMF,CAAC"}