@unifiedcommerce/core 0.2.0 → 0.2.2

package/src/modules/cart/service.ts

@@ -0,0 +1,541 @@
+import { resolveOrgId } from "../../auth/org.js";
+import { assertOwnership, 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, runBeforeHooks } from "../../kernel/hooks/executor.js";
+import { createHookContext } from "../../kernel/hooks/create-context.js";
+import type {
+  AfterHook,
+  BeforeHook,
+  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 { TxContext } from "../../kernel/database/tx-context.js";
+import { CartRepository, type Cart, type CartLineItem } from "./repository/index.js";
+import type { CatalogRepository } from "../catalog/repository/index.js";
+
+export type {
+  CreateCartInput,
+  AddCartItemInput,
+  UpdateCartItemInput,
+} from "./schemas.js";
+
+import type {
+  CreateCartInput,
+  AddCartItemInput,
+  UpdateCartItemInput,
+} from "./schemas.js";
+
+import { defaultCartItemMatcher, type CartItemMatcher } from "./matcher.js";
+
+export interface CartServiceDeps {
+  repository: CartRepository;
+  catalogRepository: CatalogRepository;
+  hooks: HookRegistry;
+  config: CommerceConfig;
+  services: Record<string, unknown>;
+  cartItemMatcher?: CartItemMatcher;
+}
+
+type CartAddBeforeHook = BeforeHook<AddCartItemInput>;
+type CartAddAfterHook = AfterHook<CartLineItem>;
+type CartRemoveBeforeHook = BeforeHook<CartLineItem>;
+type CartRemoveAfterHook = AfterHook<CartLineItem>;
+type CartUpdateBeforeHook = BeforeHook<UpdateCartItemInput>;
+type CartUpdateAfterHook = AfterHook<CartLineItem>;
+
+function makeContext(
+  actor: Actor | null,
+  services: Record<string, unknown>,
+  tx: unknown = null,
+): HookContext {
+  return createHookContext({
+    actor,
+    tx,
+    logger: createLogger("cart"),
+    services,
+  });
+}
+
+function isExpired(cart: Cart): boolean {
+  return cart.expiresAt.getTime() < Date.now();
+}
+
+export class CartService {
+  private readonly repo: CartRepository;
+  private readonly catalogRepo: CatalogRepository;
+
+  constructor(private deps: CartServiceDeps) {
+    this.repo = deps.repository;
+    this.catalogRepo = deps.catalogRepository;
+  }
+
+  async create(
+    input: CreateCartInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Cart>> {
+    try {
+      assertPermission(actor ?? null, "cart:create");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const ttlMinutes = this.deps.config.cart?.ttlMinutes ?? 60 * 24 * 7;
+    const now = new Date();
+    const orgId = resolveOrgId(actor ?? null);
+
+    const cart = await this.repo.create(
+      {
+        organizationId: orgId,
+        status: "active",
+        currency: input.currency ?? "USD",
+        metadata: input.metadata ?? {},
+        expiresAt: new Date(now.getTime() + ttlMinutes * 60 * 1000),
+        ...(input.customerId !== undefined
+          ? { customerId: input.customerId }
+          : {}),
+      },
+      ctx,
+    );
+
+    return Ok(cart);
+  }
+
+  async getById(
+    id: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Cart & { lineItems: CartLineItem[] }>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const cart = await this.repo.findById(orgId, id, ctx);
+    if (!cart) return Err(new CommerceNotFoundError("Cart not found."));
+
+    // H2 fix: Non-admin actors can only access their own carts.
+    // Guest carts (customerId is null) are accessible by anyone (token-gated).
+    try {
+      this.assertCartOwnership(actor ?? null, cart);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    if (isExpired(cart) && cart.status === "active") {
+      await this.repo.updateStatus(cart.id, "abandoned", ctx);
+      cart.status = "abandoned";
+    }
+
+    const lineItems = await this.repo.findLineItemsByCartId(id, ctx);
+    return Ok({
+      ...cart,
+      lineItems,
+    });
+  }
+
+  async addItem(
+    input: AddCartItemInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CartLineItem>> {
+    try {
+      assertPermission(actor ?? null, "cart:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const orgId = resolveOrgId(actor ?? null);
+    const cart = await this.repo.findById(orgId, input.cartId, ctx);
+    if (!cart) return Err(new CommerceNotFoundError("Cart not found."));
+
+    try {
+      this.assertCartOwnership(actor ?? null, cart);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    if (cart.status !== "active") {
+      return Err(new CommerceValidationError("Cart is not active."));
+    }
+
+    const quantity = input.quantity ?? 1;
+    if (quantity <= 0) {
+      return Err(
+        new CommerceValidationError("Quantity must be greater than zero."),
+      );
+    }
+
+    // Validate entity exists
+    const entity = await this.catalogRepo.findEntityById(input.entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    // Check if entity has variants
+    const entityVariants = await this.catalogRepo.findVariantsByEntityId(
+      input.entityId,
+      ctx,
+    );
+    const hasVariants = entityVariants.length > 0;
+    if (hasVariants && !input.variantId) {
+      const variantIds = entityVariants.map((v) => v.id);
+      return Err(
+        new CommerceValidationError(
+          `Entity "${entity.slug}" has variants enabled, but no variantId was provided.`,
+          [
+            {
+              field: "variantId",
+              message: `Available variants: ${variantIds.join(", ")}`,
+            },
+          ],
+        ),
+      );
+    }
+
+    const context = makeContext(actor ?? null, this.deps.services, ctx?.tx);
+    const beforeHooks = this.deps.hooks.resolve(
+      "cart.beforeAddItem",
+    ) as CartAddBeforeHook[];
+    const afterHooks = this.deps.hooks.resolve(
+      "cart.afterAddItem",
+    ) as CartAddAfterHook[];
+
+    const processed = await runBeforeHooks(
+      beforeHooks,
+      input,
+      "addItem",
+      context,
+    );
+
+    // CartItemMatcher: deduplicate by merging quantity into existing matching item
+    const matcher = this.deps.cartItemMatcher ?? defaultCartItemMatcher;
+    const existingItems = await this.repo.findLineItemsByCartId(
+      input.cartId,
+      ctx,
+    );
+    const match = existingItems.find((existing) =>
+      matcher({
+        existingItem: existing,
+        newItem: {
+          ...processed,
+          variantId: processed.variantId ?? null,
+        },
+      }),
+    );
+
+    let item: CartLineItem;
+    if (match) {
+      const updated = await this.repo.updateLineItem(
+        match.id,
+        { quantity: match.quantity + quantity },
+        ctx,
+      );
+      item = updated!;
+    } else {
+      item = await this.repo.createLineItem(
+        {
+          cartId: input.cartId,
+          entityId: processed.entityId,
+          quantity,
+          unitPriceSnapshot: processed.unitPriceSnapshot ?? 1000,
+          currency: processed.currency ?? cart.currency,
+          metadata: processed.metadata ?? {},
+          ...(processed.variantId !== undefined
+            ? { variantId: processed.variantId }
+            : {}),
+        },
+        ctx,
+      );
+    }
+
+    await runAfterHooks(afterHooks, null, item, "addItem", context);
+
+    return Ok(item);
+  }
+
+  async removeItem(
+    cartId: string,
+    itemId: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    try {
+      assertPermission(actor ?? null, "cart:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const orgId = resolveOrgId(actor ?? null);
+    const cart = await this.repo.findById(orgId, cartId, ctx);
+    if (!cart) return Err(new CommerceNotFoundError("Cart not found."));
+
+    try {
+      this.assertCartOwnership(actor ?? null, cart);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const existing = await this.repo.findLineItemById(itemId, ctx);
+    if (!existing || existing.cartId !== cartId) {
+      return Err(new CommerceNotFoundError("Cart item not found."));
+    }
+
+    const context = makeContext(actor ?? null, this.deps.services, ctx?.tx);
+    const beforeHooks = this.deps.hooks.resolve(
+      "cart.beforeRemoveItem",
+    ) as CartRemoveBeforeHook[];
+    const afterHooks = this.deps.hooks.resolve(
+      "cart.afterRemoveItem",
+    ) as CartRemoveAfterHook[];
+    await runBeforeHooks(beforeHooks, existing, "removeItem", context);
+
+    await this.repo.deleteLineItem(itemId, ctx);
+
+    await runAfterHooks(afterHooks, existing, existing, "removeItem", context);
+    return Ok(undefined);
+  }
+
+  async updateQuantity(
+    input: UpdateCartItemInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CartLineItem>> {
+    try {
+      assertPermission(actor ?? null, "cart:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const orgId = resolveOrgId(actor ?? null);
+    const cart = await this.repo.findById(orgId, input.cartId, ctx);
+    if (!cart) return Err(new CommerceNotFoundError("Cart not found."));
+
+    try {
+      this.assertCartOwnership(actor ?? null, cart);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const item = await this.repo.findLineItemById(input.itemId, ctx);
+    if (!item || item.cartId !== input.cartId) {
+      return Err(new CommerceNotFoundError("Cart item not found."));
+    }
+
+    if (input.quantity <= 0) {
+      return Err(
+        new CommerceValidationError("Quantity must be greater than zero."),
+      );
+    }
+
+    const context = makeContext(actor ?? null, this.deps.services, ctx?.tx);
+    const beforeHooks = this.deps.hooks.resolve(
+      "cart.beforeUpdateQuantity",
+    ) as CartUpdateBeforeHook[];
+    const afterHooks = this.deps.hooks.resolve(
+      "cart.afterUpdateQuantity",
+    ) as CartUpdateAfterHook[];
+
+    await runBeforeHooks(beforeHooks, input, "update", context);
+
+    const updated = await this.repo.updateLineItem(
+      input.itemId,
+      { quantity: input.quantity },
+      ctx,
+    );
+
+    if (!updated) {
+      return Err(new CommerceNotFoundError("Cart item not found."));
+    }
+
+    await runAfterHooks(afterHooks, item, updated, "update", context);
+    return Ok(updated);
+  }
+
+  async merge(
+    sourceCartId: string,
+    targetCartId: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    try {
+      assertPermission(actor ?? null, "cart:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const orgId = resolveOrgId(actor ?? null);
+    const source = await this.repo.findById(orgId, sourceCartId, ctx);
+    const target = await this.repo.findById(orgId, targetCartId, ctx);
+    if (!source || !target)
+      return Err(new CommerceNotFoundError("Cart not found."));
+
+    const sourceItems = await this.repo.findLineItemsByCartId(
+      sourceCartId,
+      ctx,
+    );
+
+    // Move items from source to target
+    for (const item of sourceItems) {
+      await this.repo.createLineItem(
+        {
+          cartId: targetCartId,
+          entityId: item.entityId,
+          variantId: item.variantId,
+          quantity: item.quantity,
+          unitPriceSnapshot: item.unitPriceSnapshot,
+          currency: item.currency,
+          metadata: item.metadata ?? {},
+        },
+        ctx,
+      );
+    }
+
+    // Clear source cart items and mark as merged
+    await this.repo.deleteLineItemsByCartId(sourceCartId, ctx);
+    await this.repo.updateStatus(sourceCartId, "merged", ctx);
+
+    return Ok(undefined);
+  }
+
+  async abandon(cartId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const cart = await this.repo.findById(orgId, cartId, ctx);
+    if (!cart) return Err(new CommerceNotFoundError("Cart not found."));
+
+    await this.repo.updateStatus(cartId, "abandoned", ctx);
+    return Ok(undefined);
+  }
+
+  async markAsCheckedOut(
+    cartId: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const cart = await this.repo.findById(orgId, cartId, ctx);
+    if (!cart) return Err(new CommerceNotFoundError("Cart not found."));
+
+    await this.repo.updateStatus(cartId, "checked_out", ctx);
+    return Ok(undefined);
+  }
+
+  /**
+   * Atomically transitions a cart from "active" to "checking_out".
+   * Returns Err if the cart was already claimed by a concurrent checkout.
+   * This prevents TOCTOU race conditions on double-checkout.
+   */
+  async claimForCheckout(
+    cartId: string,
+    ctx?: TxContext,
+  ): Promise<Result<Cart>> {
+    const claimed = await this.repo.transitionToCheckingOut(cartId, ctx);
+    if (!claimed) {
+      return Err(
+        new CommerceValidationError(
+          "Cart is not available for checkout. It may have already been checked out by a concurrent request.",
+        ),
+      );
+    }
+    return Ok(claimed);
+  }
+
+  /**
+   * Creates an anonymous guest cart with a secret token for access control.
+   * The secret must be stored client-side (cookie/local storage) and sent
+   * with subsequent requests to identify the cart owner.
+   */
+  async createGuestCart(
+    currency = "USD",
+    ctx?: TxContext,
+  ): Promise<Result<{ cart: Cart; secret: string }>> {
+    const secret = crypto.randomUUID();
+    const ttlMinutes = this.deps.config.cart?.ttlMinutes ?? 60 * 24 * 7;
+    const now = new Date();
+
+    const cart = await this.repo.create(
+      {
+        organizationId: resolveOrgId(null),
+        customerId: undefined,
+        status: "active",
+        currency,
+        secret,
+        metadata: {},
+        expiresAt: new Date(now.getTime() + ttlMinutes * 60 * 1000),
+      },
+      ctx,
+    );
+
+    return Ok({ cart, secret });
+  }
+
+  /**
+   * Merges a guest (source) cart into an authenticated (target) cart on login.
+   * Uses addItem() internally so CartItemMatcher deduplication is applied.
+   * The source cart's secret must be provided for access control.
+   */
+  async mergeCarts(
+    targetCartId: string,
+    sourceCartId: string,
+    sourceSecret: string,
+    actor: Actor,
+    ctx?: TxContext,
+  ): Promise<Result<Cart>> {
+    const orgId = resolveOrgId(actor);
+    const sourceCart = await this.repo.findById(orgId, sourceCartId, ctx);
+    if (!sourceCart || sourceCart.secret !== sourceSecret) {
+      return Err(
+        new CommerceValidationError("Invalid cart or cart secret."),
+      );
+    }
+
+    const targetCart = await this.repo.findById(orgId, targetCartId, ctx);
+    if (!targetCart) {
+      return Err(new CommerceNotFoundError("Target cart not found."));
+    }
+
+    const sourceItems = await this.repo.findLineItemsByCartId(
+      sourceCartId,
+      ctx,
+    );
+
+    for (const item of sourceItems) {
+      await this.addItem(
+        {
+          cartId: targetCartId,
+          entityId: item.entityId,
+          quantity: item.quantity,
+          ...(item.variantId != null ? { variantId: item.variantId } : {}),
+          unitPriceSnapshot: item.unitPriceSnapshot,
+          currency: item.currency,
+          metadata: item.metadata ?? {},
+        },
+        actor,
+        ctx,
+      );
+    }
+
+    // Mark source cart as merged
+    await this.repo.updateStatus(sourceCartId, "merged", ctx);
+
+    const mergedCart = await this.repo.findById(orgId, targetCartId, ctx);
+    return Ok(mergedCart!);
+  }
+
+  /**
+   * Asserts the actor owns the cart. Bypassed for:
+   * - Admin/staff actors (permissions include `*:*`)
+   * - Guest carts (customerId is null) — access is token-gated instead
+   * - Null actors (unauthenticated guest access)
+   */
+  private assertCartOwnership(actor: Actor | null, cart: Cart): void {
+    // Guest carts have no customerId — access is controlled by cart secret/token
+    if (cart.customerId == null) return;
+    // Unauthenticated access to a customer cart is blocked by assertPermission elsewhere
+    if (!actor) return;
+    // Admin/staff bypass
+    assertOwnership(actor, cart.customerId);
+  }
+}