@pimia/sdk 0.5.0 → 0.7.0

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;
     /**
@@ -146,6 +181,11 @@ export declare class PimiaClient {
             meta: {
                 invoice_total_count: number;
             };
+        } | {
+            data: components["schemas"]["InvoiceSummaryResource"][];
+            meta: {
+                invoice_total_count: number;
+            };
         }>;
         get: (id: number | string, options?: ReadOptions) => Promise<{
             data: components["schemas"]["InvoiceResource"] & Record<string, never>;
@@ -155,175 +195,177 @@ export declare class PimiaClient {
          * `200` de `invoices.store` está vacío ahí (ver {@link ResourceEnvelope}).
          */
         create: (body: InvoicesRequest, options?: WriteOptions) => Promise<ResourceEnvelope<{
-            id: string;
+            id: number;
             invoice_date: string;
-            due_date: string;
-            invoice_number: string;
+            due_date: string | null;
+            invoice_number: string | null;
             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;
+            notes: string | null;
+            discount_type: string | null;
+            discount: number;
+            discount_val: number;
+            sub_total: number;
+            total: number;
             effective_total: string;
-            tax: string;
+            tax: number;
             due_amount: string;
             effective_due_amount: string;
             sent: string;
             viewed: string;
-            unique_hash: string;
-            template_name: string;
+            sent_at: string;
+            viewed_at: string;
+            unique_hash: string | null;
+            template_name: string | null;
             invoice_series_id: string;
-            customer_id: string;
+            customer_id: number | null;
             external_ref: string | null;
             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;
+            sequence_number: number | null;
+            exchange_rate: number | null;
+            base_discount_val: string | null;
+            base_sub_total: string | null;
+            base_total: string | null;
+            creator_id: number | null;
+            base_tax: string | null;
+            base_due_amount: string | null;
             effective_base_total: string;
             effective_base_due_amount: string;
             credited_total: string;
             credited_base_total: string;
-            currency_id: string;
+            currency_id: number | null;
             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;
+            qr_data: string | null;
+            hash: string | null;
+            aeat_csv: string | null;
+            is_credit_note: boolean;
+            rectified_invoice_id: number | null;
             rectified_invoice_number?: string | null;
             rectified_invoice?: {
-                id: string;
-                invoice_number: string;
+                id: number;
+                invoice_number: string | null;
                 tax_per_item: string;
                 tax_included: string;
-                sub_total: string;
-                discount_val: string;
-                tax: string;
-                total: string;
+                sub_total: number;
+                discount_val: number;
+                tax: number;
+                total: number;
                 items: components["schemas"]["InvoiceItemResource"][];
                 taxes: components["schemas"]["TaxResource"][];
             };
-            credit_notes_count: number;
+            credit_notes_count: string | number;
             items?: components["schemas"]["InvoiceItemResource"][];
             payments?: components["schemas"]["PaymentResource"][];
-            customer?: components["schemas"]["CustomerResource"];
+            email_logs?: components["schemas"]["EmailLogResource"][];
+            customer?: components["schemas"]["CustomerResource"] | null;
             invoice_series?: components["schemas"]["InvoiceSeriesResource"];
             payment_method?: components["schemas"]["PaymentMethodResource"];
-            creator?: components["schemas"]["UserResource"];
+            creator?: components["schemas"]["UserResource"] | null;
             taxes: components["schemas"]["TaxResource"][];
             fields?: components["schemas"]["CustomFieldValueResource"][];
-            company?: components["schemas"]["CompanyResource"];
-            currency?: components["schemas"]["CurrencyResource"];
+            company?: components["schemas"]["CompanyResource"] | null;
+            currency?: components["schemas"]["CurrencyResource"] | null;
         }>>;
         /** 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;
+            id: number;
             invoice_date: string;
-            due_date: string;
-            invoice_number: string;
+            due_date: string | null;
+            invoice_number: string | null;
             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;
+            notes: string | null;
+            discount_type: string | null;
+            discount: number;
+            discount_val: number;
+            sub_total: number;
+            total: number;
             effective_total: string;
-            tax: string;
+            tax: number;
             due_amount: string;
             effective_due_amount: string;
             sent: string;
             viewed: string;
-            unique_hash: string;
-            template_name: string;
+            sent_at: string;
+            viewed_at: string;
+            unique_hash: string | null;
+            template_name: string | null;
             invoice_series_id: string;
-            customer_id: string;
+            customer_id: number | null;
             external_ref: string | null;
             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;
+            sequence_number: number | null;
+            exchange_rate: number | null;
+            base_discount_val: string | null;
+            base_sub_total: string | null;
+            base_total: string | null;
+            creator_id: number | null;
+            base_tax: string | null;
+            base_due_amount: string | null;
             effective_base_total: string;
             effective_base_due_amount: string;
             credited_total: string;
             credited_base_total: string;
-            currency_id: string;
+            currency_id: number | null;
             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;
+            qr_data: string | null;
+            hash: string | null;
+            aeat_csv: string | null;
+            is_credit_note: boolean;
+            rectified_invoice_id: number | null;
             rectified_invoice_number?: string | null;
             rectified_invoice?: {
-                id: string;
-                invoice_number: string;
+                id: number;
+                invoice_number: string | null;
                 tax_per_item: string;
                 tax_included: string;
-                sub_total: string;
-                discount_val: string;
-                tax: string;
-                total: string;
+                sub_total: number;
+                discount_val: number;
+                tax: number;
+                total: number;
                 items: components["schemas"]["InvoiceItemResource"][];
                 taxes: components["schemas"]["TaxResource"][];
             };
-            credit_notes_count: number;
+            credit_notes_count: string | number;
             items?: components["schemas"]["InvoiceItemResource"][];
             payments?: components["schemas"]["PaymentResource"][];
-            customer?: components["schemas"]["CustomerResource"];
+            email_logs?: components["schemas"]["EmailLogResource"][];
+            customer?: components["schemas"]["CustomerResource"] | null;
             invoice_series?: components["schemas"]["InvoiceSeriesResource"];
             payment_method?: components["schemas"]["PaymentMethodResource"];
-            creator?: components["schemas"]["UserResource"];
+            creator?: components["schemas"]["UserResource"] | null;
             taxes: components["schemas"]["TaxResource"][];
             fields?: components["schemas"]["CustomFieldValueResource"][];
-            company?: components["schemas"]["CompanyResource"];
-            currency?: components["schemas"]["CurrencyResource"];
+            company?: components["schemas"]["CompanyResource"] | null;
+            currency?: components["schemas"]["CurrencyResource"] | null;
         }>>;
     };
     get customers(): {
@@ -332,6 +374,11 @@ export declare class PimiaClient {
             meta: {
                 customer_total_count: number;
             };
+        } | {
+            data: components["schemas"]["CustomerSummaryResource"][];
+            meta: {
+                customer_total_count: number;
+            };
         }>;
         get: (id: number | string, options?: ReadOptions) => Promise<{
             data: components["schemas"]["CustomerResource"];
@@ -341,40 +388,36 @@ export declare class PimiaClient {
         }>;
         /** El `200` de `customers.update` no está tipado en el spec. */
         update: (id: number | string, body: CustomerRequest, options?: WriteOptions) => Promise<ResourceEnvelope<{
-            id: string;
+            id: number;
             name: string;
-            email: string;
-            phone: string;
-            contact_name: string;
-            company_name: string;
-            website: string;
-            enable_portal: string;
+            email: string | null;
+            phone: string | null;
+            contact_name: string | null;
+            website: string | null;
+            enable_portal: boolean;
             password_added: boolean;
-            currency_id: string;
+            currency_id: number | null;
             payment_method_id: string;
-            company_id: string;
-            facebook_id: string;
-            google_id: string;
-            github_id: string;
-            created_at: string;
+            company_id: number | null;
+            created_at: string | null;
             formatted_created_at: string;
-            updated_at: string;
+            updated_at: string | null;
             avatar: string;
             due_amount: string;
             base_due_amount: string;
-            prefix: string;
+            prefix: string | null;
             tax_id: string;
             notes: string;
             external_ref: string | null;
-            iban: string;
-            bic: string;
-            sepa_mandate_id: string;
-            sepa_mandate_date: string;
-            billing?: components["schemas"]["AddressResource"];
-            shipping?: components["schemas"]["AddressResource"];
+            iban: string | null;
+            bic: string | null;
+            sepa_mandate_id: string | null;
+            sepa_mandate_date: string | null;
+            billing?: components["schemas"]["AddressResource"] | null;
+            shipping?: components["schemas"]["AddressResource"] | null;
             fields?: components["schemas"]["CustomFieldValueResource"][];
-            company?: components["schemas"]["CompanyResource"];
-            currency?: components["schemas"]["CurrencyResource"];
+            company?: components["schemas"]["CompanyResource"] | null;
+            currency?: components["schemas"]["CurrencyResource"] | null;
             payment_method?: components["schemas"]["PaymentMethodResource"];
         }>>;
     };
