recker 1.0.73 → 1.0.75-next.2e5a94f

package/README.md

@@ -6,7 +6,7 @@
 
 Nine protocols unified: HTTP, WebSocket, DNS, WHOIS, RDAP, FTP, SFTP, Telnet, HLS.
 <br>
-AI-native: OpenAI, Anthropic, Google, Ollama + MCP server with 65 tools.
+AI-native: OpenAI, Anthropic, Google, Ollama + MCP server with 70 tools.
 <br>
 48 service presets built-in. Zero config.
 
@@ -121,7 +121,7 @@ recker.ws('wss://example.com/socket'); // WebSocket
 | **SEO** | 400+ rules, 19 categories, site-wide spider crawler |
 | **Testing** | 10 mock servers (HTTP, Proxy, WebSocket, DNS, FTP, HLS, SSE...) |
 | **CLI** | `rek` - curl replacement with superpowers |
-| **MCP** | 65 tools for AI assistants (Claude, Cursor, Windsurf) |
+| **MCP** | 70 tools for AI assistants (Claude, Cursor, Windsurf) |
 
 ## Highlights
 
@@ -253,7 +253,7 @@ rek shell
 
 ## MCP Server
 
-65 tools for AI assistants like Claude Code, Cursor, and Windsurf:
+70 tools for AI assistants like Claude Code, Cursor, and Windsurf:
 
 ```bash
 # One-liner for Claude Code (uses minimal category by default)
@@ -262,11 +262,11 @@ claude mcp add recker npx recker@latest mcp
 # Add more categories as needed
 claude mcp add recker npx recker@latest mcp --category=minimal,video,seo
 
-# Enable all 65 tools
+# Enable all 70 tools
 claude mcp add recker npx recker@latest mcp --category=full
 ```
 
