@pimia/sdk 0.1.0 → 0.2.0

package/README.md

@@ -12,13 +12,10 @@ Requisitos: Node ≥ 20 (o cualquier runtime con `fetch` y WebCrypto global).
 npm install @pimia/sdk
 ```
 
-> **Pendiente del primer publish en npm.** El repositorio ya es **público**,
-> así que mientras tanto no hace falta invitación: clona
-> `Pimia-AI/pimia-sdks`, compila este directorio (`npm ci && npm run build`) e
-> instálalo por ruta (`npm install /ruta/a/pimia-sdks/typescript`) o como
-> tarball (`npm pack`). Ojo, `npm install git+https://…` **no** vale: npm
-> instalaría la raíz del monorepo, no `typescript/`. El detalle está en el
-> [README del monorepo](https://github.com/Pimia-AI/pimia-sdks#instalación).
+Publicado desde v0.1.0, con
+[provenance SLSA](https://docs.npmjs.com/generating-provenance-statements)
+firmada por el workflow de release: el tarball es verificablemente
+[este repositorio](https://github.com/Pimia-AI/pimia-sdks).
 
 ## Uso en 20 líneas
 
@@ -66,6 +63,35 @@ cliente exige un `TokenStore` en lugar de un string: persiste el conjunto de
 tokens tras cada refresco y no refresques dos veces en paralelo con el mismo
 token. Las dos cosas las cubre el SDK si lo usas como está pensado.
 
+## Reintentar un `POST` sin duplicar
+
+Manda una `Idempotency-Key` única por operación y Pimia ejecuta la escritura
+una sola vez, por muchos reintentos que haya:
+
+```ts
+const clave = crypto.randomUUID()
+await client.estimates.create(presupuesto, { idempotencyKey: clave })
+```
+
+Reúsala **solo** en los reintentos de esa misma operación: la misma clave con
+otro cuerpo responde `422`.
+
+Tras un reintento el cuerpo que recibes es idéntico al de la primera llamada
+—ese es justo el contrato—, así que el cuerpo solo no dice si Pimia escribió o
+se limitó a repetirse. Para saberlo, `requestWithMeta`:
+
+```ts
+const { data, meta } = await client.requestWithMeta('/estimates', {
+  method: 'POST',
+  body: presupuesto,
+  idempotencyKey: clave,
+})
+
+if (meta.idempotentReplay) {
+  // ya existía: no se ha creado nada nuevo
+}
+```
+
 ## Más
 
 Documentación completa, modelo mental (un tenant = una base URL = un token),