import { Cart, Order } from "@/models";
import { getSettings } from "@/models/settings.model";
import {
  getStripeForSecretKey,
  isStripeSecretKeyConfigured,
} from "@/lib/stripe";
import { resolveStripeCredentials } from "@/lib/credentials";
import { ORDER_STATUS, PAYMENT_STATUS } from "@/config/app.config";
import { sendOrderConfirmationEmail } from "@/lib/order-emails";
import { decrementInventory, InsufficientStockError } from "@/lib/inventory";
import { markOrderInventoryReserved } from "@/lib/order-inventory";
import {
  getOrderPreorderLines,
  getPreorderReleaseDateForOrder,
  markOrderPreorderReserved,
  PREORDER_ITEM_STATUS,
  PreorderUnavailableError,
  PURCHASE_TYPE,
  reservePreorderQuantity,
} from "@/lib/preorders";
import { getNextOnlineOrderNumber } from "@/lib/order-number";
import { DEFAULT_VENDOR_COMMISSION_RATE } from "@/lib/order-settings";
import {
  applyCouponUsageForOrder,
  reverseCouponUsageForOrder,
} from "@/lib/coupons";
import { ensureChargeTransaction } from "@/lib/payment-transactions";
import {
  auditOrderCancelled,
  auditOrderPaid,
  auditOrderPlaced,
  systemActor,
} from "@/lib/audit-order";
import { markCheckoutRecovered } from "@/lib/abandoned-checkouts";
import {
  buildVendorSubOrders,
  getOrderItemVendorId,
  groupItemsByOrderVendor,
  resolveOrderVendorContext,
} from "@/lib/order-vendors";
import { notifyOrderCreatedParticipants } from "@/lib/notifications";
import {
  parseShippingMetadata,
  allocateSubOrderShipping,
} from "@/lib/checkout-shipping";
import type Stripe from "stripe";
import {
  buildOrderItemCustomsSnapshot,
  resolveItemShipping,
  type ProductShippingData,
  type VariantShippingData,
} from "@/lib/product-shipping";
import { revalidateProductContent } from "@/lib/cache-invalidation";

type SettingsDocument = Awaited<ReturnType<typeof getSettings>>;

/** True when no line on the order needs physical shipping. */
function isDigitalOnlyOrder(
  items: Array<{
    productId: {
      shipping?: ProductShippingData;
      variants?: Array<
        { _id: { toString(): string } } & VariantShippingData
      >;
    };
    variantId?: unknown;
  }>,
): boolean {
  return !items.some(
    (item) =>
      resolveItemShipping({
        productShipping: item.productId.shipping,
        variantShipping: item.variantId
          ? item.productId.variants?.find(
              (candidate) =>
                candidate._id.toString() === String(item.variantId),
            )
          : undefined,
      }).requiresShipping,
  );
}

type StripeOrderShippingAddress = { fullName?: string } & Record<
  string,
  unknown
>;

type StripeOrderCartItem = {
  productId: {
    _id: string;
    name: string;
    sku?: string;
    images?: string[];
    vendorId: string | { _id: string };
    shipping?: ProductShippingData;
    variants?: Array<
      VariantShippingData & { _id: { toString: () => string } }
    >;
  };
  variantId?: string;
  quantity: number;
  price: number;
  purchaseType?: string;
  preorderReleaseDate?: Date;
  preorderMessage?: string;
  preorderPaymentMode?: "full" | "deposit" | "pay_later";
  preorderDepositAmount?: number;
  preorderOutstandingAmount?: number;
  preorderSupplierEta?: Date;
  preorderBatchName?: string;
};

export type FinalizeStripeOrderResult = {
  created: boolean;
  orderId?: string;
  orderNumber?: string;
};

/**
 * Anti-tampering guard for Stripe finalization. The order is rebuilt from the
 * CURRENT cart, but the amount charged was frozen in metadata when the
 * PaymentIntent/Checkout Session was created. If the live cart no longer sums to
 * the quoted subtotal, the cart was changed after payment was quoted and the
 * order must NOT be fulfilled (otherwise a $5 intent could ship a $2000 cart).
 */
function stripeCartMatchesQuote(
  items: Array<{ price?: number; quantity?: number }>,
  metadataSubtotal?: string,
): boolean {
  const computed = items.reduce(
    (sum, item) => sum + Number(item.price || 0) * Number(item.quantity || 0),
    0,
  );
  const quoted = parseFloat(metadataSubtotal || "0");
  return Math.abs(computed - quoted) <= 0.01;
}

/**
 * Handle a captured payment whose quote no longer matches the live cart:
 * write a permanent do-not-fulfil marker for the PaymentIntent on the cart,
 * auto-refund the payment, and alert admins.
 *
 * The marker is written FIRST and the refund only issued if it persisted —
 * refunding without the marker would let the cart be edited back to the
 * quoted sum, at which point a later webhook/verify retry would happily
 * create an order for an already-REFUNDED payment. If the marker write
 * fails, the money simply stays captured for an admin to resolve (safe).
 */
