@dunx/http 0.5.0 → 0.6.1

package/README.md

@@ -766,6 +766,101 @@ const name: HttpStatusName = 'CONFLICT'; // 'OK' | 'CREATED' | ...
 `HttpError.status` stays `number`, so an uncommon code the table omits (451, 507)
 still works.
 
+## Calling out: `@dunx/http/client`
+
+The outbound half, on a subpath because `HttpFactory` in the root barrel already
+means the inbound direction:
+
+```ts
+import { HttpFactory } from '@dunx/http'; // serving
+import { HttpModule, HttpService } from '@dunx/http/client'; // calling out
+```
+
+```ts
+@Module({
+  imports: [
+    HttpModule.forRootAsync({
+      useFactory: (config: AppConfigService) => ({
+        baseUrl: config.get('upstream').url,
+        timeoutMs: 5_000,
+        retry: { maxRetries: 3, retryDelayMs: 500 },
+      }),
+      inject: [AppConfigService],
+    }),
+  ],
+})
+export class UpstreamModule {}
+```
+
+```ts
+export class Rates {
+  constructor(private readonly http: HttpService) {}
+
+  async latest(base: string): Promise<Quote> {
+    return this.http.get<Quote>('/rates/{base}', {
+      pathParams: { base },
+      queryParams: { precision: 4 },
+    });
+  }
+}
+```
+
+`fetch` and nothing else underneath: it is a Web standard Bun implements natively,
+which is why `axios` and `node-fetch` are banned repo-wide and why there is no
+client dependency to justify. What the service adds is the part every caller
+otherwise rewrites slightly differently.
+
+| | |
+| ---------------------- | ------------------------------------------------------------------------------------------------- |
+| **Timeout** | `AbortSignal.timeout`, combined with a caller's own signal through `AbortSignal.any` |
+| **Retry** | Exponential backoff with jitter from `crypto.getRandomValues`, and `Bun.sleep` between attempts |
+| **`Retry-After`** | Honoured over the computed backoff, in seconds or as an HTTP date, still capped by the ceiling |
+| **URLs** | `buildUrl` and `interpolate` from `@arkv/shared`, so `{param}` and query building are not rewritten |
+| **Tracing** | The inbound request id is forwarded as `x-request-id`, so one trace spans both services |
+| **Bun-only** | `proxy`, `tls`, `unix`, `decompress` passed straight through to `fetch` |
+| **SSE** | `streamSse` yields each `data:` payload; deliberately never retried |
+
+### A failure is not your status
+
+A non-2xx throws `FetchError`, which is **not** an `HttpError`:
+
+```ts
+try {
+  return await this.http.get<User>(`/users/${id}`);
+} catch (error) {
+  if (error instanceof FetchError && error.status === 404) return null;
+  throw new HttpError(HttpStatusCode.BAD_GATEWAY, 'user service unavailable');
+}
+```
+
+An `HttpError` is the inbound contract - the error mapper reads its status and
+answers with it - so an upstream 401 arriving as `HttpError(401)` would tell *your*
+client they are unauthorized, when what happened is that your service could not
+authenticate upstream. Unhandled, a `FetchError` becomes a 500, which is honest;
+only the caller knows whether 404 means "gone" or "not my problem".
+
+A request that never got a response - DNS, refused connection, TLS, or the timeout -
+throws `FetchTransportError` instead, with `aborted` saying which. An abort is never
+retried: the budget for that call is already spent.
+
+### Several upstreams
+
+A named client binds its own options, so two can coexist alongside one default:
+
+```ts
+imports: [
+  HttpModule.forRoot({ baseUrl: internal }),
+  HttpModule.forRoot({ name: 'stripe', baseUrl: stripe, timeoutMs: 10_000 }),
+];
+
+class Payments {
+  readonly stripe = inject(httpClient('stripe'));
+}
+```
+
+`inject()` in a field initialiser rather than a constructor parameter, because a
+`Token` is not a constructor type.
+
 ## Notes
 
 - Routes are discovered at boot by walking each controller's prototype chain, so an

