@vertesia/api-fetch-client 1.2.0 → 1.3.0-dev.20260620.061059Z

package/README.md

@@ -140,6 +140,54 @@ try {
 }
 ```
 
+## Retries
+
+Retries are disabled by default. Enable them explicitly on a client or a single request:
+
+```typescript
+const client = new FetchClient('https://api.example.com')
+  .withRetryPolicy({
+    attempts: 3,
+    methods: ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'],
+    statuses: [502, 503, 504],
+    baseDelayMs: 250,
+    maxDelayMs: 4000
+  });
+
+// POST requests are not retried by the default method list. Opt in only when
+// the operation is safe to replay.
+await client.post('/workflow/execute', {
+  payload,
+  retryPolicy: { methods: ['POST'] }
+});
+
+// Disable a client-level retry policy for one request.
+await client.get('/no-retry', { retryPolicy: false });
+```
+
+## Timeouts
+
+No request timeout is applied by default. Set a default on the client (applies to every request) and/or override it per request. The timeout aborts the **whole** request — connection, response headers, **and** body consumption (JSON parse) — using a browser-standard `AbortSignal`, so it behaves the same in the browser and in Node (no `undici`-specific configuration).
+
+```typescript
+// Default timeout (ms) for every request on this client.
+const client = new FetchClient('https://api.example.com').withTimeout(60_000);
+
+// Override for a single slow request (e.g. one that blocks on an LLM).
+await client.post('/long-running', { payload, timeoutMs: 30 * 60_000 });
+
+// Disable the client default for one request.
+await client.get('/no-timeout', { timeoutMs: false });
+
+// Combine with a caller-supplied AbortSignal — whichever aborts first wins.
+await client.get('/data', { signal: controller.signal, timeoutMs: 5_000 });
+```
+
+- `timeoutMs`: a positive number sets the timeout; `false`/`null`/`0` disables it for that request (overriding the client default); omitted falls back to the client default (`withTimeout` / `defaultTimeoutMs`).
+- On timeout the request rejects as a connection failure. When a retry policy is enabled, a timed-out attempt is retried like any other connection error, with a **fresh deadline per attempt**.
+- SSE requests (`reader: 'sse'`) are never given a total-request timeout — they are long-lived by design; apply your own idle/close handling to the stream.
+- `ApiTopic` sub-clients inherit the parent client's default timeout, so setting it once on the root client covers all topics.
+
 ### Custom Error Factory
 
 Transform errors before they're thrown:
@@ -256,6 +304,9 @@ The main client class for making HTTP requests.
 | `payload` | `object \| BodyInit` | Request body |
 | `reader` | `'sse' \| function` | Custom response reader |
 | `jsonPayload` | `boolean` | Auto-serialize payload as JSON (default: true) |
+| `retryPolicy` | `IRequestRetryPolicy \| false` | Per-request retry policy; `false` disables the client default |
+| `timeoutMs` | `number \| false \| null` | Per-request timeout (ms). Positive sets it; `false`/`null`/`0` disables; omitted uses the client default |
+| `signal` | `AbortSignal` | Caller abort signal, merged with the timeout signal |
 
 ### Error Classes
 

package/lib/base.d.ts

@@ -0,0 +1,169 @@
+import { type RequestError } from './errors.js';
+import { type ServerSentEvent } from './sse/index.js';
+export type FETCH_FN = (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+type IPrimitives = string | number | boolean | null | undefined | string[] | number[] | boolean[];
+export interface IRequestRetryPolicy {
+    /**
+     * Total attempts, including the first request. Defaults to 3 when a retry policy is enabled.
+     */
+    attempts?: number;
+    /**
+     * HTTP methods that may be retried. Defaults to idempotent methods.
+     */
+    methods?: string[];
+    /**
+     * HTTP response statuses that should be retried. Defaults to 502, 503, and 504.
+     */
+    statuses?: number[];
+    /**
+     * Also retry any 5xx whose body is not JSON — e.g. an HTML error page from a load balancer,
+     * gateway, or Cloud Run ("no available instance" / "try again in 30 seconds"). These originate
+     * at the edge, not the application (which serializes its errors as JSON), so they are transient
+     * and safe to retry even when the exact status (often 500) is not in `statuses`. Defaults to true.
+     */
+    retryNonJsonServerErrors?: boolean;
+    /**
+     * Retry network failures thrown by fetch. Defaults to true.
+     */
+    retryOnConnectionError?: boolean;
+    /**
+     * Initial backoff delay in milliseconds. Defaults to 250.
+     */
+    baseDelayMs?: number;
+    /**
+     * Maximum backoff delay in milliseconds. Defaults to 4000.
+     */
+    maxDelayMs?: number;
+    /**
+     * Use full jitter for backoff delays. Defaults to true.
+     */
+    jitter?: boolean;
+}
+type NormalizedRetryPolicy = {
+    attempts: number;
+    methods: Set<string>;
+    statuses: Set<number>;
+    retryNonJsonServerErrors: boolean;
+    retryOnConnectionError: boolean;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: boolean;
+};
+export interface IRequestParams {
+    query?: Record<string, IPrimitives> | null;
+    headers?: Record<string, string> | null;
+    reader?: 'sse' | ((response: Response) => unknown);
+    /**
+     * Set to false to disable automatic JSON payload serialization
+     * If you need to post other data than a json payload, set this to false and use the `payload` property to set the desired payload
+     */
+    jsonPayload?: boolean;
+    /**
+     * Opt-in retry policy for this request. Retries are disabled by default.
+     * Set to false to disable a client-level retry policy for this request.
+     */
+    retryPolicy?: IRequestRetryPolicy | false | null;
+    /**
+     * Per-request timeout in milliseconds. Aborts the whole request — connection, response headers,
+     * AND body consumption (JSON parse) — via a browser-standard AbortSignal. A positive number sets
+     * the timeout; `false`/`null`/`0` disables it for this request (overriding any client default).
+     * When omitted, the client-level default (`withTimeout` / `defaultTimeoutMs`) applies.
+     * Not applied to SSE (`reader: 'sse'`) requests, which are long-lived by design.
+     */
+    timeoutMs?: number | false | null;
+    /**
+     * Caller-supplied AbortSignal. Merged with the timeout signal — whichever aborts first wins.
+     */
+    signal?: AbortSignal;
+}
+export interface IRequestParamsWithPayload extends IRequestParams {
+    payload?: object | BodyInit | null;
+}
+export declare function fetchPromise(fetchImpl?: FETCH_FN | Promise<FETCH_FN>): Promise<FETCH_FN>;
+export declare abstract class ClientBase {
+    _fetch: Promise<FETCH_FN>;
+    baseUrl: string;
+    errorFactory: (err: RequestError) => Error;
+    verboseErrors: boolean;
+    retryPolicy?: IRequestRetryPolicy;
+    defaultTimeoutMs?: number;
+    abstract get headers(): Record<string, string>;
+    constructor(baseUrl: string, fetchImpl?: FETCH_FN | Promise<FETCH_FN>);
+    /**
+     * Can be subclassed to map to custom errors
+     * @param err
+     */
+    throwError(err: RequestError): never;
+    withRetryPolicy(policy?: IRequestRetryPolicy | null): this;
+    getRetryPolicy(): IRequestRetryPolicy | undefined;
+    /**
+     * Set a default request timeout (ms) applied to every request unless overridden per-request via
+     * `timeoutMs`. Pass `false`/`null`/`0` to clear it. The timeout aborts the whole request
+     * (connection + response headers + body consumption) via AbortSignal.
+     */
+    withTimeout(timeoutMs?: number | false | null): this;
+    getTimeout(): number | undefined;
+    /**
+     * Resolve the effective timeout for a request: per-request `timeoutMs` wins (a positive number
+     * sets it; `false`/`null`/`0` disables it), otherwise the client default applies. SSE streams are
+     * never given a total-request timeout.
+     */
+    protected resolveTimeout(params: IRequestParams | undefined): number | undefined;
+    /**
+     * Resolve a path to a full URL. If the path is already an absolute URL
+     * (starts with http:// or https://), it is returned as-is.
+     */
+    getUrl(path: string): string;
+    get<T = unknown>(path: string, params?: IRequestParams): Promise<T>;
+    del<T = unknown>(path: string, params?: IRequestParams): Promise<T>;
+    delete(path: string, params?: IRequestParams): Promise<unknown>;
+    post<T = unknown>(path: string, params?: IRequestParamsWithPayload): Promise<T>;
+    put<T = unknown>(path: string, params?: IRequestParamsWithPayload): Promise<T>;
+    /**
+     * You can customize the json parser by overriding this method
+     * @param text
+     * @returns
+     */
+    jsonParse(text: string): unknown;
+    /**
+     * Can be overridden to create the request
+     * @param fetch
+     * @param url
+     * @param init
+     * @returns
+     */
+    createRequest(url: string, init: RequestInit): Promise<Request>;
+    handleFetchResponse(_req: Request, _res: Response): void;
+    createServerError(req: Request, res: Response, payload: unknown): RequestError;
+    readJSONPayload(res: Response): Promise<unknown>;
+    /**
+     * Subclasses You can override this to do something with the response
+     * @param res
+     */
+    handleResponse<T = unknown>(req: Request, res: Response, params: IRequestParamsWithPayload | undefined): T | Promise<T>;
+    request<T = unknown>(method: string, path: string, params?: IRequestParamsWithPayload): Promise<T>;
+    protected resolveRetryPolicy(params: IRequestParamsWithPayload | undefined): NormalizedRetryPolicy | undefined;
+    private shouldRetryResponse;
+    private shouldRetryConnectionError;
+    private waitBeforeRetry;
+    /**
+     * Perform a request and consume the response as an SSE stream.
+     * Calls `onEvent` for each parsed SSE event, then returns the last event.
+     *
+     * @param method HTTP method
+     * @param path URL path (relative to baseUrl) or absolute URL (http:// or https://)
+     * @param params Request parameters (payload, headers, query)
+     * @param onEvent Callback for each SSE event
+     * @returns The last SSE event received, or undefined if the stream was empty
+     */
+    sseRequest(method: string, path: string, params: IRequestParamsWithPayload | undefined, onEvent: (event: ServerSentEvent) => void): Promise<ServerSentEvent | undefined>;
+    /**
+     * Expose the fetch method
+     * @param input
+     * @param init
+     * @returns
+     */
+    fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;
+}
+export {};
+//# sourceMappingURL=base.d.ts.map

package/lib/base.d.ts.map

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