@gusnips/server 0.1.0

package/dist/logger/index.js

@@ -0,0 +1,74 @@
+/**
+ * One JSON line per event, on stdout, and nothing else.
+ *
+ * Twelve backends were read for this and none of them installs a logging library. The measured
+ * gap between 60 lines of `console.log(JSON.stringify(...))` and a real one is not levels,
+ * transports or child loggers — it is the error serializer, and the standard one ships the same
+ * copy-loop this package exists to remove. So the package ships no logging library, no transports,
+ * no file rotation and no extra levels. Every backend here runs under a process manager or a
+ * container that already owns stdout; nothing in twelve repos writes a log file.
+ */
+import { errorReplacer } from "./serialize.js";
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+const SILENT = Number.POSITIVE_INFINITY;
+function resolveThreshold(level) {
+    if (level === undefined || level === "")
+        return LEVELS.info;
+    if (level === "silent")
+        return SILENT;
+    const known = LEVELS[level];
+    if (known !== undefined)
+        return known;
+    // Loud, at construction, rather than silently falling back to "info": a box running at the
+    // wrong level is discovered during the incident it was meant to explain. This is called once
+    // at boot, so a typo fails the deploy instead of the 3am read.
+    throw new Error(`Unknown log level ${JSON.stringify(level)}. ` +
+        `Use one of: debug, info, warn, error, silent — or leave it unset for info.`);
+}
+function consoleWrite(line, level) {
+    if (level === "error")
+        console.error(line);
+    else if (level === "warn")
+        console.warn(line);
+    else
+        console.log(line);
+}
+/**
+ * Build a logger. Call it once, at boot, and pass the result to everything that logs.
+ *
+ *     const logger = createLogger({ level: process.env.LOG_LEVEL });
+ *     logger.info("server started", { port: 3000 });
+ *     logger.error("charge failed", { orderId, error: err });   // the RAW error, never String(err)
+ */
+export function createLogger(options = {}) {
+    const threshold = resolveThreshold(options.level);
+    const write = options.write ?? consoleWrite;
+    function emit(level, message, meta) {
+        if (LEVELS[level] < threshold)
+            return;
+        // Canonical fields last, so they win: a meta `message`, `level` or `time` must never replace
+        // the line's own label, severity or timestamp. One backend re-implemented this logger inline
+        // with the order inverted, and a `meta.message` silently became the line.
+        const time = new Date().toISOString();
+        const entry = { ...meta, level, time, message };
+        let line;
+        try {
+            line = JSON.stringify(entry, errorReplacer());
+        }
+        catch {
+            // A logger must never take down the process it is reporting on. Reachable through a
+            // throwing getter or a throwing `toJSON()` on something in `meta` — and the flag is there
+            // so a reader knows a line was lost rather than never written.
+            line = JSON.stringify({ level, time, message, logSerializationFailed: true });
+        }
+        write(line, level);
+    }
+    return {
+        debug: (message, meta) => emit("debug", message, meta),
+        info: (message, meta) => emit("info", message, meta),
+        warn: (message, meta) => emit("warn", message, meta),
+        error: (message, meta) => emit("error", message, meta),
+    };
+}
+export { errorReplacer, keptErrorFields } from "./serialize.js";
+//# sourceMappingURL=index.js.map

package/dist/logger/index.js.map

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

