@pimia/sdk 0.1.0 → 0.3.0

package/dist/client.d.ts

@@ -13,8 +13,42 @@
  *  - **429**: respeta `Retry-After` y reintenta con espera acotada;
  *  - **errores tipados**: MissingScopeError trae el scope exacto que falta.
  */
+import type { components } from './api.js';
 import { OAuth, type OAuthConfig } from './oauth.js';
 import { type TokenStore } from './tokens.js';
+type Schemas = components['schemas'];
+/** Cliente tal y como lo devuelve la API. */
+export type CustomerResource = Schemas['CustomerResource'];
+/** Factura tal y como la devuelve la API. */
+export type InvoiceResource = Schemas['InvoiceResource'];
+/** Presupuesto tal y como lo devuelve la API. */
+export type EstimateResource = Schemas['EstimateResource'];
+/** Cuerpo de alta/edición de cliente. Incluye `customFields`. */
+export type CustomerRequest = Schemas['CustomerRequest'];
+/** Cuerpo de alta/edición de factura. Incluye `customFields`. */
+export type InvoicesRequest = Schemas['InvoicesRequest'];
+/** Cuerpo de alta/edición de presupuesto. Incluye `customFields`. */
+export type EstimatesRequest = Schemas['EstimatesRequest'];
+/**
+ * El sobre `{ data: … }` de Laravel para las escrituras que el spec **no
+ * tipa**.
+ *
+ * Hay 17 operaciones cuyo `200` sale del generador como objeto vacío, y entre
+ * ellas están `POST /invoices`, `PUT /invoices/{id}`, `PUT /customers/{id}` y
+ * `POST /estimates/{id}/convert-to-invoice`. Usar ahí el tipo generado sería
+ * peor que no tipar: `Record<string, never>` afirma que la respuesta **no
+ * tiene propiedades**, y el `data` real desaparecería del autocompletado.
+ *
+ * Así que el sobre se declara aquí y el recurso de dentro sí sale del spec.
+ * Está verificado contra los controladores del core, no supuesto: los cuatro
+ * devuelven `new XResource($modelo)` con el envoltorio `data` de Laravel
+ * activo. La causa del hueco es del generador —un `@return JsonResponse`
+ * heredado que le gana a la inferencia—, no del contrato; cuando se arregle
+ * en el core, estos tipos pasarán a salir de `Ok<…>` como los demás.
+ */
+export interface ResourceEnvelope<T> {
+    data: T;
+}
 export interface PimiaClientOptions extends OAuthConfig {
     tokens: TokenStore;
     /** Segundos de margen para refrescar antes de que caduque (default 60). */
@@ -34,12 +68,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;
@@ -56,32 +128,385 @@ export declare class PimiaClient {
     /** Cabeceras `X-RateLimit-*` de la última respuesta. */
     get rateLimit(): RateLimit;
     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>;
+        list: (query?: RequestOptions["query"]) => Promise<{
+            data: components["schemas"]["InvoiceResource"][];
+            meta: {
+                invoice_total_count: number;
+            };
+        }>;
+        get: (id: number | string) => Promise<{
+            data: components["schemas"]["InvoiceResource"] & Record<string, never>;
+        }>;
+        /**
+         * Devuelve `{ data: InvoiceResource }`. El tipo NO sale del spec: el
+         * `200` de `invoices.store` está vacío ahí (ver {@link ResourceEnvelope}).
+         */
+        create: (body: InvoicesRequest, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: string;
+            invoice_date: string;
+            due_date: string;
+            invoice_number: string;
+            reference_number: string;
+            status: string;
+            paid_status: string;
+            tax_per_item: string;
+            tax_included: string;
+            discount_per_item: string;
+            notes: string;
+            discount_type: string;
+            discount: string;
+            discount_val: string;
+            sub_total: string;
+            total: string;
+            effective_total: string;
+            tax: string;
+            due_amount: string;
+            effective_due_amount: string;
+            sent: string;
+            viewed: string;
+            unique_hash: string;
+            template_name: string;
+            invoice_series_id: string;
+            customer_id: string;
+            payment_method_id: string;
+            recurring_invoice_id: string;
+            sequence_number: string;
+            exchange_rate: string;
+            base_discount_val: string;
+            base_sub_total: string;
+            base_total: string;
+            creator_id: string;
+            base_tax: string;
+            base_due_amount: string;
+            effective_base_total: string;
+            effective_base_due_amount: string;
+            credited_total: string;
+            credited_base_total: string;
+            currency_id: string;
+            formatted_created_at: string;
+            invoice_pdf_url: string;
+            formatted_invoice_date: string;
+            formatted_due_date: string;
+            allow_edit: string;
+            payment_module_enabled: string;
+            sales_tax_type: string;
+            sales_tax_address_type: string;
+            overdue: string;
+            effective_paid_status: string;
+            effective_overdue: string;
+            aeat_status: string;
+            qr_data: string;
+            hash: string;
+            aeat_csv: string;
+            is_credit_note: string | boolean;
+            rectified_invoice_id: string;
+            rectified_invoice_number?: string | null;
+            rectified_invoice?: {
+                id: string;
+                invoice_number: string;
+                tax_per_item: string;
+                tax_included: string;
+                sub_total: string;
+                discount_val: string;
+                tax: string;
+                total: string;
+                items: components["schemas"]["InvoiceItemResource"][];
+                taxes: components["schemas"]["TaxResource"][];
+            };
+            credit_notes_count: number;
+            items?: components["schemas"]["InvoiceItemResource"][];
+            payments?: components["schemas"]["PaymentResource"][];
+            customer?: components["schemas"]["CustomerResource"];
+            invoice_series?: components["schemas"]["InvoiceSeriesResource"];
+            payment_method?: components["schemas"]["PaymentMethodResource"];
+            creator?: components["schemas"]["UserResource"];
+            taxes: components["schemas"]["TaxResource"][];
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            company?: components["schemas"]["CompanyResource"];
+            currency?: components["schemas"]["CurrencyResource"];
+        }>>;
+        /** Mismo caso que `create`: el `200` de `invoices.update` no está tipado en el spec. */
+        update: (id: number | string, body: InvoicesRequest, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: string;
+            invoice_date: string;
+            due_date: string;
+            invoice_number: string;
+            reference_number: string;
+            status: string;
+            paid_status: string;
+            tax_per_item: string;
+            tax_included: string;
+            discount_per_item: string;
+            notes: string;
+            discount_type: string;
+            discount: string;
+            discount_val: string;
+            sub_total: string;
+            total: string;
+            effective_total: string;
+            tax: string;
+            due_amount: string;
+            effective_due_amount: string;
+            sent: string;
+            viewed: string;
+            unique_hash: string;
+            template_name: string;
+            invoice_series_id: string;
+            customer_id: string;
+            payment_method_id: string;
+            recurring_invoice_id: string;
+            sequence_number: string;
+            exchange_rate: string;
+            base_discount_val: string;
+            base_sub_total: string;
+            base_total: string;
+            creator_id: string;
+            base_tax: string;
+            base_due_amount: string;
+            effective_base_total: string;
+            effective_base_due_amount: string;
+            credited_total: string;
+            credited_base_total: string;
+            currency_id: string;
+            formatted_created_at: string;
+            invoice_pdf_url: string;
+            formatted_invoice_date: string;
+            formatted_due_date: string;
+            allow_edit: string;
+            payment_module_enabled: string;
+            sales_tax_type: string;
+            sales_tax_address_type: string;
+            overdue: string;
+            effective_paid_status: string;
+            effective_overdue: string;
+            aeat_status: string;
+            qr_data: string;
+            hash: string;
+            aeat_csv: string;
+            is_credit_note: string | boolean;
+            rectified_invoice_id: string;
+            rectified_invoice_number?: string | null;
+            rectified_invoice?: {
+                id: string;
+                invoice_number: string;
+                tax_per_item: string;
+                tax_included: string;
+                sub_total: string;
+                discount_val: string;
+                tax: string;
+                total: string;
+                items: components["schemas"]["InvoiceItemResource"][];
+                taxes: components["schemas"]["TaxResource"][];
+            };
+            credit_notes_count: number;
+            items?: components["schemas"]["InvoiceItemResource"][];
+            payments?: components["schemas"]["PaymentResource"][];
+            customer?: components["schemas"]["CustomerResource"];
+            invoice_series?: components["schemas"]["InvoiceSeriesResource"];
+            payment_method?: components["schemas"]["PaymentMethodResource"];
+            creator?: components["schemas"]["UserResource"];
+            taxes: components["schemas"]["TaxResource"][];
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            company?: components["schemas"]["CompanyResource"];
+            currency?: components["schemas"]["CurrencyResource"];
+        }>>;
     };
     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>;
+        list: (query?: RequestOptions["query"]) => Promise<{
+            data: components["schemas"]["CustomerResource"][];
+            meta: {
+                customer_total_count: number;
+            };
+        }>;
+        get: (id: number | string) => Promise<{
+            data: components["schemas"]["CustomerResource"];
+        }>;
+        create: (body: CustomerRequest, options?: WriteOptions) => Promise<{
+            data: components["schemas"]["CustomerResource"];
+        }>;
+        /** El `200` de `customers.update` no está tipado en el spec. */
+        update: (id: number | string, body: CustomerRequest, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: string;
+            name: string;
+            email: string;
+            phone: string;
+            contact_name: string;
+            company_name: string;
+            website: string;
+            enable_portal: string;
+            password_added: boolean;
+            currency_id: string;
+            payment_method_id: string;
+            company_id: string;
+            facebook_id: string;
+            google_id: string;
+            github_id: string;
+            created_at: string;
+            formatted_created_at: string;
+            updated_at: string;
+            avatar: string;
+            due_amount: string;
+            base_due_amount: string;
+            prefix: string;
+            tax_id: string;
+            notes: string;
+            iban: string;
+            bic: string;
+            sepa_mandate_id: string;
+            sepa_mandate_date: string;
+            billing?: components["schemas"]["AddressResource"];
+            shipping?: components["schemas"]["AddressResource"];
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            company?: components["schemas"]["CompanyResource"];
+            currency?: components["schemas"]["CurrencyResource"];
+            payment_method?: components["schemas"]["PaymentMethodResource"];
+        }>>;
     };
     get estimates(): {
-        list: (query?: RequestOptions["query"]) => Promise<unknown>;
-        get: (id: number | string) => Promise<unknown>;
-        create: (body: unknown) => Promise<unknown>;
+        list: (query?: RequestOptions["query"]) => Promise<{
+            data: components["schemas"]["EstimateResource"][];
+            meta: {
+                estimate_total_count: number;
+            };
+        }>;
+        get: (id: number | string) => Promise<{
+            data: components["schemas"]["EstimateResource"];
+        }>;
+        create: (body: EstimatesRequest, options?: WriteOptions) => Promise<{
+            data: components["schemas"]["EstimateResource"];
+        }>;
+        /**
+         * Convierte un presupuesto aceptado en factura.
+         *
+         * El helper existe porque es el cierre natural del bucle
+         * `estimate.accepted` → facturar, y sin él hay que ir por ruta cruda y
+         * adivinar la forma de la respuesta.
+         *
+         * Dos cosas que conviene saber y que el spec no dice:
+         *
+         *  - **la factura nace BORRADOR y sin numerar**: `data.invoice_number` es
+         *    `null` hasta que la publiques cambiando su estado. No es un fallo;
+         *  - el id de la factura nueva está en `data.id`. El `r?.data?.id ?? r?.id`
+         *    defensivo que se ve por ahí sobra: la segunda rama nunca ocurre.
+         *
+         * Manda `idempotencyKey` —una clave estable por presupuesto, del estilo
+         * `estimate:{id}:invoice`— y el reintento tras un timeout no te creará
+         * una segunda factura.
+         *
+         * Exige `estimates:write` **e** `invoices:write`.
+         */
+        convertToInvoice: (id: number | string, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: string;
+            invoice_date: string;
+            due_date: string;
+            invoice_number: string;
+            reference_number: string;
+            status: string;
+            paid_status: string;
+            tax_per_item: string;
+            tax_included: string;
+            discount_per_item: string;
+            notes: string;
+            discount_type: string;
+            discount: string;
+            discount_val: string;
+            sub_total: string;
+            total: string;
+            effective_total: string;
+            tax: string;
+            due_amount: string;
+            effective_due_amount: string;
+            sent: string;
+            viewed: string;
+            unique_hash: string;
+            template_name: string;
+            invoice_series_id: string;
+            customer_id: string;
+            payment_method_id: string;
+            recurring_invoice_id: string;
+            sequence_number: string;
+            exchange_rate: string;
+            base_discount_val: string;
+            base_sub_total: string;
+            base_total: string;
+            creator_id: string;
+            base_tax: string;
+            base_due_amount: string;
+            effective_base_total: string;
+            effective_base_due_amount: string;
+            credited_total: string;
+            credited_base_total: string;
+            currency_id: string;
+            formatted_created_at: string;
+            invoice_pdf_url: string;
+            formatted_invoice_date: string;
+            formatted_due_date: string;
+            allow_edit: string;
+            payment_module_enabled: string;
+            sales_tax_type: string;
+            sales_tax_address_type: string;
+            overdue: string;
+            effective_paid_status: string;
+            effective_overdue: string;
+            aeat_status: string;
+            qr_data: string;
+            hash: string;
+            aeat_csv: string;
+            is_credit_note: string | boolean;
+            rectified_invoice_id: string;
+            rectified_invoice_number?: string | null;
+            rectified_invoice?: {
+                id: string;
+                invoice_number: string;
+                tax_per_item: string;
+                tax_included: string;
+                sub_total: string;
+                discount_val: string;
+                tax: string;
+                total: string;
+                items: components["schemas"]["InvoiceItemResource"][];
+                taxes: components["schemas"]["TaxResource"][];
+            };
+            credit_notes_count: number;
+            items?: components["schemas"]["InvoiceItemResource"][];
+            payments?: components["schemas"]["PaymentResource"][];
+            customer?: components["schemas"]["CustomerResource"];
+            invoice_series?: components["schemas"]["InvoiceSeriesResource"];
+            payment_method?: components["schemas"]["PaymentMethodResource"];
+            creator?: components["schemas"]["UserResource"];
+            taxes: components["schemas"]["TaxResource"][];
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            company?: components["schemas"]["CompanyResource"];
+            currency?: components["schemas"]["CurrencyResource"];
+        }>>;
     };
     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
