@pimia/sdk 0.6.0 → 0.7.0

package/README.md

@@ -92,6 +92,56 @@ if (meta.idempotentReplay) {
 }
 ```
 
+## Subir un fichero
+
+Diez operaciones de la API son `multipart/form-data`: el justificante de un
+gasto, el documento de una factura recibida, un extracto bancario, el membrete
+de una plantilla, el certificado de firma, el avatar. Para ésas pásale un
+`FormData` y el cliente lo manda tal cual — **no le pongas `content-type`**: el
+runtime escribe el suyo con el `boundary` que separa las partes, y una cabecera
+puesta a mano se lo quita (el cliente lo rechaza antes de salir, con un aviso
+que lo explica).
+
+`toFormData` hace las tres conversiones que el servidor espera y que `FormData`
+sola no hace: los booleanos como `1`/`0`, los objetos y arrays como cadena
+JSON, y los `null` omitidos en vez de mandados como la cadena `"null"`.
+
+```ts
+import { toFormData } from '@pimia/sdk'
+
+// Un gasto con su justificante en PDF, de una sola llamada.
+await client.post('/expenses', toFormData({
+  expense_date: '2026-08-24',
+  expense_category_id: 3,
+  amount: 12100,                       // céntimos, como todo importe
+  attachment_receipt: ficheroDelInput, // un File del navegador
+  customFields: [{ id: 3, value: 'REF-42' }],
+}))
+
+// El documento de una factura recibida, con un Blob al que le das nombre.
+const form = new FormData()
+form.append('document', blobPdf, 'factura-proveedor.pdf')
+await client.post(`/received-invoices/${id}/upload/document`, form)
+```
+
+Los campos de fichero salen tipados como `Blob` en `@pimia/sdk/api`, así que un
+`File` del navegador encaja sin ceremonia.
+
+⚠️ Lo que **no** puedes pasar es un `ReadableStream`: el cliente reintenta ante
+un 401 y ante un 429, y un cuerpo de un solo uso no se puede volver a mandar.
+
+## Descargar un fichero
+
+Para las dos operaciones que devuelven un binario, `download`:
+
+```ts
+const pdf = await client.download(`/received-invoices/${id}/show/document`)
+const url = URL.createObjectURL(pdf)
+```
+
+⚠️ **No uses `get()` para esto.** Lee la respuesta con `response.text()`, así
+que un PDF llega entero de tamaño y no se abre — sin ningún error que mirar.
+
 ## Recibir webhooks
 
 `verifyWebhook` comprueba la firma `PIMIA-WEBHOOK-v1` y te devuelve el evento

package/dist/api.d.ts

@@ -1,6 +1,10 @@
 /**
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
+ *
+ * Generado con `npm run generate:types` (scripts/generate-types.mjs), que
+ * añade UN transform al generador: `format: binary` sale como `Blob` y no
+ * como `string`. El porqué, en ese fichero.
  */
 export interface paths {
     "/absences/balance": {
@@ -4043,7 +4047,7 @@ export interface components {
              * Format: binary
              * @description Maximum file size: 20000 kilobytes.
              */
-            admin_avatar?: string | null;
+            admin_avatar?: Blob | null;
             avatar?: string | null;
         };
         /** BankAccount */
@@ -5067,7 +5071,7 @@ export interface components {
              * Format: binary
              * @description Maximum file size: 20000 kilobytes.
              */
-            attachment_receipt?: string | null;
+            attachment_receipt?: Blob | null;
             /** @description Valores de campo personalizado del recurso. `id` es el de la definición, que se descubre en `GET /custom-fields` (catálogo `meta`, legible con cualquier token); las definiciones las crea el dueño del tenant desde su panel. Se devuelven en la clave `fields` del recurso. En `multipart/form-data` viaja como cadena JSON: `[{"id":3,"value":"REF-42"}]`. */
             customFields?: string;
             /** @description Borra el recibo adjunto del gasto. Solo surte efecto en la actualización; en `multipart/form-data` viaja como `1` o `0`. */
@@ -7778,7 +7782,7 @@ export interface operations {
                      * Format: binary
                      * @description Maximum file size: 10240 kilobytes.
                      */
-                    file: string;
+                    file: Blob;
                     bank_account_id: number;
                     /** @enum {string} */
                     format: "norma43" | "csv" | "auto";
@@ -10925,7 +10929,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/octet-stream": string;
+                    "application/octet-stream": Blob;
                 };
             };
             404: components["responses"]["ModelNotFoundException"];
@@ -10948,7 +10952,7 @@ export interface operations {
                      * Format: binary
                      * @description Maximum file size: 5120 kilobytes.
                      */
-                    letterhead: string;
+                    letterhead: Blob;
                 };
             };
         };
@@ -11522,7 +11526,7 @@ export interface operations {
                      * Format: binary
                      * @description Maximum file size: 5120 kilobytes.
                      */
-                    file: string;
+                    file: Blob;
                 };
             };
         };
@@ -13044,7 +13048,7 @@ export interface operations {
                      * Format: binary
                      * @description Maximum file size: 10240 kilobytes.
                      */
-                    certificate: string;
+                    certificate: Blob;
                     password: string;
                 };
             };
@@ -13279,7 +13283,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/octet-stream": string;
+                    "application/octet-stream": Blob;
                 };
             };
             404: components["responses"]["ModelNotFoundException"];
@@ -13302,7 +13306,7 @@ export interface operations {
                      * Format: binary
                      * @description Maximum file size: 10240 kilobytes.
                      */
-                    document: string;
+                    document: Blob;
                 };
             };
         };

package/dist/api.js

@@ -1,5 +1,9 @@
 /**
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
+ *
+ * Generado con `npm run generate:types` (scripts/generate-types.mjs), que
+ * añade UN transform al generador: `format: binary` sale como `Blob` y no
+ * como `string`. El porqué, en ese fichero.
  */
 export {};

package/dist/client.d.ts

@@ -64,8 +64,43 @@ export interface RequestOptions {
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     /** Query string. Los `undefined`/`null` se omiten; los arrays se repiten. */
     query?: Record<string, string | number | boolean | undefined | null | Array<string | number>>;
-    /** Cuerpo JSON. */
+    /**
+     * El cuerpo de la petición.
+     *
+     * Por defecto se manda como **JSON**, que es lo que pide casi toda la API.
+     *
+     * Diez operaciones del contrato son `multipart/form-data` —el justificante
+     * de un gasto, el documento de una factura recibida, importar un extracto
+     * bancario, el membrete de una plantilla, el certificado de firma…—, y para
+     * ésas se pasa un {@link FormData}: el cliente lo manda **tal cual** y **no
+     * le pone `content-type`**, para que el runtime escriba el suyo con su
+     * `boundary`. {@link toFormData} lo arma con las conversiones que el
+     * servidor espera.
+     *
+     * También pasan sin tocar `Blob`, `URLSearchParams`, `ArrayBuffer` y las
+     * vistas de `ArrayBuffer`.
+     *
+     * ⛔ Un `ReadableStream` **no**, y es a propósito: este cliente reintenta
+     * ante un 401 (tras refrescar) y ante un 429, y un stream ya consumido no se
+     * puede volver a mandar — el reintento fallaría con un error que no se
+     * parece en nada a su causa. Los cinco de arriba se pueden releer.
+     */
     body?: unknown;
+    /**
+     * Cómo leer una respuesta **correcta**.
+     *
+     * `'json'` (el defecto) es lo de siempre. `'blob'` es para las dos
+     * operaciones que devuelven un fichero (`application/octet-stream`):
+     * descargar el membrete de una plantilla y el documento escaneado de una
+     * factura recibida.
+     *
+     * ⚠️ Sin esto, un PDF se lee con `response.text()` y **se corrompe en
+     * silencio**: el fichero «llega», pesa lo suyo y no se abre.
+     *
+     * Los errores se siguen leyendo como JSON aunque pidas `'blob'` — cuando la
+     * API falla contesta su sobre de error, no el fichero.
+     */
+    responseType?: 'json' | 'blob';
     headers?: Record<string, string>;
     signal?: AbortSignal;
     /**
@@ -531,6 +566,25 @@ export declare class PimiaClient {
     put<T = unknown>(path: string, body?: unknown, options?: WriteOptions): Promise<T>;
     patch<T = unknown>(path: string, body?: unknown, options?: WriteOptions): Promise<T>;
     delete<T = unknown>(path: string, options?: ReadOptions): Promise<T>;
+    /**
+     * Descarga un fichero de la API y te lo da como `Blob`.
+     *
+     * Son dos operaciones: el membrete de una plantilla
+     * (`GET /invoice-templates/{id}/letterhead`) y el documento escaneado de una
+     * factura recibida (`GET /received-invoices/{id}/show/document`).
+     *
+     * Existe porque `get()` **corrompe un binario sin decirlo**: lee la
+     * respuesta con `response.text()`, y un PDF pasado por ahí llega entero de
+     * tamaño y no se abre. Ese es el peor final posible para una descarga, así
+     * que la forma correcta tiene nombre propio en vez de ser una bandera que
+     * hay que acordarse de poner.
+     *
+     * ```ts
+     * const pdf = await client.download(`/received-invoices/${id}/show/document`)
+     * const url = URL.createObjectURL(pdf)
+     * ```
+     */
+    download(path: string, query?: RequestOptions['query'], options?: ReadOptions): Promise<Blob>;
     /**
      * Petición cruda contra `/api/v1`. `path` puede llevar el prefijo o no:
      * `/invoices` y `/api/v1/invoices` son lo mismo.
@@ -565,4 +619,35 @@ export declare class PimiaClient {
     private captureRateLimit;
     private retryDelay;
 }
+/**
+ * Arma el `FormData` de una operación multipart con las conversiones que el
+ * servidor de Pimia espera, que **no** son las que hace `FormData` sola.
+ *
+ * Tres reglas, y las tres salen del contrato, no de la costumbre:
+ *
+ * - **Los booleanos viajan como `1` y `0`.** Lo dice el propio spec en
+ *   `ExpenseRequest.is_attachment_receipt_removed`: «en `multipart/form-data`
+ *   viaja como `1` o `0`». Un `String(false)` daría `"false"`, que PHP lee
+ *   como verdadero.
+ * - **Los objetos y arrays viajan como JSON en una cadena.** También del
+ *   spec, en `ExpenseRequest.customFields`: «viaja como cadena JSON:
+ *   `[{"id":3,"value":"REF-42"}]`».
+ * - **`null` y `undefined` se omiten**, en vez de mandar `"null"`. Un campo
+ *   ausente es un campo ausente; la cadena `"null"` es un valor.
+ *
+ * Un `Blob` o un `File` se añaden tal cual. Con un `File` el runtime manda ya
+ * su nombre; con un `Blob` suelto se puede dar uno pasando `[blob, 'x.pdf']`,
+ * que es la forma que el tercer argumento de `append` admite.
+ *
+ * ```ts
+ * await client.post('/expenses', toFormData({
+ *   expense_date: '2026-08-24',
+ *   expense_category_id: 3,
+ *   amount: 12100,
+ *   attachment_receipt: ficheroPdf,
+ *   customFields: [{ id: 3, value: 'REF-42' }],
+ * }))
+ * ```
+ */
+export declare function toFormData(fields: Record<string, unknown | [Blob, string]>): FormData;
 export {};

package/dist/client.js

@@ -127,6 +127,32 @@ export class PimiaClient {
     delete(path, options) {
         return this.request(path, { ...options, method: 'DELETE' });
     }
+    /**
+     * Descarga un fichero de la API y te lo da como `Blob`.
+     *
+     * Son dos operaciones: el membrete de una plantilla
+     * (`GET /invoice-templates/{id}/letterhead`) y el documento escaneado de una
+     * factura recibida (`GET /received-invoices/{id}/show/document`).
+     *
+     * Existe porque `get()` **corrompe un binario sin decirlo**: lee la
+     * respuesta con `response.text()`, y un PDF pasado por ahí llega entero de
+     * tamaño y no se abre. Ese es el peor final posible para una descarga, así
+     * que la forma correcta tiene nombre propio en vez de ser una bandera que
+     * hay que acordarse de poner.
+     *
+     * ```ts
+     * const pdf = await client.download(`/received-invoices/${id}/show/document`)
+     * const url = URL.createObjectURL(pdf)
+     * ```
+     */
+    download(path, query, options) {
+        return this.request(path, {
+            ...options,
+            method: 'GET',
+            query,
+            responseType: 'blob',
+        });
+    }
     /**
      * Petición cruda contra `/api/v1`. `path` puede llevar el prefijo o no:
      * `/invoices` y `/api/v1/invoices` son lo mismo.
@@ -152,6 +178,13 @@ export class PimiaClient {
      * ```
      */
     async requestWithMeta(path, options = {}) {
+        /* El cuerpo se clasifica UNA vez, fuera del bucle: lo que se manda no
+           cambia entre el intento y su reintento, y decidirlo dentro invitaría a
+           que algún día dejaran de coincidir. */
+        const cuerpoNativo = esCuerpoNativo(options.body);
+        if (cuerpoNativo) {
+            exigirSinContentType(options.body, { ...this.extraHeaders, ...options.headers });
+        }
         let tokens = await this.currentTokens();
         if (isExpired(tokens, this.skew)) {
             tokens = await this.refreshTokens(tokens);
@@ -162,8 +195,17 @@ export class PimiaClient {
             const response = await this.doFetch(this.urlFor(path, options.query), {
                 method: options.method ?? 'GET',
                 headers: {
-                    accept: 'application/json',
-                    ...(options.body === undefined ? {} : { 'content-type': 'application/json' }),
+                    /* Una descarga no pide JSON: si se dejara `application/json` fijo, un
+                       servidor que negocie el tipo tendría derecho a contestar 406 —o a
+                       mandar un JSON de error donde se esperaba el fichero. */
+                    accept: options.responseType === 'blob' ? '*/*' : 'application/json',
+                    /* Un cuerpo nativo trae su propio tipo: el runtime le pone
+                       `multipart/form-data` CON su `boundary`, o el de un `Blob`, o
+                       `application/x-www-form-urlencoded`. Escribirlo aquí a mano se lo
+                       quitaría, y sin `boundary` el servidor no puede parsear nada. */
+                    ...(options.body === undefined || cuerpoNativo
+                        ? {}
+                        : { 'content-type': 'application/json' }),
                     ...this.extraHeaders,
                     ...options.headers,
                     // Después de `options.headers` para que la opción con nombre mande
@@ -174,13 +216,23 @@ export class PimiaClient {
                         : { 'idempotency-key': options.idempotencyKey }),
                     authorization: `Bearer ${tokens.accessToken}`,
                 },
-                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                body: options.body === undefined
+                    ? undefined
+                    : cuerpoNativo
+                        ? options.body
+                        : JSON.stringify(options.body),
                 signal: options.signal,
             });
             this.captureRateLimit(response);
             if (response.ok) {
                 return {
-                    data: (await parseBody(response)),
+                    /* Una descarga se devuelve como `Blob` SIN pasar por `parseBody`,
+                       que hace `response.text()`: un PDF leído como texto se corrompe en
+                       la primera secuencia que no sea UTF-8 válido, y lo hace en
+                       silencio — el fichero «llega» y no se abre. */
+                    data: (options.responseType === 'blob'
+                        ? await response.blob()
+                        : await parseBody(response)),
                     meta: {
                         status: response.status,
                         // Presente solo cuando Pimia reproduce; su ausencia significa
@@ -287,6 +339,110 @@ export class PimiaClient {
         return Math.min(base, this.maxRetryDelayMs);
     }
 }
+/**
+ * ¿Es un cuerpo que el runtime serializa por su cuenta?
+ *
+ * Los cinco de la lista tienen dos cosas en común, y las dos importan: `fetch`
+ * sabe convertirlos y **se pueden releer**. Lo segundo es lo que decide quién
+ * entra: este cliente reintenta ante un 401 (después de refrescar) y ante un
+ * 429, así que un cuerpo de un solo uso —un `ReadableStream`— reventaría en el
+ * reintento con un «body already used» que no se parece en nada a su causa.
+ *
+ * Los `typeof … !== 'undefined'` no son celo: este paquete corre en Node y en
+ * el navegador, y aunque Node 20 los trae todos, un runtime recortado que no
+ * tenga `FormData` debe fallar en el `instanceof`, no al evaluarlo.
+ */
+function esCuerpoNativo(body) {
+    if (body === undefined || body === null)
+        return false;
+    return ((typeof FormData !== 'undefined' && body instanceof FormData) ||
+        (typeof Blob !== 'undefined' && body instanceof Blob) ||
+        (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body));
+}
+/**
+ * Un `FormData` con un `content-type` puesto a mano **no se manda**: se avisa.
+ *
+ * La cabecera de un multipart lleva el `boundary` que separa las partes, y lo
+ * genera el runtime al serializar. Escribir `content-type:
+ * multipart/form-data` a mano se lo quita, y entonces el servidor recibe un
+ * cuerpo que no puede parsear: contesta un 422 sobre un campo obligatorio que
+ * el cliente **sí mandó**, y el rastro no lleva a ninguna parte.
+ *
+ * Es un error de quien llama, no de la API, así que se lanza aquí y no se
+ * intenta arreglar por su cuenta: quitarle la cabecera en silencio dejaría en
+ * pie la creencia de que hacía falta.
+ */
+function exigirSinContentType(body, headers) {
+    if (typeof FormData === 'undefined' || !(body instanceof FormData))
+        return;
+    const puesta = Object.keys(headers).find((k) => k.toLowerCase() === 'content-type');
+    if (puesta === undefined)
+        return;
+    throw new TypeError('No le pongas `content-type` a un cuerpo FormData: el runtime escribe el suyo ' +
+        'con el `boundary` que separa las partes, y una cabecera a mano se lo quita ' +
+        `(el servidor respondería 422 sobre un campo que sí mandaste). Quita \`${puesta}\` ` +
+        'de las cabeceras de esta petición.');
+}
+/**
+ * Arma el `FormData` de una operación multipart con las conversiones que el
+ * servidor de Pimia espera, que **no** son las que hace `FormData` sola.
+ *
+ * Tres reglas, y las tres salen del contrato, no de la costumbre:
+ *
+ * - **Los booleanos viajan como `1` y `0`.** Lo dice el propio spec en
+ *   `ExpenseRequest.is_attachment_receipt_removed`: «en `multipart/form-data`
+ *   viaja como `1` o `0`». Un `String(false)` daría `"false"`, que PHP lee
+ *   como verdadero.
+ * - **Los objetos y arrays viajan como JSON en una cadena.** También del
+ *   spec, en `ExpenseRequest.customFields`: «viaja como cadena JSON:
+ *   `[{"id":3,"value":"REF-42"}]`».
+ * - **`null` y `undefined` se omiten**, en vez de mandar `"null"`. Un campo
+ *   ausente es un campo ausente; la cadena `"null"` es un valor.
+ *
+ * Un `Blob` o un `File` se añaden tal cual. Con un `File` el runtime manda ya
+ * su nombre; con un `Blob` suelto se puede dar uno pasando `[blob, 'x.pdf']`,
+ * que es la forma que el tercer argumento de `append` admite.
+ *
+ * ```ts
+ * await client.post('/expenses', toFormData({
+ *   expense_date: '2026-08-24',
+ *   expense_category_id: 3,
+ *   amount: 12100,
+ *   attachment_receipt: ficheroPdf,
+ *   customFields: [{ id: 3, value: 'REF-42' }],
+ * }))
+ * ```
+ */
+export function toFormData(fields) {
+    const form = new FormData();
+    for (const [name, value] of Object.entries(fields)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value) && value.length === 2 && esBlob(value[0]) && typeof value[1] === 'string') {
+            form.append(name, value[0], value[1]);
+            continue;
+        }
+        if (esBlob(value)) {
+            form.append(name, value);
+            continue;
+        }
+        if (typeof value === 'boolean') {
+            form.append(name, value ? '1' : '0');
+            continue;
+        }
+        if (typeof value === 'object') {
+            form.append(name, JSON.stringify(value));
+            continue;
+        }
+        form.append(name, String(value));
+    }
+    return form;
+}
+function esBlob(value) {
+    return typeof Blob !== 'undefined' && value instanceof Blob;
+}
 function retryAfterSeconds(response) {
     const header = response.headers.get('retry-after');
     if (header === null)

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * por README.md; el contrato completo de endpoints está en el OpenAPI del que
  * salen los tipos de `./api`.
  */
-export { PimiaClient } from './client.js';
+export { PimiaClient, toFormData } from './client.js';
 export type { CustomerRequest, CustomerResource, EstimateResource, EstimatesRequest, InvoiceResource, InvoicesRequest, PimiaClientOptions, RateLimit, ReadOptions, RequestOptions, ResourceEnvelope, ResponseMeta, ResponseWithMeta, WriteOptions, } from './client.js';
 export { OAuth, createPkceChallenge, createState } from './oauth.js';
 export type { AuthorizationServerMetadata, AuthorizeUrlOptions, OAuthConfig, PkceChallenge, } from './oauth.js';

package/dist/index.js

@@ -5,7 +5,7 @@
  * por README.md; el contrato completo de endpoints está en el OpenAPI del que
  * salen los tipos de `./api`.
  */
-export { PimiaClient } from './client.js';
+export { PimiaClient, toFormData } from './client.js';
 export { OAuth, createPkceChallenge, createState } from './oauth.js';
 export { MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
 export { DuplicateExternalRefError, ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pimia/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Cliente TypeScript de la API de Pimia para apps de partner: OAuth con PKCE, rotación de refresh persistida, reintentos de rate limit y tipos generados del OpenAPI.",
   "license": "MIT",
   "author": "Pimia (https://pimia.es)",
@@ -40,7 +40,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "generate:types": "openapi-typescript ../spec/pimia-api-v1.json -o src/api.ts",
+    "generate:types": "node scripts/generate-types.mjs",
     "test": "node --test test/*.test.js",
     "prepublishOnly": "npm run build"
   },