@zoxllc/shopify-checkout-extensions 0.0.8 → 0.2.0

package/CLAUDE.md

@@ -0,0 +1,136 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a TypeScript library for Shopify checkout extensions. It provides reusable utility classes for building discount campaigns, qualifiers, and selectors that can be shared across multiple Shopify Functions (Product Discount Functions, Shipping Discount Functions, Cart Validation Functions).
+
+## Commands
+
+### Build
+```bash
+npm run build
+```
+Compiles TypeScript to JavaScript in the `dist/` directory. Always run before publishing.
+
+### Testing
+```bash
+npm test          # Run all tests with Vitest
+```
+
+### Publishing
+```bash
+npm run prepublishOnly  # Automatically runs build before publishing
+```
+
+## Architecture
+
+### Core Concepts
+
+The library is built around three main abstractions:
+
+1. **Campaigns**: Define discount logic and qualification rules (e.g., `BuyXGetY`, `ConditionalDiscount`, `ShippingDiscount`)
+2. **Qualifiers**: Determine if a cart/customer meets certain conditions (e.g., cart amount, customer tags, country)
+3. **Selectors**: Target specific products/items in the cart (e.g., by product ID, tag, type)
+
+### Campaign System
+
+**Campaign** (src/common/Campaign.ts) is the base class with a lifecycle:
+- `qualifies()`: Checks if all qualifiers match based on `QualifierBehavior` (ALL or ANY)
+- `runWithHooks()`: Executes the campaign lifecycle
+- `run()`: Override this in subclasses to apply discount logic
+- `afterRun()`: Post-processing hook
+
+Campaign types:
+- **ConditionalDiscount** (src/lineItem/ConditionalDiscount.ts): Apply discounts when qualifiers match
+- **BuyXGetY** (src/lineItem/BuyXGetY.ts): Buy X items, get Y items with discount
+- **ShippingDiscount** (src/shipping/ShippingDiscount.ts): Apply discounts to shipping rates
+
+### CampaignFactory Pattern
+
+**CampaignFactory** (src/common/CampaignFactory.ts) creates campaigns from JSON configuration objects. Configuration has this structure:
+
+```typescript
+{
+  __type: 'BuyXGetY' | 'ConditionalDiscount' | 'ShippingDiscount',
+  label: string,
+  active: boolean,
+  inputs: [/* constructor arguments */]
+}
+```
+
+The factory recursively deserializes nested objects (qualifiers, selectors, discounts) using the `__type` field as a discriminator.
+
+### Qualifiers
+
+**Qualifier** (src/common/Qualifier.ts) is the base class. Qualifiers check cart/customer conditions:
+
+- **AndSelector/OrSelector**: Combine multiple qualifiers with AND/OR logic
+- **CartAmountQualifier**: Check cart subtotal amount
+- **CartQuantityQualifier**: Check total item quantity
+- **PostCartAmountQualifier**: Check cart amount after discounts
+- **CustomerTagQualifier**: Check customer tags
+- **CustomerEmailQualifier**: Match customer email patterns
+- **CustomerSubscriberQualifier**: Check if customer is a subscriber
+- **CountryCodeQualifier**: Match shipping country
+- **CartHasItemQualifier**: Check if cart contains specific items
+
+Qualifiers use enums for comparison:
+- `QualifierMatchType`: DOES, DOES_NOT
+- `NumericalComparisonType`: GREATER_THAN, EQUAL_TO, etc.
+- `StringComparisonType`: MATCH, CONTAINS, START_WITH, END_WITH
+
+### Selectors
+
+**Selector** (src/common/Selector.ts) targets items in the cart:
+
+- **ProductIdSelector**: Match by product variant ID
+- **ProductTagSelector**: Match by product tags
+- **ProductTypeSelector**: Match by product type
+- **ProductHandleSelector**: Match by product handle
+- **SaleItemSelector**: Match items on sale
+- **SubscriptionItemSelector**: Match subscription items
+- **RateNameSelector**: Match shipping rates by name (for shipping discounts)
+
+Selectors use `MatchType` enum: ALL, IS_ONE, NOT_ONE, DOES, DOES_NOT
+
+### DiscountCart Wrapper
+
+**DiscountCart** (src/common/DiscountCart.ts) wraps Shopify's cart object and provides:
+- `subtotalAmount`: Cart subtotal excluding gifts
+- `appliedDiscountTotal`: Track applied discounts
+- `totalLineItemQuantity()`: Total items in cart
+- `subtotalExcludingGifts()`: Excludes items tagged `meta-exclude-gift`
+- `addDiscount()`, `addShippingDiscount()`: Track applied discounts
+- `reset()`: Reset discount tracking
+
+### API Types
+
+- **src/lineItem/api.ts**: TypeScript types for Product Discount Functions
+- **src/shipping/api.ts**: TypeScript types for Shipping Discount Functions
+
+These files contain Shopify's GraphQL schema types for cart, products, customers, etc.
+
+### Special Conventions
+
+- Items tagged with `meta-exclude-gift` are excluded from cart totals and quantities
+- The library supports both percentage and fixed-amount discounts
+- Discounts can apply per-item or to the entire target group
+
+## Configuration & Validation
+
+**ConfigValidator** (src/common/ConfigValidator.ts) validates campaign configurations before use:
+```typescript
+const result = ConfigValidator.validate(config);
+if (!result.valid) {
+  console.error(result.errors);
+}
+```
+
+**ConfigSchema** (src/common/ConfigSchema.ts) provides JSON Schema definitions for configurations, useful for:
+- Form validation in UI applications
+- Documentation of configuration structure
+- Type safety with TypeScript
+
+See EXAMPLES.md for complete configuration examples.