-**Categories:** `minimal` (default) `docs` `network` `dns` `security` `seo` `scrape` `video` `ai` `protocols` `parsing` `streaming` `full`
+**Categories:** `minimal` (default) `docs` `network` `dns` `security` `seo` `scrape` `video` `ai` `protocols` `parsing` `streaming` `template` `full`
 
 [→ MCP Documentation](https://forattini-dev.github.io/recker/#/getting-started/mcp)
 
@@ -285,19 +285,6 @@ claude mcp add recker npx recker@latest mcp --category=full
 | Mock Servers | [→ Testing](https://forattini-dev.github.io/recker/#/cli/08-mock-servers) |
 | API Reference | [→ Full API](https://forattini-dev.github.io/recker/#/reference/01-api) |
 
-## Numbers
-
-| Metric | Value |
-|:-------|:------|
-| Protocols | 9 (HTTP, WS, DNS, WHOIS, RDAP, FTP, SFTP, Telnet, HLS) |
-| Plugins | 30+ |
-| Auth Methods | 15 |
-| API Presets | 48 |
-| MCP Tools | 65 |
-| SEO Rules | 400+ |
-| Mock Servers | 10 |
-| Tests | 4200+ |
-
 ## License
 
 MIT © [Forattini](https://github.com/forattini-dev)

package/dist/browser/core/client.d.ts

@@ -1,6 +1,7 @@
 import { ClientOptions, Middleware, ReckerRequest, ReckerResponse, RequestOptions, CacheStorage, PageResult } from '../types/index.js';
 import type { ClientAI, ClientOptionsWithAI } from '../types/ai-client.js';
 import { RequestPromise } from './request-promise.js';
+import { type RuntimeEventName, type RuntimeEventPayloads, type TypedEventBus } from '../core-runtime/typed-events.js';
 import { type VersionInfo } from '../version.js';
 import { PaginationOptions } from '../plugins/pagination.js';
 import { RetryOptions } from '../plugins/retry.js';
@@ -15,6 +16,12 @@ interface ClientCacheConfig extends Omit<CacheOptions, 'storage'> {
     driver?: 'memory' | 'file';
     fileStoragePath?: string;
 }
+interface BatchRequestOptions<T = ReckerResponse> {
+    concurrency?: number;
+    mapResponse?: (res: ReckerResponse) => Promise<T> | T;
+    signal?: AbortSignal;
+    deadlineMs?: number;
+}
 export interface ExtendedClientOptions extends ClientOptions {
     retry?: RetryOptions;
     cache?: ClientCacheConfig;
@@ -41,6 +48,10 @@ export declare class Client {
     private concurrencyConfig;
     private requestPool?;
     private maxResponseSize?;
+    readonly runtimeEventBus: TypedEventBus;
+    private shouldEmitRuntimeEvents;
+    private runtimeEventBusProviderAttached;
+    private runtimeEventListenerCount;
     private cookieJar?;
     private cookieIgnoreInvalid;
     private defaultTimeout?;
@@ -63,6 +74,7 @@ export declare class Client {
     beforeRequest(hook: (req: ReckerRequest) => ReckerRequest | void | Promise<ReckerRequest | void>): this;
     afterResponse(hook: (req: ReckerRequest, res: ReckerResponse) => ReckerResponse | void | Promise<ReckerResponse | void>): this;
     onError(hook: (error: Error, req: ReckerRequest) => ReckerResponse | void | Promise<ReckerResponse | void>): this;
+    onRuntimeEvent<K extends RuntimeEventName>(name: K, handler: (event: RuntimeEventPayloads[K]) => void): () => void;
     private buildUrl;
     request<T = unknown>(path: string, options?: RequestOptions): RequestPromise<T>;
     get<T = unknown>(path: string, options?: Omit<RequestOptions, 'method'>): RequestPromise<T>;
@@ -70,10 +82,7 @@ export declare class Client {
     batch<T = ReckerResponse>(requests: Array<{
         path: string;
         options?: RequestOptions;
-    }>, options?: {
-        concurrency?: number;
-        mapResponse?: (res: ReckerResponse) => Promise<T> | T;
-    }): Promise<{
+    }>, options?: BatchRequestOptions<T>): Promise<{
         results: (T | Error)[];
         stats: {
             total: number;
@@ -85,10 +94,7 @@ export declare class Client {
     multi<T = ReckerResponse>(requests: Array<{
         path: string;
         options?: RequestOptions;
-    }>, options?: {
-        concurrency?: number;
-        mapResponse?: (res: ReckerResponse) => Promise<T> | T;
-    }): Promise<{
+    }>, options?: BatchRequestOptions<T>): Promise<{
         results: (Error | T)[];
         stats: {
             total: number;

package/dist/browser/core/client.js

@@ -5,6 +5,9 @@ import { RequestPromise } from './request-promise.js';
 import { HttpError, MaxSizeExceededError, ConfigurationError, ValidationError, TimeoutError, UnsupportedError } from '../core/errors.js';
 import { processBody, createFormData, isPlainObject } from '../utils/body.js';
 import { RequestPool } from '../utils/request-pool.js';
+import { createRequestContext, attachRequestContext, getRequestContext } from '../core-runtime/request-context.js';
+import { createNoopEventBus } from '../core-runtime/typed-events.js';
+import { attachPluginManifest, getPluginManifest, normalizePlugins, toSortedPlugins } from '../core-runtime/plugin-manifest.js';
 import { normalizeConcurrency, expandHTTP2Options } from '../utils/concurrency.js';
 import { getGlobalProtocolCache } from '../utils/protocol-cache.js';
 import { getDefaultUserAgent } from '../utils/user-agent.js';
@@ -188,6 +191,10 @@ export class Client {
     concurrencyConfig;
     requestPool;
     maxResponseSize;
+    runtimeEventBus;
+    shouldEmitRuntimeEvents;
+    runtimeEventBusProviderAttached = false;
+    runtimeEventListenerCount = 0;
     cookieJar;
     cookieIgnoreInvalid = false;
     defaultTimeout;
@@ -215,6 +222,18 @@ export class Client {
         this.defaultParams = options.defaults?.params || {};
         this.paginationConfig = options.pagination;
         this.maxResponseSize = options.maxResponseSize;
+        const runtimeEventBus = options.runtimeEventBus;
+        if (runtimeEventBus) {
+            this.runtimeEventBus = {
+                on: (name, handler) => runtimeEventBus.on(name, handler),
+                emit: (name, event) => runtimeEventBus.emit(name, event),
+            };
+        }
+        else {
+            this.runtimeEventBus = createNoopEventBus();
+        }
+        this.shouldEmitRuntimeEvents = runtimeEventBus !== undefined;
+        this.runtimeEventBusProviderAttached = runtimeEventBus !== undefined;
         this.debugEnabled = options.debug === true;
         if (this.debugEnabled) {
             this.logger = options.logger ?? consoleLogger;
@@ -276,8 +295,20 @@ export class Client {
             this.transport = new FetchTransport();
             this.transportKind = 'fetch';
         }
+        const registerPlugin = (plugin, manifest = {}) => {
+            const existingManifest = getPluginManifest(plugin);
+            pluginRegistrations.push(attachPluginManifest(plugin, {
+                ...existingManifest,
+                ...manifest
+            }));
+        };
+        const pluginRegistrations = [];
         if (options.retry) {
-            retryPlugin(options.retry)(this);
+            registerPlugin(retryPlugin(options.retry), {
+                name: 'recker:retry',
+                priority: 120,
+                scope: 'request'
+            });
         }
         if (this.concurrencyConfig.max < Infinity || this.concurrencyConfig.requestsPerInterval < Infinity) {
             this.requestPool = new RequestPool({
@@ -285,7 +316,13 @@ export class Client {
                 requestsPerInterval: this.concurrencyConfig.requestsPerInterval,
                 interval: this.concurrencyConfig.interval
             });
-            this.middlewares.unshift(this.requestPool.asMiddleware());
+            registerPlugin((client) => {
+                client.middlewares.unshift(this.requestPool.asMiddleware());
+            }, {
+                name: 'recker:request-pool',
+                priority: 130,
+                scope: 'runtime'
+            });
             if (this.debugEnabled && this.logger) {
                 this.logger.debug(`Global concurrency limit: ${this.concurrencyConfig.max} concurrent requests`);
             }
@@ -296,7 +333,11 @@ export class Client {
             }
         }
         if (options.dedup) {
-            dedupPlugin(options.dedup)(this);
+            registerPlugin(dedupPlugin(options.dedup), {
+                name: 'recker:dedup',
+                priority: 110,
+                scope: 'request'
+            });
         }
         if (options.cache) {
             let storage;
@@ -309,13 +350,31 @@ export class Client {
             else {
                 storage = createDefaultCacheStorage();
             }
-            cachePlugin({
+            registerPlugin(cachePlugin({
                 ...options.cache,
                 storage
-            })(this);
+            }), {
+                name: 'recker:cache',
+                priority: 100,
+                scope: 'request'
+            });
         }
         if (options.plugins) {
-            options.plugins.forEach((plugin) => plugin(this));
+            options.plugins.forEach((plugin, index) => {
+                const existingManifest = getPluginManifest(plugin);
+                registerPlugin(plugin, {
+                    name: existingManifest?.name || `user-plugin:${index}`,
+                    priority: existingManifest?.priority ?? 90 - index,
+                    scope: existingManifest?.scope || 'request'
+                });
+            });
+        }
+        const { ordered, debugOrder } = normalizePlugins(toSortedPlugins(pluginRegistrations));
+        ordered.forEach(({ plugin }) => {
+            plugin(this);
+        });
+        if (this.debugEnabled && this.logger) {
+            this.logger.debug(`Applied plugins in order: ${debugOrder.join(' | ')}`);
         }
         if (options.compression) {
             const compressionMiddleware = createCompressionMiddleware(options.compression);
@@ -458,13 +517,46 @@ export class Client {
         return header.split(/,(?=\s*[a-zA-Z0-9_-]+=)/g).map(s => s.trim());
     }
     async dispatch(req) {
-        if (req.useCurl && this.transportKind !== 'curl') {
-            if (!this.curlTransport) {
-                this.curlTransport = createLazyCurlTransport();
+        const context = getRequestContext(req);
+        const transportStart = context ? Date.now() : 0;
+        if (context) {
+            this.runtimeEventBus.emit('transport:start', { context, req });
+        }
+        try {
+            if (req.useCurl && this.transportKind !== 'curl') {
+                if (!this.curlTransport) {
+                    this.curlTransport = createLazyCurlTransport();
+                }
+                const response = await this.curlTransport.dispatch(req);
+                if (context) {
+                    this.runtimeEventBus.emit('transport:finish', {
+                        context,
+                        req,
+                        durationMs: Date.now() - transportStart
+                    });
+                }
+                return response;
+            }
+            const response = await this.transport.dispatch(req);
+            if (context) {
+                this.runtimeEventBus.emit('transport:finish', {
+                    context,
+                    req,
+                    durationMs: Date.now() - transportStart
+                });
             }
-            return this.curlTransport.dispatch(req);
+            return response;
+        }
+        catch (error) {
+            if (context) {
+                this.runtimeEventBus.emit('transport:error', {
+                    context,
+                    req,
+                    error: error instanceof Error ? error : new Error(String(error))
+                });
+            }
+            throw error;
         }
-        return this.transport.dispatch(req);
     }
     composeMiddlewares() {
         const chain = [...this.middlewares];
@@ -563,6 +655,20 @@ export class Client {
         this.canFastPath = false;
         return this;
     }
+    onRuntimeEvent(name, handler) {
+        this.shouldEmitRuntimeEvents = true;
+        this.runtimeEventListenerCount += 1;
+        const unsubscribe = this.runtimeEventBus.on(name, handler);
+        return () => {
+            unsubscribe();
+            if (this.runtimeEventListenerCount > 0) {
+                this.runtimeEventListenerCount -= 1;
+            }
+            if (!this.runtimeEventBusProviderAttached && this.runtimeEventListenerCount === 0) {
+                this.shouldEmitRuntimeEvents = false;
+            }
+        };
+    }
     buildUrl(path, requestParams) {
         const hasRequestParams = requestParams && Object.keys(requestParams).length > 0;
         const hasDefaultParams = Object.keys(this.defaultParams).length > 0;
@@ -581,7 +687,7 @@ export class Client {
         const mergedParams = { ...this.defaultParams, ...requestParams };
         const usedParams = new Set();
         if (finalPath.includes(':')) {
-            finalPath = finalPath.replace(/:([a-zA-Z0-9_]+)/g, (match, paramName) => {
+            finalPath = finalPath.replace(/:([a-zA-Z0-9_]+)/g, (_match, paramName) => {
                 if (mergedParams && paramName in mergedParams) {
                     usedParams.add(paramName);
                     return encodeURIComponent(String(mergedParams[paramName]));
@@ -616,19 +722,62 @@ export class Client {
     }
     request(path, options = {}) {
         const url = this.buildUrl(path, options.params);
+        const canRequestMutateHeaders = (this.hooks.beforeRequest?.length ?? 0) > 0 ||
+            this.middlewares.length > 0;
+        const shouldAttachContext = this.shouldEmitRuntimeEvents ||
+            !!options.correlationId ||
+            !!options.tenant ||
+            !!options.traceId ||
+            !!options.policySource ||
+            (options.policyTags?.length ?? 0) > 0;
+        const createContextSeed = () => createRequestContext({
+            correlationId: options.correlationId,
+            tenant: options.tenant,
+            policyTags: options.policyTags,
+            policySource: options.policySource,
+            traceId: options.traceId
+        });
         const usesFastPath = this.canFastPath &&
             !options.headers &&
             !options.timeout &&
             !options.signal &&
             options.maxResponseSize === undefined;
         if (usesFastPath) {
-            const req = new HttpRequest(url, {
+            let req = new HttpRequest(url, {
                 method: options.method || 'GET',
                 body: options.body,
                 headers: this.defaultHeadersObj,
                 throwHttpErrors: options.throwHttpErrors,
             });
-            const responsePromise = this.fastHandler(req);
+            if (shouldAttachContext) {
+                req = attachRequestContext(req, createContextSeed());
+            }
+            const requestContext = getRequestContext(req);
+            const startTime = Date.now();
+            if (requestContext) {
+                this.runtimeEventBus.emit('request:start', { context: requestContext, req });
+            }
+            let responsePromise = this.fastHandler(req);
+            if (requestContext) {
+                responsePromise = responsePromise.then((response) => {
+                    this.runtimeEventBus.emit('request:success', {
+                        context: requestContext,
+                        req,
+                        res: response,
+                        durationMs: Date.now() - startTime
+                    });
+                    return response;
+                }, (error) => {
+                    const requestError = error instanceof Error ? error : new Error(String(error));
+                    this.runtimeEventBus.emit('request:failed', {
+                        context: requestContext,
+                        req,
+                        error: requestError,
+                        durationMs: Date.now() - startTime
+                    });
+                    throw error;
+                });
+            }
             return new RequestPromise(responsePromise);
         }
         let mergedHeaders;
@@ -639,6 +788,9 @@ export class Client {
                 : new Headers(options.headers);
             optHeaders.forEach((value, key) => mergedHeaders.set(key, value));
         }
+        else if (canRequestMutateHeaders) {
+            mergedHeaders = new Headers(this.defaultHeadersObj);
+        }
         else {
             mergedHeaders = this.defaultHeadersObj;
         }
@@ -672,13 +824,41 @@ export class Client {
                 }
             }
         }
-        const req = new HttpRequest(url, {
+        let req = new HttpRequest(url, {
             ...options,
             headers: mergedHeaders,
             signal,
             maxResponseSize: options.maxResponseSize ?? this.maxResponseSize
         });
-        const responsePromise = this.handler(req);
+        if (shouldAttachContext) {
+            req = attachRequestContext(req, createContextSeed());
+        }
+        const requestContext = getRequestContext(req);
+        const startTime = Date.now();
+        if (requestContext) {
+            this.runtimeEventBus.emit('request:start', { context: requestContext, req });
+        }
+        let responsePromise = this.handler(req);
+        if (requestContext) {
+            responsePromise = responsePromise.then((response) => {
+                this.runtimeEventBus.emit('request:success', {
+                    context: requestContext,
+                    req,
+                    res: response,
+                    durationMs: Date.now() - startTime
+                });
+                return response;
+            }, (error) => {
+                const requestError = error instanceof Error ? error : new Error(String(error));
+                this.runtimeEventBus.emit('request:failed', {
+                    context: requestContext,
+                    req,
+                    error: requestError,
+                    durationMs: Date.now() - startTime
+                });
+                throw error;
+            });
+        }
         if (timeoutId || externalAbortCleanup) {
             responsePromise.finally(() => {
                 if (timeoutId)
@@ -708,6 +888,9 @@ export class Client {
         const runnerResult = await runner.run(requests, async (item) => {
             const res = await this.request(item.path, item.options);
             return mapResponse(res);
+        }, {
+            signal: options.signal,
+            deadlineMs: options.deadlineMs
         });
         return runnerResult;
     }
@@ -857,7 +1040,6 @@ export class Client {
     }
     page(path, pageNumber, options = {}) {
         const pageParam = options.pageParam || this.paginationConfig?.pageParam || 'page';
-        const url = new URL(path.startsWith('http') ? path : `http://base${path}`);
         const params = { ...options.params, [pageParam]: pageNumber };
         return this.request(path, { ...options, params });
     }

package/dist/browser/core/errors.d.ts

@@ -1,10 +1,23 @@
 import { ReckerRequest, ReckerResponse } from '../types/index.js';
+export type CanonicalErrorCategory = 'http' | 'network' | 'timeout' | 'protocol' | 'validation' | 'state' | 'filesystem' | 'resource' | 'policy' | 'queue' | 'unknown';
+export type ErrorSource = 'client' | 'transport' | 'server' | 'upstream';
+export type CanonicalErrorSeverity = 'low' | 'medium' | 'high';
+export interface CanonicalErrorMetadata {
+    category: CanonicalErrorCategory;
+    source: ErrorSource;
+    severity: CanonicalErrorSeverity;
+    canRetry: boolean;
+    reason: string;
+    statusCode?: number;
+    retryAfterMs?: number;
+}
 export declare class ReckerError extends Error {
     request?: ReckerRequest;
     response?: ReckerResponse;
     suggestions: string[];
     retriable: boolean;
-    constructor(message: string, request?: ReckerRequest, response?: ReckerResponse, suggestions?: string[], retriable?: boolean);
+    classification?: CanonicalErrorMetadata;
+    constructor(message: string, request?: ReckerRequest, response?: ReckerResponse, suggestions?: string[], retriable?: boolean, classification?: CanonicalErrorMetadata);
 }
 export declare class HttpError extends ReckerError {
     status: number;
@@ -40,6 +53,7 @@ export declare class Http2Error extends ReckerError {
     });
 }
 export declare function parseHttp2Error(error: Error): Http2Error | null;
+export declare function classifyTransportError(error: unknown): CanonicalErrorMetadata | undefined;
 export declare class MaxSizeExceededError extends ReckerError {
     maxSize: number;
     actualSize?: number;