@emircansahin/ghostfetch 0.1.0

package/dist/esm/proxy-manager.js

@@ -0,0 +1,167 @@
+import { NoProxyAvailableError } from './errors';
+/** Failures within this window (ms) from different requests count as 1. */
+const DEDUP_WINDOW = 1000;
+/** How often to poll for an available proxy when waiting (ms). */
+const WAIT_POLL_INTERVAL = 2000;
+const DEFAULT_BAN = {
+    maxFailures: 3,
+    duration: 60 * 60 * 1000, // 1 hour
+};
+export class ProxyManager {
+    constructor(proxies, banConfig) {
+        this.proxies = [];
+        this.banMap = new Map();
+        this.countryMap = new Map(); // proxy → country code
+        this.proxies = [...proxies];
+        this.banConfig = banConfig === false ? false : { ...DEFAULT_BAN, ...banConfig };
+    }
+    /**
+     * Get a random non-banned proxy.
+     * Supports exclude (skip last failed proxy) and country filter.
+     * Returns null if none available.
+     */
+    getProxy(opts) {
+        // Backwards compat: allow passing just exclude string
+        const { exclude, country } = typeof opts === 'string' || opts === null || opts === undefined
+            ? { exclude: opts ?? undefined, country: undefined }
+            : opts;
+        let available = this.getAvailableProxies();
+        // Filter by country if requested
+        if (country) {
+            const upper = country.toUpperCase();
+            available = available.filter((p) => this.countryMap.get(p) === upper);
+        }
+        const candidates = exclude
+            ? available.filter((p) => p !== exclude)
+            : available;
+        // If excluding leaves nothing but there are available proxies, fall back
+        const pool = candidates.length > 0 ? candidates : available;
+        if (pool.length === 0)
+            return null;
+        return pool[Math.floor(Math.random() * pool.length)];
+    }
+    /**
+     * Wait until a proxy becomes available (bans expire or list is refreshed).
+     * Resolves with the proxy string. Supports country filter.
+     *
+     * Automatically calculates timeout from the earliest ban expiry.
+     * If no ban will ever expire (shouldn't happen), times out after 5 minutes.
+     */
+    waitForProxy(opts) {
+        const immediate = this.getProxy(opts);
+        if (immediate)
+            return Promise.resolve(immediate);
+        // Calculate max wait from earliest ban expiry + buffer
+        const maxWait = this.getEarliestBanExpiry() ?? 5 * 60 * 1000;
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                clearInterval(interval);
+                reject(new NoProxyAvailableError());
+            }, maxWait);
+            const interval = setInterval(() => {
+                const proxy = this.getProxy(opts);
+                if (proxy) {
+                    clearTimeout(timeout);
+                    clearInterval(interval);
+                    resolve(proxy);
+                }
+            }, WAIT_POLL_INTERVAL);
+        });
+    }
+    /** Get ms until the earliest ban expires, or null if no active bans. */
+    getEarliestBanExpiry() {
+        if (this.banConfig === false)
+            return null;
+        const now = Date.now();
+        let earliest = Infinity;
+        for (const [, entry] of this.banMap) {
+            if (!entry.bannedAt)
+                continue;
+            const expiresAt = entry.bannedAt + this.banConfig.duration;
+            const remaining = expiresAt - now;
+            if (remaining > 0 && remaining < earliest) {
+                earliest = remaining;
+            }
+        }
+        // Add 1s buffer so the ban is definitely expired when we check
+        return earliest === Infinity ? null : earliest + 1000;
+    }
+    /** Get all currently available (non-banned) proxies. */
+    getAvailableProxies() {
+        if (this.banConfig === false)
+            return [...this.proxies];
+        const now = Date.now();
+        const duration = this.banConfig.duration;
+        return this.proxies.filter((proxy) => {
+            const ban = this.banMap.get(proxy);
+            if (!ban)
+                return true;
+            if (!ban.bannedAt)
+                return true;
+            if (now - ban.bannedAt >= duration) {
+                this.banMap.delete(proxy);
+                return true;
+            }
+            return false;
+        });
+    }
+    /**
+     * Report a proxy failure. Returns true if the proxy got banned.
+     *
+     * Concurrent dedup: if the last failure was within DEDUP_WINDOW ms,
+     * this call is ignored (multiple parallel requests failing at the same
+     * moment count as a single failure).
+     */
+    reportFailure(proxy) {
+        if (this.banConfig === false)
+            return false;
+        const now = Date.now();
+        const entry = this.banMap.get(proxy);
+        if (entry && (now - entry.lastFailure) < DEDUP_WINDOW) {
+            // Check if actually still banned (not expired)
+            return entry.bannedAt > 0 && (now - entry.bannedAt) < this.banConfig.duration;
+        }
+        const failCount = (entry?.failCount ?? 0) + 1;
+        if (failCount >= this.banConfig.maxFailures) {
+            this.banMap.set(proxy, { bannedAt: now, failCount, lastFailure: now });
+            return true;
+        }
+        this.banMap.set(proxy, { bannedAt: 0, failCount, lastFailure: now });
+        return false;
+    }
+    /** Report a proxy success — resets its fail count. */
+    reportSuccess(proxy) {
+        this.banMap.delete(proxy);
+    }
+    /** Replace the proxy list and clear all bans + country data. */
+    replaceProxies(proxies) {
+        this.proxies = [...proxies];
+        this.banMap.clear();
+        this.countryMap.clear();
+    }
+    /** Set country for a proxy. */
+    setCountry(proxy, country) {
+        this.countryMap.set(proxy, country.toUpperCase());
+    }
+    /** Get country for a proxy (or undefined if not resolved). */
+    getCountry(proxy) {
+        return this.countryMap.get(proxy);
+    }
+    /** Get all proxies for a specific country. */
+    getProxiesByCountry(country) {
+        const upper = country.toUpperCase();
+        return this.proxies.filter((p) => this.countryMap.get(p) === upper);
+    }
+    /** Get total proxy count. */
+    get total() {
+        return this.proxies.length;
+    }
+    /** Get available (non-banned) proxy count. */
+    get available() {
+        return this.getAvailableProxies().length;
+    }
+    /** Get banned proxy count. */
+    get banned() {
+        return this.total - this.available;
+    }
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/classifier.d.ts

