@molecule/api-resource-inventory 1.0.0

package/dist/handlers/confirm.js

@@ -0,0 +1,68 @@
+/**
+ * Handler for confirming a stock reservation (permanently removing from stock).
+ *
+ * @module
+ */
+import { create, deleteById, findById, findOne, updateById } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+import { logger } from '@molecule/api-logger';
+import { assertReservationActor } from '../authorizers/index.js';
+/**
+ * Confirms a reservation, permanently removing the reserved quantity from total stock.
+ * @param req - The request with `reservationId` param.
+ * @param res - The response object.
+ */
+export async function confirm(req, res) {
+    const { reservationId } = req.params;
+    try {
+        const reservation = await findById('inventory_reservations', reservationId);
+        if (!reservation) {
+            res.status(404).json({
+                error: t('inventory.error.reservationNotFound', undefined, {
+                    defaultValue: 'Reservation not found',
+                }),
+                errorKey: 'inventory.error.reservationNotFound',
+            });
+            return;
+        }
+        // Only the reservation's owner or an inventory admin may confirm it.
+        if (!assertReservationActor(res, reservation.userId)) {
+            return;
+        }
+        // Find the stock record
+        const where = [
+            { field: 'productId', operator: '=', value: reservation.productId },
+            { field: 'variantId', operator: '=', value: reservation.variantId },
+        ];
+        const stockRow = await findOne('inventory_stock', where);
+        if (stockRow) {
+            // Decrease both total and reserved
+            await updateById('inventory_stock', stockRow.id, {
+                total: stockRow.total - reservation.quantity,
+                reserved: Math.max(0, stockRow.reserved - reservation.quantity),
+            });
+        }
+        // Record movement
+        await create('inventory_movements', {
+            productId: reservation.productId,
+            variantId: reservation.variantId,
+            type: 'confirmation',
+            quantity: -reservation.quantity,
+            reason: null,
+            referenceId: reservationId,
+        });
+        // Delete reservation
+        await deleteById('inventory_reservations', reservationId);
+        logger.debug('Reservation confirmed', { reservationId, productId: reservation.productId });
+        res.status(204).end();
+    }
+    catch (error) {
+        logger.error('Failed to confirm reservation', { reservationId, error });
+        res.status(500).json({
+            error: t('inventory.error.confirmFailed', undefined, {
+                defaultValue: 'Failed to confirm reservation',
+            }),
+            errorKey: 'inventory.error.confirmFailed',
+        });
+    }
+}

