@unifiedcommerce/core 0.1.1 → 0.2.1

package/src/modules/inventory/service.ts

@@ -0,0 +1,490 @@
+import { resolveOrgId } from "../../auth/org.js";
+import { assertPermission } from "../../auth/permissions.js";
+import type { Actor } from "../../auth/types.js";
+import type { CommerceConfig } from "../../config/types.js";
+import {
+  CommerceNotFoundError,
+  CommerceValidationError,
+  toCommerceError,
+} from "../../kernel/errors.js";
+import { runAfterHooks } from "../../kernel/hooks/executor.js";
+import { createHookContext } from "../../kernel/hooks/create-context.js";
+import type { HookContext } from "../../kernel/hooks/types.js";
+import type { HookRegistry } from "../../kernel/hooks/registry.js";
+import { Err, Ok, type Result } from "../../kernel/result.js";
+import { createLogger } from "../../utils/logger.js";
+import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
+import { createTxContext, type TxContext } from "../../kernel/database/tx-context.js";
+import {
+  InventoryRepository,
+  type Warehouse,
+  type InventoryLevel,
+} from "./repository/index.js";
+
+export type { InventoryAdjustInput, InventoryReserveInput, InventoryReleaseInput } from "./schemas.js";
+import type { InventoryAdjustInput, InventoryReserveInput, InventoryReleaseInput } from "./schemas.js";
+
+export interface InventoryServiceDeps {
+  repository: InventoryRepository;
+  hooks: HookRegistry;
+  config: CommerceConfig;
+  services: Record<string, unknown>;
+  database: DatabaseAdapter;
+}
+
+export class InventoryService {
+  private readonly repo: InventoryRepository;
+
+  constructor(private deps: InventoryServiceDeps) {
+    this.repo = deps.repository;
+  }
+
+  private async pickWarehouse(actor?: Actor | null, ctx?: TxContext): Promise<string> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const warehouses = await this.repo.findAllWarehouses(orgId, ctx);
+    const sorted = warehouses.sort((a, b) => a.priority - b.priority);
+    if (sorted.length > 0) {
+      return sorted[0]!.id;
+    }
+
+    // Create default warehouse if none exists
+    const defaultWarehouse = await this.repo.createWarehouse(
+      {
+        organizationId: orgId,
+        name: "Default Warehouse",
+        code: "DEFAULT",
+        isActive: true,
+        priority: 0,
+        metadata: {},
+      },
+      ctx,
+    );
+    return defaultWarehouse.id;
+  }
+
+  async createWarehouse(
+    input: Partial<Warehouse>,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Warehouse>> {
+    if (!input.name || !input.code) {
+      return Err(
+        new CommerceValidationError("Warehouse name and code are required."),
+      );
+    }
+
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+
+    const warehouse = await this.repo.createWarehouse(
+      {
+        organizationId: orgId,
+        name: input.name,
+        code: input.code,
+        isActive: input.isActive ?? true,
+        priority: input.priority ?? 0,
+        metadata: input.metadata ?? {},
+        ...(input.address !== undefined ? { address: input.address } : {}),
+      },
+      ctx,
+    );
+
+    return Ok(warehouse);
+  }
+
+  async listWarehouses(actor?: Actor | null, ctx?: TxContext): Promise<Result<Warehouse[]>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const warehouses = await this.repo.findAllWarehouses(orgId, ctx);
+    return Ok(warehouses.sort((a, b) => a.priority - b.priority));
+  }
+
+  async getAvailable(
+    entityId: string,
+    variantId?: string,
+    ctx?: TxContext,
+  ): Promise<Result<number>> {
+    const available = await this.repo.getAvailableQuantity(
+      entityId,
+      variantId,
+      ctx,
+    );
+    return Ok(available);
+  }
+
+  async checkMultiple(
+    entityIds: string[],
+    ctx?: TxContext,
+  ): Promise<Result<Record<string, number>>> {
+    const data = await this.repo.getAvailableQuantities(entityIds, ctx);
+    return Ok(data);
+  }
+
+  async getLevelsByEntityId(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<Result<InventoryLevel[]>> {
+    const levels = await this.repo.findLevelsByEntityId(entityId, ctx);
+    return Ok(levels);
+  }
+
+  async reserve(
+    input: InventoryReserveInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    if (input.quantity <= 0) {
+      return Err(
+        new CommerceValidationError(
+          "Reservation quantity must be greater than zero.",
+        ),
+      );
+    }
+
+    const warehouseId = input.warehouseId ?? (await this.pickWarehouse(actor, ctx));
+    const performedBy = input.performedBy ?? actor?.userId ?? "system";
+    const variantId = input.variantId ?? null;
+
+    // If we have a transaction context, use the concurrency-safe
+    // reserveWithLock (SELECT FOR UPDATE). This is the correct path
+    // for checkout — it prevents two concurrent requests from both
+    // reserving the last unit.
+    if (ctx?.tx) {
+      const reserveResult = await this.repo.reserveWithLock(
+        input.entityId,
+        variantId,
+        warehouseId,
+        input.quantity,
+        ctx,
+      );
+
+      if (!reserveResult.ok) {
+        return Err(new CommerceValidationError(reserveResult.reason));
+      }
+
+      await this.repo.createMovement(
+        {
+          entityId: input.entityId,
+          warehouseId,
+          type: "reservation",
+          quantity: input.quantity,
+          performedBy,
+          referenceType: "order",
+          referenceId: input.orderId,
+          ...(input.variantId != null
+            ? { variantId: input.variantId }
+            : {}),
+        },
+        ctx,
+      );
+
+      return Ok(undefined);
+    }
+
+    // Fallback: no transaction provided. Wrap in a transaction so we can
+    // use reserveWithLock (SELECT FOR UPDATE) for concurrency safety.
+    const result = await this.deps.database.transaction(async (tx) => {
+      const txCtx = createTxContext(tx, { actor: actor ?? null });
+      const reserveResult = await this.repo.reserveWithLock(
+        input.entityId,
+        variantId,
+        warehouseId,
+        input.quantity,
+        txCtx,
+      );
+
+      if (!reserveResult.ok) {
+        return Err(new CommerceValidationError(reserveResult.reason));
+      }
+
+      await this.repo.createMovement(
+        {
+          entityId: input.entityId,
+          warehouseId,
+          type: "reservation",
+          quantity: input.quantity,
+          performedBy,
+          referenceType: "order",
+          referenceId: input.orderId,
+          ...(input.variantId != null
+            ? { variantId: input.variantId }
+            : {}),
+        },
+        txCtx,
+      );
+
+      return Ok(undefined);
+    });
+
+    return result;
+  }
+
+  async release(
+    input: InventoryReleaseInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const warehouseId = input.warehouseId ?? (await this.pickWarehouse(actor, ctx));
+    const performedBy = input.performedBy ?? actor?.userId ?? "system";
+    const variantId = input.variantId ?? null;
+
+    const doRelease = async (txCtx: TxContext): Promise<Result<void>> => {
+      const releaseResult = await this.repo.releaseWithLock(
+        input.entityId,
+        variantId,
+        warehouseId,
+        input.quantity,
+        txCtx,
+      );
+
+      if (!releaseResult.ok) {
+        return Err(new CommerceValidationError(releaseResult.reason));
+      }
+
+      await this.repo.createMovement(
+        {
+          entityId: input.entityId,
+          warehouseId,
+          type: "release",
+          quantity: input.quantity,
+          performedBy,
+          referenceType: "order",
+          referenceId: input.orderId,
+          ...(input.variantId != null
+            ? { variantId: input.variantId }
+            : {}),
+        },
+        txCtx,
+      );
+
+      return Ok(undefined);
+    };
+
+    // If we already have a transaction, use it directly
+    if (ctx?.tx) {
+      return doRelease(ctx);
+    }
+
+    // Otherwise wrap in a new transaction for locking safety
+    return this.deps.database.transaction(async (tx) => {
+      return doRelease(createTxContext(tx, { actor: actor ?? null }));
+    });
+  }
+
+  async adjust(
+    input: InventoryAdjustInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<InventoryLevel>> {
+    try {
+      assertPermission(actor ?? null, "inventory:adjust");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const warehouseId = input.warehouseId ?? (await this.pickWarehouse(actor, ctx));
+
+    // Use upsertLevel to create or update
+    const existingLevel = await this.repo.findLevelByKey(
+      input.entityId,
+      warehouseId,
+      input.variantId,
+      ctx,
+    );
+
+    let level: InventoryLevel;
+    if (existingLevel) {
+      const newQuantity = Math.max(
+        0,
+        existingLevel.quantityOnHand + input.adjustment,
+      );
+      const updated = await this.repo.updateLevel(
+        existingLevel.id,
+        { quantityOnHand: newQuantity },
+        ctx,
+      );
+      level = updated!;
+    } else {
+      level = await this.repo.createLevel(
+        {
+          entityId: input.entityId,
+          warehouseId,
+          quantityOnHand: Math.max(0, input.adjustment),
+          quantityReserved: 0,
+          quantityIncoming: 0,
+          ...(input.variantId !== undefined
+            ? { variantId: input.variantId }
+            : {}),
+        },
+        ctx,
+      );
+    }
+
+    await this.repo.createMovement(
+      {
+        entityId: input.entityId,
+        warehouseId,
+        type: "adjustment",
+        quantity: input.adjustment,
+        reason: input.reason,
+        performedBy: input.performedBy ?? actor?.userId ?? "system",
+        ...(input.variantId !== undefined
+          ? { variantId: input.variantId }
+          : {}),
+        ...(input.referenceType !== undefined
+          ? { referenceType: input.referenceType }
+          : {}),
+        ...(input.referenceId !== undefined
+          ? { referenceId: input.referenceId }
+          : {}),
+      },
+      ctx,
+    );
+
+    const context: HookContext = createHookContext({
+      actor: actor ?? null,
+      tx: ctx?.tx ?? null,
+      logger: createLogger("inventory.adjust"),
+      services: this.deps.services,
+      context: { moduleName: "inventory" },
+    });
+
+    const afterHooks = this.deps.hooks.resolve("inventory.afterAdjust");
+    await runAfterHooks(
+      afterHooks as Parameters<typeof runAfterHooks>[0],
+      null,
+      level,
+      "update",
+      context,
+    );
+
+    return Ok(level);
+  }
+
+  /**
+   * Set inventory to an absolute quantity (not a delta).
+   *
+   * Used by external store webhooks where the source system reports
+   * the current stock level (e.g., Shopify sends `{ available: 6 }`).
+   * Computes the delta internally so audit movements stay correct.
+   */
+  async setAbsolute(
+    input: {
+      entityId: string;
+      quantity: number;
+      warehouseId?: string;
+      variantId?: string;
+      reason?: string;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<InventoryLevel>> {
+    const warehouseId = input.warehouseId ?? (await this.pickWarehouse(actor, ctx));
+
+    const existingLevel = await this.repo.findLevelByKey(
+      input.entityId,
+      warehouseId,
+      input.variantId,
+      ctx,
+    );
+
+    const currentOnHand = existingLevel?.quantityOnHand ?? 0;
+    const delta = input.quantity - currentOnHand;
+
+    // Delegate to adjust() so hooks, movements, and permission checks are consistent
+    return this.adjust(
+      {
+        entityId: input.entityId,
+        warehouseId,
+        adjustment: delta,
+        reason: input.reason ?? "External store absolute inventory sync",
+        ...(input.variantId !== undefined ? { variantId: input.variantId } : {}),
+      },
+      actor,
+      ctx,
+    );
+  }
+
+  /**
+   * Deduct inventory on fulfillment (system-level, no permission check).
+   *
+   * Decrements quantityOnHand for fulfilled items. This is a system
+   * operation triggered by order status → fulfilled, not a manual
+   * stock adjustment. Creates a "fulfillment" type movement for audit.
+   *
+   * Net effect when paired with release():
+   *   Before: on_hand=100, reserved=5, available=95
+   *   After deduct+release: on_hand=95, reserved=0, available=95
+   */
+  async deductForFulfillment(
+    input: {
+      entityId: string;
+      variantId?: string;
+      warehouseId?: string;
+      quantity: number;
+      orderId: string;
+      orgId?: string;
+    },
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const warehouseId = input.warehouseId ?? (await this.pickWarehouse(null, ctx));
+    const variantId = input.variantId ?? null;
+
+    const level = await this.repo.findLevelByKey(
+      input.entityId,
+      warehouseId,
+      variantId != null ? variantId : undefined,
+      ctx,
+    );
+
+    if (!level) {
+      // No inventory record — nothing to deduct
+      return Ok(undefined);
+    }
+
+    const newOnHand = Math.max(0, level.quantityOnHand - input.quantity);
+    await this.repo.updateLevel(
+      level.id,
+      { quantityOnHand: newOnHand },
+      ctx,
+    );
+
+    await this.repo.createMovement(
+      {
+        entityId: input.entityId,
+        warehouseId,
+        type: "fulfillment",
+        quantity: -input.quantity,
+        performedBy: "system",
+        referenceType: "order",
+        referenceId: input.orderId,
+        ...(variantId != null ? { variantId } : {}),
+      },
+      ctx,
+    );
+
+    return Ok(undefined);
+  }
+
+  async setUnitCost(
+    entityId: string,
+    warehouseId: string,
+    unitCost: number,
+    variantId?: string,
+    ctx?: TxContext,
+  ): Promise<Result<InventoryLevel>> {
+    const level = await this.repo.findLevelByKey(
+      entityId,
+      warehouseId,
+      variantId,
+      ctx,
+    );
+    if (!level) {
+      return Err(
+        new CommerceNotFoundError(
+          `Inventory level not found for entity ${entityId} at warehouse ${warehouseId}.`,
+        ),
+      );
+    }
+    const updated = await this.repo.updateLevel(level.id, { unitCost }, ctx);
+    return Ok(updated!);
+  }
+}

package/src/modules/media/adapter.ts

@@ -0,0 +1,17 @@
+import type { Result } from "../../kernel/result.js";
+
+export interface StoredFile {
+  key: string;
+  url: string;
+  contentType: string;
+  size?: number;
+}
+
+export interface StorageAdapter {
+  readonly providerId: string;
+  upload(key: string, data: ArrayBuffer | ReadableStream, contentType: string): Promise<Result<StoredFile>>;
+  getUrl(key: string): Promise<Result<string>>;
+  getSignedUrl(key: string, expiresIn: number): Promise<Result<string>>;
+  delete(key: string): Promise<Result<void>>;
+  list(prefix: string): Promise<Result<StoredFile[]>>;
+}