@riligar/contract 1.0.0

package/package.json

@@ -0,0 +1,28 @@
+{
+    "name": "@riligar/contract",
+    "version": "1.0.0",
+    "license": "MIT",
+    "type": "module",
+    "description": "O contrato de API da stack RiLiGar: envelope único, catálogo de códigos de erro e os helpers que tornam impossível responder fora dele.",
+    "main": "src/index.js",
+    "files": ["src", "README.md"],
+    "exports": {
+        ".": "./src/index.js",
+        "./codes": "./src/codes.js",
+        "./schemas": "./src/schemas.js"
+    },
+    "scripts": {
+        "test": "bun test tests/",
+        "release": "semantic-release"
+    },
+    "peerDependencies": { "zod": "^4.0.0" },
+    "peerDependenciesMeta": { "zod": { "optional": true } },
+    "devDependencies": {
+        "zod": "^4.5.4",
+        "semantic-release": "^24.0.0",
+        "@semantic-release/changelog": "^6.0.3",
+        "@semantic-release/git": "^10.0.1"
+    },
+    "publishConfig": { "access": "public" },
+    "repository": { "type": "git", "url": "git+https://github.com/riligar-applications/contract.git" }
+}

package/src/codes.js

@@ -0,0 +1,212 @@
+// ============================================================================
+// CÓDIGOS DE ERRO — o vocabulário fechado da stack
+// ============================================================================
+//
+// `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.
+//
+// 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.
+//
+// Adicionar um código é mudança deliberada: entra aqui, não no handler.
+
+export const CODES = {
+    // ── Identidade e acesso ──────────────────────────────────────────────
+    /** Sem credencial, ou credencial ilegível. O cliente não se identificou. */
+    UNAUTHORIZED: 'UNAUTHORIZED',
+    /** Identificado, mas sem permissão para ESTE recurso. */
+    FORBIDDEN: 'FORBIDDEN',
+    /** Token válido, emitido para OUTRO servidor (RFC 8707). */
+    WRONG_AUDIENCE: 'WRONG_AUDIENCE',
+    /** A credencial não cobre a operação — falta escopo, não permissão. */
+    INSUFFICIENT_SCOPE: 'INSUFFICIENT_SCOPE',
+
+    // ── O recurso ────────────────────────────────────────────────────────
+    /** Não existe, ou não é visível para quem pergunta. */
+    NOT_FOUND: 'NOT_FOUND',
+    /** Já existe outro com a mesma chave natural (nome, slug, e-mail). */
+    CONFLICT: 'CONFLICT',
+    /** O nome pedido está tomado. É um CONFLICT com diagnóstico próprio. */
+    NAME_TAKEN: 'NAME_TAKEN',
+    /** Existiu e não vale mais — versão de deploy, token, link de convite. */
+    EXPIRED: 'EXPIRED',
+    /** A remoção esbarra em dependentes que precisam sair antes. */
+    HAS_RESOURCES: 'HAS_RESOURCES',
+
+    // ── O pedido ─────────────────────────────────────────────────────────
+    /** Corpo, query ou path malformado. `details` carrega o que falhou. */
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    /** Sintaticamente válido, mas impossível no estado atual do recurso. */
+    UNPROCESSABLE: 'UNPROCESSABLE',
+    /** Excedeu a janela de chamadas. `details.retryAfter` diz quando voltar. */
+    RATE_LIMITED: 'RATE_LIMITED',
+    /** Corpo maior que o teto aceito. */
+    PAYLOAD_TOO_LARGE: 'PAYLOAD_TOO_LARGE',
+
+    // ── Comercial ────────────────────────────────────────────────────────
+    /** O plano atual não comporta. `details` traz current/limit/requiredPlan. */
+    PLAN_LIMIT: 'PLAN_LIMIT',
+    /** A assinatura do dono não está ativa. Bloqueia a operação inteira. */
+    SUBSCRIPTION_REQUIRED: 'SUBSCRIPTION_REQUIRED',
+
+    // ── Nós ──────────────────────────────────────────────────────────────
+    /** Falha inesperada. NUNCA carrega mensagem de exceção interna. */
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    /** Dependência externa fora do ar. É transitório — vale repetir. */
+    SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+    /** Um provedor de terceiros recusou (gateway, SES, Cloudflare). */
+    UPSTREAM_ERROR: 'UPSTREAM_ERROR',
+}
+
+/**
+ * O status HTTP de cada código.
+ *
+ * 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.
+ */
+export const STATUS_BY_CODE = {
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    WRONG_AUDIENCE: 401,
+    INSUFFICIENT_SCOPE: 403,
+
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    NAME_TAKEN: 409,
+    EXPIRED: 410,
+    HAS_RESOURCES: 409,
+
+    VALIDATION_ERROR: 400,
+    UNPROCESSABLE: 422,
+    RATE_LIMITED: 429,
+    PAYLOAD_TOO_LARGE: 413,
+
+    PLAN_LIMIT: 402,
+    SUBSCRIPTION_REQUIRED: 402,
+
+    INTERNAL_ERROR: 500,
+    SERVICE_UNAVAILABLE: 503,
+    UPSTREAM_ERROR: 502,
+}
+
+/** Um erro transitório merece nova tentativa; os outros, não. */
+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.
+ *
+ * POR QUE ISTO EXISTE, E POR QUE NÃO É DÍVIDA
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * O QUE ISTO NÃO É
+ *
+ * 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.
+ *
+ * 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.
+ */
+export const ALIASES = {
+    // ── Validação ────────────────────────────────────────────────────────
+    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 ──────────────────────────────────────────────
+    unauthorized: CODES.UNAUTHORIZED,
+    forbidden: CODES.FORBIDDEN,
+    access_denied: CODES.FORBIDDEN,
+    no_access: CODES.FORBIDDEN,
+    application_mismatch: CODES.FORBIDDEN,
+    wrong_audience: CODES.WRONG_AUDIENCE,
+    insufficient_scope: CODES.INSUFFICIENT_SCOPE,
+
+    // ── Recurso ──────────────────────────────────────────────────────────
+    not_found: CODES.NOT_FOUND,
+    conflict: CODES.CONFLICT,
+    taken: CODES.NAME_TAKEN,
+    name_taken: CODES.NAME_TAKEN,
+    duplicate_name: CODES.NAME_TAKEN,
+    expired: CODES.EXPIRED,
+    expired_token: CODES.EXPIRED,
+    has_resources: CODES.HAS_RESOURCES,
+    organization_not_empty: CODES.HAS_RESOURCES,
+
+    // ── Não processável ──────────────────────────────────────────────────
+    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".
+    authorization_pending: CODES.UNPROCESSABLE,
+
+    // ── Plano e cobrança ─────────────────────────────────────────────────
+    plan_limit: CODES.PLAN_LIMIT,
+    subscription_required: CODES.SUBSCRIPTION_REQUIRED,
+
+    // ── Ritmo e tamanho ──────────────────────────────────────────────────
+    rate_limited: CODES.RATE_LIMITED,
+    slow_down: CODES.RATE_LIMITED,
+    payload_too_large: CODES.PAYLOAD_TOO_LARGE,
+
+    // ── Falha nossa ou de terceiro ───────────────────────────────────────
+    server_error: CODES.INTERNAL_ERROR,
+    internal_error: CODES.INTERNAL_ERROR,
+    service_unavailable: CODES.SERVICE_UNAVAILABLE,
+    upstream_error: CODES.UPSTREAM_ERROR,
+    email_delivery_failed: CODES.UPSTREAM_ERROR,
+}
+
+export const isCode = valor => Object.prototype.hasOwnProperty.call(STATUS_BY_CODE, valor)
+
+/**
+ * O código canônico a partir do que o handler escreveu.
+ *
+ * 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.
+ */
+export const toCode = valor => (isCode(valor) ? valor : ALIASES[valor] || CODES.INTERNAL_ERROR)
+
+/**
+ * O código a partir de um status HTTP.
+ *
+ * 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.
+ */
+export const STATUS_TO_CODE = {
+    400: CODES.VALIDATION_ERROR,
+    401: CODES.UNAUTHORIZED,
+    402: CODES.PLAN_LIMIT,
+    403: CODES.FORBIDDEN,
+    404: CODES.NOT_FOUND,
+    409: CODES.CONFLICT,
+    410: CODES.EXPIRED,
+    413: CODES.PAYLOAD_TOO_LARGE,
+    422: CODES.UNPROCESSABLE,
+    429: CODES.RATE_LIMITED,
+    500: CODES.INTERNAL_ERROR,
+    502: CODES.UPSTREAM_ERROR,
+    503: CODES.SERVICE_UNAVAILABLE,
+}
+
+export const codeFromStatus = status => STATUS_TO_CODE[status] || CODES.INTERNAL_ERROR