package/dist/handlers/getAlerts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Handler for retrieving low-stock alerts.
+ *
+ * @module
+ */
+import type { MoleculeRequest, MoleculeResponse } from '@molecule/api-resource';
+/**
+ * Returns all products whose available stock is at or below their low-stock threshold.
+ * Accepts an optional `threshold` query parameter to override the per-product threshold.
+ * @param req - The request with optional `threshold` query parameter.
+ * @param res - The response object.
+ */
+export declare function getAlerts(req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
+//# sourceMappingURL=getAlerts.d.ts.map

package/dist/handlers/getAlerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getAlerts.d.ts","sourceRoot":"","sources":["../../src/handlers/getAlerts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAM/E;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqC1F"}

package/dist/handlers/getAlerts.js

@@ -0,0 +1,52 @@
+/**
+ * Handler for retrieving low-stock alerts.
+ *
+ * @module
+ */
+import { findMany } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+import { logger } from '@molecule/api-logger';
+import { getInventorySession } from '../authorizers/index.js';
+import { toLowStockAlert } from '../utilities.js';
+/**
+ * Returns all products whose available stock is at or below their low-stock threshold.
+ * Accepts an optional `threshold` query parameter to override the per-product threshold.
+ * @param req - The request with optional `threshold` query parameter.
+ * @param res - The response object.
+ */
+export async function getAlerts(req, res) {
+    // Low-stock alerts expose the full product/stock ledger — require auth in the
+    // handler, not just route middleware (the scanner can drop a declared
+    // authorizer whose name has no handler-map entry). Fail closed.
+    if (!getInventorySession(res)?.userId) {
+        res.status(401).json({
+            error: t('resource.error.unauthorized', undefined, { defaultValue: 'Unauthorized' }),
+            errorKey: 'resource.error.unauthorized',
+        });
+        return;
+    }
+    try {
+        const customThreshold = req.query.threshold ? Number(req.query.threshold) : undefined;
+        // Fetch all stock records — filtering by computed field (available = total - reserved)
+        // must be done in application code since the DataStore abstraction doesn't support
+        // computed-column filters.
+        const rows = await findMany('inventory_stock');
+        const alerts = rows
+            .filter((row) => {
+            const available = row.total - row.reserved;
+            const threshold = customThreshold ?? row.lowStockThreshold;
+            return available <= threshold;
+        })
+            .map(toLowStockAlert);
+        res.json(alerts);
+    }
+    catch (error) {
+        logger.error('Failed to get low stock alerts', { error });
+        res.status(500).json({
+            error: t('inventory.error.alertsFailed', undefined, {
+                defaultValue: 'Failed to get low stock alerts',
+            }),
+            errorKey: 'inventory.error.alertsFailed',
+        });
+    }
+}

package/dist/handlers/getMovements.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Handler for retrieving stock movement history for a product.
+ *
+ * @module
+ */
+import type { MoleculeRequest, MoleculeResponse } from '@molecule/api-resource';
+/**
+ * Returns paginated stock movement history for the given product.
+ * @param req - The request with `productId` param and optional pagination query params.
+ * @param res - The response object.
+ */
+export declare function getMovements(req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
+//# sourceMappingURL=getMovements.d.ts.map

package/dist/handlers/getMovements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMovements.d.ts","sourceRoot":"","sources":["../../src/handlers/getMovements.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAW/E;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C7F"}

package/dist/handlers/getMovements.js

@@ -0,0 +1,62 @@
+/**
+ * Handler for retrieving stock movement history for a product.
+ *
+ * @module
+ */
+import { count, findMany } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+import { logger } from '@molecule/api-logger';
+import { getInventorySession } from '../authorizers/index.js';
+import { toStockMovement } from '../utilities.js';
+/** Default page size. */
+const DEFAULT_LIMIT = 20;
+/** Maximum page size. */
+const MAX_LIMIT = 100;
+/**
+ * Returns paginated stock movement history for the given product.
+ * @param req - The request with `productId` param and optional pagination query params.
+ * @param res - The response object.
+ */
+export async function getMovements(req, res) {
+    // The full stock ledger for a product — require auth in the handler. Fail closed.
+    if (!getInventorySession(res)?.userId) {
+        res.status(401).json({
+            error: t('resource.error.unauthorized', undefined, { defaultValue: 'Unauthorized' }),
+            errorKey: 'resource.error.unauthorized',
+        });
+        return;
+    }
+    const { productId } = req.params;
+    try {
+        const page = Math.max(1, Number(req.query.page) || 1);
+        const limit = Math.min(MAX_LIMIT, Math.max(1, Number(req.query.limit) || DEFAULT_LIMIT));
+        const offset = (page - 1) * limit;
+        const where = [
+            { field: 'productId', operator: '=', value: productId },
+        ];
+        const [rows, total] = await Promise.all([
+            findMany('inventory_movements', {
+                where,
+                orderBy: [{ field: 'createdAt', direction: 'desc' }],
+                limit,
+                offset,
+            }),
+            count('inventory_movements', where),
+        ]);
+        res.json({
+            data: rows.map(toStockMovement),
+            total,
+            page,
+            limit,
+        });
+    }
+    catch (error) {
+        logger.error('Failed to get stock movements', { productId, error });
+        res.status(500).json({
+            error: t('inventory.error.movementsFailed', undefined, {
+                defaultValue: 'Failed to get stock movements',
+            }),
+            errorKey: 'inventory.error.movementsFailed',
+        });
+    }
+}

package/dist/handlers/getStock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Handler for retrieving stock information for a product.
+ *
+ * @module
+ */
+import type { MoleculeRequest, MoleculeResponse } from '@molecule/api-resource';
+/**
+ * Returns stock information for the given product (and optional variant).
+ * @param req - The request with `productId` param and optional `variantId` query.
+ * @param res - The response object.
+ */
+export declare function getStock(req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
+//# sourceMappingURL=getStock.d.ts.map

package/dist/handlers/getStock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getStock.d.ts","sourceRoot":"","sources":["../../src/handlers/getStock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAM/E;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CzF"}

package/dist/handlers/getStock.js

@@ -0,0 +1,58 @@
+/**
+ * Handler for retrieving stock information for a product.
+ *
+ * @module
+ */
+import { findOne } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+import { logger } from '@molecule/api-logger';
+import { getInventorySession } from '../authorizers/index.js';
+import { toStockInfo } from '../utilities.js';
+/**
+ * Returns stock information for the given product (and optional variant).
+ * @param req - The request with `productId` param and optional `variantId` query.
+ * @param res - The response object.
+ */
+export async function getStock(req, res) {
+    // Stock levels are business data — require auth in the handler. Fail closed.
+    if (!getInventorySession(res)?.userId) {
+        res.status(401).json({
+            error: t('resource.error.unauthorized', undefined, { defaultValue: 'Unauthorized' }),
+            errorKey: 'resource.error.unauthorized',
+        });
+        return;
+    }
+    const { productId } = req.params;
+    const variantId = req.query.variantId;
+    try {
+        const where = [
+            { field: 'productId', operator: '=', value: productId },
+        ];
+        if (variantId) {
+            where.push({ field: 'variantId', operator: '=', value: variantId });
+        }
+        else {
+            where.push({ field: 'variantId', operator: '=', value: null });
+        }
+        const row = await findOne('inventory_stock', where);
+        if (!row) {
+            res.status(404).json({
+                error: t('inventory.error.stockNotFound', undefined, {
+                    defaultValue: 'Stock record not found',
+                }),
+                errorKey: 'inventory.error.stockNotFound',
+            });
+            return;
+        }
+        res.json(toStockInfo(row));
+    }
+    catch (error) {
+        logger.error('Failed to get stock', { productId, variantId, error });
+        res.status(500).json({
+            error: t('inventory.error.getStockFailed', undefined, {
+                defaultValue: 'Failed to get stock information',
+            }),
+            errorKey: 'inventory.error.getStockFailed',
+        });
+    }
+}

package/dist/handlers/index.d.ts

@@ -0,0 +1,9 @@
+export { bulkUpdate } from './bulkUpdate.js';
+export { confirm } from './confirm.js';
+export { getAlerts } from './getAlerts.js';
+export { getMovements } from './getMovements.js';
+export { getStock } from './getStock.js';
+export { release } from './release.js';
+export { reserve } from './reserve.js';
+export { updateStock } from './updateStock.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/handlers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/handlers/index.js

@@ -0,0 +1,8 @@
+export { bulkUpdate } from './bulkUpdate.js';
+export { confirm } from './confirm.js';
+export { getAlerts } from './getAlerts.js';
+export { getMovements } from './getMovements.js';
+export { getStock } from './getStock.js';
+export { release } from './release.js';
+export { reserve } from './reserve.js';
+export { updateStock } from './updateStock.js';

package/dist/handlers/release.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Handler for releasing a stock reservation.
+ *
+ * @module
+ */
+import type { MoleculeRequest, MoleculeResponse } from '@molecule/api-resource';
+/**
+ * Releases a stock reservation, returning the reserved quantity to available stock.
+ * @param req - The request with `reservationId` param.
+ * @param res - The response object.
+ */
+export declare function release(req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
+//# sourceMappingURL=release.d.ts.map

package/dist/handlers/release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../src/handlers/release.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAK/E;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DxF"}

package/dist/handlers/release.js

@@ -0,0 +1,67 @@
+/**
+ * Handler for releasing a stock reservation.
+ *
+ * @module
+ */
+import { create, deleteById, findById, findOne, updateById } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+import { logger } from '@molecule/api-logger';
+import { assertReservationActor } from '../authorizers/index.js';
+/**
+ * Releases a stock reservation, returning the reserved quantity to available stock.
+ * @param req - The request with `reservationId` param.
+ * @param res - The response object.
+ */
+export async function release(req, res) {
+    const { reservationId } = req.params;
+    try {
+        const reservation = await findById('inventory_reservations', reservationId);
+        if (!reservation) {
+            res.status(404).json({
+                error: t('inventory.error.reservationNotFound', undefined, {
+                    defaultValue: 'Reservation not found',
+                }),
+                errorKey: 'inventory.error.reservationNotFound',
+            });
+            return;
+        }
+        // Only the reservation's owner or an inventory admin may release it.
+        if (!assertReservationActor(res, reservation.userId)) {
+            return;
+        }
+        // Find the stock record
+        const where = [
+            { field: 'productId', operator: '=', value: reservation.productId },
+            { field: 'variantId', operator: '=', value: reservation.variantId },
+        ];
+        const stockRow = await findOne('inventory_stock', where);
+        if (stockRow) {
+            // Decrease reserved count
+            await updateById('inventory_stock', stockRow.id, {
+                reserved: Math.max(0, stockRow.reserved - reservation.quantity),
+            });
+        }
+        // Record movement
+        await create('inventory_movements', {
+            productId: reservation.productId,
+            variantId: reservation.variantId,
+            type: 'release',
+            quantity: reservation.quantity,
+            reason: null,
+            referenceId: reservationId,
+        });
+        // Delete reservation
+        await deleteById('inventory_reservations', reservationId);
+        logger.debug('Reservation released', { reservationId, productId: reservation.productId });
+        res.status(204).end();
+    }
+    catch (error) {
+        logger.error('Failed to release reservation', { reservationId, error });
+        res.status(500).json({
+            error: t('inventory.error.releaseFailed', undefined, {
+                defaultValue: 'Failed to release reservation',
+            }),
+            errorKey: 'inventory.error.releaseFailed',
+        });
+    }
+}

package/dist/handlers/reserve.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Handler for reserving stock for an order.
+ *
+ * @module
+ */
+import type { MoleculeRequest, MoleculeResponse } from '@molecule/api-resource';
+/**
+ * Reserves stock for the given product and order.
+ * @param req - The request with `productId` param and {@link ReserveStockInput} body.
+ * @param res - The response object.
+ */
+export declare function reserve(req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
+//# sourceMappingURL=reserve.d.ts.map

package/dist/handlers/reserve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reserve.d.ts","sourceRoot":"","sources":["../../src/handlers/reserve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAM/E;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2GxF"}

package/dist/handlers/reserve.js

@@ -0,0 +1,112 @@
+/**
+ * Handler for reserving stock for an order.
+ *
+ * @module
+ */
+import { create, findOne, updateById } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+import { logger } from '@molecule/api-logger';
+import { getInventorySession } from '../authorizers/index.js';
+import { toReservation } from '../utilities.js';
+/**
+ * Reserves stock for the given product and order.
+ * @param req - The request with `productId` param and {@link ReserveStockInput} body.
+ * @param res - The response object.
+ */
+export async function reserve(req, res) {
+    // A reservation is tied to the caller's cart/order — require an authenticated
+    // user and bind the reservation to them so release/confirm can verify
+    // ownership. Fail closed in-handler regardless of route middleware.
+    const userId = getInventorySession(res)?.userId;
+    if (!userId) {
+        res.status(401).json({
+            error: t('resource.error.unauthorized', undefined, { defaultValue: 'Unauthorized' }),
+            errorKey: 'resource.error.unauthorized',
+        });
+        return;
+    }
+    const { productId } = req.params;
+    const input = req.body;
+    const variantId = req.query.variantId ?? null;
+    if (!input.quantity || input.quantity < 1) {
+        res.status(400).json({
+            error: t('inventory.error.invalidQuantity', undefined, {
+                defaultValue: 'Quantity must be at least 1',
+            }),
+            errorKey: 'inventory.error.invalidQuantity',
+        });
+        return;
+    }
+    if (!input.orderId) {
+        res.status(400).json({
+            error: t('inventory.error.orderIdRequired', undefined, {
+                defaultValue: 'Order ID is required',
+            }),
+            errorKey: 'inventory.error.orderIdRequired',
+        });
+        return;
+    }
+    try {
+        const where = [
+            { field: 'productId', operator: '=', value: productId },
+            { field: 'variantId', operator: '=', value: variantId },
+        ];
+        const row = await findOne('inventory_stock', where);
+        if (!row) {
+            res.status(404).json({
+                error: t('inventory.error.stockNotFound', undefined, {
+                    defaultValue: 'Stock record not found',
+                }),
+                errorKey: 'inventory.error.stockNotFound',
+            });
+            return;
+        }
+        const available = row.total - row.reserved;
+        if (input.quantity > available) {
+            res.status(409).json({
+                error: t('inventory.error.insufficientAvailable', undefined, {
+                    defaultValue: 'Insufficient stock available',
+                }),
+                errorKey: 'inventory.error.insufficientAvailable',
+            });
+            return;
+        }
+        // Create reservation record
+        const reservationResult = await create('inventory_reservations', {
+            productId,
+            variantId,
+            quantity: input.quantity,
+            orderId: input.orderId,
+            userId,
+        });
+        // Increase reserved count
+        await updateById('inventory_stock', row.id, {
+            reserved: row.reserved + input.quantity,
+        });
+        // Record movement
+        await create('inventory_movements', {
+            productId,
+            variantId,
+            type: 'reservation',
+            quantity: -input.quantity,
+            reason: null,
+            referenceId: input.orderId,
+        });
+        logger.debug('Stock reserved', {
+            productId,
+            variantId,
+            quantity: input.quantity,
+            orderId: input.orderId,
+        });
+        res.status(201).json(toReservation(reservationResult.data));
+    }
+    catch (error) {
+        logger.error('Failed to reserve stock', { productId, error });
+        res.status(500).json({
+            error: t('inventory.error.reserveFailed', undefined, {
+                defaultValue: 'Failed to reserve stock',
+            }),
+            errorKey: 'inventory.error.reserveFailed',
+        });
+    }
+}

package/dist/handlers/updateStock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Handler for updating stock levels for a product.
+ *
+ * @module
+ */
+import type { MoleculeRequest, MoleculeResponse } from '@molecule/api-resource';
+/**
+ * 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 declare function updateStock(req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
+//# sourceMappingURL=updateStock.d.ts.map

package/dist/handlers/updateStock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateStock.d.ts","sourceRoot":"","sources":["../../src/handlers/updateStock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAS/E;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsH5F"}