@rubriclab/rubrot-api 0.1.0 → 0.2.0

package/README.md

@@ -7,7 +7,9 @@ The fleet's API contract layer, folded together from the metal `/api/v1` `_lib`
 Every failure body is `{ error: { code, message } }` with a stable `ApiErrorCode` (`AUTH_MISSING`, `AUTH_INVALID`, `SCOPE_MISSING`, `BAD_REQUEST`, `INVALID_JSON`, `NOT_FOUND`, `UPSTREAM_CONTRACT`, `UPSTREAM_ERROR`, `INTERNAL`). Every response built here — success or failure — carries `cache-control: no-store`.
 
 ```
-jsonError(code, message, status)       structured failure
+jsonError(code, message, status)       structured failure, explicit code (the primitive)
+apiError(message, status, code?)       structured failure, code defaulted by status
+codeForStatus(status)                  the default status → ApiErrorCode map
 apiJson(data, status?)                 non-cached JSON success
 apiText(body, status?)                 non-cached text/plain (dotenv projections)
 parseRequestJson(request, contract)    JSON + zod in one step → data | ready 400
@@ -17,9 +19,34 @@ pageItems / pageLimitOnlyItems         { items, pagination } envelope (exact / c
 limitForOffset(query)                  SQL LIMIT with the next-page sentinel row
 ```
 
+### Status → code
+
+`codeForStatus(status)` is the one default map — the glue vault (`codeForStatus`)
+and rubrot (`authErrorCode`) each hand-rolled, reconciled:
+
+| status | code            |
+| ------ | --------------- |
+| 400    | `BAD_REQUEST`   |
+| 401    | `AUTH_INVALID`  |
+| 403    | `SCOPE_MISSING` |
+| 404    | `NOT_FOUND`     |
+| else   | `INTERNAL`      |
+
+`apiError(message, status, code?)` builds a failure from a status alone
+(`code` defaults via `codeForStatus`) or takes an explicit `code` to override —
+it is vault's `apiError` and rubrot's `caughtApiError` folded into one, with
+`jsonError` as the explicit-code primitive underneath.
+
+`AUTH_MISSING` is **never** produced by the default map — a 401 defaults to
+`AUTH_INVALID` (a presented credential was bad). "No credential at all" is a
+distinction only the caller can draw, so it is **consumer-emitted**: pass
+`code: "AUTH_MISSING"` (on an `AuthFailure`, or straight to `apiError`) where the
+app decides a request carried no credentials. `INTERNAL` is the fail-closed
+floor for any unmapped status.
+
 ## Authenticated routes
 