async function rejectTamperedStripePayment(params: {
  paymentIntentId: string;
  cartId: string;
  settings: SettingsDocument;
}): Promise<void> {
  const { paymentIntentId, cartId, settings } = params;
  console.error(
    "Stripe order rejected — cart changed after checkout was quoted:",
    cartId,
    paymentIntentId,
  );

  let marked = false;
  if (paymentIntentId) {
    try {
      await Cart.updateOne(
        { _id: cartId },
        { $addToSet: { rejectedPaymentIntentIds: paymentIntentId } },
      );
      marked = true;
    } catch (err) {
      console.error("Failed to record rejected Stripe intent:", err);
    }
  }

  let refundNote =
    "NOT auto-refunded — refund it manually from the Stripe dashboard";
  if (marked) {
    try {
      const credentials = resolveStripeCredentials(settings.payment?.stripe);
      if (isStripeSecretKeyConfigured(credentials.secretKey)) {
        // Full refund (covers deposit-only pre-order charges too). The
        // idempotency key makes the webhook + /verify double-invocation safe.
        await getStripeForSecretKey(credentials.secretKey).refunds.create(
          {
            payment_intent: paymentIntentId,
            metadata: { reason: "cart_changed_after_quote", cartId },
          },
          { idempotencyKey: `tamper-refund-${paymentIntentId}` },
        );
        refundNote = "auto-refunded in full";
      }
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err);
      if (/already been refunded|charge_already_refunded/i.test(message)) {
        refundNote = "auto-refunded in full";
      } else {
        console.error("Failed to auto-refund rejected Stripe payment:", err);
      }
    }
  }

  await import("@/lib/notifications")
    .then(({ notifyAdminsPaymentAnomaly }) =>
      notifyAdminsPaymentAnomaly({
        title: "Stripe payment rejected (cart mismatch)",
        message: `Stripe payment ${paymentIntentId || "(unknown intent)"} was captured, but the cart changed after checkout was quoted. No order was created; the payment was ${refundNote}.`,
        paymentIntentId,
        cartId,
      }),
    )
    .catch((err) => console.error("Failed to send payment anomaly alert:", err));
}

/** True when this intent was previously tamper-rejected (and refunded). */
function isRejectedIntentForCart(
  cart: { rejectedPaymentIntentIds?: string[] },
  paymentIntentId: string,
): boolean {
  return Boolean(
    paymentIntentId &&
      (cart.rejectedPaymentIntentIds || []).includes(paymentIntentId),
  );
}

/**
 * Idempotently create an order for a succeeded Stripe PaymentIntent.
 *
 * Safe to call from both the Stripe webhook and the /verify polling
 * endpoint: it returns the existing order if one already exists and
 * guards against duplicate-key races.
 */