package/dist/chunk-x80f562w.js

@@ -0,0 +1,40 @@
+// @bun
+// src/server/status.ts
+var HttpStatusCode = Object.freeze({
+  OK: 200,
+  CREATED: 201,
+  ACCEPTED: 202,
+  NO_CONTENT: 204,
+  MOVED_PERMANENTLY: 301,
+  FOUND: 302,
+  NOT_MODIFIED: 304,
+  TEMPORARY_REDIRECT: 307,
+  PERMANENT_REDIRECT: 308,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  PAYMENT_REQUIRED: 402,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  NOT_ACCEPTABLE: 406,
+  REQUEST_TIMEOUT: 408,
+  CONFLICT: 409,
+  GONE: 410,
+  PRECONDITION_FAILED: 412,
+  PAYLOAD_TOO_LARGE: 413,
+  URI_TOO_LONG: 414,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  IM_A_TEAPOT: 418,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500,
+  NOT_IMPLEMENTED: 501,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504
+});
+
+export { HttpStatusCode };
+
+//# debugId=881F02139124CAE264756E2164756E21
+//# sourceMappingURL=chunk-x80f562w.js.map

package/dist/chunk-x80f562w.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/server/status.ts"],
+  "sourcesContent": [
+    "/**\n * Frozen object plus an indexed-access union, not an `enum`. An enum emits a\n * runtime object that no other syntax can produce, which is why the repo bans it -\n * see CLAUDE.md. This gives the same `HttpStatusCode.NOT_FOUND` ergonomics, a\n * narrower type, and erases cleanly.\n */\nexport const HttpStatusCode = Object.freeze({\n  OK: 200,\n  CREATED: 201,\n  ACCEPTED: 202,\n  NO_CONTENT: 204,\n  MOVED_PERMANENTLY: 301,\n  FOUND: 302,\n  NOT_MODIFIED: 304,\n  TEMPORARY_REDIRECT: 307,\n  PERMANENT_REDIRECT: 308,\n  BAD_REQUEST: 400,\n  UNAUTHORIZED: 401,\n  PAYMENT_REQUIRED: 402,\n  FORBIDDEN: 403,\n  NOT_FOUND: 404,\n  METHOD_NOT_ALLOWED: 405,\n  NOT_ACCEPTABLE: 406,\n  REQUEST_TIMEOUT: 408,\n  CONFLICT: 409,\n  GONE: 410,\n  PRECONDITION_FAILED: 412,\n  PAYLOAD_TOO_LARGE: 413,\n  URI_TOO_LONG: 414,\n  UNSUPPORTED_MEDIA_TYPE: 415,\n  IM_A_TEAPOT: 418,\n  UNPROCESSABLE_ENTITY: 422,\n  TOO_MANY_REQUESTS: 429,\n  INTERNAL_SERVER_ERROR: 500,\n  NOT_IMPLEMENTED: 501,\n  BAD_GATEWAY: 502,\n  SERVICE_UNAVAILABLE: 503,\n  GATEWAY_TIMEOUT: 504,\n} as const);\n\n/** The status numbers: `200 | 201 | ...`. */\nexport type HttpStatusCode =\n  (typeof HttpStatusCode)[keyof typeof HttpStatusCode];\n\n/** The names: `'OK' | 'CREATED' | ...`. */\nexport type HttpStatusName = keyof typeof HttpStatusCode;\n"
+  ],
+  "mappings": ";;AAMO,IAAM,iBAAiB,OAAO,OAAO;AAAA,EAC1C,IAAI;AAAA,EACJ,SAAS;AAAA,EACT,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,mBAAmB;AAAA,EACnB,OAAO;AAAA,EACP,cAAc;AAAA,EACd,oBAAoB;AAAA,EACpB,oBAAoB;AAAA,EACpB,aAAa;AAAA,EACb,cAAc;AAAA,EACd,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,WAAW;AAAA,EACX,oBAAoB;AAAA,EACpB,gBAAgB;AAAA,EAChB,iBAAiB;AAAA,EACjB,UAAU;AAAA,EACV,MAAM;AAAA,EACN,qBAAqB;AAAA,EACrB,mBAAmB;AAAA,EACnB,cAAc;AAAA,EACd,wBAAwB;AAAA,EACxB,aAAa;AAAA,EACb,sBAAsB;AAAA,EACtB,mBAAmB;AAAA,EACnB,uBAAuB;AAAA,EACvB,iBAAiB;AAAA,EACjB,aAAa;AAAA,EACb,qBAAqB;AAAA,EACrB,iBAAiB;AACnB,CAAU;",
+  "debugId": "881F02139124CAE264756E2164756E21",
+  "names": []
+}

