@pimia/sdk 0.5.0 → 0.7.0

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';
@@ -35,6 +35,16 @@ export declare const SCOPES: {
     readonly agendaRead: "agenda:read";
     readonly agendaWrite: "agenda:write";
     readonly reportsRead: "reports:read";
+    /** Leer la configuración de la empresa (impuestos, preferencias, series). */
+    readonly settingsRead: "settings:read";
+    /** Ver la tienda de módulos y qué tiene contratado el tenant. */
+    readonly storeRead: "store:read";
+    /** Leer la gestión de personal: empleados, ausencias, fichajes, calendarios. */
+    readonly hrRead: "hr:read";
+    /** Gestionar el personal: altas, ausencias, correcciones de fichaje, horarios. */
+    readonly hrWrite: "hr:write";
+    /** Gestionar los avisos (webhooks) que recibe tu app. */
+    readonly webhooksWrite: "webhooks:write";
     /**
      * Proponer cambios que el dueño del tenant aprueba antes de aplicarse.
      * `approvalsSubmit` es un alias del mismo permiso, aceptado por el

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';
@@ -31,6 +31,16 @@ export const SCOPES = {
     agendaRead: 'agenda:read',
     agendaWrite: 'agenda:write',
     reportsRead: 'reports:read',
+    /** Leer la configuración de la empresa (impuestos, preferencias, series). */
+    settingsRead: 'settings:read',
+    /** Ver la tienda de módulos y qué tiene contratado el tenant. */
+    storeRead: 'store:read',
+    /** Leer la gestión de personal: empleados, ausencias, fichajes, calendarios. */
+    hrRead: 'hr:read',
+    /** Gestionar el personal: altas, ausencias, correcciones de fichaje, horarios. */
+    hrWrite: 'hr:write',
+    /** Gestionar los avisos (webhooks) que recibe tu app. */
+    webhooksWrite: 'webhooks:write',
     /**
      * Proponer cambios que el dueño del tenant aprueba antes de aplicarse.
      * `approvalsSubmit` es un alias del mismo permiso, aceptado por el

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pimia/sdk",
-  "version": "0.5.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"
   },