@medusa-it/cartlift 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @medusa-it/cartlift
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cart drawer and in-cart upsells for Catalyst storefronts on BigCommerce. Configure it from the Cartlift app in the BigCommerce control panel; the full install guide (with your keys filled in) is in its Setup tab.
+
+```bash
+pnpm add @medusa-it/cartlift
+```
+
+```env
+BIGCOMMERCE_CHANNEL_ID=1
+CARTLIFT_PUBLIC_KEY=cl_pub_…
+CARTLIFT_API_URL=https://…
+CARTLIFT_REVALIDATE_SECRET=cl_rev_…
+```
+
+| Entry | For | Exports |
+|---|---|---|
+| `@medusa-it/cartlift` | Server Components (layout, header) | `CartDrawerProvider`, `CartDrawer`, `CartTrigger`, `useCartDrawer`, `openCartDrawer`, `getCartConfig` |
+| `@medusa-it/cartlift/server` | `'use server'` files | `createCartAdapter`, `wrapAddToCart`, `CARTLIFT_PRODUCTS_QUERY`, `fromCatalystProducts`, `fromCatalystCart` |
+| `@medusa-it/cartlift/next` | Route handlers | `createRecommendationsRoute`, `createRevalidateRoute` |
+| `@medusa-it/cartlift/client` | Your own `'use client'` components | `useCartDrawer`, `openCartDrawer`, `CartTrigger` |
+
+```tsx
+// layout.tsx
+<CartDrawerProvider cart={cart} checkout={checkout} actions={{ addToCart, updateQuantity, removeItem, applyCoupon }} context={{ customerGroupId, country, locale }}>
+  {children}
+  <CartDrawer expressCheckout={<PayPalButton />} />
+</CartDrawerProvider>
+```
+
+Events: the drawer opens on `cartlift:added` and `cartlift:open` (window `CustomEvent`s); `wrapAddToCart()` triggers the first after a successful add.
+
+Styling: every colour defaults to Catalyst's theme tokens (`--primary`, `--foreground`, …); override with `--cl-accent`, `--cl-accent-fg`, `--cl-bg`, `--cl-fg`, `--cl-progress`, `--cl-radius`, `--cl-font` or from the Design tab.

package/dist/client/CartDrawer.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+export interface CartDrawerProps {
+    /** The merchant's express checkout buttons (PayPal, Apple Pay), when switched on in the control panel. */
+    expressCheckout?: ReactNode;
+    /** Replaces the drawer's own announcement line (e.g. Nudgekit's <AnnouncementBar />). */
+    announcement?: ReactNode;
+}
+export declare function CartDrawer({ expressCheckout, announcement }: CartDrawerProps): import("react").JSX.Element | null;

package/dist/client/CartDrawer.js