package/dist/client/errors.d.ts

@@ -0,0 +1,64 @@
+import { AppError } from '@dunx/core';
+/**
+ * Any non-2xx response from an outbound call, carrying the parsed body.
+ *
+ * **Deliberately not an `HttpError`.** `HttpError` is the inbound contract - the
+ * default error mapper reads its `status` and answers the caller with it - so an
+ * upstream 401 arriving as an `HttpError(401)` would make this service reply 401,
+ * telling *its* client "you are unauthorized" when what actually happened is that
+ * this service could not authenticate upstream. Extending `AppError` instead means
+ * an unhandled upstream failure surfaces as a 500, which is the honest default, and
+ * a caller who knows better maps it:
+ *
+ * ```ts
+ * try {
+ *   return await this.http.get(url);
+ * } catch (error) {
+ *   if (error instanceof FetchError && error.status === 404) return null;
+ *   throw new HttpError(HttpStatusCode.BAD_GATEWAY, 'upstream unavailable');
+ * }
+ * ```
+ */
+export declare class FetchError extends AppError {
+    readonly status: number;
+    readonly statusText: string;
+    /** The response body, parsed as JSON when it was, else text, else undefined. */
+    readonly body: unknown;
+    readonly response: {
+        readonly method: string;
+        readonly url: string;
+        readonly headers: Headers;
+    };
+    readonly name = "FetchError";
+    constructor(status: number, statusText: string, 
+    /** The response body, parsed as JSON when it was, else text, else undefined. */
+    body: unknown, response: {
+        readonly method: string;
+        readonly url: string;
+        readonly headers: Headers;
+    });
+}
+/**
+ * The request never produced a response: DNS failure, connection refused, TLS
+ * rejection, or the timeout firing. `fetch` reports these as a `TypeError` or an
+ * `AbortError`, neither of which says which call died.
+ *
+ * Separate from {@link FetchError} because there is no status to branch on and the
+ * retry decision is different: a transport failure is worth retrying by default,
+ * while a 400 never is.
+ */
+export declare class FetchTransportError extends AppError {
+    readonly response: {
+        readonly method: string;
+        readonly url: string;
+    };
+    /** True when the timeout or the caller's signal aborted it. */
+    readonly aborted: boolean;
+    readonly name = "FetchTransportError";
+    constructor(response: {
+        readonly method: string;
+        readonly url: string;
+    }, 
+    /** True when the timeout or the caller's signal aborted it. */
+    aborted: boolean, options?: ErrorOptions);
+}

