@molecule/api-resource-inventory 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/authorizers/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Inventory authorizers.
+ *
+ * Inventory is store/admin-scoped: stock is a shared catalog resource with no
+ * per-user owner. The destructive admin-side mutations — `updateStock` and
+ * `bulkUpdate` — directly rewrite stock levels and are therefore **admin-only**.
+ * That intent is enforced in two independent layers:
+ *
+ * 1. {@link requireInventoryAdmin} — a route middleware referenced from
+ *    {@link routes}. It is a key in `requestHandlerMap`, so the mlcl injector's
+ *    route scanner keeps it (a bare `'authenticate'` string is silently dropped
+ *    because it isn't a handler-map key — which is exactly why the old gate was
+ *    inert and any authenticated user could rewrite stock).
+ * 2. {@link isInventoryAdmin} — called at the top of every admin handler, so
+ *    protection holds even when the resource is wired via the middleware-less
+ *    module `@example` (`requestHandlerMap[route.handler]` only). Secure by
+ *    default: the handler fails closed regardless of whether the route
+ *    middleware survives codegen.
+ *
+ * Reservation lifecycle endpoints (`reserve`/`release`/`confirm`) are tied to a
+ * cart/order rather than the catalog: any authenticated user may reserve stock,
+ * the reservation is bound to the caller's `userId`, and `release`/`confirm`
+ * verify ownership (owner **or** admin) in-handler.
+ *
+ * "Admin" is resolved fail-closed from session claims only, keeping this resource
+ * dependency-light: an explicit `isAdmin`/`role`/`roles`/`permissions` claim on
+ * `res.locals.session`. With none, access is denied — the app developer must
+ * define who may administer inventory (or compose a richer authz middleware,
+ * e.g. `@molecule/api-permissions`, that sets an admin claim before this runs).
+ *
+ * @module
+ */
+import type { MoleculeRequestHandler, MoleculeResponse } from '@molecule/api-resource';
+/**
+ * Permission action describing inventory administration, e.g. for an app's own
+ * `@molecule/api-permissions` wiring.
+ */
+export declare const INVENTORY_PERMISSION_ACTION = "manage";
+/**
+ * Permission resource describing inventory administration, e.g. for an app's own
+ * `@molecule/api-permissions` wiring.
+ */
+export declare const INVENTORY_PERMISSION_RESOURCE = "inventory";
+/**
+ * Session-claim permission string (`'inventory:manage'`) that, when present in a
+ * session's `permissions` array, grants inventory administration.
+ */
+export declare const INVENTORY_ADMIN_PERMISSION = "inventory:manage";
+/**
+ * Structural view of the fields on `res.locals.session` this resource inspects to
+ * decide authorization. All fields are optional — a standard molecule session
+ * carries only `userId`; apps that model roles may also set `isAdmin`/`role`/
+ * `roles`/`permissions` claims, which are honored here.
+ */
+export interface InventorySession {
+    /** Authenticated user id (set by the global auth middleware). */
+    userId?: string;
+    /** Optional boolean admin claim. */
+    isAdmin?: boolean;
+    /** Optional single-role claim. */
+    role?: string;
+    /** Optional multi-role claim. */
+    roles?: string[];
+    /** Optional permission strings claim. */
+    permissions?: string[];
+}
+/**
+ * Reads the structural session off `res.locals`.
+ *
+ * @param res - The response whose `locals.session` is inspected.
+ * @returns The session, or `undefined` when unauthenticated.
+ */
+export declare function getInventorySession(res: MoleculeResponse): InventorySession | undefined;
+/**
+ * Resolves whether the current request's session belongs to an actor authorized
+ * to administer inventory (rewrite/bulk-update stock, release/confirm any
+ * reservation). Fail-closed: returns `false` when there is no authenticated
+ * session, and otherwise only `true` when the session carries an admin claim —
+ * `isAdmin === true`, `role === 'admin'`, `roles` containing `'admin'`, or
+ * `permissions` containing `'admin'` / `'inventory:manage'`.
+ *
+ * Use this for in-handler defense-in-depth (it does not depend on the route
+ * middleware being preserved by the injector).
+ *
+ * @param res - The response whose `locals.session` is inspected.
+ * @returns `true` when the session is an authorized inventory admin.
+ */
+export declare function isInventoryAdmin(res: MoleculeResponse): boolean;
+/**
+ * In-handler admin guard for the admin-only inventory mutations. Writes the
+ * appropriate JSON error and returns `false` when the caller is not an
+ * authorized admin — `401` when unauthenticated, `403` when authenticated but
+ * not an admin. Returns `true` (and writes nothing) when the caller is an admin.
+ *
+ * Call this at the top of every admin handler so protection holds independently
+ * of the route middleware (defense-in-depth, fail-closed).
+ *
+ * @param res - The response, whose `locals.session` is inspected and onto which
+ *   an error is written when access is denied.
+ * @returns `true` when the caller is an authorized admin, otherwise `false`.
+ */
+export declare function assertInventoryAdmin(res: MoleculeResponse): boolean;
+/**
+ * In-handler guard for reservation-lifecycle mutations (`release`, `confirm`).
+ * A reservation is owned by the user who created it; only that owner — or an
+ * inventory admin — may release or confirm it. Writes the appropriate JSON
+ * error and returns `false` when access is denied (`401` when unauthenticated,
+ * `403` when authenticated but neither the owner nor an admin); returns `true`
+ * (writing nothing) when the caller may act.
+ *
+ * Fail-closed: a reservation with no recorded owner (`null` — e.g. a legacy row
+ * created before ownership binding) is accessible only to admins.
+ *
+ * @param res - The response, whose `locals.session` is inspected and onto which
+ *   an error is written when access is denied.
+ * @param reservationUserId - The `userId` recorded on the reservation, or `null`.
+ * @returns `true` when the caller is the owner or an admin, otherwise `false`.
+ */
+export declare function assertReservationActor(res: MoleculeResponse, reservationUserId: string | null): boolean;
+/**
+ * Route middleware that gates the admin-only inventory routes (`updateStock`,
+ * `bulkUpdate`). Calls `next()` only for an authenticated admin; otherwise
+ * forwards an error to the framework error handler — `Unauthorized` when no
+ * session is present, `Forbidden` when the session is authenticated but not an
+ * admin.
+ *
+ * Exposed as a `requestHandlerMap` key so the injector's route scanner keeps it
+ * (unlike the inert global `'authenticate'` string, which is dropped).
+ *
+ * @returns An Express-compatible middleware function.
+ */
+export declare const requireInventoryAdmin: () => MoleculeRequestHandler;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/authorizers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAEtF;;;GAGG;AACH,eAAO,MAAM,2BAA2B,WAAW,CAAA;AAEnD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,cAAc,CAAA;AAExD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,qBAAoE,CAAA;AAE3G;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,GAAG,SAAS,CAEvF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAsB/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAmBnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,gBAAgB,EACrB,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,OAAO,CAsBT;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,QAC5B,sBAcH,CAAA"}