@@ -0,0 +1,100 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { lazy, Suspense, useEffect, useId, useRef, useState } from 'react';
+import { designVars } from '../views/styles.js';
+import { DrawerView } from '../views/views.js';
+import { giftNames, useCartDrawerContext } from './Provider.js';
+// The drawer itself (SPEC §3.1): a modal dialog sliding in from the side (a bottom sheet on phones),
+// with a focus trap, Escape and overlay to close, and no motion when the shopper asks for less.
+const Rail = lazy(() => import('./Rail.js'));
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+export function CartDrawer({ expressCheckout, announcement }) {
+    const d = useCartDrawerContext();
+    const titleId = useId();
+    const panel = useRef(null);
+    const returnFocus = useRef(null);
+    const [phase, setPhase] = useState('closed');
+    const isOpen = d?.isOpen ?? false;
+    // Mounted closed, then flipped on the next frame so the slide-in transition runs.
+    useEffect(() => {
+        if (isOpen) {
+            returnFocus.current = document.activeElement;
+            setPhase('opening');
+            const f = requestAnimationFrame(() => setPhase('open'));
+            return () => cancelAnimationFrame(f);
+        }
+        setPhase((p) => (p === 'closed' ? p : 'closing'));
+        const reduced = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+        const t = setTimeout(() => setPhase('closed'), reduced ? 0 : 260);
+        return () => clearTimeout(t);
+    }, [isOpen]);
+    // Focus into the dialog, lock the page's scroll, give focus back on close.
+    useEffect(() => {
+        if (phase !== 'open')
+            return;
+        const first = panel.current?.querySelector('.cl-head button');
+        first?.focus();
+        const root = document.documentElement;
+        const overflow = root.style.overflow;
+        root.style.overflow = 'hidden';
+        return () => {
+            root.style.overflow = overflow;
+        };
+    }, [phase]);
+    // A removed line takes its focused button with it: keep focus in the dialog.
+    const lines = d?.cart?.lines.length;
+    useEffect(() => {
+        if (phase === 'open' && (document.activeElement === document.body || !document.activeElement))
+            panel.current?.focus();
+    }, [phase, lines]);
+    // Keys are watched on the document: focus can fall out of the panel.
+    const close = d?.close;
+    useEffect(() => {
+        if (phase !== 'open' || !close)
+            return;
+        const onKeyDown = (e) => {
+            if (e.key === 'Escape') {
+                e.stopPropagation();
+                close();
+                return;
+            }
+            if (e.key !== 'Tab' || !panel.current)
+                return;
+            const items = [...panel.current.querySelectorAll(FOCUSABLE)].filter((el) => el.offsetParent !== null || el === document.activeElement);
+            if (!items.length)
+                return;
+            const first = items[0];
+            const last = items[items.length - 1];
+            const inside = panel.current.contains(document.activeElement);
+            if (!inside || (e.shiftKey && document.activeElement === first)) {
+                e.preventDefault();
+                (e.shiftKey ? last : first).focus();
+            }
+            else if (!e.shiftKey && document.activeElement === last) {
+                e.preventDefault();
+                first.focus();
+            }
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [phase, close]);
+    useEffect(() => {
+        if (phase === 'closed' && returnFocus.current) {
+            returnFocus.current.focus?.();
+            returnFocus.current = null;
+        }
+    }, [phase]);
+    if (!d?.config?.enabled || phase === 'closed')
+        return null;
+    const { config, cart, ctx, data } = d;
+    const shown = phase === 'open';
+    const { layout } = config;
+    const railOn = config.modules.includes('recommendations');
+    const rail = (title, recs) => recs && (_jsx(Suspense, { fallback: null, children: _jsx(Rail, { title: title }) }));
+    return (_jsxs("div", { className: "cl-root", style: designVars(config.design, layout), children: [_jsx("div", { className: "cl-overlay", "data-open": shown, onClick: d.close, "aria-hidden": "true" }), _jsx("div", { ref: panel, role: "dialog", "aria-modal": "true", "aria-labelledby": titleId, className: `cl-panel${layout.position === 'left' ? ' cl-panel--left' : ''}${layout.mobile === 'sheet' ? ' cl-panel--sheet' : ''}`, "data-open": shown, tabIndex: -1, children: _jsx(DrawerView, { config: config, cart: cart, ctx: ctx, titleId: titleId, error: d.error, giftNames: giftNames(data), bulk: data?.bulk, addonProducts: data?.extras, rail: rail(config.copy.railTitle, railOn), emptyRail: rail(config.copy.emptyRailTitle, config.features.emptyFeatured), announcement: announcement, express: expressCheckout, lineHandlers: { onQuantity: d.setQuantity, onRemove: d.remove }, footerHandlers: {
+                        onCoupon: d.applyCoupon ?? undefined,
+                        onRemoveCoupon: d.removeCoupon ?? undefined,
+                        onNote: d.setNote ?? undefined,
+                        onContinue: d.close,
+                    }, onAddon: d.toggleAddon, onClose: d.close }) })] }));
+}

package/dist/client/CartTrigger.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+export interface CartTriggerProps {
+    /** Item count from the header's own data; the drawer's live count replaces it once known. */
+    count?: number;
+    /** Without the drawer (switched off, outside the provider) the trigger is a plain link here. */
+    href?: string;
+    label?: string;
+    className?: string;
+    /** Replaces the bag icon. */
+    children?: ReactNode;
+}
+/** The header's cart button (in place of Catalyst's cart icon link). */
+export declare function CartTrigger({ count, href, label, className, children }: CartTriggerProps): import("react").JSX.Element;

package/dist/client/CartTrigger.js

@@ -0,0 +1,15 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { BagIcon } from '../views/views.js';
+import { useCartDrawerContext } from './Provider.js';
+/** The header's cart button (in place of Catalyst's cart icon link). */
+export function CartTrigger({ count, href = '/cart', label = 'Cart', className = 'cl-trigger', children }) {
+    const d = useCartDrawerContext();
+    const n = d?.cart ? d.cart.itemCount : (count ?? 0);
+    const badge = n > 0 && (_jsx("span", { className: "cl-badge", "aria-hidden": "true", children: n > 99 ? '99+' : n }));
+    const name = n > 0 ? `${label}, ${n} item${n === 1 ? '' : 's'}` : label;
+    if (!d?.config?.enabled) {
+        return (_jsxs("a", { href: href, className: className, "aria-label": name, children: [children ?? _jsx(BagIcon, {}), badge] }));
+    }
+    return (_jsxs("button", { type: "button", className: className, "aria-label": name, "aria-haspopup": "dialog", "aria-expanded": d.isOpen, onClick: d.open, children: [children ?? _jsx(BagIcon, {}), badge] }));
+}

package/dist/client/Provider.d.ts

@@ -0,0 +1,52 @@
+import { type ReactNode } from 'react';
+import { type AddSource, type CartActions, type DrawerData } from '../core/actions.js';
+import type { AddonOffer, CartLine, CartliftCart, CartliftConfig, RailProduct, ShopperContext } from '../core/types.js';
+export interface DrawerContextValue {
+    config: CartliftConfig | null;
+    /** The cart as shown: the server's, with pending changes applied. */
+    cart: CartliftCart | null;
+    ctx: ShopperContext;
+    isOpen: boolean;
+    /** Opened at least once on this page (the rail loads then). */
+    everOpened: boolean;
+    open: () => void;
+    close: () => void;
+    data: DrawerData | null;
+    loading: boolean;
+    error: string | null;
+    setQuantity: (line: CartLine, quantity: number) => void;
+    remove: (line: CartLine) => void;
+    add: (product: RailProduct, variantId: number | null, source: AddSource, ruleId?: string | null) => void;
+    applyCoupon: ((code: string) => Promise<string | null>) | null;
+    removeCoupon: ((code: string) => void) | null;
+    setNote: ((note: string) => void) | null;
+    toggleAddon: (addon: AddonOffer, on: boolean) => void;
+}
+/** The drawer's state, or null outside <CartDrawerProvider>. */
+export declare const useCartDrawerContext: () => DrawerContextValue | null;
+/** For the merchant's own components: open or close the drawer, read the item count. */
+export declare function useCartDrawer(): {
+    open: () => void;
+    close: () => void;
+    isOpen: boolean;
+    cart: CartliftCart | null;
+    itemCount: number;
+};
+/** Open the drawer from anywhere (also works from code outside React). */
+export declare function openCartDrawer(): void;
+export interface CartDrawerClientProviderProps {
+    config: CartliftConfig | null;
+    cart: CartliftCart | null;
+    actions: CartActions;
+    context?: ShopperContext;
+    /** The storefront's recommendations route (createRecommendationsRoute); null = no rail, gifts or add-on prices. */
+    endpoint?: string | null;
+    /** Loads the drawer's data itself in place of `endpoint` (storefronts without a server, such as Stencil). */
+    loadData?: DrawerDataLoader | null;
+    children?: ReactNode;
+}
+/** Answers the query the drawer would send to `endpoint` (cart=…&extra=…&bulk=1…). */
+export type DrawerDataLoader = (query: URLSearchParams, signal: AbortSignal) => Promise<DrawerData | null>;
+export declare function CartDrawerClientProvider({ config, cart: serverCart, actions, context, endpoint, loadData, children }: CartDrawerClientProviderProps): import("react").JSX.Element;
+/** Gift product names for the progress messages, from the loaded extras. */
+export declare function giftNames(data: DrawerData | null): Record<number, string>;

package/dist/client/Provider.js

@@ -0,0 +1,227 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, startTransition, useCallback, useContext, useEffect, useMemo, useOptimistic, useRef, useState } from 'react';
+import { ADDED_COOKIE, ADDED_EVENT, DEFAULT_ENDPOINT, OPEN_EVENT } from '../core/actions.js';
+import { applyPatch, cartSignature } from '../core/cart.js';
+import { giftPlan, progressFor, tiersFor } from '../core/thresholds.js';
+import { configureEvents, track, trackOnce } from './events.js';
+// The drawer's state (SPEC §2.1). The cart comes from the layout (already fetched, no request on
+// page load); changes go through the merchant's server actions, shown at once with useOptimistic and
+// replaced by the cart each action answers with.
+const GENERIC_ERROR = 'Something went wrong. Please try again.';
+const DrawerContext = createContext(null);
+/** The drawer's state, or null outside <CartDrawerProvider>. */
+export const useCartDrawerContext = () => useContext(DrawerContext);
+/** For the merchant's own components: open or close the drawer, read the item count. */
+export function useCartDrawer() {
+    const c = useContext(DrawerContext);
+    return { open: c?.open ?? openCartDrawer, close: c?.close ?? (() => undefined), isOpen: c?.isOpen ?? false, cart: c?.cart ?? null, itemCount: c?.cart?.itemCount ?? 0 };
+}
+/** Open the drawer from anywhere (also works from code outside React). */
+export function openCartDrawer() {
+    window.dispatchEvent(new CustomEvent(OPEN_EVENT));
+}
+function readCookie(name) {
+    const m = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
+    return m ? decodeURIComponent(m[1]) : null;
+}
+/** Gift tiers the shopper removed by hand this session: not added again. */
+const DECLINED_KEY = 'cl_gift_declined';
+function declinedGifts() {
+    try {
+        return new Set(sessionStorage.getItem(DECLINED_KEY)?.split('|').filter(Boolean) ?? []);
+    }
+    catch {
+        return new Set();
+    }
+}
+function declineGift(tierId) {
+    try {
+        sessionStorage.setItem(DECLINED_KEY, [...declinedGifts(), tierId].join('|'));
+    }
+    catch {
+        // no storage: it may be added again on the next change
+    }
+}
+const fetchEndpoint = (endpoint) => (query, signal) => fetch(`${endpoint}?${query}`, { signal, credentials: 'same-origin', headers: { Accept: 'application/json' } }).then((r) => (r.ok ? r.json() : null));
+export function CartDrawerClientProvider({ config, cart: serverCart, actions, context, endpoint = DEFAULT_ENDPOINT, loadData, children }) {
+    const [base, setBase] = useState(serverCart);
+    // A new cart from the layout (router refresh after an action, navigation) is the truth.
+    useEffect(() => setBase(serverCart), [serverCart]);
+    const [cart, addPatch] = useOptimistic(base, applyPatch);
+    const [isOpen, setOpen] = useState(false);
+    const [everOpened, setEverOpened] = useState(false);
+    const [error, setError] = useState(null);
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const ctx = useMemo(() => ({ ...context }), [context?.customerGroupId, context?.country, context?.locale]);
+    const enabled = !!config?.enabled;
+    useEffect(() => configureEvents(enabled ? (config?.events ?? null) : null), [enabled, config?.events]);
+    const open = useCallback(() => {
+        if (!enabled)
+            return;
+        setOpen(true);
+        setEverOpened(true);
+        track({ type: 'open' });
+    }, [enabled]);
+    const close = useCallback(() => setOpen(false), []);
+    // Listening first: effects run in order, and the cookie check below may dispatch at once.
+    useEffect(() => {
+        window.addEventListener(ADDED_EVENT, open);
+        window.addEventListener(OPEN_EVENT, open);
+        return () => {
+            window.removeEventListener(ADDED_EVENT, open);
+            window.removeEventListener(OPEN_EVENT, open);
+        };
+    }, [open]);
+    // Opening on add to cart: wrapAddToCart() leaves a short-lived cookie (a server action cannot
+    // dispatch DOM events); it is turned into the `cartlift:added` event, which opens the drawer.
+    useEffect(() => {
+        if (!enabled || !readCookie(ADDED_COOKIE))
+            return;
+        document.cookie = `${ADDED_COOKIE}=; Path=/; Max-Age=0; SameSite=Lax`;
+        window.dispatchEvent(new CustomEvent(ADDED_EVENT));
+    }, [serverCart, enabled]);
+    /** Run a server action: the patch shows at once, the answer replaces it. Resolves with the error shown, if any. */
+    const run = useCallback((patch, call) => new Promise((resolve) => {
+        startTransition(async () => {
+            if (patch)
+                addPatch(patch);
+            let message = null;
+            try {
+                const res = await call();
+                message = res.error ?? null;
+                if (!res.error || res.cart)
+                    startTransition(() => setBase(res.cart));
+            }
+            catch {
+                message = GENERIC_ERROR;
+            }
+            setError(message);
+            resolve(message);
+        });
+    }), [addPatch]);
+    const tiers = useMemo(() => (config && base ? tiersFor(config.thresholds, base.currency, ctx) : []), [config, base, ctx]);
+    const setQuantity = useCallback((line, quantity) => {
+        if (quantity <= 0)
+            return void run({ type: 'remove', lineId: line.id }, () => actions.removeItem({ lineId: line.id }));
+        void run({ type: 'quantity', lineId: line.id, quantity }, () => actions.updateQuantity({ lineId: line.id, productId: line.productId, variantId: line.variantId, quantity }));
+    }, [actions, run]);
+    const remove = useCallback((line) => {
+        if (config?.modules.includes('gift')) {
+            const tier = tiers.find((t) => t.type === 'gift' && t.giftProductId === line.productId);
+            if (tier)
+                declineGift(tier.id);
+        }
+        void run({ type: 'remove', lineId: line.id }, () => actions.removeItem({ lineId: line.id }));
+    }, [actions, run, config, tiers]);
+    const add = useCallback((product, variantId, source, ruleId = null) => {
+        if (source === 'upsell')
+            track({ type: 'add', productId: product.id, ruleId });
+        void run({ type: 'add', product, variantId, quantity: 1 }, () => actions.addToCart({ productId: product.id, variantId, quantity: 1, source, ruleId }));
+    }, [actions, run]);
+    const toggleAddon = useCallback((addon, on) => {
+        const product = data?.extras[addon.productId];
+        if (on) {
+            if (product)
+                add(product, addon.variantId, 'addon');
+            else
+                void run(null, () => actions.addToCart({ productId: addon.productId, variantId: addon.variantId, quantity: 1, source: 'addon' }));
+            return;
+        }
+        const line = cart?.lines.find((l) => l.productId === addon.productId);
+        if (line)
+            void run({ type: 'remove', lineId: line.id }, () => actions.removeItem({ lineId: line.id }));
+    }, [actions, add, cart, data, run]);
+    const applyCoupon = useMemo(() => (actions.applyCoupon ? (code) => run(null, () => actions.applyCoupon({ code })) : null), [actions, run]);
+    const removeCoupon = useMemo(() => (actions.removeCoupon ? (code) => void run(null, () => actions.removeCoupon({ code })) : null), [actions, run]);
+    const setNote = useMemo(() => (actions.setNote ? (note) => void run({ type: 'note', note }, () => actions.setNote({ note })) : null), [actions, run]);
+    // ---- Free gift automation (SPEC §3.2 module 2): one step per server answer -----------------------
+    const giftInFlight = useRef(false);
+    const giftFailed = useRef(new Set());
+    useEffect(() => {
+        if (!enabled || !config.modules.includes('gift') || !base || giftInFlight.current)
+            return;
+        const plan = giftPlan(base, config.thresholds, ctx, new Set([...declinedGifts(), ...giftFailed.current]));
+        const step = plan.add[0] ? { kind: 'add', ...plan.add[0] } : plan.remove[0] ? { kind: 'remove', ...plan.remove[0] } : null;
+        if (!step)
+            return;
+        giftInFlight.current = true;
+        const call = step.kind === 'add'
+            ? () => actions.addToCart({ productId: step.productId, variantId: step.variantId, quantity: 1, source: 'gift' })
+            : step.line.quantity > 1
+                ? () => actions.updateQuantity({ lineId: step.line.id, productId: step.line.productId, variantId: step.line.variantId, quantity: step.line.quantity - 1 })
+                : () => actions.removeItem({ lineId: step.line.id });
+        void run(null, call)
+            .then((err) => {
+            if (err)
+                giftFailed.current.add(step.tierId);
+        })
+            .finally(() => {
+            giftInFlight.current = false;
+        });
+    }, [enabled, config, base, ctx, actions, run]);
+    // Thresholds reached (analytics), once per tier and session.
+    useEffect(() => {
+        if (!enabled || !base || !config.modules.includes('progress'))
+            return;
+        for (const s of progressFor(base, config.thresholds, ctx).tiers)
+            if (s.reached)
+                trackOnce(`thr:${s.tier.id}`, { type: 'threshold', tierId: s.tier.id });
+    }, [enabled, config, base, ctx]);
+    // ---- Recommendations, gift / add-on products and bulk pricing: loaded on first open ------------
+    const signature = cartSignature(base).join(',');
+    const total = Math.floor(base?.subtotal ?? 0);
+    const lastKey = useRef(null);
+    const load = useMemo(() => loadData ?? (endpoint ? fetchEndpoint(endpoint) : null), [loadData, endpoint]);
+    useEffect(() => {
+        if (!everOpened || !load || !enabled)
+            return;
+        const c = config;
+        const recs = c.modules.includes('recommendations') || c.features.emptyFeatured;
+        const extras = [
+            ...(c.modules.includes('addons') ? c.addons.map((a) => a.productId) : []),
+            ...(c.modules.includes('gift') || c.modules.includes('progress') ? tiers.filter((t) => t.giftProductId).map((t) => t.giftProductId) : []),
+        ];
+        const bulk = c.modules.includes('quantityBreaks') && signature !== '';
+        if (!recs && !extras.length && !bulk)
+            return;
+        const params = new URLSearchParams();
+        if (signature)
+            params.set('cart', signature);
+        if (!recs)
+            params.set('recs', '0');
+        if (extras.length)
+            params.set('extra', [...new Set(extras)].join(','));
+        if (bulk)
+            params.set('bulk', '1');
+        if (ctx.customerGroupId)
+            params.set('group', String(ctx.customerGroupId));
+        // Whole units only, so small quantity changes keep the same cache key.
+        if (recs && c.rail.cartTotalRules && total)
+            params.set('total', String(total));
+        const key = params.toString();
+        if (lastKey.current === key)
+            return;
+        const ctrl = new AbortController();
+        // The first load at once; later ones once the cart settles.
+        const t = setTimeout(() => {
+            lastKey.current = key;
+            setLoading(true);
+            load(params, ctrl.signal)
+                .then((d) => d && setData(d))
+                .catch(() => undefined)
+                .finally(() => !ctrl.signal.aborted && setLoading(false));
+        }, lastKey.current === null ? 0 : 400);
+        return () => {
+            clearTimeout(t);
+            ctrl.abort();
+        };
+    }, [everOpened, load, enabled, config, signature, total, tiers, ctx.customerGroupId]);
+    const value = useMemo(() => ({ config, cart, ctx, isOpen, everOpened, open, close, data, loading, error, setQuantity, remove, add, applyCoupon, removeCoupon, setNote, toggleAddon }), [config, cart, ctx, isOpen, everOpened, open, close, data, loading, error, setQuantity, remove, add, applyCoupon, removeCoupon, setNote, toggleAddon]);
+    return _jsx(DrawerContext.Provider, { value: value, children: children });
+}
+/** Gift product names for the progress messages, from the loaded extras. */
+export function giftNames(data) {
+    return Object.fromEntries(Object.values(data?.extras ?? {}).map((p) => [p.id, p.name]));
+}

package/dist/client/Rail.d.ts

@@ -0,0 +1,3 @@
+export default function Rail({ title }: {
+    title: string;
+}): import("react").JSX.Element | null;

package/dist/client/Rail.js

@@ -0,0 +1,25 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from 'react';
+import { RailView } from '../views/rail.js';
+import { track, trackOnce } from './events.js';
+import { useCartDrawerContext } from './Provider.js';
+// Recommendations rail (SPEC §3.2 module 3), loaded with the drawer's first open. Products already
+// in the cart are left out; the rest keep the service's order.
+export default function Rail({ title }) {
+    const d = useCartDrawerContext();
+    const inCart = new Set(d?.cart?.lines.map((l) => l.productId));
+    const items = (d?.data?.items ?? []).filter((p) => !inCart.has(p.id)).slice(0, d?.config?.rail.maxItems ?? 4);
+    const shown = d?.isOpen && !d.loading;
+    const ids = items.map((i) => i.id).join(',');
+    useEffect(() => {
+        if (!shown)
+            return;
+        for (const p of items)
+            trackOnce(`imp:${p.id}`, { type: 'impression', productId: p.id, ruleId: p.ruleId });
+    }, [shown, ids]);
+    if (!d?.config)
+        return null;
+    const byId = new Map(items.map((i) => [i.id, i]));
+    return (_jsx(RailView, { title: title, products: items, loading: d.loading && !d.data, showImage: d.config.layout.showImages, picker: d.config.rail.variantPicker, locale: d.ctx.locale, onAdd: (p, variantId) => d.add(p, variantId, 'upsell', byId.get(p.id)?.ruleId ?? null), onClick: (p) => track({ type: 'click', productId: p.id, ruleId: byId.get(p.id)?.ruleId ?? null }) }));
+}

package/dist/client/events.d.ts

@@ -0,0 +1,8 @@
+import type { CartEvent } from '../core/types.js';
+export declare function configureEvents(events: {
+    url: string;
+    token: string;
+} | null): void;
+export declare function track(event: CartEvent): void;
+/** Once per browser session (impressions, thresholds), so reopening the drawer does not inflate them. */
+export declare function trackOnce(key: string, event: CartEvent): void;

package/dist/client/events.js

@@ -0,0 +1,49 @@
+// Analytics (SPEC §3.4): events are batched and sent with navigator.sendBeacon to POST /v1/events
+// (a text/plain body, so no CORS preflight). Lost events are acceptable; a slow page is not.
+const queue = [];
+let target = null;
+let timer;
+let listening = false;
+function flush() {
+    clearTimeout(timer);
+    timer = undefined;
+    if (!target || !queue.length)
+        return;
+    const body = JSON.stringify({ token: target.token, events: queue.splice(0, 50) });
+    try {
+        if (!navigator.sendBeacon?.(target.url, body))
+            void fetch(target.url, { method: 'POST', body, keepalive: true, mode: 'no-cors' }).catch(() => undefined);
+    }
+    catch {
+        // analytics never break the drawer
+    }
+    if (queue.length)
+        flush();
+}
+export function configureEvents(events) {
+    target = events;
+    if (!target || listening || typeof document === 'undefined')
+        return;
+    listening = true;
+    document.addEventListener('visibilitychange', () => document.visibilityState === 'hidden' && flush());
+    window.addEventListener('pagehide', flush);
+}
+export function track(event) {
+    if (!target)
+        return;
+    queue.push(event);
+    timer ??= setTimeout(flush, 4000);
+}
+/** Once per browser session (impressions, thresholds), so reopening the drawer does not inflate them. */
+export function trackOnce(key, event) {
+    try {
+        const seen = sessionStorage.getItem('cl_seen')?.split('|') ?? [];
+        if (seen.includes(key))
+            return;
+        sessionStorage.setItem('cl_seen', [...seen.slice(-200), key].join('|'));
+    }
+    catch {
+        // no storage: count it
+    }
+    track(event);
+}

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+export { CartDrawerClientProvider, useCartDrawer, useCartDrawerContext, openCartDrawer, type CartDrawerClientProviderProps, type DrawerContextValue, type DrawerDataLoader } from './Provider.js';
+export { CartDrawer, type CartDrawerProps } from './CartDrawer.js';
+export { CartTrigger, type CartTriggerProps } from './CartTrigger.js';

package/dist/client/index.js

@@ -0,0 +1,5 @@
+'use client';
+// Client-only entry: safe to import from your own 'use client' components.
+export { CartDrawerClientProvider, useCartDrawer, useCartDrawerContext, openCartDrawer } from './Provider.js';
+export { CartDrawer } from './CartDrawer.js';
+export { CartTrigger } from './CartTrigger.js';

package/dist/core/actions.d.ts

@@ -0,0 +1,62 @@
+import type { BulkTier, CartliftCart, RailProduct, RecommendationReason } from './types.js';
+export type AddSource = 'upsell' | 'gift' | 'addon' | 'nudge';
+export interface AddItemInput {
+    productId: number;
+    variantId: number | null;
+    quantity: number;
+    /** Multiple-choice selections, for products without a variant id (option id → value id). */
+    selectedOptions?: {
+        optionId: number;
+        valueId: number;
+    }[];
+    /** Why the drawer adds it (analytics attribution). */
+    source: AddSource;
+    ruleId?: string | null;
+}
+export interface UpdateQuantityInput {
+    lineId: string;
+    productId: number;
+    variantId: number | null;
+    quantity: number;
+}
+export interface CartActionResult {
+    cart: CartliftCart | null;
+    /** A message for the shopper ("Only 2 left"), shown in the drawer. */
+    error?: string | null;
+}
+export interface CartActions {
+    addToCart: (input: AddItemInput) => Promise<CartActionResult>;
+    updateQuantity: (input: UpdateQuantityInput) => Promise<CartActionResult>;
+    removeItem: (input: {
+        lineId: string;
+    }) => Promise<CartActionResult>;
+    applyCoupon?: (input: {
+        code: string;
+    }) => Promise<CartActionResult>;
+    removeCoupon?: (input: {
+        code: string;
+    }) => Promise<CartActionResult>;
+    /** Saves the order note (the checkout's customer message). */
+    setNote?: (input: {
+        note: string;
+    }) => Promise<CartActionResult>;
+}
+/** A recommended product, with why it is shown. */
+export type RailItem = RailProduct & {
+    reason: RecommendationReason;
+    ruleId: string | null;
+};
+/** What the storefront's recommendations route answers (createRecommendationsRoute). */
+export interface DrawerData {
+    items: RailItem[];
+    /** Gift and add-on products, by id. */
+    extras: Record<number, RailProduct>;
+    /** Bulk pricing of the cart's products, by id. */
+    bulk: Record<number, BulkTier[]>;
+}
+/** The custom DOM events the drawer listens to and dispatches (SPEC §2.1). */
+export declare const ADDED_EVENT = "cartlift:added";
+export declare const OPEN_EVENT = "cartlift:open";
+/** Set by wrapAddToCart() after a successful add; read (and cleared) by the drawer. */
+export declare const ADDED_COOKIE = "cl_added";
+export declare const DEFAULT_ENDPOINT = "/api/cartlift/recommendations";

package/dist/core/actions.js

@@ -0,0 +1,6 @@
+/** The custom DOM events the drawer listens to and dispatches (SPEC §2.1). */
+export const ADDED_EVENT = 'cartlift:added';
+export const OPEN_EVENT = 'cartlift:open';
+/** Set by wrapAddToCart() after a successful add; read (and cleared) by the drawer. */
+export const ADDED_COOKIE = 'cl_added';
+export const DEFAULT_ENDPOINT = '/api/cartlift/recommendations';

package/dist/core/breaks.d.ts

@@ -0,0 +1,13 @@
+import type { BulkTier, CartLine } from './types.js';
+export interface QuantityBreak {
+    /** Units to add to reach the next tier. */
+    more: number;
+    tier: BulkTier;
+    /** What the shopper saves on the whole line at the new quantity. */
+    saving: number;
+    message: string;
+}
+/** Unit price at a bulk tier. */
+export declare function tierUnitPrice(tier: BulkTier, unitPrice: number): number;
+/** The next bulk tier above the line's quantity, within `maxMore` units (null when there is none). */
+export declare function quantityBreakFor(line: CartLine, tiers: BulkTier[], template: string, currency: string, locale?: string, maxMore?: number): QuantityBreak | null;