packages/bundle-pricing/
├── src/
│   ├── types.ts          # Zod schemas & TypeScript types for Tiers, Slots, Goals & Scarcity
│   ├── constants.ts      # Production defaults (PICKSHO_FLASH_LIGHT_TIERS, DEFAULT_PICKSHO_VARIANTS)
│   ├── slots.ts          # allocateVariantSlots, updateSlotVariant, validateSlotAllocations
│   ├── pricing.ts        # calculateBundlePricing, formatUsd, BundlePricingOptions
│   ├── goals.ts          # calculateCartGoal (Gamified Free Shipping / VIP Milestone Tracker)
│   ├── scarcity.ts       # calculateScarcityDecay (Session-consistent urgency decay)
│   └── index.ts          # SSoT Barrel Export

import {
  calculateBundlePricing,
  allocateVariantSlots,
  updateSlotVariant,
  calculateCartGoal,
  calculateScarcityDecay,
  PICKSHO_FLASH_LIGHT_TIERS,
  DEFAULT_PICKSHO_VARIANTS,
  type BundleTierConfig,
} from '@kido/bundle-pricing';

// 1. Select the Best Value Tier (Buy 3 Flashlights @ $18.33 each)
const selectedTier = PICKSHO_FLASH_LIGHT_TIERS.find(t => t.id === 'picksho-tier-3')!;

// 2. Allocate 3 customizable variant slots initialized to 'tactical-black'
let slots = allocateVariantSlots(
  selectedTier.quantity,
  'tactical-black',
  [...DEFAULT_PICKSHO_VARIANTS]
);

// 3. Customer personalizes Slot #2 to 'coyote-tan' and Slot #3 to 'military-olive'
slots = updateSlotVariant(slots, 2, 'coyote-tan');
slots = updateSlotVariant(slots, 3, 'military-olive');

// 4. Calculate accurate bundle pricing & customer savings
const bundleResult = calculateBundlePricing(selectedTier, { slots });

console.log('Bundle Calculation:', {
  tierName: selectedTier.name,
  quantity: bundleResult.quantity,
  unitPrice: `$${bundleResult.unitPrice.toFixed(2)}`,
  totalPrice: `$${bundleResult.totalPrice.toFixed(2)}`,       // $54.99
  originalPrice: `$${bundleResult.totalOriginalPrice.toFixed(2)}`, // $107.97
  savings: `$${bundleResult.totalSavings.toFixed(2)}`,         // $52.98 savings!
  savingsPercent: `${bundleResult.savingsPercent}%`,           // 49%
  slotAssignments: bundleResult.slots.map(s => ({
    slot: s.slotIndex,
    variant: s.selectedVariantId,
  })),
});

// 5. Check Gamified Cart Goal for Free Shipping ($80.00 target)
const goalProgress = calculateCartGoal(bundleResult.totalPrice, 80.0);

console.log('Cart Goal Progress:', {
  current: `$${goalProgress.currentAmount.toFixed(2)}`,
  target: `$${goalProgress.targetAmount.toFixed(2)}`,
  remaining: `$${goalProgress.remainingAmount.toFixed(2)}`, // $25.01 remaining
  progress: `${goalProgress.progressPercent}%`,             // 68.7%
  unlocked: goalProgress.isUnlocked,                       // false
  message: goalProgress.motivationMessage,                 // "Add $25.01 more to unlock FREE Shipping!"
});

// 6. Evaluate Real-Time Scarcity & Stock Urgency (4 minutes into 15m promotion)
const scarcity = calculateScarcityDecay(100, 240, 2.0, 900);
console.log('Scarcity State:', {
  remainingStock: scarcity.remainingStock,                 // 92 units
  claimedPercent: `${scarcity.totalClaimedPercent}%`,      // 8%
  secondsLeft: scarcity.timerSecondsRemaining,             // 660s (11m 00s)
  isExpiringSoon: scarcity.isExpiringSoon,                 // false
});