-`withAuth(authenticate, handler)` collapses what every route must get right — the auth gate, `no-store`, and fail-closed errors (a thrown handler logs and returns a clean structured 500, never a leak) — into one place. The authenticator is injected: header in, `{ ok, identity } | { ok: false, status, error, code? }` out. On failure, `code` defaults by status (403 → `SCOPE_MISSING`, else `AUTH_INVALID`).
+`withAuth(authenticate, handler)` collapses what every route must get right — the auth gate, `no-store`, and fail-closed errors (a thrown handler logs and returns a clean structured 500, never a leak) — into one place. The authenticator is injected: header in, `{ ok, identity } | { ok: false, status, error, code? }` out. On failure the wrapper builds the response via `apiError` — a set `code` wins, otherwise it defaults through `codeForStatus` (see the table above).
 
 ```ts
 // lib/api.ts — bind once per app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubriclab/rubrot-api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "description": "The fleet's API contract layer: structured errors, zod request parsing, pagination, and fail-closed authenticated route wrappers",

package/src/handler.ts

@@ -1,4 +1,4 @@
-import { type ApiErrorCode, jsonError } from "./json";
+import { type ApiErrorCode, apiError } from "./json";
 
 /**
  * The shared handler harness — vault's `withRead`/`withWrite` pattern with the
@@ -49,15 +49,12 @@ export type AuthedHandler<Identity, P = Record<string, string | string[]>> = (
   context: RouteContext<P>,
 ) => Promise<Response>;
 
-function failureCode(failure: AuthFailure): ApiErrorCode {
-  if (failure.code) return failure.code;
-  return failure.status === 403 ? "SCOPE_MISSING" : "AUTH_INVALID";
-}
-
 /**
  * The core wrapper: authenticate with `authenticate`, then run the handler
  * under a fail-closed catch. An auth failure and a thrown handler both resolve
- * to the canonical structured error — never an unstructured 500.
+ * to the canonical structured error — never an unstructured 500. On an auth
+ * failure `apiError` fills `code` from `auth.code` if the authenticator set one
+ * (e.g. `AUTH_MISSING`), else defaults it via `codeForStatus`.
  */
 export function withAuth<Identity, P = Record<string, string | string[]>>(
   authenticate: Authenticator<Identity>,
@@ -65,12 +62,12 @@ export function withAuth<Identity, P = Record<string, string | string[]>>(
 ): (request: Request, context: RouteContext<P>) => Promise<Response> {
   return async (request, context) => {
     const auth = await authenticate(request.headers.get("authorization"));
-    if (!auth.ok) return jsonError(failureCode(auth), auth.error, auth.status);
+    if (!auth.ok) return apiError(auth.error, auth.status, auth.code);
     try {
       return await handler(request, auth.identity, context);
     } catch (error) {
       console.error("[api] handler error", error);
-      return jsonError("INTERNAL", "internal error", 500);
+      return apiError("internal error", 500);
     }
   };
 }

package/src/index.ts

@@ -1,8 +1,5 @@
 export {
-  type ApiAuth,
-  type AuthedHandler,
   type Authenticator,
-  type AuthFailure,
   type AuthResult,
   createApiAuth,
   type RouteContext,
@@ -11,20 +8,17 @@ export {
 export {
   type ApiErrorBody,
   type ApiErrorCode,
+  apiError,
   apiJson,
   apiText,
+  codeForStatus,
   jsonError,
-  type ParsedRequestJson,
   parseRequestJson,
   zodMessage,
 } from "./json";
 export {
   limitForOffset,
-  type Pagination,
-  type PaginationQuery,
-  type ParsedPagination,
   pageItems,
   pageLimitOnlyItems,
-  paginationQueryContract,
   parsePagination,
 } from "./pagination";

package/src/json.ts

@@ -31,6 +31,48 @@ export type ApiErrorBody = {
 
 const noStore = { "cache-control": "no-store" } as const;
 
+/**
+ * The default status → code map — the glue every consumer hand-rolled (vault's
+ * `codeForStatus`, rubrot's `authErrorCode`), reconciled into one place:
+ *
+ *   400 → BAD_REQUEST   401 → AUTH_INVALID   403 → SCOPE_MISSING
+ *   404 → NOT_FOUND     else → INTERNAL
+ *
+ * `AUTH_MISSING` is deliberately NOT here: a 401 defaults to `AUTH_INVALID`
+ * (a presented credential was bad/expired), and "no credential presented" is a
+ * distinction only the caller can draw — so it is consumer-emitted (pass a
+ * `code` explicitly), never inferred from status. `INTERNAL` is the fail-closed
+ * floor for anything unmapped — 5xx and unexpected codes alike.
+ */
+export function codeForStatus(status: number): ApiErrorCode {
+  switch (status) {
+    case 400:
+      return "BAD_REQUEST";
+    case 401:
+      return "AUTH_INVALID";
+    case 403:
+      return "SCOPE_MISSING";
+    case 404:
+      return "NOT_FOUND";
+    default:
+      return "INTERNAL";
+  }
+}
+
+/**
+ * The status-defaulted structured failure — vault's `apiError` and rubrot's
+ * `caughtApiError`, one function: `code` defaults via `codeForStatus(status)`,
+ * or pass it to override (e.g. `AUTH_MISSING`, `INVALID_JSON`). `jsonError` is
+ * the explicit-code primitive underneath.
+ */
+export function apiError(
+  message: string,
+  status: number,
+  code?: ApiErrorCode,
+): Response {
+  return jsonError(code ?? codeForStatus(status), message, status);
+}
+
 /** A non-cached JSON response — the canonical success shape. */
 export function apiJson(data: unknown, status = 200): Response {
   return Response.json(data, { status, headers: noStore });