@molecule/api-resource-inventory 1.0.0

package/dist/handlers/updateStock.js

@@ -0,0 +1,126 @@
+/**
+ * Handler for updating stock levels for a product.
+ *
+ * @module
+ */
+import { create, findOne, updateById } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+import { logger } from '@molecule/api-logger';
+import { assertInventoryAdmin } from '../authorizers/index.js';
+import { toStockInfo } from '../utilities.js';
+/** Valid adjustment types. */
+const VALID_TYPES = ['add', 'remove', 'set'];
+/**
+ * Updates stock for the given product. Creates the stock record if it doesn't exist.
+ * @param req - The request with `productId` param and {@link StockAdjustment} body.
+ * @param res - The response object.
+ */
+export async function updateStock(req, res) {
+    // Admin-only: rewriting stock is a catalog mutation. Fail closed in-handler so
+    // the gate holds even if the route middleware is dropped by the injector.
+    if (!assertInventoryAdmin(res)) {
+        return;
+    }
+    const { productId } = req.params;
+    const input = req.body;
+    if (input.quantity == null || !VALID_TYPES.includes(input.type)) {
+        res.status(400).json({
+            error: t('inventory.error.invalidAdjustment', undefined, {
+                defaultValue: 'Invalid adjustment: quantity and valid type (add, remove, set) are required',
+            }),
+            errorKey: 'inventory.error.invalidAdjustment',
+        });
+        return;
+    }
+    if (input.quantity < 0) {
+        res.status(400).json({
+            error: t('inventory.error.negativeQuantity', undefined, {
+                defaultValue: 'Quantity must be non-negative',
+            }),
+            errorKey: 'inventory.error.negativeQuantity',
+        });
+        return;
+    }
+    try {
+        const variantId = input.variantId ?? null;
+        const where = [
+            { field: 'productId', operator: '=', value: productId },
+            { field: 'variantId', operator: '=', value: variantId },
+        ];
+        let row = await findOne('inventory_stock', where);
+        let newTotal;
+        if (!row) {
+            // Create new stock record
+            newTotal = input.type === 'set' ? input.quantity : input.type === 'add' ? input.quantity : 0;
+            const result = await create('inventory_stock', {
+                productId,
+                variantId,
+                total: newTotal,
+                reserved: 0,
+                lowStockThreshold: 10,
+            });
+            row = result.data;
+        }
+        else {
+            // Update existing record
+            if (input.type === 'add') {
+                newTotal = row.total + input.quantity;
+            }
+            else if (input.type === 'remove') {
+                newTotal = row.total - input.quantity;
+                if (newTotal < row.reserved) {
+                    res.status(409).json({
+                        error: t('inventory.error.insufficientStock', undefined, {
+                            defaultValue: 'Cannot remove: would drop below reserved quantity',
+                        }),
+                        errorKey: 'inventory.error.insufficientStock',
+                    });
+                    return;
+                }
+            }
+            else {
+                // 'set'
+                newTotal = input.quantity;
+                if (newTotal < row.reserved) {
+                    res.status(409).json({
+                        error: t('inventory.error.insufficientStock', undefined, {
+                            defaultValue: 'Cannot set: value is below reserved quantity',
+                        }),
+                        errorKey: 'inventory.error.insufficientStock',
+                    });
+                    return;
+                }
+            }
+            const updateResult = await updateById('inventory_stock', row.id, {
+                total: newTotal,
+            });
+            row = updateResult.data ?? { ...row, total: newTotal };
+        }
+        // Record movement
+        const movementQuantity = input.type === 'add' ? input.quantity : input.type === 'remove' ? -input.quantity : newTotal;
+        await create('inventory_movements', {
+            productId,
+            variantId,
+            type: 'adjustment',
+            quantity: movementQuantity,
+            reason: input.reason ?? null,
+            referenceId: null,
+        });
+        logger.debug('Stock updated', {
+            productId,
+            variantId,
+            type: input.type,
+            quantity: input.quantity,
+        });
+        res.json(toStockInfo(row));
+    }
+    catch (error) {
+        logger.error('Failed to update stock', { productId, error });
+        res.status(500).json({
+            error: t('inventory.error.updateFailed', undefined, {
+                defaultValue: 'Failed to update stock',
+            }),
+            errorKey: 'inventory.error.updateFailed',
+        });
+    }
+}

