@iflow-mcp/jakeliume-webpeel 0.22.0 → 0.22.2

package/dist/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * WebPeel Typed Error System
+ *
+ * Every error thrown in the pipeline should use these types.
+ * The `retryable` flag tells the retry system whether to attempt again.
+ * The `code` enables smart routing, logging, and Sentry filtering.
+ */
+export type ErrorCode = 'NETWORK_ERROR' | 'DNS_RESOLUTION_FAILED' | 'CONNECTION_REFUSED' | 'CONNECTION_RESET' | 'SSL_ERROR' | 'SOCKET_TIMEOUT' | 'HTTP_CLIENT_ERROR' | 'HTTP_SERVER_ERROR' | 'HTTP_TOO_MANY_REQUESTS' | 'TIMEOUT' | 'FETCH_TIMEOUT' | 'RENDER_TIMEOUT' | 'NAVIGATION_TIMEOUT' | 'BLOCKED' | 'BLOCKED_CLOUDFLARE' | 'BLOCKED_CAPTCHA' | 'BLOCKED_WAF' | 'BLOCKED_GEO' | 'BLOCKED_RATE_LIMIT' | 'BROWSER_CRASH' | 'BROWSER_OOM' | 'BROWSER_LAUNCH_FAILED' | 'BROWSER_CONTEXT_ERROR' | 'EMPTY_CONTENT' | 'INVALID_URL' | 'UNSUPPORTED_PROTOCOL' | 'ROBOTS_DENIED' | 'AUTH_REQUIRED' | 'PROXY_ERROR' | 'PROXY_EXHAUSTED' | 'CIRCUIT_OPEN' | 'MEMORY_LIMIT' | 'RATE_LIMITED' | 'JOB_TIMEOUT' | 'JOB_CANCELLED' | 'JOB_STALLED' | 'UNKNOWN';
+export declare class WebPeelError extends Error {
+    readonly code: ErrorCode;
+    readonly retryable: boolean;
+    readonly statusCode: number;
+    readonly context?: Record<string, any>;
+    readonly timestamp: string;
+    constructor(code: ErrorCode, message: string, options?: {
+        retryable?: boolean;
+        statusCode?: number;
+        context?: Record<string, any>;
+        cause?: Error;
+    });
+    /** Serialize for transport across processes (worker ↔ API) */
+    serialize(): Record<string, any>;
+    /** Deserialize from JSON (e.g., from Bull job result) */
+    static deserialize(data: Record<string, any>): WebPeelError;
+    /** Convert a generic Error into the most appropriate WebPeelError */
+    static fromError(err: Error, fallbackCode?: ErrorCode): WebPeelError;
+}
+/** Helper factory functions for common errors */
+export declare const Errors: {
+    timeout: (msg: string, ctx?: Record<string, any>) => WebPeelError;
+    fetchTimeout: (url: string, ms: number) => WebPeelError;
+    renderTimeout: (url: string, ms: number) => WebPeelError;
+    blocked: (url: string, reason?: string) => WebPeelError;
+    invalidUrl: (url: string) => WebPeelError;
+    networkError: (msg: string, cause?: Error) => WebPeelError;
+    proxyError: (msg: string) => WebPeelError;
+    proxyExhausted: () => WebPeelError;
+    circuitOpen: (name: string) => WebPeelError;
+    memoryLimit: (usage: number) => WebPeelError;
+    emptyContent: (url: string) => WebPeelError;
+    authRequired: (url: string) => WebPeelError;
+    rateLimited: (identifier: string) => WebPeelError;
+    jobCancelled: (jobId: string) => WebPeelError;
+    browserCrash: (msg: string) => WebPeelError;
+    unknown: (msg: string, cause?: Error) => WebPeelError;
+};
+/** Check if an error is retryable (works for both WebPeelError and generic Error) */
+export declare function isRetryable(err: Error): boolean;

package/dist/errors.js

