@molecule/api-resource-inventory 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Inventory resource types.
+ *
+ * @module
+ */
+/**
+ * Types of stock adjustment operations.
+ */
+export type StockAdjustmentType = 'add' | 'remove' | 'set';
+/**
+ * Types of stock movements recorded in the movement history.
+ */
+export type StockMovementType = 'adjustment' | 'reservation' | 'release' | 'confirmation';
+/**
+ * Current stock information for a product or variant.
+ */
+export interface StockInfo {
+    /** The product this stock belongs to. */
+    productId: string;
+    /** Optional variant identifier (size, color, etc.). */
+    variantId?: string;
+    /** Quantity available for purchase (total − reserved). */
+    available: number;
+    /** Quantity currently reserved by pending orders. */
+    reserved: number;
+    /** Total quantity in stock (available + reserved). */
+    total: number;
+    /** Threshold below which the product is considered low-stock. */
+    lowStockThreshold: number;
+    /** Whether current available stock is at or below the threshold. */
+    isLowStock: boolean;
+}
+/**
+ * Input for adjusting stock levels.
+ */
+export interface StockAdjustment {
+    /** Optional variant identifier. */
+    variantId?: string;
+    /** Quantity to adjust by (or absolute value for 'set'). */
+    quantity: number;
+    /** Type of adjustment: add, remove, or set to absolute value. */
+    type: StockAdjustmentType;
+    /** Human-readable reason for the adjustment. */
+    reason?: string;
+}
+/**
+ * A stock reservation tied to an order.
+ */
+export interface Reservation {
+    /** Unique reservation identifier. */
+    id: string;
+    /** The product being reserved. */
+    productId: string;
+    /** Optional variant identifier. */
+    variantId?: string;
+    /** Quantity reserved. */
+    quantity: number;
+    /** The order this reservation belongs to. */
+    orderId: string;
+    /** The authenticated user who created this reservation, if known. */
+    userId?: string;
+    /** When the reservation was created. */
+    createdAt: string;
+}
+/**
+ * Input for creating a stock reservation.
+ */
+export interface ReserveStockInput {
+    /** Quantity to reserve. */
+    quantity: number;
+    /** The order to associate this reservation with. */
+    orderId: string;
+}
+/**
+ * A low-stock alert entry.
+ */
+export interface LowStockAlert {
+    /** The product that is low on stock. */
+    productId: string;
+    /** Optional variant identifier. */
+    variantId?: string;
+    /** Current available quantity. */
+    available: number;
+    /** The low-stock threshold. */
+    threshold: number;
+}
+/**
+ * A record of a stock movement (adjustment, reservation, release, or confirmation).
+ */
+export interface StockMovement {
+    /** Unique movement identifier. */
+    id: string;
+    /** The product affected. */
+    productId: string;
+    /** Optional variant identifier. */
+    variantId?: string;
+    /** Type of movement. */
+    type: StockMovementType;
+    /** Quantity change (positive for additions, negative for removals). */
+    quantity: number;
+    /** Reason or description for this movement. */
+    reason?: string;
+    /** Associated order or reservation identifier. */
+    referenceId?: string;
+    /** When this movement occurred. */
+    createdAt: string;
+}
+/**
+ * Pagination options for list queries.
+ */
+export interface PaginationOptions {
+    /** Page number (1-based). */
+    page?: number;
+    /** Number of items per page. */
+    limit?: number;
+}
+/**
+ * A paginated result set.
+ */
+export interface PaginatedResult<T> {
+    /** The items in this page. */
+    data: T[];
+    /** Total number of items matching the query. */
+    total: number;
+    /** Current page number (1-based). */
+    page: number;
+    /** Number of items per page. */
+    limit: number;
+}
+/**
+ * Input for a single item in a bulk stock update.
+ */
+export interface BulkStockAdjustment {
+    /** The product to adjust. */
+    productId: string;
+    /** Optional variant identifier. */
+    variantId?: string;
+    /** Quantity to adjust. */
+    quantity: number;
+    /** Type of adjustment. */
+    type: StockAdjustmentType;
+    /** Reason for the adjustment. */
+    reason?: string;
+}
+/**
+ * Result of a single item in a bulk update.
+ */
+export interface BulkUpdateItemResult {
+    /** The product that was adjusted. */
+    productId: string;
+    /** Optional variant identifier. */
+    variantId?: string;
+    /** Whether this individual adjustment succeeded. */
+    success: boolean;
+    /** Error message if the adjustment failed. */
+    error?: string;
+    /** Updated stock info if successful. */
+    stock?: StockInfo;
+}
+/**
+ * Result of a bulk stock update operation.
+ */
+export interface BulkUpdateResult {
+    /** Total number of adjustments attempted. */
+    total: number;
+    /** Number of successful adjustments. */
+    succeeded: number;
+    /** Number of failed adjustments. */
+    failed: number;
+    /** Per-item results. */
+    results: BulkUpdateItemResult[];
+}
+/**
+ * Internal database row for an inventory stock record.
+ */
+export interface StockRow {
+    /** Unique stock record identifier. */
+    id: string;
+    /** The product this stock belongs to. */
+    productId: string;
+    /** Optional variant identifier. */
+    variantId: string | null;
+    /** Total quantity in stock. */
+    total: number;
+    /** Quantity currently reserved. */
+    reserved: number;
+    /** Low-stock threshold. */
+    lowStockThreshold: number;
+    /** Creation timestamp. */
+    createdAt: string;
+    /** Last modification timestamp. */
+    updatedAt: string;
+}
+/**
+ * Internal database row for a stock reservation.
+ */
+export interface ReservationRow {
+    /** Unique reservation identifier. */
+    id: string;
+    /** The product being reserved. */
+    productId: string;
+    /** Optional variant identifier. */
+    variantId: string | null;
+    /** Quantity reserved. */
+    quantity: number;
+    /** The order this reservation belongs to. */
+    orderId: string;
+    /** The authenticated user who created this reservation (null for legacy rows). */
+    userId: string | null;
+    /** Creation timestamp. */
+    createdAt: string;
+}
+/**
+ * Internal database row for a stock movement.
+ */
+export interface StockMovementRow {
+    /** Unique movement identifier. */
+    id: string;
+    /** The product affected. */
+    productId: string;
+    /** Optional variant identifier. */
+    variantId: string | null;
+    /** Type of movement. */
+    type: StockMovementType;
+    /** Quantity change. */
+    quantity: number;
+    /** Reason for this movement. */
+    reason: string | null;
+    /** Associated reference identifier. */
+    referenceId: string | null;
+    /** Creation timestamp. */
+    createdAt: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Inventory resource types.
+ *
+ * @module
+ */
+export {};

package/dist/utilities.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Inventory utility functions for converting database rows to typed objects.
+ *
+ * @module
+ */
+import type { LowStockAlert, Reservation, ReservationRow, StockInfo, StockMovement, StockMovementRow, StockRow } from './types.js';
+/**
+ * Converts a database stock row into a typed {@link StockInfo}.
+ * @param row - The raw database row.
+ * @returns The deserialized stock info.
+ */
+export declare function toStockInfo(row: StockRow): StockInfo;
+/**
+ * Converts a database reservation row into a typed {@link Reservation}.
+ * @param row - The raw database row.
+ * @returns The deserialized reservation.
+ */
+export declare function toReservation(row: ReservationRow): Reservation;
+/**
+ * Converts a database stock movement row into a typed {@link StockMovement}.
+ * @param row - The raw database row.
+ * @returns The deserialized stock movement.
+ */
+export declare function toStockMovement(row: StockMovementRow): StockMovement;
+/**
+ * Converts a database stock row into a typed {@link LowStockAlert}.
+ * @param row - The raw database row.
+ * @returns The low-stock alert.
+ */
+export declare function toLowStockAlert(row: StockRow): LowStockAlert;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,cAAc,EACd,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACT,MAAM,YAAY,CAAA;AAEnB;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,SAAS,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,WAAW,CAW9D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,GAAG,aAAa,CAYpE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,CAQ5D"}

package/dist/utilities.js

@@ -0,0 +1,79 @@
+/**
+ * Inventory utility functions for converting database rows to typed objects.
+ *
+ * @module
+ */
+/**
+ * Converts a database stock row into a typed {@link StockInfo}.
+ * @param row - The raw database row.
+ * @returns The deserialized stock info.
+ */
+export function toStockInfo(row) {
+    const available = row.total - row.reserved;
+    const info = {
+        productId: row.productId,
+        available,
+        reserved: row.reserved,
+        total: row.total,
+        lowStockThreshold: row.lowStockThreshold,
+        isLowStock: available <= row.lowStockThreshold,
+    };
+    if (row.variantId)
+        info.variantId = row.variantId;
+    return info;
+}
+/**
+ * Converts a database reservation row into a typed {@link Reservation}.
+ * @param row - The raw database row.
+ * @returns The deserialized reservation.
+ */
+export function toReservation(row) {
+    const reservation = {
+        id: row.id,
+        productId: row.productId,
+        quantity: row.quantity,
+        orderId: row.orderId,
+        createdAt: row.createdAt,
+    };
+    if (row.variantId)
+        reservation.variantId = row.variantId;
+    if (row.userId)
+        reservation.userId = row.userId;
+    return reservation;
+}
+/**
+ * Converts a database stock movement row into a typed {@link StockMovement}.
+ * @param row - The raw database row.
+ * @returns The deserialized stock movement.
+ */
+export function toStockMovement(row) {
+    const movement = {
+        id: row.id,
+        productId: row.productId,
+        type: row.type,
+        quantity: row.quantity,
+        createdAt: row.createdAt,
+    };
+    if (row.variantId)
+        movement.variantId = row.variantId;
+    if (row.reason)
+        movement.reason = row.reason;
+    if (row.referenceId)
+        movement.referenceId = row.referenceId;
+    return movement;
+}
+/**
+ * Converts a database stock row into a typed {@link LowStockAlert}.
+ * @param row - The raw database row.
+ * @returns The low-stock alert.
+ */
+export function toLowStockAlert(row) {
+    const alert = {
+        productId: row.productId,
+        available: row.total - row.reserved,
+        threshold: row.lowStockThreshold,
+    };
+    if (row.variantId)
+        alert.variantId = row.variantId;
+    return alert;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@molecule/api-resource-inventory",
+  "version": "1.0.0",
+  "description": "Inventory resource with stock tracking, reservations, low-stock alerts, movement history, and bulk updates.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "inventory",
+    "stock",
+    "commerce",
+    "resource"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.0",
+    "@molecule/api-database": "1.0.0",
+    "@molecule/api-i18n": "1.0.0",
+    "@molecule/api-logger": "1.0.0",
+    "@molecule/api-resource": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@molecule/api-database": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0",
+    "@molecule/api-logger": "^1.0.0",
+    "@molecule/api-resource": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@molecule/api-database": {
+      "optional": true
+    },
+    "@molecule/api-logger": {
+      "optional": true
+    }
+  }
+}