@gusnips/http 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Salomé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @gusnips/http
+
+The two shapes your API answers with, written down once as types. No dependencies, and nothing
+tied to a framework or a platform — your server, your browser client and your SDK all compile
+this same file.
+
+```bash
+bun add @gusnips/http
+```
+
+```ts
+import type { ApiSuccess } from "@gusnips/http";
+
+type Me = ApiSuccess<{ id: string; name: string }>;
+// → { data: { id: string; name: string }; meta?: PaginationMeta }
+```
+
+## The envelope
+
+Every route answers one of two things, and never anything else:
+
+```jsonc
+// 2xx
+{ "data": { "id": "u_1" }, "meta": { "total": 40, "limit": 20, "offset": 0, "hasMore": true } }
+
+// anything else
+{ "error": { "code": "NOT_FOUND", "message": "No such user" } }
+```
+
+Which means unwrapping and error-shaping happen in one place instead of in every hook.
+
+## The error half has four fields, and each does a different job
+
+```ts
+{
+  code: "RATE_LIMITED",              // what your code switches on. Stable, machine-facing.
+  message: "Too many requests",      // English, for logs and curl. Never your primary copy.
+  messageKey: "errors.rateLimited",  // names the SENTENCE, so the client localizes it
+  params: { limit: 100 },            // fills that sentence's blanks
+  details: { resetAt: "2026-01-01T00:00:00Z" }  // what makes the refusal actionable
+}
+```
+
+The split that matters is `message` versus `messageKey`. The server owns the _condition_; the
+client owns the _prose_. That is what lets an API refuse something without knowing what language
+the person reads, and `details` is what lets the client offer a way forward instead of a dead
+end.
+
+## The codes are yours
+
+Everything is generic over your own code union. Two codebases this came from had 30 codes and 16
+codes, overlapping on nine — a code list is an API's vocabulary and belongs to it.
+
+```ts
+import { asErrorCode, isApiError, type ApiError } from "@gusnips/http";
+
+type Code = "NOT_FOUND" | "RATE_LIMITED" | "UNKNOWN";
+const CODES = ["NOT_FOUND", "RATE_LIMITED", "UNKNOWN"] as const;
+
+if (isApiError<Code>(body)) {
+  switch (asErrorCode(CODES, body.error.code, "UNKNOWN")) {
+    case "RATE_LIMITED": /* … */
+  }
+}
+```
+
+`asErrorCode` exists for one reason: **a code you do not recognise means the server is newer than
+the tab.** A deploy landed ahead of the bundle someone is still running. That is not a parse
+failure and must not throw, so it falls back instead.
+
+## Status codes
+
+Write the map at the call site and let `satisfies` do the work:
+
+```ts
+export const ERROR_STATUS = {
+  NOT_FOUND: 404,
+  RATE_LIMITED: 429,
+} as const satisfies Record<Code, number>;
+```
+
+That one line is the point: adding a code to the union without giving it a status becomes a build
+error, instead of a route answering 500 for a refusal it knew how to explain.
+
+MIT · part of [frontkit](https://github.com/gusnips/frontkit)

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The HTTP envelope an API and its clients agree on.
+ *
+ * Every route answers one of two shapes — `{data, meta?}` or `{error:{…}}` — so unwrapping
+ * and error-shaping belong in one place rather than in every hook. This module is that
+ * place, and it is deliberately types plus three tiny functions: the API server produces
+ * the envelope, the browser client consumes it, the SDK re-exports it, and an agent reads
+ * it. All four compile this file unchanged, which is why it carries no framework and no
+ * platform (see `scripts/check-purity.ts`).
+ *
+ * **The codes are yours, not ours.** Two donor repos had 30 codes and 16 codes respectively,
+ * overlapping on nine; the list is an API's vocabulary and belongs to it. Everything here is
+ * generic over that union, so a product declares its own codes once and gets the envelope,
+ * the status map and the narrowing for free.
+ */
+/** Where a list route puts its counts. Identical in every donor, to the field. */
+export interface PaginationMeta {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+/**
+ * Success envelope — every 2xx JSON body is exactly this shape.
+ *
+ * `M` is the meta a route may attach. It defaults to {@link PaginationMeta} because a list
+ * route is the common case; a metered API passes its own union instead (one donor carries
+ * cache/credit counters there, and its rule — a cache hit is free and visibly so — is the
+ * kind of thing that must stay in that product).
+ */
+export interface ApiSuccess<T, M = PaginationMeta> {
+    data: T;
+    meta?: M;
+}
+/**
+ * Error envelope — byte-compatible with a server's `AppError.toJSON()`.
+ *
+ * The four fields are not decoration, and every donor arrived at the same four:
+ *
+ * - `code` is what a client switches on. Machine-oriented and stable.
+ * - `message` is English, for logs, `curl` output and agents. It is the fallback a client
+ *   shows when it cannot do better — never the primary copy for a person.
+ * - `messageKey` names the SENTENCE, so a client can localize or re-word a refusal without
+ *   the server knowing any language. The server owns the condition; the client owns the prose.
+ * - `params` fills that sentence's blanks, and `details` carries what makes a refusal
+ *   ACTIONABLE — the `resetAt` on a 429, the plan that lifts a 402. A refusal a caller cannot
+ *   act on is a dead end, which is the thing the whole product rule exists to prevent.
+ */
+export interface ApiError<Code extends string = string> {
+    error: {
+        code: Code;
+        /** English fallback — for logs, curl output and agents. Not shown when `messageKey` resolves. */
+        message: string;
+        /** Stable key naming the sentence, for a client that localizes or brands its copy. */
+        messageKey?: string;
+        /** Interpolation values for `messageKey`. */
+        params?: Record<string, string | number>;
+        details?: unknown;
+    };
+}
+export type ApiResponse<T, Code extends string = string, M = PaginationMeta> = ApiSuccess<T, M> | ApiError<Code>;
+/** True when a parsed body is the error half of the envelope. */
+export declare function isApiError<Code extends string>(body: unknown): body is ApiError<Code>;
+/**
+ * Narrow a code off the wire against the product's own list.
+ *
+ * An unrecognized code means the SERVER IS NEWER than this client — a deploy that landed
+ * ahead of the bundle a tab is still running. That is not a parse failure and must not throw;
+ * `fallback` is the honest read of "something failed and this build cannot classify it".
+ */
+export declare function asErrorCode<Code extends string>(codes: readonly Code[], value: string, fallback: Code): Code;
+/**
+ * A note on the code→status map, which is deliberately NOT a function here.
+ *
+ * Write it at the call site and let `satisfies` do the work:
+ *
+ * ```ts
+ * export const ERROR_STATUS = {
+ *   NOT_FOUND: 404,
+ *   RATE_LIMIT_EXCEEDED: 429,
+ * } as const satisfies Record<HttpErrorCode, number>;
+ * ```
+ *
+ * That is one line, and it is the line that matters: adding a code to the union without
+ * giving it a status becomes a build error rather than a route answering 500 for a refusal
+ * it knew how to explain. A helper wrapping this would add a call and subtract nothing.
+ * Keep every such map exhaustive — providerkit learned the same about its error→copy maps,
+ * where a widened union fell through to a status code in every locale at once.
+ */
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc;IAC/C,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,CAAC,EAAE,CAAC,CAAC;CACV;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,QAAQ,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACpD,KAAK,EAAE;QACL,IAAI,EAAE,IAAI,CAAC;QACX,iGAAiG;QACjG,OAAO,EAAE,MAAM,CAAC;QAChB,sFAAsF;QACtF,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,6CAA6C;QAC7C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;QACzC,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,cAAc,IACzE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;AAEpC,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,CAQrF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAC7C,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,IAAI,GACb,IAAI,CAEN;AAED;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/index.js

@@ -0,0 +1,52 @@
+/**
+ * The HTTP envelope an API and its clients agree on.
+ *
+ * Every route answers one of two shapes — `{data, meta?}` or `{error:{…}}` — so unwrapping
+ * and error-shaping belong in one place rather than in every hook. This module is that
+ * place, and it is deliberately types plus three tiny functions: the API server produces
+ * the envelope, the browser client consumes it, the SDK re-exports it, and an agent reads
+ * it. All four compile this file unchanged, which is why it carries no framework and no
+ * platform (see `scripts/check-purity.ts`).
+ *
+ * **The codes are yours, not ours.** Two donor repos had 30 codes and 16 codes respectively,
+ * overlapping on nine; the list is an API's vocabulary and belongs to it. Everything here is
+ * generic over that union, so a product declares its own codes once and gets the envelope,
+ * the status map and the narrowing for free.
+ */
+/** True when a parsed body is the error half of the envelope. */
+export function isApiError(body) {
+    return (typeof body === "object" &&
+        body !== null &&
+        "error" in body &&
+        typeof body.error === "object" &&
+        body.error !== null);
+}
+/**
+ * Narrow a code off the wire against the product's own list.
+ *
+ * An unrecognized code means the SERVER IS NEWER than this client — a deploy that landed
+ * ahead of the bundle a tab is still running. That is not a parse failure and must not throw;
+ * `fallback` is the honest read of "something failed and this build cannot classify it".
+ */
+export function asErrorCode(codes, value, fallback) {
+    return codes.find((c) => c === value) ?? fallback;
+}
+/**
+ * A note on the code→status map, which is deliberately NOT a function here.
+ *
+ * Write it at the call site and let `satisfies` do the work:
+ *
+ * ```ts
+ * export const ERROR_STATUS = {
+ *   NOT_FOUND: 404,
+ *   RATE_LIMIT_EXCEEDED: 429,
+ * } as const satisfies Record<HttpErrorCode, number>;
+ * ```
+ *
+ * That is one line, and it is the line that matters: adding a code to the union without
+ * giving it a status becomes a build error rather than a route answering 500 for a refusal
+ * it knew how to explain. A helper wrapping this would add a call and subtract nothing.
+ * Keep every such map exhaustive — providerkit learned the same about its error→copy maps,
+ * where a widened union fell through to a status code in every locale at once.
+ */
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAqDH,iEAAiE;AACjE,MAAM,UAAU,UAAU,CAAsB,IAAa;IAC3D,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,OAAO,IAAI,IAAI;QACf,OAAQ,IAAiB,CAAC,KAAK,KAAK,QAAQ;QAC3C,IAAiB,CAAC,KAAK,KAAK,IAAI,CAClC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,KAAsB,EACtB,KAAa,EACb,QAAc;IAEd,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,QAAQ,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@gusnips/http",
+  "version": "0.1.0",
+  "description": "The HTTP envelope an API and its clients agree on: {data, meta} or {error:{code, message, messageKey, params, details}}. Types only, zero dependencies, no framework.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Gustavo Salomé",
+  "homepage": "https://github.com/gusnips/frontkit/tree/main/http#readme",
+  "bugs": {
+    "url": "https://github.com/gusnips/frontkit/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "http",
+    "api",
+    "envelope",
+    "error-codes",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "sync:docs": "cp ../LICENSE .",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build && bun run sync:docs",
+    "release:patch": "bun pm version patch && bun publish --access public",
+    "release:minor": "bun pm version minor && bun publish --access public",
+    "release:major": "bun pm version major && bun publish --access public"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gusnips/frontkit.git",
+    "directory": "http"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { asErrorCode, isApiError } from "./index.ts";
+
+const CODES = ["NOT_FOUND", "RATE_LIMIT_EXCEEDED", "INTERNAL_ERROR"] as const;
+type Code = (typeof CODES)[number];
+
+describe("asErrorCode", () => {
+  it("passes a known code through", () => {
+    expect(asErrorCode<Code>(CODES, "NOT_FOUND", "INTERNAL_ERROR")).toBe("NOT_FOUND");
+  });
+
+  // The invariant: a server deployed ahead of the bundle a tab is still running sends a code
+  // this build has never heard of. That must degrade, not throw — an exception here would
+  // turn a refusal the server explained into a crash the client cannot report.
+  it("falls back rather than throwing on a code from a newer server", () => {
+    expect(asErrorCode<Code>(CODES, "SOME_CODE_SHIPPED_LAST_TUESDAY", "INTERNAL_ERROR")).toBe(
+      "INTERNAL_ERROR",
+    );
+  });
+});
+
+describe("isApiError", () => {
+  it("recognises the error half of the envelope", () => {
+    expect(isApiError({ error: { code: "NOT_FOUND", message: "no" } })).toBe(true);
+  });
+
+  it("rejects the success half, and anything that is not an object", () => {
+    expect(isApiError({ data: { id: 1 } })).toBe(false);
+    expect(isApiError(null)).toBe(false);
+    expect(isApiError("error")).toBe(false);
+    // `{error: null}` is the one that a bare `"error" in body` check gets wrong — a route
+    // that serialises a null error field would be read as a refusal with no code.
+    expect(isApiError({ error: null })).toBe(false);
+  });
+});

package/src/index.ts

@@ -0,0 +1,111 @@
+/**
+ * The HTTP envelope an API and its clients agree on.
+ *
+ * Every route answers one of two shapes — `{data, meta?}` or `{error:{…}}` — so unwrapping
+ * and error-shaping belong in one place rather than in every hook. This module is that
+ * place, and it is deliberately types plus three tiny functions: the API server produces
+ * the envelope, the browser client consumes it, the SDK re-exports it, and an agent reads
+ * it. All four compile this file unchanged, which is why it carries no framework and no
+ * platform (see `scripts/check-purity.ts`).
+ *
+ * **The codes are yours, not ours.** Two donor repos had 30 codes and 16 codes respectively,
+ * overlapping on nine; the list is an API's vocabulary and belongs to it. Everything here is
+ * generic over that union, so a product declares its own codes once and gets the envelope,
+ * the status map and the narrowing for free.
+ */
+
+/** Where a list route puts its counts. Identical in every donor, to the field. */
+export interface PaginationMeta {
+  total: number;
+  limit: number;
+  offset: number;
+  hasMore: boolean;
+}
+
+/**
+ * Success envelope — every 2xx JSON body is exactly this shape.
+ *
+ * `M` is the meta a route may attach. It defaults to {@link PaginationMeta} because a list
+ * route is the common case; a metered API passes its own union instead (one donor carries
+ * cache/credit counters there, and its rule — a cache hit is free and visibly so — is the
+ * kind of thing that must stay in that product).
+ */
+export interface ApiSuccess<T, M = PaginationMeta> {
+  data: T;
+  meta?: M;
+}
+
+/**
+ * Error envelope — byte-compatible with a server's `AppError.toJSON()`.
+ *
+ * The four fields are not decoration, and every donor arrived at the same four:
+ *
+ * - `code` is what a client switches on. Machine-oriented and stable.
+ * - `message` is English, for logs, `curl` output and agents. It is the fallback a client
+ *   shows when it cannot do better — never the primary copy for a person.
+ * - `messageKey` names the SENTENCE, so a client can localize or re-word a refusal without
+ *   the server knowing any language. The server owns the condition; the client owns the prose.
+ * - `params` fills that sentence's blanks, and `details` carries what makes a refusal
+ *   ACTIONABLE — the `resetAt` on a 429, the plan that lifts a 402. A refusal a caller cannot
+ *   act on is a dead end, which is the thing the whole product rule exists to prevent.
+ */
+export interface ApiError<Code extends string = string> {
+  error: {
+    code: Code;
+    /** English fallback — for logs, curl output and agents. Not shown when `messageKey` resolves. */
+    message: string;
+    /** Stable key naming the sentence, for a client that localizes or brands its copy. */
+    messageKey?: string;
+    /** Interpolation values for `messageKey`. */
+    params?: Record<string, string | number>;
+    details?: unknown;
+  };
+}
+
+export type ApiResponse<T, Code extends string = string, M = PaginationMeta> =
+  ApiSuccess<T, M> | ApiError<Code>;
+
+/** True when a parsed body is the error half of the envelope. */
+export function isApiError<Code extends string>(body: unknown): body is ApiError<Code> {
+  return (
+    typeof body === "object" &&
+    body !== null &&
+    "error" in body &&
+    typeof (body as ApiError).error === "object" &&
+    (body as ApiError).error !== null
+  );
+}
+
+/**
+ * Narrow a code off the wire against the product's own list.
+ *
+ * An unrecognized code means the SERVER IS NEWER than this client — a deploy that landed
+ * ahead of the bundle a tab is still running. That is not a parse failure and must not throw;
+ * `fallback` is the honest read of "something failed and this build cannot classify it".
+ */
+export function asErrorCode<Code extends string>(
+  codes: readonly Code[],
+  value: string,
+  fallback: Code,
+): Code {
+  return codes.find((c) => c === value) ?? fallback;
+}
+
+/**
+ * A note on the code→status map, which is deliberately NOT a function here.
+ *
+ * Write it at the call site and let `satisfies` do the work:
+ *
+ * ```ts
+ * export const ERROR_STATUS = {
+ *   NOT_FOUND: 404,
+ *   RATE_LIMIT_EXCEEDED: 429,
+ * } as const satisfies Record<HttpErrorCode, number>;
+ * ```
+ *
+ * That is one line, and it is the line that matters: adding a code to the union without
+ * giving it a status becomes a build error rather than a route answering 500 for a refusal
+ * it knew how to explain. A helper wrapping this would add a call and subtract nothing.
+ * Keep every such map exhaustive — providerkit learned the same about its error→copy maps,
+ * where a widened union fell through to a status code in every locale at once.
+ */