package/EXAMPLES.md

@@ -0,0 +1,463 @@
+# Example Campaign Configurations
+
+This document shows example JSON configurations that can be used with the CampaignFactory.
+
+## How to Use
+
+In your Shopify app, store these configurations in your database or as metafields. Then, in your Shopify Function:
+
+```typescript
+import { CampaignFactory, DiscountCart } from '@zoxllc/shopify-checkout-extensions';
+
+export function run(input) {
+  // Get configuration from metafield or API
+  const config = JSON.parse(input.discountNode.metafield?.value || '{}');
+
+  // Create campaign from configuration
+  const campaign = CampaignFactory.createFromConfig(config);
+
+  // Run the campaign
+  const cart = new DiscountCart(input.cart);
+  campaign.runWithHooks(cart);
+
+  return { discounts: cart.discounts };
+}
+```
+
+---
+
+## Example 1: Simple Percentage Discount for VIP Customers
+
+**Use Case:** Give 20% off to customers with the "VIP" tag
+
+```json
+{
+  "__type": "ConditionalDiscount",
+  "label": "VIP Customer Discount",
+  "active": true,
+  "description": "20% off for VIP customers",
+  "inputs": [
+    ":all",
+    [
+      {
+        "__type": "CustomerTagQualifier",
+        "inputs": [":does", ":match", ["VIP"]]
+      }
+    ],
+    {
+      "__type": "PercentageDiscount",
+      "inputs": [20, "VIP Discount - 20% Off"]
+    },
+    null,
+    0
+  ]
+}
+```
+
+---
+
+## Example 2: Spend $100, Get 15% Off
+
+**Use Case:** Discount when cart subtotal is over $100
+
+```json
+{
+  "__type": "ConditionalDiscount",
+  "label": "Spend $100 Get 15% Off",
+  "active": true,
+  "inputs": [
+    ":all",
+    [
+      {
+        "__type": "CartAmountQualifier",
+        "inputs": [":subtotal", ":greater_than_or_equal", 100]
+      }
+    ],
+    {
+      "__type": "PercentageDiscount",
+      "inputs": [15, "Spend $100+ and Save 15%"]
+    },
+    null,
+    0
+  ]
+}
+```
+
+---
+
+## Example 3: Buy 2, Get 1 Free
+
+**Use Case:** Buy 2 of any product with tag "eligible", get 1 free (100% off)
+
+```json
+{
+  "__type": "BuyXGetY",
+  "label": "Buy 2 Get 1 Free",
+  "active": true,
+  "inputs": [
+    ":all",
+    [],
+    {
+      "__type": "PercentageDiscount",
+      "inputs": [100, "Buy 2 Get 1 Free!"]
+    },
+    {
+      "__type": "ProductTagSelector",
+      "inputs": [":does", ":match", ["eligible"]]
+    },
+    {
+      "__type": "ProductTagSelector",
+      "inputs": [":does", ":match", ["eligible"]]
+    },
+    2,
+    1,
+    null
+  ]
+}
+```
+
+---
+
+## Example 4: Discount Specific Products
+
+**Use Case:** 10% off specific product variants
+
+```json
+{
+  "__type": "ConditionalDiscount",
+  "label": "10% Off Select Products",
+  "active": true,
+  "inputs": [
+    ":all",
+    [],
+    {
+      "__type": "PercentageDiscount",
+      "inputs": [10, "10% Off Select Items"]
+    },
+    {
+      "__type": "ProductIdSelector",
+      "inputs": [
+        ":is_one",
+        [
+          "gid://shopify/ProductVariant/123456789",
+          "gid://shopify/ProductVariant/987654321"
+        ]
+      ]
+    },
+    0
+  ]
+}
+```
+
+---
+
+## Example 5: Free Shipping for Orders Over $50
+
+**Use Case:** Free shipping when cart is over $50
+
+```json
+{
+  "__type": "ShippingDiscount",
+  "label": "Free Shipping Over $50",
+  "active": true,
+  "inputs": [
+    ":all",
+    [
+      {
+        "__type": "CartAmountQualifier",
+        "inputs": [":subtotal", ":greater_than_or_equal", 50]
+      }
+    ],
+    {
+      "__type": "PercentageDiscount",
+      "inputs": [100, "Free Shipping!"]
+    },
+    {
+      "__type": "RateNameSelector",
+      "inputs": [":does", ":contains", ["Standard"]]
+    }
+  ]
+}
+```
+
+---
+
+## Example 6: Country-Specific Discount
+
+**Use Case:** 25% off for Canadian customers
+
+```json
+{
+  "__type": "ConditionalDiscount",
+  "label": "Canada Day Sale",
+  "active": true,
+  "inputs": [
+    ":all",
+    [
+      {
+        "__type": "CountryCodeQualifier",
+        "inputs": [":does", ["CA"]]
+      }
+    ],
+    {
+      "__type": "PercentageDiscount",
+      "inputs": [25, "Canada Day - 25% Off"]
+    },
+    null,
+    0
+  ]
+}
+```
+
+---
+
+## Example 7: Discount on Sale Items Only
+
+**Use Case:** Extra 10% off items already on sale
+
+```json
+{
+  "__type": "ConditionalDiscount",
+  "label": "Extra 10% Off Sale Items",
+  "active": true,
+  "inputs": [
+    ":all",
+    [],
+    {
+      "__type": "PercentageDiscount",
+      "inputs": [10, "Extra 10% Off Sale!"]
+    },
+    {
+      "__type": "SaleItemSelector",
+      "inputs": [":is_on_sale"]
+    },
+    0
+  ]
+}
+```
+
+---
+
+## Example 8: Subscriber Discount
+
+**Use Case:** 15% off for active subscribers
+
+```json
+{
+  "__type": "ConditionalDiscount",
+  "label": "Subscriber Discount",
+  "active": true,
+  "inputs": [
+    ":all",
+    [
+      {
+        "__type": "CustomerSubscriberQualifier",
+        "inputs": [":does"]
+      }
+    ],
+    {
+      "__type": "PercentageDiscount",
+      "inputs": [15, "Subscriber Exclusive - 15% Off"]
+    },
+    null,
+    0
+  ]
+}
+```
+
+---
+
+## Example 9: Multiple Conditions (AND Logic)
+
+**Use Case:** 30% off for VIP customers in the US with cart over $75
+
+```json
+{
+  "__type": "ConditionalDiscount",
+  "label": "VIP US High Value",
+  "active": true,
+  "inputs": [
+    ":all",
+    [
+      {
+        "__type": "CustomerTagQualifier",
+        "inputs": [":does", ":match", ["VIP"]]
+      },
+      {
+        "__type": "CountryCodeQualifier",
+        "inputs": [":does", ["US"]]
+      },
+      {
+        "__type": "CartAmountQualifier",
+        "inputs": [":subtotal", ":greater_than_or_equal", 75]
+      }
+    ],
+    {
+      "__type": "PercentageDiscount",
+      "inputs": [30, "VIP Exclusive - 30% Off"]
+    },
+    null,
+    0
+  ]
+}
+```
+
+---
+
+## Example 10: Fixed Amount Discount
+
+**Use Case:** $10 off orders over $50
+
+```json
+{
+  "__type": "ConditionalDiscount",
+  "label": "$10 Off Orders Over $50",
+  "active": true,
+  "inputs": [
+    ":all",
+    [
+      {
+        "__type": "CartAmountQualifier",
+        "inputs": [":subtotal", ":greater_than_or_equal", 50]
+      }
+    ],
+    {
+      "__type": "FixedItemDiscount",
+      "inputs": [10, false, "$10 Off Your Order"]
+    },
+    null,
+    0
+  ]
+}
+```
+
+---
+
+## Configuration Structure Reference
+
+### ConditionalDiscount Inputs Array:
+1. **QualifierBehavior** - `:all` or `:any`
+2. **Qualifiers Array** - Array of qualifier configurations
+3. **Discount** - Discount configuration object
+4. **LineItemSelector** - Selector configuration (or `null` for all items)
+5. **MaxDiscounts** - Number (0 for unlimited, or specific count)
+
+### BuyXGetY Inputs Array:
+1. **QualifierBehavior** - `:all` or `:any`
+2. **Qualifiers Array** - Array of qualifier configurations
+3. **Discount** - Discount configuration object
+4. **BuyItemSelector** - Selector for items to buy
+5. **GetItemSelector** - Selector for items to discount
+6. **BuyX** - Number of items to buy
+7. **GetY** - Number of items to get discounted
+8. **MaxSets** - Maximum number of times to apply (or `null` for unlimited)
+
+### ShippingDiscount Inputs Array:
+1. **QualifierBehavior** - `:all` or `:any`
+2. **Qualifiers Array** - Array of qualifier configurations
+3. **Discount** - Discount configuration object
+4. **RateSelector** - Selector for shipping rates
+
+---
+
+## Example 11: Multi-Tier Gift with Purchase
+
+**Use Case:** Offer tiered gifts based on cart spend threshold (e.g., spend $75 get Gift A, $100 get Gift B, $250 get Gift C). Only the highest qualifying tier is applied.
+
+```json
+{
+  "__type": "MultiTierDiscount",
+  "label": "Winter 2025 Tiered GWP",
+  "active": true,
+  "description": "Spend more, get better gifts!",
+  "inputs": [
+    ":all",
+    [],
+    [
+      {
+        "threshold": 75,
+        "discount": {
+          "__type": "PercentageDiscount",
+          "inputs": [100, "Free Colorwheel F&F"]
+        },
+        "productIds": ["6638547533896"],
+        "itemsToDiscount": 1,
+        "label": "Free Colorwheel F&F"
+      },
+      {
+        "threshold": 100,
+        "discount": {
+          "__type": "PercentageDiscount",
+          "inputs": [100, "Free Goldie Mystery ZOX"]
+        },
+        "productIds": ["6640591011912"],
+        "itemsToDiscount": 1,
+        "label": "Free Goldie Mystery ZOX"
+      },
+      {
+        "threshold": 250,
+        "discount": {
+          "__type": "PercentageDiscount",
+          "inputs": [100, "Free Cosmic Drift Daily"]
+        },
+        "productIds": ["6980288053320"],
+        "itemsToDiscount": 1,
+        "label": "Free Cosmic Drift Daily"
+      }
+    ],
+    ["meta-exclude-gift"]
+  ]
+}
+```
+
+**How It Works:**
+- Customer adds items to cart totaling $150
+- Cart subtotal is calculated (excluding items tagged "meta-exclude-gift")
+- Tiers are evaluated from highest to lowest
+- $250 tier doesn't qualify ($150 < $250)
+- $100 tier DOES qualify ($150 >= $100)
+- Product "6640591011912" (Goldie Mystery ZOX) gets 100% discount
+- Lower tiers ($75) are NOT applied
+
+**Key Features:**
+- Automatically excludes gift items from threshold calculation
+- Only applies the highest qualifying tier (no stacking)
+- Supports product IDs or product tags per tier
+- Perfect for seasonal promotions with start/end dates
+
+### MultiTierDiscount Inputs Array:
+1. **QualifierBehavior** - `:all` or `:any`
+2. **Qualifiers Array** - Array of cart-level qualifiers (optional, can be empty `[]`)
+3. **Tiers Array** - Array of tier objects, each containing:
+   - `threshold` - Minimum cart amount to qualify
+   - `discount` - Discount configuration (typically 100% for free gifts)
+   - `productIds` - Array of product IDs to discount (optional)
+   - `productTags` - Array of product tags to discount (optional)
+   - `itemsToDiscount` - Maximum items to discount (optional, defaults to all)
+   - `label` - Display name for the tier (optional)
+4. **Exclude Tags** - Array of product tags to exclude from subtotal calculation (default: `["meta-exclude-gift"]`)
+
+---
+
+## Tips for Your UI App
+
+1. **Store configurations in your database** with fields:
+   - `id`, `shop_id`, `campaign_config` (JSON), `priority`, `created_at`, `updated_at`
+
+2. **Use the ConfigValidator** before saving:
+   ```typescript
+   import { ConfigValidator } from '@zoxllc/shopify-checkout-extensions';
+
+   const result = ConfigValidator.validate(userConfig);
+   if (!result.valid) {
+     return { errors: result.errors };
+   }
+   ```
+
+3. **Pass configurations via metafields** to your Shopify Function:
+   - Store the JSON configuration in a discount metafield
+   - Read it in your Function's `input.discountNode.metafield.value`
+
+4. **Test configurations** before activating:
+   - Use the `DiscountCart` class with sample cart data
+   - Preview what discounts would be applied