@@ -0,0 +1,36 @@
+import { ErrorType, GhostFetchResponse, Interceptor, InterceptorAction } from './types';
+/**
+ * Classify an error as proxy, server, or ambiguous.
+ *
+ * - proxy:     request definitely never reached the server (DNS fail, connection refused, etc.)
+ * - server:    an HTTP response was received — the proxy worked fine
+ * - ambiguous: could be either (timeout, connection reset) — proxy should NOT be penalized
+ */
+export declare function classifyError(error: unknown): ErrorType;
+/**
+ * Check if a successful response is actually a Cloudflare JS challenge.
+ */
+export declare function isCloudflareChallenge(response: GhostFetchResponse): boolean;
+export interface InterceptorResult {
+    /** Whether an interceptor matched this URL */
+    matched: boolean;
+    /** The action returned by check(), or null if not matched */
+    action: InterceptorAction;
+    /** The interceptor that matched (if any) */
+    interceptor?: Interceptor;
+}
+/**
+ * Run interceptors against a response.
+ *
+ * First interceptor whose `match` returns true takes ownership.
+ * Its `check` result determines the action. Default status handling
+ * is bypassed whenever an interceptor matches (even if check returns null).
+ */
+export declare function checkInterceptors(url: string, response: GhostFetchResponse, interceptors: Interceptor[]): InterceptorResult;
+/**
+ * Check if a response status code should trigger a default retry.
+ * Only called when no interceptor matched the URL.
+ * Returns the error type if retry should happen, or null if response is fine.
+ */
+export declare function checkDefaultRetryStatus(status: number): ErrorType | null;
+//# sourceMappingURL=classifier.d.ts.map

package/dist/types/classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../src/classifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAoDxF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAiCvD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAK3E;AAED,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,MAAM,EAAE,iBAAiB,CAAC;IAC1B,4CAA4C;IAC5C,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,kBAAkB,EAC5B,YAAY,EAAE,WAAW,EAAE,GAC1B,iBAAiB,CASnB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAExE"}

package/dist/types/client.d.ts