package/dist/authorizers/index.js

@@ -0,0 +1,188 @@
+/**
+ * Inventory authorizers.
+ *
+ * Inventory is store/admin-scoped: stock is a shared catalog resource with no
+ * per-user owner. The destructive admin-side mutations — `updateStock` and
+ * `bulkUpdate` — directly rewrite stock levels and are therefore **admin-only**.
+ * That intent is enforced in two independent layers:
+ *
+ * 1. {@link requireInventoryAdmin} — a route middleware referenced from
+ *    {@link routes}. It is a key in `requestHandlerMap`, so the mlcl injector's
+ *    route scanner keeps it (a bare `'authenticate'` string is silently dropped
+ *    because it isn't a handler-map key — which is exactly why the old gate was
+ *    inert and any authenticated user could rewrite stock).
+ * 2. {@link isInventoryAdmin} — called at the top of every admin handler, so
+ *    protection holds even when the resource is wired via the middleware-less
+ *    module `@example` (`requestHandlerMap[route.handler]` only). Secure by
+ *    default: the handler fails closed regardless of whether the route
+ *    middleware survives codegen.
+ *
+ * Reservation lifecycle endpoints (`reserve`/`release`/`confirm`) are tied to a
+ * cart/order rather than the catalog: any authenticated user may reserve stock,
+ * the reservation is bound to the caller's `userId`, and `release`/`confirm`
+ * verify ownership (owner **or** admin) in-handler.
+ *
+ * "Admin" is resolved fail-closed from session claims only, keeping this resource
+ * dependency-light: an explicit `isAdmin`/`role`/`roles`/`permissions` claim on
+ * `res.locals.session`. With none, access is denied — the app developer must
+ * define who may administer inventory (or compose a richer authz middleware,
+ * e.g. `@molecule/api-permissions`, that sets an admin claim before this runs).
+ *
+ * @module
+ */
+import { t } from '@molecule/api-i18n';
+/**
+ * Permission action describing inventory administration, e.g. for an app's own
+ * `@molecule/api-permissions` wiring.
+ */
+export const INVENTORY_PERMISSION_ACTION = 'manage';
+/**
+ * Permission resource describing inventory administration, e.g. for an app's own
+ * `@molecule/api-permissions` wiring.
+ */
+export const INVENTORY_PERMISSION_RESOURCE = 'inventory';
+/**
+ * Session-claim permission string (`'inventory:manage'`) that, when present in a
+ * session's `permissions` array, grants inventory administration.
+ */
+export const INVENTORY_ADMIN_PERMISSION = `${INVENTORY_PERMISSION_RESOURCE}:${INVENTORY_PERMISSION_ACTION}`;
+/**
+ * Reads the structural session off `res.locals`.
+ *
+ * @param res - The response whose `locals.session` is inspected.
+ * @returns The session, or `undefined` when unauthenticated.
+ */
+export function getInventorySession(res) {
+    return res.locals.session;
+}
+/**
+ * Resolves whether the current request's session belongs to an actor authorized
+ * to administer inventory (rewrite/bulk-update stock, release/confirm any
+ * reservation). Fail-closed: returns `false` when there is no authenticated
+ * session, and otherwise only `true` when the session carries an admin claim —
+ * `isAdmin === true`, `role === 'admin'`, `roles` containing `'admin'`, or
+ * `permissions` containing `'admin'` / `'inventory:manage'`.
+ *
+ * Use this for in-handler defense-in-depth (it does not depend on the route
+ * middleware being preserved by the injector).
+ *
+ * @param res - The response whose `locals.session` is inspected.
+ * @returns `true` when the session is an authorized inventory admin.
+ */
+export function isInventoryAdmin(res) {
+    const session = getInventorySession(res);
+    if (!session?.userId) {
+        return false;
+    }
+    if (session.isAdmin === true) {
+        return true;
+    }
+    if (session.role === 'admin') {
+        return true;
+    }
+    if (Array.isArray(session.roles) && session.roles.includes('admin')) {
+        return true;
+    }
+    if (Array.isArray(session.permissions) &&
+        (session.permissions.includes('admin') ||
+            session.permissions.includes(INVENTORY_ADMIN_PERMISSION))) {
+        return true;
+    }
+    return false;
+}
+/**
+ * In-handler admin guard for the admin-only inventory mutations. Writes the
+ * appropriate JSON error and returns `false` when the caller is not an
+ * authorized admin — `401` when unauthenticated, `403` when authenticated but
+ * not an admin. Returns `true` (and writes nothing) when the caller is an admin.
+ *
+ * Call this at the top of every admin handler so protection holds independently
+ * of the route middleware (defense-in-depth, fail-closed).
+ *
+ * @param res - The response, whose `locals.session` is inspected and onto which
+ *   an error is written when access is denied.
+ * @returns `true` when the caller is an authorized admin, otherwise `false`.
+ */
+export function assertInventoryAdmin(res) {
+    const session = getInventorySession(res);
+    if (!session?.userId) {
+        res.status(401).json({
+            error: t('resource.error.unauthorized', undefined, { defaultValue: 'Unauthorized' }),
+            errorKey: 'resource.error.unauthorized',
+        });
+        return false;
+    }
+    if (!isInventoryAdmin(res)) {
+        res.status(403).json({
+            error: t('inventory.error.forbidden', undefined, {
+                defaultValue: 'Admin access required to manage inventory',
+            }),
+            errorKey: 'inventory.error.forbidden',
+        });
+        return false;
+    }
+    return true;
+}
+/**
+ * In-handler guard for reservation-lifecycle mutations (`release`, `confirm`).
+ * A reservation is owned by the user who created it; only that owner — or an
+ * inventory admin — may release or confirm it. Writes the appropriate JSON
+ * error and returns `false` when access is denied (`401` when unauthenticated,
+ * `403` when authenticated but neither the owner nor an admin); returns `true`
+ * (writing nothing) when the caller may act.
+ *
+ * Fail-closed: a reservation with no recorded owner (`null` — e.g. a legacy row
+ * created before ownership binding) is accessible only to admins.
+ *
+ * @param res - The response, whose `locals.session` is inspected and onto which
+ *   an error is written when access is denied.
+ * @param reservationUserId - The `userId` recorded on the reservation, or `null`.
+ * @returns `true` when the caller is the owner or an admin, otherwise `false`.
+ */
+export function assertReservationActor(res, reservationUserId) {
+    const userId = getInventorySession(res)?.userId;
+    if (!userId) {
+        res.status(401).json({
+            error: t('resource.error.unauthorized', undefined, { defaultValue: 'Unauthorized' }),
+            errorKey: 'resource.error.unauthorized',
+        });
+        return false;
+    }
+    if (isInventoryAdmin(res)) {
+        return true;
+    }
+    if (reservationUserId !== null && reservationUserId === userId) {
+        return true;
+    }
+    res.status(403).json({
+        error: t('inventory.error.reservationForbidden', undefined, {
+            defaultValue: 'You do not have permission to modify this reservation',
+        }),
+        errorKey: 'inventory.error.reservationForbidden',
+    });
+    return false;
+}
+/**
+ * Route middleware that gates the admin-only inventory routes (`updateStock`,
+ * `bulkUpdate`). Calls `next()` only for an authenticated admin; otherwise
+ * forwards an error to the framework error handler — `Unauthorized` when no
+ * session is present, `Forbidden` when the session is authenticated but not an
+ * admin.
+ *
+ * Exposed as a `requestHandlerMap` key so the injector's route scanner keeps it
+ * (unlike the inert global `'authenticate'` string, which is dropped).
+ *
+ * @returns An Express-compatible middleware function.
+ */
+export const requireInventoryAdmin = () => (req, res, next) => {
+    const session = getInventorySession(res);
+    if (!session?.userId) {
+        return next(t('resource.error.unauthorized', undefined, { defaultValue: 'Unauthorized' }));
+    }
+    if (isInventoryAdmin(res)) {
+        return next();
+    }
+    return next(t('inventory.error.forbidden', undefined, {
+        defaultValue: 'Admin access required to manage inventory',
+    }));
+};

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-resource-inventory` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-resource-inventory is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/handlers/bulkUpdate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Handler for bulk stock updates.
+ *
+ * @module
+ */
+import type { MoleculeRequest, MoleculeResponse } from '@molecule/api-resource';
+/**
+ * Processes multiple stock adjustments in a single request.
+ * @param req - The request with `adjustments` array body.
+ * @param res - The response object.
+ */
+export declare function bulkUpdate(req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
+//# sourceMappingURL=bulkUpdate.d.ts.map

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

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

package/dist/handlers/bulkUpdate.js

@@ -0,0 +1,168 @@
+/**
+ * Handler for bulk stock updates.
+ *
+ * @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'];
+/**
+ * Processes multiple stock adjustments in a single request.
+ * @param req - The request with `adjustments` array body.
+ * @param res - The response object.
+ */
+export async function bulkUpdate(req, res) {
+    // Admin-only: bulk-rewriting stock is a catalog mutation. Fail closed
+    // in-handler so the gate holds even if the route middleware is dropped.
+    if (!assertInventoryAdmin(res)) {
+        return;
+    }
+    const { adjustments } = req.body;
+    if (!adjustments || !Array.isArray(adjustments) || adjustments.length === 0) {
+        res.status(400).json({
+            error: t('inventory.error.adjustmentsRequired', undefined, {
+                defaultValue: 'At least one adjustment is required',
+            }),
+            errorKey: 'inventory.error.adjustmentsRequired',
+        });
+        return;
+    }
+    try {
+        const results = [];
+        let succeeded = 0;
+        let failed = 0;
+        for (const adjustment of adjustments) {
+            try {
+                if (!adjustment.productId ||
+                    adjustment.quantity == null ||
+                    adjustment.quantity < 0 ||
+                    !VALID_TYPES.includes(adjustment.type)) {
+                    results.push({
+                        productId: adjustment.productId ?? 'unknown',
+                        variantId: adjustment.variantId,
+                        success: false,
+                        error: 'Invalid adjustment parameters',
+                    });
+                    failed++;
+                    continue;
+                }
+                const variantId = adjustment.variantId ?? null;
+                const where = [
+                    { field: 'productId', operator: '=', value: adjustment.productId },
+                    { field: 'variantId', operator: '=', value: variantId },
+                ];
+                let row = await findOne('inventory_stock', where);
+                let newTotal;
+                if (!row) {
+                    newTotal =
+                        adjustment.type === 'set'
+                            ? adjustment.quantity
+                            : adjustment.type === 'add'
+                                ? adjustment.quantity
+                                : 0;
+                    const createResult = await create('inventory_stock', {
+                        productId: adjustment.productId,
+                        variantId,
+                        total: newTotal,
+                        reserved: 0,
+                        lowStockThreshold: 10,
+                    });
+                    row = createResult.data;
+                }
+                else {
+                    if (adjustment.type === 'add') {
+                        newTotal = row.total + adjustment.quantity;
+                    }
+                    else if (adjustment.type === 'remove') {
+                        newTotal = row.total - adjustment.quantity;
+                        if (newTotal < row.reserved) {
+                            results.push({
+                                productId: adjustment.productId,
+                                variantId: adjustment.variantId,
+                                success: false,
+                                error: 'Would drop below reserved quantity',
+                            });
+                            failed++;
+                            continue;
+                        }
+                    }
+                    else {
+                        newTotal = adjustment.quantity;
+                        if (newTotal < row.reserved) {
+                            results.push({
+                                productId: adjustment.productId,
+                                variantId: adjustment.variantId,
+                                success: false,
+                                error: 'Value is below reserved quantity',
+                            });
+                            failed++;
+                            continue;
+                        }
+                    }
+                    const updateResult = await updateById('inventory_stock', row.id, {
+                        total: newTotal,
+                    });
+                    row = updateResult.data ?? { ...row, total: newTotal };
+                }
+                // Record movement
+                const movementQuantity = adjustment.type === 'add'
+                    ? adjustment.quantity
+                    : adjustment.type === 'remove'
+                        ? -adjustment.quantity
+                        : newTotal;
+                await create('inventory_movements', {
+                    productId: adjustment.productId,
+                    variantId,
+                    type: 'adjustment',
+                    quantity: movementQuantity,
+                    reason: adjustment.reason ?? null,
+                    referenceId: null,
+                });
+                results.push({
+                    productId: adjustment.productId,
+                    variantId: adjustment.variantId,
+                    success: true,
+                    stock: toStockInfo(row),
+                });
+                succeeded++;
+            }
+            catch (error) {
+                logger.warn('Failed to process stock adjustment', {
+                    error,
+                    productId: adjustment.productId,
+                });
+                results.push({
+                    productId: adjustment.productId ?? 'unknown',
+                    variantId: adjustment.variantId,
+                    success: false,
+                    error: 'Internal error processing adjustment',
+                });
+                failed++;
+            }
+        }
+        logger.debug('Bulk stock update completed', {
+            total: adjustments.length,
+            succeeded,
+            failed,
+        });
+        res.json({
+            total: adjustments.length,
+            succeeded,
+            failed,
+            results,
+        });
+    }
+    catch (error) {
+        logger.error('Failed to process bulk stock update', { error });
+        res.status(500).json({
+            error: t('inventory.error.bulkUpdateFailed', undefined, {
+                defaultValue: 'Failed to process bulk stock update',
+            }),
+            errorKey: 'inventory.error.bulkUpdateFailed',
+        });
+    }
+}

package/dist/handlers/confirm.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.d.ts","sourceRoot":"","sources":["../../src/handlers/confirm.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,CA8DxF"}