@pimia/sdk 0.4.0 → 0.5.0

package/dist/client.d.ts

@@ -112,6 +112,19 @@ export interface ResponseWithMeta<T> {
 }
 /** Lo que se puede afinar en una escritura (`post`/`put`/`patch`). */
 export type WriteOptions = Pick<RequestOptions, 'headers' | 'query' | 'signal' | 'idempotencyKey'>;
+/**
+ * Lo que se puede afinar en una lectura (`get`/`delete` y los atajos de
+ * recurso).
+ *
+ * Sin `idempotencyKey`, que no significa nada en una lectura, y sin `query`,
+ * que en `get()` ya es un parámetro propio.
+ *
+ * Existe sobre todo por `signal`: hasta la 0.4 los atajos de lectura no
+ * aceptaban opciones, así que ponerle un timeout a un GET obligaba a bajar a
+ * `request()` — o a quedarse sin él, que es lo que pasa de verdad. Un cliente
+ * que sondea y se cuelga en una lectura deja de sondear sin dar un solo error.
+ */
+export type ReadOptions = Pick<RequestOptions, 'headers' | 'signal'>;
 export declare class PimiaClient {
     readonly oauth: OAuth;
     private readonly baseUrl;
@@ -128,13 +141,13 @@ export declare class PimiaClient {
     /** Cabeceras `X-RateLimit-*` de la última respuesta. */
     get rateLimit(): RateLimit;
     get invoices(): {
-        list: (query?: RequestOptions["query"]) => Promise<{
+        list: (query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
             data: components["schemas"]["InvoiceResource"][];
             meta: {
                 invoice_total_count: number;
             };
         }>;
-        get: (id: number | string) => Promise<{
+        get: (id: number | string, options?: ReadOptions) => Promise<{
             data: components["schemas"]["InvoiceResource"] & Record<string, never>;
         }>;
         /**
@@ -314,13 +327,13 @@ export declare class PimiaClient {
         }>>;
     };
     get customers(): {
-        list: (query?: RequestOptions["query"]) => Promise<{
+        list: (query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
             data: components["schemas"]["CustomerResource"][];
             meta: {
                 customer_total_count: number;
             };
         }>;
-        get: (id: number | string) => Promise<{
+        get: (id: number | string, options?: ReadOptions) => Promise<{
             data: components["schemas"]["CustomerResource"];
         }>;
         create: (body: CustomerRequest, options?: WriteOptions) => Promise<{
@@ -366,13 +379,13 @@ export declare class PimiaClient {
         }>>;
     };
     get estimates(): {
-        list: (query?: RequestOptions["query"]) => Promise<{
+        list: (query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
             data: components["schemas"]["EstimateResource"][];
             meta: {
                 estimate_total_count: number;
             };
         }>;
-        get: (id: number | string) => Promise<{
+        get: (id: number | string, options?: ReadOptions) => Promise<{
             data: components["schemas"]["EstimateResource"];
         }>;
         create: (body: EstimatesRequest, options?: WriteOptions) => Promise<{
@@ -396,9 +409,24 @@ export declare class PimiaClient {
          * `estimate:{id}:invoice`— y el reintento tras un timeout no te creará
          * una segunda factura.
          *
+         * Y manda `externalRef` si la venta nació en tu sistema: es lo que hace
+         * que `invoice.created` e `invoice.paid` te lleguen con tu referencia en
+         * vez de con `null`. **Tiene que ir aquí, en la conversión**; etiquetar
+         * después con `PUT /invoices/{id}` llega tarde por dos motivos: para
+         * entonces `invoice.created` ya salió con la referencia nula, y entre las
+         * dos llamadas hay una ventana en la que la factura existe y no la
+         * encuentras por tu referencia.
+         *
+         * Va como opción y no como segundo parámetro para no romperle la llamada
+         * a quien ya hace `convertToInvoice(id, { idempotencyKey })`: el cuerpo lo
+         * monta el atajo, y `external_ref` es además el único campo que el
+         * endpoint acepta.
+         *
          * Exige `estimates:write` **e** `invoices:write`.
          */
-        convertToInvoice: (id: number | string, options?: WriteOptions) => Promise<ResourceEnvelope<{
+        convertToInvoice: (id: number | string, options?: WriteOptions & {
+            externalRef?: string | null;
+        }) => Promise<ResourceEnvelope<{
             id: string;
             invoice_date: string;
             due_date: string;
@@ -484,11 +512,11 @@ export declare class PimiaClient {
             currency?: components["schemas"]["CurrencyResource"];
         }>>;
     };
-    get<T = unknown>(path: string, query?: RequestOptions['query']): Promise<T>;
+    get<T = unknown>(path: string, query?: RequestOptions['query'], options?: ReadOptions): 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>;
+    delete<T = unknown>(path: string, options?: ReadOptions): Promise<T>;
     /**
      * Petición cruda contra `/api/v1`. `path` puede llevar el prefijo o no:
      * `/invoices` y `/api/v1/invoices` son lo mismo.

package/dist/client.js

@@ -44,8 +44,8 @@ export class PimiaClient {
     }
     get invoices() {
         return {
-            list: (query) => this.get('/invoices', query),
-            get: (id) => this.get(`/invoices/${id}`),
+            list: (query, options) => this.get('/invoices', query, options),
+            get: (id, options) => this.get(`/invoices/${id}`, undefined, options),
             /**
              * Devuelve `{ data: InvoiceResource }`. El tipo NO sale del spec: el
              * `200` de `invoices.store` está vacío ahí (ver {@link ResourceEnvelope}).
@@ -57,8 +57,8 @@ export class PimiaClient {
     }
     get customers() {
         return {
-            list: (query) => this.get('/customers', query),
-            get: (id) => this.get(`/customers/${id}`),
+            list: (query, options) => this.get('/customers', query, options),
+            get: (id, options) => this.get(`/customers/${id}`, undefined, options),
             create: (body, options) => this.post('/customers', body, options),
             /** El `200` de `customers.update` no está tipado en el spec. */
             update: (id, body, options) => this.put(`/customers/${id}`, body, options),
@@ -66,8 +66,8 @@ export class PimiaClient {
     }
     get estimates() {
         return {
-            list: (query) => this.get('/estimates', query),
-            get: (id) => this.get(`/estimates/${id}`),
+            list: (query, options) => this.get('/estimates', query, options),
+            get: (id, options) => this.get(`/estimates/${id}`, undefined, options),
             create: (body, options) => this.post('/estimates', body, options),
             /**
              * Convierte un presupuesto aceptado en factura.
@@ -87,13 +87,33 @@ export class PimiaClient {
              * `estimate:{id}:invoice`— y el reintento tras un timeout no te creará
              * una segunda factura.
              *
+             * Y manda `externalRef` si la venta nació en tu sistema: es lo que hace
+             * que `invoice.created` e `invoice.paid` te lleguen con tu referencia en
+             * vez de con `null`. **Tiene que ir aquí, en la conversión**; etiquetar
+             * después con `PUT /invoices/{id}` llega tarde por dos motivos: para
+             * entonces `invoice.created` ya salió con la referencia nula, y entre las
+             * dos llamadas hay una ventana en la que la factura existe y no la
+             * encuentras por tu referencia.
+             *
+             * Va como opción y no como segundo parámetro para no romperle la llamada
+             * a quien ya hace `convertToInvoice(id, { idempotencyKey })`: el cuerpo lo
+             * monta el atajo, y `external_ref` es además el único campo que el
+             * endpoint acepta.
+             *
              * Exige `estimates:write` **e** `invoices:write`.
              */
-            convertToInvoice: (id, options) => this.post(`/estimates/${id}/convert-to-invoice`, {}, options),
+            convertToInvoice: (id, options) => {
+                const { externalRef, ...resto } = options ?? {};
+                return this.post(`/estimates/${id}/convert-to-invoice`, 
+                // Cuerpo vacío si no se pide, y no `external_ref: null`: mandar el
+                // null explícito DESVINCULA la referencia, que no es lo mismo que no
+                // tocarla.
+                externalRef === undefined ? {} : { external_ref: externalRef }, resto);
+            },
         };
     }
-    get(path, query) {
-        return this.request(path, { method: 'GET', query });
+    get(path, query, options) {
+        return this.request(path, { ...options, method: 'GET', query });
     }
     post(path, body, options) {
         return this.request(path, { ...options, method: 'POST', body });
@@ -104,8 +124,8 @@ export class PimiaClient {
     patch(path, body, options) {
         return this.request(path, { ...options, method: 'PATCH', body });
     }
-    delete(path) {
-        return this.request(path, { method: 'DELETE' });
+    delete(path, options) {
+        return this.request(path, { ...options, method: 'DELETE' });
     }
     /**
      * Petición cruda contra `/api/v1`. `path` puede llevar el prefijo o no:

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * salen los tipos de `./api`.
  */
 export { PimiaClient } from './client.js';
-export type { CustomerRequest, CustomerResource, EstimateResource, EstimatesRequest, InvoiceResource, InvoicesRequest, PimiaClientOptions, RateLimit, RequestOptions, ResourceEnvelope, ResponseMeta, ResponseWithMeta, WriteOptions, } 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';
 export { MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';

package/package.json

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