@pimia/sdk 0.15.0 → 0.16.0

package/dist/api.d.ts

@@ -8202,6 +8202,15 @@ export interface components {
             is_active: boolean;
             is_time_trackable: boolean;
             opening_stock: number;
+            /**
+             * @description Lo COMPROMETIDO por documentos que aún no han movido el almacén
+             *     (N2 · pieza 3, cifra derivada — nadie la escribe). ⚠️ `null` NO
+             *     es cero: es «no se está calculando» (módulo `stock` sin
+             *     instalar, o el ciclo de inventario apagado). Pintar un 0 ahí
+             *     afirmaría «nada comprometido», que es lo que no se sabe.
+             *     El porqué entero, en {@see \App\Support\StockCommitments}.
+             */
+            committed_quantity: number | null;
             stock_alert_qty: number | null;
             allow_sale_without_stock: boolean;
             purchase_tax_type_id: number | null;
@@ -8245,6 +8254,13 @@ export interface components {
             is_active: boolean;
             is_time_trackable: boolean;
             opening_stock: number;
+            /**
+             * @description Igual que en el recurso completo: `null` es «no se está
+             *     calculando», no cero (N2 · pieza 3). La celda de stock del
+             *     listado del panel lo lee de aquí — el índice del catálogo va
+             *     por `?view=summary`.
+             */
+            committed_quantity: number | null;
             stock_alert_qty: number | null;
             allow_sale_without_stock: boolean;
             /** Format: date-time */
@@ -8270,6 +8286,15 @@ export interface components {
             item_name: string;
             warehouse_id: number;
             quantity: number;
+            /**
+             * @description Lo que el ARTÍCULO tiene comprometido — global, no de este
+             *     almacén (N2 · pieza 3). El nombre lleva el `item_` delante por
+             *     eso: en una fila que habla de una nave, «comprometido» a secas
+             *     se leería como «comprometido aquí», y de los dos documentos que
+             *     comprometen solo el albarán declara almacén. `null` = no se
+             *     está calculando; nunca es cero.
+             */
+            item_committed_quantity: number | null;
         };
         /** ItemsRequest */
         ItemsRequest: {
@@ -20028,6 +20053,46 @@ export interface operations {
                                 warehouse_name: string;
                                 quantity: number;
                             }[];
+                            /**
+                             * @description Lo COMPROMETIDO y lo DISPONIBLE (N2 · pieza 3). Cifra
+                             *     derivada: nadie la escribe, se calcula al preguntarla.
+                             *     `null` ENTERO = no se está calculando (módulo `stock` sin
+                             *     instalar o ciclo de inventario apagado); un cero ahí
+                             *     afirmaría «nada comprometido», que es lo que no se sabe. El desglose viaja entero y sin paginar, como
+                             *     `warehouse_stock`: es cabecera de pestaña, y son los
+                             *     borradores vivos de UN artículo, que en una pyme se cuentan
+                             *     con los dedos. Va aquí y no en un endpoint aparte porque la
+                             *     pregunta es la misma que abre el libro — «¿por qué tengo
+                             *     47?» y «¿por qué solo puedo vender 35?» se responden en la
+                             *     misma pantalla.
+                             */
+                            committed: {
+                                quantity: number;
+                                /**
+                                 * @description ⚠️ `null` cuando el artículo NUNCA ha llevado stock
+                                 *     (`opening_stock` NULL, la distinción que la migración se
+                                 *     esforzó en preservar): de ese no hay disponible que
+                                 *     calcular, y un «−4» ahí sería una alarma inventada.
+                                 */
+                                available: number | null;
+                                documents: ({
+                                    /** @constant */
+                                    document_type: "delivery_note";
+                                    document_id: number;
+                                    document_number: string;
+                                    customer_name: string;
+                                    date: string;
+                                    quantity: number;
+                                } | {
+                                    /** @constant */
+                                    document_type: "invoice";
+                                    document_id: number;
+                                    document_number: string;
+                                    customer_name: string;
+                                    date: string;
+                                    quantity: number;
+                                })[];
+                            } | null;
                         };
                     };
                 };

package/dist/client.d.ts

@@ -960,6 +960,94 @@ export declare class PimiaClient {
             success: string;
         }>;
     };
