@riligar/contract 1.0.0 → 1.1.0

package/package.json

@@ -1,11 +1,14 @@
 {
     "name": "@riligar/contract",
-    "version": "1.0.0",
+    "version": "1.1.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.",
+    "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.",
     "main": "src/index.js",
-    "files": ["src", "README.md"],
+    "files": [
+        "src",
+        "README.md"
+    ],
     "exports": {
         ".": "./src/index.js",
         "./codes": "./src/codes.js",
@@ -15,14 +18,25 @@
         "test": "bun test tests/",
         "release": "semantic-release"
     },
-    "peerDependencies": { "zod": "^4.0.0" },
-    "peerDependenciesMeta": { "zod": { "optional": true } },
+    "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" }
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/riligar-applications/contract.git"
+    }
 }

package/src/index.js

@@ -8,6 +8,18 @@
 //
 // 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.**
+//
+// POR QUE OS SCHEMAS NÃO SAEM DAQUI
+//
+// `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.
+//
+// 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.
 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'
+export { ok, criado, colecao, falha, falhaComStatus, corpoDeFalha, paginacao, pagina } from './respostas.js'

package/src/respostas.js

@@ -48,17 +48,42 @@ export const criado = (recurso, { headers } = {}) => responder(recurso, 201, hea
  *
  * `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.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * `total: null` QUANDO NINGUÉM CONTOU — e isso é o ponto deste helper.
+ *
+ * Até 10/09 os defaults preenchiam `page` a partir do próprio array: uma rota
+ * que NUNCA paginou devolvia `{limit: N, offset: 0, total: N, hasMore: false}`,
+ * byte a byte idêntico ao de uma rota que paginou e chegou ao fim. Das 39
+ * rotas de coleção da stack, 29 não paginavam e todas as 29 afirmavam
+ * `hasMore: false` — o campo que existe para o agente não ter de deduzir
+ * deduzia errado em 87% dos casos.
+ *
+ * Agora: quem não passa `total` recebe `total: null` e `hasMore: null`. Nulo é
+ * "não sei", e é diferente de zero e de falso. O agente que lê `total: null`
+ * sabe que precisa perguntar de outro jeito; o que lê `hasMore: false` para de
+ * paginar — e essas duas conclusões não podem sair da mesma resposta.
+ *
+ * Quem pagina de verdade passa `total` e recebe `hasMore` calculado. Quem
+ * devolve a lista inteira de propósito passa `total: itens.length`, e aí o
+ * `hasMore: false` é uma afirmação, não um default.
  */
 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)
+    // `null` só quando NINGUÉM contou. `total: 0` é uma contagem legítima.
+    const total = pagina.total ?? null
+    const hasMore = pagina.hasMore ?? (total === null ? null : offset + items.length < total)
+
+    /*
+     * `extra` vai na RAIZ, não dentro de `page`. O `activeDeployId` do Hoster e
+     * as `contagens` do Monitors são contexto do CONJUNTO, não paginação —
+     * dentro de `page` eles diriam que são, e um cliente genérico que lê
+     * `page` para paginar tropeçaria neles.
+     */
+    return responder({ items, page: { limit, offset, total, hasMore }, ...(pagina.extra ?? {}) }, status, headers)
 }
 
 /**
@@ -118,6 +143,33 @@ export const paginacao = (url, { limitPadrao = 50, limitMaximo = 200 } = {}) =>
     return { limit, offset }
 }
 
+/**
+ * A página de uma consulta paginada, pronta para o `colecao`.
+ *
+ * Existe para tornar MECÂNICO o que a stack errava à mão em duas frentes:
+ *
+ * 1. **O `limit` reportado tem de ser o APLICADO.** Duas rotas clampavam na
+ *    camada de dados e reportavam o valor cru da query: com `?limit=5000`
+ *    devolviam 200 linhas e diziam `page:{limit:5000, hasMore:false}`. O
+ *    cliente conclui "pedi 5000, vieram 200, logo acabou" — e para de paginar
+ *    no meio.
+ *
+ * 2. **`total` vem de quem contou.** Passar `total` é obrigatório aqui, porque
+ *    o `colecao` sozinho não tem como saber se ninguém contou ou se a conta
+ *    deu o tamanho do array.
+ *
+ *   const { limit, offset } = paginacao(url)
+ *   const linhas = await buscar(limit, offset)
+ *   const [{ total }] = await contar()
+ *   return colecao(linhas, pagina({ limit, offset, total }))
+ */
+export const pagina = ({ limit, offset = 0, total, extra }) => {
+    if (!Number.isFinite(total)) {
+        throw new TypeError('pagina() exige `total` numérico — use colecao(itens) direto quando ninguém contou.')
+    }
+    return { limit, offset, total, extra }
+}
+
 /**
  * Uma falha de que só se sabe o status HTTP.
  *