@emircansahin/ghostfetch 0.1.0

package/dist/cjs/proxy-manager.js.map

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

package/dist/cjs/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/esm/classifier.js

@@ -0,0 +1,111 @@
+/** Error codes that are definitely proxy/network failures — request never reached the server. */
+const PROXY_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'EPIPE',
+]);
+/** Error codes that could be proxy OR server — we can't tell for sure. */
+const AMBIGUOUS_ERROR_CODES = new Set([
+    'ETIMEDOUT',
+    'ECONNRESET',
+    'ECONNABORTED',
+]);
+const PROXY_ERROR_KEYWORDS = [
+    'proxy',
+    'tunnel',
+    'connect econnrefused',
+];
+const AMBIGUOUS_ERROR_KEYWORDS = [
+    'socket hang up',
+    'timeout',
+];
+/** Cloudflare JS challenge detection patterns */
+const CF_CHALLENGE_PATTERNS = [
+    'cf-browser-verification',
+    'cf_chl_opt',
+    'jschl_vc',
+    'jschl_answer',
+    'Checking your browser',
+    'Just a moment...',
+    '_cf_chl_tk',
+];
+/**
+ * Default status codes that should trigger retry.
+ * - 'server': retry with different proxy, proxy is not penalized
+ * - 'proxy': retry with different proxy, proxy fail count incremented
+ */
+const DEFAULT_RETRY_STATUSES = {
+    429: 'server', // Rate limit — not proxy's fault, just retry with different IP
+    503: 'server', // Service unavailable — server overloaded
+    407: 'proxy', // Proxy authentication required — proxy is broken
+};
+/**
+ * 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 function classifyError(error) {
+    if (error && typeof error === 'object') {
+        const err = error;
+        // If there's an HTTP status code, the request reached the server → server error
+        if (err.status && typeof err.status === 'number') {
+            return 'server';
+        }
+        const code = (err.code || err.errno);
+        const message = (err.message || '').toLowerCase();
+        // Check definite proxy errors first
+        if (code && PROXY_ERROR_CODES.has(code)) {
+            return 'proxy';
+        }
+        if (PROXY_ERROR_KEYWORDS.some((kw) => message.includes(kw))) {
+            return 'proxy';
+        }
+        // Check ambiguous errors
+        if (code && AMBIGUOUS_ERROR_CODES.has(code)) {
+            return 'ambiguous';
+        }
+        if (AMBIGUOUS_ERROR_KEYWORDS.some((kw) => message.includes(kw))) {
+            return 'ambiguous';
+        }
+    }
+    // Default: treat unknown errors as server errors (keep proxies alive)
+    return 'server';
+}
+/**
+ * Check if a successful response is actually a Cloudflare JS challenge.
+ */
+export function isCloudflareChallenge(response) {
+    if (response.status === 403 || response.status === 503) {
+        return CF_CHALLENGE_PATTERNS.some((pattern) => response.body.includes(pattern));
+    }
+    return false;
+}
+/**
+ * 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 function checkInterceptors(url, response, interceptors) {
+    for (const interceptor of interceptors) {
+        if (!interceptor.match(url))
+            continue;
+        const action = interceptor.check(response);
+        return { matched: true, action, interceptor };
+    }
+    return { matched: false, action: null };
+}
+/**
+ * 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 function checkDefaultRetryStatus(status) {
+    return DEFAULT_RETRY_STATUSES[status] ?? null;
+}

package/dist/esm/client.js

@@ -0,0 +1,403 @@
+import initCycleTLS from 'cycletls';
+import { ProxyManager } from './proxy-manager';
+import { classifyError, isCloudflareChallenge, checkInterceptors, checkDefaultRetryStatus } from './classifier';
+import { GhostFetchRequestError, CloudflareJSChallengeError, NoProxyAvailableError, MaxRetriesExceededError } from './errors';
+const DEFAULT_DELAYS = [1000, 2000, 4000];
+const DEFAULT_TIMEOUT = 30000;
+const HEALTH_BATCH_CONCURRENCY = 10;
+const HEALTH_RETRY_DELAYS = [0, 15000, 60000]; // immediate, +15s, +60s
+export class GhostFetch {
+    constructor(config = {}) {
+        this.cycleTLS = null;
+        this.initPromise = null;
+        this.interceptors = [];
+        this.refreshTimer = null;
+        this.refreshing = false;
+        this.healthCheckPromise = null;
+        this.config = config;
+        // Start with empty proxy list — healthCheck will populate it
+        this.proxyManager = new ProxyManager([], config.ban);
+        this.retryDefaults = { delays: config.retry?.delays ?? DEFAULT_DELAYS };
+        // Auto health check on init if proxies provided
+        if (config.proxies?.length) {
+            this.healthCheckPromise = this.healthCheckProxies(config.proxies).catch((err) => {
+                // Prevent unhandled rejection — return empty result so ready() resolves safely
+                return { total: config.proxies.length, healthy: 0, dead: config.proxies.length, countries: {}, proxies: {} };
+            });
+        }
+        // Start proxy refresh interval only if both callback and interval are provided
+        if (config.onProxyRefresh && config.proxyRefreshInterval) {
+            this.refreshTimer = setInterval(() => this.refreshProxies(), config.proxyRefreshInterval);
+        }
+    }
+    /**
+     * 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', ... }
+     * // }
+     */
+    async ready() {
+        if (this.healthCheckPromise)
+            return this.healthCheckPromise;
+        return { total: 0, healthy: 0, dead: 0, countries: {}, proxies: {} };
+    }
+    /** Lazy-initialize CycleTLS instance. */
+    async ensureClient() {
+        if (this.cycleTLS)
+            return this.cycleTLS;
+        if (!this.initPromise) {
+            this.initPromise = initCycleTLS().then((client) => {
+                this.cycleTLS = client;
+            });
+        }
+        await this.initPromise;
+        return this.cycleTLS;
+    }
+    /** Add a custom interceptor for site-specific error handling. */
+    addInterceptor(interceptor) {
+        this.interceptors.push(interceptor);
+    }
+    /** Remove an interceptor by name. */
+    removeInterceptor(name) {
+        this.interceptors = this.interceptors.filter((i) => i.name !== name);
+    }
+    /** Manually refresh the proxy list via the onProxyRefresh callback. */
+    async refreshProxies() {
+        if (!this.config.onProxyRefresh)
+            return;
+        if (this.refreshing)
+            return; // prevent overlapping refreshes
+        // Wait for any in-progress health check (e.g., initial startup)
+        if (this.healthCheckPromise)
+            await this.healthCheckPromise;
+        this.refreshing = true;
+        try {
+            const proxies = await this.config.onProxyRefresh();
+            // Health check first — only replace if it succeeds
+            // healthCheckProxies calls replaceProxies internally with healthy list
+            await this.healthCheckProxies(proxies);
+        }
+        finally {
+            this.refreshing = false;
+        }
+    }
+    /** Get proxy manager stats. */
+    get stats() {
+        return {
+            totalProxies: this.proxyManager.total,
+            availableProxies: this.proxyManager.available,
+            bannedProxies: this.proxyManager.banned,
+        };
+    }
+    // --- HTTP methods ---
+    async get(url, options) {
+        return this.request('GET', url, options);
+    }
+    async post(url, options) {
+        return this.request('POST', url, options);
+    }
+    async put(url, options) {
+        return this.request('PUT', url, options);
+    }
+    async delete(url, options) {
+        return this.request('DELETE', url, options);
+    }
+    async patch(url, options) {
+        return this.request('PATCH', url, options);
+    }
+    async head(url, options) {
+        return this.request('HEAD', url, options);
+    }
+    // --- Core request logic ---
+    async request(method, url, options) {
+        // Wait for health check to finish before first request
+        await this.ready();
+        const delays = options?.retry?.delays ?? this.retryDefaults.delays ?? DEFAULT_DELAYS;
+        const maxAttempts = delays.length + 1; // first attempt + retries
+        const forceProxy = options?.forceProxy ?? this.config.forceProxy ?? false;
+        let lastError = null;
+        let lastFailedProxy = null;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            // Wait before retry (not on first attempt)
+            if (attempt > 0) {
+                await sleep(delays[attempt - 1]);
+            }
+            // Pick a proxy
+            const proxy = options?.proxy ?? await this.pickProxy(forceProxy, lastFailedProxy, options?.country);
+            try {
+                const response = await this.executeRequest(method, url, proxy, options);
+                // 1. Per-request interceptor takes highest priority
+                if (options?.interceptor) {
+                    const reqAction = options.interceptor.check(response);
+                    if (reqAction !== null) {
+                        const result = this.handleInterceptorAction(reqAction, 'request', response, proxy);
+                        if (result === 'return') {
+                            return response;
+                        }
+                        lastError = result.error;
+                        lastFailedProxy = proxy;
+                        continue;
+                    }
+                    // null → fall through to instance interceptors
+                }
+                // 2. Instance-level interceptors — first match takes full ownership
+                const { matched, action, interceptor } = checkInterceptors(url, response, [...this.interceptors]);
+                if (matched) {
+                    if (action === 'skip' || action === null) {
+                        if (proxy)
+                            this.proxyManager.reportSuccess(proxy);
+                        return response;
+                    }
+                    const result = this.handleInterceptorAction(action, interceptor?.name ?? 'unnamed', response, proxy);
+                    if (result === 'return') {
+                        return response;
+                    }
+                    lastError = result.error;
+                    lastFailedProxy = proxy;
+                    continue;
+                }
+                // 3. Cloudflare JS challenge (only when no interceptor claimed the response)
+                if (isCloudflareChallenge(response)) {
+                    throw new CloudflareJSChallengeError(url, proxy ?? undefined);
+                }
+                // 4. No interceptor matched → check default retry statuses (429, 503, 407)
+                const defaultRetry = checkDefaultRetryStatus(response.status);
+                if (defaultRetry) {
+                    if (proxy) {
+                        if (defaultRetry === 'proxy') {
+                            this.proxyManager.reportFailure(proxy);
+                        }
+                        else {
+                            this.proxyManager.reportSuccess(proxy);
+                        }
+                    }
+                    lastError = new GhostFetchRequestError({
+                        type: defaultRetry,
+                        message: `HTTP ${response.status}`,
+                        status: response.status,
+                        body: response.body,
+                        proxy: proxy ?? undefined,
+                    });
+                    lastFailedProxy = proxy;
+                    continue;
+                }
+                // 4. Normal response — return it
+                if (proxy)
+                    this.proxyManager.reportSuccess(proxy);
+                return response;
+            }
+            catch (error) {
+                if (error instanceof CloudflareJSChallengeError) {
+                    throw error;
+                }
+                if (error instanceof NoProxyAvailableError) {
+                    throw error;
+                }
+                const errorType = classifyError(error);
+                const requestError = error instanceof GhostFetchRequestError
+                    ? error
+                    : new GhostFetchRequestError({
+                        type: errorType,
+                        message: error instanceof Error ? error.message : String(error),
+                        proxy: proxy ?? undefined,
+                        cause: error,
+                    });
+                if (proxy) {
+                    if (errorType === 'proxy') {
+                        this.proxyManager.reportFailure(proxy);
+                    }
+                    else if (errorType === 'server') {
+                        this.proxyManager.reportSuccess(proxy);
+                    }
+                    // 'ambiguous' — do nothing
+                }
+                lastError = requestError;
+                lastFailedProxy = proxy;
+            }
+        }
+        throw new MaxRetriesExceededError(maxAttempts, lastError);
+    }
+    /**
+     * 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)
+     */
+    async pickProxy(forceProxy, exclude, country) {
+        const opts = { exclude, country };
+        const proxy = this.proxyManager.getProxy(opts);
+        if (proxy)
+            return proxy;
+        // No proxy available
+        if (this.proxyManager.total === 0) {
+            // No proxies configured at all
+            if (forceProxy)
+                throw new NoProxyAvailableError();
+            return null;
+        }
+        // Proxies exist but all banned or none match the country filter
+        if (forceProxy) {
+            // If filtering by country and no proxies exist for that country, fail immediately
+            if (country && this.proxyManager.getProxiesByCountry(country).length === 0) {
+                throw new NoProxyAvailableError();
+            }
+            // Wait until one becomes available (ban expires or refresh happens)
+            return this.proxyManager.waitForProxy(opts);
+        }
+        // Not forced — proceed without proxy
+        return null;
+    }
+    /** Handle an interceptor action (retry/ban/skip). Returns 'return' to send response, or { error } to continue retry loop. */
+    handleInterceptorAction(action, name, response, proxy) {
+        if (action === 'skip') {
+            if (proxy)
+                this.proxyManager.reportSuccess(proxy);
+            return 'return';
+        }
+        if (action === 'ban') {
+            if (proxy)
+                this.proxyManager.reportFailure(proxy);
+            return {
+                error: new GhostFetchRequestError({
+                    type: 'proxy',
+                    message: `Interceptor "${name}": ban (HTTP ${response.status})`,
+                    status: response.status,
+                    body: response.body,
+                    proxy: proxy ?? undefined,
+                }),
+            };
+        }
+        // retry
+        if (proxy)
+            this.proxyManager.reportSuccess(proxy);
+        return {
+            error: new GhostFetchRequestError({
+                type: 'server',
+                message: `Interceptor "${name}": retry (HTTP ${response.status})`,
+                status: response.status,
+                body: response.body,
+                proxy: proxy ?? undefined,
+            }),
+        };
+    }
+    async executeRequest(method, url, proxy, options) {
+        const client = await this.ensureClient();
+        const timeout = options?.timeout ?? this.config.timeout ?? DEFAULT_TIMEOUT;
+        const headers = {
+            ...this.config.headers,
+            ...options?.headers,
+        };
+        const cycleTLSOptions = {
+            headers,
+            timeout,
+            disableRedirect: false,
+        };
+        if (proxy) {
+            cycleTLSOptions.proxy = proxy;
+        }
+        if (this.config.ja3) {
+            cycleTLSOptions.ja3 = this.config.ja3;
+        }
+        if (this.config.userAgent) {
+            cycleTLSOptions.userAgent = this.config.userAgent;
+        }
+        if (options?.body) {
+            cycleTLSOptions.body = typeof options.body === 'string'
+                ? options.body
+                : JSON.stringify(options.body);
+            if (typeof options.body !== 'string') {
+                const hasContentType = Object.keys(headers).some((k) => k.toLowerCase() === 'content-type');
+                if (!hasContentType) {
+                    headers['content-type'] = 'application/json';
+                }
+            }
+        }
+        const response = await client(url, cycleTLSOptions, method.toLowerCase());
+        return {
+            status: response.status,
+            headers: (response.headers ?? {}),
+            body: response.body == null ? '' : typeof response.body === 'string' ? response.body : JSON.stringify(response.body),
+            url: response.finalUrl || url,
+        };
+    }
+    /**
+     * 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.
+     */
+    async healthCheckProxies(proxies) {
+        const client = await this.ensureClient();
+        const healthy = [];
+        const proxyDetails = {};
+        const countries = {};
+        const countryEntries = [];
+        // Process in batches
+        for (let i = 0; i < proxies.length; i += HEALTH_BATCH_CONCURRENCY) {
+            const batch = proxies.slice(i, i + HEALTH_BATCH_CONCURRENCY);
+            await Promise.allSettled(batch.map(async (proxy) => {
+                for (let attempt = 0; attempt < HEALTH_RETRY_DELAYS.length; attempt++) {
+                    if (attempt > 0) {
+                        await sleep(HEALTH_RETRY_DELAYS[attempt]);
+                    }
+                    try {
+                        const res = await client('https://ipinfo.io/json', { proxy, timeout: 10000, headers: {} }, 'get');
+                        const data = typeof res.body === 'string' ? JSON.parse(res.body) : res.body;
+                        const country = data.country ?? null;
+                        if (country) {
+                            countryEntries.push([proxy, country]);
+                            countries[country] = (countries[country] ?? 0) + 1;
+                        }
+                        proxyDetails[proxy] = country;
+                        healthy.push(proxy);
+                        return;
+                    }
+                    catch {
+                        // Will retry or discard
+                    }
+                }
+                // All 3 attempts failed — proxy is dead
+                proxyDetails[proxy] = null;
+            }));
+        }
+        // Add only healthy proxies to the manager, then restore country data
+        this.proxyManager.replaceProxies(healthy);
+        for (const [proxy, country] of countryEntries) {
+            this.proxyManager.setCountry(proxy, country);
+        }
+        return {
+            total: proxies.length,
+            healthy: healthy.length,
+            dead: proxies.length - healthy.length,
+            countries,
+            proxies: proxyDetails,
+        };
+    }
+    /** Gracefully shut down the CycleTLS instance and clear timers. */
+    async destroy() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        if (this.cycleTLS) {
+            try {
+                await this.cycleTLS.exit();
+            }
+            catch {
+                // CycleTLS may throw ESRCH when the Go process is already gone
+            }
+            this.cycleTLS = null;
+            this.initPromise = null;
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/esm/errors.js

@@ -0,0 +1,35 @@
+export class GhostFetchRequestError extends Error {
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'GhostFetchRequestError';
+        this.type = opts.type;
+        this.status = opts.status;
+        this.body = opts.body;
+        this.proxy = opts.proxy;
+        this.cause = opts.cause;
+    }
+}
+export class CloudflareJSChallengeError extends GhostFetchRequestError {
+    constructor(url, proxy) {
+        super({
+            type: 'server',
+            message: `Cloudflare JS challenge detected at ${url}. This requires a headless browser (e.g. puppeteer-extra with stealth plugin).`,
+            proxy,
+        });
+        this.name = 'CloudflareJSChallengeError';
+    }
+}
+export class NoProxyAvailableError extends Error {
+    constructor() {
+        super('No proxies available — all proxies are banned or the proxy list is empty.');
+        this.name = 'NoProxyAvailableError';
+    }
+}
+export class MaxRetriesExceededError extends Error {
+    constructor(attempts, lastError) {
+        super(`Max retries exceeded (${attempts} attempts). Last error: ${lastError.message}`);
+        this.name = 'MaxRetriesExceededError';
+        this.lastError = lastError;
+        this.attempts = attempts;
+    }
+}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { GhostFetch } from './client';
+export { ProxyManager } from './proxy-manager';
+export { GhostFetchRequestError, CloudflareJSChallengeError, NoProxyAvailableError, MaxRetriesExceededError, } from './errors';

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}