lifecycleion 0.0.8 → 0.0.10

package/dist/lib/http-client/index.d.cts

@@ -0,0 +1,372 @@
+import { R as RequestState, c as HTTPMethod, d as HTTPRequestOptions, e as HTTPResponse, f as HTTPClientError, g as HTTPProgressEvent, h as AttemptStartEvent, i as AttemptEndEvent, S as StreamResponseFactory, j as HTTPClientConfig, A as AdapterType, k as RequestInterceptor, l as RequestInterceptorFilter, m as ResponseObserver, n as ResponseObserverFilter, E as ErrorObserver, o as ErrorObserverFilter, p as SubClientConfig, H as HTTPAdapter, a as AdapterRequest, b as AdapterResponse } from '../../types-CUPvmYQ8.cjs';
+export { v as AttemptRequest, C as ContentType, N as Cookie, O as CookieInput, q as CookieJar, P as CookieJarJSON, s as ErrorCode, G as ErrorObserverPhase, B as ErrorObserverPhaseName, u as InterceptedRequest, I as InterceptorCancel, D as InterceptorPhase, y as InterceptorPhaseName, Q as QueryObject, r as QueryValue, J as RedirectHopInfo, t as RequestInterceptorContext, w as RequestPhase, x as RequestPhaseName, F as ResponseObserverPhase, z as ResponseObserverPhaseName, M as StreamResponseCancel, L as StreamResponseContext, K as StreamResponseInfo, W as WritableLike } from '../../types-CUPvmYQ8.cjs';
+import { R as RetryPolicyOptions } from '../../types-D_MywcG0.cjs';
+
+interface TrackedRequest {
+    requestID: string;
+    clientID: string;
+    label?: string;
+    state: RequestState;
+    abortController: AbortController;
+}
+/**
+ * Shared in-flight request map. One instance is shared between a root HTTPClient and
+ * all its sub-clients so that cancelAll() cancels across all of them.
+ */
+declare class RequestTracker {
+    private requests;
+    add(entry: TrackedRequest): void;
+    remove(requestID: string): void;
+    get(requestID: string): TrackedRequest | undefined;
+    updateState(requestID: string, state: RequestState): void;
+    /**
+     * Cancels a single request by ID. Returns 1 if cancelled, 0 if not found.
+     */
+    cancel(requestID: string, reason?: string): number;
+    /**
+     * Cancels ALL in-flight requests across the shared tracker (all clients).
+     * Returns the number of requests cancelled.
+     */
+    cancelAll(reason?: string): number;
+    /**
+     * Cancels all requests owned by a specific client.
+     * Returns the number of requests cancelled.
+     */
+    cancelOwn(clientID: string, reason?: string): number;
+    /**
+     * Cancels all requests that have the given label (across all clients in the shared tracker).
+     * Returns the number of requests cancelled.
+     */
+    cancelAllWithLabel(label: string, reason?: string): number;
+    /**
+     * Cancels requests owned by a specific client that also have the given label.
+     * Returns the number of requests cancelled.
+     */
+    cancelOwnWithLabel(clientID: string, label: string, reason?: string): number;
+    /**
+     * Returns a read-only view of tracked requests.
+     *
+     * Intentionally omits abortController,
+     * callers cancel via cancel()/cancelAll()/etc. so that
+     * the tracker remains the sole owner of state mutations.
+     */
+    list(filter?: {
+        clientID?: string;
+        label?: string;
+    }): {
+        count: number;
+        requests: RequestInfo[];
+    };
+}
+interface RequestInfo {
+    requestID: string;
+    clientID: string;
+    label?: string;
+    state: RequestState;
+}
+
+interface BuilderCallbacks<T> {
+    setState: (state: RequestState) => void;
+    setResponse: (response: HTTPResponse<T>) => void;
+    setError: (error: HTTPClientError) => void;
+    setAttemptCount: (count: number) => void;
+    setNextRetryDelayMS: (delayMS: number | null) => void;
+    setNextRetryAt: (timestampMS: number | null) => void;
+    setStartedAt: (timestampMS: number) => void;
+    setCancelFn: (fn: (reason?: string) => void) => void;
+}
+interface BuilderSendContext<T = unknown> {
+    method: HTTPMethod;
+    path: string;
+    requestID: string;
+    options: ResolvedBuilderOptions;
+    callbacks: BuilderCallbacks<T>;
+}
+interface ResolvedBuilderOptions extends HTTPRequestOptions {
+    headers: Record<string, string | string[]>;
+}
+type SendFn<T> = (context: BuilderSendContext<T>) => Promise<HTTPResponse<T>>;
+/**
+ * Fluent, single-use request builder. Returned by HTTPClient methods.
+ * Call .send() to execute the request.
+ */
+declare class HTTPRequestBuilder<T = unknown> {
+    private _method;
+    private _path;
+    private _headers;
+    private _params?;
+    private _body?;
+    private _timeout?;
+    private _signal?;
+    private _retryPolicy?;
+    private _label?;
+    private _onUploadProgress?;
+    private _onDownloadProgress?;
+    private _onAttemptStart?;
+    private _onAttemptEnd?;
+    private _streamResponse?;
+    private _sendFn;
+    private _sent;
+    private _requestID;
+    private _state;
+    private _response;
+    private _error;
+    private _attemptCount;
+    private _nextRetryDelayMS;
+    private _nextRetryAt;
+    private _startedAt;
+    private _completedAt;
+    private _cancelFn;
+    private _preSendCancelReason;
+    constructor(method: HTTPMethod, path: string, sendFn: SendFn<T>, options?: HTTPRequestOptions);
+    headers(headers: Record<string, string | string[]>): this;
+    params(params: Record<string, unknown>): this;
+    json(data: unknown): this;
+    formData(data: FormData): this;
+    text(data: string): this;
+    body(data: unknown): this;
+    timeout(ms: number): this;
+    signal(abortSignal: AbortSignal): this;
+    label(label: string): this;
+    retryPolicy(options: RetryPolicyOptions | null): this;
+    onUploadProgress(fn: (event: HTTPProgressEvent) => void): this;
+    onDownloadProgress(fn: (event: HTTPProgressEvent) => void): this;
+    onAttemptStart(fn: (event: AttemptStartEvent) => void): this;
+    onAttemptEnd(fn: (event: AttemptEndEvent) => void): this;
+    /**
+     * NodeAdapter only. Called after response headers arrive on a 200 response,
+     * before any body bytes are read. Return a WritableLike to pipe the body into
+     * it, or null to cancel the request entirely.
+     *
+     * The context provides an attempt-scoped AbortSignal that fires on cancel,
+     * timeout, or stream write failure — useful for co-locating cleanup with setup:
+     *
+     *   .streamResponse((_info, { signal }) => {
+     *     const stream = createWriteStream('/tmp/file.bin');
+     *
+     *     signal.addEventListener('abort', () => {
+     *       stream.destroy();
+     *       fs.unlinkSync('/tmp/file.bin'); // clean up partial file
+     *     });
+     *     return stream;
+     *   })
+     *
+     * HTTPClient rejects non-node adapters before dispatch if this is set.
+     */
+    streamResponse(fn: StreamResponseFactory): this;
+    get requestID(): string;
+    get state(): RequestState;
+    get response(): HTTPResponse<T> | null;
+    get error(): HTTPClientError | null;
+    get attemptCount(): number | null;
+    get nextRetryDelayMS(): number | null;
+    get nextRetryAt(): number | null;
+    /** Epoch ms when the first attempt was dispatched. null before send(). */
+    get startedAt(): number | null;
+    /** Total wall-clock ms since the first attempt, including retry waits. null before send().
+     * Freezes once the request completes.
+     */
+    get elapsedMS(): number | null;
+    /**
+     * Cancels the request. Returns true if the cancel was applied, false if it
+     * was a no-op (already completed, cancelled, or failed).
+     *
+     * Calling cancel() before send() marks the builder as cancelled so that
+     * send() throws instead of dispatching the request.
+     */
+    cancel(reason?: string): boolean;
+    send<U = T>(): Promise<HTTPResponse<U>>;
+    private _applyOptions;
+    private _assertNotSent;
+}
+
+type RemoveFn = () => void;
+interface InternalClientState {
+    tracker?: RequestTracker;
+    parentClient?: BaseHTTPClient | null;
+}
+declare class BaseHTTPClient {
+    protected _clientID: string;
+    protected _config: Required<Pick<HTTPClientConfig, 'timeout' | 'includeRequestID' | 'includeAttemptHeader' | 'followRedirects' | 'maxRedirects'>> & HTTPClientConfig;
+    protected _adapter: NonNullable<HTTPClientConfig['adapter']>;
+    protected _tracker: RequestTracker;
+    protected _parentClient: BaseHTTPClient | null;
+    protected _isBrowserRuntime: boolean;
+    private _requestInterceptors;
+    private _responseObservers;
+    private _errorObservers;
+    private _disabled;
+    constructor(config?: HTTPClientConfig, internal?: InternalClientState);
+    get clientID(): string;
+    get adapterType(): AdapterType;
+    addRequestInterceptor(fn: RequestInterceptor, filter?: RequestInterceptorFilter): RemoveFn;
+    addResponseObserver(fn: ResponseObserver, filter?: ResponseObserverFilter): RemoveFn;
+    addErrorObserver(fn: ErrorObserver, filter?: ErrorObserverFilter): RemoveFn;
+    /**
+     * Start a request. `path` is usually **relative** to {@link HTTPClientConfig.baseURL}
+     * when `baseURL` is set (e.g. `/v1/users`, `v1/users`).
+     *
+     * You may also pass a full **`http:` / `https:`** URL or a **protocol-relative**
+     * `//host/...` string; those are **not** concatenated onto `baseURL`, so one
+     * client can occasionally target another origin without a sub-client. The
+     * final string is still run through `resolveAbsoluteURL` with `baseURL` so
+     * `//…` picks up the right scheme. See `buildURL` in `./utils`.
+     */
+    request<T = unknown>(method: HTTPMethod, path: string, options?: HTTPRequestOptions): HTTPRequestBuilder<T>;
+    get<T = unknown>(path: string, options?: HTTPRequestOptions): HTTPRequestBuilder<T>;
+    post<T = unknown>(path: string, options?: HTTPRequestOptions): HTTPRequestBuilder<T>;
+    put<T = unknown>(path: string, options?: HTTPRequestOptions): HTTPRequestBuilder<T>;
+    patch<T = unknown>(path: string, options?: HTTPRequestOptions): HTTPRequestBuilder<T>;
+    delete<T = unknown>(path: string, options?: HTTPRequestOptions): HTTPRequestBuilder<T>;
+    head<T = unknown>(path: string, options?: HTTPRequestOptions): HTTPRequestBuilder<T>;
+    cancel(requestID: string, reason?: string): void;
+    cancelAll(reason?: string): void;
+    cancelOwn(reason?: string): void;
+    cancelAllWithLabel(label: string, reason?: string): void;
+    cancelOwnWithLabel(label: string, reason?: string): void;
+    listRequests(filter?: {
+        scope?: 'own' | 'all';
+        label?: string;
+    }): {
+        count: number;
+        requests: RequestInfo[];
+    };
+    disable(): void;
+    enable(): void;
+    get isDisabled(): boolean;
+    protected _buildSubClientConfig(overrides?: SubClientConfig): HTTPClientConfig;
+    private _execute;
+    private _sanitizeRedirectRequest;
+    private _isCrossOriginRedirect;
+    /**
+     * Core retry loop — sends the request through the adapter and retries on
+     * retryable status codes (503, 429, etc.) or network errors, up to the
+     * policy's max attempts. Each attempt gets its own independent timeout.
+     *
+     * Cancellation (via cancelSignal) is checked after every retry delay so
+     * the caller doesn't have to wait for the full delay to finish.
+     *
+     * The same RetryPolicy instance is shared across the redirect loop in
+     * _execute, so retries during redirect hops eat into the same budget.
+     */
+    private _dispatchRequestAttempts;
+    /**
+     * Delay that resolves early when the cancel signal fires.
+     * Only wired to cancelSignal (user cancel / cancelAll) — the per-attempt
+     * timeout does NOT cancel retry delays.
+     * Cleans up both the timer and the abort listener to avoid leaks.
+     */
+    private _cancellableDelay;
+    private _buildResponse;
+    /**
+     * Build an HTTPClientError from a failed response.
+     *
+     * Error code priority:
+     * 1. Explicit codeOverride (redirect_disabled, redirect_loop, request_setup_error, adapter_error, stream_write_error, stream_response_error, stream_setup_error)
+     * 2. Response flags (isCancelled → cancelled, isTimeout → timeout),
+     *    except streamed-body failures preserve their specific stream_* code while
+     *    still surfacing `isTimeout: true`
+     * 3. Default fallback → network_error
+     *
+     * Key distinction:
+     * - `adapter_error`: Adapter threw an exception (DNS failure, connection refused, etc.)
+     *   The adapter failed to handle the error gracefully.
+     * - `network_error`: Adapter reported a transport-level failure cleanly via
+     *   `isTransportError`, or returned `status: 0` to indicate a transport
+     *   failure.
+     *
+     * Well-behaved adapters should catch their own transport failures and return
+     * an AdapterResponse instead of throwing. Prefer `isTransportError: true`
+     * when reporting adapter-originated transport failures. If an adapter
+     * throws, that's an adapter implementation problem.
+     */
+    private _makeError;
+    /**
+     * Runs parent + own interceptor chains in order.
+     * Returns the (possibly modified) request, or an InterceptorCancel signal.
+     */
+    private _runInterceptors;
+    /**
+     * Phase for an attempt outcome that will be retried (before the retry delay).
+     * `attempt` matches `onAttemptEnd.attemptNumber` for that outcome.
+     */
+    private _retryOutcomePhase;
+    private _withInternalRequestHeaders;
+    private _buildAttemptRequest;
+    private _bestEffortAttemptRequestFromPending;
+    private _runResponseObservers;
+    private _runErrorObservers;
+    private _composeSignals;
+    private _assertRequestIsSupported;
+    private _assertInterceptorResolvedURL;
+    private _isSupportedRequestURL;
+}
+declare class HTTPClient extends BaseHTTPClient {
+    constructor(config?: HTTPClientConfig);
+    /**
+     * Creates a sub-client that inherits this client's config, request tracker,
+     * and interceptor/observer chain integration.
+     *
+     * `defaultHeaders` use `'replace'` behavior by default. Set
+     * `defaultHeadersStrategy: 'merge'` to preserve inherited defaults and
+     * layer new headers on top.
+     *
+     * If no new `defaultHeaders` are provided, `'merge'` keeps the inherited defaults as-is,
+     * which is useful for sub-clients that only swap adapters or other non-header config.
+     */
+    createSubClient(overrides?: SubClientConfig): HTTPSubClient;
+}
+/**
+ * Public type for sub-clients returned by {@link HTTPClient.createSubClient}.
+ *
+ * Identical to {@link HTTPClient} except `createSubClient` is not available —
+ * sub-clients share the parent's tracker and observer chain but cannot spawn
+ * further sub-clients.
+ */
+type HTTPSubClient = Omit<HTTPClient, 'createSubClient'>;
+
+declare class FetchAdapter implements HTTPAdapter {
+    getType(): AdapterType;
+    send(request: AdapterRequest): Promise<AdapterResponse>;
+}
+
+/**
+ * HTTP responses that are plausibly transient and worth retrying when a retry
+ * policy is explicitly enabled.
+ *
+ * `status === 0` is included on purpose because browser/XHR-style adapters can
+ * surface "no real HTTP response" that way when the network is unavailable or
+ * the request otherwise fails before a normal status code is received.
+ */
+declare const RETRYABLE_STATUS_CODES: ReadonlySet<number>;
+declare const DEFAULT_TIMEOUT_MS = 30000;
+declare const DEFAULT_REQUEST_ID_HEADER = "x-local-client-request-id";
+declare const DEFAULT_REQUEST_ATTEMPT_HEADER = "x-local-client-request-attempt";
+declare const DEFAULT_USER_AGENT = "lifecycleion-http-client";
+declare const HTTP_METHODS: ReadonlyArray<HTTPMethod>;
+/**
+ * Exact-match request headers that browsers either forbid outright or do not
+ * let this client set reliably via plain Fetch/XHR headers.
+ *
+ * Prefix-based rules like `proxy-*` and `sec-*` are handled in `header-utils.ts`.
+ */
+declare const BROWSER_RESTRICTED_HEADERS: ReadonlySet<string>;
+declare const BROWSER_RESTRICTED_HEADER_PREFIXES: ReadonlyArray<string>;
+/**
+ * Headers that can tunnel the real method through POST. Browsers block these
+ * when they try to smuggle forbidden transport methods.
+ */
+declare const BROWSER_METHOD_OVERRIDE_HEADER_NAMES: ReadonlySet<string>;
+/**
+ * Methods that browsers do not allow request headers to tunnel via the
+ * override headers above.
+ */
+declare const BROWSER_FORBIDDEN_METHOD_OVERRIDE_VALUES: ReadonlySet<string>;
+declare const DEFAULT_MAX_REDIRECTS = 5;
+/**
+ * Redirect responses that carry a follow-up `Location` hop. `300` and `304`
+ * are excluded because they do not represent an automatic redirect here.
+ */
+declare const REDIRECT_STATUS_CODES: ReadonlySet<number>;
+
+export { AdapterRequest, AdapterResponse, AdapterType, AttemptEndEvent, AttemptStartEvent, BROWSER_FORBIDDEN_METHOD_OVERRIDE_VALUES, BROWSER_METHOD_OVERRIDE_HEADER_NAMES, BROWSER_RESTRICTED_HEADERS, BROWSER_RESTRICTED_HEADER_PREFIXES, DEFAULT_MAX_REDIRECTS, DEFAULT_REQUEST_ATTEMPT_HEADER, DEFAULT_REQUEST_ID_HEADER, DEFAULT_TIMEOUT_MS, DEFAULT_USER_AGENT, ErrorObserver, ErrorObserverFilter, FetchAdapter, HTTPAdapter, HTTPClient, HTTPClientConfig, HTTPClientError, HTTPMethod, HTTPProgressEvent, HTTPRequestBuilder, HTTPRequestOptions, HTTPResponse, type HTTPSubClient, HTTP_METHODS, REDIRECT_STATUS_CODES, RETRYABLE_STATUS_CODES, type RequestInfo, RequestInterceptor, RequestInterceptorFilter, RequestState, ResponseObserver, ResponseObserverFilter, StreamResponseFactory, SubClientConfig };