@@ -384,9 +427,14 @@ export declare class PimiaClient {
             meta: {
                 estimate_total_count: number;
             };
+        } | {
+            data: components["schemas"]["EstimateSummaryResource"][];
+            meta: {
+                estimate_total_count: number;
+            };
         }>;
         get: (id: number | string, options?: ReadOptions) => Promise<{
-            data: components["schemas"]["EstimateResource"];
+            data: components["schemas"]["EstimateResource"] & Record<string, never>;
         }>;
         create: (body: EstimatesRequest, options?: WriteOptions) => Promise<{
             data: components["schemas"]["EstimateResource"];
@@ -427,89 +475,90 @@ export declare class PimiaClient {
         convertToInvoice: (id: number | string, options?: WriteOptions & {
             externalRef?: string | null;
         }) => Promise<ResourceEnvelope<{
-            id: string;
+            id: number;
             invoice_date: string;
-            due_date: string;
-            invoice_number: string;
+            due_date: string | null;
+            invoice_number: string | null;
             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;
+            notes: string | null;
+            discount_type: string | null;
+            discount: number;
+            discount_val: number;
+            sub_total: number;
+            total: number;
             effective_total: string;
-            tax: string;
+            tax: number;
             due_amount: string;
             effective_due_amount: string;
             sent: string;
             viewed: string;
-            unique_hash: string;
-            template_name: string;
+            sent_at: string;
+            viewed_at: string;
+            unique_hash: string | null;
+            template_name: string | null;
             invoice_series_id: string;
-            customer_id: string;
+            customer_id: number | null;
             external_ref: string | null;
             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;
+            sequence_number: number | null;
+            exchange_rate: number | null;
+            base_discount_val: string | null;
+            base_sub_total: string | null;
+            base_total: string | null;
+            creator_id: number | null;
+            base_tax: string | null;
+            base_due_amount: string | null;
             effective_base_total: string;
             effective_base_due_amount: string;
             credited_total: string;
             credited_base_total: string;
-            currency_id: string;
+            currency_id: number | null;
             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;
+            qr_data: string | null;
+            hash: string | null;
+            aeat_csv: string | null;
+            is_credit_note: boolean;
+            rectified_invoice_id: number | null;
             rectified_invoice_number?: string | null;
             rectified_invoice?: {
-                id: string;
-                invoice_number: string;
+                id: number;
+                invoice_number: string | null;
                 tax_per_item: string;
                 tax_included: string;
-                sub_total: string;
-                discount_val: string;
-                tax: string;
-                total: string;
+                sub_total: number;
+                discount_val: number;
+                tax: number;
+                total: number;
                 items: components["schemas"]["InvoiceItemResource"][];
                 taxes: components["schemas"]["TaxResource"][];
             };
-            credit_notes_count: number;
+            credit_notes_count: string | number;
             items?: components["schemas"]["InvoiceItemResource"][];
             payments?: components["schemas"]["PaymentResource"][];
-            customer?: components["schemas"]["CustomerResource"];
+            email_logs?: components["schemas"]["EmailLogResource"][];
+            customer?: components["schemas"]["CustomerResource"] | null;
             invoice_series?: components["schemas"]["InvoiceSeriesResource"];
             payment_method?: components["schemas"]["PaymentMethodResource"];
-            creator?: components["schemas"]["UserResource"];
+            creator?: components["schemas"]["UserResource"] | null;
             taxes: components["schemas"]["TaxResource"][];
             fields?: components["schemas"]["CustomFieldValueResource"][];
-            company?: components["schemas"]["CompanyResource"];
-            currency?: components["schemas"]["CurrencyResource"];
+            company?: components["schemas"]["CompanyResource"] | null;
+            currency?: components["schemas"]["CurrencyResource"] | null;
         }>>;
     };
     get<T = unknown>(path: string, query?: RequestOptions['query'], options?: ReadOptions): Promise<T>;
@@ -517,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.
@@ -551,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 {};