@calimero-network/mero-js 21.2.2 → 21.4.0

package/README.md

@@ -85,6 +85,13 @@ Every failure surfaces as a typed error:
 - **`RpcError`** — the WASM contract returned a JSON-RPC error (`code`, `message`,
   optional `type`/`data`).
 
+`classifyError(err)` turns any of these into `{ kind, retryable, message }`.
+`kind` is read off the status (`'conflict'` for a 409, `'unavailable'` for a
+503, `'unreachable'` for status 0, and so on). `retryable` says whether the same
+request could work later. `message` is the node's own words. To follow an
+invitation, use `sdk.admin.redeemInvitation`: a join that failed but landed
+comes back as `already-member` rather than as an error.
+
 `401`s are handled internally: the SDK refreshes the token and retries once, so
 you only see a `401` if the refresh itself fails. Full details in the
 [error model reference](https://calimero-network.github.io/mero-js/reference/error-model/).

package/dist/admin-api/admin-client.d.ts

@@ -1,5 +1,6 @@
 import { HttpClient } from '../http-client/index.js';
 import type { HealthStatus, ReadinessStatus, AdminAuthStatus, InstallApplicationRequest, InstallApplicationResponseData, InstallDevApplicationRequest, UninstallApplicationResponseData, ListApplicationsResponseData, GetApplicationResponseData, ApplicationVersionEntry, GetApplicationAbiResponseData, GetLatestVersionResponseData, ListPackagesResponseData, ListVersionsResponseData, CreateContextRequest, CreateContextResponseData, DeleteContextResponseData, GetContextsResponseData, Context, GenerateContextIdentityResponseData, GetContextIdentitiesResponseData, JoinContextResponseData, JoinSubgroupInheritanceResponseData, ContextGroupResponseData, ContextStorageResponseData, InviteSpecializedNodeRequest, InviteSpecializedNodeResponseData, UpdateContextApplicationRequest, ResyncContextRequest, ResyncContextResponseData, ContextsWithExecutorsResponseData, UploadBlobRequest, UploadBlobResponseData, DeleteBlobResponseData, ListBlobsResponseData, GetBlobInfoResponseData, BlobReadOptions, CreateContextAliasRequest, CreateApplicationAliasRequest, CreateDeviceAliasRequest, CreateAliasResponseData, LookupAliasResponseData, DeleteAliasResponseData, ListAliasesResponseData, ListNamespacesResponseData, CreateNamespaceRequest, CreateNamespaceResponseData, DeleteNamespaceResponseData, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, JoinNamespaceRequest, JoinNamespaceResponseData, CreateGroupInNamespaceRequest, CreateGroupInNamespaceResponseData, SubgroupEntry, Namespace, NamespaceIdentity, NodeIdentity, AccountPairInitRequest, AccountPairInitResponseData, AccountPairCompleteRequest, AccountPairCompleteResponseData, AccountSignWithRootRequest, AccountSignWithRootResponseData, RelinkDeviceRequest, RelinkDeviceResponseData, RescopeDeviceRequest, RescopeDeviceResponseData, LabelDeviceRequest, LabelDeviceResponseData, AccountDeviceEntry, AccountApplicationEntry, RevokeAccountDeviceRequest, RevokeAccountDeviceResponseData, GroupInfoResponseData, CreateGroupRequest, CreateGroupResponseData, DeleteGroupResponseData, ListGroupMembersResponseData, ListGroupContextsResponseData, AddGroupMembersRequest, RemoveGroupMembersRequest, UpdateMemberRoleRequest, MemberCapabilities, SetMemberCapabilitiesRequest, SetDefaultCapabilitiesRequest, SetMemberAutoFollowRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, GetTeeAdmissionPolicyResponseData, SetTeeAuthoringPolicyRequest, SetGroupMetadataRequest, SetMemberMetadataRequest, SetContextMetadataRequest, MetadataRecord, SyncGroupResponseData, UpgradeGroupRequest, UpgradeGroupResponseData, GroupUpgradeStatusResponseData, MigrationStatus, CascadeStatusEntry, RetryGroupUpgradeResponseData, ReparentGroupRequest, ReparentGroupResponseData, IssueOwnershipProofRequest, IssueNamespaceOwnershipProofRequest, IssueOwnershipProofResponseData, CreateGroupInvitationRequest, CreateGroupInvitationResponseData, CreateRecursiveGroupInvitationResponseData, JoinGroupRequest, JoinGroupResponseData, TeeInfoResponseData, TeeAttestRequest, TeeAttestResponseData, TeeVerifyQuoteRequest, TeeVerifyQuoteResponseData, PerformIntentRequest, PerformIntentResponseData, IntentRelayInfo, QueryContextRequest, QueryContextResponseData, ListMemberDevicesOptions, ListMemberDevicesResponseData, SealToAccountRequest, SealedEnvelope, AdmitJoinRequest, AdmitJoinResponseData } from './admin-types.js';
+import { type RedeemOutcome } from './redeem-invitation.js';
 /**
  * Compare two version strings by SemVer 2.0 precedence, ascending: negative if
  * `a < b`, positive if `a > b`, `0` if equal. Build metadata (`+...`) is stripped
@@ -237,6 +238,29 @@ export declare class AdminApiClient {
      */
     admitJoin(namespaceId: string, request: AdmitJoinRequest): Promise<AdmitJoinResponseData>;
     joinNamespace(namespaceId: string, request: JoinNamespaceRequest): Promise<JoinNamespaceResponseData>;
+    /**
+     * Join the namespace an invitation grants, and say what happened — including
+     * when the request failed but the join landed anyway.
+     *
+     * Use this rather than {@link joinNamespace} whenever someone is following an
+     * invitation. A join waits for a member to come online and can outlast any
+     * proxy in front of the node; the request then fails while the join
+     * succeeds. This sends the join once, then checks {@link listNamespaces}:
+     * a failed request whose namespace is listed is `already-member`, a success.
+     *
+     * Never throws for an ordinary failure. A failed outcome carries a `reason`
+     * read off the node's status (core rc.56+), and `retryable`, which says
+     * whether to keep the invitation for another attempt.
+     *
+     * @param namespaceId the namespace the invitation names, 64 hex
+     * @param invitation the signed invitation, as the inviter's node minted it
+     * @param options `groupName` is sent with the join; `teamName` is echoed back
+     *   on a successful outcome for the caller's UI
+     */
+    redeemInvitation(namespaceId: string, invitation: JoinNamespaceRequest['invitation'], options?: {
+        groupName?: string;
+        teamName?: string;
+    }): Promise<RedeemOutcome>;
     createGroupInNamespace(namespaceId: string, request?: CreateGroupInNamespaceRequest): Promise<CreateGroupInNamespaceResponseData>;
     listNamespaceGroups(namespaceId: string): Promise<SubgroupEntry[]>;
     /**

package/dist/admin-api/admin-client.js

@@ -1,5 +1,6 @@
 import { withRetry } from '../http-client/index.js';
 import { CAPABILITIES, hasCap, withCap } from '../capabilities.js';
+import { redeemInvitation } from './redeem-invitation.js';
 /**
  * Helper: server wraps most responses in `{ data: T }`.
  * This extracts `.data` so callers get the inner payload directly. Null-safe so an
@@ -545,6 +546,34 @@ export class AdminApiClient {
         }
         return data;
     }
+    /**
+     * Join the namespace an invitation grants, and say what happened — including
+     * when the request failed but the join landed anyway.
+     *
+     * Use this rather than {@link joinNamespace} whenever someone is following an
+     * invitation. A join waits for a member to come online and can outlast any
+     * proxy in front of the node; the request then fails while the join
+     * succeeds. This sends the join once, then checks {@link listNamespaces}:
+     * a failed request whose namespace is listed is `already-member`, a success.
+     *
+     * Never throws for an ordinary failure. A failed outcome carries a `reason`
+     * read off the node's status (core rc.56+), and `retryable`, which says
+     * whether to keep the invitation for another attempt.
+     *
+     * @param namespaceId the namespace the invitation names, 64 hex
+     * @param invitation the signed invitation, as the inviter's node minted it
+     * @param options `groupName` is sent with the join; `teamName` is echoed back
+     *   on a successful outcome for the caller's UI
+     */
+    async redeemInvitation(namespaceId, invitation, options = {}) {
+        const { groupName, teamName } = options;
+        return redeemInvitation({ namespaceId, invitation, teamName }, {
+            join: async () => {
+                await this.joinNamespace(namespaceId, groupName === undefined ? { invitation } : { invitation, groupName });
+            },
+            memberships: async () => ((await this.listNamespaces()) ?? []).map((n) => n.namespaceId),
+        });
+    }
     async createGroupInNamespace(namespaceId, request) {
         return unwrap(await this.httpClient.post(`/admin-api/namespaces/${namespaceId}/groups`, request ?? {}));
     }

package/dist/admin-api/admin-types.d.ts

@@ -370,32 +370,11 @@ export interface Namespace {
      */
     appVersion?: string;
     /**
-     * What the namespace id was derived from, on nodes that hold it: every
-     * replica of a namespace founded with a derived id. Absent for namespaces
-     * created before ids were derived, and on nodes that predate it.
+     * What the namespace id was derived from, on nodes that hold it. Every
+     * namespace's id is derived from its founder since core's schema v10, so
+     * this is absent only on nodes that predate it.
      */
     founding?: NamespaceFounding;
-    /**
-     * The founder and genesis op of a namespace created BEFORE ids were derived,
-     * on this node's copy. A separate field from `founding`, never inside it: it
-     * proves nothing about the id, so it must not be accepted where a derived-id
-     * founding is checked. Absent for derived namespaces, and on nodes that
-     * predate it.
-     */
-    legacyFounding?: NamespaceLegacyFounding;
-}
-/**
- * The founder a pre-derivation namespace's plain genesis names, and the hash
- * of that genesis op (its id in the namespace governance DAG). Lets a client
- * see which founder and which exact genesis a replica's copy was founded by,
- * and compare replicas — not a proof of founding: a random id commits to no
- * founder.
- */
-export interface NamespaceLegacyFounding {
-    /** Hex `AccountId` of the founder the genesis names. */
-    founderAccountId: string;
-    /** Lowercase hex 32-byte content hash of the genesis op. */
-    genesisOpHash: string;
 }
 /**
  * The founder and salt a namespace id was derived from:

package/dist/admin-api/index.d.ts

@@ -1,3 +1,4 @@
 export * from './admin-client.js';
 export * from './admin-types.js';
 export * from './admin-factory.js';
+export * from './redeem-invitation.js';

package/dist/admin-api/index.js

@@ -2,3 +2,4 @@
 export * from './admin-client.js';
 export * from './admin-types.js';
 export * from './admin-factory.js';
+export * from './redeem-invitation.js';

package/dist/admin-api/redeem-invitation.d.ts

@@ -0,0 +1,94 @@
+/** The two calls a redeem needs, so any client (or any app's join) can drive it. */
+export interface InviteRedeemer {
+    /**
+     * Send the join. Resolve on success, throw on failure.
+     *
+     * It does not have to be reliable, and it does not have to be idempotent on
+     * the client — the node's join is idempotent, and `memberships()` settles any
+     * ambiguity this throws.
+     */
+    join(namespaceId: string, invitation: unknown): Promise<void>;
+    /**
+     * Namespace ids this node is a member of.
+     *
+     * Throwing is a legitimate answer ("could not tell") and is treated as such:
+     * it never turns a join that succeeded into a failure.
+     */
+    memberships(): Promise<readonly string[]>;
+}
+/**
+ * Why a join failed, as far as it tells a person what to do next.
+ *
+ * Read off the HTTP status where the node gives one (core rc.56+ answers a
+ * refused join with a 4xx, not a 500), and off the message otherwise.
+ */
+export type InviteFailureReason = 
+/** The invitation's time ran out. Only a new link helps. */
+'expired'
+/** The link is malformed or names nothing joinable. Only a new link helps. */
+ | 'invalid'
+/** The node refused this person (removed, blocked, not allowed). */
+ | 'refused'
+/** This client's session with the node lapsed; signing in finishes it. */
+ | 'signed-out'
+/** No member was reachable to let them in yet. Trying later can work. */
+ | 'no-one-online'
+/** This client could not reach its own node at all. */
+ | 'node-unreachable'
+/** Nothing more specific is known; the node's message is all there is. */
+ | 'unknown';
+/**
+ * What happened, in the terms a UI needs.
+ *
+ * `already-member` is deliberately a success and deliberately distinct: it is
+ * the outcome of following a link twice, or of the timeout above, and telling
+ * someone "you are already in this one" is neither an error nor the same
+ * message as having just joined.
+ */
+export type RedeemOutcome = {
+    status: 'joined';
+    namespaceId: string;
+    teamName?: string;
+} | {
+    status: 'already-member';
+    namespaceId: string;
+    teamName?: string;
+} | {
+    status: 'failed';
+    namespaceId: string | null;
+    /** The node's own words, for logs and for a UI that shows detail. */
+    message: string;
+    /** Why, in terms a person can act on. */
+    reason: InviteFailureReason;
+    /**
+     * Whether trying again later could plausibly work. A malformed token
+     * cannot; an unreachable peer can. A caller holding the invitation uses
+     * this to decide whether to keep it — see {@link shouldRetain}.
+     */
+    retryable: boolean;
+};
+/** Whether an outcome means the invitation is finished with. */
+export declare function isSettled(outcome: RedeemOutcome): boolean;
+/**
+ * Whether the invitation should be kept for another attempt later.
+ *
+ * The inverse of {@link isSettled}, named for the decision it drives.
+ */
+export declare function shouldRetain(outcome: RedeemOutcome): boolean;
+/**
+ * Join the namespace an invitation names, and report what happened.
+ *
+ * Sends the join once and never retries it: a failed request whose namespace
+ * is then listed is `already-member`, not a failure. Never throws for an
+ * ordinary failure — the outcome carries it, because every caller has to branch
+ * on "already a member" anyway.
+ *
+ * Most callers want {@link AdminApiClient.redeemInvitation}, which supplies the
+ * redeemer from the admin API. This form is for a join that is more than one
+ * call — a namespace followed by the context inside it, say.
+ */
+export declare function redeemInvitation(parsed: {
+    namespaceId: string;
+    invitation: unknown;
+    teamName?: string;
+}, redeemer: InviteRedeemer): Promise<RedeemOutcome>;

package/dist/admin-api/redeem-invitation.js

@@ -0,0 +1,131 @@
+// ── Redeeming an invitation: joining once, and knowing whether it worked ──────
+//
+// Deciding "did we join?" by whether the join request resolved is the wrong
+// question, and on a real node (core rc.41, 2026-09-22) it failed two ways:
+//
+//   1. The desktop proxy aborts every admin request at 30s. A namespace join
+//      whose members are all offline waits for one to appear — measured at 95s.
+//      So the request failed, the join landed anyway, and the app reported
+//      "could not join" for a namespace it was already in. It kept the
+//      invitation, and replayed it on every load.
+//
+//   2. A refresh after the join shared its `try`, so a refresh that threw
+//      turned a real join into a reported failure.
+//
+// So membership is the question, and there are two independent proofs of it:
+// the request resolving, and the namespace being listed. Either one is enough,
+// which matters because either one can be missing.
+import { classifyError, messageOf } from '../errors/classify.js';
+/** Whether an outcome means the invitation is finished with. */
+export function isSettled(outcome) {
+    return outcome.status !== 'failed' || !outcome.retryable;
+}
+/**
+ * Whether the invitation should be kept for another attempt later.
+ *
+ * The inverse of {@link isSettled}, named for the decision it drives.
+ */
+export function shouldRetain(outcome) {
+    return !isSettled(outcome);
+}
+/**
+ * Which reason the message alone names, for a node that answers without a
+ * useful status — older than rc.56, where every refusal was a bare 500.
+ *
+ * Kept narrow on purpose. Anything not recognised here stays retryable, because
+ * the cost of retrying a dead link is one more attempt, while the cost of
+ * discarding a live one is someone who cannot join at all.
+ */
+function reasonFromMessage(message) {
+    const m = message.toLowerCase();
+    if (m.includes('invitation has expired') ||
+        m.includes('invitation expired') ||
+        // Core rc.56+ names the group between the words: "invitation for group
+        // <id> expired at <secs>".
+        /\binvitation for group .+? expired at \d+/.test(m)) {
+        return 'expired';
+    }
+    if (m.includes('malformed') ||
+        m.includes('does not match namespace_id') ||
+        m.includes('invalid invitation') ||
+        /\binvitation for group .+? is invalid:/.test(m)) {
+        return 'invalid';
+    }
+    return null;
+}
+/**
+ * Why a join failed, and whether a later attempt could work.
+ *
+ * The status decides where there is one. A 4xx the node chose is a definitive
+ * answer about this invitation or this person, so it is not retried; a 5xx or
+ * no answer at all is about the moment, so it is. Two exceptions keep an
+ * invitation that is still good: a 401 is the client's session, not the
+ * invitation, and a 404 is not specific enough to throw a link away on.
+ */
+function classifyJoinFailure(err, message) {
+    const { kind, status } = classifyError(err);
+    const fromText = reasonFromMessage(message);
+    if (status === 401)
+        return { reason: 'signed-out', retryable: true };
+    if (status === 400)
+        return { reason: fromText ?? 'invalid', retryable: false };
+    if (status === 410)
+        return { reason: 'expired', retryable: false };
+    if (status === 403)
+        return { reason: 'refused', retryable: false };
+    // An expired invitation, a spent one, a member who was removed or blocked:
+    // every 409 a join can answer is final.
+    if (status === 409)
+        return { reason: fromText ?? 'refused', retryable: false };
+    if (kind === 'unavailable')
+        return { reason: 'no-one-online', retryable: true };
+    if (kind === 'unreachable')
+        return { reason: 'node-unreachable', retryable: true };
+    // A 500 from a node older than rc.56 may still be a refusal in disguise;
+    // anything else has only its message to go on.
+    if (fromText)
+        return { reason: fromText, retryable: false };
+    return { reason: 'unknown', retryable: true };
+}
+/**
+ * Join the namespace an invitation names, and report what happened.
+ *
+ * Sends the join once and never retries it: a failed request whose namespace
+ * is then listed is `already-member`, not a failure. Never throws for an
+ * ordinary failure — the outcome carries it, because every caller has to branch
+ * on "already a member" anyway.
+ *
+ * Most callers want {@link AdminApiClient.redeemInvitation}, which supplies the
+ * redeemer from the admin API. This form is for a join that is more than one
+ * call — a namespace followed by the context inside it, say.
+ */
+export async function redeemInvitation(parsed, redeemer) {
+    const { namespaceId, invitation, teamName } = parsed;
+    let joinError = null;
+    try {
+        await redeemer.join(namespaceId, invitation);
+    }
+    catch (err) {
+        joinError = err;
+    }
+    // The request resolving is proof on its own, so this must not be able to
+    // demote a real join: a `memberships()` that throws is "could not tell".
+    let listed = null;
+    try {
+        listed = (await redeemer.memberships()).includes(namespaceId);
+    }
+    catch {
+        listed = null;
+    }
+    if (joinError === null) {
+        return { status: 'joined', namespaceId, teamName };
+    }
+    if (listed === true) {
+        // The join landed despite the error — an aborted request, or a link
+        // followed twice.
+        return { status: 'already-member', namespaceId, teamName };
+    }
+    const message = messageOf(joinError, 'Could not join. Check the invitation.');
+    const { reason, retryable } = classifyJoinFailure(joinError, message);
+    return { status: 'failed', namespaceId, message, reason, retryable };
+}

package/dist/errors/classify.d.ts

@@ -0,0 +1,65 @@
+/** The kind of failure, as far as it decides what the caller does next. */
+export type ErrorKind = 
+/** 400. The request is wrong; sending it again cannot help. */
+'invalid'
+/** 401. This client's session lapsed; signing in again can finish it. */
+ | 'unauthorized'
+/** 403. The node will not do this for this caller. */
+ | 'forbidden'
+/** 404. What the request names does not exist on this node (yet). */
+ | 'not-found'
+/** 409. The request contradicts the current state: expired, spent, removed. */
+ | 'conflict'
+/** 410. It existed and is gone for good. */
+ | 'gone'
+/** 413. The body is over the node's limit. */
+ | 'too-large'
+/** 429. The node asked the caller to slow down. */
+ | 'rate-limited'
+/** 503 or 504. The node cannot serve this yet — no peer online, say. */
+ | 'unavailable'
+/** Any other 5xx. The node failed; the request may well have been fine. */
+ | 'server'
+/** Status 0. The request never reached the node: offline, CORS, a timeout. */
+ | 'unreachable'
+/** Not an HTTP failure, or one with nothing more specific to go on. */
+ | 'unknown';
+export interface ClassifiedError {
+    kind: ErrorKind;
+    /** The HTTP status, when the error carries one. 0 means no response. */
+    status: number | undefined;
+    /**
+     * Whether the same request could succeed later without anything changing on
+     * the caller's side. False for a refusal the node chose — asking again gets
+     * the same answer — and true for a failure about the moment.
+     */
+    retryable: boolean;
+    /**
+     * The node's own explanation, without an `HTTP <status>` prefix, falling back
+     * to the error's message. For logs and for a UI that shows detail; a UI that
+     * wants friendly copy should switch on `kind`.
+     */
+    message: string;
+}
+/**
+ * The HTTP status an error carries, in any shape a client throws: mero-js's
+ * `HTTPError.status`, an axios-style `response.status`, or a bare `statusCode`.
+ * Undefined when there is none — a thrown string, or an error raised before the
+ * request was sent.
+ */
+export declare function statusOf(err: unknown): number | undefined;
+/**
+ * The most specific human-readable explanation an error carries, or
+ * `fallback`. Prefers the node's words (`HTTPError.explanation`, or an axios
+ * body's `error`/`message`) over a message that repeats the status line.
+ */
+export declare function messageOf(err: unknown, fallback?: string): string;
+/**
+ * What a failed request means: its kind, whether a later attempt could work,
+ * and the node's own words for it.
+ *
+ * Accepts anything a `catch` hands over. A browser `fetch` that could not
+ * connect throws a `TypeError`, which is read as `unreachable` like mero-js's
+ * own status-0 `HTTPError`.
+ */
+export declare function classifyError(err: unknown): ClassifiedError;

package/dist/errors/classify.js

@@ -0,0 +1,121 @@
+// ── What a failed request means, in terms a caller can act on ────────────────
+//
+// Core rc.56 onwards (calimero-network/core#4151 to #4164) answers a refused
+// admin request with the status that names the refusal: a malformed body is a
+// 400, a caller the node will not serve a 403, a missing resource a 404, a
+// state the request contradicts (an expired invitation, a removed member) a
+// 409, an oversized upload a 413, and a request the node cannot serve *yet*
+// (no member online to hand over a group key) a 503. Before that, every one of
+// them was a bare 500 and the only way to tell them apart was to match text.
+//
+// Every caller asks the same two questions of such an error: what kind of
+// failure is this, and would doing it again later help? This answers both once,
+// so apps stop keeping their own copies of the status table.
+const RETRYABLE = {
+    invalid: false,
+    // The session, not the request: signing in again and repeating it works.
+    unauthorized: true,
+    forbidden: false,
+    // Too broad to give up on — the resource may simply not have synced yet.
+    'not-found': true,
+    conflict: false,
+    gone: false,
+    'too-large': false,
+    'rate-limited': true,
+    unavailable: true,
+    server: true,
+    unreachable: true,
+    unknown: true,
+};
+function kindForStatus(status) {
+    switch (status) {
+        case 0:
+            return 'unreachable';
+        case 400:
+            return 'invalid';
+        case 401:
+            return 'unauthorized';
+        case 403:
+            return 'forbidden';
+        case 404:
+            return 'not-found';
+        case 409:
+            return 'conflict';
+        case 410:
+            return 'gone';
+        case 413:
+            return 'too-large';
+        case 429:
+            return 'rate-limited';
+        case 503:
+        case 504:
+            return 'unavailable';
+    }
+    if (status >= 500 && status < 600)
+        return 'server';
+    if (status >= 400 && status < 500)
+        return 'invalid';
+    return 'unknown';
+}
+/**
+ * The HTTP status an error carries, in any shape a client throws: mero-js's
+ * `HTTPError.status`, an axios-style `response.status`, or a bare `statusCode`.
+ * Undefined when there is none — a thrown string, or an error raised before the
+ * request was sent.
+ */
+export function statusOf(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const shaped = err;
+    for (const candidate of [shaped.status, shaped.response?.status, shaped.statusCode]) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * The most specific human-readable explanation an error carries, or
+ * `fallback`. Prefers the node's words (`HTTPError.explanation`, or an axios
+ * body's `error`/`message`) over a message that repeats the status line.
+ */
+export function messageOf(err, fallback = 'Request failed') {
+    if (typeof err === 'string')
+        return err.trim() || fallback;
+    if (!err || typeof err !== 'object')
+        return fallback;
+    const shaped = err;
+    for (const candidate of [
+        shaped.explanation,
+        shaped.response?.data?.error,
+        shaped.response?.data?.message,
+        shaped.data?.message,
+        shaped.error,
+        shaped.message,
+    ]) {
+        if (typeof candidate === 'string' && candidate.trim())
+            return candidate;
+    }
+    return fallback;
+}
+/**
+ * What a failed request means: its kind, whether a later attempt could work,
+ * and the node's own words for it.
+ *
+ * Accepts anything a `catch` hands over. A browser `fetch` that could not
+ * connect throws a `TypeError`, which is read as `unreachable` like mero-js's
+ * own status-0 `HTTPError`.
+ */
+export function classifyError(err) {
+    const status = statusOf(err);
+    let kind;
+    if (status !== undefined) {
+        kind = kindForStatus(status);
+    }
+    else if (err instanceof TypeError) {
+        kind = 'unreachable';
+    }
+    else {
+        kind = 'unknown';
+    }
+    return { kind, status, retryable: RETRYABLE[kind], message: messageOf(err) };
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,2 @@
+export { classifyError } from './classify.js';
+export type { ClassifiedError, ErrorKind } from './classify.js';

package/dist/errors/index.js

@@ -0,0 +1 @@
+export { classifyError } from './classify.js';

package/dist/http-client/web-client.d.ts

@@ -6,6 +6,12 @@ export declare class HTTPError extends Error {
     headers: Headers;
     bodyText?: string;
     name: string;
+    /**
+     * The node's own words for the failure, without the `HTTP <status>` prefix
+     * `message` carries: the body's `error` (or `detail`) for a response, the
+     * thrown error's text for status 0. Undefined when there was none.
+     */
+    readonly explanation: string | undefined;
     constructor(status: number, statusText: string, url: string, headers: Headers, bodyText?: string);
     toJSON(): {
         status: number;

package/dist/http-client/web-client.js

@@ -56,6 +56,7 @@ export class HTTPError extends Error {
         this.headers = headers;
         this.bodyText = bodyText;
         this.name = 'HTTPError';
+        this.explanation = explanation;
     }
     toJSON() {
         return {