package/dist/logger/serialize.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The error serializer. This is the one file in `@gusnips/server` that exists because of an
+ * incident rather than because of duplication.
+ *
+ * Six backends shipped the same replacer, and it copied **every own enumerable property** off a
+ * caught Error into the log line. The comment beside the loop said it was there to pick up a
+ * Postgres `code`/`detail`/`hint`. What it actually picked up was whatever the SDK that threw had
+ * hung on the error — which for two vendors in use is the request the caller sent us.
+ */
+/**
+ * A thrown value that is NOT an Error, narrowed to what a log line may print off it.
+ *
+ * The allow-list above is written against Errors, and until this the narrowing stopped there: an
+ * Error was filtered and whatever sat in its `cause` was copied whole. That gap is not theoretical
+ * here, it is this package's own doing — `errorBoundary` turns every non-Error throw into
+ * `new Error(toMessage(err), { cause: err })`, because Hono's `onError` never sees a non-Error and
+ * a PostgREST client rejects with plain objects. So in a Hono app the cause slot is precisely where
+ * a vendor's rejection object ends up, and a leak there reads as if the list had run.
+ *
+ * `cause` means "the error this one came from", so whatever sits in it is in the error slot and
+ * gets the same treatment. `name` and `message` come along because a rejection object usually
+ * carries them and a line with neither says nothing at all.
+ *
+ * Deliberate state it does NOT keep: context an app attaches on purpose. That belongs in the
+ * logger's `meta`, which is untouched — `cause` is not the place for it, and one incident of a
+ * vendor's request body in the log outweighs a field nobody put there deliberately.
+ */
+export declare function narrowErrorLike(value: object): Record<string, unknown>;
+/**
+ * A `JSON.stringify` replacer that keeps log lines useful and crash-proof:
+ *
+ * - Errors serialize to a readable object. `message` and `stack` are non-enumerable, so a plain
+ *   `JSON.stringify(err)` is `{}` — which is how a logger ends up printing nothing about the
+ *   failure it was called to report. They are added explicitly, and the allow-listed extras ride
+ *   along beside them.
+ * - A nested `cause` is followed, and so is an `AggregateError`'s `errors`. Both are
+ *   non-enumerable, so both are invisible to the loop above; without this line "all attempts
+ *   failed" is the whole log entry. Each one goes back through this replacer, so the allow-list
+ *   covers the chain, not just the top — and a cause that is not an Error is narrowed here
+ *   instead, by {@link narrowErrorLike}, because the replacer's Error branch would never see it.
+ * - bigints stringify instead of throwing.
+ * - Circular references collapse to "[Circular]" instead of crashing the log call.
+ *
+ * Paired with callers passing the RAW error rather than `String(err)`, this is why a log line
+ * never reads "[object Object]".
+ *
+ * One ordering fact decides what this replacer would otherwise see: `JSON.stringify` calls a
+ * value's own `toJSON()` **before** the replacer, so an error class that defines one arrives here
+ * already turned into whatever that method returns — the stack and the cause gone, and the result
+ * usually shaped for the WIRE, because that is what an error's `toJSON()` is for. Seven backends
+ * on this stack define one, and `logger.error("x", { error: appErr })` wrote
+ * `{"error":{"error":{…}}}` in every one of them: double-nested, no stack, no cause, and
+ * invisible, because the line still looks like a log line.
+ *
+ * The original is still there. `JSON.stringify` calls the replacer with the HOLDER as `this`, and
+ * the holder's own property is the untouched value — so `this[key]` recovers the Error that
+ * `toJSON()` replaced. That is why this is a `function` and not an arrow.
+ *
+ * What a log line keeps off an Error is this file's decision, not the error's: an error class is
+ * free to define the body it sends a client, and the log still gets name, message, stack, cause
+ * and the allow-list.
+ *
+ * A new replacer per log line, because the `seen` set must not outlive one entry.
+ */
+export declare function errorReplacer(): (this: unknown, key: string, value: unknown) => unknown;
+/** The keys an Error may contribute to a log line, beside `name`, `message`, `stack` and `cause`. */
+export declare const keptErrorFields: ReadonlySet<string>;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/logger/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/logger/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2EH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEtE;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,aAAa,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CA4BvF;AAED,qGAAqG;AACrG,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAAqB,CAAC"}

package/dist/logger/serialize.js

