@ciromaciel/contract 1.0.0 → 1.0.2

package/README.md

@@ -1,38 +1,100 @@
 # @ciromaciel/contract
 
-O contrato de API da stack RiLiGar: um envelope, um catálogo de códigos de erro,
-e os helpers que tornam impossível responder fora dele.
+One response envelope, a closed catalogue of error codes, and helpers that make
+answering outside it impossible.
 
-A norma escrita vive [no
-infrastructure](https://github.com/riligar/infrastructure/blob/prod/apps/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.
+This package is the **executable** norm: what services import in order to
+respond, and what tests import in order to check. The rules it enforces are
+described below.
+
+## Installation
 
 ```bash
 bun add @ciromaciel/contract
 ```
 
+`zod` is an **optional** peer, needed only by the `/schemas` entrypoint.
+
+## Quick start
+
 ```js
-import { ok, created, failure, collection } from '@ciromaciel/contract'
+import { ok, created, collection, failure } from '@ciromaciel/contract'
 import { CODES } from '@ciromaciel/contract/codes'
 
-return ok({ id, nome })
-return failure(CODES.NOT_FOUND, 'projeto não encontrado')
+return ok({ id, name })
+return created({ id, name })
+return failure(CODES.NOT_FOUND, 'project not found')
 ```
 
-## Os schemas ficam num caminho próprio
+`failure()` derives the HTTP status from the code — there is no signature that
+lets you return `NOT_FOUND` with a 200.
+
+## API
+
+### `@ciromaciel/contract`
+
+| Export | What it does |
+| --- | --- |
+| `ok(resource, { status, headers })` | One resource, at the root. No `data`, no `success`, no `message`. |
+| `created(resource, { headers })` | A resource that has just been born — 201. |
+| `collection(list, page, { status, headers })` | `{ items, page: { limit, offset, total, hasMore } }`. Without `total`, `total` and `hasMore` come back `null` — "nobody counted" is not the same as zero. |
+| `page({ limit, offset, total, extra })` | Builds the `page` object for `collection`, requiring a numeric `total`. |
+| `pagination(url, { defaultLimit, maxLimit })` | Reads `limit`/`offset` from a URL, with a ceiling. |
+| `failure(code, message, { details, headers, status })` | An error `Response`. Status comes from the code. |
+| `failureBody(code, message, details)` | `{ body, status }` for frameworks that assemble the response themselves. |
+| `failureWithStatus(status, message, details, headers)` | For a global error handler that only has the HTTP number at hand. |
+| `CODES` · `STATUS_BY_CODE` · `RETRIABLE` · `ALIASES` | The vocabulary and its tables. |
+| `isCode` · `toCode` · `codeFromStatus` | Code guards and conversions. |
+
+### `@ciromaciel/contract/codes`
+
+The closed enum: `UNAUTHORIZED`, `FORBIDDEN`, `WRONG_AUDIENCE`,
+`INSUFFICIENT_SCOPE`, `NOT_FOUND`, `CONFLICT`, `NAME_TAKEN`, `EXPIRED`,
+`HAS_RESOURCES`, `VALIDATION_ERROR`, `UNPROCESSABLE`, `RATE_LIMITED`,
+`PAYLOAD_TOO_LARGE`, `PLAN_LIMIT`, `SUBSCRIPTION_REQUIRED`, `INTERNAL_ERROR`,
+`SERVICE_UNAVAILABLE`, `UPSTREAM_ERROR`.
+
+`code` is the part the client reads; `message` is for the human and its wording
+may change at any time. Renaming a code is a breaking change.
+
+### `@ciromaciel/contract/schemas`
+
+```js
+import { errorSchema, collectionSchema, resourceSchema, pageSchema, codeSchema } from '@ciromaciel/contract/schemas'
+```
+
+Zod schemas for the same rules, from the reader's side. This path is separate on
+purpose: `schemas.js` imports Zod, and a worker that only needs to respond
+should not have to load a validator it never calls. While the index re-exported
+the schemas, the import was eager — asking for `failure` pulled Zod in, and the
+install broke with *"Cannot find package 'zod'"* for anyone who treated the peer
+as optional.
+
+### `@ciromaciel/contract/plan`
 
 ```js
-import { envelope } from '@ciromaciel/contract/schemas'   // requer zod
+import { createPlanGate } from '@ciromaciel/contract/plan'
+
+export const plan = createPlanGate({
+    product: 'auth',
+    resource: 'applications',
+    tiers: [
+        { slug: 'auth-applications-1', limit: 1 },
+        { slug: 'auth-applications-5', limit: 5 },
+        { slug: 'auth-applications-unlimited', limit: Infinity },
+    ],
+})
 ```
 
-`schemas.js` importa Zod, que é um peer **opcional** — um worker que só precisa
-responder não deveria carregar um validador de 60 kB. Enquanto o índice
-reexportava os schemas, o import era eager: pedir `failure` puxava Zod junto, e
-a instalação quebrava com *"Cannot find package 'zod'"* para quem tratou o peer
-como opcional. Quem quer os schemas importa o caminho deles, onde Zod é um
-requisito legítimo e declarado.
+Also exports `hasSlug`, `tierLimit`, `getPlanNotice`, `withPlanNotice`,
+`gateTelemetry`, `recordGateDecision` and `resetGateTelemetry`. A product owns
+the prefix, the slugs and the wording of the notice; the cache, the fail-open,
+the product-prefix check and the choice between `PLAN_LIMIT` and
+`SUBSCRIPTION_REQUIRED` are the same reasoning everywhere.
+
+## Links
 
-## A regra que este pacote torna mecânica
+- [Documentation](https://myinfrastructure.click)
+- [Package on npm](https://www.npmjs.com/package/@ciromaciel/contract)
 
-Um agente que aprendeu um produto da RiLiGar já sabe usar os outros seis.
+MIT © [Ciro Cesar Maciel](https://ciromaciel.click)

package/package.json

@@ -1,9 +1,9 @@
 {
     "name": "@ciromaciel/contract",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "license": "MIT",
     "type": "module",
-    "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.",
+    "description": "A single response envelope, a closed catalogue of error codes, and helpers that make answering outside it impossible.",
     "main": "src/index.js",
     "files": [
         "src",
@@ -32,9 +32,9 @@
     "publishConfig": {
         "access": "public"
     },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/riligar/packages.git",
-        "directory": "contract"
-    }
+    "homepage": "https://myinfrastructure.click",
+    "bugs": {
+        "url": "https://myinfrastructure.click"
+    },
+    "author": "Ciro Cesar Maciel <maciel.ciro@icloud.com> (https://ciromaciel.click)"
 }

package/src/index.js

@@ -2,7 +2,7 @@
 // @ciromaciel/contract — the API contract of the seven products
 // ============================================================================
 //
-// The written norm lives in https://github.com/riligar/infrastructure/blob/prod/apps/website/docs/2026-09-09-api-contract.md. This
+// The written norm lives in https://github.com/ciro-maciel/infrastructure/blob/prod/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.
 //