@pimia/sdk 0.11.0 → 0.13.0

package/dist/client.d.ts

@@ -23,12 +23,29 @@ export type CustomerResource = Schemas['CustomerResource'];
 export type InvoiceResource = Schemas['InvoiceResource'];
 /** Presupuesto tal y como lo devuelve la API. */
 export type EstimateResource = Schemas['EstimateResource'];
+/** Contrato de servicio tal y como lo devuelve la API. */
+export type ContractResource = Schemas['ContractResource'];
+/** Almacén tal y como lo devuelve la API. */
+export type WarehouseResource = Schemas['WarehouseResource'];
+/** El saldo de un artículo EN un almacén. */
+export type ItemWarehouseStockResource = Schemas['ItemWarehouseStockResource'];
 /** 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'];
+/**
+ * Cuerpo de alta/edición de contrato. Sin `status` a propósito: el ciclo de
+ * vida va por sus acciones (`activate`/`cancel`/`renew`), nunca por el PUT.
+ */
+export type ContractRequest = Schemas['ContractRequest'];
+/**
+ * Cuerpo de alta/edición de almacén. `is_default` se manda como INTENCIÓN
+ * («que este sea el de por defecto»): el servidor apaga el anterior en la
+ * misma transacción, porque la empresa necesita exactamente uno.
+ */
+export type WarehouseRequest = Schemas['WarehouseRequest'];
 /**
  * El sobre `{ data: … }` de Laravel para las escrituras que el spec **no
  * tipa**.
@@ -561,6 +578,289 @@ export declare class PimiaClient {
             currency?: components["schemas"]["CurrencyResource"] | null;
         }>>;
     };
+    /**
+     * Contratos de servicio. Exige `contracts:read` / `contracts:write`.
+     *
+     * Un contrato GOBIERNA facturas recurrentes: su periodo se vuelve los
+     * límites de la recurrente. El ciclo de vida va por sus acciones — el
+     * `PUT` no acepta `status`, y fuera de borrador solo toca lo descriptivo
+     * (el periodo se cambia con `renew`, que sí propaga).
+     */
+    get contracts(): {
+        list: (query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
+            data: components["schemas"]["ContractResource"][];
+            meta: {
+                contract_total_count: number;
+            };
+        }>;
+        get: (id: number | string, options?: ReadOptions) => Promise<{
+            data: components["schemas"]["ContractResource"];
+        }>;
+        create: (body: ContractRequest, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: number;
+            title: string;
+            description: string | null;
+            contract_number: string | null;
+            customer_id: number | null;
+            company_id: number | null;
+            creator_id: number | null;
+            currency_id: number | null;
+            status: string;
+            ha_vencido: boolean;
+            starts_at: string | null;
+            ends_at: string | null;
+            amount: number | null;
+            billing_every: string;
+            billing_anchor_day: number | null;
+            renewal_mode: string;
+            notice_days: number | null;
+            notice_days_effective: number;
+            has_document: boolean;
+            estimate_id: number | null;
+            cancelled_at: string | null;
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            customer?: components["schemas"]["CustomerResource"] | null;
+            estimate?: components["schemas"]["EstimateResource"] | null;
+            recurring_invoices?: components["schemas"]["RecurringInvoiceResource"][];
+            invoices?: components["schemas"]["InvoiceResource"][];
+        }>>;
+        update: (id: number | string, body: ContractRequest, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: number;
+            title: string;
+            description: string | null;
+            contract_number: string | null;
+            customer_id: number | null;
+            company_id: number | null;
+            creator_id: number | null;
+            currency_id: number | null;
+            status: string;
+            ha_vencido: boolean;
+            starts_at: string | null;
+            ends_at: string | null;
+            amount: number | null;
+            billing_every: string;
+            billing_anchor_day: number | null;
+            renewal_mode: string;
+            notice_days: number | null;
+            notice_days_effective: number;
+            has_document: boolean;
+            estimate_id: number | null;
+            cancelled_at: string | null;
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            customer?: components["schemas"]["CustomerResource"] | null;
+            estimate?: components["schemas"]["EstimateResource"] | null;
+            recurring_invoices?: components["schemas"]["RecurringInvoiceResource"][];
+            invoices?: components["schemas"]["InvoiceResource"][];
+        }>>;
+        /**
+         * Activa el contrato: DRAFT → ACTIVE, lo numera, y crea la recurrente
+         * gobernada — o adopta la de `recurringInvoiceId` (misma empresa y
+         * mismo cliente; sus líneas e impuestos no se tocan).
+         *
+         * Exige `contracts:write` **e** `invoices:write`: la recurrente que
+         * nace emitirá facturas por su cuenta. Manda `idempotencyKey` —una
+         * clave estable del estilo `contract:{id}:activate`— y el reintento
+         * tras un timeout no te creará una segunda recurrente.
+         */
+        activate: (id: number | string, options?: WriteOptions & {
+            recurringInvoiceId?: number | string;
+        }) => Promise<ResourceEnvelope<{
+            id: number;
+            title: string;
+            description: string | null;
+            contract_number: string | null;
+            customer_id: number | null;
+            company_id: number | null;
+            creator_id: number | null;
+            currency_id: number | null;
+            status: string;
+            ha_vencido: boolean;
+            starts_at: string | null;
+            ends_at: string | null;
+            amount: number | null;
+            billing_every: string;
+            billing_anchor_day: number | null;
+            renewal_mode: string;
+            notice_days: number | null;
+            notice_days_effective: number;
+            has_document: boolean;
+            estimate_id: number | null;
+            cancelled_at: string | null;
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            customer?: components["schemas"]["CustomerResource"] | null;
+            estimate?: components["schemas"]["EstimateResource"] | null;
+            recurring_invoices?: components["schemas"]["RecurringInvoiceResource"][];
+            invoices?: components["schemas"]["InvoiceResource"][];
+        }>>;
+        /**
+         * Cancela: sus recurrentes quedan en pausa (`ON_HOLD`) y las facturas
+         * emitidas conservan el rastro entero.
+         */
+        cancel: (id: number | string, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: number;
+            title: string;
+            description: string | null;
+            contract_number: string | null;
+            customer_id: number | null;
+            company_id: number | null;
+            creator_id: number | null;
+            currency_id: number | null;
+            status: string;
+            ha_vencido: boolean;
+            starts_at: string | null;
+            ends_at: string | null;
+            amount: number | null;
+            billing_every: string;
+            billing_anchor_day: number | null;
+            renewal_mode: string;
+            notice_days: number | null;
+            notice_days_effective: number;
+            has_document: boolean;
+            estimate_id: number | null;
+            cancelled_at: string | null;
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            customer?: components["schemas"]["CustomerResource"] | null;
+            estimate?: components["schemas"]["EstimateResource"] | null;
+            recurring_invoices?: components["schemas"]["RecurringInvoiceResource"][];
+            invoices?: components["schemas"]["InvoiceResource"][];
+        }>>;
+        /**
+         * Renovación manual: extiende `ends_at` (posterior al fin actual) y lo
+         * propaga a las recurrentes gobernadas, reviviendo las completadas por
+         * el límite viejo.
+         */
+        renew: (id: number | string, endsAt: string, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: number;
+            title: string;
+            description: string | null;
+            contract_number: string | null;
+            customer_id: number | null;
+            company_id: number | null;
+            creator_id: number | null;
+            currency_id: number | null;
+            status: string;
+            ha_vencido: boolean;
+            starts_at: string | null;
+            ends_at: string | null;
+            amount: number | null;
+            billing_every: string;
+            billing_anchor_day: number | null;
+            renewal_mode: string;
+            notice_days: number | null;
+            notice_days_effective: number;
+            has_document: boolean;
+            estimate_id: number | null;
+            cancelled_at: string | null;
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            customer?: components["schemas"]["CustomerResource"] | null;
+            estimate?: components["schemas"]["EstimateResource"] | null;
+            recurring_invoices?: components["schemas"]["RecurringInvoiceResource"][];
+            invoices?: components["schemas"]["InvoiceResource"][];
+        }>>;
+        /**
+         * El enlace del PDF para el cliente final: URL FIRMADA con caducidad.
+         * Un contrato en borrador —sin número— es un 422.
+         */
+        sharedLink: (id: number | string, options?: ReadOptions) => Promise<{
+            data: {
+                url: string;
+                expires_at: string;
+            };
+        }>;
+        /**
+         * Sube (o reemplaza: un fichero por colección) el contrato FIRMADO —
+         * el papel escaneado. Multiparte por `POST` dedicado; el `FormData` lo
+         * arma el atajo, no le pongas `content-type`.
+         */
+        uploadDocument: (id: number | string, document: Blob, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: number;
+            title: string;
+            description: string | null;
+            contract_number: string | null;
+            customer_id: number | null;
+            company_id: number | null;
+            creator_id: number | null;
+            currency_id: number | null;
+            status: string;
+            ha_vencido: boolean;
+            starts_at: string | null;
+            ends_at: string | null;
+            amount: number | null;
+            billing_every: string;
+            billing_anchor_day: number | null;
+            renewal_mode: string;
+            notice_days: number | null;
+            notice_days_effective: number;
+            has_document: boolean;
+            estimate_id: number | null;
+            cancelled_at: string | null;
+            fields?: components["schemas"]["CustomFieldValueResource"][];
+            customer?: components["schemas"]["CustomerResource"] | null;
+            estimate?: components["schemas"]["EstimateResource"] | null;
+            recurring_invoices?: components["schemas"]["RecurringInvoiceResource"][];
+            invoices?: components["schemas"]["InvoiceResource"][];
+        }>>;
+    };
+    /**
+     * Almacenes: la DIMENSIÓN del stock. Exige `items:read` / `items:write` —
+     * el almacén cuelga del catálogo que dimensiona, sin scope propio.
+     *
+     * ⚠️ **Vive tras el módulo `stock`, que es opt-in**: si la empresa no lo ha
+     * instalado, estas rutas responden `403` con `error: module_not_installed`,
+     * y eso NO es un problema de permisos. El libro de movimientos, el ajuste
+     * con motivo y la mercancía recibida son de todos y no pasan por aquí.
+     *
+     * Exactamente un almacén lleva `is_default`, y es el que hereda todo
+     * movimiento que no elige otro. El saldo por almacén es el REPARTO del
+     * contador global: su suma por artículo es exactamente `opening_stock`.
+     */
+    get warehouses(): {
+        list: (query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
+            data: components["schemas"]["WarehouseResource"][];
+        }>;
+        get: (id: number | string, options?: ReadOptions) => Promise<{
+            data: components["schemas"]["WarehouseResource"];
+        }>;
+        create: (body: WarehouseRequest, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: number;
+            name: string;
+            code: string | null;
+            address: string | null;
+            is_default: boolean;
+            is_active: boolean;
+            created_at: string | null;
+            updated_at: string | null;
+        }>>;
+        update: (id: number | string, body: WarehouseRequest, options?: WriteOptions) => Promise<ResourceEnvelope<{
+            id: number;
+            name: string;
+            code: string | null;
+            address: string | null;
+            is_default: boolean;
+            is_active: boolean;
+            created_at: string | null;
+            updated_at: string | null;
+        }>>;
+        /**
+         * Borra un almacén VACÍO y sin historia. Tres negativas con su código:
+         * `default_warehouse_required`, `stock_movements_attached` (su pasado
+         * explica saldos de hoy) y `stock_attached`. Para el que ya no se usa,
+         * `update` con `is_active: false`.
+         */
+        delete: (id: number | string, options?: ReadOptions) => Promise<{
+            success: string;
+        }>;
+        /**
+         * Las existencias de UN almacén, artículo a artículo — la pregunta que
+         * la dimensión vino a contestar. `only_with_stock` deja fuera los ceros.
+         */
+        stock: (id: number | string, query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
+            data: components["schemas"]["ItemWarehouseStockResource"][];
+            meta: {
+                warehouse: components["schemas"]["WarehouseResource"];
+            };
+        }>;
+    };
     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>;