@@ -0,0 +1,68 @@
+import { GhostFetchConfig, GhostFetchResponse, HealthCheckResult, Interceptor, RequestOptions, HttpMethod } from './types';
+export declare class GhostFetch {
+    private cycleTLS;
+    private initPromise;
+    private proxyManager;
+    private interceptors;
+    private config;
+    private retryDefaults;
+    private refreshTimer;
+    private refreshing;
+    private healthCheckPromise;
+    constructor(config?: GhostFetchConfig);
+    /**
+     * Wait until the initial health check is complete.
+     * Returns health check results with proxy details and country info.
+     * Requests automatically wait for this internally.
+     *
+     * @example
+     * const result = await client.ready();
+     * console.log(result);
+     * // {
+     * //   total: 10, healthy: 8, dead: 2,
+     * //   countries: { US: 3, DE: 5 },
+     * //   proxies: { 'http://...@host:8001': 'US', 'http://...@host:8002': 'DE', ... }
+     * // }
+     */
+    ready(): Promise<HealthCheckResult>;
+    /** Lazy-initialize CycleTLS instance. */
+    private ensureClient;
+    /** Add a custom interceptor for site-specific error handling. */
+    addInterceptor(interceptor: Interceptor): void;
+    /** Remove an interceptor by name. */
+    removeInterceptor(name: string): void;
+    /** Manually refresh the proxy list via the onProxyRefresh callback. */
+    refreshProxies(): Promise<void>;
+    /** Get proxy manager stats. */
+    get stats(): {
+        totalProxies: number;
+        availableProxies: number;
+        bannedProxies: number;
+    };
+    get(url: string, options?: RequestOptions): Promise<GhostFetchResponse>;
+    post(url: string, options?: RequestOptions): Promise<GhostFetchResponse>;
+    put(url: string, options?: RequestOptions): Promise<GhostFetchResponse>;
+    delete(url: string, options?: RequestOptions): Promise<GhostFetchResponse>;
+    patch(url: string, options?: RequestOptions): Promise<GhostFetchResponse>;
+    head(url: string, options?: RequestOptions): Promise<GhostFetchResponse>;
+    request(method: HttpMethod, url: string, options?: RequestOptions): Promise<GhostFetchResponse>;
+    /**
+     * Pick a proxy based on forceProxy and country settings.
+     * - If forceProxy: wait until a proxy is available (blocks)
+     * - If !forceProxy: return null if none available (proceed without proxy)
+     */
+    private pickProxy;
+    /** Handle an interceptor action (retry/ban/skip). Returns 'return' to send response, or { error } to continue retry loop. */
+    private handleInterceptorAction;
+    private executeRequest;
+    /**
+     * Health check + country resolution for proxies.
+     * Each proxy gets up to 3 attempts (0s, +15s, +60s) to reach ipinfo.io.
+     * Healthy proxies are added to the pool with their country code.
+     * Failed proxies are discarded.
+     */
+    private healthCheckProxies;
+    /** Gracefully shut down the CycleTLS instance and clear timers. */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/types/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,cAAc,EAEd,UAAU,EACX,MAAM,SAAS,CAAC;AAQjB,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,kBAAkB,CAA2C;gBAEzD,MAAM,GAAE,gBAAqB;IAoBzC;;;;;;;;;;;;;OAaG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAKzC,yCAAyC;YAC3B,YAAY;IAa1B,iEAAiE;IACjE,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAI9C,qCAAqC;IACrC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIrC,uEAAuE;IACjE,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBrC,+BAA+B;IAC/B,IAAI,KAAK;;;;MAMR;IAIK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIvE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIxE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIvE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI1E,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIzE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMxE,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAoHrG;;;;OAIG;YACW,SAAS;IA+BvB,6HAA6H;IAC7H,OAAO,CAAC,uBAAuB;YAqCjB,cAAc;IAyD5B;;;;;OAKG;YACW,kBAAkB;IA6DhC,mEAAmE;IAC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAgB/B"}

package/dist/types/errors.d.ts

@@ -0,0 +1,21 @@
+import { ErrorType, GhostFetchError } from './types';
+export declare class GhostFetchRequestError extends Error implements GhostFetchError {
+    readonly type: ErrorType;
+    readonly status?: number;
+    readonly body?: string;
+    readonly proxy?: string;
+    readonly cause?: unknown;
+    constructor(opts: GhostFetchError);
+}
+export declare class CloudflareJSChallengeError extends GhostFetchRequestError {
+    constructor(url: string, proxy?: string);
+}
+export declare class NoProxyAvailableError extends Error {
+    constructor();
+}
+export declare class MaxRetriesExceededError extends Error {
+    readonly lastError: GhostFetchRequestError;
+    readonly attempts: number;
+    constructor(attempts: number, lastError: GhostFetchRequestError);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAErD,qBAAa,sBAAuB,SAAQ,KAAM,YAAW,eAAe;IAC1E,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,IAAI,EAAE,eAAe;CASlC;AAED,qBAAa,0BAA2B,SAAQ,sBAAsB;gBACxD,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAQxC;AAED,qBAAa,qBAAsB,SAAQ,KAAK;;CAK/C;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,sBAAsB;CAMhE"}

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export { GhostFetch } from './client';
+export { ProxyManager } from './proxy-manager';
+export { GhostFetchRequestError, CloudflareJSChallengeError, NoProxyAvailableError, MaxRetriesExceededError, } from './errors';
+export type { GhostFetchConfig, GhostFetchResponse, GhostFetchError, HealthCheckResult, Interceptor, InterceptorAction, RequestInterceptor, RequestOptions, RetryConfig, BanConfig, ErrorType, HttpMethod, } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,SAAS,EACT,SAAS,EACT,UAAU,GACX,MAAM,SAAS,CAAC"}

package/dist/types/proxy-manager.d.ts

@@ -0,0 +1,55 @@
+import { BanConfig } from './types';
+export interface GetProxyOptions {
+    exclude?: string | null;
+    country?: string;
+}
+export declare class ProxyManager {
+    private proxies;
+    private banMap;
+    private banConfig;
+    private countryMap;
+    constructor(proxies: string[], banConfig?: BanConfig | false);
+    /**
+     * Get a random non-banned proxy.
+     * Supports exclude (skip last failed proxy) and country filter.
+     * Returns null if none available.
+     */
+    getProxy(opts?: GetProxyOptions | string | null): string | null;
+    /**
+     * Wait until a proxy becomes available (bans expire or list is refreshed).
+     * Resolves with the proxy string. Supports country filter.
+     *
+     * Automatically calculates timeout from the earliest ban expiry.
+     * If no ban will ever expire (shouldn't happen), times out after 5 minutes.
+     */
+    waitForProxy(opts?: GetProxyOptions): Promise<string>;
+    /** Get ms until the earliest ban expires, or null if no active bans. */
+    private getEarliestBanExpiry;
+    /** Get all currently available (non-banned) proxies. */
+    getAvailableProxies(): string[];
+    /**
+     * Report a proxy failure. Returns true if the proxy got banned.
+     *
+     * Concurrent dedup: if the last failure was within DEDUP_WINDOW ms,
+     * this call is ignored (multiple parallel requests failing at the same
+     * moment count as a single failure).
+     */
+    reportFailure(proxy: string): boolean;
+    /** Report a proxy success — resets its fail count. */
+    reportSuccess(proxy: string): void;
+    /** Replace the proxy list and clear all bans + country data. */
+    replaceProxies(proxies: string[]): void;
+    /** Set country for a proxy. */
+    setCountry(proxy: string, country: string): void;
+    /** Get country for a proxy (or undefined if not resolved). */
+    getCountry(proxy: string): string | undefined;
+    /** Get all proxies for a specific country. */
+    getProxiesByCountry(country: string): string[];
+    /** Get total proxy count. */
+    get total(): number;
+    /** Get available (non-banned) proxy count. */
+    get available(): number;
+    /** Get banned proxy count. */
+    get banned(): number;
+}
+//# sourceMappingURL=proxy-manager.d.ts.map

package/dist/types/proxy-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-manager.d.ts","sourceRoot":"","sources":["../../src/proxy-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAoBpC,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,UAAU,CAA6B;gBAEnC,OAAO,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,KAAK;IAK5D;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI;IAyB/D;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBrD,wEAAwE;IACxE,OAAO,CAAC,oBAAoB;IAmB5B,wDAAwD;IACxD,mBAAmB,IAAI,MAAM,EAAE;IAiB/B;;;;;;OAMG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAsBrC,sDAAsD;IACtD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIlC,gEAAgE;IAChE,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAMvC,+BAA+B;IAC/B,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIhD,8DAA8D;IAC9D,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C,8CAA8C;IAC9C,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAK9C,6BAA6B;IAC7B,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,8CAA8C;IAC9C,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,8BAA8B;IAC9B,IAAI,MAAM,IAAI,MAAM,CAEnB;CACF"}

package/dist/types/types.d.ts

@@ -0,0 +1,141 @@
+export interface GhostFetchConfig {
+    /** List of proxy URLs in format http://user:pass@host:port */
+    proxies?: string[];
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Proxy ban configuration. Set to false to disable banning entirely. */
+    ban?: BanConfig | false;
+    /**
+     * If true, requests will wait until a proxy becomes available when all are
+     * banned. If false (default), requests proceed without a proxy when none
+     * are available.
+     */
+    forceProxy?: boolean;
+    /**
+     * Called periodically to refresh the proxy list.
+     * When called, all bans are cleared and the returned list replaces the current one.
+     */
+    onProxyRefresh?: () => Promise<string[]> | string[];
+    /** Interval in ms to call onProxyRefresh (default: 3600000 = 1 hour) */
+    proxyRefreshInterval?: number;
+    /** Default headers for all requests */
+    headers?: Record<string, string>;
+    /** CycleTLS JA3 fingerprint (optional — CycleTLS picks a realistic default) */
+    ja3?: string;
+    /** User-Agent string (optional — CycleTLS picks a realistic default) */
+    userAgent?: string;
+}
+export interface RetryConfig {
+    /**
+     * Delay before each retry in ms. Array length = number of retries.
+     *
+     * @example [5000, 15000, 30000] → 3 retries: wait 5s, 15s, 30s
+     * @default [1000, 2000, 4000]
+     */
+    delays?: number[];
+}
+export interface BanConfig {
+    /** Number of consecutive failures before banning a proxy (default: 3) */
+    maxFailures?: number;
+    /** Ban duration in ms (default: 3600000 = 1 hour) */
+    duration?: number;
+}
+/**
+ * Interceptor action returned by check():
+ * - 'retry' — retry with different proxy, current proxy is not penalized
+ * - 'ban'   — retry with different proxy AND penalize current proxy (fail counter +1)
+ * - 'skip'  — return response as-is, no retry, bypass all default handling
+ * - null    — interceptor doesn't care, fall through to default behavior
+ */
+export type InterceptorAction = 'retry' | 'ban' | 'skip' | null;
+export interface Interceptor {
+    /** Name for debugging purposes */
+    name?: string;
+    /** Return true if this interceptor applies to the given URL */
+    match: (url: string) => boolean;
+    /**
+     * Inspect the HTTP response and decide what to do.
+     *
+     * @returns
+     * - 'retry' — retry with different proxy (proxy is fine)
+     * - 'ban'   — retry + penalize this proxy
+     * - 'skip'  — return response directly, no retry, no default handling
+     * - null    — interceptor doesn't care, default behavior applies
+     */
+    check: (response: GhostFetchResponse) => InterceptorAction;
+}
+/**
+ * Per-request interceptor — same as Interceptor but without `match` and `name`
+ * since it applies to the specific request URL.
+ */
+export interface RequestInterceptor {
+    check: (response: GhostFetchResponse) => InterceptorAction;
+}
+export type ErrorType = 'proxy' | 'server' | 'ambiguous';
+export interface GhostFetchResponse {
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Response body as string */
+    body: string;
+    /** Final URL (after redirects) */
+    url: string;
+}
+export interface GhostFetchError {
+    /** Error type classification: proxy, server, or ambiguous */
+    type: ErrorType;
+    /** Error message */
+    message: string;
+    /** HTTP status code (if response was received) */
+    status?: number;
+    /** Response body (if response was received) */
+    body?: string;
+    /** The proxy URL that was used */
+    proxy?: string;
+    /** Original error */
+    cause?: unknown;
+}
+export interface RequestOptions {
+    /** Additional headers for this request */
+    headers?: Record<string, string>;
+    /** Override timeout for this request */
+    timeout?: number;
+    /** Request body (for POST, PUT, PATCH) */
+    body?: string | Record<string, unknown>;
+    /** Force a specific proxy for this request */
+    proxy?: string;
+    /** Override retry config for this request */
+    retry?: RetryConfig;
+    /**
+     * Override forceProxy for this request.
+     * If true, wait until a proxy is available. If false, proceed without proxy.
+     * Defaults to instance-level forceProxy (which defaults to false).
+     */
+    forceProxy?: boolean;
+    /**
+     * Per-request interceptor. Takes priority over instance-level interceptors.
+     * No `match` needed — it applies to this request's URL automatically.
+     */
+    interceptor?: RequestInterceptor;
+    /**
+     * Require a proxy from this country (ISO 3166-1 alpha-2, e.g. 'US', 'DE').
+     */
+    country?: string;
+}
+export interface HealthCheckResult {
+    /** Total proxies that were tested */
+    total: number;
+    /** Number of healthy proxies added to the pool */
+    healthy: number;
+    /** Number of dead proxies that were discarded */
+    dead: number;
+    /** Country distribution (e.g. { US: 3, DE: 5 }) */
+    countries: Record<string, number>;
+    /** Per-proxy detail: proxy → country or null if no country resolved */
+    proxies: Record<string, string | null>;
+}
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@emircansahin/ghostfetch",
+  "version": "0.1.0",
+  "description": "Resilient HTTP client with CycleTLS, proxy rotation, smart error classification, and per-site interceptors",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.esm.json && echo '{\"type\":\"module\"}' > dist/esm/package.json && tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "fetch",
+    "proxy",
+    "cycletls",
+    "cloudflare",
+    "bypass",
+    "rotation",
+    "resilient",
+    "scraping"
+  ],
+  "author": "Emircan Sahin",
+  "license": "MIT",
+  "dependencies": {
+    "cycletls": "^1.0.26",
+    "form-data": "^4.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}