@hablala/api-contract 0.4.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +10522 -5122
- package/llms.txt +53 -0
- package/openapi.json +16488 -9641
- package/package.json +7 -6
package/llms.txt
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# @hablala/api-contract
|
|
2
|
+
|
|
3
|
+
> El contrato **single source of truth** de la API de Hablalá: un `openapi.json` (OpenAPI 3.1)
|
|
4
|
+
> generado desde el backend Elixir con OpenApiSpex, del que derivan los tipos TypeScript. Nadie
|
|
5
|
+
> escribe tipos de la API a mano. Hablalá es API-first y headless: la API es el producto, solo
|
|
6
|
+
> habla JSON, sin UI.
|
|
7
|
+
|
|
8
|
+
## El contrato
|
|
9
|
+
|
|
10
|
+
- [openapi.json](./openapi.json): el spec OpenAPI 3.1 completo, generado desde Elixir
|
|
11
|
+
(`mix openapi.spec.json`). Es la fuente de verdad; los tipos y los clientes derivan de aquí.
|
|
12
|
+
- [generated/types.ts](./generated/types.ts): tipos TypeScript generados con `openapi-typescript`
|
|
13
|
+
(no editar a mano). Se reexportan desde `src/index.ts` como `paths`, `components`, `operations`.
|
|
14
|
+
|
|
15
|
+
## Formato de error (RFC 9457)
|
|
16
|
+
|
|
17
|
+
Todo error de la API responde con `application/problem+json` (RFC 9457), un formato único:
|
|
18
|
+
|
|
19
|
+
{
|
|
20
|
+
"type": "https://hablala.com/errors/<code>",
|
|
21
|
+
"title": "<etiqueta canónica en inglés>",
|
|
22
|
+
"status": <int>,
|
|
23
|
+
"detail": "<mensaje humano>",
|
|
24
|
+
"code": "<code estable, legible por máquina>",
|
|
25
|
+
"did_you_mean": ["<sugerencia>"], // opcional (unknown_attribute/object)
|
|
26
|
+
"errors": [{ "field": "...", "message": "..." }] // opcional (validación por campo)
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
El `code` es el ancla del contrato: ramifica por él, no por el status. El schema está en
|
|
30
|
+
`components.schemas.Error` del `openapi.json`.
|
|
31
|
+
|
|
32
|
+
## Rate limiting
|
|
33
|
+
|
|
34
|
+
Las respuestas llevan `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. Al
|
|
35
|
+
exceder la cuota: `429` con `Retry-After` (segundos) y un cuerpo RFC 9457 con `code: "rate_limited"`.
|
|
36
|
+
|
|
37
|
+
## Autenticación
|
|
38
|
+
|
|
39
|
+
Una credencial es una identidad completa (el token porta su tenant): no se pasa `organizationId`
|
|
40
|
+
ni `workspaceId`. Access token de máquina `hpat_…` (Bearer) para el motor; storefront token
|
|
41
|
+
`sfpk_…`/`sfpr_…` (header `X-Hablala-Storefront-Token`) para la Data API pública read-only.
|
|
42
|
+
|
|
43
|
+
## Cómo consumirlo
|
|
44
|
+
|
|
45
|
+
- TypeScript (web/móvil): importa los tipos de `@hablala/api-contract` y usa `openapi-fetch`.
|
|
46
|
+
El SDK de alto nivel es [`@hablala/client`](../client).
|
|
47
|
+
- Regeneración: `npm run generate` (openapi.json → types.ts). CI falla si hay drift.
|
|
48
|
+
|
|
49
|
+
## Docs de arquitectura (en el monorepo)
|
|
50
|
+
|
|
51
|
+
- [apps/api/ARCHITECTURE.md](../../apps/api/ARCHITECTURE.md): el mapa completo de la plataforma.
|
|
52
|
+
- [apps/api/API_FIRST.md](../../apps/api/API_FIRST.md): por qué API-first, cómo se genera el contrato.
|
|
53
|
+
- [apps/api/UBIQUITOUS_LANGUAGE.md](../../apps/api/UBIQUITOUS_LANGUAGE.md): el vocabulario normativo.
|