package/dist/client/json.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A `JSON.stringify` that survives a cycle. **For logging only.**
+ *
+ * Never for a request body. The implementation this was ported from used it for
+ * both, so a circular payload was *sent* upstream as `"[Circular]"` - a wrong body
+ * that reads as a successful call and comes back as someone else's 400. A body goes
+ * through plain `JSON.stringify`, which throws, because a cycle there is a bug in
+ * the caller and should say so.
+ */
+export declare const safeStringify: (value: unknown) => string;
+/**
+ * A plain object: `{}`, `Object.create(null)`, or a JSON-parsed value. Anything
+ * with its own prototype - `Date`, `Map`, `Error`, a class instance - is not one.
+ *
+ * The prototype check rather than the reference's `typeof === 'object' && !Array
+ * && !(instanceof Error)`, which answered `true` for a `Date` and for every class
+ * instance, so "is this a plain object" did not mean what it said. Body routing
+ * does not use this - see {@link isJsonBody} - so tightening it changes no
+ * behaviour beyond making the predicate honest.
+ */
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Whether a payload should be JSON-encoded, or handed to `fetch` as-is.
+ *
+ * `fetch` already knows what to do with a `BodyInit` - it sets the boundary for a
+ * `FormData`, the content type for a `URLSearchParams`, streams a `ReadableStream`
+ * - so the only question is whether this value is one. Everything else, including
+ * a `Date` or a class instance, is JSON: that is what `JSON.stringify` is for.
+ *
+ * Listed explicitly rather than inferred from `isPlainObject`, because the two
+ * questions have different answers. `new Date()` is not a plain object but is
+ * JSON-encodable; a `Blob` is neither.
+ */
+export declare const isJsonBody: (payload: unknown) => boolean;

package/dist/client/module.d.ts

@@ -0,0 +1,66 @@
+import { type Deps, type DynamicModule, type FactoryProvider, type Token } from '@dunx/core';
+import { type HttpClientOptionsInit } from './options.js';
+import { HttpService } from './service.js';
+/**
+ * The token a named client is bound to.
+ *
+ * Memoised, because `token()` returns a fresh object every call - without this the
+ * module and the consumer would hold different tokens for `'stripe'` and the lookup
+ * would miss. Same name in, same token out.
+ *
+ * A `Token` is not a constructor type, so a named client cannot be a constructor
+ * parameter. Reach it with `inject()` in a field initialiser:
+ *
+ * ```ts
+ * class Payments {
+ *   readonly stripe = inject(httpClient('stripe'));
+ * }
+ * ```
+ */
+export declare const httpClient: (name: string) => Token<HttpService>;
+/**
+ * The outbound half of `@dunx/http`.
+ *
+ * Named `HttpModule` and `HttpService` under the `./client` subpath rather than in
+ * the root barrel, where `HttpFactory` already means the inbound direction. The
+ * subpath is what keeps the name unambiguous at the import site:
+ *
+ * ```ts
+ * import { HttpFactory } from '@dunx/http';         // serving
+ * import { HttpModule } from '@dunx/http/client';   // calling out
+ * ```
+ *
+ * It depends on `Logger` and `RequestContext`, both of which core always binds, so
+ * it works in an app that imported no logging module at all.
+ */
+export declare class HttpModule {
+    /**
+     * Binds `HttpService` and `HttpClientOptions`, or `httpClient(init.name)` alone
+     * when `name` is set - a named registration deliberately does not also claim
+     * `HttpService`, so several upstreams can coexist alongside one default.
+     */
+    static forRoot(init?: HttpClientOptionsInit): DynamicModule;
+    /**
+     * `forRoot` with the options behind a factory, which is the one thing a
+     * zero-argument `forRoot` cannot do: read the base url or the timeout off
+     * `ConfigService`.
+     *
+     * There is no separate async machinery - the container resolves eagerly and
+     * awaits factories before any constructor runs, so awaited config is settled by
+     * the time anything is built.
+     *
+     * ```ts
+     * HttpModule.forRootAsync({
+     *   useFactory: (config: AppConfigService) => ({
+     *     baseUrl: config.get('upstream').url,
+     *   }),
+     *   inject: [AppConfigService],
+     * });
+     * ```
+     *
+     * `name` is a parameter rather than a field of the awaited init, because the
+     * token has to exist before the factory runs.
+     */
+    static forRootAsync(load: () => HttpClientOptionsInit | Promise<HttpClientOptionsInit>, name?: string): DynamicModule;
+    static forRootAsync<const D extends Deps>(config: FactoryProvider<HttpClientOptionsInit, D>, name?: string): DynamicModule;
+}