package/dist/i18n.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Locale registration for the inventory resource.
+ *
+ * Errors fall back to inline English defaults via `t(key, vars, { defaultValue })`
+ * — this resource ships without a companion locale bond.
+ *
+ * @module
+ */
+/**
+ * Whether i18n registration has been attempted. Always `true`; this module is
+ * a placeholder for symmetry with locale-bonded resources.
+ */
+export declare const i18nRegistered = true;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc,OAAO,CAAA"}

package/dist/i18n.js

@@ -0,0 +1,13 @@
+/**
+ * Locale registration for the inventory resource.
+ *
+ * Errors fall back to inline English defaults via `t(key, vars, { defaultValue })`
+ * — this resource ships without a companion locale bond.
+ *
+ * @module
+ */
+/**
+ * Whether i18n registration has been attempted. Always `true`; this module is
+ * a placeholder for symmetry with locale-bonded resources.
+ */
+export const i18nRegistered = true;

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Inventory resource for molecule.dev.
+ *
+ * Provides stock tracking with reservations, low-stock alerts,
+ * movement history, and bulk update support.
+ *
+ * @module
+ * @example
+ * ```typescript
+ * import { routes, requestHandlerMap } from '@molecule/api-resource-inventory'
+ * ```
+ *
+ * @remarks
+ * Tables: `src/__setup__/inventory.sql` creates `inventory_stock`,
+ * `inventory_reservations`, and `inventory_movements`. An mlcl-scaffolded API
+ * replays `__setup__/*.sql` automatically on migrate; anywhere else run it
+ * once — nothing at runtime creates them.
+ *
+ * Stock rows are keyed by `productId` — SHARED app-wide state, not per-user
+ * rows. Writing stock (`PUT /inventory/:productId`) and
+ * `POST /inventory/bulk` are role-gated and DENY BY DEFAULT (admin session
+ * claim or an `@molecule/api-permissions` grant), enforced both as the
+ * `requireInventoryAdmin` route middleware and inside the handlers
+ * (fail-closed). Out of the box no one can mutate stock — grant the role
+ * first; never "fix" the 403 by removing the gate.
+ *
+ * Reservation flow: `POST /inventory/:productId/reserve` holds quantity →
+ * `POST /inventory/reservations/:id/confirm` deducts it,
+ * `DELETE /inventory/reservations/:id` releases the hold. All handlers read
+ * the authenticated user from `res.locals.session` (mount behind your global
+ * auth middleware; 401 otherwise).
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual stock/admin screens, and check every box off
+ * one by one. Correctness is the whole point here: a box you can't check is a
+ * bug to fix, not a skip.
+ * - [ ] Setting stock (`PUT /inventory/:productId`, `type:'set'`) then
+ *   reloading `GET /inventory/:productId` shows the exact `total`/`available`
+ *   you set — it persisted, not just optimistic UI. `available` = `total` -
+ *   `reserved`.
+ * - [ ] `type:'add' N` raises `total` by exactly N and `type:'remove' N`
+ *   lowers it by exactly N — verify the arithmetic on the specific
+ *   `productId`/`variantId`; variant stock is tracked independently, so
+ *   adjusting one variant must not move another.
+ * - [ ] Stock never goes negative: removing or `set`ting below the currently
+ *   reserved quantity is rejected with a visible 409 error
+ *   (`inventory.error.insufficientStock`) and the stored `total` is unchanged
+ *   — never persisted as a negative; reserving more than `available` is
+ *   likewise rejected (409 `insufficientAvailable`).
+ * - [ ] Low-stock crossing flags the item: when `available` falls to or below
+ *   `lowStockThreshold` (default 10) it reads `isLowStock:true` and appears in
+ *   `GET /inventory/alerts`; raising stock back above the threshold clears it.
+ * - [ ] Every mutation appends an `inventory_movements` row shown in
+ *   `GET /inventory/:productId/movements` with the signed delta (`+N`/`-N`),
+ *   type (adjustment/reservation/confirmation), timestamp, and `referenceId`
+ *   (orderId/reservationId); the acting user is recorded on the reservation.
+ *   The movement log must reconstruct the current total.
+ * - [ ] Concurrency: two reservations or removals fired at once that together
+ *   exceed `available` don't double-spend the last unit — exactly one
+ *   succeeds, and final `total`/`reserved` stay consistent (`available` never
+ *   goes negative).
+ * - [ ] AUTHORIZATION — stock mutation is admin-only and denies by default:
+ *   `PUT /inventory/:productId` and `POST /inventory/bulk` return 403 for a
+ *   normal signed-in user (no `isAdmin`/`role:'admin'`/`roles`/`permissions`
+ *   claim) and 401 when signed out; only an admin session can change stock. A
+ *   customer cannot mutate the shared catalog stock through any endpoint, and
+ *   one user cannot release/confirm another user's reservation (403
+ *   `reservationForbidden`).
+ */
+export * from './authorizers/index.js';
+export * from './browser-guard.js';
+export * from './handlers/index.js';
+export * from './i18n.js';
+export * from './requestHandlerMap.js';
+export * from './routes.js';
+export * from './types.js';
+export * from './utilities.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAEH,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,78 @@
+/**
+ * Inventory resource for molecule.dev.
+ *
+ * Provides stock tracking with reservations, low-stock alerts,
+ * movement history, and bulk update support.
+ *
+ * @module
+ * @example
+ * ```typescript
+ * import { routes, requestHandlerMap } from '@molecule/api-resource-inventory'
+ * ```
+ *
+ * @remarks
+ * Tables: `src/__setup__/inventory.sql` creates `inventory_stock`,
+ * `inventory_reservations`, and `inventory_movements`. An mlcl-scaffolded API
+ * replays `__setup__/*.sql` automatically on migrate; anywhere else run it
+ * once — nothing at runtime creates them.
+ *
+ * Stock rows are keyed by `productId` — SHARED app-wide state, not per-user
+ * rows. Writing stock (`PUT /inventory/:productId`) and
+ * `POST /inventory/bulk` are role-gated and DENY BY DEFAULT (admin session
+ * claim or an `@molecule/api-permissions` grant), enforced both as the
+ * `requireInventoryAdmin` route middleware and inside the handlers
+ * (fail-closed). Out of the box no one can mutate stock — grant the role
+ * first; never "fix" the 403 by removing the gate.
+ *
+ * Reservation flow: `POST /inventory/:productId/reserve` holds quantity →
+ * `POST /inventory/reservations/:id/confirm` deducts it,
+ * `DELETE /inventory/reservations/:id` releases the hold. All handlers read
+ * the authenticated user from `res.locals.session` (mount behind your global
+ * auth middleware; 401 otherwise).
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual stock/admin screens, and check every box off
+ * one by one. Correctness is the whole point here: a box you can't check is a
+ * bug to fix, not a skip.
+ * - [ ] Setting stock (`PUT /inventory/:productId`, `type:'set'`) then
+ *   reloading `GET /inventory/:productId` shows the exact `total`/`available`
+ *   you set — it persisted, not just optimistic UI. `available` = `total` -
+ *   `reserved`.
+ * - [ ] `type:'add' N` raises `total` by exactly N and `type:'remove' N`
+ *   lowers it by exactly N — verify the arithmetic on the specific
+ *   `productId`/`variantId`; variant stock is tracked independently, so
+ *   adjusting one variant must not move another.
+ * - [ ] Stock never goes negative: removing or `set`ting below the currently
+ *   reserved quantity is rejected with a visible 409 error
+ *   (`inventory.error.insufficientStock`) and the stored `total` is unchanged
+ *   — never persisted as a negative; reserving more than `available` is
+ *   likewise rejected (409 `insufficientAvailable`).
+ * - [ ] Low-stock crossing flags the item: when `available` falls to or below
+ *   `lowStockThreshold` (default 10) it reads `isLowStock:true` and appears in
+ *   `GET /inventory/alerts`; raising stock back above the threshold clears it.
+ * - [ ] Every mutation appends an `inventory_movements` row shown in
+ *   `GET /inventory/:productId/movements` with the signed delta (`+N`/`-N`),
+ *   type (adjustment/reservation/confirmation), timestamp, and `referenceId`
+ *   (orderId/reservationId); the acting user is recorded on the reservation.
+ *   The movement log must reconstruct the current total.
+ * - [ ] Concurrency: two reservations or removals fired at once that together
+ *   exceed `available` don't double-spend the last unit — exactly one
+ *   succeeds, and final `total`/`reserved` stay consistent (`available` never
+ *   goes negative).
+ * - [ ] AUTHORIZATION — stock mutation is admin-only and denies by default:
+ *   `PUT /inventory/:productId` and `POST /inventory/bulk` return 403 for a
+ *   normal signed-in user (no `isAdmin`/`role:'admin'`/`roles`/`permissions`
+ *   claim) and 401 when signed out; only an admin session can change stock. A
+ *   customer cannot mutate the shared catalog stock through any endpoint, and
+ *   one user cannot release/confirm another user's reservation (403
+ *   `reservationForbidden`).
+ */
+export * from './authorizers/index.js';
+export * from './browser-guard.js';
+export * from './handlers/index.js';
+export * from './i18n.js';
+export * from './requestHandlerMap.js';
+export * from './routes.js';
+export * from './types.js';
+export * from './utilities.js';