package/dist/client.js

@@ -112,6 +112,91 @@ export class PimiaClient {
             },
         };
     }
+    /**
+     * Contratos de servicio. Exige `contracts:read` / `contracts:write`.
+     *
+     * Un contrato GOBIERNA facturas recurrentes: su periodo se vuelve los
+     * límites de la recurrente. El ciclo de vida va por sus acciones — el
+     * `PUT` no acepta `status`, y fuera de borrador solo toca lo descriptivo
+     * (el periodo se cambia con `renew`, que sí propaga).
+     */
+    get contracts() {
+        return {
+            list: (query, options) => this.get('/contracts', query, options),
+            get: (id, options) => this.get(`/contracts/${id}`, undefined, options),
+            create: (body, options) => this.post('/contracts', body, options),
+            update: (id, body, options) => this.put(`/contracts/${id}`, body, options),
+            /**
+             * Activa el contrato: DRAFT → ACTIVE, lo numera, y crea la recurrente
+             * gobernada — o adopta la de `recurringInvoiceId` (misma empresa y
+             * mismo cliente; sus líneas e impuestos no se tocan).
+             *
+             * Exige `contracts:write` **e** `invoices:write`: la recurrente que
+             * nace emitirá facturas por su cuenta. Manda `idempotencyKey` —una
+             * clave estable del estilo `contract:{id}:activate`— y el reintento
+             * tras un timeout no te creará una segunda recurrente.
+             */
+            activate: (id, options) => {
+                const { recurringInvoiceId, ...resto } = options ?? {};
+                return this.post(`/contracts/${id}/activate`, recurringInvoiceId === undefined ? {} : { recurring_invoice_id: recurringInvoiceId }, resto);
+            },
+            /**
+             * Cancela: sus recurrentes quedan en pausa (`ON_HOLD`) y las facturas
+             * emitidas conservan el rastro entero.
+             */
+            cancel: (id, options) => this.post(`/contracts/${id}/cancel`, {}, options),
+            /**
+             * Renovación manual: extiende `ends_at` (posterior al fin actual) y lo
+             * propaga a las recurrentes gobernadas, reviviendo las completadas por
+             * el límite viejo.
+             */
+            renew: (id, endsAt, options) => this.post(`/contracts/${id}/renew`, { ends_at: endsAt }, options),
+            /**
+             * El enlace del PDF para el cliente final: URL FIRMADA con caducidad.
+             * Un contrato en borrador —sin número— es un 422.
+             */
+            sharedLink: (id, options) => this.get(`/contracts/${id}/shared-link`, undefined, options),
+            /**
+             * Sube (o reemplaza: un fichero por colección) el contrato FIRMADO —
+             * el papel escaneado. Multiparte por `POST` dedicado; el `FormData` lo
+             * arma el atajo, no le pongas `content-type`.
+             */
+            uploadDocument: (id, document, options) => this.post(`/contracts/${id}/document`, toFormData({ document }), options),
+        };
+    }
+    /**
+     * Almacenes: la DIMENSIÓN del stock. Exige `items:read` / `items:write` —
+     * el almacén cuelga del catálogo que dimensiona, sin scope propio.
+     *
+     * ⚠️ **Vive tras el módulo `stock`, que es opt-in**: si la empresa no lo ha
+     * instalado, estas rutas responden `403` con `error: module_not_installed`,
+     * y eso NO es un problema de permisos. El libro de movimientos, el ajuste
+     * con motivo y la mercancía recibida son de todos y no pasan por aquí.
+     *
+     * Exactamente un almacén lleva `is_default`, y es el que hereda todo
+     * movimiento que no elige otro. El saldo por almacén es el REPARTO del
+     * contador global: su suma por artículo es exactamente `opening_stock`.
+     */
+    get warehouses() {
+        return {
+            list: (query, options) => this.get('/warehouses', query, options),
+            get: (id, options) => this.get(`/warehouses/${id}`, undefined, options),
+            create: (body, options) => this.post('/warehouses', body, options),
+            update: (id, body, options) => this.put(`/warehouses/${id}`, body, options),
+            /**
+             * Borra un almacén VACÍO y sin historia. Tres negativas con su código:
+             * `default_warehouse_required`, `stock_movements_attached` (su pasado
+             * explica saldos de hoy) y `stock_attached`. Para el que ya no se usa,
+             * `update` con `is_active: false`.
+             */
+            delete: (id, options) => this.delete(`/warehouses/${id}`, options),
+            /**
+             * Las existencias de UN almacén, artículo a artículo — la pregunta que
+             * la dimensión vino a contestar. `only_with_stock` deja fuera los ceros.
+             */
+            stock: (id, query, options) => this.get(`/warehouses/${id}/stock`, query, options),
+        };
+    }
     get(path, query, options) {
         return this.request(path, { ...options, method: 'GET', query });
     }

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * salen los tipos de `./api`.
  */
 export { PimiaClient, toFormData } from './client.js';
