@discount-depot/hydrogen 0.1.4

package/README.md

@@ -0,0 +1,337 @@
+# Discount Depot for Hydrogen
+
+Reusable automatic-discount price previews for Shopify Hydrogen stores.
+The package has separate React and server entry points. One shared API URL ships
+inside the package; no Discount Depot tokens or merchant environment settings are required. Tested with Hydrogen 2026.4.5, React 18.3.1,
+React Router 7.16.0 and Vite 8. Other headless frameworks require their own
+server adapter; this package is not a universal Shopify theme app extension.
+
+## Merchant setup
+
+1. Install the package supplied by Discount Depot. During development, install
+   the provided tarball: `npm install ./discount-depot-hydrogen-0.1.3.tgz`.
+   After publication, the command will be `npm install @discount-depot/hydrogen`.
+   This repository does not publish it automatically.
+
+2. Add `app/routes/($locale).api.discount-depot.ts`:
+
+   ```ts
+   import {createDiscountDepotRoute} from '@discount-depot/hydrogen/server';
+
+   const discountDepot = createDiscountDepotRoute();
+   export const action = discountDepot.action;
+   export const loader = discountDepot.loader;
+   ```
+
+   A store without optional locale routing can name it `api.discount-depot.ts`.
+   Keep `/api/discount-depot` as the public path. For a different path, pass
+   `endpoint` to the component. Route registration follows the host's route setup.
+
+3. Wrap the existing PDP price block:
+
+   ```tsx
+   import {DiscountDepotPrice} from '@discount-depot/hydrogen/react';
+
+   <DiscountDepotPrice variant={selectedVariant}>
+     <ProductPrice
+       price={selectedVariant?.price}
+       compareAtPrice={selectedVariant?.compareAtPrice}
+     />
+   </DiscountDepotPrice>;
+   ```
+
+   `variant` needs only `id` and `price: {amount, currencyCode}`. No product
+   loader edits, product IDs, hardcoded shop name or discount logic are needed.
+   Existing price markup remains the fallback. Optional props: `locale` for
+   number formatting, `className` for the discount block, and `endpoint` for
+   a custom resource route. Restart the development server after installation.
+
+## Behavior
+
+### Collection and catalog batches
+
+Use `DiscountDepotCollection` from the React entry point for a grid. Pass only
+the **current connection page's variants**, not the accumulated Load more list.
+Its render function receives a map keyed by variant ID. Pass each mapped result
+to `DiscountDepotPricePreview`, which is presentational and never fetches:
+
+```tsx
+<DiscountDepotCollection
+  variants={pageProducts.map((p) => p.selectedOrFirstAvailableVariant)}
+>
+  {(discounts) =>
+    visibleProducts.map((product) => (
+      <DiscountDepotPricePreview
+        key={product.id}
+        variant={product.selectedOrFirstAvailableVariant}
+        discount={discounts.get(
+          product.selectedOrFirstAvailableVariant?.id ?? '',
+        )}
+      >
+        <ExistingProductPrice product={product} />
+      </DiscountDepotPricePreview>
+    ))
+  }
+</DiscountDepotCollection>
+```
+
+This repository's `DiscountDepotProductGrid` connects this to Hydrogen Pagination
+and `ProductItem`. Include `selectedOrFirstAvailableVariant { id price { amount
+currencyCode } }` in grid queries. Configure page sizes at 50 or fewer; the
+component batches at most 50 unique variants and leaves extra cards at regular
+prices. It retains results for accumulated cards, requests each new page once,
+and separates results by collection/market/filter context. An optional `scopeKey`
+can define custom filter scope for other pagination implementations.
+
+The same local route accepts `{"variantIds":["gid://shopify/ProductVariant/..."]}`.
+It resolves IDs with one `nodes(ids: $ids)` Storefront query and sends one POST to
+the shared `/api/headless/discounts` backend with `{"requests":[...]}`. Each request
+row has the same shop/product/variant/price/currency/country/automatic fields as
+the single-product endpoint. The response is `{"discounts":[{"variantId":"...",
+"discount":{...}}]}`. Null, missing, duplicate or invalid result rows fall back
+independently. The batch contract may omit `discountType` inside a discount;
+an explicitly non-automatic type is rejected. The original amount always comes
+from Shopify. A batch with more than 50 IDs, an empty batch or malformed IDs
+returns HTTP 400.
+
+Both price renderers prefer `ruleLabel` over `message`, allow only selected CSS
+properties and simple safe values in `ruleLabelCss`, use a validated `priceColor`,
+and show the original amount only for `showOriginalPrice === true`. There is no
+HTML injection or CSS stylesheet injection. Existing `DiscountDepotPrice`
+continues to use the single-variant route for PDPs.
+
+The first server render and loading state show the existing Shopify price.
+After hydration, the widget requests its same-origin resource route. That
+route reads Shopify's actual price, product ID and market on the server and
+calls the common Discount Depot endpoint with the domain returned by Hydrogen's
+`storefront.getShopifyDomain()`. Browser-provided prices and shops are ignored. The widget cancels stale requests and refetches when
+the variant, price, currency or locale route changes. Missing configuration,
+ineligible offers and outages preserve the existing price. There is no shared
+cross-store price cache or mutable global store configuration.
+
+Automatic discounts only are displayed. Cart/checkout amounts remain computed
+by Shopify: the app must create the matching Shopify automatic discount.
+This package never changes merchandise prices or applies coupon codes.
+
+## Backend contract
+
+`POST /api/headless/discount`, JSON, without an Authorization header:
+
+```json
+{
+  "shop": "merchant.myshopify.com",
+  "productId": "gid://shopify/Product/123",
+  "variantId": "gid://shopify/ProductVariant/456",
+  "price": "1000.00",
+  "currencyCode": "INR",
+  "country": "IN",
+  "discountType": "AUTOMATIC"
+}
+```
+
+Normalize `shop` and use it to select that installed store's active public
+rules. Scope every lookup by shop and verify that products/variants belong to
+it. Return no discount for unknown, uninstalled or disabled shops. If a store
+uses a custom domain, resolve it to the corresponding installed shop on your
+backend. Anonymous previews need no token; authenticated previews use the Shopify customer access token described below. The `shop`
+is a lookup key rather than proof of shop ownership. Return only public
+pricing/message fields, not private rule definitions or management data.
+
+Evaluate only active automatic discounts targeting this product/variant and
+market. Return no unit-price discount if quantity/cart/customer/BXGY eligibility
+cannot be established by this request. Use Shopify-compatible selection and
+combination rules. Price amounts are in major currency units (rupees, not paise).
+
+```json
+{
+  "eligible": true,
+  "discountType": "AUTOMATIC",
+  "displayPrice": "900.00",
+  "currencyCode": "INR",
+  "message": "10% automatic discount"
+}
+```
+
+No eligible discount: `{"eligible": false}`. No `data` wrapper. Non-automatic
+responses, mismatched currencies and invalid prices are rejected. The backend
+must calculate in the requested currency. The original amount comes from Shopify.
+Upstream calls time out after ten seconds; the widget stops waiting after fifteen.
+
+## Shared URL: set once in the package
+
+Set the full working endpoint in `src/config.ts`:
+
+```ts
+export const DISCOUNT_DEPOT_API_URL =
+  'https://custompricing.axtrics.com/api/headless/discount';
+```
+
+The shared staging endpoint is configured in this release. Build and pack after
+changing it. Backend availability and discount responses must be verified before
+live rollout. All stores on that package version use the same URL.
+A changed URL requires rebuilding/distributing an updated package; use a stable
+domain so merchants do not need updates when your backend deployment changes.
+There are no Discount Depot API URL/token/shop env variables to configure.
+
+## App-owner rollout
+
+Host one stable `/api/headless/discount` endpoint. In merchant onboarding,
+provide the package install command, resource route and price-wrapper snippets.
+The server receives `shop` automatically and looks up rules scoped to that
+shop. The backend still needs to implement the public automatic-discount lookup
+and matching Shopify automatic discounts for actual cart/checkout amounts.
+This repository does not contain the app backend.
+
+Build: `npm run build`. Create an installable package: `npm pack`.
+
+## PDP volume discount table
+
+## Cart Goal banner
+
+Exported components: `DiscountDepotCartGoal` (fetching) and
+`DiscountDepotCartGoalPreview` (presentation). Add a local route at
+`($locale).api.discount-depot.cart-goal.ts` using
+`createDiscountDepotCartGoalRoute()` from the server export. It reads the
+session cart with `context.cart.get({numCartLines:250})` and calls the shared
+`/api/headless/cart-goal` endpoint. It never forwards the cart secret.
+
+```tsx
+<DiscountDepotCartGoal cart={originalCart} pending={optimisticCart?.isOptimistic === true} />
+```
+
+Use the settled cart and mark pending optimistic mutations. Empty/incomplete
+carts, pending updates, invalid/currency-mismatched offers and failed requests
+hide the banner. Matching cart fingerprints prevent stale offers. Labels and
+safe cg_* style fields match the Cart Offer app block. Completed goals hide
+unless the backend returns a higher next tier. This is a promotional preview;
+Shopify remains responsible for totals and applying the actual discount.
+
+The storefront's `/cart` page is wired. Backend contract and implementation
+prompt: `guides/discount-depot-cart-goal-backend-prompt.md`.
+
+## Volume table integration
+
+## Buy X Get Y
+
+Enable `showBuyXGetY` on `DiscountDepotPrice` for PDP previews and on
+`DiscountDepotCartGoal` for cart offers. Both are enabled in this storefront.
+Existing single-product/cart requests carry `includeBuyXGetY:true`; no per-card
+requests are made. The backend must return the optional `buyXGetY` array.
+
+The reusable `DiscountDepotBuyXGetY` component accepts `offers`, `currencyCode`,
+optional `locale` and `allowCartActions` (default false). It displays conditions,
+reward products/prices, safe saved design and countdowns. In the cart, unlocked
+and available rewards with a positive validated `addQuantity` have a manual
+Add reward button using the localized Hydrogen cart route. Applied/sold-out
+rewards cannot be added. No automatic gift insertion/removal is implemented.
+Shopify's discount function determines actual cart/checkout savings.
+
+Backend implementation contract: `guides/discount-depot-bxgy-backend-prompt.md`.
+
+## Volume table usage
+
+Product discounts support countdowns independently: the single-preview backend
+returns an optional top-level `countdown` for its selected eligible product rule.
+The local adapter validates it into `discount.countdown`; `DiscountDepotPrice`
+renders it below the price even without `showVolumeTable`. It uses the same
+absolute-window rules as the volume timer. No extra network request is made.
+
+The table also renders an optional `volumeTable.countdown` below it. Its fields
+are `enabled: true`, `eligible: true`, ISO `startsAt`/`endsAt` with timezone, and
+optional plain-text `title`/`label`. It stays hidden outside that absolute window,
+updates every second, and never starts a fresh duration on refresh or variant
+change. Expiry hides only the timer. Missing/invalid metadata keeps it hidden.
+The backend must resolve the checkbox, eligibility, timezone and stable deadline
+from the saved rule; see `guides/discount-depot-countdown-backend-prompt.md` in
+the storefront repository. `DiscountDepotCountdown` is also exported for reuse.
+
+Put effective saved countdown customization in `countdown.design` for both
+product and volume timers. It supports the app's classic/banner/coupon themes
+(coupon uses sticky-bottom placement), dhms/hms/ms formats, unit labels, colors,
+safe linear gradients, font size, roundness, padding and timer padding. Use
+`vd_countdown_*` keys, unprefixed `countdown_*` or admin camelCase names. Existing
+volume table design is a fallback. Admin text renders as plain text; only known
+settings are used. Missing settings use matching theme defaults. The backend
+must send the saved design to reproduce merchant customization.
+
+Enable the table in the existing price wrapper:
+
+```tsx
+<DiscountDepotPrice variant={selectedVariant} showVolumeTable>
+  <ProductPrice price={selectedVariant?.price} />
+</DiscountDepotPrice>
+```
+
+This makes one combined request per selected variant, with
+`{variantId, includeVolumeTable: true}`. The adapter adds trusted Shopify context
+and forwards the flag to the existing single-preview backend endpoint. It does
+not change collection batch calls. Old backends that omit `volumeTable` keep
+working; the table stays hidden until the backend supplies eligible tiers.
+The table can display even when the unconditional product discount is null.
+Variant/market changes clear old data and ignore late responses.
+
+For custom layouts, the exported presentational component needs no network call:
+
+```tsx
+import {DiscountDepotVolumeTable} from '@discount-depot/hydrogen/react';
+
+<DiscountDepotVolumeTable variant={selectedVariant} table={preview.volumeTable} />
+```
+
+The `/server` export also provides `getDepotProductPreview(shop, input, apiUrl, true)`
+for server integrations. Both exports provide the `DepotVolumeTable` TypeScript
+type. A table has `eligible: true`, `discountType: 'AUTOMATIC'`, matching
+`currencyCode` and `originalPrice`, `condition: 'quantity' | 'subtotal'`, and
+1–50 tiers with decimal-string `minimum`, nullable `maximum`,
+`discountType: 'percentage' | 'fixed'`, `discountValue`, and nullable `unitPrice`.
+Quantity tiers require a unit price; subtotal tiers may leave it null.
+
+Saved `vd_*` design fields support the app block's labels, colors, border,
+roundness, padding, hover highlight and savings/price column visibility.
+Unprefixed legacy field names are also supported. Labels render as text, colors
+are validated, and numeric spacing is bounded; raw HTML/CSS is never injected.
+Invalid or ineligible tables render nothing and leave normal pricing usable.
+This component previews future volume tiers; Shopify calculates checkout totals.
+
+The storefront repository contains the full backend implementation prompt and
+JSON example in `guides/discount-depot-volume-backend-prompt.md`.
+
+## Customer eligibility with Shopify login
+
+Version 0.1.2 uses Hydrogen's existing Customer Account login, with no Discount
+Depot signing key or per-store key setup. Keep the normal Shopify customer login
+configured and expose `context.customerAccount` in the resource route context.
+The app must be installed and have customer permissions for tag/segment checks.
+
+For logged-in customers the route calls `getAccessToken()` on that server client
+and forwards the Shopify credential to Discount Depot in a server-only header.
+The backend discovers that shop's Customer Account API and verifies `customer { id }`
+with Shopify before evaluating customer IDs, tags, exclusions or live segments.
+PDP product prices, volume ladder rules and collection batches all use this flow.
+Browser JSON and incoming customer headers cannot override the session.
+
+The package returns no credentials or customer data to the browser. Both servers
+use private/no-store responses. Upstream redirects are rejected. Keep the shared
+backend on HTTPS and redact customer-token headers in infrastructure logs.
+
+Guest sessions request anonymous/guest offers. A failed session or missing
+Customer Account client keeps public offers but hides restricted offers.
+Returning from login/logout invalidates personalized previews. Shopify remains
+responsible for eligibility and totals at checkout; usage/cart-dependent offers
+are not established by this customer login integration.
+
+No `DISCOUNT_DEPOT_CUSTOMER_SIGNING_KEY` is needed. Update both backend and package
+from the earlier signed-proof implementation. This supports Shopify Customer
+Account sessions; legacy/custom login requires an adapter. Tests use Hydrogen
+2026.4.5, so compatibility with every Hydrogen release is not claimed.
+
+For custom server loaders, pass credentials resolved by your own trusted Shopify
+session as the optional final parameter of `getDepotProductPreview` or
+`getDepotDiscounts`: `{state: 'authenticated', accessToken, origin}`. Never accept
+this object from browser input. Prefer `createDiscountDepotRoute()` to get the
+automatic session integration.
+
+Version 0.1.3 fixes Oxygen runtime compatibility by using manual redirects and
+rejecting non-success responses. Customer credentials are never forwarded across
+redirects. The regression suite includes real workerd fetch tests for guest and
+logged-in PDP/batch requests.