@@ -0,0 +1,203 @@
+/**
+ * The error serializer. This is the one file in `@gusnips/server` that exists because of an
+ * incident rather than because of duplication.
+ *
+ * Six backends shipped the same replacer, and it copied **every own enumerable property** off a
+ * caught Error into the log line. The comment beside the loop said it was there to pick up a
+ * Postgres `code`/`detail`/`hint`. What it actually picked up was whatever the SDK that threw had
+ * hung on the error — which for two vendors in use is the request the caller sent us.
+ */
+/**
+ * The own enumerable properties a log line keeps off an Error. An ALLOW-list, not a deny-list,
+ * because an SDK hangs its own INPUTS off the error it throws, and the list of words vendors use
+ * for that is open-ended:
+ *
+ * - **A payment SDK.** Its signature-verification error carries `payload` — the entire unparsed
+ *   webhook body — and `header`, the signature it was checked against. Measured on the pinned
+ *   version: that error has **25 own enumerable properties** and this list admits **4** of them
+ *   (`type`, `code`, `detail`, `statusCode`). Among the 21 dropped are `raw` (the whole error body)
+ *   and `headers`. A webhook route is unauthenticated by definition, so the old loop let anyone on
+ *   the internet write content of their choosing into the log by POSTing a junk signature.
+ * - **A Redis client.** A server-returned error carries `command = { name, args }`. On an AUTH
+ *   failure those args are the password — written to stdout at the exact moment an operator is
+ *   reading the log to find out why Redis is refusing them.
+ * - **Postgres.** A `DatabaseError` carries `where` and `internalQuery`, which hold **statement
+ *   text with its literals in it**. Reproduced against Postgres 18: a CHECK violation raised inside
+ *   a PL/pgSQL function set `where` to the failing INSERT, e-mail address and card number included.
+ *   pg is in every backend here, so this one was never vendor-specific.
+ *
+ * A deny-list would have had to know `payload`, `header`, `raw`, `command`, `where` and the next
+ * vendor's word for it, and it learns each one from an incident. This list only has to know ours.
+ *
+ * **Add a key when our own code reads it off a caught error.** Two on it have no reader and say so
+ * below; everything else was measured across twelve backends.
+ */
+const KEPT_ERROR_FIELDS = new Set([
+    // Postgres and PostgREST diagnostics. `detail` is the pg driver's spelling, `details`
+    // PostgREST's. `hint` has no reader anywhere in the fleet — it is kept because the donor
+    // comment promises it by name and a Postgres HINT never carries a value, only a suggestion.
+    "code",
+    "detail",
+    "details",
+    "hint",
+    "constraint",
+    "severity",
+    // Our own error classes, and the classified failures the modules throw.
+    "statusCode",
+    "status",
+    "messageKey",
+    "params",
+    "retryAfterSecs",
+    // The same number under an SDK's spelling. Our house word is `retryAfterSecs`; one SDK in the
+    // fleet says `retryAfter`, and two call sites read it off the caught error — so without this a
+    // rate-limit line says it was rate-limited and not for how long.
+    "retryAfter",
+    "kind",
+    "retryable",
+    // Which vendor error this was. One vendor sets `type` and never sets `name`, so without this
+    // every failure from it logs as a bare "Error". Read off the SDK, not guessed.
+    "type",
+]);
+/**
+ * Postgres writes the **entire failing row** into DETAIL for a CHECK or NOT NULL violation —
+ * every column of it, whatever that table happens to hold. Measured against Postgres 18:
+ *
+ *     detail: "Failing row contains (someone@example.com, 4242424242424242)."
+ *
+ * That is the one value-level rule in this file, and it is here rather than in a redaction pass
+ * because it is not a pattern over arbitrary text: it is one exact message form, and Postgres is
+ * the only thing that writes it. The unique-violation form — `Key (slug)=(demo) already exists.` —
+ * names only the key columns, which is the diagnostic this field is kept for, and survives.
+ */
+const PG_FAILING_ROW = "Failing row contains (";
+const OMITTED_ROW = "[row omitted: Postgres DETAIL for this error is the whole failing row]";
+function keptValue(key, value) {
+    if ((key === "detail" || key === "details") && typeof value === "string") {
+        return value.startsWith(PG_FAILING_ROW) ? OMITTED_ROW : value;
+    }
+    return value;
+}
+/**
+ * A thrown value that is NOT an Error, narrowed to what a log line may print off it.
+ *
+ * The allow-list above is written against Errors, and until this the narrowing stopped there: an
+ * Error was filtered and whatever sat in its `cause` was copied whole. That gap is not theoretical
+ * here, it is this package's own doing — `errorBoundary` turns every non-Error throw into
+ * `new Error(toMessage(err), { cause: err })`, because Hono's `onError` never sees a non-Error and
+ * a PostgREST client rejects with plain objects. So in a Hono app the cause slot is precisely where
+ * a vendor's rejection object ends up, and a leak there reads as if the list had run.
+ *
+ * `cause` means "the error this one came from", so whatever sits in it is in the error slot and
+ * gets the same treatment. `name` and `message` come along because a rejection object usually
+ * carries them and a line with neither says nothing at all.
+ *
+ * Deliberate state it does NOT keep: context an app attaches on purpose. That belongs in the
+ * logger's `meta`, which is untouched — `cause` is not the place for it, and one incident of a
+ * vendor's request body in the log outweighs a field nobody put there deliberately.
+ */
+export function narrowErrorLike(value) {
+    return narrow(value, new WeakSet());
+}
+function narrow(value, seen) {
+    seen.add(value);
+    const out = {};
+    const { name, message, cause } = value;
+    if (typeof name === "string")
+        out.name = name;
+    if (typeof message === "string")
+        out.message = message;
+    for (const [k, v] of Object.entries(value)) {
+        if (KEPT_ERROR_FIELDS.has(k))
+            out[k] = keptValue(k, v);
+    }
+    if (cause !== undefined)
+        out.cause = narrowCause(cause, seen);
+    return out;
+}
+/**
+ * An Error cause goes back unchanged, because `JSON.stringify` walks it into the replacer's own
+ * Error branch. Anything that is not an object is a string or a number, which is its own value.
+ */
+function narrowCause(cause, seen) {
+    if (cause instanceof Error || typeof cause !== "object" || cause === null)
+        return cause;
+    // The recursion builds new objects, so the replacer's `seen` cannot see this chain: a rejection
+    // that holds itself would recurse until the stack ends, inside the one call that must never take
+    // the process down.
+    return seen.has(cause) ? "[Circular]" : narrow(cause, seen);
+}
+/**
+ * A `JSON.stringify` replacer that keeps log lines useful and crash-proof:
+ *
+ * - Errors serialize to a readable object. `message` and `stack` are non-enumerable, so a plain
+ *   `JSON.stringify(err)` is `{}` — which is how a logger ends up printing nothing about the
+ *   failure it was called to report. They are added explicitly, and the allow-listed extras ride
+ *   along beside them.
+ * - A nested `cause` is followed, and so is an `AggregateError`'s `errors`. Both are
+ *   non-enumerable, so both are invisible to the loop above; without this line "all attempts
+ *   failed" is the whole log entry. Each one goes back through this replacer, so the allow-list
+ *   covers the chain, not just the top — and a cause that is not an Error is narrowed here
+ *   instead, by {@link narrowErrorLike}, because the replacer's Error branch would never see it.
+ * - bigints stringify instead of throwing.
+ * - Circular references collapse to "[Circular]" instead of crashing the log call.
+ *
+ * Paired with callers passing the RAW error rather than `String(err)`, this is why a log line
+ * never reads "[object Object]".
+ *
+ * One ordering fact decides what this replacer would otherwise see: `JSON.stringify` calls a
+ * value's own `toJSON()` **before** the replacer, so an error class that defines one arrives here
+ * already turned into whatever that method returns — the stack and the cause gone, and the result
+ * usually shaped for the WIRE, because that is what an error's `toJSON()` is for. Seven backends
+ * on this stack define one, and `logger.error("x", { error: appErr })` wrote
+ * `{"error":{"error":{…}}}` in every one of them: double-nested, no stack, no cause, and
+ * invisible, because the line still looks like a log line.
+ *
+ * The original is still there. `JSON.stringify` calls the replacer with the HOLDER as `this`, and
+ * the holder's own property is the untouched value — so `this[key]` recovers the Error that
+ * `toJSON()` replaced. That is why this is a `function` and not an arrow.
+ *
+ * What a log line keeps off an Error is this file's decision, not the error's: an error class is
+ * free to define the body it sends a client, and the log still gets name, message, stack, cause
+ * and the allow-list.
+ *
+ * A new replacer per log line, because the `seen` set must not outlive one entry.
+ */
+export function errorReplacer() {
+    const seen = new WeakSet();
+    return function (key, value) {
+        const held = typeof this === "object" && this !== null
+            ? this[key]
+            : undefined;
+        if (held instanceof Error)
+            value = held;
+        if (typeof value === "bigint")
+            return value.toString();
+        if (value instanceof Error) {
+            if (seen.has(value))
+                return "[Circular]";
+            seen.add(value);
+            const out = { name: value.name, message: value.message };
+            for (const [k, v] of Object.entries(value)) {
+                if (KEPT_ERROR_FIELDS.has(k))
+                    out[k] = keptValue(k, v);
+            }
+            const { cause } = value;
+            if (cause !== undefined)
+                out.cause = narrowCause(cause, seen);
+            if (value instanceof AggregateError)
+                out.errors = value.errors;
+            if (value.stack)
+                out.stack = value.stack;
+            return out;
+        }
+        if (typeof value === "object" && value !== null) {
+            if (seen.has(value))
+                return "[Circular]";
+            seen.add(value);
+        }
+        return value;
+    };
+}
+/** The keys an Error may contribute to a log line, beside `name`, `message`, `stack` and `cause`. */
+export const keptErrorFields = KEPT_ERROR_FIELDS;
+//# sourceMappingURL=serialize.js.map

