@unifiedcommerce/core 0.1.0 → 0.2.0

package/src/hooks/checkout-completion.ts

@@ -1,262 +0,0 @@
-import type { Step } from "../kernel/compensation/types.js";
-import type { CheckoutData } from "./checkout.js";
-import { Ok, Err } from "../kernel/result.js";
-import { CommerceValidationError } from "../kernel/errors.js";
-
-// Service type narrowing — these mirror the actual service interfaces
-// without creating circular imports.
-
-interface InventoryServiceLike {
-  reserve(input: {
-    entityId: string;
-    variantId?: string;
-    quantity: number;
-    orderId: string;
-    performedBy: string;
-  }): Promise<{ ok: boolean; error?: { message: string } }>;
-  release(input: {
-    entityId: string;
-    variantId?: string;
-    quantity: number;
-    orderId: string;
-    performedBy: string;
-  }): Promise<unknown>;
-}
-
-interface PaymentsServiceLike {
-  capture(
-    paymentIntentId: string,
-    amount?: number,
-  ): Promise<{ ok: boolean; error?: { message: string } }>;
-  refund(
-    paymentId: string,
-    amount: number,
-    reason?: string,
-  ): Promise<unknown>;
-}
-
-interface OrdersServiceLike {
-  updateStatus?(
-    orderId: string,
-    status: string,
-    reason?: string,
-  ): Promise<unknown>;
-}
-
-/**
- * Reservation record produced by the reserve-inventory step.
- * Passed to compensate() so it knows exactly what to undo.
- */
-export interface InventoryReservation {
-  entityId: string;
-  variantId: string | undefined;
-  quantity: number;
-  orderId: string;
-}
-
-/**
- * Step 1: Reserve inventory.
- *
- * Output: the list of reservations created.
- * Compensate: release each reservation.
- *
- * Inventory reservation runs BEFORE payment capture. This is deliberate:
- * if stock is unavailable, we should find out before charging the customer.
- * The compensation for this step releases the reserved quantities.
- */
-export const reserveInventoryStep: Step<
-  CheckoutData,
-  InventoryReservation[]
-> = {
-  id: "reserve-inventory",
-
-  async run(data, ctx) {
-    const inventory = ctx.hook.services.inventory as InventoryServiceLike;
-    const reservations: InventoryReservation[] = [];
-    const performedBy = ctx.hook.actor?.userId ?? "system";
-
-    for (const item of data.lineItems) {
-      const result = await inventory.reserve({
-        entityId: item.entityId,
-        ...(item.variantId != null ? { variantId: item.variantId } : {}),
-        quantity: item.quantity,
-        orderId: data.checkoutId,
-        performedBy,
-      });
-
-      if (!result.ok) {
-        return Err(
-          new CommerceValidationError(
-            `Inventory reservation failed for ${item.title ?? item.entityId}: ${result.error?.message ?? "unknown"}`,
-          ),
-        );
-      }
-
-      reservations.push({
-        entityId: item.entityId,
-        variantId: item.variantId,
-        quantity: item.quantity,
-        orderId: data.checkoutId,
-      });
-    }
-
-    return Ok(reservations);
-  },
-
-  async compensate(reservations, ctx) {
-    const inventory = ctx.hook.services.inventory as InventoryServiceLike;
-    const performedBy = ctx.hook.actor?.userId ?? "system";
-
-    for (const r of reservations) {
-      await inventory.release({
-        entityId: r.entityId,
-        ...(r.variantId != null ? { variantId: r.variantId } : {}),
-        quantity: r.quantity,
-        orderId: r.orderId,
-        performedBy,
-      });
-    }
-  },
-};
-
-/**
- * Step 2: Capture payment.
- *
- * Output: the captured payment intent ID and amount.
- * Compensate: issue a full refund via the payments service.
- *
- * Runs AFTER inventory reservation. If capture fails, inventory reservations
- * are released by the compensation chain. If capture succeeds but a later step
- * fails, a refund is issued.
- */
-export const capturePaymentStep: Step<
-  CheckoutData,
-  { paymentIntentId: string; amount: number }
-> = {
-  id: "capture-payment",
-
-  async run(data, ctx) {
-    if (!data.paymentIntentId) {
-      return Err(
-        new CommerceValidationError(
-          "No authorized payment intent to capture.",
-        ),
-      );
-    }
-
-    const payments = ctx.hook.services.payments as PaymentsServiceLike;
-    const result = await payments.capture(data.paymentIntentId);
-
-    if (!result.ok) {
-      return Err(
-        new CommerceValidationError(
-          `Payment capture failed: ${result.error?.message ?? "unknown"}`,
-        ),
-      );
-    }
-
-    return Ok({ paymentIntentId: data.paymentIntentId, amount: data.total });
-  },
-
-  async compensate({ paymentIntentId, amount }, ctx) {
-    const payments = ctx.hook.services.payments as PaymentsServiceLike;
-    await payments.refund(
-      paymentIntentId,
-      amount,
-      "Checkout compensation: downstream step failed after payment capture",
-    );
-  },
-};
-
-/**
- * Step 3: Initiate fulfillment.
- *
- * Output: the order ID (for logging).
- * No compensate: fulfillment initiation is best-effort and idempotent.
- * A failed fulfillment should be retried through the job queue, not
- * compensated by rolling back the entire checkout.
- */
-export const initiateFulfillmentStep: Step<
-  CheckoutData,
-  { orderId: string }
-> = {
-  id: "initiate-fulfillment",
-
-  async run(data, ctx) {
-    const fulfillment = ctx.hook.services.fulfillment as {
-      fulfillOrder(orderId: string, actor?: unknown): Promise<unknown>;
-    };
-
-    try {
-      await fulfillment.fulfillOrder(data.checkoutId, ctx.hook.actor);
-    } catch (error) {
-      // Fulfillment initiation failure should not fail the checkout.
-      // The order is paid and inventory is reserved — fulfillment can be retried.
-      ctx.hook.logger.warn(
-        `Fulfillment initiation failed for order ${data.checkoutId}. Will need manual retry.`,
-        { error },
-      );
-    }
-
-    return Ok({ orderId: data.checkoutId });
-  },
-
-  // No compensate — fulfillment is best-effort at this stage
-};
-
-/**
- * Step 4: Send confirmation email.
- *
- * Output: void (best-effort).
- * No compensate: you cannot unsend an email.
- */
-export const sendConfirmationStep: Step<
-  CheckoutData,
-  { sent: boolean }
-> = {
-  id: "send-confirmation",
-
-  async run(data, ctx) {
-    const customers = ctx.hook.services.customers as {
-      getByUserId(
-        userId: string,
-        actor?: unknown,
-      ): Promise<{ ok: boolean; value?: { email?: string } }>;
-    };
-    const email = ctx.hook.services.email as
-      | {
-          send(input: {
-            template: string;
-            to: string;
-            data?: Record<string, unknown>;
-          }): Promise<void>;
-        }
-      | undefined;
-
-    if (!data.customerId || !email?.send) {
-      return Ok({ sent: false });
-    }
-
-    try {
-      const customer = await customers.getByUserId(data.customerId, ctx.hook.actor);
-      if (customer.ok && customer.value?.email) {
-        await email.send({
-          template: "order-confirmation",
-          to: customer.value.email,
-          data: { orderId: data.checkoutId, total: data.total, currency: data.currency },
-        });
-        return Ok({ sent: true });
-      }
-    } catch (error) {
-      // Email failure should not fail checkout
-      ctx.hook.logger.warn(
-        `Confirmation email failed for order ${data.checkoutId}.`,
-        { error },
-      );
-    }
-
-    return Ok({ sent: false });
-  },
-
-  // No compensate — cannot unsend an email
-};