@pimia/sdk 0.1.0 → 0.2.0

package/dist/client.d.ts

@@ -34,12 +34,50 @@ export interface RequestOptions {
     body?: unknown;
     headers?: Record<string, string>;
     signal?: AbortSignal;
+    /**
+     * Clave de idempotencia para este `POST`. Manda una única por operación —un
+     * UUID nuevo— y reúsala SOLO en los reintentos de esa misma operación:
+     * Pimia ejecuta la escritura una vez y reproduce la respuesta original en
+     * los reintentos. La misma clave con otro cuerpo responde 422.
+     *
+     * Para saber si lo que recibiste es un eco y no una escritura nueva, usa
+     * {@link PimiaClient.requestWithMeta} y mira `meta.idempotentReplay`.
+     */
+    idempotencyKey?: string;
 }
 /** Cabeceras de rate limit que devuelve la API en cada respuesta. */
 export interface RateLimit {
     limit?: number;
     remaining?: number;
 }
+/**
+ * Lo que la respuesta dice ADEMÁS del cuerpo.
+ *
+ * Va por petición y no como estado del cliente —al contrario que
+ * {@link PimiaClient.rateLimit}— a propósito: `idempotentReplay` solo
+ * significa algo referido a UNA llamada concreta, y justo se consulta cuando
+ * hay reintentos, que es cuando puede haber varias en vuelo. Un campo
+ * compartido en el cliente daría la respuesta de otra.
+ */
+export interface ResponseMeta {
+    status: number;
+    /**
+     * `true` si Pimia reprodujo la respuesta de una petición anterior con la
+     * misma `Idempotency-Key` en vez de volver a escribir. Es la diferencia
+     * entre «he creado la factura» y «ya estaba creada»: sin esto, un partner
+     * no puede distinguirlas en sus propios registros.
+     */
+    idempotentReplay: boolean;
+    requestId?: string;
+    rateLimit: RateLimit;
+}
+/** Cuerpo y metadatos de una misma respuesta. */
+export interface ResponseWithMeta<T> {
+    data: T;
+    meta: ResponseMeta;
+}
+/** Lo que se puede afinar en una escritura (`post`/`put`/`patch`). */
+export type WriteOptions = Pick<RequestOptions, 'headers' | 'query' | 'signal' | 'idempotencyKey'>;
 export declare class PimiaClient {
     readonly oauth: OAuth;
     private readonly baseUrl;
@@ -58,30 +96,47 @@ export declare class PimiaClient {
     get invoices(): {
         list: (query?: RequestOptions["query"]) => Promise<unknown>;
         get: (id: number | string) => Promise<unknown>;
-        create: (body: unknown) => Promise<unknown>;
-        update: (id: number | string, body: unknown) => Promise<unknown>;
+        create: (body: unknown, options?: WriteOptions) => Promise<unknown>;
+        update: (id: number | string, body: unknown, options?: WriteOptions) => Promise<unknown>;
     };
     get customers(): {
         list: (query?: RequestOptions["query"]) => Promise<unknown>;
         get: (id: number | string) => Promise<unknown>;
-        create: (body: unknown) => Promise<unknown>;
-        update: (id: number | string, body: unknown) => Promise<unknown>;
+        create: (body: unknown, options?: WriteOptions) => Promise<unknown>;
+        update: (id: number | string, body: unknown, options?: WriteOptions) => Promise<unknown>;
     };
     get estimates(): {
         list: (query?: RequestOptions["query"]) => Promise<unknown>;
         get: (id: number | string) => Promise<unknown>;
-        create: (body: unknown) => Promise<unknown>;
+        create: (body: unknown, options?: WriteOptions) => Promise<unknown>;
     };
     get<T = unknown>(path: string, query?: RequestOptions['query']): Promise<T>;
-    post<T = unknown>(path: string, body?: unknown): Promise<T>;
-    put<T = unknown>(path: string, body?: unknown): Promise<T>;
-    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, options?: WriteOptions): Promise<T>;
+    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): Promise<T>;
     /**
      * Petición cruda contra `/api/v1`. `path` puede llevar el prefijo o no:
      * `/invoices` y `/api/v1/invoices` son lo mismo.
      */
     request<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Lo mismo que {@link request}, pero devuelve también los metadatos de la