package/dist/logger/serialize.js.map

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

package/dist/responses.d.ts

@@ -0,0 +1,107 @@
+/**
+ * How a backend answers: the success envelope, and the one function that turns a thrown thing
+ * into an HTTP answer.
+ *
+ * Nothing here knows about a framework, and that is a measurement rather than a preference.
+ * Five backends put this logic inside one `app.onError`, and then **three of them re-derived
+ * the same two arms inside an MCP tool wrapper** so an agent would get a real refusal instead
+ * of "an unexpected error occurred". A fourth re-derived the error body inside a background
+ * worker's health handler and got it wrong, answering a caught Redis message on a 503 — the
+ * API next door masks exactly that. A `Context`-shaped function would serve one of those four
+ * callers. The framework adapter is eight lines and lives in `/hono`.
+ */
+import type { ApiError, ApiSuccess, PaginationMeta } from "@gusnips/http";
+/** Every 2xx body is `{ data }`, or `{ data, meta }` where a route has counts to report. */
+export declare function ok<T, M = PaginationMeta>(data: T, meta?: M): {
+    status: 200;
+    body: ApiSuccess<T, M>;
+};
+export declare function created<T>(data: T): {
+    status: 201;
+    body: ApiSuccess<T, PaginationMeta>;
+};
+/**
+ * `hasMore` is computed from the page that was actually returned, not from `limit`: a page cut
+ * short by a filter still has to answer the question honestly. Identical, to the field, in five
+ * donors.
+ */
+export declare function paginated<T>(rows: T[], meta: Omit<PaginationMeta, "hasMore">): {
+    status: 200;
+    body: ApiSuccess<T[], PaginationMeta>;
+};
+export declare function noContent(): {
+    status: 204;
+    body: null;
+};
+export interface ErrorAnswer<Code extends string = string> {
+    status: number;
+    body: ApiError<Code>;
+    /** `Retry-After` when the refusal states a wait; `WWW-Authenticate` on a 401. */
+    headers: Record<string, string>;
+    /**
+     * What kind of failure this was, which is the one thing a caller cannot work out from the
+     * status. A 500 raised on purpose and a `TypeError` that escaped are both 500s, and only the
+     * second one means nobody is watching a log for it — every donor fires its admin alert on
+     * exactly that branch.
+     */
+    kind: "client" | "server" | "unexpected";
+}
+/** The envelope a masked 5xx, an unexpected throw, or a refused body is answered with. */
+export interface CannedError<Code extends string, Key extends string> {
+    code: Code;
+    /** English, for logs, `curl` and agents. A client localizes from `messageKey`. */
+    message: string;
+    messageKey?: Key;
+}
+export interface ErrorResponseOptions<Code extends string, Key extends string> {
+    /** Answers a masked 5xx and anything that escaped. */
+    internal: CannedError<Code, Key>;
+    /** Answers a validation failure. */
+    validation: CannedError<Code, Key>;
+    /**
+     * The 5xx codes whose message is replaced. Defaults to `["INTERNAL_ERROR"]`, which is what
+     * four of the five newest donors do, and their reason is worth keeping: flattening a
+     * `GATEWAY_ERROR` or a `SERVICE_UNAVAILABLE` into a generic 500 "would take away the one
+     * thing that tells a developer whether to retry."
+     *
+     * **That default is safe because of your call sites, not because of this code.** It holds
+     * only while every non-masked 5xx is handed a message somebody wrote for the client. A repo
+     * whose repository layer interpolates the driver's error into the message it raises — one
+     * donor's does, deliberately, so that duplicate-key heuristics keep working — wants
+     * `maskAll` instead.
+     */
+    maskedCodes?: readonly Code[];
+    /** Replace every 5xx message, and let `expose` be what opts an authored sentence back in. */
+    maskAll?: boolean;
+    /**
+     * Drop `details` from a 5xx whose message you did NOT mask — a separate knob because it is a
+     * separate decision. The newest donors put a readiness report in a 503's details, naming
+     * which dependency is down so a deploy gate and a human at 3am can both read it; another
+     * donor's details are where caught error text is recorded, and must never go out. Both are
+     * right about their own repo, which is why this is not folded into the mask above. (A masked
+     * 5xx drops its details on its own: the body is built fresh from `internal`.)
+     *
+     * The sharpest reason to turn it on is a caught driver error handed straight to `details`.
+     * On a CHECK or NOT NULL violation Postgres writes the ENTIRE failing row into its `detail`
+     * field — `Failing row contains (someone@example.com, 4242…)`, every column, values
+     * included. Measured against a real server, not assumed.
+     */
+    maskDetails?: boolean;
+}
+/**
+ * Binds the mask policy and the two canned bodies, and returns the function that answers.
+ *
+ * Bound once, at the app's edge, because the alternative is what the reading found: four places
+ * in one fleet deciding the mask separately, and the one furthest from the API getting it
+ * wrong. Every other door — a tool wrapper, a worker's health port — imports the same bound
+ * function and cannot disagree with the API about what a refusal looks like.
+ *
+ * ```ts
+ * export const errorResponse = createErrorResponse<ErrorCode, MessageKey>({
+ *   internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+ *   validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+ * });
+ * ```
+ */
+export declare function createErrorResponse<Code extends string = string, Key extends string = string>(opts: ErrorResponseOptions<Code, Key>): (err: unknown) => ErrorAnswer<Code>;
+//# sourceMappingURL=responses.d.ts.map