package/dist/requestHandlerMap.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Maps route handler names to their implementations.
+ *
+ * @module
+ */
+import { bulkUpdate } from './handlers/bulkUpdate.js';
+import { confirm } from './handlers/confirm.js';
+import { getAlerts } from './handlers/getAlerts.js';
+import { getMovements } from './handlers/getMovements.js';
+import { getStock } from './handlers/getStock.js';
+import { release } from './handlers/release.js';
+import { reserve } from './handlers/reserve.js';
+import { updateStock } from './handlers/updateStock.js';
+/**
+ * Handler map for the inventory resource routes.
+ *
+ * `requireInventoryAdmin` is the admin authorizer middleware referenced by the
+ * `updateStock`/`bulkUpdate` routes. It must live here (as a real handler-map
+ * key) so the mlcl injector's route scanner preserves it — a bare middleware
+ * string that isn't a handler-map key is silently dropped, which is exactly how
+ * the previous bare `'authenticate'` gate became inert.
+ */
+export declare const requestHandlerMap: {
+    readonly getStock: typeof getStock;
+    readonly updateStock: typeof updateStock;
+    readonly reserve: typeof reserve;
+    readonly release: typeof release;
+    readonly confirm: typeof confirm;
+    readonly getAlerts: typeof getAlerts;
+    readonly getMovements: typeof getMovements;
+    readonly bulkUpdate: typeof bulkUpdate;
+    readonly requireInventoryAdmin: import("@molecule/api-resource").MoleculeRequestHandler;
+};
+//# sourceMappingURL=requestHandlerMap.d.ts.map

