@riligar/contract 1.0.1 → 2.0.0

package/package.json

@@ -1,9 +1,9 @@
 {
     "name": "@riligar/contract",
-    "version": "1.0.1",
+    "version": "2.0.0",
     "license": "MIT",
     "type": "module",
-    "description": "O contrato de API da stack RiLiGar: envelope \u00fanico, cat\u00e1logo de c\u00f3digos de erro e os helpers que tornam imposs\u00edvel responder fora dele.",
+    "description": "The API contract of the RiLiGar stack: a single envelope, a catalogue of error codes, and the helpers that make it impossible to answer outside it.",
     "main": "src/index.js",
     "files": [
         "src",

package/src/codes.js

@@ -1,74 +1,74 @@
 // ============================================================================
-// CÓDIGOS DE ERRO — o vocabulário fechado da stack
+// ERROR CODES — the stack's closed vocabulary
 // ============================================================================
 //
-// `code` é a parte do erro que o AGENTE lê. `message` é para o humano e pode
-// mudar de redação a qualquer momento; `code` não pode — renomear um código é
-// quebra de contrato, e por isso ele vive aqui, num enum fechado, e não solto
-// em cada handler.
+// `code` is the part of the error the AGENT reads. `message` is for the human
+// and its wording may change at any time; `code` may not — renaming a code is
+// a breaking change to the contract, and that is why it lives here, in a closed
+// enum, instead of loose in each handler.
 //
-// Este vocabulário não foi inventado: é a consolidação dos `reason` que já
-// existiam espalhados pelos sete produtos (`plan_limit`, `has_resources`,
-// `taken`, `expired`, `duplicate_name`, `no_access`…). A stack já havia
-// convergido sozinha — só não tinha escrito, e por isso cada produto grafava
-// o mesmo conceito de um jeito.
+// This vocabulary was not invented: it is the consolidation of the `reason`
+// values that already existed scattered across the seven products
+// (`plan_limit`, `has_resources`, `taken`, `expired`, `duplicate_name`,
+// `no_access`…). The stack had already converged on its own — it just had never
+// written it down, and so each product spelled the same concept its own way.
 //
-// Adicionar um código é mudança deliberada: entra aqui, não no handler.
+// Adding a code is a deliberate change: it goes here, not in the handler.
 
 export const CODES = {
-    // ── Identidade e acesso ──────────────────────────────────────────────
-    /** Sem credencial, ou credencial ilegível. O cliente não se identificou. */
+    // ── Identity and access ──────────────────────────────────────────────
+    /** No credential, or an unreadable one. The client did not identify itself. */
     UNAUTHORIZED: 'UNAUTHORIZED',
-    /** Identificado, mas sem permissão para ESTE recurso. */
+    /** Identified, but without permission for THIS resource. */
     FORBIDDEN: 'FORBIDDEN',
-    /** Token válido, emitido para OUTRO servidor (RFC 8707). */
+    /** Valid token, issued for ANOTHER server (RFC 8707). */
     WRONG_AUDIENCE: 'WRONG_AUDIENCE',
-    /** A credencial não cobre a operação — falta escopo, não permissão. */
+    /** The credential does not cover the operation — missing scope, not permission. */
     INSUFFICIENT_SCOPE: 'INSUFFICIENT_SCOPE',
 
-    // ── O recurso ────────────────────────────────────────────────────────
-    /** Não existe, ou não é visível para quem pergunta. */
+    // ── The resource ─────────────────────────────────────────────────────
+    /** Does not exist, or is not visible to whoever is asking. */
     NOT_FOUND: 'NOT_FOUND',
-    /** Já existe outro com a mesma chave natural (nome, slug, e-mail). */
+    /** Another one already exists with the same natural key (name, slug, e-mail). */
     CONFLICT: 'CONFLICT',
-    /** O nome pedido está tomado. É um CONFLICT com diagnóstico próprio. */
+    /** The requested name is taken. It is a CONFLICT with its own diagnosis. */
     NAME_TAKEN: 'NAME_TAKEN',
-    /** Existiu e não vale mais — versão de deploy, token, link de convite. */
+    /** It existed and no longer holds — deploy version, token, invite link. */
     EXPIRED: 'EXPIRED',
-    /** A remoção esbarra em dependentes que precisam sair antes. */
+    /** The removal runs into dependents that have to go first. */
     HAS_RESOURCES: 'HAS_RESOURCES',
 
-    // ── O pedido ─────────────────────────────────────────────────────────
-    /** Corpo, query ou path malformado. `details` carrega o que falhou. */
+    // ── The request ──────────────────────────────────────────────────────
+    /** Malformed body, query or path. `details` carries what failed. */
     VALIDATION_ERROR: 'VALIDATION_ERROR',
-    /** Sintaticamente válido, mas impossível no estado atual do recurso. */
+    /** Syntactically valid, but impossible in the resource's current state. */
     UNPROCESSABLE: 'UNPROCESSABLE',
-    /** Excedeu a janela de chamadas. `details.retryAfter` diz quando voltar. */
+    /** Exceeded the call window. `details.retryAfter` says when to come back. */
     RATE_LIMITED: 'RATE_LIMITED',
-    /** Corpo maior que o teto aceito. */
+    /** Body larger than the accepted ceiling. */
     PAYLOAD_TOO_LARGE: 'PAYLOAD_TOO_LARGE',
 
-    // ── Comercial ────────────────────────────────────────────────────────
-    /** O plano atual não comporta. `details` traz current/limit/requiredPlan. */
+    // ── Commercial ───────────────────────────────────────────────────────
+    /** The current plan does not cover it. `details` brings current/limit/requiredPlan. */
     PLAN_LIMIT: 'PLAN_LIMIT',
-    /** A assinatura do dono não está ativa. Bloqueia a operação inteira. */
+    /** The owner's subscription is not active. Blocks the whole operation. */
     SUBSCRIPTION_REQUIRED: 'SUBSCRIPTION_REQUIRED',
 
-    // ── Nós ──────────────────────────────────────────────────────────────
-    /** Falha inesperada. NUNCA carrega mensagem de exceção interna. */
+    // ── Us ───────────────────────────────────────────────────────────────
+    /** Unexpected failure. NEVER carries an internal exception message. */
     INTERNAL_ERROR: 'INTERNAL_ERROR',
-    /** Dependência externa fora do ar. É transitório — vale repetir. */
+    /** External dependency down. It is transient — worth retrying. */
     SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
-    /** Um provedor de terceiros recusou (gateway, SES, Cloudflare). */
+    /** A third-party provider refused (gateway, SES, Cloudflare). */
     UPSTREAM_ERROR: 'UPSTREAM_ERROR',
 }
 
 /**
- * O status HTTP de cada código.
+ * The HTTP status of each code.
  *
- * A tabela vive aqui para que status e código NUNCA discordem: um `NOT_FOUND`
- * com 200 é o defeito que esta migração existe para eliminar, e a única forma
- * de garantir isso é o chamador não escolher o número.
+ * The table lives here so that status and code NEVER disagree: a `NOT_FOUND`
+ * with a 200 is the defect this migration exists to eliminate, and the only way
+ * to guarantee that is for the caller not to pick the number.
  */
 export const STATUS_BY_CODE = {
     UNAUTHORIZED: 401,
@@ -95,43 +95,45 @@ export const STATUS_BY_CODE = {
     UPSTREAM_ERROR: 502,
 }
 
-/** Um erro transitório merece nova tentativa; os outros, não. */
+/** A transient error deserves a retry; the others do not. */
 export const RETRIABLE = new Set([CODES.RATE_LIMITED, CODES.SERVICE_UNAVAILABLE, CODES.UPSTREAM_ERROR])
 
 /**
- * Os `reason` antigos, e o código que cada um virou.
+ * The old `reason` values, and the code each one became.
  *
- * POR QUE ISTO EXISTE, E POR QUE NÃO É DÍVIDA
+ * WHY THIS EXISTS, AND WHY IT IS NOT DEBT
  *
- * Antes deste pacote, cada produto tinha seu vocabulário de `reason` em
- * snake_case: `invalid_request`, `plan_limit`, `not_found`. São centenas de
- * chamadas espalhadas — só no Auth são 54. Trocá-las todas de uma vez seria
- * uma refatoração ampla, com risco real e zero ganho visível: o que o cliente
- * da API lê é o `code` da RESPOSTA, e ele já sai correto.
+ * Before this package, each product had its own vocabulary of `reason` values
+ * in snake_case: `invalid_request`, `plan_limit`, `not_found`. There are
+ * hundreds of calls scattered around — in Auth alone there are 54. Swapping
+ * them all at once would be a sweeping refactor, with real risk and zero
+ * visible gain: what the API client reads is the `code` of the RESPONSE, and
+ * that already comes out correct.
  *
- * A tradução acontece na borda, uma vez, aqui. `falha('invalid_request')`
- * emite `VALIDATION_ERROR` — o handler continua legível na língua que já
- * falava, e a resposta cumpre o contrato.
+ * The translation happens at the edge, once, here. `failure('invalid_request')`
+ * emits `VALIDATION_ERROR` — the handler stays readable in the language it
+ * already spoke, and the response honours the contract.
  *
- * O QUE ISTO NÃO É
+ * WHAT THIS IS NOT
  *
- * Não é um segundo vocabulário. Nada aqui é código válido de saída: o mapa só
- * traduz PARA `CODES`, nunca a partir dele. Código novo escreve
- * `CODES.VALIDATION_ERROR` direto; esta tabela só cobre o que já existia.
+ * It is not a second vocabulary. Nothing here is a valid output code: the map
+ * only translates INTO `CODES`, never out of it. New code writes
+ * `CODES.VALIDATION_ERROR` directly; this table only covers what already
+ * existed.
  *
- * O mapa é fechado de propósito. Um `reason` que não estiver aqui cai em
- * `INTERNAL_ERROR` — barulhento, e é o certo: código desconhecido é bug de
- * quem chamou, não algo para adivinhar.
+ * The map is closed on purpose. A `reason` that is not here falls into
+ * `INTERNAL_ERROR` — loud, and that is the right call: an unknown code is a bug
+ * in whoever called, not something to guess at.
  */
 export const ALIASES = {
-    // ── Validação ────────────────────────────────────────────────────────
+    // ── Validation ───────────────────────────────────────────────────────
     validation_error: CODES.VALIDATION_ERROR,
     invalid_request: CODES.VALIDATION_ERROR,
     invalid_email: CODES.VALIDATION_ERROR,
     bad_request: CODES.VALIDATION_ERROR,
     missing_field: CODES.VALIDATION_ERROR,
 
-    // ── Identidade e acesso ──────────────────────────────────────────────
+    // ── Identity and access ──────────────────────────────────────────────
     unauthorized: CODES.UNAUTHORIZED,
     forbidden: CODES.FORBIDDEN,
     access_denied: CODES.FORBIDDEN,
@@ -140,7 +142,7 @@ export const ALIASES = {
     wrong_audience: CODES.WRONG_AUDIENCE,
     insufficient_scope: CODES.INSUFFICIENT_SCOPE,
 
-    // ── Recurso ──────────────────────────────────────────────────────────
+    // ── Resource ─────────────────────────────────────────────────────────
     not_found: CODES.NOT_FOUND,
     conflict: CODES.CONFLICT,
     taken: CODES.NAME_TAKEN,
@@ -151,24 +153,24 @@ export const ALIASES = {
     has_resources: CODES.HAS_RESOURCES,
     organization_not_empty: CODES.HAS_RESOURCES,
 
-    // ── Não processável ──────────────────────────────────────────────────
+    // ── Unprocessable ────────────────────────────────────────────────────
     unprocessable: CODES.UNPROCESSABLE,
     no_op: CODES.UNPROCESSABLE,
     last_owner: CODES.UNPROCESSABLE,
-    // RFC 8628: o device flow espera o humano digitar o código. Não é erro de
-    // cliente nem falha do servidor — é "ainda não".
+    // RFC 8628: the device flow waits for the human to type the code. It is
+    // neither a client error nor a server failure — it is "not yet".
     authorization_pending: CODES.UNPROCESSABLE,
 
-    // ── Plano e cobrança ─────────────────────────────────────────────────
+    // ── Plan and billing ─────────────────────────────────────────────────
     plan_limit: CODES.PLAN_LIMIT,
     subscription_required: CODES.SUBSCRIPTION_REQUIRED,
 
-    // ── Ritmo e tamanho ──────────────────────────────────────────────────
+    // ── Pace and size ────────────────────────────────────────────────────
     rate_limited: CODES.RATE_LIMITED,
     slow_down: CODES.RATE_LIMITED,
     payload_too_large: CODES.PAYLOAD_TOO_LARGE,
 
-    // ── Falha nossa ou de terceiro ───────────────────────────────────────
+    // ── Our failure, or a third party's ──────────────────────────────────
     server_error: CODES.INTERNAL_ERROR,
     internal_error: CODES.INTERNAL_ERROR,
     service_unavailable: CODES.SERVICE_UNAVAILABLE,
@@ -176,22 +178,23 @@ export const ALIASES = {
     email_delivery_failed: CODES.UPSTREAM_ERROR,
 }
 
-export const isCode = valor => Object.prototype.hasOwnProperty.call(STATUS_BY_CODE, valor)
+export const isCode = value => Object.prototype.hasOwnProperty.call(STATUS_BY_CODE, value)
 
 /**
- * O código canônico a partir do que o handler escreveu.
+ * The canonical code, derived from whatever the handler wrote.
  *
- * Aceita o código já canônico (passa direto), um `reason` antigo (traduz), ou
- * qualquer outra coisa (`INTERNAL_ERROR`). É o único ponto da stack que decide
- * isso — antes, cada produto tinha a sua tabela, e elas divergiam.
+ * Accepts the already canonical code (passes straight through), an old `reason`
+ * (translates it), or anything else (`INTERNAL_ERROR`). It is the only point in
+ * the stack that decides this — before, each product had its own table, and they
+ * diverged.
  */
-export const toCode = valor => (isCode(valor) ? valor : ALIASES[valor] || CODES.INTERNAL_ERROR)
+export const toCode = value => (isCode(value) ? value : ALIASES[value] || CODES.INTERNAL_ERROR)
 
 /**
- * O código a partir de um status HTTP.
+ * The code, derived from an HTTP status.
  *
- * Para os pontos que já tinham o número na mão — um `throw { status: 401 }`
- * pego num catch, por exemplo — e não têm de onde tirar o código.
+ * For the places that already had the number at hand — a `throw { status: 401 }`
+ * caught in a catch, for example — and have nowhere to get the code from.
  */
 export const STATUS_TO_CODE = {
     400: CODES.VALIDATION_ERROR,

package/src/index.js

@@ -1,25 +1,25 @@
 // ============================================================================
-// @riligar/contract — o contrato de API dos sete produtos
+// @riligar/contract — the API contract of the seven products
 // ============================================================================
 //
-// A norma escrita vive em `website/docs/2026-09-09-api-contract.md`. Este
-// pacote é a norma EXECUTÁVEL: o que os produtos importam para responder, e o
-// que os testes importam para conferir.
+// The written norm lives in `website/docs/2026-09-09-api-contract.md`. This
+// package is the EXECUTABLE norm: what the products import in order to respond,
+// and what the tests import in order to check.
 //
-// A regra de ouro é a que este pacote torna mecânica: **um agente que aprendeu
-// um produto da RiLiGar já sabe usar os outros seis.**
+// The golden rule is the one this package makes mechanical: **an agent that has
+// learned one RiLiGar product already knows how to use the other six.**
 //
-// POR QUE OS SCHEMAS NÃO SAEM DAQUI
+// WHY THE SCHEMAS DO NOT COME OUT OF HERE
 //
-// `schemas.js` importa Zod, que é peer OPCIONAL — um worker que só precisa
-// responder não deve carregar um validador de 60 kB. Mas enquanto este arquivo
-// reexportava os schemas, o import era eager: `import { falha } from
-// '@riligar/contract'` puxava `schemas.js`, que puxava Zod, e a instalação
-// quebrava com "Cannot find package 'zod'" em quem seguiu a peer como
-// opcional. O peer opcional não era opcional.
+// `schemas.js` imports Zod, which is an OPTIONAL peer — a worker that only needs
+// to respond should not have to load a 60 kB validator. But as long as this file
+// reexported the schemas, the import was eager: `import { failure } from
+// '@riligar/contract'` pulled in `schemas.js`, which pulled in Zod, and the
+// install broke with "Cannot find package 'zod'" for anyone who treated the peer
+// as optional. The optional peer was not optional.
 //
-// Quem quer os schemas importa `@riligar/contract/schemas`, e aí Zod é
-// requisito legítimo daquele caminho — declarado no export map, não escondido
-// numa cadeia de reexports.
+// Whoever wants the schemas imports `@riligar/contract/schemas`, and there Zod
+// is a legitimate requirement of that path — declared in the export map, not
+// hidden in a chain of reexports.
 export { CODES, STATUS_BY_CODE, RETRIABLE, isCode, toCode, codeFromStatus, ALIASES } from './codes.js'
-export { ok, criado, colecao, falha, falhaComStatus, corpoDeFalha, paginacao } from './respostas.js'
+export { ok, created, collection, failure, failureWithStatus, failureBody, pagination, page } from './responses.js'

package/src/responses.js

@@ -0,0 +1,189 @@
+// ============================================================================
+// RESPONSES — the only way out of the server
+// ============================================================================
+//
+// Four functions. If a handler in any of the seven products builds a
+// `Response` by hand, it has stepped outside the contract.
+//
+// The point of this file is not to save typing — it is to make the defect
+// IMPOSSIBLE. `failure()` derives the status from the code: there is no
+// signature that lets you return `NOT_FOUND` with a 200. That discordant pair
+// was exactly what made an agent read 200, conclude success, and carry on with
+// data that did not exist.
+import { CODES, STATUS_BY_CODE, RETRIABLE, isCode, toCode, codeFromStatus } from './codes.js'
+
+const JSON_HEADERS = { 'content-type': 'application/json; charset=utf-8' }
+
+const respond = (body, status, headers) => new Response(JSON.stringify(body), { status, headers: { ...JSON_HEADERS, ...headers } })
+
+/**
+ * One resource, at the root.
+ *
+ *   ok({ id: 'mon_a1', name: 'checkout' })
+ *   → 200 {"id":"mon_a1","name":"checkout"}
+ *
+ * No `data`, no `success`, no `message`. The HTTP status already said it went
+ * well; repeating that in the body is noise the agent has to learn to ignore —
+ * once per product.
+ */
+export const ok = (resource, { status = 200, headers } = {}) => respond(resource, status, headers)
+
+/**
+ * A resource that has just been BORN.
+ *
+ * 201 is the creation signal, and nothing else. An upsert that updated returns
+ * `ok()`; the one that created returns `created()`. That is what lets the agent
+ * know whether its own call was the one that created — without having to
+ * compare timestamps.
+ */
+export const created = (resource, { headers } = {}) => respond(resource, 201, headers)
+
+/**
+ * A collection, always in the same shape.
+ *
+ *   collection([a, b], { limit: 50, offset: 0, total: 128 })
+ *   → {"items":[…],"page":{"limit":50,"offset":0,"total":128,"hasMore":true}}
+ *
+ * `items` is always an array — empty is a legitimate response and has the SAME
+ * shape as a full one. Pruning the empty list (which Payments used to do) broke
+ * on the very first client, because every test environment has seeded data.
+ *
+ * `hasMore` is explicit on purpose: the consumer should not have to compare
+ * `offset + limit` against `total` to know whether to keep paginating.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * `total: null` WHEN NOBODY COUNTED — and that is the whole point of this helper.
+ *
+ * Until 09/10 the defaults filled `page` from the array itself: a route that
+ * NEVER paginated returned `{limit: N, offset: 0, total: N, hasMore: false}`,
+ * byte for byte identical to a route that paginated and reached the end. Of the
+ * stack's 39 collection routes, 29 did not paginate and all 29 asserted
+ * `hasMore: false` — the very field that exists so the agent need not deduce
+ * was deducing wrong in 87% of cases.
+ *
+ * Now: whoever does not pass `total` gets `total: null` and `hasMore: null`.
+ * Null means "I don't know", and that differs from zero and from false. An
+ * agent reading `total: null` knows it must ask another way; one reading
+ * `hasMore: false` stops paginating — and those two conclusions must not come
+ * out of the same response.
+ *
+ * Whoever truly paginates passes `total` and gets `hasMore` computed. Whoever
+ * returns the whole list on purpose passes `total: items.length`, and then
+ * `hasMore: false` is an assertion, not a default.
+ */
+export const collection = (list, page = {}, { status = 200, headers } = {}) => {
+    const items = Array.isArray(list) ? list : []
+    const limit = page.limit ?? items.length
+    const offset = page.offset ?? 0
+
+    // `null` only when NOBODY counted. `total: 0` is a legitimate count.
+    const total = page.total ?? null
+    const hasMore = page.hasMore ?? (total === null ? null : offset + items.length < total)
+
+    /*
+     * `extra` goes at the ROOT, not inside `page`. Hoster's `activeDeployId`
+     * and Monitors' `counts` are context about the SET, not about pagination —
+     * inside `page` they would claim to be pagination, and a generic client
+     * reading `page` to paginate would trip over them.
+     */
+    return respond({ items, page: { limit, offset, total, hasMore }, ...(page.extra ?? {}) }, status, headers)
+}
+
+/**
+ * A failure. The status comes from the CODE — the caller does not pick the number.
+ *
+ *   failure(CODES.NOT_FOUND, 'Project not found.')
+ *   → 404 {"error":{"code":"NOT_FOUND","message":"Project not found."}}
+ *
+ * `details` is for what the agent can ACT on: the limit that was exceeded, the
+ * field that was missing, how many seconds to wait. Never for a stack trace.
+ *
+ * An unknown code becomes INTERNAL_ERROR rather than a silent 500 with a
+ * malformed body: if someone wrote a code outside the enum, the bug is ours,
+ * and the response to the client stays well formed.
+ */
+export const failure = (code, message, { details, headers, status } = {}) => {
+    const resolved = toCode(code)
+    const body = { error: { code: resolved, message: String(message ?? '') } }
+
+    if (details && Object.keys(details).length) body.error.details = details
+    if (RETRIABLE.has(resolved)) body.error.retriable = true
+
+    return respond(body, status ?? STATUS_BY_CODE[resolved], headers)
+}
+
+/**
+ * The error body, without the `Response` around it.
+ *
+ * For whoever answers through a framework that assembles the response itself —
+ * the Elysia of Storage and Functions, where the handler returns an object and
+ * the status travels via `set.status`. Returns `{ body, status }` so the two go
+ * together and there is no way to forget one.
+ */
+export const failureBody = (code, message, details) => {
+    const resolved = toCode(code)
+    const error = { code: resolved, message: String(message ?? '') }
+
+    if (details && Object.keys(details).length) error.details = details
+    if (RETRIABLE.has(resolved)) error.retriable = true
+
+    return { body: { error }, status: STATUS_BY_CODE[resolved] }
+}
+
+/**
+ * Reads `limit`/`offset` from a URL, with a ceiling.
+ *
+ * A `limit` with no ceiling is a way to take the service down with one query; a
+ * ceiling with no `offset` is what made record 101 of Messages unreachable. The
+ * two travel together.
+ */
+export const pagination = (url, { defaultLimit = 50, maxLimit = 200 } = {}) => {
+    const p = url instanceof URL ? url.searchParams : new URL(url, 'http://x').searchParams
+    const rawLimit = Number(p.get('limit'))
+    const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(Math.floor(rawLimit), maxLimit) : defaultLimit
+    const rawOffset = Number(p.get('offset'))
+    const offset = Number.isFinite(rawOffset) && rawOffset > 0 ? Math.floor(rawOffset) : 0
+    return { limit, offset }
+}
+
+/**
+ * The page of a paginated query, ready for `collection`.
+ *
+ * It exists to make MECHANICAL what the stack got wrong by hand on two fronts:
+ *
+ * 1. **The reported `limit` must be the APPLIED one.** Two routes clamped in
+ *    the data layer and reported the raw query value: with `?limit=5000` they
+ *    returned 200 rows and said `page:{limit:5000, hasMore:false}`. The client
+ *    concludes "I asked for 5000, got 200, therefore it's over" — and stops
+ *    paginating halfway.
+ *
+ * 2. **`total` comes from whoever counted.** Passing `total` is mandatory here,
+ *    because `collection` on its own has no way to tell whether nobody counted
+ *    or the count happened to equal the array length.
+ *
+ *   const { limit, offset } = pagination(url)
+ *   const rows = await fetchRows(limit, offset)
+ *   const [{ total }] = await count()
+ *   return collection(rows, page({ limit, offset, total }))
+ */
+export const page = ({ limit, offset = 0, total, extra }) => {
+    if (!Number.isFinite(total)) {
+        throw new TypeError('page() requires a numeric `total` — use collection(items) directly when nobody counted.')
+    }
+    return { limit, offset, total, extra }
+}
+
+/**
+ * A failure for which only the HTTP status is known.
+ *
+ * For the global error handler, where a `throw { status, message }` arrives
+ * from any layer and there is no code at hand. It derives the `code` from the
+ * number instead of always falling into `INTERNAL_ERROR` — a 401 that turns
+ * into a 500 at the edge hides the real problem from whoever is debugging.
+ *
+ * `status` is preserved: whoever already had the number keeps it, even when the
+ * canonical code maps to another (401 for `UNAUTHORIZED`, 402 for `PLAN_LIMIT`).
+ */
+export const failureWithStatus = (status, message, details, headers) => failure(codeFromStatus(status), message, { details, headers, status })
+
+export { CODES, STATUS_BY_CODE }

package/src/schemas.js

@@ -1,18 +1,18 @@
 // ============================================================================
-// SCHEMAS — o contrato como coisa executável
+// SCHEMAS — the contract as an executable thing
 // ============================================================================
 //
-// As mesmas regras de `respostas.js`, do lado de quem LÊ. Servem para o teste
-// de contrato afirmar a forma sem reimplementar a asserção em cada suíte, e
-// para um consumidor validar o que recebeu.
+// The same rules as `responses.js`, from the READER's side. They let the
+// contract test assert the shape without reimplementing the assertion in every
+// suite, and let a consumer validate what it received.
 //
-// Zod é peer: os sete produtos já o têm (v4), e embutir uma segunda cópia num
-// worker significa pagar o bundle duas vezes.
+// Zod is a peer: the seven products already have it (v4), and embedding a
+// second copy in a worker means paying the bundle cost twice.
 import { z } from 'zod'
 
 import { STATUS_BY_CODE } from './codes.js'
 
-/** O código é o enum fechado — nada de string livre. */
+/** The code is the closed enum — no free-form strings. */
 export const codeSchema = z.enum(Object.keys(STATUS_BY_CODE))
 
 export const errorSchema = z.object({
@@ -39,42 +39,43 @@ export const collectionSchema = item =>
     })
 
 /**
- * O recurso vai na raiz, então não há envelope a validar — o que se pode
- * afirmar é o que ele NÃO pode ser.
+ * The resource goes at the root, so there is no envelope to validate — what can
+ * be asserted is what it must NOT be.
  *
- * As três chaves proibidas são exatamente os envelopes que a stack usava. Um
- * recurso que ainda tenha `data`, `success` ou `message` no topo é um produto
- * que não migrou — e o teste de contrato precisa dizer isso com todas as
- * letras, em vez de passar porque "veio um objeto".
+ * The three forbidden keys are exactly the envelopes the stack used to use. A
+ * resource that still carries `data`, `success` or `message` at the top is a
+ * product that has not migrated — and the contract test must say so in plain
+ * words, instead of passing because "an object came back".
  */
-export const resourceSchema = corpo =>
-    (corpo ?? z.object({}).loose()).refine(v => !v || typeof v !== 'object' || (!('data' in v) && !('success' in v) && !('message' in v)), {
-        message: 'recurso não pode vir envelopado em `data`, `success` ou `message`',
+export const resourceSchema = body =>
+    (body ?? z.object({}).loose()).refine(v => !v || typeof v !== 'object' || (!('data' in v) && !('success' in v) && !('message' in v)), {
+        message: 'a resource must not be wrapped in `data`, `success` or `message`',
     })
 
 const CAMEL = /^[a-z][a-zA-Z0-9]*$/
 
 /**
- * Toda chave do corpo é camelCase, em qualquer profundidade.
+ * Every key in the body is camelCase, at any depth.
  *
- * O Storage devolvia `tenant_id` no corpo e `tenantId` no path da MESMA rota.
- * Um consumidor precisava saber, campo a campo, qual vocabulário usar.
+ * Storage used to return `tenant_id` in the body and `tenantId` in the path of
+ * the SAME route. A consumer had to know, field by field, which vocabulary to
+ * use.
  *
- * Chaves que são DADO do usuário (o nome de uma coleção, de uma variável de
- * ambiente, de um cabeçalho) não seguem a regra — não são contrato nosso.
- * Por isso `ignorar`.
+ * Keys that are user DATA (the name of a collection, of an environment
+ * variable, of a header) do not follow the rule — they are not our contract.
+ * Hence `ignore`.
  */
-export const chavesCamelCase = (valor, { ignorar = [] } = {}, caminho = '') => {
-    const fora = []
-    const anda = (v, path) => {
-        if (Array.isArray(v)) return v.forEach((x, i) => anda(x, `${path}[${i}]`))
+export const camelCaseKeys = (value, { ignore = [] } = {}, path = '') => {
+    const offenders = []
+    const walk = (v, path) => {
+        if (Array.isArray(v)) return v.forEach((x, i) => walk(x, `${path}[${i}]`))
         if (!v || typeof v !== 'object') return
         for (const [k, sub] of Object.entries(v)) {
-            const aqui = path ? `${path}.${k}` : k
-            if (!ignorar.includes(k) && !CAMEL.test(k)) fora.push(aqui)
-            anda(sub, aqui)
+            const here = path ? `${path}.${k}` : k
+            if (!ignore.includes(k) && !CAMEL.test(k)) offenders.push(here)
+            walk(sub, here)
         }
     }
-    anda(valor, caminho)
-    return fora
+    walk(value, path)
+    return offenders
 }

package/src/respostas.js

@@ -1,135 +0,0 @@
-// ============================================================================
-// RESPOSTAS — a única forma de sair do servidor
-// ============================================================================
-//
-// Quatro funções. Se um handler dos sete produtos constrói `Response` na mão,
-// é porque saiu do contrato.
-//
-// O ponto do arquivo não é economizar digitação — é tornar o defeito
-// IMPOSSÍVEL. `falha()` deriva o status do código: não existe assinatura que
-// permita devolver `NOT_FOUND` com 200. Era exatamente esse par discordante
-// que fazia o agente ler 200, concluir sucesso e seguir com dado inexistente.
-import { CODES, STATUS_BY_CODE, RETRIABLE, isCode, toCode, codeFromStatus } from './codes.js'
-
-const JSON_HEADERS = { 'content-type': 'application/json; charset=utf-8' }
-
-const responder = (corpo, status, headers) => new Response(JSON.stringify(corpo), { status, headers: { ...JSON_HEADERS, ...headers } })
-
-/**
- * Um recurso, na raiz.
- *
- *   ok({ id: 'mon_a1', name: 'checkout' })
- *   → 200 {"id":"mon_a1","name":"checkout"}
- *
- * Sem `data`, sem `success`, sem `message`. O status HTTP já disse que deu
- * certo; repetir isso no corpo é ruído que o agente precisa aprender a
- * ignorar — por produto.
- */
-export const ok = (recurso, { status = 200, headers } = {}) => responder(recurso, status, headers)
-
-/**
- * Um recurso que acabou de NASCER.
- *
- * 201 é o sinal de criação, e só. Um upsert que atualizou devolve `ok()`;
- * quem criou devolve `criado()`. É o que permite ao agente saber se a
- * chamada dele foi a que criou — sem precisar comparar timestamps.
- */
-export const criado = (recurso, { headers } = {}) => responder(recurso, 201, headers)
-
-/**
- * Uma coleção, sempre com a mesma forma.
- *
- *   colecao([a, b], { limit: 50, offset: 0, total: 128 })
- *   → {"items":[…],"page":{"limit":50,"offset":0,"total":128,"hasMore":true}}
- *
- * `items` é sempre um array — vazio é uma resposta legítima e tem a MESMA
- * forma da cheia. A poda de lista vazia (que o Payments fazia) quebrava só no
- * primeiro cliente, porque todo ambiente de teste tem dado semeado.
- *
- * `hasMore` é explícito de propósito: o consumidor não deveria precisar
- * comparar `offset + limit` com `total` para saber se continua paginando.
- * Quando `total` não é conhecido (contar custaria uma query a mais em coisa
- * que ninguém pagina), `hasMore` sai do tamanho da página cheia.
- */
-export const colecao = (itens, pagina = {}, { status = 200, headers } = {}) => {
-    const items = Array.isArray(itens) ? itens : []
-    const limit = pagina.limit ?? items.length
-    const offset = pagina.offset ?? 0
-    const total = pagina.total ?? offset + items.length
-    const hasMore = pagina.hasMore ?? offset + items.length < total
-
-    return responder({ items, page: { limit, offset, total, hasMore } }, status, headers)
-}
-
-/**
- * Uma falha. O status vem do CÓDIGO — quem chama não escolhe o número.
- *
- *   falha(CODES.NOT_FOUND, 'Projeto não encontrado.')
- *   → 404 {"error":{"code":"NOT_FOUND","message":"Projeto não encontrado."}}
- *
- * `details` é para o que o agente pode AGIR: o limite que estourou, o campo
- * que faltou, quantos segundos esperar. Nunca para stack trace.
- *
- * Um código desconhecido vira INTERNAL_ERROR em vez de 500 silencioso com
- * corpo torto: se alguém escreveu um código fora do enum, o bug é nosso, e a
- * resposta ao cliente continua bem formada.
- */
-export const falha = (code, message, { details, headers, status } = {}) => {
-    const codigo = toCode(code)
-    const corpo = { error: { code: codigo, message: String(message ?? '') } }
-
-    if (details && Object.keys(details).length) corpo.error.details = details
-    if (RETRIABLE.has(codigo)) corpo.error.retriable = true
-
-    return responder(corpo, status ?? STATUS_BY_CODE[codigo], headers)
-}
-
-/**
- * O corpo do erro, sem a `Response` em volta.
- *
- * Para quem responde por um framework que monta a resposta sozinho — o Elysia
- * do Storage e do Functions, onde o handler devolve objeto e o status vai por
- * `set.status`. Devolve `{ corpo, status }` para os dois irem juntos e não
- * haver como esquecer um.
- */
-export const corpoDeFalha = (code, message, details) => {
-    const codigo = toCode(code)
-    const error = { code: codigo, message: String(message ?? '') }
-
-    if (details && Object.keys(details).length) error.details = details
-    if (RETRIABLE.has(codigo)) error.retriable = true
-
-    return { corpo: { error }, status: STATUS_BY_CODE[codigo] }
-}
-
-/**
- * Lê `limit`/`offset` de uma URL, com teto.
- *
- * Um `limit` sem teto é um jeito de derrubar o serviço com uma query; um teto
- * sem `offset` é o que tornava o registro 101 do Messages inalcançável. Os
- * dois andam juntos.
- */
-export const paginacao = (url, { limitPadrao = 50, limitMaximo = 200 } = {}) => {
-    const p = url instanceof URL ? url.searchParams : new URL(url, 'http://x').searchParams
-    const bruto = Number(p.get('limit'))
-    const limit = Number.isFinite(bruto) && bruto > 0 ? Math.min(Math.floor(bruto), limitMaximo) : limitPadrao
-    const off = Number(p.get('offset'))
-    const offset = Number.isFinite(off) && off > 0 ? Math.floor(off) : 0
-    return { limit, offset }
-}
-
-/**
- * Uma falha de que só se sabe o status HTTP.
- *
- * Para o handler global de erro, onde chega um `throw { status, message }` de
- * qualquer camada e não há código na mão. Deriva o `code` do número em vez de
- * cair sempre em `INTERNAL_ERROR` — um 401 que vira 500 na borda esconde o
- * problema real de quem depura.
- *
- * `status` é preservado: quem já tinha o número continua com ele, mesmo quando
- * o código canônico mapeia para outro (401 de `UNAUTHORIZED`, 402 de
- * `PLAN_LIMIT`).
- */
-export const falhaComStatus = (status, message, details, headers) => falha(codeFromStatus(status), message, { details, headers, status })
-
-export { CODES, STATUS_BY_CODE }