package/dist/buy-x-get-y-data.d.ts

@@ -0,0 +1,29 @@
+import { type DepotCountdown } from './countdown-data.js';
+export interface DepotBuyXGetYOffer {
+    id: string;
+    eligible: true;
+    discountType: 'AUTOMATIC';
+    currencyCode: string;
+    title: string;
+    /** Fully resolved, plain-text condition; never claim an unearned gift is free. */
+    message: string;
+    status: 'potential' | 'unlocked' | 'applied';
+    /** Store-wide rewards use the compact message card, as in the app block. */
+    showGiftProducts: boolean;
+    gifts: {
+        variantId: string;
+        handle: string;
+        title: string;
+        image?: {
+            url: string;
+            altText: string;
+        } | null;
+        available: boolean;
+        originalPrice: string;
+        displayPrice: string;
+        addQuantity: number;
+    }[];
+    design: Record<string, string | number>;
+    countdown: DepotCountdown | null;
+}
+export declare function normalizeBuyXGetY(value: unknown, currency: string, allowCartActions?: boolean): DepotBuyXGetYOffer[];

package/dist/buy-x-get-y-data.js

@@ -0,0 +1,103 @@
+import { normalizeCountdown } from './countdown-data.js';
+export function normalizeBuyXGetY(value, currency, allowCartActions = false) {
+    if (!Array.isArray(value) || value.length > 10)
+        return [];
+    const money = (amount) => typeof amount === 'string' &&
+        /^\d+(?:\.\d+)?$/.test(amount) &&
+        Number.isFinite(Number(amount));
+    const text = (entry) => typeof entry === 'string' && entry.trim().length > 0 && entry.length <= 500;
+    const seen = new Set();
+    const offers = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const offer = raw;
+        if (!text(offer.id) ||
+            seen.has(offer.id) ||
+            offer.eligible !== true ||
+            offer.discountType !== 'AUTOMATIC' ||
+            offer.currencyCode !== currency ||
+            !text(offer.title) ||
+            !text(offer.message) ||
+            !['potential', 'unlocked', 'applied'].includes(offer.status ?? '') ||
+            !Array.isArray(offer.gifts) ||
+            offer.gifts.length > 20)
+            continue;
+        const gifts = [];
+        let invalid = false;
+        const ids = new Set();
+        for (const gift of offer.gifts) {
+            if (!gift ||
+                !/^gid:\/\/shopify\/ProductVariant\/\d+$/.test(gift.variantId) ||
+                ids.has(gift.variantId) ||
+                typeof gift.handle !== 'string' ||
+                !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,254}$/.test(gift.handle) ||
+                !text(gift.title) ||
+                typeof gift.available !== 'boolean' ||
+                !money(gift.originalPrice) ||
+                !money(gift.displayPrice) ||
+                Number(gift.displayPrice) > Number(gift.originalPrice) ||
+                !Number.isSafeInteger(gift.addQuantity) ||
+                gift.addQuantity < 0 ||
+                gift.addQuantity > 100) {
+                invalid = true;
+                break;
+            }
+            ids.add(gift.variantId);
+            gifts.push({
+                variantId: gift.variantId,
+                handle: gift.handle,
+                title: gift.title,
+                image: normalizeGiftImage(gift.image),
+                available: gift.available,
+                originalPrice: gift.originalPrice,
+                displayPrice: gift.displayPrice,
+                addQuantity: allowCartActions && offer.status === 'unlocked' && gift.available
+                    ? gift.addQuantity
+                    : 0,
+            });
+        }
+        if (invalid)
+            continue;
+        const design = {};
+        if (offer.design && typeof offer.design === 'object') {
+            for (const [key, entry] of Object.entries(offer.design).slice(0, 50)) {
+                if (/^[a-z_]+$/.test(key) &&
+                    ((typeof entry === 'string' && entry.length <= 300) ||
+                        (typeof entry === 'number' && Number.isFinite(entry))))
+                    design[key] = entry;
+            }
+        }
+        seen.add(offer.id);
+        offers.push({
+            id: offer.id,
+            eligible: true,
+            discountType: 'AUTOMATIC',
+            currencyCode: currency,
+            title: offer.title,
+            message: offer.message,
+            status: offer.status,
+            showGiftProducts: offer.showGiftProducts !== false,
+            gifts,
+            design,
+            countdown: normalizeCountdown(offer.countdown),
+        });
+    }
+    return offers;
+}
+function normalizeGiftImage(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const image = value;
+    if (typeof image.url !== 'string' || image.url.length > 2048)
+        return null;
+    try {
+        const url = new URL(image.url);
+        if (url.protocol !== 'https:' || url.username || url.password)
+            return null;
+        return { url: url.href, altText: typeof image.altText === 'string' ? image.altText.slice(0, 500) : '' };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/buy-x-get-y-design.d.ts

@@ -0,0 +1,2 @@
+import type { CSSProperties } from 'react';
+export declare function buyXGetYDesign(design: Record<string, string | number>): CSSProperties;

package/dist/buy-x-get-y-design.js

@@ -0,0 +1,38 @@
+import { safePriceColor } from './presentation.js';
+// Same setting names as bxgy-inline-styles.liquid. Only validated scalar
+// values reach CSS; backend-supplied stylesheets and HTML are never rendered.
+export function buyXGetYDesign(design) {
+    const colors = {
+        'card-background': ['bxgy_card_background_color', '#ffffff'],
+        'card-border-color': ['bxgy_card_border_color', '#e4e8ef', 'border_color'],
+        'header-background': ['bxgy_header_background_color', '#0f2027'],
+        'header-border-color': ['bxgy_header_border_color', '#203a43'],
+        'icon-background': ['bxgy_icon_background_color', 'rgba(255,255,255,0.15)'],
+        'icon-border-color': ['bxgy_icon_border_color', 'rgba(255,255,255,0.25)'],
+        'heading-text-color': ['bxgy_heading_text_color', '#ffffff'],
+        'body-text-color': ['bxgy_body_text_color', '#374151', 'text_color'],
+        'link-color': ['bxgy_link_color', '#2563eb'],
+        'item-background': ['bxgy_item_background_color', '#f8fafc'],
+        'item-border-color': ['bxgy_item_border_color', '#e9ecf2'],
+        'price-color': ['bxgy_price_color', '#16a34a'],
+        'button-background': ['bxgy_button_background_color', '#16a34a', 'button_background_color'],
+        'button-border-color': ['bxgy_button_border_color', '#15803d'],
+        'button-text-color': ['bxgy_button_text_color', '#ffffff', 'button_text_color'],
+        'warning-background': ['bxgy_warning_background_color', '#f0f9ff'],
+        'warning-border-color': ['bxgy_warning_border_color', '#bae6fd'],
+        'warning-text-color': ['bxgy_warning_text_color', '#0369a1'],
+    };
+    const style = {};
+    for (const [variable, [key, fallback, alias]] of Object.entries(colors)) {
+        style[`--bxgy-${variable}`] = safePriceColor(String(design[key] ?? (alias ? design[alias] : '') ?? '')) ?? fallback;
+    }
+    for (const [variable, key, fallback, alias] of [
+        ['card-border-radius', 'bxgy_card_border_radius', 16, 'border_radius'],
+        ['button-border-radius', 'bxgy_button_border_radius', 10, ''],
+    ]) {
+        const raw = design[key] ?? design[alias];
+        const value = raw !== undefined && raw !== '' ? Number(raw) : fallback;
+        style[`--bxgy-${variable}`] = `${Number.isFinite(value) ? Math.max(0, Math.min(200, value)) : fallback}px`;
+    }
+    return style;
+}