package/dist/requestHandlerMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestHandlerMap.d.ts","sourceRoot":"","sources":["../src/requestHandlerMap.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAEvD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;CAUpB,CAAA"}

package/dist/requestHandlerMap.js

@@ -0,0 +1,34 @@
+/**
+ * Maps route handler names to their implementations.
+ *
+ * @module
+ */
+import { requireInventoryAdmin } from './authorizers/index.js';
+import { bulkUpdate } from './handlers/bulkUpdate.js';
+import { confirm } from './handlers/confirm.js';
+import { getAlerts } from './handlers/getAlerts.js';
+import { getMovements } from './handlers/getMovements.js';
+import { getStock } from './handlers/getStock.js';
+import { release } from './handlers/release.js';
+import { reserve } from './handlers/reserve.js';
+import { updateStock } from './handlers/updateStock.js';
+/**
+ * Handler map for the inventory resource routes.
+ *
+ * `requireInventoryAdmin` is the admin authorizer middleware referenced by the
+ * `updateStock`/`bulkUpdate` routes. It must live here (as a real handler-map
+ * key) so the mlcl injector's route scanner preserves it — a bare middleware
+ * string that isn't a handler-map key is silently dropped, which is exactly how
+ * the previous bare `'authenticate'` gate became inert.
+ */
+export const requestHandlerMap = {
+    getStock,
+    updateStock,
+    reserve,
+    release,
+    confirm,
+    getAlerts,
+    getMovements,
+    bulkUpdate,
+    requireInventoryAdmin: requireInventoryAdmin(),
+};

