@molecule/app-http 1.2.1 → 1.4.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-18T17:46:02.937Z
+Generated: 2026-10-19T22:40:45.495Z
 -->
 
 # @molecule/app-http
@@ -187,6 +187,58 @@ interface HttpClientConfig {
    * it returns.
    */
   authScheme?: string
+
+  /**
+   * Default retry policy for every request this client makes, or `false` to
+   * disable retries. A request's own `retry` overrides it.
+   */
+  retry?: RetryOptions | false
+}
+```
+
+#### `RetryOptions`
+
+Tuning for the retry policy.
+
+```typescript
+interface RetryOptions {
+  /**
+   * Maximum retries AFTER the first attempt. Defaults to `2` (three attempts
+   * in total).
+   */
+  maxRetries?: number
+
+  /** Base backoff in milliseconds. Defaults to `300`. */
+  baseDelayMs?: number
+
+  /** Maximum backoff (before `Retry-After` can extend it). Defaults to `5000`. */
+  maxDelayMs?: number
+
+  /** Statuses treated as transient. Defaults to `[502, 503, 504]`. */
+  retryStatuses?: number[]
+}
+```
+
+#### `RetryDecisionInput`
+
+The request fields the policy decides from.
+
+```typescript
+interface RetryDecisionInput {
+  /** The request method. */
+  method: HttpMethod
+  /** The request headers (lower-cased lookup is done here). */
+  headers: Record<string, string | undefined>
+  /** The HTTP status, or `0` when no response arrived. */
+  status: number
+  /** How many retries have already been made (0 for the first failure). */
+  attempt: number
+  /** The error message, used to recognize a connection reset/refusal. */
+  errorMessage?: string
+  /** `true` when the request was aborted before a response. */
+  aborted?: boolean
+  /** Overrides layered over {@link DEFAULT_RETRY_OPTIONS}. */
+  options?: RetryOptions | false
 }
 ```
 
@@ -264,6 +316,17 @@ interface RequestConfig {
    * Custom request options (implementation-specific).
    */
   options?: Record<string, unknown>
+
+  /**
+   * Retry policy for this request, or `false` to disable retries.
+   *
+   * The default policy retries only IDEMPOTENT requests (`GET`/`HEAD`/`PUT`/
+   * `DELETE`/`OPTIONS`, and `POST`/`PATCH` carrying an `Idempotency-Key`) on
+   * `502`/`503`/`504` or a reset/refused connection, twice, with exponential
+   * backoff and jitter, honoring `Retry-After`. See `@molecule/app-http`'s
+   * `shouldRetryRequest`.
+   */
+  retry?: RetryOptions | false
 }
 ````
 
@@ -401,14 +464,38 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTION
 
 HTTP error with response details.
 
+**`status` is an HTTP status when the server answered, and `0` when it did not.**
+A `0` means NO response exists: the request was aborted (an `AbortController`, a
+component's effect cleanup, a route change tearing the request down) or the
+network failed before anything came back. It is not an HTTP status at all, so it
+says nothing about the session — an app must never treat `status < 500` as
+"signed out", because every aborted request on a route change would clear the
+session. The correct check is {@link isAuthFailure} (`status === 401 || status === 403`);
+`isNoResponse` (`status === 0`) identifies this case.
+
 ```typescript
 class HttpError extends Error {
+  /**
+   * Builds a failed-request error.
+   *
+   * @param message - Human-readable message (already translated where a key exists).
+   * @param status - HTTP status, or `0` when no response was received (aborted / network failure).
+   * @param response - Parsed response when the server answered, otherwise undefined.
+   * @param config - The request config that failed.
+   * @param errorKey - Translation key for the failure (`http.error.aborted` for an
+   *   aborted request, `http.error.networkError` for a real network failure).
+   * @param aborted - Whether the request was aborted before a response: an
+   *   `AbortController` signal (component cleanup, a cancelled request) or the
+   *   browser tearing the fetch down during a navigation. Distinguishes an abort
+   *   from a network outage on the same `status === 0`, without parsing the message.
+   */
   constructor(
     message: string,
     public status: number,
     public response?: HttpResponse,
     public config?: FullRequestConfig,
     public errorKey?: string,
+    public aborted = false,
   ) {
     super(message)
     this.name = 'HttpError'
@@ -468,6 +555,66 @@ function awaitAuthGate(request?: AuthGateRequest): Promise<void>
 
 **Returns:** A promise that settles when the gate has released the request.
 
+#### `isHttpError(err)`
+
+Whether `err` is an {@link HttpError} from this package.
+
+```typescript
+function isHttpError(err: unknown): boolean
+```
+
+- `err` — Any thrown value.
+
+**Returns:** True for an `HttpError`.
+
+#### `isAuthFailure(err)`
+
+Whether the server REJECTED the request's credential — the only failure that
+justifies clearing a session.
+
+`401` (unauthenticated/expired token) and `403` (authenticated but refused) are
+the two statuses that say "this credential no longer authorizes this session".
+Everything else — `0` (aborted or offline), `404` (wrong endpoint), `5xx` (server
+fault), a rate limit — says nothing about the credential.
+
+```typescript
+function isAuthFailure(err: unknown): boolean
+```
+
+- `err` — Any thrown value.
+
+**Returns:** True only when `err` is an `HttpError` with status 401 or 403.
+
+#### `isNoResponse(err)`
+
+Whether no response was received at all: the request was aborted or the network
+failed. `status === 0` is not an HTTP status — it must never be read as
+"the user is not signed in".
+
+```typescript
+function isNoResponse(err: unknown): boolean
+```
+
+- `err` — Any thrown value.
+
+**Returns:** True when `err` is an `HttpError` with status `0`.
+
+#### `isAborted(err)`
+
+Whether the request was ABORTED (an `AbortController` signal, or the browser
+cancelling the fetch during a navigation) rather than failing on the network.
+
+Both arrive as `status === 0`; this distinguishes them, so a UI can stay silent
+for a cancelled request while still reporting a real outage.
+
+```typescript
+function isAborted(err: unknown): boolean
+```
+
+- `err` — Any thrown value.
+
+**Returns:** True when `err` is an `HttpError` flagged `aborted`.
+
 #### `createFetchClient(config)`
 
 Creates a fetch-based HTTP client using the native Fetch API.
@@ -484,6 +631,83 @@ function createFetchClient(config?: HttpClientConfig): HttpClient
 
 **Returns:** A fully configured `HttpClient` instance.
 
+#### `isIdempotentRequest(method, headers)`
+
+Whether a request may be repeated at all.
+
+```typescript
+function isIdempotentRequest(
+  method: HttpMethod,
+  headers: Record<string, string | undefined>,
+): boolean
+```
+
+- `method` — The HTTP method.
+- `headers` — The request headers (an `Idempotency-Key` makes POST/PATCH repeatable).
+
+**Returns:** `true` when repeating the request cannot duplicate a side effect.
+
+#### `isTransientConnectionError(message)`
+
+Whether a connection-level error is transient (a restarted process refuses
+or resets connections; a DNS or TLS configuration error does not).
+
+```typescript
+function isTransientConnectionError(message: string | undefined): boolean
+```
+
+- `message` — The error message.
+
+**Returns:** `true` for reset/refused/closed-early/timeout shapes.
+
+#### `parseRetryAfter(value, now)`
+
+Parse a `Retry-After` header into milliseconds from now.
+
+```typescript
+function parseRetryAfter(value: string | undefined, now?: number): number | undefined
+```
+
+- `value` — The header value (`seconds` or an HTTP date).
+- `now` — The clock, injected for tests.
+
+**Returns:** Milliseconds to wait, or undefined when absent/unparseable.
+
+#### `shouldRetryRequest(input)`
+
+Decide whether one failed request should be retried.
+
+```typescript
+function shouldRetryRequest(input: RetryDecisionInput): boolean
+```
+
+- `input` — The method, headers, status/error and attempt count.
+
+**Returns:** `true` when the request may be repeated.
+
+#### `retryDelayMs(retryAfter, attempt, options, random)`
+
+Compute the wait before the next attempt.
+
+`Retry-After` wins when the server sent one (it knows when the instance will
+be back); otherwise exponential backoff with full jitter.
+
+```typescript
+function retryDelayMs(
+  retryAfter: string | undefined,
+  attempt: number,
+  options?: false | RetryOptions,
+  random?: () => number,
+): number
+```
+
+- `retryAfter` — The raw `Retry-After` header value, when present.
+- `attempt` — How many retries have already been made (0 for the first).
+- `options` — Policy overrides.
+- `random` — Jitter source, injected for tests (defaults to `Math.random`).
+
+**Returns:** Milliseconds to wait before retrying.
+
 #### `unwrapList(res)`
 
 Normalize an unknown response body into a typed array.
@@ -507,6 +731,11 @@ r.json())`) or the `HttpResponse` returned by `useHttpClient().get(...)`.
 Both shapes are handled here so pages don't have to remember to call
 `unwrapList(res.data)` vs `unwrapList(res)`.
 
+A custom envelope such as `{ items: [...], count: 10 }` is not a `data`
+envelope and returns `[]`. Read its named array directly: `body.items` for
+raw JSON, or `response.data.items` for an `HttpResponse`. Passing that
+array to `unwrapList` is also valid; passing the enclosing object is not.
+
 ```typescript
 function unwrapList(res: unknown): T[]
 ```
@@ -665,6 +894,14 @@ function del(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
 
 ### Constants
 
+#### `DEFAULT_RETRY_OPTIONS`
+
+The resolved policy used when a caller passes no options.
+
+```typescript
+const DEFAULT_RETRY_OPTIONS: Required<RetryOptions>
+```
+
 #### `fetchClient`
 
 Pre-created fetch client for environments where `fetch` is available.
@@ -751,6 +988,17 @@ skipAuthGate: true })`. Without the opt-out the gate waits on itself, the restor
 settles, and every request the gate holds stalls until it times out (3 s).
 `@molecule/app-auth`'s own restore does not need it (it calls `fetch`, not this client).
 
+**A failed request's `status` is `0` when NO response arrived — never read it as
+"signed out".** An aborted request (an `AbortController` signal, a component's
+effect cleanup, a route change tearing the fetch down) and a network outage both
+throw an `HttpError` with `status === 0`; the aborted ones also carry
+`aborted: true` and the `http.error.aborted` key, the rest `http.error.networkError`.
+Neither says anything about the session. To decide whether a session ended, use
+`isAuthFailure(err)` (401/403 only); `isNoResponse(err)` identifies the no-response
+case so a caller can stay silent instead of reporting an outage. **Do not write
+`err instanceof HttpError && err.status < 500` as a sign-out check** — it clears
+the session on every aborted navigation request.
+
 ## Translations
 
 Translation strings are provided by `@molecule/app-locales-http`.

package/dist/client.d.ts

@@ -6,6 +6,7 @@
  * @module
  */
 import type { ErrorInterceptor, RequestInterceptor, ResponseInterceptor } from './interceptors.js';
+import type { RetryOptions } from './retry.js';
 import type { FullRequestConfig, HttpResponse, RequestConfig } from './types.js';
 /**
  * HTTP client interface.
@@ -109,5 +110,10 @@ export interface HttpClientConfig {
      * it returns.
      */
     authScheme?: string;
+    /**
+     * Default retry policy for every request this client makes, or `false` to
+     * disable retries. A request's own `retry` overrides it.
+     */
+    retry?: RetryOptions | false;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEhF;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEtC;;;OAGG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAEzE;;OAEG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAE/E;;;;OAIG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAEhG;;;OAGG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAE/F;;;OAGG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAEjG;;OAEG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAElF;;;OAGG;IACH,qBAAqB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAAA;IAElE;;;OAGG;IACH,sBAAsB,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAAA;IAEpE;;;OAGG;IACH,mBAAmB,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAAA;IAE9D;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAExC;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI,CAAA;IAE7B;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEvC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAClG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEhF;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEtC;;;OAGG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAEzE;;OAEG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAE/E;;;;OAIG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAEhG;;;OAGG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAE/F;;;OAGG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAEjG;;OAEG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAElF;;;OAGG;IACH,qBAAqB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAAA;IAElE;;;OAGG;IACH,sBAAsB,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAAA;IAEpE;;;OAGG;IACH,mBAAmB,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAAA;IAE9D;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAExC;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI,CAAA;IAE7B;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEvC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,KAAK,CAAC,EAAE,YAAY,GAAG,KAAK,CAAA;CAC7B"}

package/dist/errors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Classify a failed request instead of reading its `status` by hand.
+ *
+ * A failure from this package is an {@link HttpError} whose `status` is either an
+ * HTTP status (the server answered) or `0` (it did not — the request was aborted or
+ * the network failed). Code that clears a session must ask "did the server REJECT
+ * the credential?", which is `status === 401 || status === 403` and nothing else:
+ *
+ * ```typescript
+ * try {
+ *   await http.get('/projects')
+ * } catch (err) {
+ *   if (isAuthFailure(err)) clearSession()
+ *   else if (isNoResponse(err)) return // aborted / offline — keep the session
+ *   else showError(err)
+ * }
+ * ```
+ *
+ * `err instanceof HttpError && err.status < 500` is the trap these helpers exist to
+ * replace: an aborted request (a component unmounting, a route change cancelling an
+ * in-flight fetch) and a network outage both arrive with `status === 0`, so that
+ * check signs the user out on every navigation that cancels a request.
+ *
+ * @module
+ */
+import { HttpError } from './types.js';
+/**
+ * Whether `err` is an {@link HttpError} from this package.
+ *
+ * @param err - Any thrown value.
+ * @returns True for an `HttpError`.
+ */
+export declare function isHttpError(err: unknown): err is HttpError;
+/**
+ * Whether the server REJECTED the request's credential — the only failure that
+ * justifies clearing a session.
+ *
+ * `401` (unauthenticated/expired token) and `403` (authenticated but refused) are
+ * the two statuses that say "this credential no longer authorizes this session".
+ * Everything else — `0` (aborted or offline), `404` (wrong endpoint), `5xx` (server
+ * fault), a rate limit — says nothing about the credential.
+ *
+ * @param err - Any thrown value.
+ * @returns True only when `err` is an `HttpError` with status 401 or 403.
+ */
+export declare function isAuthFailure(err: unknown): boolean;
+/**
+ * Whether no response was received at all: the request was aborted or the network
+ * failed. `status === 0` is not an HTTP status — it must never be read as
+ * "the user is not signed in".
+ *
+ * @param err - Any thrown value.
+ * @returns True when `err` is an `HttpError` with status `0`.
+ */
+export declare function isNoResponse(err: unknown): boolean;
+/**
+ * Whether the request was ABORTED (an `AbortController` signal, or the browser
+ * cancelling the fetch during a navigation) rather than failing on the network.
+ *
+ * Both arrive as `status === 0`; this distinguishes them, so a UI can stay silent
+ * for a cancelled request while still reporting a real outage.
+ *
+ * @param err - Any thrown value.
+ * @returns True when `err` is an `HttpError` flagged `aborted`.
+ */
+export declare function isAborted(err: unknown): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEtC;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,SAAS,CAE1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE/C"}

package/dist/errors.js

@@ -0,0 +1,75 @@
+/**
+ * Classify a failed request instead of reading its `status` by hand.
+ *
+ * A failure from this package is an {@link HttpError} whose `status` is either an
+ * HTTP status (the server answered) or `0` (it did not — the request was aborted or
+ * the network failed). Code that clears a session must ask "did the server REJECT
+ * the credential?", which is `status === 401 || status === 403` and nothing else:
+ *
+ * ```typescript
+ * try {
+ *   await http.get('/projects')
+ * } catch (err) {
+ *   if (isAuthFailure(err)) clearSession()
+ *   else if (isNoResponse(err)) return // aborted / offline — keep the session
+ *   else showError(err)
+ * }
+ * ```
+ *
+ * `err instanceof HttpError && err.status < 500` is the trap these helpers exist to
+ * replace: an aborted request (a component unmounting, a route change cancelling an
+ * in-flight fetch) and a network outage both arrive with `status === 0`, so that
+ * check signs the user out on every navigation that cancels a request.
+ *
+ * @module
+ */
+import { HttpError } from './types.js';
+/**
+ * Whether `err` is an {@link HttpError} from this package.
+ *
+ * @param err - Any thrown value.
+ * @returns True for an `HttpError`.
+ */
+export function isHttpError(err) {
+    return err instanceof HttpError;
+}
+/**
+ * Whether the server REJECTED the request's credential — the only failure that
+ * justifies clearing a session.
+ *
+ * `401` (unauthenticated/expired token) and `403` (authenticated but refused) are
+ * the two statuses that say "this credential no longer authorizes this session".
+ * Everything else — `0` (aborted or offline), `404` (wrong endpoint), `5xx` (server
+ * fault), a rate limit — says nothing about the credential.
+ *
+ * @param err - Any thrown value.
+ * @returns True only when `err` is an `HttpError` with status 401 or 403.
+ */
+export function isAuthFailure(err) {
+    return isHttpError(err) && (err.status === 401 || err.status === 403);
+}
+/**
+ * Whether no response was received at all: the request was aborted or the network
+ * failed. `status === 0` is not an HTTP status — it must never be read as
+ * "the user is not signed in".
+ *
+ * @param err - Any thrown value.
+ * @returns True when `err` is an `HttpError` with status `0`.
+ */
+export function isNoResponse(err) {
+    return isHttpError(err) && err.status === 0;
+}
+/**
+ * Whether the request was ABORTED (an `AbortController` signal, or the browser
+ * cancelling the fetch during a navigation) rather than failing on the network.
+ *
+ * Both arrive as `status === 0`; this distinguishes them, so a UI can stay silent
+ * for a cancelled request while still reporting a real outage.
+ *
+ * @param err - Any thrown value.
+ * @returns True when `err` is an `HttpError` flagged `aborted`.
+ */
+export function isAborted(err) {
+    return isHttpError(err) && err.aborted;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEtC;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,OAAO,GAAG,YAAY,SAAS,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAA;AACvE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,CAAA;AAC7C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,GAAY;IACpC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,OAAO,CAAA;AACxC,CAAC"}

package/dist/index.d.ts

@@ -88,12 +88,25 @@
  * settles, and every request the gate holds stalls until it times out (3 s).
  * `@molecule/app-auth`'s own restore does not need it (it calls `fetch`, not this client).
  *
+ * **A failed request's `status` is `0` when NO response arrived — never read it as
+ * "signed out".** An aborted request (an `AbortController` signal, a component's
+ * effect cleanup, a route change tearing the fetch down) and a network outage both
+ * throw an `HttpError` with `status === 0`; the aborted ones also carry
+ * `aborted: true` and the `http.error.aborted` key, the rest `http.error.networkError`.
+ * Neither says anything about the session. To decide whether a session ended, use
+ * `isAuthFailure(err)` (401/403 only); `isNoResponse(err)` identifies the no-response
+ * case so a caller can stay silent instead of reporting an outage. **Do not write
+ * `err instanceof HttpError && err.status < 500` as a sign-out check** — it clears
+ * the session on every aborted navigation request.
+ *
  * @module
  */
 export * from './auth-gate.js';
 export * from './client.js';
+export * from './errors.js';
 export * from './interceptors.js';
 export * from './provider.js';
+export * from './retry.js';
 export * from './types.js';
 export * from './unwrap.js';
 export * from './utilities.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -88,12 +88,25 @@
  * settles, and every request the gate holds stalls until it times out (3 s).
  * `@molecule/app-auth`'s own restore does not need it (it calls `fetch`, not this client).
  *
+ * **A failed request's `status` is `0` when NO response arrived — never read it as
+ * "signed out".** An aborted request (an `AbortController` signal, a component's
+ * effect cleanup, a route change tearing the fetch down) and a network outage both
+ * throw an `HttpError` with `status === 0`; the aborted ones also carry
+ * `aborted: true` and the `http.error.aborted` key, the rest `http.error.networkError`.
+ * Neither says anything about the session. To decide whether a session ended, use
+ * `isAuthFailure(err)` (401/403 only); `isNoResponse(err)` identifies the no-response
+ * case so a caller can stay silent instead of reporting an outage. **Do not write
+ * `err instanceof HttpError && err.status < 500` as a sign-out check** — it clears
+ * the session on every aborted navigation request.
+ *
  * @module
  */
 export * from './auth-gate.js';
 export * from './client.js';
+export * from './errors.js';
 export * from './interceptors.js';
 export * from './provider.js';
+export * from './retry.js';
 export * from './types.js';
 export * from './unwrap.js';
 export * from './utilities.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAQ/D;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAQ,gBAAqB,KAAG,UAwXjE,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAc/D;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAQ,gBAAqB,KAAG,UA8ajE,CAAA"}