Shopify Cart Transform API: bundle expansion, component pricing, and inventory integrity

import assert from "node:assert/strict";

export interface ComponentDefinition {
  variantId: string;
  sku: string;
  title: string;
  quantityPerBundle: number;
  weightRatio: number; // For proportional pricing distribution
  inStockQuantity: number;
}

export interface BundleDefinition {
  bundleVariantId: string;
  bundleSku: string;
  bundleTitle: string;
  advertisedPriceCents: number; // In smallest currency subunit (cents)
  components: ComponentDefinition[];
}

export interface CartLineItemInput {
  id: string; // gid://shopify/CartLine/101
  merchandiseId: string; // gid://shopify/ProductVariant/9001
  quantity: number;
  costCents: number;
  attributes: Record<string, string>;
}

export interface CartTransformRunInput {
  cartLines: CartLineItemInput[];
  bundlesCatalog: Record<string, BundleDefinition>;
  maxCartLineCeiling?: number;
}

export interface ExpandOperationLineItem {
  merchandiseId: string;
  quantity: number;
  price: {
    adjustment: {
      fixedPricePerUnit: {
        amount: string;
        currencyCode: string;
      };
    };
  };
  attributes?: Array<{ key: string; value: string }>;
}

export interface ExpandOperation {
  cartLineId: string;
  title: string;
  image?: { url: string };
  lineItems: ExpandOperationLineItem[];
}

export interface CartTransformRunResult {
  status: "EXPANDED" | "NOOP" | "INVENTORY_ERROR" | "CART_OVERFLOW_ERROR";
  operations: Array<{ expand: ExpandOperation }>;
  totalExpandedLines: number;
  allocatedPriceCents: number;
  discrepancyCents: number;
  errorMessage?: string;
}

/**
 * Pure WebAssembly Cart Transform simulation engine for bundle expansion.
 */
export function expandBundleCartTransform(
  input: CartTransformRunInput,
  currencyCode: string = "USD"
): CartTransformRunResult {
  const lineCeiling = input.maxCartLineCeiling ?? 250;
  const operations: Array<{ expand: ExpandOperation }> = [];
  let totalProjectedLines = input.cartLines.length;
  let allocatedPriceCentsSum = 0;
  let discrepancyCentsSum = 0;

  for (const line of input.cartLines) {
    const bundleDef = input.bundlesCatalog[line.merchandiseId];
    if (!bundleDef) {
      continue;
    }

    // Check inventory sufficiency across all constituent components
    for (const comp of bundleDef.components) {
      const requiredQuantity = comp.quantityPerBundle * line.quantity;
      if (comp.inStockQuantity < requiredQuantity) {
        return {
          status: "INVENTORY_ERROR",
          operations: [],
          totalExpandedLines: totalProjectedLines,
          allocatedPriceCents: 0,
          discrepancyCents: 0,
          errorMessage: `Component SKU ${comp.sku} is out of stock (required: ${requiredQuantity}, available: ${comp.inStockQuantity}) for bundle ${bundleDef.bundleSku}.`,
        };
      }
    }

    // Check cart line limit expansion defense (Shopify 250 line limit)
    const netLineAddition = bundleDef.components.length - 1;
    if (totalProjectedLines + netLineAddition > lineCeiling) {
      return {
        status: "CART_OVERFLOW_ERROR",
        operations: [],
        totalExpandedLines: totalProjectedLines + netLineAddition,
        allocatedPriceCents: 0,
        discrepancyCents: 0,
        errorMessage: `Bundle expansion exceeds Shopify checkout limit of ${lineCeiling} lines.`,
      };
    }

    // Calculate price allocation across components with exact cent-parity
    const totalWeight = bundleDef.components.reduce((sum, c) => sum + c.weightRatio, 0);
    const bundleUnitCents = bundleDef.advertisedPriceCents;
    let distributedCents = 0;

    // First pass: calculate proportional floor cents
    const componentPrices: number[] = bundleDef.components.map((comp) => {
      const share = comp.weightRatio / totalWeight;
      const compTotalCents = Math.floor(bundleUnitCents * share);
      distributedCents += compTotalCents;
      return compTotalCents;
    });

    // Remainder penny distribution: assign residual cents to highest weight component
    let remainderCents = bundleUnitCents - distributedCents;
    if (remainderCents > 0) {
      let maxWeightIndex = 0;
      let maxWeight = -1;
      for (let i = 0; i < bundleDef.components.length; i++) {
        if (bundleDef.components[i].weightRatio > maxWeight) {
          maxWeight = bundleDef.components[i].weightRatio;
          maxWeightIndex = i;
        }
      }
      componentPrices[maxWeightIndex] += remainderCents;
      distributedCents += remainderCents;
    }

    // Verify cent parity
    const parityError = bundleUnitCents - distributedCents;
    assert.equal(parityError, 0, "Price allocation must match bundle unit price down to zero cents");

    allocatedPriceCentsSum += distributedCents * line.quantity;
    discrepancyCentsSum += parityError;

    // Build the expand operation line items
    const expandedLineItems: ExpandOperationLineItem[] = bundleDef.components.map((comp, idx) => {
      const compCents = componentPrices[idx];
      const formattedPrice = (compCents / (100 * comp.quantityPerBundle)).toFixed(2);

      return {
        merchandiseId: comp.variantId,
        quantity: comp.quantityPerBundle * line.quantity,
        price: {
          adjustment: {
            fixedPricePerUnit: {
              amount: formattedPrice,
              currencyCode,
            },
          },
        },
        attributes: [
          { key: "_bundleParentId", value: line.merchandiseId },
          { key: "_bundleSku", value: bundleDef.bundleSku },
          { key: "_componentSku", value: comp.sku },
        ],
      };
    });

    operations.push({
      expand: {
        cartLineId: line.id,
        title: bundleDef.bundleTitle,
        lineItems: expandedLineItems,
      },
    });

    totalProjectedLines += netLineAddition;
  }

  if (operations.length === 0) {
    return {
      status: "NOOP",
      operations: [],
      totalExpandedLines: totalProjectedLines,
      allocatedPriceCents: 0,
      discrepancyCents: 0,
    };
  }

  return {
    status: "EXPANDED",
    operations,
    totalExpandedLines: totalProjectedLines,
    allocatedPriceCents: allocatedPriceCentsSum,
    discrepancyCents: discrepancyCentsSum,
  };
}