+    /**
+     * El libro del almacén: por qué un artículo tiene el saldo que tiene. Exige
+     * `items:read` — leer el libro es leer el catálogo que explica— y, a
+     * diferencia de almacenes y recuentos, **NO va tras el módulo `stock`**: el
+     * libro es N1 y N1 es de todos.
+     *
+     * ## El COMPROMETIDO, en la cabecera de `forItem`
+     *
+     * `meta.committed` responde la otra mitad de la pregunta: no «cuánto tengo»
+     * sino **«cuánto de lo que tengo puedo vender»**. Trae la cantidad, el
+     * disponible (saldo − comprometido) y el DESGLOSE de los documentos que lo
+     * comprometen.
+     *
+     * ⛔ **Tres cosas que hay que tener delante:**
+     *
+     * 1. **Es una cifra DERIVADA**: no hay columna que escribir, no existe un
+     *    `PUT` para reservar. Comprometen el albarán y la factura **en
+     *    borrador**, y dejan de hacerlo solos cuando mueven el almacén (al
+     *    entregar y al publicar). El presupuesto aceptado NO compromete: nada en
+     *    el núcleo dice cuándo se cumplió.
+     * 2. ⚠️ **`committed` a `null` NO es cero.** Es «no se está calculando» — la
+     *    empresa no tiene el módulo `stock`, o tiene el ciclo de inventario
+     *    apagado. Pintar un 0 ahí afirma «nada comprometido», que es justo lo
+     *    que no se sabe. Igual con `committed_quantity` en el artículo.
+     * 3. **Es GLOBAL por artículo, sin dimensión de almacén**: de los documentos
+     *    que comprometen solo el albarán declara almacén.
+     */
+    get stockMovements(): {
+        /**
+         * El libro entero de la empresa, filtrable por artículo, almacén, motivo
+         * y fechas. Su `meta` trae además el valor informativo del almacén
+         * (`stock_value_cents`), que NO es valoración contable.
+         */
+        list: (query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
+            data: components["schemas"]["StockMovementResource"][];
+            meta: {
+                stock_movement_total_count: number;
+                stock_value_cents: number;
+            };
+        }>;
+        /**
+         * El libro de UN artículo, con la cabecera que lo explica: saldo
+         * (`meta.opening_stock`), reparto por almacén (`meta.warehouse_stock`) y
+         * comprometido (`meta.committed`).
+         */
+        forItem: (itemId: number | string, query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
+            data: components["schemas"]["StockMovementResource"][];
+            meta: {
+                opening_stock: number | null;
+                warehouse_stock: {
+                    warehouse_id: number;
+                    warehouse_name: string;
+                    quantity: number;
+                }[];
+                committed: {
+                    quantity: number;
+                    available: number | null;
+                    documents: ({
+                        document_type: "delivery_note";
+                        document_id: number;
+                        document_number: string;
+                        customer_name: string;
+                        date: string;
+                        quantity: number;
+                    } | {
+                        document_type: "invoice";
+                        document_id: number;
+                        document_number: string;
+                        customer_name: string;
+                        date: string;
+                        quantity: number;
+                    })[];
+                } | null;
+            };
+        }>;
+        /**
+         * El ajuste manual con motivo: la corrección que deja rastro, frente al
+         * `PUT /items/{item}` que pisa el contador sin decir por qué. Cantidad
+         * FIRMADA (± decimal) y `note` obligatoria; `warehouse_id` opcional.
+         */
+        adjust: (itemId: number | string, body: {
+            quantity: number;
+            note: string;
+            warehouse_id?: number;
+        }, options?: WriteOptions) => Promise<{
+            data: components["schemas"]["StockMovementResource"];
+        }>;
+    };
     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

@@ -245,6 +245,55 @@ export class PimiaClient {
             delete: (id, options) => this.delete(`/stock-counts/${id}`, options),
         };
     }
+    /**
+     * El libro del almacén: por qué un artículo tiene el saldo que tiene. Exige
+     * `items:read` — leer el libro es leer el catálogo que explica— y, a
+     * diferencia de almacenes y recuentos, **NO va tras el módulo `stock`**: el
+     * libro es N1 y N1 es de todos.
+     *
+     * ## El COMPROMETIDO, en la cabecera de `forItem`
+     *
+     * `meta.committed` responde la otra mitad de la pregunta: no «cuánto tengo»
+     * sino **«cuánto de lo que tengo puedo vender»**. Trae la cantidad, el
+     * disponible (saldo − comprometido) y el DESGLOSE de los documentos que lo
+     * comprometen.
+     *
+     * ⛔ **Tres cosas que hay que tener delante:**
+     *
+     * 1. **Es una cifra DERIVADA**: no hay columna que escribir, no existe un
+     *    `PUT` para reservar. Comprometen el albarán y la factura **en
+     *    borrador**, y dejan de hacerlo solos cuando mueven el almacén (al
+     *    entregar y al publicar). El presupuesto aceptado NO compromete: nada en
+     *    el núcleo dice cuándo se cumplió.
+     * 2. ⚠️ **`committed` a `null` NO es cero.** Es «no se está calculando» — la
+     *    empresa no tiene el módulo `stock`, o tiene el ciclo de inventario
+     *    apagado. Pintar un 0 ahí afirma «nada comprometido», que es justo lo
+     *    que no se sabe. Igual con `committed_quantity` en el artículo.
+     * 3. **Es GLOBAL por artículo, sin dimensión de almacén**: de los documentos
+     *    que comprometen solo el albarán declara almacén.
+     */
+    get stockMovements() {
+        return {
+            /**
+             * El libro entero de la empresa, filtrable por artículo, almacén, motivo
+             * y fechas. Su `meta` trae además el valor informativo del almacén
+             * (`stock_value_cents`), que NO es valoración contable.
+             */
+            list: (query, options) => this.get('/stock-movements', query, options),
+            /**
+             * El libro de UN artículo, con la cabecera que lo explica: saldo
+             * (`meta.opening_stock`), reparto por almacén (`meta.warehouse_stock`) y
+             * comprometido (`meta.committed`).
+             */
+            forItem: (itemId, query, options) => this.get(`/items/${itemId}/stock-movements`, query, options),
+            /**
+             * El ajuste manual con motivo: la corrección que deja rastro, frente al
+             * `PUT /items/{item}` que pisa el contador sin decir por qué. Cantidad
+             * FIRMADA (± decimal) y `note` obligatoria; `warehouse_id` opcional.
+             */
+            adjust: (itemId, body, options) => this.post(`/items/${itemId}/stock-adjustments`, body, options),
+        };
+    }
     get(path, query, options) {
         return this.request(path, { ...options, method: 'GET', query });
     }

package/package.json

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