package/dist/client/options.d.ts

@@ -0,0 +1,57 @@
+import type { RetryOptions } from './retry.js';
+/**
+ * Named `HttpClientOptions`, not `HttpOptions`: the server half already exports
+ * that from `@dunx/http` for `HttpFactory.create`, and two things called
+ * `HttpOptions` meaning opposite directions of traffic is the confusion this
+ * subpath exists to avoid.
+ */
+export interface HttpClientOptionsInit {
+    /**
+     * Prefixed to a relative `path`. With it, calls name a path; without it, every
+     * call passes a whole url.
+     */
+    readonly baseUrl?: string | URL;
+    /** Per-request budget, enforced with `AbortSignal.timeout`. @default 30000 */
+    readonly timeoutMs?: number;
+    /** Sent on every request, under anything a call sets itself. */
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly retry?: RetryOptions<unknown>;
+    /**
+     * Forward the inbound request id to the upstream, so one trace spans both
+     * services. `true` uses `x-request-id`; a string names the header. Read from
+     * `RequestContext`, so it only carries when there is a request in scope.
+     *
+     * @default true
+     */
+    readonly propagateRequestId?: boolean | string;
+    /** Bound as its own token, so a second client can be injected by name. */
+    readonly name?: string;
+    /**
+     * Bun-only `fetch` extensions, passed straight through. None of these exist on
+     * Node's fetch, and they are the reason an outbound client on Bun can do things a
+     * ported one cannot: talk through a proxy, pin a certificate, or reach a unix
+     * socket, with no dependency.
+     */
+    readonly proxy?: string;
+    readonly tls?: Bun.TLSOptions;
+    readonly unix?: string;
+    /** @default true - Bun decompresses by default. */
+    readonly decompress?: boolean;
+    /** Bun's own request/response tracing on stderr. Never on in production. */
+    readonly verbose?: boolean;
+}
+export declare const DEFAULT_REQUEST_ID_HEADER = "x-request-id";
+/**
+ * The resolved options, as a class so it is both the injection token and the type
+ * a factory annotates - the same trick `RedisOptions` and `ConfigService` use.
+ */
+export declare class HttpClientOptions {
+    readonly baseUrl: string | undefined;
+    readonly timeoutMs: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly retry: RetryOptions<unknown>;
+    readonly requestIdHeader: string | undefined;
+    readonly name: string | undefined;
+    readonly fetchOptions: Readonly<Record<string, unknown>>;
+    constructor(init?: HttpClientOptionsInit);
+}

package/dist/client/retry.d.ts

@@ -0,0 +1,49 @@
+export interface BackoffOptions {
+    /** Base delay, doubled each attempt. */
+    readonly baseMs: number;
+    /** @default 2 */
+    readonly power?: number;
+    /** Upper bound of the random component added to each delay. @default 1000 */
+    readonly jitterMs?: number;
+    /** @default 30000 */
+    readonly maxMs?: number;
+}
+/** `base * power^attempt + jitter`, capped. `attempt` is 0 for the first retry. */
+export declare const backoffDelay: (attempt: number, { baseMs, power, jitterMs, maxMs }: BackoffOptions) => number;
+/**
+ * The wait an upstream asked for, in ms, or undefined.
+ *
+ * RFC 9110 allows either a delay in seconds or an HTTP date, and both appear in
+ * the wild - GitHub sends seconds, some CDNs send a date. Ignoring the header, as
+ * the reference did, means retrying straight back into a rate limit that had just
+ * told you exactly how long to wait.
+ */
+export declare const retryAfterMs: (headers: Headers, now?: number) => number | undefined;
+/**
+ * Statuses worth trying again: a server that failed, one that is overloaded, and
+ * one that timed out. Deliberately narrower than the source, which also retried
+ * 409 and 422 - both of those are the server rejecting the *request*, and sending
+ * it again unchanged gets the same answer.
+ */
+export declare const isRetryableStatus: (status: number) => boolean;
+export interface RetryOptions<T> {
+    /** Retries *after* the first attempt, so 3 means up to 4 calls. @default 3 */
+    readonly maxRetries?: number;
+    /** @default 1000 */
+    readonly retryDelayMs?: number;
+    readonly backoff?: Omit<BackoffOptions, 'baseMs'>;
+    /** @default isRetryableStatus */
+    readonly shouldRetryOnStatus?: (status: number) => boolean;
+    /** Honour a `Retry-After` header over the computed backoff. @default true */
+    readonly respectRetryAfter?: boolean;
+    readonly onAttempt?: (attempt: number, isRetry: boolean) => void;
+    readonly onError?: (error: unknown, attempt: number, willRetry: boolean) => void;
+    readonly onSuccess?: (result: T, attempt: number) => void;
+}
+/**
+ * Runs `operation`, retrying per `options`.
+ *
+ * `Bun.sleep` rather than a `setTimeout` promise: it is the runtime's own timer and
+ * needs no wrapper.
+ */
+export declare const executeWithRetry: <T>(operation: () => Promise<T> | T, options?: RetryOptions<T>) => Promise<T>;

