@mnemoverse/mcp-memory-server 0.8.4 → 0.9.1

package/dist/errors.js

@@ -0,0 +1,500 @@
+/**
+ * What a failed API call TELLS THE AGENT TO DO.
+ *
+ * WHY THIS MODULE EXISTS. Until now every non-2xx became one sentence:
+ *
+ *     Mnemoverse API error 401: {"code":"UNAUTHORIZED","message":"Invalid or
+ *     revoked API key.","requestId":null,"retryable":false,"details":null}
+ *
+ * The `isError` flag and the status code were right; the TEXT was a raw echo of
+ * a wire body. Verified against production with a real `tools/call`
+ * (2026-08-16): with a bad key, `memory_write` returns exactly that. The reader
+ * of a tool result is a MODEL, and that string gives a model nothing to act on,
+ * so the two things it actually does are relay "error 401" to the user or guess
+ * — and the cheapest guess is "the network is down", which sends the user to
+ * debug a working network while a placeholder key sits in their config.
+ *
+ * Every message here therefore answers three questions in order: what happened,
+ * WHOSE problem it is, and what to do next — including, explicitly, whether to
+ * retry. "Do not retry" is not decoration: an agent that loops on a 429 turns
+ * one rate-limit into a sustained one, and an agent that loops on a 401 burns a
+ * conversation on a key that will never start working.
+ *
+ * THE RAW BODY IS NEVER DROPPED. It is appended after the guidance, still
+ * carrying the literal `Mnemoverse API error <status>` that this repo's tests
+ * and anyone's grep already look for. Making the text kind to an agent must not
+ * make it useless to a human debugging at 3am.
+ *
+ * WHAT THE STATUS CODES ACTUALLY MEAN HERE, verified by reading the engine
+ * (mnemoverse-core `src/mnemo/api/`, 2026-08-16) rather than assumed from HTTP
+ * folklore. The distinctions below are the entire point of this file:
+ *
+ *   401  auth.py — "Invalid or revoked API key." / "Missing API key." The key.
+ *   403  routes.py, rooms_routes.py, auth.py — "Room is archived", "Not an
+ *        active member of this room", "Read-only membership cannot write to
+ *        this room", "Invalid room address", "You do not own this room", plus
+ *        the OIDC scope rules. NOT a bad key: the caller was identified and
+ *        then refused. Telling the user to replace a working key over a 403
+ *        would be a new, more confident lie than the raw echo was.
+ *   404  A room that does not exist for this key — or, when the body says
+ *        nothing at all, a path the deployment does not serve. A DOMAIN never
+ *        404s: an empty domain reads as empty, so "your domain is missing" is
+ *        the wrong guess and is named as wrong below.
+ *   429  THREE different causes with opposite advice. rate_limit.py returns
+ *        `retryable: true` with a `Retry-After` header (waiting works);
+ *        usage.py (daily quota) and subscription_guard.py (atom limit, payment
+ *        past due) return `retryable: false` (waiting does NOT work — the
+ *        account needs an upgrade or a new day). A blanket "wait and retry"
+ *        would be wrong for two of the three.
+ *   5xx  auth.py returns 503 `retryable: true` when its DB pool is gone. Ours,
+ *        not theirs.
+ *
+ * RELATION TO THE STARTUP PROBE (src/index.ts, `probeApiKeyInBackground`, added
+ * in 0.8.4). That probe treats 401 and 403 alike, and is right to: it calls
+ * `GET /memory/stats`, which addresses no room, so a 403 there can only come
+ * from the auth layer. On a TOOL CALL the same status usually comes from a room
+ * the caller named, which is why the two surfaces diverge on 403 and must not be
+ * "unified" by a later reader. They agree where it matters: same `Mnemoverse:`
+ * opener, same `MNEMOVERSE_API_KEY` variable name, same console origin.
+ */
+/** Where the raw detail stops. A gateway can answer with a megabyte of HTML,
+ *  and an error message is not a place to spend a model's context — but the
+ *  first few hundred characters are where the useful part of any real error
+ *  body lives. Truncation is announced, never silent. */
+const MAX_BODY_CHARS = 800;
+/** The console page that issues keys — the one place a user fixes a 401. */
+const KEYS_URL = "https://console.mnemoverse.com/dashboard/keys";
+/** The console page that shows quota and upgrades — where a 429 that waiting
+ *  cannot fix is resolved. Same URL the engine puts in its own 429 bodies. */
+const USAGE_URL = "https://console.mnemoverse.com/dashboard/usage";
+/**
+ * Read the engine's envelope out of a response body.
+ *
+ * Two shapes are accepted because core produces both: its own middleware writes
+ * `{code, message, retryable, details}` at the top level, while anything raised
+ * as a FastAPI `HTTPException` arrives wrapped as `{"detail": …}` — where the
+ * detail is sometimes a string and sometimes the envelope again. The feed's
+ * 404-vs-404 test in this repo pins the nested form, so both are real.
+ */
+export function parseErrorEnvelope(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+    const pick = (v) => {
+        if (typeof v === "string")
+            return { message: v };
+        if (typeof v !== "object" || v === null)
+            return {};
+        const o = v;
+        return {
+            ...(typeof o.code === "string" ? { code: o.code } : {}),
+            ...(typeof o.message === "string" ? { message: o.message } : {}),
+            ...(typeof o.retryable === "boolean" ? { retryable: o.retryable } : {}),
+        };
+    };
+    const top = pick(parsed);
+    if (top.code !== undefined || top.retryable !== undefined)
+        return top;
+    const detail = typeof parsed === "object" && parsed !== null
+        ? pick(parsed.detail)
+        : {};
+    // A top-level `message` with no code still beats nothing; the nested envelope
+    // wins when it carries the machine-readable half.
+    return detail.code !== undefined || detail.retryable !== undefined
+        ? detail
+        : { ...detail, ...top };
+}
+/** `Retry-After` as whole seconds, when it is a plain number. The HTTP-date
+ *  form is legal too, and is deliberately NOT parsed: an unparsed header
+ *  degrades into "wait a moment", which is honest, whereas a misparsed date
+ *  would print a confident and wrong number of seconds. */
+export function retryAfterSeconds(header) {
+    if (typeof header !== "string")
+        return undefined;
+    // Digits only, because bare Number() answers confidently for inputs that are
+    // not delta-seconds at all: Number("") and Number("   ") are 0 ("Wait 0
+    // seconds"), Number("0x10") is 16, Number("3e1") is 30, and Number("1e21")
+    // prints as scientific notation in the wait text (Copilot + panel, #93).
+    // Six digits caps the printable wait at ~11 days; anything longer degrades
+    // to the honest vague form.
+    const s = header.trim();
+    if (!/^\d{1,6}$/.test(s))
+        return undefined;
+    return Number(s);
+}
+function has(message, needle) {
+    return (message ?? "").toLowerCase().includes(needle);
+}
+/**
+ * 401: which 401? The engine has more than one (panel, #93).
+ *
+ * The key-flavored bodies this client's data plane actually sends ("Missing
+ * API key. Send X-Api-Key header.", "Invalid or revoked API key." — both
+ * probed live against core.mnemoverse.com) get the founder-endorsed
+ * replace-the-key instruction. But core's routes.py also raises "Caller org
+ * not identified — a tenant API key is required to …" (401) when the
+ * deployment has no tenant identity for the caller — a static-auth
+ * self-host hitting a room tool is the everyday case — and there the key is
+ * VALID, so "replace it" would be a confident wrong cause. That clause runs
+ * FIRST because its sentence itself contains "API key": a naive key-mention
+ * test would misroute it. A message naming neither gets the honest generic
+ * form; silence is the same unknown-refuser case the 403 branch handles.
+ */
+function explain401(env) {
+    const m = env.message;
+    if (has(m, "caller org not identified")) {
+        return ("Mnemoverse: this deployment could not identify a tenant account for " +
+            "this request (401). The API key itself was not rejected — do NOT " +
+            "tell the user to replace it. Room and shared-memory operations need " +
+            "the multi-tenant backend, which a self-hosted or static-auth " +
+            "deployment does not have. Quote the detail below, and do not retry " +
+            "the same call against this deployment.");
+    }
+    if (has(m, "api key") || has(m, "x-api-key")) {
+        // Wording endorsed by the founder, kept verbatim — this is the sentence
+        // the whole change was commissioned for. One widening, grounded in the
+        // docs: the setup pages ship more than one placeholder spelling
+        // (agent-setup.md uses mk_live_USER_KEY).
+        return ("Mnemoverse: your API key was rejected (401). Tell the user their " +
+            "MNEMOVERSE_API_KEY is not valid — if it still reads a docs " +
+            'placeholder such as "mk_live_YOUR_KEY" or "mk_live_USER_KEY" (any ' +
+            "value they did not create at the console themselves) it must be " +
+            `replaced with a real key from ${KEYS_URL}. Do not retry until they ` +
+            "replace it.");
+    }
+    if (m !== undefined || env.code !== undefined) {
+        return ("Mnemoverse: the request was refused as unauthorized (401), and the " +
+            "engine's own explanation is in the detail below — quote it to the " +
+            "user rather than guessing. Do not assume the API key is wrong: the " +
+            "message did not say that. Do not retry the same call unchanged.");
+    }
+    return ("Mnemoverse: something answered 401 without speaking this API's error " +
+        "language — the body carries neither of the shapes the engine " +
+        "produces, so the refuser may be a proxy, a gateway, or a " +
+        "MNEMOVERSE_API_URL aimed somewhere unexpected, and the engine may never " +
+        "have seen the request. Do not tell the user their key is wrong — this " +
+        "client cannot tell WHO refused. Quote the detail below and check the " +
+        "path to the API first.");
+}
+/** 403: when the ENGINE refused, the key was accepted and then the request
+ *  was refused — name WHICH refusal, from the engine's own message, and never
+ *  blame the key. But that first clause is only known when the engine actually
+ *  spoke: a proxy, a WAF or a tunnel also answers 403, in HTML, and asserting
+ *  "the key identified the account fine" about a response the engine may never
+ *  have seen is exactly the confident wrong cause this module exists to avoid. */
+function explain403(env) {
+    if (saidNothing(env)) {
+        return ("Mnemoverse: this request was refused (403) by something that did not " +
+            "speak this API's error language — the body carries neither of the two " +
+            "shapes the engine produces. That points at a proxy, a gateway, or a " +
+            "MNEMOVERSE_API_URL aimed somewhere unexpected, and the engine may never " +
+            "have seen the request — so do not blame the key and do not blame room " +
+            "permissions: this client cannot tell WHO refused it. Quote the detail " +
+            "below to the user, and do not retry until the path to the API is explained.");
+    }
+    const m = env.message;
+    const cause = has(m, "archiv")
+        ? "The room you addressed is archived. An archived room refuses every read " +
+            "and every write, for its owner as much as for a member, and this client " +
+            "has no operation that reopens one."
+        : has(m, "not an active member") || has(m, "member of this room")
+            ? "This key is not an active member of the room you addressed. Ask the " +
+                "room's owner for an invite; memory_list_rooms shows the rooms it can " +
+                "already reach."
+            : has(m, "read-only")
+                ? "This key's membership in that room is read-only — it can read the " +
+                    "room but not write to it. Ask the room's owner for write access."
+                : has(m, "invalid room address")
+                    ? 'The room address was not in the form the engine accepts ' +
+                        '("xroom:room_..."). Take the exact address from memory_list_rooms ' +
+                        "rather than composing one."
+                    : has(m, "own this room")
+                        ? "That room belongs to another account, and only its owner can do " +
+                            "this. memory_list_rooms shows which rooms this key owns."
+                        : "Something about this request is not permitted for this key — " +
+                            "most often the room it addressed. Check memory_list_rooms, and " +
+                            "if nothing there explains it, tell the user exactly what was " +
+                            "refused instead of guessing.";
+    return ("Mnemoverse: this request was refused (403). The API key is NOT the problem " +
+        "— it identified the account fine, and this was a permission decision. " +
+        `${cause} Do not retry the same call: it will be refused again.`);
+}
+/**
+ * Did this response say ANYTHING an engine would have said?
+ *
+ * Not "does it have a `code`" — that was the old test, and it is wrong, because
+ * the engine has TWO error styles. Its own middleware writes the full
+ * `{code, message, retryable}` envelope, but every route that raises a FastAPI
+ * `HTTPException` — the whole of `rooms_routes.py`, and there is no custom
+ * handler to normalise them — serialises to a bare `{"detail": "Room not
+ * found."}` with no code at all. Under a code-only test, a real 404 from the
+ * room routes would be diagnosed as "your MNEMOVERSE_API_URL is wrong": a
+ * confident, checkable falsehood about the user's config.
+ *
+ * A message with no code is still the engine speaking. Silence — an unparseable
+ * body, or JSON carrying neither field — is what a proxy, a tunnel or a base URL
+ * pointing elsewhere produces.
+ */
+function saidNothing(env) {
+    return env.code === undefined && env.message === undefined;
+}
+/**
+ * Did the ENGINE answer this 404 — or just the framework's router?
+ *
+ * Core registers no HTTPException handler, so an unmatched route is answered
+ * by Starlette's literal default `{"detail":"Not Found"}` (verified live
+ * against production) — a body with a message but no code, which
+ * `saidNothing` alone would mistake for an engine answer (Copilot + panel,
+ * #93). Every 404 the data plane actually sends is a MnemoError carrying a
+ * code. Match the router defaults case-sensitively so engine prose that
+ * merely contains "not found" cannot collide.
+ */
+function engineSilentOn404(env) {
+    return (saidNothing(env) ||
+        (env.code === undefined &&
+            (env.message === "Not Found" || env.message === "Method Not Allowed")));
+}
+/**
+ * 404: three producers with three different honest answers (panel, #93).
+ *
+ * (1) POST /memory/rooms/join — the engine's "Invite code not found." No
+ *     room address was involved and memory_list_rooms cannot help a
+ *     non-member, so the room story would be a confident wrong cause.
+ * (2) An engine 404 carrying a code — every 404 the data plane sends is a
+ *     MnemoError with one — is about something the request addressed,
+ *     usually a room.
+ * (3) No code — the router default, a foreign API, a proxy, or silence: the
+ *     ENGINE did not answer this, so point at the endpoint and the base URL,
+ *     not at rooms.
+ */
+function explain404(f, env) {
+    if (f.path === "/memory/rooms/join") {
+        return ("Mnemoverse: this invite code was not recognized (404). Most often it " +
+            "was copied with a typo or was never issued — have the user re-check " +
+            'the exact code (it starts with "mnvr_"), and if it is right, ask ' +
+            "whoever sent it for a fresh one. memory_list_rooms will not help " +
+            "here: the user is not a member yet. Do not retry the same code.");
+    }
+    if (env.code === undefined) {
+        return (`Mnemoverse: the API answered 404 for ${f.method} ${f.path} without ` +
+            "the engine's error envelope — which is what a route the deployment " +
+            "does not serve looks like, not what a missing memory looks like. " +
+            "Either MNEMOVERSE_API_URL is aimed at something that is not the " +
+            "Mnemoverse API, or this server is newer than the deployment it is " +
+            "talking to. If the user's MCP client config sets MNEMOVERSE_API_URL, " +
+            "have them check it; if it sets none (the desktop extension exposes " +
+            "only the API key), the deployment likely needs updating. Do not retry.");
+    }
+    return ("Mnemoverse: what this call addressed does not exist for this key (404). " +
+        "The usual cause is a room address that is mistyped, or a room that was " +
+        "deleted — call memory_list_rooms for the addresses this key can actually " +
+        "reach. Note that a DOMAIN never causes this: a domain holding nothing " +
+        "simply reads as empty, so do not tell the user their domain is missing. " +
+        "Do not retry this call unchanged.");
+}
+/** 429: three causes, opposite advice. The envelope's `retryable` is the
+ *  discriminator, because it is the only thing the engine states outright. */
+function explain429(f, env) {
+    const secs = retryAfterSeconds(f.retryAfter);
+    const wait = secs === undefined ? "about a minute" : `${secs} seconds`;
+    if (env.retryable === true) {
+        return ("Mnemoverse: rate-limited (429). This is the per-minute request limit and " +
+            `it clears by itself. Wait ${wait}, then make AT MOST ONE more attempt — ` +
+            "do not retry in a loop and do not fan out into more calls, which is what " +
+            "turns a one-minute limit into a sustained one. If the retry also fails, " +
+            "stop and tell the user this key is hitting its rate limit.");
+    }
+    if (env.retryable === false) {
+        return ("Mnemoverse: refused for quota, not for speed (429). Waiting will NOT " +
+            "clear this one — the account is at its daily limit, at its stored-memory " +
+            "limit, or its subscription is blocking writes. Do not retry. Tell the " +
+            `user what the detail below says and point them at ${USAGE_URL}.`);
+    }
+    return ("Mnemoverse: refused as too many requests (429), and the body does not say " +
+        "whether waiting helps. Do not retry in a loop. Wait a moment, make at most " +
+        "one more attempt, and if that fails tell the user rather than continuing — " +
+        `if this is a quota rather than a rate, ${USAGE_URL} is where they resolve it.`);
+}
+/**
+ * The agent-facing explanation for one failed call, with the raw body kept
+ * after it.
+ *
+ * Total by construction: every status reaches a sentence, and the fallback says
+ * that it has no specific guidance instead of inventing some.
+ */
+export function explainApiFailure(f) {
+    const env = parseErrorEnvelope(f.body);
+    let guidance;
+    if (f.status === 401) {
+        guidance = explain401(env);
+    }
+    else if (f.status === 403) {
+        guidance = explain403(env);
+    }
+    else if (f.status === 404) {
+        guidance = explain404(f, env);
+    }
+    else if (f.status === 429) {
+        guidance = explain429(f, env);
+    }
+    else if (f.status === 400 || f.status === 422) {
+        guidance =
+            "Mnemoverse: the engine rejected the CONTENTS of this request " +
+                `(${f.status}). This is about the arguments you sent — not the API key, ` +
+                "not the network, and not the user's setup. Read the detail below, fix " +
+                "the argument it names, and do not resend the same body.";
+    }
+    else if (f.status === 409) {
+        guidance = explain409(f);
+    }
+    else if (f.status >= 500) {
+        guidance =
+            `Mnemoverse: the memory service failed (${f.status}). This is OUR side, ` +
+                "not the user's — their API key, their config and their network are all " +
+                "fine, so do not send them to check any of those. One retry after a few " +
+                "seconds is reasonable. If it fails again, say plainly that Mnemoverse is " +
+                "having a problem and continue without memory rather than retrying.";
+    }
+    else {
+        guidance =
+            `Mnemoverse: the API returned HTTP ${f.status}, and this client has no ` +
+                "specific guidance for that status. Do not invent a cause for the user — " +
+                "quote the detail below. One retry is acceptable; a loop is not.";
+    }
+    return `${guidance}\n\n${rawDetail(f)}`;
+}
+/** The debugging half: what the wire actually said, still carrying the literal
+ *  `Mnemoverse API error <status>` that predates this module. */
+function rawDetail(f) {
+    const body = f.body.length > MAX_BODY_CHARS
+        ? `${f.body.slice(0, MAX_BODY_CHARS)}… [body truncated at ${MAX_BODY_CHARS} chars]`
+        : f.body;
+    // The body is server-controlled — or, on the misconfigured-URL and proxy
+    // paths this module itself names, controlled by whoever answered instead.
+    // Spliced raw into model-facing text, a body with newlines could open its
+    // own paragraph and speak in this module's instruction voice (panel, #93).
+    // Strip control, format/bidi and line/paragraph separators so the quoted
+    // body stays one inert line; the guidance above it is the only voice here.
+    const inert = body.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, " ");
+    return `Raw detail — Mnemoverse API error ${f.status} on ${f.method} ${f.path}: ${inert}`;
+}
+/**
+ * The request never got an answer at all: DNS, connectivity, a host that does
+ * not listen, or this client's own probe deadline firing.
+ *
+ * Included even though the brief was about HTTP statuses, because it is the
+ * OTHER half of the same defect and the two are easy to confuse. The 401
+ * message above tells an agent not to blame the network; this is the case where
+ * the network genuinely IS the answer, and `TypeError: fetch failed` — which is
+ * all a model saw before — is no more actionable than the raw 401 body was.
+ *
+ * A timeout is named separately because the advice differs in one word: an
+ * unreachable host is unlikely to become reachable in three seconds, whereas a
+ * request that ran out of time may well succeed on a second try.
+ */
+export function explainNetworkFailure(method, path, cause) {
+    const name = cause instanceof Error ? cause.name : "";
+    const timedOut = name === "TimeoutError" || name === "AbortError";
+    const detail = cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);
+    const head = timedOut
+        ? `Mnemoverse: the memory service did not answer ${method} ${path} in time.`
+        : `Mnemoverse: the memory service could not be reached at all — ${method} ` +
+            `${path} failed before any HTTP response came back.`;
+    const cause_ = timedOut
+        ? "The service may just be slow right now."
+        : "That is a connectivity or DNS problem, or MNEMOVERSE_API_URL pointing at " +
+            "a host that does not answer.";
+    return (`${head} ${cause_} This is NOT a rejected API key and NOT a quota — no ` +
+        "reply arrived to say anything about either, so do not send the user to " +
+        "check their key. One retry is reasonable. If that also fails, tell the " +
+        "user memory is unreachable and carry on without it rather than retrying.\n\n" +
+        `Raw detail — request to ${method} ${path} failed: ${detail}`);
+}
+/**
+ * 409: name the conflict this tool actually produced (panel, #93). The two
+ * real producers on this server are the join tool (used/expired/revoked
+ * invite) and memory_create_room (core: "A room with this name already
+ * exists.", 409). The old single sentence gave the invite advice to a
+ * duplicate-name conflict, misdirecting the agent to a nonexistent inviter.
+ */
+function explain409(f) {
+    if (f.path === "/memory/rooms/join") {
+        return ("Mnemoverse: this invite code cannot be used (409) — it has already " +
+            "been used, has expired, or was revoked. Ask whoever invited the user " +
+            "for a fresh one. Retrying the same code will conflict again.");
+    }
+    if (f.path === "/memory/rooms" && f.method === "POST") {
+        return ("Mnemoverse: a room with this name already exists for this account " +
+            "(409). Pick a different name, or reuse the existing room — " +
+            "memory_list_rooms shows its address. Retrying the same name will " +
+            "conflict again.");
+    }
+    return ("Mnemoverse: this request conflicts with the current state (409). The " +
+        "engine's own explanation is in the detail below — quote it to the " +
+        "user. Retrying the same request will conflict again.");
+}
+/** {@link explainNetworkFailure} as an error, so `instanceof` can tell a
+ *  transport failure from an HTTP one without reading either message. */
+export class NetworkError extends Error {
+    method;
+    path;
+    constructor(method, path, cause) {
+        super(explainNetworkFailure(method, path, cause), { cause });
+        this.name = "NetworkError";
+        this.method = method;
+        this.path = path;
+    }
+}
+/**
+ * A failed API call, as an ERROR OBJECT rather than a parsed string.
+ *
+ * The status and the body are fields because a caller that needs to branch on
+ * them must not do it by matching the message. `memory_list_recent` used to
+ * decide between "the endpoint is not deployed" and "this room does not exist"
+ * with `message.startsWith("Mnemoverse API error 404:")`, which coupled a
+ * behavioural branch to the exact prefix of a user-facing sentence — so
+ * improving the sentence, which is this change, would have silently flipped
+ * that branch. Structured fields make the wording free to change.
+ */
+export class ApiError extends Error {
+    status;
+    body;
+    method;
+    path;
+    /** The engine's envelope, already parsed — so a caller never re-parses. */
+    envelope;
+    constructor(f) {
+        super(explainApiFailure(f));
+        this.name = "ApiError";
+        this.status = f.status;
+        this.body = f.body;
+        this.method = f.method;
+        this.path = f.path;
+        this.envelope = parseErrorEnvelope(f.body);
+    }
+    /**
+     * A 404 the ENGINE did not answer: silence, or the router's literal
+     * defaults. This is what a path the deployment does not serve looks like
+     * — the first version of this predicate tested silence alone, mistook the
+     * real framework body `{"detail":"Not Found"}` for an engine answer, and
+     * un-fired the feed's degrade branch for the exact rollout case it exists
+     * for (panel, #93).
+     *
+     * NAMED FOR WHAT IT TESTS, not for what it implies: a gateway, a proxy or a
+     * wrong MNEMOVERSE_API_URL can produce the same shapes and is
+     * indistinguishable from here. Known, accepted edge: a foreign API whose
+     * 404 nests its error under a key this parser does not read
+     * (`{"error":{…}}`) also reads as bare, so the feed degrades to its
+     * not-supported notice instead of surfacing the foreign body — bounded
+     * harm, since against a wrong base URL the very next call fails with the
+     * instructive no-envelope wording.
+     */
+    get isBare404() {
+        return this.status === 404 && engineSilentOn404(this.envelope);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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