feat: structured client debug pipeline (debug, logger, stages)

- Add OpenFetchConfig.debug and logger with OpenFetchDebugEvent
- Emit lifecycle events from client, dispatch, and retry (basic vs verbose)
- Redact URLs and mask headers in debug output; classify retry reasons
- Export OpenFetchDebugEvent; add debug-pipeline tests

Made-with: Cursor

Author: hamdymohamedak

dist/domain/types.d.ts

@@ -4,6 +4,11 @@ import type { StandardSchemaV1 } from "./standardSchema.js";
 export type NextFn = () => Promise<void>;
 export type TransformRequest = (data: unknown, headers: Record<string, string>) => unknown | Promise<unknown>;
 export type TransformResponse<T = unknown> = (data: unknown) => T | Promise<T>;
+/** Structured record emitted when {@link OpenFetchConfig.debug} is enabled. */
+export type OpenFetchDebugEvent = {
+    stage: string;
+    timestamp: number;
+} & Record<string, unknown>;
 /** Per-request overrides for the memory cache middleware. */
 export type OpenFetchMemoryCacheRequestOptions = {
     ttlMs?: number;
@@ -77,6 +82,14 @@ export type OpenFetchConfig = {
      * Default false — return full `OpenFetchResponse`.
      */
     unwrapResponse?: boolean;
+    /**
+     * DevTools-style lifecycle logging. `true` / `"verbose"` emit structured events for the full
+     * pipeline (merge, fetch, retries, parse, schema). `"basic"` logs `request`, final `response`,
+     * and `error` only. Events go to {@link OpenFetchConfig.logger} or `console.debug`.
+     */
+    debug?: boolean | "basic" | "verbose";
+    /** Custom sink for structured {@link OpenFetchDebugEvent} records when `debug` is enabled. */
+    logger?: (log: OpenFetchDebugEvent) => void;
 } & Partial<Pick<RequestInit, "cache" | "credentials" | "integrity" | "keepalive" | "mode" | "redirect" | "referrer" | "referrerPolicy">>;
 export type OpenFetchResponse<T = unknown> = {
     data: T;

dist/domain/types.d.ts.map

@@ -19,5 +19,5 @@ export { cloneResponse } from "./shared/cloneResponse.js";
 export { SchemaValidationError, isSchemaValidationError, } from "./domain/schemaValidationError.js";
 export { OpenFetchForceRetry, isOpenFetchForceRetry, } from "./domain/forceRetry.js";
 export type { StandardSchemaV1, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Options, StandardSchemaV1Result, StandardSchemaV1SuccessResult, StandardSchemaV1FailureResult, StandardSchemaV1Types, } from "./domain/standardSchema.js";
-export type { Middleware, NextFn, OpenFetchClient, OpenFetchConfig, OpenFetchContext, OpenFetchInterceptors, OpenFetchMemoryCacheRequestOptions, OpenFetchResponse, OpenFetchRetryOptions, RequestConfig, TransformRequest, TransformResponse, } from "./types/index.js";
+export type { Middleware, NextFn, OpenFetchClient, OpenFetchConfig, OpenFetchContext, OpenFetchDebugEvent, OpenFetchInterceptors, OpenFetchMemoryCacheRequestOptions, OpenFetchResponse, OpenFetchRetryOptions, RequestConfig, TransformRequest, TransformResponse, } from "./types/index.js";
 //# sourceMappingURL=index.d.ts.map