package/dist/client/service.d.ts

@@ -0,0 +1,104 @@
+import { Logger, RequestContext } from '@dunx/core';
+import { UrlHelper, type ParamsType } from '@arkv/shared';
+import type { HttpMethod } from '../route/marker.js';
+import { HttpClientOptions } from './options.js';
+import { type RetryOptions } from './retry.js';
+/** The client speaks two more verbs than a route can declare. */
+export type RequestMethod = HttpMethod | 'HEAD' | 'OPTIONS';
+/**
+ * `@arkv/shared`'s own param type, imported rather than restated - a local copy
+ * would drift from what `buildUrl` actually accepts, which is how `null` ended up
+ * in the first draft of this file and `interpolate` would never have seen it.
+ */
+type Params = ParamsType;
+export type HeaderFactory = (params: {
+    /** Unix seconds, which is what every HMAC scheme signs. */
+    readonly timestamp: number;
+    readonly method: RequestMethod;
+    /** `pathname + search`, the part such schemes sign. */
+    readonly requestPath: string;
+    /** The serialised body, or `''`. */
+    readonly body: string;
+}) => Record<string, string>;
+export interface RequestConfig<TRequest = unknown, TResponse = unknown> {
+    readonly method: RequestMethod;
+    /** Absolute, or relative to `baseUrl`. Omit when `baseUrl` plus `path` is enough. */
+    readonly url?: string | URL;
+    readonly payload?: TRequest;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Appended to the base, with `{param}` interpolated from `pathParams`. */
+    readonly path?: string;
+    readonly pathParams?: Params;
+    readonly queryParams?: Params;
+    /** Overrides the client's default budget. */
+    readonly timeoutMs?: number;
+    /** Called once per attempt, so a signature covers the body it is sent with. */
+    readonly headerFactory?: HeaderFactory;
+    /** Merged into the async context for this call, so its logs carry it. */
+    readonly flow?: string;
+    readonly retry?: RetryOptions<TResponse>;
+    /** Cancels the call. Combined with the timeout, whichever fires first. */
+    readonly signal?: AbortSignal;
+}
+type BaseOptions<TRequest, TResponse> = Omit<RequestConfig<TRequest, TResponse>, 'method' | 'url' | 'payload'>;
+/**
+ * A `fetch` client with a per-request timeout, retry with backoff, request-id
+ * propagation and one log line per call.
+ *
+ * `fetch` and nothing else: it is a Web standard Bun implements natively, so there
+ * is no client dependency to justify - which is also why `axios` and `node-fetch`
+ * are banned repo-wide. What this adds over calling `fetch` yourself is the parts
+ * every caller otherwise reimplements slightly differently: the timeout, the
+ * retry policy, `Retry-After`, url building, and a failure that says which call
+ * failed.
+ *
+ * Extends `UrlHelper` from `@arkv/shared`, so `buildUrl` and `interpolate` are
+ * available on the service, and there is one implementation of them across the
+ * owner's projects rather than a fork per repo.
+ */
+export declare class HttpService extends UrlHelper {
+    private readonly options;
+    private readonly logger;
+    private readonly requestContext;
+    constructor(options: HttpClientOptions, logger: Logger, requestContext: RequestContext);
+    request<TRequest = unknown, TResponse = unknown>(config: RequestConfig<TRequest, TResponse>): Promise<TResponse>;
+    get<TResponse = unknown>(url?: string | URL, options?: BaseOptions<never, TResponse>): Promise<TResponse>;
+    post<TRequest = unknown, TResponse = unknown>(url?: string | URL, payload?: TRequest, options?: BaseOptions<TRequest, TResponse>): Promise<TResponse>;
+    put<TRequest = unknown, TResponse = unknown>(url?: string | URL, payload?: TRequest, options?: BaseOptions<TRequest, TResponse>): Promise<TResponse>;
+    patch<TRequest = unknown, TResponse = unknown>(url?: string | URL, payload?: TRequest, options?: BaseOptions<TRequest, TResponse>): Promise<TResponse>;
+    delete<TResponse = unknown>(url?: string | URL, options?: BaseOptions<never, TResponse>): Promise<TResponse>;
+    /**
+     * Yields each `data:` payload of a Server-Sent-Events response, consuming the
+     * terminating `[DONE]` sentinel rather than yielding it.
+     *
+     * **No retry**, deliberately: a partially consumed stream cannot be replayed, so
+     * retrying would re-deliver events the caller has already seen. The timeout
+     * covers the connect only - it is dropped once headers arrive, or a long-lived
+     * stream would be cut off mid-flight.
+     *
+     * Hand-rolled rather than delegated: Bun exposes no `EventSource` global and no
+     * SSE parser, which was measured rather than assumed.
+     */
+    streamSse<TRequest = unknown>(config: Omit<RequestConfig<TRequest>, 'method' | 'retry'> & {
+        readonly method?: 'GET' | 'POST';
+    }): AsyncGenerator<string>;
+    /**
+     * Resolves the target, accepting the three forms a caller actually reaches for:
+     * an absolute url, a path relative to `baseUrl`, or `baseUrl` plus an explicit
+     * `path`.
+     *
+     * `get('/users')` is the one worth calling out. A relative first argument is what
+     * every HTTP client takes once a base url exists, and passing it straight to
+     * `buildUrl` throws `ERR_INVALID_URL` from inside `new URL()` - a message naming
+     * neither the call nor the missing base. So a first argument that is not an
+     * absolute url is treated as the path, which is what it reads as.
+     *
+     * `URL.canParse` decides, rather than a regex over `//` or `:` - it is the same
+     * parser `new URL` uses, so the two cannot disagree.
+     */
+    private urlFor;
+    /** `serialised` is what a `headerFactory` signs, and is `''` for no body. */
+    private bodyFor;
+    private send;
+}
+export {};

package/dist/client.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@dunx/http/client` - the outbound half.
+ *
+ * A subpath rather than the root barrel: `HttpFactory` there is the inbound
+ * direction, and `HttpModule` next to it would read as either. Importing
+ * `@dunx/http` does not load any of this.
+ */
+export { FetchError, FetchTransportError } from './client/errors.js';
+export { isJsonBody, isPlainObject, safeStringify } from './client/json.js';
+export { DEFAULT_REQUEST_ID_HEADER, HttpClientOptions, type HttpClientOptionsInit, } from './client/options.js';
+export { backoffDelay, executeWithRetry, isRetryableStatus, retryAfterMs, type BackoffOptions, type RetryOptions, } from './client/retry.js';
+export { httpClient, HttpModule } from './client/module.js';
+export { HttpService, type HeaderFactory, type RequestConfig, type RequestMethod, } from './client/service.js';