package/dist/routes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Inventory route definitions.
+ *
+ * Declarative routing — mlcl inject reads these to generate the Express router.
+ *
+ * @module
+ */
+/**
+ * Inventory resource routes.
+ *
+ * All routes require authentication. The destructive admin-side mutations
+ * (`updateStock`, `bulkUpdate`) are additionally gated by the
+ * `requireInventoryAdmin` middleware — a real `requestHandlerMap` key (see
+ * {@link requireInventoryAdmin}) so the injector preserves it; the previously
+ * declared bare `'authenticate'` string was silently dropped by the route
+ * scanner, leaving stock open to rewrite by any authenticated user. Each
+ * admin/reservation handler additionally re-checks authorization internally, so
+ * the gate holds even if a consumer wires the routes without these middlewares.
+ */
+export declare const routes: readonly [{
+    readonly method: "get";
+    readonly path: "/inventory/:productId";
+    readonly handler: "getStock";
+    readonly middlewares: readonly ["authenticate"];
+}, {
+    readonly method: "put";
+    readonly path: "/inventory/:productId";
+    readonly handler: "updateStock";
+    readonly middlewares: readonly ["requireInventoryAdmin"];
+}, {
+    readonly method: "post";
+    readonly path: "/inventory/:productId/reserve";
+    readonly handler: "reserve";
+    readonly middlewares: readonly ["authenticate"];
+}, {
+    readonly method: "delete";
+    readonly path: "/inventory/reservations/:reservationId";
+    readonly handler: "release";
+    readonly middlewares: readonly ["authenticate"];
+}, {
+    readonly method: "post";
+    readonly path: "/inventory/reservations/:reservationId/confirm";
+    readonly handler: "confirm";
+    readonly middlewares: readonly ["authenticate"];
+}, {
+    readonly method: "get";
+    readonly path: "/inventory/alerts";
+    readonly handler: "getAlerts";
+    readonly middlewares: readonly ["authenticate"];
+}, {
+    readonly method: "get";
+    readonly path: "/inventory/:productId/movements";
+    readonly handler: "getMovements";
+    readonly middlewares: readonly ["authenticate"];
+}, {
+    readonly method: "post";
+    readonly path: "/inventory/bulk";
+    readonly handler: "bulkUpdate";
+    readonly middlewares: readonly ["requireInventoryAdmin"];
+}];
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDT,CAAA"}

package/dist/routes.js

@@ -0,0 +1,69 @@
+/**
+ * Inventory route definitions.
+ *
+ * Declarative routing — mlcl inject reads these to generate the Express router.
+ *
+ * @module
+ */
+/**
+ * Inventory resource routes.
+ *
+ * All routes require authentication. The destructive admin-side mutations
+ * (`updateStock`, `bulkUpdate`) are additionally gated by the
+ * `requireInventoryAdmin` middleware — a real `requestHandlerMap` key (see
+ * {@link requireInventoryAdmin}) so the injector preserves it; the previously
+ * declared bare `'authenticate'` string was silently dropped by the route
+ * scanner, leaving stock open to rewrite by any authenticated user. Each
+ * admin/reservation handler additionally re-checks authorization internally, so
+ * the gate holds even if a consumer wires the routes without these middlewares.
+ */
+export const routes = [
+    {
+        method: 'get',
+        path: '/inventory/:productId',
+        handler: 'getStock',
+        middlewares: ['authenticate'],
+    },
+    {
+        method: 'put',
+        path: '/inventory/:productId',
+        handler: 'updateStock',
+        middlewares: ['requireInventoryAdmin'],
+    },
+    {
+        method: 'post',
+        path: '/inventory/:productId/reserve',
+        handler: 'reserve',
+        middlewares: ['authenticate'],
+    },
+    {
+        method: 'delete',
+        path: '/inventory/reservations/:reservationId',
+        handler: 'release',
+        middlewares: ['authenticate'],
+    },
+    {
+        method: 'post',
+        path: '/inventory/reservations/:reservationId/confirm',
+        handler: 'confirm',
+        middlewares: ['authenticate'],
+    },
+    {
+        method: 'get',
+        path: '/inventory/alerts',
+        handler: 'getAlerts',
+        middlewares: ['authenticate'],
+    },
+    {
+        method: 'get',
+        path: '/inventory/:productId/movements',
+        handler: 'getMovements',
+        middlewares: ['authenticate'],
+    },
+    {
+        method: 'post',
+        path: '/inventory/bulk',
+        handler: 'bulkUpdate',
+        middlewares: ['requireInventoryAdmin'],
+    },
+];