@pimia/sdk 0.2.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). */
@@ -94,21 +128,357 @@ 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, options?: WriteOptions) => Promise<unknown>;
-        update: (id: number | string, body: unknown, options?: WriteOptions) => 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, options?: WriteOptions) => Promise<unknown>;
-        update: (id: number | string, body: unknown, options?: WriteOptions) => 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, options?: WriteOptions) => 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, options?: WriteOptions): Promise<T>;
@@ -149,3 +519,4 @@ export declare class PimiaClient {
     private captureRateLimit;
     private retryDelay;
 }
+export {};

package/dist/client.js

@@ -46,7 +46,12 @@ export class PimiaClient {
         return {
             list: (query) => this.get('/invoices', query),
             get: (id) => this.get(`/invoices/${id}`),
+            /**
+             * 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),
         };
     }
@@ -55,6 +60,7 @@ export class PimiaClient {
             list: (query) => this.get('/customers', query),
             get: (id) => this.get(`/customers/${id}`),
             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),
         };
     }
@@ -63,6 +69,27 @@ export class PimiaClient {
             list: (query) => this.get('/estimates', query),
             get: (id) => this.get(`/estimates/${id}`),
             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) {

package/dist/index.d.ts

@@ -6,12 +6,14 @@
  * salen los tipos de `./api`.
  */
 export { PimiaClient } from './client.js';
-export type { PimiaClientOptions, RateLimit, RequestOptions, ResponseMeta, ResponseWithMeta, WriteOptions, } 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";

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',