export async function finalizeStripePaymentIntentOrder(
  paymentIntent: Stripe.PaymentIntent,
  settings: SettingsDocument,
): Promise<FinalizeStripeOrderResult> {
  const metadata = (paymentIntent.metadata || {}) as Record<
    string,
    string | undefined
  >;
  const {
    userId,
    cartId,
    shippingAddress: shippingAddressStr,
    billingAddress: billingAddressStr,
    subtotal,
    shipping,
    tax,
    discount,
    total,
    customerEmail,
    couponCode,
    couponType,
    couponValue,
    couponId,
  } = metadata;

  if (!userId || !cartId || !shippingAddressStr) {
    console.error("Missing metadata in payment intent:", paymentIntent.id);
    return { created: false };
  }

  const existingOrder = await Order.findOne({
    stripePaymentIntentId: paymentIntent.id,
  }).lean();
  if (existingOrder) {
    return {
      created: false,
      orderId: String(existingOrder._id),
      orderNumber: existingOrder.orderNumber,
    };
  }

  let shippingAddress: StripeOrderShippingAddress;
  try {
    shippingAddress = JSON.parse(shippingAddressStr);
  } catch {
    console.error("Failed to parse shipping address from payment intent");
    return { created: false };
  }
  let billingAddress: StripeOrderShippingAddress = shippingAddress;
  if (billingAddressStr) {
    try {
      billingAddress = JSON.parse(billingAddressStr);
    } catch {
      billingAddress = shippingAddress;
    }
  }

  const cart = await Cart.findById(cartId)
    .populate({
      path: "items.productId",
      select: "name price images vendorId stock sku slug shipping variants",
      populate: { path: "vendorId", select: "_id" },
    })
    .lean();

  if (!cart || !cart.items || cart.items.length === 0) {
    console.error("Cart not found or empty:", cartId);
    return { created: false };
  }

  const items = cart.items as StripeOrderCartItem[];

  // A previously tamper-rejected (and refunded) intent must never fulfil an
  // order, even if the cart has since been edited back to the quoted sum.
  // Re-run the rejection: every step is idempotent ($addToSet no-ops, the
  // refund has a fixed idempotency key, the alert dedupes per admin), and it
  // completes the refund if a crash landed between the marker write and the
  // refund on the first attempt.
  if (isRejectedIntentForCart(cart, paymentIntent.id)) {
    console.error(
      "Refusing to fulfil previously rejected Stripe intent:",
      paymentIntent.id,
    );
    await rejectTamperedStripePayment({
      paymentIntentId: paymentIntent.id,
      cartId: String(cart._id),
      settings,
    });
    return { created: false };
  }

  if (!stripeCartMatchesQuote(items, subtotal)) {
    await rejectTamperedStripePayment({
      paymentIntentId: paymentIntent.id,
      cartId: String(cart._id),
      settings,
    });
    return { created: false };
  }

  const orderNumber = await getNextOnlineOrderNumber(settings.orders?.prefix);

  const vendorContext = await resolveOrderVendorContext({
    isMultiVendorEnabled: Boolean(settings.multiVendorMode?.enabled),
  });
  const vendorGroups = groupItemsByOrderVendor(
    items,
    vendorContext,
    (item) => item.productId.vendorId,
  );
  const subOrders = await buildVendorSubOrders(vendorGroups, {
    getProductId: (item) => item.productId._id,
    getVariantId: (item) => item.variantId,
    getName: (item) => item.productId.name,
    getSku: (item) => item.productId.sku,
    getQuantity: (item) => item.quantity,
    getPrice: (item) => item.price,
    getImage: (item) => item.productId.images?.[0],
    getPurchaseType: (item) => item.purchaseType || PURCHASE_TYPE.STANDARD,
    getPreorderReleaseDate: (item) => item.preorderReleaseDate,
    getPreorderMessage: (item) => item.preorderMessage,
    getPreorderStatus: (item) =>
      item.purchaseType === PURCHASE_TYPE.PREORDER
        ? PREORDER_ITEM_STATUS.RESERVED
        : undefined,
    getPreorderPaymentMode: (item) => item.preorderPaymentMode,
    getPreorderDepositAmount: (item) => item.preorderDepositAmount,
    getPreorderOutstandingAmount: (item) => item.preorderOutstandingAmount,
    getPreorderSupplierEta: (item) => item.preorderSupplierEta,
    getPreorderBatchName: (item) => item.preorderBatchName,
    getCustoms: (item) => buildOrderItemCustomsSnapshot({
      productShipping: item.productId.shipping,
      variantShipping: item.variantId
        ? item.productId.variants?.find(
            (candidate) => candidate._id.toString() === String(item.variantId),
          )
        : undefined,
    }),
    fallbackCommissionPercent:
      settings.orders?.commission?.vendorRate ?? DEFAULT_VENDOR_COMMISSION_RATE,
    status: items.some((item) => item.purchaseType === PURCHASE_TYPE.PREORDER)
      ? ORDER_STATUS.PREORDERED
      : ORDER_STATUS.PENDING,
  });

  // Apply shipping captured at PaymentIntent/Checkout creation so the
  // Stripe-created order matches the other payment paths (per-vendor split,
  // selected method, duties).
  const parsedShipping = parseShippingMetadata(metadata);
  allocateSubOrderShipping(
    subOrders as Array<{
      vendorId: { toString: () => string };
      shippingCost?: number;
      shippingMethod?: unknown;
    }>,
    {
      vendorShippingCosts: parsedShipping.vendorShippingCosts,
      orderShippingCost: parseFloat(shipping || "0"),
      orderShippingMethod: parsedShipping.shippingMethod,
    },
  );

  const hasPreorder = items.some(
    (item) => item.purchaseType === PURCHASE_TYPE.PREORDER,
  );
  const preorderReleaseDate = getPreorderReleaseDateForOrder(items);
  const preorderItems = items.filter(
    (item) => item.purchaseType === PURCHASE_TYPE.PREORDER,
  );
  const preorderPaymentModes = new Set(
    preorderItems.map((item) => item.preorderPaymentMode || "full"),
  );
  const preorderPaymentMode =
    preorderPaymentModes.size === 1
      ? Array.from(preorderPaymentModes)[0]
      : hasPreorder
        ? "full"
        : undefined;
  const preorderDepositAmount = preorderItems.reduce(
    (sum, item) => sum + Number(item.preorderDepositAmount || 0),
    0,
  );
  const preorderOutstandingAmount = preorderItems.reduce(
    (sum, item) => sum + Number(item.preorderOutstandingAmount || 0),
    0,
  );

  let createdOrder;
  try {
    createdOrder = await Order.create({
      customerId: userId,
      orderNumber,
      currency: settings.general?.defaultCurrency || "USD",
      items: items.map((item) => ({
        productId: item.productId._id,
        variantId: item.variantId,
        vendorId: getOrderItemVendorId(item.productId.vendorId, vendorContext),
        name: item.productId.name,
        sku: item.productId.sku || "",
        quantity: item.quantity,
        price: item.price,
        image: item.productId.images?.[0],
        purchaseType: item.purchaseType || PURCHASE_TYPE.STANDARD,
        preorderReleaseDate: item.preorderReleaseDate,
        preorderMessage: item.preorderMessage,
        preorderStatus:
          item.purchaseType === PURCHASE_TYPE.PREORDER
            ? PREORDER_ITEM_STATUS.RESERVED
            : undefined,
        preorderPaymentMode: item.preorderPaymentMode,
        preorderDepositAmount: item.preorderDepositAmount,
        preorderOutstandingAmount: item.preorderOutstandingAmount,
        preorderSupplierEta: item.preorderSupplierEta,
        preorderBatchName: item.preorderBatchName,
        customs: buildOrderItemCustomsSnapshot({
          productShipping: item.productId.shipping,
          variantShipping: item.variantId
            ? item.productId.variants?.find(
                (candidate) =>
                  candidate._id.toString() === String(item.variantId),
              )
            : undefined,
        }),
      })),
      subOrders,
      shippingAddress,
      billingAddress,
      digitalOnly: isDigitalOnlyOrder(items),
      paymentMethod: "card",
      paymentStatus:
        preorderOutstandingAmount > 0
          ? PAYMENT_STATUS.PARTIALLY_PAID
          : PAYMENT_STATUS.PAID,
      stripePaymentIntentId: paymentIntent.id,
      paymentId: paymentIntent.id,
      subtotal: parseFloat(subtotal || "0"),
      shippingCost: parseFloat(shipping || "0"),
      shippingMethod: parsedShipping.shippingMethod,
      customs: parsedShipping.customs,
      tax: parseFloat(tax || "0"),
      discount: parseFloat(discount || "0"),
      coupon:
        couponCode && couponCode.trim()
          ? {
              code: couponCode.trim().toUpperCase(),
              type: couponType || undefined,
              value: couponValue ? Number(couponValue) : undefined,
              couponId: couponId || undefined,
              usageIncremented: false,
            }
          : undefined,
      total: parseFloat(total || "0"),
      channel: "online",
      hasPreorder,
      preorderStatus: hasPreorder ? PREORDER_ITEM_STATUS.RESERVED : undefined,
      preorderReleaseDate,
      preorderAcknowledgedAt: hasPreorder ? new Date() : undefined,
      preorderPaymentMode,
      preorderDepositAmount,
      preorderOutstandingAmount,
      status: hasPreorder ? ORDER_STATUS.PREORDERED : ORDER_STATUS.PROCESSING,
    });
  } catch (err: unknown) {
    // Concurrent webhook + verify race: another caller already created it.
    if (
      err &&
      typeof err === "object" &&
      "code" in err &&
      (err as { code?: number }).code === 11000
    ) {
      const raced = await Order.findOne({
        stripePaymentIntentId: paymentIntent.id,
      }).lean();
      if (raced) {
        return {
          created: false,
          orderId: String(raced._id),
          orderNumber: raced.orderNumber,
        };
      }
    }
    throw err;
  }

  await ensureChargeTransaction({
    _id: String(createdOrder._id),
    orderNumber: createdOrder.orderNumber,
    paymentMethod: createdOrder.paymentMethod,
    paymentStatus: createdOrder.paymentStatus,
    paymentId: createdOrder.paymentId,
    stripePaymentIntentId: createdOrder.stripePaymentIntentId,
    paypalCaptureId: createdOrder.paypalCaptureId,
    subtotal: createdOrder.subtotal,
    shippingCost: createdOrder.shippingCost,
    tax: createdOrder.tax,
    discount: createdOrder.discount,
    total: createdOrder.total,
    preorderOutstandingAmount: createdOrder.preorderOutstandingAmount,
    currency: createdOrder.currency || settings.general?.defaultCurrency,
    channel: createdOrder.channel || "online",
    createdAt: createdOrder.createdAt,
  });

  // Stripe creates the order already paid, so both facts are recorded here.
  // The duplicate-key catch above means reaching this point implies THIS call
  // created the order — a replayed webhook returns early and audits nothing.
  const stripeActor = systemActor();
  await auditOrderPlaced(stripeActor, createdOrder, {
    source: "storefront",
    total: createdOrder.total,
    currency: createdOrder.currency || settings.general?.defaultCurrency,
    itemCount: createdOrder.items.length,
    paymentMethod: createdOrder.paymentMethod,
  });
  await auditOrderPaid(stripeActor, createdOrder, {
    gateway: "Stripe",
    amount:
      Number(createdOrder.total || 0) -
      Number(createdOrder.preorderOutstandingAmount || 0),
    currency: createdOrder.currency || settings.general?.defaultCurrency,
    transactionId: createdOrder.stripePaymentIntentId,
    partial: createdOrder.paymentStatus === PAYMENT_STATUS.PARTIALLY_PAID,
  });

  import("@/lib/customer")
    .then(({ refreshCustomerStats }) =>
      refreshCustomerStats(String(createdOrder.customerId)),
    )
    .catch((err) => console.error("Failed to refresh customer stats:", err));

  await applyCouponUsageForOrder(String(createdOrder._id)).catch((err) =>
    console.error("Failed to apply coupon usage on Stripe payment intent:", err),
  );

  try {
    if (hasPreorder) {
      await reservePreorderQuantity(getOrderPreorderLines(items));
      await markOrderPreorderReserved(String(createdOrder._id)).catch((err) =>
        console.error(
          "Failed to mark preorder reserved on Stripe payment intent:",
          err,
        ),
      );
    } else {
      await decrementInventory(
        items.map((item) => ({
          productId: String(item.productId._id),
          variantId: item.variantId,
          quantity: item.quantity,
        })),
      );
      await markOrderInventoryReserved(String(createdOrder._id)).catch((err) =>
        console.error(
          "Failed to mark inventory reserved on Stripe payment intent:",
          err,
        ),
      );
      revalidateProductContent({
        slugs: items
          .map((item) =>
            (item.productId as { slug?: string } | null)?.slug,
          )
          .filter(
            (slug): slug is string =>
              typeof slug === "string" && slug.length > 0,
          ),
      });
    }
  } catch (err) {
    if (err instanceof InsufficientStockError || err instanceof PreorderUnavailableError) {
      await Order.updateOne(
        { _id: createdOrder._id },
        { $set: { status: ORDER_STATUS.CANCELLED } },
      );
      // Charged, then auto-cancelled because stock ran out between checkout
      // and webhook. Without this the order just appears cancelled, with the
      // money taken and no explanation anywhere in the admin.
      await auditOrderCancelled(systemActor(), createdOrder, {
        from: String(createdOrder.status),
        by: "system",
        reason: "Inventory no longer available after payment was captured",
      });
      await reverseCouponUsageForOrder(String(createdOrder._id)).catch(
        (reverseErr) =>
          console.error(
            "Failed to reverse coupon usage after stock cancel:",
            reverseErr,
          ),
      );
      return {
        created: false,
        orderId: String(createdOrder._id),
        orderNumber: createdOrder.orderNumber,
      };
    }
    throw err;
  }

  await markCheckoutRecovered({
    cartId,
    orderId: createdOrder._id,
    paymentEvent: {
      gateway: "stripe",
      status: "succeeded",
      paymentId: paymentIntent.id,
      message: "Stripe PaymentIntent succeeded",
    },
  }).catch((err) =>
    console.error("Failed to mark abandoned checkout recovered:", err),
  );

  await Cart.findByIdAndUpdate(cartId, { $set: { items: [] } });

  const email = paymentIntent.receipt_email || customerEmail;
  if (email) {
    await sendOrderConfirmationEmail(
      {
        orderNumber: createdOrder.orderNumber,
        customerName: shippingAddress.fullName || "Customer",
        customerEmail: email,
        items: createdOrder.items.map(
          (i: {
            name: string;
            quantity: number;
            price: number;
            image?: string;
          }) => ({
            name: i.name,
            quantity: i.quantity,
            price: i.price,
            image: i.image,
          }),
        ),
        subtotal: createdOrder.subtotal,
        shipping: createdOrder.shippingCost,
        tax: createdOrder.tax,
        total: createdOrder.total,
        shippingAddress: createdOrder.shippingAddress,
        paymentMethod: createdOrder.paymentMethod,
      },
      settings,
    );
  }

  await notifyOrderCreatedParticipants(createdOrder).catch((err) =>
    console.error("Failed to create Stripe payment notifications:", err),
  );

  console.log("Order created successfully:", orderNumber);

  return {
    created: true,
    orderId: String(createdOrder._id),
    orderNumber: createdOrder.orderNumber,
  };
}