package/src/index.js

@@ -0,0 +1,13 @@
+// ============================================================================
+// @riligar/contract — o contrato de API dos sete produtos
+// ============================================================================
+//
+// 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.
+//
+// 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.**
+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 { codeSchema, errorSchema, pageSchema, collectionSchema, resourceSchema, chavesCamelCase } from './schemas.js'

package/src/respostas.js

@@ -0,0 +1,135 @@
+// ============================================================================
+// 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 }

package/src/schemas.js

@@ -0,0 +1,80 @@
+// ============================================================================
+// SCHEMAS — o contrato como coisa executável
+// ============================================================================
+//
+// 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.
+//
+// Zod é peer: os sete produtos já o têm (v4), e embutir uma segunda cópia num
+// worker significa pagar o bundle duas vezes.
+import { z } from 'zod'
+
+import { STATUS_BY_CODE } from './codes.js'
+
+/** O código é o enum fechado — nada de string livre. */
+export const codeSchema = z.enum(Object.keys(STATUS_BY_CODE))
+
+export const errorSchema = z.object({
+    error: z.object({
+        code: codeSchema,
+        message: z.string().min(1),
+        details: z.record(z.string(), z.unknown()).optional(),
+        retriable: z.boolean().optional(),
+    }),
+})
+
+export const pageSchema = z.object({
+    limit: z.number().int().nonnegative(),
+    offset: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    hasMore: z.boolean(),
+})
+
+/** `{items, page}` — a forma de TODA coleção. */
+export const collectionSchema = item =>
+    z.object({
+        items: z.array(item ?? z.unknown()),
+        page: pageSchema,
+    })
+
+/**
+ * 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.
+ *
+ * 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".
+ */
+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`',
+    })
+
+const CAMEL = /^[a-z][a-zA-Z0-9]*$/
+
+/**
+ * Toda chave do corpo é camelCase, em qualquer profundidade.
+ *
+ * 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.
+ *
+ * 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`.
+ */
+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}]`))
+        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)
+        }
+    }
+    anda(valor, caminho)
+    return fora
+}