@@ -0,0 +1,128 @@
+/**
+ * WebPeel Typed Error System
+ *
+ * Every error thrown in the pipeline should use these types.
+ * The `retryable` flag tells the retry system whether to attempt again.
+ * The `code` enables smart routing, logging, and Sentry filtering.
+ */
+export class WebPeelError extends Error {
+    code;
+    retryable;
+    statusCode;
+    context;
+    timestamp;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'WebPeelError';
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+        this.statusCode = options.statusCode ?? 500;
+        this.context = options.context;
+        this.timestamp = new Date().toISOString();
+        if (options.cause) {
+            this.cause = options.cause;
+        }
+    }
+    /** Serialize for transport across processes (worker ↔ API) */
+    serialize() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            retryable: this.retryable,
+            statusCode: this.statusCode,
+            context: this.context,
+            timestamp: this.timestamp,
+            stack: this.stack,
+        };
+    }
+    /** Deserialize from JSON (e.g., from Bull job result) */
+    static deserialize(data) {
+        const err = new WebPeelError(data.code, data.message, {
+            retryable: data.retryable,
+            statusCode: data.statusCode,
+            context: data.context,
+        });
+        err.stack = data.stack;
+        return err;
+    }
+    /** Convert a generic Error into the most appropriate WebPeelError */
+    static fromError(err, fallbackCode = 'UNKNOWN') {
+        if (err instanceof WebPeelError)
+            return err;
+        const msg = err.message?.toLowerCase() || '';
+        // DNS errors
+        if (msg.includes('getaddrinfo') || msg.includes('enotfound') || msg.includes('dns')) {
+            return new WebPeelError('DNS_RESOLUTION_FAILED', err.message, { retryable: true, statusCode: 502, cause: err });
+        }
+        // Connection errors
+        if (msg.includes('econnrefused')) {
+            return new WebPeelError('CONNECTION_REFUSED', err.message, { retryable: true, statusCode: 502, cause: err });
+        }
+        if (msg.includes('econnreset') || msg.includes('socket hang up')) {
+            return new WebPeelError('CONNECTION_RESET', err.message, { retryable: true, statusCode: 502, cause: err });
+        }
+        // SSL errors
+        if (msg.includes('ssl') || msg.includes('tls') || msg.includes('certificate') || msg.includes('cert_')) {
+            return new WebPeelError('SSL_ERROR', err.message, { retryable: false, statusCode: 502, cause: err });
+        }
+        // Timeout errors
+        if (msg.includes('timeout') || msg.includes('etimedout') || msg.includes('timed out')) {
+            if (msg.includes('navigation'))
+                return new WebPeelError('NAVIGATION_TIMEOUT', err.message, { retryable: true, statusCode: 504, cause: err });
+            if (msg.includes('render') || msg.includes('browser'))
+                return new WebPeelError('RENDER_TIMEOUT', err.message, { retryable: true, statusCode: 504, cause: err });
+            return new WebPeelError('FETCH_TIMEOUT', err.message, { retryable: true, statusCode: 504, cause: err });
+        }
+        // Browser errors
+        if (msg.includes('browser') && (msg.includes('crash') || msg.includes('killed'))) {
+            return new WebPeelError('BROWSER_CRASH', err.message, { retryable: true, statusCode: 500, cause: err });
+        }
+        if (msg.includes('browsertype.launch') || msg.includes('failed to launch')) {
+            return new WebPeelError('BROWSER_LAUNCH_FAILED', err.message, { retryable: true, statusCode: 500, cause: err });
+        }
+        // Blocked
+        if (msg.includes('cloudflare') || msg.includes('cf-') || msg.includes('challenge')) {
+            return new WebPeelError('BLOCKED_CLOUDFLARE', err.message, { retryable: true, statusCode: 403, cause: err });
+        }
+        if (msg.includes('captcha') || msg.includes('recaptcha')) {
+            return new WebPeelError('BLOCKED_CAPTCHA', err.message, { retryable: false, statusCode: 403, cause: err });
+        }
+        if (msg.includes('blocked') || msg.includes('forbidden') || msg.includes('access denied')) {
+            return new WebPeelError('BLOCKED', err.message, { retryable: true, statusCode: 403, cause: err });
+        }
+        return new WebPeelError(fallbackCode, err.message, { retryable: false, statusCode: 500, cause: err });
+    }
+}
+/** Helper factory functions for common errors */
+export const Errors = {
+    timeout: (msg, ctx) => new WebPeelError('TIMEOUT', msg, { retryable: true, statusCode: 504, context: ctx }),
+    fetchTimeout: (url, ms) => new WebPeelError('FETCH_TIMEOUT', `Fetch timed out after ${ms}ms: ${url}`, { retryable: true, statusCode: 504, context: { url, timeoutMs: ms } }),
+    renderTimeout: (url, ms) => new WebPeelError('RENDER_TIMEOUT', `Render timed out after ${ms}ms: ${url}`, { retryable: true, statusCode: 504, context: { url, timeoutMs: ms } }),
+    blocked: (url, reason) => new WebPeelError('BLOCKED', `Blocked: ${url}${reason ? ` (${reason})` : ''}`, { retryable: true, statusCode: 403, context: { url, reason } }),
+    invalidUrl: (url) => new WebPeelError('INVALID_URL', `Invalid URL: ${url}`, { retryable: false, statusCode: 400, context: { url } }),
+    networkError: (msg, cause) => new WebPeelError('NETWORK_ERROR', msg, { retryable: true, statusCode: 502, cause }),
+    proxyError: (msg) => new WebPeelError('PROXY_ERROR', msg, { retryable: true, statusCode: 502 }),
+    proxyExhausted: () => new WebPeelError('PROXY_EXHAUSTED', 'All proxy attempts exhausted', { retryable: false, statusCode: 502 }),
+    circuitOpen: (name) => new WebPeelError('CIRCUIT_OPEN', `Circuit breaker open: ${name}`, { retryable: false, statusCode: 503 }),
+    memoryLimit: (usage) => new WebPeelError('MEMORY_LIMIT', `Memory usage too high: ${(usage * 100).toFixed(1)}%`, { retryable: false, statusCode: 503, context: { memoryPct: usage } }),
+    emptyContent: (url) => new WebPeelError('EMPTY_CONTENT', `No content extracted from ${url}`, { retryable: false, statusCode: 422, context: { url } }),
+    authRequired: (url) => new WebPeelError('AUTH_REQUIRED', `Authentication required: ${url}`, { retryable: false, statusCode: 403, context: { url } }),
+    rateLimited: (identifier) => new WebPeelError('RATE_LIMITED', `Rate limit exceeded for ${identifier}`, { retryable: false, statusCode: 429 }),
+    jobCancelled: (jobId) => new WebPeelError('JOB_CANCELLED', `Job ${jobId} was cancelled`, { retryable: false, context: { jobId } }),
+    browserCrash: (msg) => new WebPeelError('BROWSER_CRASH', msg, { retryable: true, statusCode: 500 }),
+    unknown: (msg, cause) => new WebPeelError('UNKNOWN', msg, { retryable: false, statusCode: 500, cause }),
+};
+/** Check if an error is retryable (works for both WebPeelError and generic Error) */
+export function isRetryable(err) {
+    if (err instanceof WebPeelError)
+        return err.retryable;
+    // Heuristic for generic errors
+    const msg = err.message?.toLowerCase() || '';
+    return (msg.includes('timeout') ||
+        msg.includes('econnreset') ||
+        msg.includes('econnrefused') ||
+        msg.includes('socket hang up') ||
+        msg.includes('getaddrinfo') ||
+        msg.includes('network'));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iflow-mcp/jakeliume-webpeel",
-  "version": "0.22.0",
+  "version": "0.22.2",
   "description": "The web data layer for AI agents — fetch, search, crawl, extract, screenshot, and monitor the web with 55+ domain extractors and MCP.",
   "author": "Jake Liu",
   "license": "SEE LICENSE IN LICENSE",
@@ -48,6 +48,8 @@
     "dist/cli-auth.js",
     "dist/cli-auth.d.ts",
     "dist/cache.js",
+    "dist/errors.js",
+    "dist/errors.d.ts",
     "dist/cache.d.ts"
   ],
   "scripts": {