@@ -94,3 +519,4 @@ export declare class PimiaClient {
     private captureRateLimit;
     private retryDelay;
 }
+export {};

package/dist/client.js

@@ -46,36 +46,63 @@ 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),
+            /**
+             * Devuelve `{ data: InvoiceResource }`. El tipo NO sale del spec: el
+             * `200` de `invoices.store` está vacío ahí (ver {@link ResourceEnvelope}).
+             */
+            create: (body, options) => this.post('/invoices', body, options),
+            /** Mismo caso que `create`: el `200` de `invoices.update` no está tipado en el spec. */
+            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),
+            /** El `200` de `customers.update` no está tipado en el spec. */
+            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),
+            /**
+             * Convierte un presupuesto aceptado en factura.
+             *
+             * El helper existe porque es el cierre natural del bucle
+             * `estimate.accepted` → facturar, y sin él hay que ir por ruta cruda y
+             * adivinar la forma de la respuesta.
+             *
+             * Dos cosas que conviene saber y que el spec no dice:
+             *
+             *  - **la factura nace BORRADOR y sin numerar**: `data.invoice_number` es
+             *    `null` hasta que la publiques cambiando su estado. No es un fallo;
+             *  - el id de la factura nueva está en `data.id`. El `r?.data?.id ?? r?.id`
+             *    defensivo que se ve por ahí sobra: la segunda rama nunca ocurre.
+             *
+             * Manda `idempotencyKey` —una clave estable por presupuesto, del estilo
+             * `estimate:{id}:invoice`— y el reintento tras un timeout no te creará
+             * una segunda factura.
+             *
+             * Exige `estimates:write` **e** `invoices:write`.
+             */
+            convertToInvoice: (id, options) => this.post(`/estimates/${id}/convert-to-invoice`, {}, 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 +112,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 +146,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 +159,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,12 +6,14 @@
  * salen los tipos de `./api`.
  */
 export { PimiaClient } from './client.js';
-export type { PimiaClientOptions, RateLimit, RequestOptions } from './client.js';
+export type { CustomerRequest, CustomerResource, EstimateResource, EstimatesRequest, InvoiceResource, InvoicesRequest, PimiaClientOptions, RateLimit, 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';
 export type { TokenSet, TokenStore } from './tokens.js';
 export { ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
+export { WEBHOOK_DEFAULT_TOLERANCE_SECONDS, WEBHOOK_EVENTS, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_VERSION, WebhookVerificationError, isWebhookEvent, signWebhook, verifyWebhook, } from './webhooks.js';
+export type { ApprovalDecidedPayload, AppRevokedPayload, CustomerPayload, EstimateAcceptedPayload, InvoiceCreatedPayload, InvoicePaidPayload, InvoiceReceivedPayload, IsoDateTime, KnownWebhook, PimiaWebhook, SignWebhookOptions, UnknownWebhook, VerifyWebhookOptions, WebhookBodyInput, WebhookEvent, WebhookHeadersInput, WebhookPayloads, WebhookVerificationReason, } from './webhooks.js';
 /** Scopes granulares del catálogo de Pimia (paso 4). Pide siempre lo mínimo. */
 export declare const SCOPES: {
     readonly invoicesRead: "invoices:read";
@@ -33,5 +35,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

@@ -9,6 +9,7 @@ export { PimiaClient } from './client.js';
 export { OAuth, createPkceChallenge, createState } from './oauth.js';
 export { MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
 export { ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
+export { WEBHOOK_DEFAULT_TOLERANCE_SECONDS, WEBHOOK_EVENTS, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_VERSION, WebhookVerificationError, isWebhookEvent, signWebhook, verifyWebhook, } from './webhooks.js';
 /** Scopes granulares del catálogo de Pimia (paso 4). Pide siempre lo mínimo. */
 export const SCOPES = {
     invoicesRead: 'invoices:read',
@@ -30,4 +31,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',
 };