/**
 * Idempotently create an order for a completed Stripe Checkout Session.
 */
export async function finalizeStripeCheckoutSessionOrder(
  session: Stripe.Checkout.Session,
  settings: SettingsDocument,
): Promise<FinalizeStripeOrderResult> {
  const { metadata } = session;

  if (!metadata) {
    console.error("No metadata in checkout session");
    return { created: false };
  }

  const {
    userId,
    cartId,
    shippingAddress: shippingAddressStr,
    billingAddress: billingAddressStr,
    subtotal,
    shipping,
    tax,
    discount,
    total,
    couponCode,
    couponType,
    couponValue,
    couponId,
  } = metadata;

  const existingOrder = await Order.findOne({
    stripeSessionId: session.id,
  }).lean();
  if (existingOrder) {
    return {
      created: false,
      orderId: String(existingOrder._id),
      orderNumber: existingOrder.orderNumber,
    };
  }

  let shippingAddress: StripeOrderShippingAddress;
  try {
    shippingAddress = JSON.parse(shippingAddressStr);
  } catch {
    console.error("Failed to parse shipping address");
    return { created: false };
  }
  let billingAddress: StripeOrderShippingAddress = shippingAddress;
  if (billingAddressStr) {
    try {
      billingAddress = JSON.parse(billingAddressStr);
    } catch {
      billingAddress = shippingAddress;
    }
  }

  const cart = await Cart.findById(cartId)
    .populate({
      path: "items.productId",
      select: "name price images vendorId stock sku slug shipping variants",
      populate: { path: "vendorId", select: "_id" },
    })
    .lean();

  if (!cart || !cart.items || cart.items.length === 0) {
    console.error("Cart not found or empty:", cartId);
    return { created: false };
  }

  const items = cart.items as StripeOrderCartItem[];

  const sessionPaymentIntentId =
    typeof session.payment_intent === "string"
      ? session.payment_intent
      : session.payment_intent?.id || "";

  // A previously tamper-rejected (and refunded) intent must never fulfil an
  // order, even if the cart has since been edited back to the quoted sum.
  // Re-run the rejection: every step is idempotent, and it completes the
  // refund if a crash landed between the marker write and the refund on the
  // first attempt.
  if (isRejectedIntentForCart(cart, sessionPaymentIntentId)) {
    console.error(
      "Refusing to fulfil previously rejected Stripe intent:",
      sessionPaymentIntentId,
    );
    await rejectTamperedStripePayment({
      paymentIntentId: sessionPaymentIntentId,
      cartId: String(cart._id),
      settings,
    });
    return { created: false };
  }

  if (!stripeCartMatchesQuote(items, subtotal)) {
    await rejectTamperedStripePayment({
      paymentIntentId: sessionPaymentIntentId,
      cartId: String(cart._id),
      settings,
    });
    return { created: false };
  }

  const orderNumber = await getNextOnlineOrderNumber(settings.orders?.prefix);

  const vendorContext = await resolveOrderVendorContext({
    isMultiVendorEnabled: Boolean(settings.multiVendorMode?.enabled),
  });
  const vendorGroups = groupItemsByOrderVendor(
    items,
    vendorContext,
    (item) => item.productId.vendorId,
  );
  const subOrders = await buildVendorSubOrders(vendorGroups, {
    getProductId: (item) => item.productId._id,
    getVariantId: (item) => item.variantId,
    getName: (item) => item.productId.name,
    getSku: (item) => item.productId.sku,
    getQuantity: (item) => item.quantity,
    getPrice: (item) => item.price,
    getImage: (item) => item.productId.images?.[0],
    getPurchaseType: (item) => item.purchaseType || PURCHASE_TYPE.STANDARD,
    getPreorderReleaseDate: (item) => item.preorderReleaseDate,
    getPreorderMessage: (item) => item.preorderMessage,
    getPreorderStatus: (item) =>
      item.purchaseType === PURCHASE_TYPE.PREORDER
        ? PREORDER_ITEM_STATUS.RESERVED
        : undefined,
    getPreorderPaymentMode: (item) => item.preorderPaymentMode,
    getPreorderDepositAmount: (item) => item.preorderDepositAmount,
    getPreorderOutstandingAmount: (item) => item.preorderOutstandingAmount,
    getPreorderSupplierEta: (item) => item.preorderSupplierEta,
    getPreorderBatchName: (item) => item.preorderBatchName,
    getCustoms: (item) => buildOrderItemCustomsSnapshot({
      productShipping: item.productId.shipping,
      variantShipping: item.variantId
        ? item.productId.variants?.find(
            (candidate) => candidate._id.toString() === String(item.variantId),
          )
        : undefined,
    }),
    fallbackCommissionPercent:
      settings.orders?.commission?.vendorRate ?? DEFAULT_VENDOR_COMMISSION_RATE,
    status: items.some((item) => item.purchaseType === PURCHASE_TYPE.PREORDER)
      ? ORDER_STATUS.PREORDERED
      : ORDER_STATUS.PENDING,
  });

  // Apply shipping captured at PaymentIntent/Checkout creation so the
  // Stripe-created order matches the other payment paths (per-vendor split,
  // selected method, duties).
  const parsedShipping = parseShippingMetadata(metadata);
  allocateSubOrderShipping(
    subOrders as Array<{
      vendorId: { toString: () => string };
      shippingCost?: number;
      shippingMethod?: unknown;
    }>,
    {
      vendorShippingCosts: parsedShipping.vendorShippingCosts,
      orderShippingCost: parseFloat(shipping || "0"),
      orderShippingMethod: parsedShipping.shippingMethod,
    },
  );

  const hasPreorder = items.some(
    (item) => item.purchaseType === PURCHASE_TYPE.PREORDER,
  );
  const preorderReleaseDate = getPreorderReleaseDateForOrder(items);
  const preorderItems = items.filter(
    (item) => item.purchaseType === PURCHASE_TYPE.PREORDER,
  );
  const preorderPaymentModes = new Set(
    preorderItems.map((item) => item.preorderPaymentMode || "full"),
  );
  const preorderPaymentMode =
    preorderPaymentModes.size === 1
      ? Array.from(preorderPaymentModes)[0]
      : hasPreorder
        ? "full"
        : undefined;
  const preorderDepositAmount = preorderItems.reduce(
    (sum, item) => sum + Number(item.preorderDepositAmount || 0),
    0,
  );
  const preorderOutstandingAmount = preorderItems.reduce(
    (sum, item) => sum + Number(item.preorderOutstandingAmount || 0),
    0,
  );

  let createdOrder;
  try {
    createdOrder = await Order.create({
      customerId: userId,
      orderNumber,
      currency: settings.general?.defaultCurrency || "USD",
      items: items.map((item) => ({
        productId: item.productId._id,
        variantId: item.variantId,
        vendorId: getOrderItemVendorId(item.productId.vendorId, vendorContext),
        name: item.productId.name,
        sku: item.productId.sku || "",
        quantity: item.quantity,
        price: item.price,
        image: item.productId.images?.[0],
        purchaseType: item.purchaseType || PURCHASE_TYPE.STANDARD,
        preorderReleaseDate: item.preorderReleaseDate,
        preorderMessage: item.preorderMessage,
        preorderStatus:
          item.purchaseType === PURCHASE_TYPE.PREORDER
            ? PREORDER_ITEM_STATUS.RESERVED
            : undefined,
        preorderPaymentMode: item.preorderPaymentMode,
        preorderDepositAmount: item.preorderDepositAmount,
        preorderOutstandingAmount: item.preorderOutstandingAmount,
        preorderSupplierEta: item.preorderSupplierEta,
        preorderBatchName: item.preorderBatchName,
        customs: buildOrderItemCustomsSnapshot({
          productShipping: item.productId.shipping,
          variantShipping: item.variantId
            ? item.productId.variants?.find(
                (candidate) =>
                  candidate._id.toString() === String(item.variantId),
              )
            : undefined,
        }),
      })),
      subOrders,
      shippingAddress,
      billingAddress,
      digitalOnly: isDigitalOnlyOrder(items),
      paymentMethod: "card",
      paymentStatus:
        preorderOutstandingAmount > 0
          ? PAYMENT_STATUS.PARTIALLY_PAID
          : PAYMENT_STATUS.PAID,
      stripeSessionId: session.id,
      stripePaymentIntentId: String(session.payment_intent || ""),
      paymentId: String(session.payment_intent || ""),
      // "0" fallbacks: a missing metadata key would yield NaN, fail Order
      // validation, and put the webhook into a 500 retry loop (the PI path
      // already defaults — this keeps the session path consistent).
      subtotal: parseFloat(subtotal || "0"),
      shippingCost: parseFloat(shipping || "0"),
      shippingMethod: parsedShipping.shippingMethod,
      customs: parsedShipping.customs,
      tax: parseFloat(tax || "0"),
      discount: parseFloat(discount || "0"),
      coupon:
        couponCode && couponCode.trim()
          ? {
              code: couponCode.trim().toUpperCase(),
              type: couponType || undefined,
              value: couponValue ? Number(couponValue) : undefined,
              couponId: couponId || undefined,
              usageIncremented: false,
            }
          : undefined,
      total: parseFloat(total || "0"),
      channel: "online",
      hasPreorder,
      preorderStatus: hasPreorder ? PREORDER_ITEM_STATUS.RESERVED : undefined,
      preorderReleaseDate,
      preorderAcknowledgedAt: hasPreorder ? new Date() : undefined,
      preorderPaymentMode,
      preorderDepositAmount,
      preorderOutstandingAmount,
      status: hasPreorder ? ORDER_STATUS.PREORDERED : ORDER_STATUS.PROCESSING,
    });
  } catch (err: unknown) {
    if (
      err &&
      typeof err === "object" &&
      "code" in err &&
      (err as { code?: number }).code === 11000
    ) {
      const raced = await Order.findOne({
        stripeSessionId: session.id,
      }).lean();
      if (raced) {
        return {
          created: false,
          orderId: String(raced._id),
          orderNumber: raced.orderNumber,
        };
      }
    }
    throw err;
  }

  await ensureChargeTransaction({
    _id: String(createdOrder._id),
    orderNumber: createdOrder.orderNumber,
    paymentMethod: createdOrder.paymentMethod,
    paymentStatus: createdOrder.paymentStatus,
    paymentId: createdOrder.paymentId,
    stripePaymentIntentId: createdOrder.stripePaymentIntentId,
    paypalCaptureId: createdOrder.paypalCaptureId,
    subtotal: createdOrder.subtotal,
    shippingCost: createdOrder.shippingCost,
    tax: createdOrder.tax,
    discount: createdOrder.discount,
    total: createdOrder.total,
    preorderOutstandingAmount: createdOrder.preorderOutstandingAmount,
    currency: createdOrder.currency || settings.general?.defaultCurrency,
    channel: createdOrder.channel || "online",
    createdAt: createdOrder.createdAt,
  });

  // Stripe creates the order already paid, so both facts are recorded here.
  // The duplicate-key catch above means reaching this point implies THIS call
  // created the order — a replayed webhook returns early and audits nothing.
  const stripeActor = systemActor();
  await auditOrderPlaced(stripeActor, createdOrder, {
    source: "storefront",
    total: createdOrder.total,
    currency: createdOrder.currency || settings.general?.defaultCurrency,
    itemCount: createdOrder.items.length,
    paymentMethod: createdOrder.paymentMethod,
  });
  await auditOrderPaid(stripeActor, createdOrder, {
    gateway: "Stripe",
    amount:
      Number(createdOrder.total || 0) -
      Number(createdOrder.preorderOutstandingAmount || 0),
    currency: createdOrder.currency || settings.general?.defaultCurrency,
    transactionId: createdOrder.stripePaymentIntentId,
    partial: createdOrder.paymentStatus === PAYMENT_STATUS.PARTIALLY_PAID,
  });

  import("@/lib/customer")
    .then(({ refreshCustomerStats }) =>
      refreshCustomerStats(String(createdOrder.customerId)),
    )
    .catch((err) => console.error("Failed to refresh customer stats:", err));

  await applyCouponUsageForOrder(String(createdOrder._id)).catch((err) =>
    console.error("Failed to apply coupon usage on Stripe webhook:", err),
  );

  try {
    if (hasPreorder) {
      await reservePreorderQuantity(getOrderPreorderLines(items));
      await markOrderPreorderReserved(String(createdOrder._id)).catch((err) =>
        console.error("Failed to mark preorder reserved on Stripe webhook:", err),
      );
    } else {
      await decrementInventory(
        items.map((item) => ({
          productId: String(item.productId._id),
          variantId: item.variantId,
          quantity: item.quantity,
        })),
      );
      await markOrderInventoryReserved(String(createdOrder._id)).catch((err) =>
        console.error("Failed to mark inventory reserved on Stripe webhook:", err),
      );
      revalidateProductContent({
        slugs: items
          .map((item) =>
            (item.productId as { slug?: string } | null)?.slug,
          )
          .filter(
            (slug): slug is string =>
              typeof slug === "string" && slug.length > 0,
          ),
      });
    }
  } catch (err) {
    if (err instanceof InsufficientStockError || err instanceof PreorderUnavailableError) {
      await Order.updateOne(
        { _id: createdOrder._id },
        { $set: { status: ORDER_STATUS.CANCELLED } },
      );
      // Charged, then auto-cancelled because stock ran out between checkout
      // and webhook. Without this the order just appears cancelled, with the
      // money taken and no explanation anywhere in the admin.
      await auditOrderCancelled(systemActor(), createdOrder, {
        from: String(createdOrder.status),
        by: "system",
        reason: "Inventory no longer available after payment was captured",
      });
      await reverseCouponUsageForOrder(String(createdOrder._id)).catch(
        (reverseErr) =>
          console.error(
            "Failed to reverse coupon usage after stock cancel:",
            reverseErr,
          ),
      );
      return {
        created: false,
        orderId: String(createdOrder._id),
        orderNumber: createdOrder.orderNumber,
      };
    }
    throw err;
  }

  await markCheckoutRecovered({
    cartId,
    orderId: createdOrder._id,
    paymentEvent: {
      gateway: "stripe",
      status: "succeeded",
      paymentId: session.payment_intent
        ? String(session.payment_intent)
        : session.id,
      message: "Stripe Checkout completed",
    },
  }).catch((err) =>
    console.error("Failed to mark abandoned checkout recovered:", err),
  );

  await Cart.findByIdAndUpdate(cartId, { $set: { items: [] } });

  if (session.customer_email) {
    await sendOrderConfirmationEmail(
      {
        orderNumber: createdOrder.orderNumber,
        customerName: shippingAddress.fullName || "Customer",
        customerEmail: session.customer_email,
        items: createdOrder.items.map(
          (i: {
            name: string;
            quantity: number;
            price: number;
            image?: string;
          }) => ({
            name: i.name,
            quantity: i.quantity,
            price: i.price,
            image: i.image,
          }),
        ),
        subtotal: createdOrder.subtotal,
        shipping: createdOrder.shippingCost,
        tax: createdOrder.tax,
        total: createdOrder.total,
        shippingAddress: createdOrder.shippingAddress,
        paymentMethod: createdOrder.paymentMethod,
      },
      settings,
    );
  }

  await notifyOrderCreatedParticipants(createdOrder).catch((err) =>
    console.error("Failed to create Stripe checkout notifications:", err),
  );

  console.log("Order created successfully:", orderNumber);

  return {
    created: true,
    orderId: String(createdOrder._id),
    orderNumber: createdOrder.orderNumber,
  };
}