-export type { CustomerRequest, CustomerResource, EstimateResource, EstimatesRequest, InvoiceResource, InvoicesRequest, PimiaClientOptions, RateLimit, ReadOptions, RequestOptions, ResourceEnvelope, ResponseMeta, ResponseWithMeta, WriteOptions, } from './client.js';
+export type { ContractRequest, ContractResource, CustomerRequest, CustomerResource, EstimateResource, EstimatesRequest, InvoiceResource, InvoicesRequest, ItemWarehouseStockResource, PimiaClientOptions, RateLimit, ReadOptions, RequestOptions, ResourceEnvelope, ResponseMeta, ResponseWithMeta, WarehouseRequest, WarehouseResource, 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';
@@ -20,6 +20,14 @@ export declare const SCOPES: {
     readonly invoicesWrite: "invoices:write";
     readonly estimatesRead: "estimates:read";
     readonly estimatesWrite: "estimates:write";
+    /** Leer contratos de servicio: periodo, estado, sus recurrentes. */
+    readonly contractsRead: "contracts:read";
+    /**
+     * Gestionar contratos: crear, activar, renovar y cancelar — pueden
+     * comprometer periodos de facturación futuros. Activar exige además
+     * `invoices:write` (la recurrente que nace emitirá facturas por su cuenta).
+     */
+    readonly contractsWrite: "contracts:write";
     readonly customersRead: "customers:read";
     readonly customersWrite: "customers:write";
     readonly expensesRead: "expenses:read";

package/dist/index.js

@@ -16,6 +16,14 @@ export const SCOPES = {
     invoicesWrite: 'invoices:write',
     estimatesRead: 'estimates:read',
     estimatesWrite: 'estimates:write',
+    /** Leer contratos de servicio: periodo, estado, sus recurrentes. */
+    contractsRead: 'contracts:read',
+    /**
+     * Gestionar contratos: crear, activar, renovar y cancelar — pueden
+     * comprometer periodos de facturación futuros. Activar exige además
+     * `invoices:write` (la recurrente que nace emitirá facturas por su cuenta).
+     */
+    contractsWrite: 'contracts:write',
     customersRead: 'customers:read',
     customersWrite: 'customers:write',
     expensesRead: 'expenses:read',

package/package.json

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