// Core types for digital asset bundling
type BundleType = 'FIXED' | 'MIX_AND_MATCH' | 'PROGRESSIVE';

interface BundleDefinition {
  id: string;
  type: BundleType;
  name: string;
  items: BundleItem[];
  pricingStrategy: PricingStrategy;
  constraints: Constraint[];
  digitalMetadata: {
    provisioningQueue: string;
    licenseType: 'PERPETUAL' | 'SUBSCRIPTION' | 'USAGE_BASED';
  };
}

interface BundleItem {
  assetId: string;
  quantity: number;
  required: boolean;
  category?: string; // Used for Mix-and-Match grouping
}

interface PricingStrategy {
  type: 'FLAT' | 'SUM_DISCOUNT' | 'HIGHEST_ITEM_FREE';
  value: number; // Amount or percentage
  currency: string;
}

interface Constraint {
  type: 'MIN_QUANTITY' | 'MAX_QUANTITY' | 'DEPENDENCY' | 'EXCLUSION';
  targetAssetId?: string;
  value: number;
  message: string;
}

class BundleResolver {
  async resolveBundle(
    bundleDef: BundleDefinition,
    selectedItems: Map<string, number>
  ): Promise<ResolvedBundle> {
    // 1. Constraint Validation
    const violations = this.validateConstraints(bundleDef, selectedItems);
    if (violations.length > 0) {
      throw new BundleValidationError(violations);
    }

    // 2. Expand Items
    const lineItems = this.expandItems(bundleDef, selectedItems);

    // 3. Calculate Price
    const price = this.calculatePrice(bundleDef.pricingStrategy, lineItems);

    // 4. Generate Entitlement Payload
    const entitlements = this.mapEntitlements(bundleDef, lineItems);

    return {
      bundleId: bundleDef.id,
      lineItems,
      totalAmount: price,
      currency: bundleDef.pricingStrategy.currency,
      entitlements,
      metadata: {
        provisioningQueue: bundleDef.digitalMetadata.provisioningQueue,
        licenseTyp

e: bundleDef.digitalMetadata.licenseType } }; }

private validateConstraints( bundle: BundleDefinition, selections: Map<string, number> ): string[] { const errors: string[] = []; // Implement logic to check dependencies, exclusions, and quantity limits // Example: Check if dependent asset is present bundle.constraints.forEach(c => { if (c.type === 'DEPENDENCY' && c.targetAssetId) { const hasTarget = selections.has(c.targetAssetId) && selections.get(c.targetAssetId)! > 0; const hasSource = selections.has(c.targetAssetId); // Logic varies by implementation // Validation logic... } }); return errors; }

private expandItems( bundle: BundleDefinition, selections: Map<string, number> ): ResolvedLineItem[] { // Logic to map bundle items to resolved line items // Handles quantity multiplication and asset metadata injection return []; }

// ... implementation details for pricing and entitlement mapping }

### 3. Architecture Decisions

*   **Idempotency:** Bundle resolution must be idempotent. The resolver should accept a `bundleToken` or deterministic hash of the bundle definition to ensure that repeated requests yield the same resolved structure, preventing double-provisioning.
*   **Event-Driven Provisioning:** Upon successful checkout, the system should emit a `BundlePurchased` event containing the `entitlements` payload. Downstream services (License Service, API Gateway, Content Delivery) consume this event to provision assets asynchronously. This decouples the payment flow from provisioning latency.
*   **Price Waterfall:** For `SUM_DISCOUNT` strategies, the discount must be allocated proportionally across line items for accurate revenue recognition and refund handling. Never apply the discount to a single line item unless the strategy is `HIGHEST_ITEM_FREE`.

### 4. Handling Digital Asset Specifics

Digital bundles require **Entitlement Graphs**. A bundle may include an API key that requires a specific tier of a backend service. The resolver must cross-reference the `licenseType` and inject configuration flags into the entitlement payload.

```typescript
interface EntitlementPayload {
  assetId: string;
  tenantId: string;
  config: Record<string, any>; // e.g., { apiRateLimit: 1000, features: ['pro_tool'] }
  expiry: Date | null;
  provisioningStatus: 'PENDING' | 'ACTIVE' | 'FAILED';
}

Pitfall Guide

1. Treating Bundles as Discounts

Mistake: Implementing bundles by applying a percentage discount to the cart total. Consequence: This obscures line-item granularity. Refunds become impossible to calculate accurately, and revenue reporting is corrupted. Digital entitlements may not be issued if the system expects individual asset purchases. Best Practice: Always resolve bundles into constituent line items with allocated prices, even if the total matches a discount.

2. Ignoring Dependency Graphs

Mistake: Allowing users to purchase a bundle where a core asset is missing a required dependency. Consequence: Provisioning failures. For example, a "Developer Bundle" includes a database license but the user lacks the required runtime environment license. Best Practice: Implement a dependency resolver that validates the full graph of assets before allowing checkout.

3. Race Conditions on Digital Inventory

Mistake: Checking inventory only at checkout submission. Consequence: Overselling of limited digital assets (e.g., unique license keys). Best Practice: Implement a two-phase commit or a reservation system. Reserve inventory upon cart validation and release if checkout fails within a timeout window.

4. Hard-coding Mix-and-Match Logic

Mistake: Writing if/else chains for bundle rules in the codebase. Consequence: Marketing requests require code deployments. Technical debt accumulates rapidly. Best Practice: Store bundle rules as JSON configurations or in a rules engine. The resolver interprets the configuration dynamically.

5. Proration Errors in Subscription Bundles

Mistake: Failing to prorate bundle items when upgrading/downgrading mid-cycle. Consequence: Customer overpayment or underpayment, leading to support tickets and revenue leakage. Best Practice: The pricing engine must support time-based proration for each line item within a bundle, calculating the delta based on remaining subscription time.

6. Circular Dependencies

Mistake: Defining bundles where Asset A requires Asset B, and Asset B requires Asset A. Consequence: Infinite loops in the resolver or validation errors. Best Practice: Run a cycle detection algorithm (e.g., DFS) on the bundle dependency graph during configuration validation.

7. Frontend Price Calculation

Mistake: Calculating bundle prices in the browser. Consequence: Security vulnerability. Users can manipulate prices. Best Practice: The frontend sends selected items to the backend; the backend returns the resolved price. Never trust client-side calculations.

Production Bundle

Action Checklist

• Define Bundle Schema: Create the JSON schema for BundleDefinition including constraints and digital metadata.
• Implement Resolver Service: Build the BundleResolver class with validation, expansion, and pricing logic.
• Add Cycle Detection: Integrate a graph algorithm to prevent circular dependencies in bundle configurations.
• Design Entitlement Events: Define the BundlePurchased event schema and ensure downstream services can consume it.
• Implement Reservation System: Add inventory reservation logic to prevent overselling digital assets.
• Audit Trail: Log all bundle resolutions and price calculations for compliance and debugging.
• Load Test Resolver: Verify resolver performance under high concurrency; ensure p99 latency meets SLA.
• Refund Logic: Implement logic to decompose refunds based on allocated line-item prices.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Simple Cross-Sell	Discount Overlay	Low complexity; no dependency management needed.	Low
SaaS Tier Upgrade	Graph-Based Resolver	Requires entitlement mapping and dependency validation.	Medium
Limited Key Pack	Fixed Bundle + Reservation	Ensures inventory integrity for scarce digital assets.	Medium
Dynamic Mix-and-Match	Config-Driven Resolver	Allows marketing agility without deployments.	High (Initial) / Low (Ongoing)
Subscription Add-ons	Proration-Aware Resolver	Handles mid-cycle changes accurately.	High

Configuration Template

Use this JSON structure to define bundles in your configuration management system.

{
  "bundleId": "bundle-dev-pro-2024",
  "type": "FIXED",
  "name": "Developer Pro Bundle",
  "pricingStrategy": {
    "type": "FLAT",
    "value": 99.00,
    "currency": "USD"
  },
  "items": [
    {
      "assetId": "lic-api-enterprise",
      "quantity": 1,
      "required": true
    },
    {
      "assetId": "lic-sdk-pro",
      "quantity": 1,
      "required": true
    }
  ],
  "constraints": [
    {
      "type": "DEPENDENCY",
      "targetAssetId": "lic-runtime-base",
      "message": "Runtime Base License is required for this bundle."
    }
  ],
  "digitalMetadata": {
    "provisioningQueue": "entitlement-queue",
    "licenseType": "SUBSCRIPTION",
    "billingCycle": "MONTHLY"
  }
}

Quick Start Guide

1. Initialize Schema: Add the BundleDefinition interface and validation schema to your shared types package.
2. Deploy Resolver: Implement the BundleResolver service and expose a POST /api/v1/bundles/resolve endpoint.
3. Create Test Bundle: Insert a simple fixed bundle into your configuration store using the template above.
4. Integrate Checkout: Update your checkout service to call the resolver endpoint when a bundle SKU is detected, replacing the bundle SKU with resolved line items before payment processing.
5. Verify Entitlements: Trigger a test purchase and confirm that the BundlePurchased event is emitted and consumed by the License Service.