+     * respuesta.
+     *
+     * Existe por la idempotencia: tras un reintento, el cuerpo 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. `meta.idempotentReplay` sí.
+     *
+     * ```ts
+     * const clave = crypto.randomUUID()
+     * const { data, meta } = await client.requestWithMeta('/estimates', {
+     *   method: 'POST', body, idempotencyKey: clave,
+     * })
+     * if (meta.idempotentReplay) log('el presupuesto ya existía; no se duplicó')
+     * ```
+     */
+    requestWithMeta<T = unknown>(path: string, options?: RequestOptions): Promise<ResponseWithMeta<T>>;
     private currentTokens;
     /**
      * Refresca UNA sola vez aunque lo pidan N peticiones en paralelo, y persiste

package/dist/client.js

@@ -46,36 +46,36 @@ export class PimiaClient {
         return {
             list: (query) => this.get('/invoices', query),
             get: (id) => this.get(`/invoices/${id}`),
-            create: (body) => this.post('/invoices', body),
-            update: (id, body) => this.put(`/invoices/${id}`, body),
+            create: (body, options) => this.post('/invoices', body, options),
+            update: (id, body, options) => this.put(`/invoices/${id}`, body, options),
         };
     }
     get customers() {
         return {
             list: (query) => this.get('/customers', query),
             get: (id) => this.get(`/customers/${id}`),
-            create: (body) => this.post('/customers', body),
-            update: (id, body) => this.put(`/customers/${id}`, body),
+            create: (body, options) => this.post('/customers', body, options),
+            update: (id, body, options) => this.put(`/customers/${id}`, body, options),
         };
     }
     get estimates() {
         return {
             list: (query) => this.get('/estimates', query),
             get: (id) => this.get(`/estimates/${id}`),
-            create: (body) => this.post('/estimates', body),
+            create: (body, options) => this.post('/estimates', body, options),
         };
     }
     get(path, query) {
         return this.request(path, { method: 'GET', query });
     }
-    post(path, body) {
-        return this.request(path, { method: 'POST', body });
+    post(path, body, options) {
+        return this.request(path, { ...options, method: 'POST', body });
     }
-    put(path, body) {
-        return this.request(path, { method: 'PUT', body });
+    put(path, body, options) {
+        return this.request(path, { ...options, method: 'PUT', body });
     }
-    patch(path, body) {
-        return this.request(path, { method: 'PATCH', body });
+    patch(path, body, options) {
+        return this.request(path, { ...options, method: 'PATCH', body });
     }
     delete(path) {
         return this.request(path, { method: 'DELETE' });
@@ -85,6 +85,26 @@ export class PimiaClient {
      * `/invoices` y `/api/v1/invoices` son lo mismo.
      */
     async request(path, options = {}) {
+        const { data } = await this.requestWithMeta(path, options);
+        return data;
+    }
+    /**
+     * Lo mismo que {@link request}, pero devuelve también los metadatos de la
+     * respuesta.
+     *
+     * Existe por la idempotencia: tras un reintento, el cuerpo 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. `meta.idempotentReplay` sí.
+     *
+     * ```ts
+     * const clave = crypto.randomUUID()
+     * const { data, meta } = await client.requestWithMeta('/estimates', {
+     *   method: 'POST', body, idempotencyKey: clave,
+     * })
+     * if (meta.idempotentReplay) log('el presupuesto ya existía; no se duplicó')
+     * ```
+     */
+    async requestWithMeta(path, options = {}) {
         let tokens = await this.currentTokens();
         if (isExpired(tokens, this.skew)) {
             tokens = await this.refreshTokens(tokens);
@@ -99,6 +119,12 @@ export class PimiaClient {
                     ...(options.body === undefined ? {} : { 'content-type': 'application/json' }),
                     ...this.extraHeaders,
                     ...options.headers,
+                    // Después de `options.headers` para que la opción con nombre mande
+                    // sobre una cabecera puesta a mano: si alguien usa las dos, la
+                    // explícita del API es la que quiso de verdad.
+                    ...(options.idempotencyKey === undefined
+                        ? {}
+                        : { 'idempotency-key': options.idempotencyKey }),
                     authorization: `Bearer ${tokens.accessToken}`,
                 },
                 body: options.body === undefined ? undefined : JSON.stringify(options.body),
@@ -106,7 +132,17 @@ export class PimiaClient {
             });
             this.captureRateLimit(response);
             if (response.ok) {
-                return (await parseBody(response));
+                return {
+                    data: (await parseBody(response)),
+                    meta: {
+                        status: response.status,
+                        // Presente solo cuando Pimia reproduce; su ausencia significa
+                        // «esta escritura ocurrió de verdad».
+                        idempotentReplay: response.headers.get('idempotency-replayed') === 'true',
+                        requestId: response.headers.get('x-request-id') ?? undefined,
+                        rateLimit: this.lastRateLimit,
+                    },
+                };
             }
             const body = await parseBody(response);
             const requestId = response.headers.get('x-request-id') ?? undefined;

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * salen los tipos de `./api`.
  */
 export { PimiaClient } from './client.js';
-export type { PimiaClientOptions, RateLimit, RequestOptions } from './client.js';
+export type { PimiaClientOptions, RateLimit, RequestOptions, ResponseMeta, ResponseWithMeta, WriteOptions, } from './client.js';
 export { OAuth, createPkceChallenge, createState } from './oauth.js';
 export type { AuthorizationServerMetadata, AuthorizeUrlOptions, OAuthConfig, PkceChallenge, } from './oauth.js';
 export { MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
@@ -33,5 +33,12 @@ export declare const SCOPES: {
     readonly agendaRead: "agenda:read";
     readonly agendaWrite: "agenda:write";
     readonly reportsRead: "reports:read";
+    /**
+     * Proponer cambios que el dueño del tenant aprueba antes de aplicarse.
+     * `approvalsSubmit` es un alias del mismo permiso, aceptado por el
+     * Authorization Server.
+     */
+    readonly approvalsWrite: "approvals:write";
+    readonly approvalsSubmit: "approvals:submit";
 };
 export type Scope = (typeof SCOPES)[keyof typeof SCOPES];

package/dist/index.js

@@ -30,4 +30,11 @@ export const SCOPES = {
     agendaRead: 'agenda:read',
     agendaWrite: 'agenda:write',
     reportsRead: 'reports:read',
+    /**
+     * Proponer cambios que el dueño del tenant aprueba antes de aplicarse.
+     * `approvalsSubmit` es un alias del mismo permiso, aceptado por el
+     * Authorization Server.
+     */
+    approvalsWrite: 'approvals:write',
+    approvalsSubmit: 'approvals:submit',
 };

package/package.json

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