package/dist/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../src/responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG1E,4FAA4F;AAC5F,wBAAgB,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;;;EAG1D;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;;;EAGjC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC;;;EAM5E;AAED,wBAAgB,SAAS;;;EAExB;AAED,MAAM,WAAW,WAAW,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACrB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;;OAKG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,YAAY,CAAC;CAC1C;AAED,0FAA0F;AAC1F,MAAM,WAAW,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM;IAClE,IAAI,EAAE,IAAI,CAAC;IACX,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,GAAG,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM;IAC3E,sDAAsD;IACtD,QAAQ,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjC,oCAAoC;IACpC,UAAU,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IAC9B,6FAA6F;IAC7F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA+GD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3F,IAAI,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,IAIP,KAAK,OAAO,KAAG,WAAW,CAAC,IAAI,CAAC,CA8C/D"}

package/dist/responses.js

@@ -0,0 +1,183 @@
+import { AppError } from "./errors.js";
+/** Every 2xx body is `{ data }`, or `{ data, meta }` where a route has counts to report. */
+export function ok(data, meta) {
+    const body = meta === undefined ? { data } : { data, meta };
+    return { status: 200, body };
+}
+export function created(data) {
+    const body = { data };
+    return { status: 201, body };
+}
+/**
+ * `hasMore` is computed from the page that was actually returned, not from `limit`: a page cut
+ * short by a filter still has to answer the question honestly. Identical, to the field, in five
+ * donors.
+ */
+export function paginated(rows, meta) {
+    const body = {
+        data: rows,
+        meta: { ...meta, hasMore: meta.offset + rows.length < meta.total },
+    };
+    return { status: 200, body };
+}
+export function noContent() {
+    return { status: 204, body: null };
+}
+/**
+ * `retryAfterSecs` also rides inside `details`, because that is where clients already look —
+ * an explicit `null` included, since "waiting cannot fix this" is an answer a client needs and
+ * the only alternative is the hand-written code list this replaces.
+ *
+ * Only an object `details` can carry it. Spreading an ARRAY — a list of validation issues —
+ * turns it into `{"0": …}` and breaks every client that parses it; spreading a STRING turns it
+ * into one key per character. Anything that is not a plain object is handed back untouched, and
+ * the header still tells that caller when to come back.
+ */
+function detailsWithRetry(err) {
+    if (err.retryAfterSecs === undefined)
+        return err.details;
+    const carries = err.details === undefined ||
+        (typeof err.details === "object" && err.details !== null && !Array.isArray(err.details));
+    if (!carries)
+        return err.details;
+    return { ...err.details, retryAfterSecs: err.retryAfterSecs };
+}
+/**
+ * The wire body for an error somebody raised on purpose.
+ *
+ * It is a function rather than a method on `AppError`, and that is a fix rather than a style
+ * choice — see the note on the class. It also keeps the envelope in one file with the mask,
+ * instead of in two.
+ */
+function appErrorBody(err) {
+    const details = detailsWithRetry(err);
+    return {
+        error: {
+            code: err.code,
+            message: err.message,
+            ...(err.messageKey !== undefined && { messageKey: err.messageKey }),
+            ...(err.params !== undefined && { params: err.params }),
+            ...(details !== undefined && { details }),
+        },
+    };
+}
+function envelope(canned, details) {
+    return {
+        error: {
+            code: canned.code,
+            message: canned.message,
+            ...(canned.messageKey !== undefined && { messageKey: canned.messageKey }),
+            ...(details !== undefined && { details }),
+        },
+    };
+}
+/**
+ * Recognize a validation failure without importing the validator.
+ *
+ * `name === "ZodError"` plus an `issues` array holds for zod 3.25, 4.4 and 4.5 — measured, all
+ * three, because this package must not make an adopter's validator its own dependency. It also
+ * accepts an issue list that arrived some other way, which is what a second door (an MCP tool,
+ * a queue consumer) needs.
+ */
+function zodIssues(err) {
+    if (typeof err !== "object" || err === null)
+        return null;
+    const { name, issues } = err;
+    if (name !== "ZodError" || !Array.isArray(issues))
+        return null;
+    return issues;
+}
+/**
+ * The field path, the rule it failed, and — for a range — the BOUND it failed against.
+ *
+ * Never the rejected value, and never the schema's internals. All six donors carry a version of
+ * that comment; what none of them carries is the proof, so here it is: handing the validator's
+ * issues straight to the client ships back the caller's own key names (`keys`), the enum's
+ * allowed values (`values`), the validator's English sentence and the expected type
+ * (`origin`) — four disclosures from one convenience, and two repos in the fleet do it today.
+ * An audit note written against an older validator looks for `received`, which the current one
+ * no longer emits; the projection is an allow-list precisely so a rename cannot reopen this.
+ *
+ * The bound is the exception, and it belongs to the caller: it is the published contract, and
+ * a `too_big` without it costs somebody a bisect to rediscover a number our own docs state.
+ */
+function safeIssues(issues) {
+    return issues.map((issue) => ({
+        path: issue.path,
+        code: issue.code,
+        ...(typeof issue.maximum === "number" && { maximum: issue.maximum }),
+        ...(typeof issue.minimum === "number" && { minimum: issue.minimum }),
+    }));
+}
+/**
+ * `AppError` is generic over the product's own code union, and no runtime check can verify
+ * membership. The predicate asserts what `createAppError` guarantees: every `AppError` in this
+ * app was built from the map whose keys are `Code`.
+ */
+function isAppError(err) {
+    return err instanceof AppError;
+}
+const DEFAULT_MASKED = ["INTERNAL_ERROR"];
+/**
+ * Binds the mask policy and the two canned bodies, and returns the function that answers.
+ *
+ * Bound once, at the app's edge, because the alternative is what the reading found: four places
+ * in one fleet deciding the mask separately, and the one furthest from the API getting it
+ * wrong. Every other door — a tool wrapper, a worker's health port — imports the same bound
+ * function and cannot disagree with the API about what a refusal looks like.
+ *
+ * ```ts
+ * export const errorResponse = createErrorResponse<ErrorCode, MessageKey>({
+ *   internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+ *   validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+ * });
+ * ```
+ */
+export function createErrorResponse(opts) {
+    const maskedCodes = opts.maskedCodes ?? DEFAULT_MASKED;
+    return function errorResponse(err) {
+        const issues = zodIssues(err);
+        if (issues !== null) {
+            return {
+                status: 400,
+                body: envelope(opts.validation, safeIssues(issues)),
+                headers: {},
+                kind: "client",
+            };
+        }
+        if (isAppError(err)) {
+            const headers = {};
+            // The standard header, not just our envelope: every HTTP client, proxy and SDK already
+            // knows how to wait on `Retry-After`, and none of them knows `details.retryAfterSecs`.
+            // A number only — a refusal that waiting cannot fix says so in the body, because
+            // `Retry-After: null` is a header that states a wait and names no time.
+            if (typeof err.retryAfterSecs === "number") {
+                headers["Retry-After"] = String(err.retryAfterSecs);
+            }
+            // RFC 6750 §3: a 401 names the scheme it wants. Without it a 401 is a closed door with no
+            // handle — which is what an agent, with no human to ask, is left holding.
+            if (err.statusCode === 401)
+                headers["WWW-Authenticate"] = "Bearer";
+            if (err.statusCode < 500)
+                return { status: err.statusCode, body: appErrorBody(err), headers, kind: "client" };
+            const hide = !err.expose && (opts.maskAll === true || maskedCodes.includes(err.code));
+            if (hide) {
+                // The message is replaced; the STATUS is not. A status is chosen by our own map and
+                // discloses nothing, while it is the only thing left telling a client whether waiting
+                // can help — collapsing a masked 502 into a 500 throws that away for no gain. One
+                // donor does collapse it, and never noticed because it masks only the code that is
+                // already a 500.
+                return { status: err.statusCode, body: envelope(opts.internal), headers, kind: "server" };
+            }
+            const body = appErrorBody(err);
+            if (opts.maskDetails === true)
+                delete body.error.details;
+            return { status: err.statusCode, body, headers, kind: "server" };
+        }
+        // Nothing raised this on purpose, so nothing in it was written for a reader. Whatever it
+        // says stays in the log: a background worker in the fleet answers `toMessage(err)` on its
+        // health port today, which is a driver's sentence on the wire.
+        return { status: 500, body: envelope(opts.internal), headers: {}, kind: "unexpected" };
+    };
+}
+//# sourceMappingURL=responses.js.map