@tiledev/sdk-shopify 0.9.1 → 0.10.1

package/dist/react/ShopifyProvider.js

@@ -4,18 +4,24 @@ exports.ShopifyProvider = ShopifyProvider;
 exports.useShopify = useShopify;
 exports.useCart = useCart;
 exports.useWishlist = useWishlist;
+exports.useWaitlist = useWaitlist;
 exports.useCustomer = useCustomer;
 exports.useCheckout = useCheckout;
+exports.useShopifyEvents = useShopifyEvents;
 exports.useShopifyMessage = useShopifyMessage;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const shopify_1 = require("../shopify");
 const client_1 = require("../client");
 const cart_1 = require("../cart");
+const checkout_1 = require("../checkout");
 const attributionRecorder_1 = require("./attributionRecorder");
 const cartPolicy_1 = require("../cartPolicy");
+const productPage_1 = require("../productPage");
 const errors_1 = require("../errors");
 const messages_1 = require("../messages");
+const types_1 = require("../types");
+const session_1 = require("../auth/session");
 /**
  * Shopify rejecting the *contents* of a mutation rather than failing to answer it: only
  * `userErrors` populate `ShopifyError.errors`, so transport and GraphQL failures arrive empty.
@@ -40,7 +46,6 @@ function lineFor(cart, input) {
 }
 const ShopifyContext = (0, react_1.createContext)(undefined);
 const CART_STORAGE_KEY = "shopify:cart-id:v1";
-const CUSTOMER_TOKEN_KEY = "shopify:customer-token:v1";
 const CART_LINES_KEY = "shopify:cart-lines:v1";
 const CHECKOUT_STARTED_KEY = "shopify:checkout-started-cart-id:v1";
 // Best-effort: the cart write that triggered it has already landed.
@@ -130,14 +135,34 @@ async function createFromSnapshot(lines, attributes) {
     }
     return next;
 }
+/**
+ * What an add changed: each line the inputs landed on, once, with the units added to it (two
+ * inputs that landed on one line, same variant and attributes, are counted together).
+ */
+function changesForAdds(cart, inputs) {
+    const changes = [];
+    for (const input of inputs) {
+        const line = lineFor(cart, input);
+        if (!line)
+            continue;
+        const sameLine = changes.find((change) => change.line.id === line.id);
+        if (sameLine)
+            sameLine.quantityChange += input.quantity;
+        else
+            changes.push({ line, quantityChange: input.quantity });
+    }
+    return changes;
+}
 /** Alert-carrying events and the message key each resolves. */
 const EVENT_MESSAGE = {
     "cart:add": "cart.added",
     "cart:remove": "cart.removed",
     "cart:limitExceeded": "cart.limitExceeded",
+    "cart:stockLimit": "cart.noMoreStock",
     "cart:outOfStock": "cart.outOfStock",
     "wishlist:add": "wishlist.added",
     "wishlist:remove": "wishlist.removed",
+    "waitlist:add": "waitlist.added",
     "auth:loginSuccess": "auth.loginSuccess",
     "auth:loginFailed": "auth.loginFailed",
     "auth:logout": "auth.loggedOut",
@@ -147,6 +172,7 @@ const EVENT_MESSAGE = {
 };
 const ERROR_EVENTS = new Set([
     "cart:limitExceeded",
+    "cart:stockLimit",
     "cart:outOfStock",
     "auth:loginFailed",
     "checkout:paymentFailed",
@@ -157,17 +183,19 @@ function defaultStorage() {
     }
     return null;
 }
-function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishlistKeepDeleted, messages, translate, cartPolicy, cartAttributes, attribution, }) {
+function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishlistKeepDeleted, wishlistStorageKey, wishlistMigrateFrom, waitlistStorageKey, waitlistMigrateFrom, messages, translate, cartPolicy, cartAttributes, auth, storeCredit, attribution, }) {
+    var _a, _b;
     const [ready, setReady] = (0, react_1.useState)(false);
     const [error, setError] = (0, react_1.useState)(null);
     const [cart, setCart] = (0, react_1.useState)(null);
+    // The cart as of the newest write, for a write that waited in the queue behind others.
+    const latestCart = (0, react_1.useRef)(null);
+    latestCart.current = cart;
     const [cartLoading, setCartLoad] = (0, react_1.useState)(false);
     const [wlItems, setWlItems] = (0, react_1.useState)([]);
-    const [customer, setCustomer] = (0, react_1.useState)(null);
-    const [token, setToken] = (0, react_1.useState)(null);
-    const [authLoading, setAuthLoad] = (0, react_1.useState)(false);
-    const [restoring, setRestoring] = (0, react_1.useState)(true);
     const wlUnsubRef = (0, react_1.useRef)(null);
+    const [wtItems, setWtItems] = (0, react_1.useState)([]);
+    const wtUnsubRef = (0, react_1.useRef)(null);
     const storageRef = (0, react_1.useRef)(null);
     storageRef.current = storage !== null && storage !== void 0 ? storage : defaultStorage();
     // In a ref so the cart callbacks keep their identity when the host passes a new guard object.
@@ -177,16 +205,23 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
     // every cart callback on each render.
     const onEventRef = (0, react_1.useRef)(onEvent);
     onEventRef.current = onEvent;
+    /** Listeners added with `useShopifyEvents`, told after `onEvent`, in the order they subscribed. */
+    const eventListeners = (0, react_1.useRef)(new Set());
+    /** Declared before `emit`, which reads the signed-in customer from it for `auth:loginSuccess`. */
+    const sessionRef = (0, react_1.useRef)(null);
     /**
-     * Resolves the copy for `type` and hands the event to the host. A throwing
-     * listener must not fail the write that triggered it — the mutation already
-     * landed, so swallowing here is the only honest option.
+     * Resolves the copy for `type` and hands the event to the host's `onEvent`, then to every
+     * `useShopifyEvents` listener. A throwing listener must not fail the write that triggered it —
+     * the mutation already landed, so swallowing here is the only honest option.
      */
-    const emit = (0, react_1.useCallback)((type, error) => {
+    const emit = (0, react_1.useCallback)((type, details) => {
+        var _a;
         const listener = onEventRef.current;
-        if (!listener)
+        if (!listener && eventListeners.current.size === 0)
             return;
         const key = EVENT_MESSAGE[type];
+        // The session has already taken the new customer when it announces the sign-in.
+        const signedIn = type === "auth:loginSuccess" ? (_a = sessionRef.current) === null || _a === void 0 ? void 0 : _a.getState() : undefined;
         const max = (0, cartPolicy_1.maxLineItems)();
         const event = {
             type,
@@ -199,15 +234,61 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
                         : (0, messages_1.message)(key),
                 }
                 : {}),
-            ...(error === undefined ? {} : { error }),
+            ...((details === null || details === void 0 ? void 0 : details.error) === undefined ? {} : { error: details.error }),
+            ...((details === null || details === void 0 ? void 0 : details.cart) ? { cart: details.cart } : {}),
+            ...((details === null || details === void 0 ? void 0 : details.changedLines) ? { changedLines: details.changedLines } : {}),
+            ...((details === null || details === void 0 ? void 0 : details.productId) ? { productId: details.productId } : {}),
+            ...(signedIn ? { customer: signedIn.customer, sessionKind: signedIn.kind } : {}),
         };
-        try {
-            listener(event);
+        if (listener) {
+            try {
+                listener(event);
+            }
+            catch (listenerError) {
+                console.warn("[ShopifyProvider] onEvent threw", listenerError);
+            }
         }
-        catch (listenerError) {
-            console.warn("[ShopifyProvider] onEvent threw", listenerError);
+        for (const eventListener of [...eventListeners.current]) {
+            try {
+                eventListener(event);
+            }
+            catch (listenerError) {
+                console.warn("[ShopifyProvider] a useShopifyEvents listener threw", listenerError);
+            }
         }
     }, []);
+    const subscribeToEvents = (0, react_1.useCallback)((eventListener) => {
+        eventListeners.current.add(eventListener);
+        return () => {
+            eventListeners.current.delete(eventListener);
+        };
+    }, []);
+    const events = (0, react_1.useMemo)(() => ({ subscribe: subscribeToEvents }), [subscribeToEvents]);
+    // ── Customer session ────────────────────────────────────────────────────────
+    // One per provider, created on first render. `auth` is read through a ref on every use, so a Live
+    // Layer publish that flips `auth.method` applies at once and leaves the current session alone.
+    const authRef = (0, react_1.useRef)(auth);
+    authRef.current = auth;
+    const configRef = (0, react_1.useRef)(config);
+    configRef.current = config;
+    if (!sessionRef.current) {
+        sessionRef.current = (0, session_1.createCustomerSession)({
+            storage: () => { var _a, _b; return (_b = (_a = authRef.current) === null || _a === void 0 ? void 0 : _a.secureStorage) !== null && _b !== void 0 ? _b : storageRef.current; },
+            legacyStorage: () => storageRef.current,
+            options: () => authRef.current,
+            apiVersion: () => configRef.current.apiVersion,
+            emit: (type, error) => emit(type, error === undefined ? undefined : { error }),
+        });
+    }
+    const session = sessionRef.current;
+    const [sessionState, setSessionState] = (0, react_1.useState)(session.getState);
+    (0, react_1.useEffect)(() => {
+        setSessionState(session.getState());
+        const unsubscribe = session.subscribe(() => setSessionState(session.getState()));
+        // Not gated on the shop loading: a stored session is restored offline too.
+        void session.restore();
+        return unsubscribe;
+    }, [session]);
     /**
      * Alert copy and cart rules, re-applied whenever the host passes new ones so a
      * Live Layer publish lands without a re-init. `config` values are the base;
@@ -305,16 +386,19 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
             return fallback;
         }
     }, []);
-    const approveAdd = (0, react_1.useCallback)(async (input) => {
+    const approveAdd = (0, react_1.useCallback)(async (input, options) => {
         const guard = guardRef.current;
         if (!(guard === null || guard === void 0 ? void 0 : guard.beforeAdd))
             return input;
-        const approved = await runGuard(() => guard.beforeAdd(input), input);
+        const approved = await runGuard(() => guard.beforeAdd(input, options), input);
         // A guard that rebuilds the input must not lose where it came from.
         return approved && !approved.source && input.source ? { ...approved, source: input.source } : approved;
     }, [runGuard]);
-    /** Hands back units the guard approved for a write that then failed. */
-    const releaseRejected = (0, react_1.useCallback)((input) => {
+    /**
+     * Hands back units the guard approved for a write that then didn't land. An add passes its approved
+     * input (the guard's receipt rides on its attributes); an increase passes the line it was to grow.
+     */
+    const releaseRejected = (0, react_1.useCallback)((input, line = null) => {
         const guard = guardRef.current;
         if (!(guard === null || guard === void 0 ? void 0 : guard.onReleased))
             return;
@@ -322,7 +406,8 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
             variantId: input.merchandiseId,
             quantity: input.quantity,
             reason: "rejected",
-            line: null,
+            line,
+            ...(line ? {} : { input }),
             cart: null,
         }), undefined);
     }, [runGuard]);
@@ -340,10 +425,46 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
     (0, react_1.useEffect)(() => {
         let mounted = true;
         (async () => {
-            var _a;
+            var _a, _b;
             try {
                 await shopify_1.shopify.init(config);
                 reapplyAlertConfig();
+                // The wishlist first, on its own: it is on the device, so it loads with no network, and a
+                // cart that can't load (offline) must not take it down with it.
+                try {
+                    const initialItems = await shopify_1.shopify.wishlist.init({
+                        storage: (_a = storageRef.current) !== null && _a !== void 0 ? _a : undefined,
+                        storageKey: wishlistStorageKey,
+                        migrateFrom: wishlistMigrateFrom,
+                        keepDeleted: wishlistKeepDeleted,
+                    });
+                    if (mounted)
+                        setWlItems(initialItems);
+                    wlUnsubRef.current = shopify_1.shopify.wishlist.onChange((items) => {
+                        if (mounted)
+                            setWlItems(items);
+                    });
+                }
+                catch (e) {
+                    console.error("[ShopifyProvider] wishlist init failed", e);
+                }
+                // The waitlist the same way, for the same reason.
+                try {
+                    const initialWaitlist = await shopify_1.shopify.waitlist.init({
+                        storage: (_b = storageRef.current) !== null && _b !== void 0 ? _b : undefined,
+                        storageKey: waitlistStorageKey,
+                        migrateFrom: waitlistMigrateFrom,
+                    });
+                    if (mounted)
+                        setWtItems(initialWaitlist);
+                    wtUnsubRef.current = shopify_1.shopify.waitlist.onChange((items) => {
+                        if (mounted)
+                            setWtItems(items);
+                    });
+                }
+                catch (e) {
+                    console.error("[ShopifyProvider] waitlist init failed", e);
+                }
                 setCartLoad(true);
                 try {
                     const s = storageRef.current;
@@ -373,40 +494,6 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
                     if (mounted)
                         setCartLoad(false);
                 }
-                const initialItems = await shopify_1.shopify.wishlist.init({
-                    storage: (_a = storageRef.current) !== null && _a !== void 0 ? _a : undefined,
-                    keepDeleted: wishlistKeepDeleted,
-                });
-                if (mounted)
-                    setWlItems(initialItems);
-                wlUnsubRef.current = shopify_1.shopify.wishlist.onChange((items) => {
-                    if (mounted)
-                        setWlItems(items);
-                });
-                // Restore a stored session. A token that no longer resolves is dropped
-                // silently — an expired login is not a failed one, and firing
-                // `auth:loginFailed` on app open would toast at a shopper who did nothing.
-                try {
-                    const s = storageRef.current;
-                    const savedToken = s ? await Promise.resolve(s.getItem(CUSTOMER_TOKEN_KEY)) : null;
-                    if (savedToken) {
-                        const profile = await shopify_1.shopify.customer.profile(savedToken);
-                        if (mounted && profile) {
-                            setCustomer(profile);
-                            setToken(savedToken);
-                        }
-                        else if (s && !profile) {
-                            await Promise.resolve(s.removeItem(CUSTOMER_TOKEN_KEY));
-                        }
-                    }
-                }
-                catch (sessionError) {
-                    console.warn("[ShopifyProvider] session restore failed", sessionError);
-                }
-                finally {
-                    if (mounted)
-                        setRestoring(false);
-                }
                 if (mounted)
                     setReady(true);
             }
@@ -414,16 +501,16 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
                 console.error("[ShopifyProvider] init failed", e);
                 if (mounted) {
                     setError(e instanceof Error ? e.message : String(e));
-                    setRestoring(false);
                     // Ready so downstream UIs render an error state rather than an indefinite spinner.
                     setReady(true);
                 }
             }
         })();
         return () => {
-            var _a;
+            var _a, _b;
             mounted = false;
             (_a = wlUnsubRef.current) === null || _a === void 0 ? void 0 : _a.call(wlUnsubRef);
+            (_b = wtUnsubRef.current) === null || _b === void 0 ? void 0 : _b.call(wtUnsubRef);
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
@@ -494,6 +581,7 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
         }
     }, [config.country]);
     const persistCart = (0, react_1.useCallback)(async (next) => {
+        latestCart.current = next;
         setCart(next);
         cartRef.current = next;
         const synced = recorder.sync(next);
@@ -523,18 +611,28 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
      */
     const reportCartFailure = (0, react_1.useCallback)((failure) => {
         if ((0, errors_1.isOutOfStockError)(failure)) {
-            emit("cart:outOfStock", failure);
+            emit("cart:outOfStock", { error: failure });
             return true;
         }
         return false;
     }, [emit]);
     const cartAddLine = (0, react_1.useCallback)(async (input) => {
+        // The variant's stock, when the caller knows it: Shopify would accept the
+        // add and clamp it silently, so the shopper would be told it worked. Before
+        // the guard, so a guard that reserves stock (Cart Hold) never reserves for an
+        // add that is then refused.
+        if (input.maxQuantity != null && !(0, productPage_1.withinCeiling)(input.maxQuantity, (0, productPage_1.quantityInCart)(cart, input.merchandiseId), input.quantity)) {
+            emit("cart:stockLimit");
+            return { ok: false, reason: "stock", message: (0, messages_1.message)("cart.noMoreStock"), cart };
+        }
         const approved = await approveAdd(input);
         if (!approved)
             return { ok: false, reason: "guard", cart };
         // Checked before the write so a refusal costs no round trip, and so the
         // shopper reads the configured message rather than a Shopify error.
         if ((0, cartPolicy_1.wouldExceedLineLimit)(cart, [approved])) {
+            // The guard may have reserved stock for this add; it won't land, so that goes back.
+            releaseRejected(approved);
             emit("cart:limitExceeded");
             const max = (0, cartPolicy_1.maxLineItems)();
             return {
@@ -546,9 +644,10 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
         }
         setCartLoad(true);
         try {
-            const id = await ensureCartId();
             let next;
             try {
+                // Inside the catch: a cart that can't be created is an add that didn't land.
+                const id = await ensureCartId();
                 next = await serialize(() => shopify_1.shopify.cart.addLines(id, [approved]));
             }
             catch (addError) {
@@ -559,7 +658,7 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
             await persistCart(next);
             await clearCheckoutStarted(storageRef.current);
             recorder.addInput(next.id, approved);
-            emit("cart:add");
+            emit("cart:add", { cart: next, changedLines: changesForAdds(next, [approved]) });
             announceLanded(approved, next);
             return { ok: true, cart: next };
         }
@@ -567,22 +666,31 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
             setCartLoad(false);
         }
     }, [cart, approveAdd, releaseRejected, announceLanded, ensureCartId, persistCart, emit, reportCartFailure, serialize, recorder]);
-    const cartAddLines = (0, react_1.useCallback)(async (requested) => {
+    const cartAddLines = (0, react_1.useCallback)(async (requested, options) => {
         if (requested.length === 0)
             return cart;
         // Vetted up front so a guard's veto does not cost the other lines their fast path.
-        const inputs = (await Promise.all(requested.map(approveAdd))).filter((input) => input !== null);
+        const inputs = (await Promise.all(requested.map((input) => approveAdd(input, options)))).filter((input) => input !== null);
         if (inputs.length === 0)
             return null;
         // The whole batch is judged against the limit, not line by line — landing
         // half a "add these 5" is worse than refusing it with the message.
         if ((0, cartPolicy_1.wouldExceedLineLimit)(cart, inputs)) {
+            inputs.forEach((input) => releaseRejected(input));
             emit("cart:limitExceeded");
             return null;
         }
         setCartLoad(true);
         try {
-            const id = await ensureCartId();
+            let id;
+            try {
+                id = await ensureCartId();
+            }
+            catch (createError) {
+                inputs.forEach((input) => releaseRejected(input));
+                reportCartFailure(createError);
+                throw createError;
+            }
             let next = null;
             // Which inputs landed, so the guard hears about exactly those.
             let landed = [];
@@ -594,7 +702,7 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
                 // A transport or GraphQL failure would fail all N the same way, so retrying it would turn
                 // one dead request into N and still end at null. Only line rejections are worth retrying.
                 if (!isLineRejection(batchError)) {
-                    inputs.forEach(releaseRejected);
+                    inputs.forEach((input) => releaseRejected(input));
                     reportCartFailure(batchError);
                     throw batchError;
                 }
@@ -613,16 +721,16 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
                             anyOutOfStock = true;
                         // Anything but a rejection means the retry itself is failing, so stop.
                         if (!isLineRejection(lineError)) {
-                            inputs.slice(i + 1).forEach(releaseRejected);
+                            inputs.slice(i + 1).forEach((rest) => releaseRejected(rest));
                             reportCartFailure(lineError);
                             throw lineError;
                         }
                     }
                 }
                 // One alert for the batch: N unsellable lines is one thing that went
-                // wrong from the shopper's side, not N toasts.
-                if (anyOutOfStock)
-                    emit("cart:outOfStock", batchError);
+                // wrong from the shopper's side, not N toasts. None when quiet: the caller reports it.
+                if (anyOutOfStock && !(options === null || options === void 0 ? void 0 : options.quiet))
+                    emit("cart:outOfStock", { error: batchError });
                 // Every line individually rejected. Surface the original rather than an empty success,
                 // which reads as "nothing to add" instead of "none of this is sellable".
                 if (landed.length === 0)
@@ -633,8 +741,8 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
                 await clearCheckoutStarted(storageRef.current);
                 const cartId = next.id;
                 landed.forEach((input) => recorder.addInput(cartId, input));
-                emit("cart:add");
                 const settled = next;
+                emit("cart:add", { cart: settled, changedLines: changesForAdds(settled, landed) });
                 landed.forEach((input) => announceLanded(input, settled));
             }
             return next;
@@ -659,20 +767,28 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
         }
     }, [cart, persistCart, emit, serialize]);
     const cartUpdateLine = (0, react_1.useCallback)(async (lineId, quantity, attributes, opts) => {
-        var _a;
+        var _a, _b;
         if (!(cart === null || cart === void 0 ? void 0 : cart.id))
             return false;
         const guard = guardRef.current;
         const previous = (_a = cart.lines.find((line) => line.id === lineId)) !== null && _a !== void 0 ? _a : null;
         const delta = previous ? quantity - previous.quantity : 0;
+        // Attributes REPLACE the line's set, so the caller's new set keeps the line's private
+        // (`_`-prefixed) attributes it didn't mention: those belong to the app's integrations (Cart
+        // Hold's expiry stamp is one), not to whoever is editing the visible ones.
+        const kept = attributes && previous
+            ? previous.attributes.filter((old) => old.key.startsWith("_") && !attributes.some((next) => next.key === old.key))
+            : [];
+        const nextAttributes = attributes ? [...attributes, ...kept] : undefined;
         // Only an increase can be vetted; a decrease is reported after the fact, once Shopify has
         // actually taken the units back.
-        let update = { id: lineId, quantity, ...(attributes ? { attributes } : {}) };
+        let update = { id: lineId, quantity, ...(nextAttributes ? { attributes: nextAttributes } : {}) };
         if (previous && delta > 0 && (guard === null || guard === void 0 ? void 0 : guard.beforeIncrease)) {
             const approved = await runGuard(() => guard.beforeIncrease(previous, quantity), update);
             if (!approved)
                 return false;
-            update = approved;
+            // The guard's answer wins, but attributes it didn't return are the caller's, not dropped.
+            update = { ...approved, ...(approved.attributes === undefined && nextAttributes ? { attributes: nextAttributes } : {}) };
         }
         setCartLoad(true);
         try {
@@ -682,7 +798,7 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
             }
             catch (updateError) {
                 if (previous && delta > 0) {
-                    releaseRejected({ merchandiseId: previous.merchandise.id, quantity: delta });
+                    releaseRejected({ merchandiseId: previous.merchandise.id, quantity: delta }, previous);
                 }
                 reportCartFailure(updateError);
                 throw updateError;
@@ -692,7 +808,12 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
             recorder.changeLine(next.id, previous, previous ? update.quantity - previous.quantity : 0, opts === null || opts === void 0 ? void 0 : opts.source);
             // A quantity change is not one of the panel's alerts — emitted as a state
             // signal so a host can refresh a badge, with no copy attached.
-            emit("cart:update");
+            // The line as it is now; gone at 0, so the line as it was.
+            const lineNow = (_b = next.lines.find((line) => line.id === lineId)) !== null && _b !== void 0 ? _b : previous;
+            emit("cart:update", {
+                cart: next,
+                changedLines: previous && lineNow ? [{ line: lineNow, quantityChange: update.quantity - previous.quantity }] : [],
+            });
             if (previous && delta < 0 && (guard === null || guard === void 0 ? void 0 : guard.onReleased)) {
                 void runGuard(() => guard.onReleased({
                     variantId: previous.merchandise.id,
@@ -722,7 +843,10 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
             recorder.changeLine(next.id, previous, -((_b = previous === null || previous === void 0 ? void 0 : previous.quantity) !== null && _b !== void 0 ? _b : 0));
             // The panel's "Removed From Cart" alert. Previously nothing fired here, so
             // the configured copy had no trigger at all.
-            emit("cart:remove");
+            emit("cart:remove", {
+                cart: next,
+                changedLines: previous ? [{ line: previous, quantityChange: -previous.quantity }] : [],
+            });
             if (previous && (guard === null || guard === void 0 ? void 0 : guard.onReleased)) {
                 void runGuard(() => guard.onReleased({
                     variantId: previous.merchandise.id,
@@ -763,6 +887,47 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
             setCartLoad(false);
         }
     }, [cart, persistCart, serialize]);
+    const cartAddGiftCardCodes = (0, react_1.useCallback)(async (codes) => {
+        if (!(cart === null || cart === void 0 ? void 0 : cart.id) || codes.length === 0)
+            return cart !== null && cart !== void 0 ? cart : null;
+        setCartLoad(true);
+        try {
+            const { cart: next, notApplied } = await serialize(async () => {
+                var _a;
+                const current = (_a = latestCart.current) !== null && _a !== void 0 ? _a : cart;
+                const signedIn = session.getState().kind !== null;
+                return (0, cart_1.addGiftCardsKeepingBuyer)(current, codes, {
+                    countryCode: async () => config.country || (await shopify_1.shopify.shop.countryCode()) || "US",
+                    // Signed in: the identity write keeps the cart linked to the shopper (it replaces the identity).
+                    customerAccessToken: signedIn ? await session.getAccessToken().catch(() => null) : null,
+                });
+            });
+            await persistCart(next);
+            if (notApplied.length) {
+                const message = `Shopify didn't apply the gift card ending in ${notApplied.map((code) => code.slice(-4)).join(", ")}`;
+                throw new types_1.ShopifyError(message, [{ field: ["giftCardCodes"], message, code: "GIFT_CARD_NOT_APPLIED" }]);
+            }
+            return next;
+        }
+        finally {
+            setCartLoad(false);
+        }
+    }, [cart, config.country, persistCart, serialize, session]);
+    const cartRemoveGiftCards = (0, react_1.useCallback)(async (appliedGiftCardIds) => {
+        if (!(cart === null || cart === void 0 ? void 0 : cart.id))
+            return null;
+        if (appliedGiftCardIds.length === 0)
+            return cart;
+        setCartLoad(true);
+        try {
+            const next = await serialize(() => shopify_1.shopify.cart.removeGiftCardCodes(cart.id, appliedGiftCardIds));
+            await persistCart(next);
+            return next;
+        }
+        finally {
+            setCartLoad(false);
+        }
+    }, [cart, persistCart, serialize]);
     const cartRefresh = (0, react_1.useCallback)(async () => {
         if (!(cart === null || cart === void 0 ? void 0 : cart.id))
             return null;
@@ -806,137 +971,39 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
     }, [persistCart]);
     // The wishlist module owns storage and hydration; these just wrap the mutating methods and
     // rely on onChange to keep React in sync.
-    const wlAdd = (0, react_1.useCallback)(async (p) => { await shopify_1.shopify.wishlist.add(p); emit("wishlist:add"); }, [emit]);
+    const wlAdd = (0, react_1.useCallback)(async (p) => {
+        await shopify_1.shopify.wishlist.add(p);
+        emit("wishlist:add", { productId: typeof p === "string" ? p : p.id });
+    }, [emit]);
     // `remove` emits too. It used not to, so "Removed From Wishlist" only ever
     // fired via `toggle` — a dedicated remove button showed nothing.
     const wlRemove = (0, react_1.useCallback)(async (id) => {
         const removed = await shopify_1.shopify.wishlist.remove(id);
         if (removed)
-            emit("wishlist:remove");
+            emit("wishlist:remove", { productId: id });
     }, [emit]);
     const wlToggle = (0, react_1.useCallback)(async (p) => {
         const nowSaved = await shopify_1.shopify.wishlist.toggle(p);
-        emit(nowSaved ? "wishlist:add" : "wishlist:remove");
+        emit(nowSaved ? "wishlist:add" : "wishlist:remove", { productId: typeof p === "string" ? p : p.id });
         return nowSaved;
     }, [emit]);
     const wlClear = (0, react_1.useCallback)(async () => { await shopify_1.shopify.wishlist.clear(); }, []);
     const wlRefresh = (0, react_1.useCallback)(async () => { await shopify_1.shopify.wishlist.refresh({ keepDeleted: wishlistKeepDeleted }); }, [wishlistKeepDeleted]);
     const wlHas = (0, react_1.useCallback)((id) => shopify_1.shopify.wishlist.has(id), []);
     const wlIds = (0, react_1.useMemo)(() => wlItems.map((item) => item.productId), [wlItems]);
-    // ── Customer session ────────────────────────────────────────────────────────
-    // Wraps `shopify.customer` with token persistence and the four Login alerts.
-    // Bad credentials resolve `false` rather than throwing: it is an expected
-    // answer to a login form, and every caller would otherwise need a try/catch to
-    // tell it apart from the store being unreachable (which still throws).
-    const persistToken = (0, react_1.useCallback)(async (next) => {
-        setToken(next);
-        const s = storageRef.current;
-        if (!s)
-            return;
-        if (next)
-            await Promise.resolve(s.setItem(CUSTOMER_TOKEN_KEY, next));
-        else
-            await Promise.resolve(s.removeItem(CUSTOMER_TOKEN_KEY));
-    }, []);
-    const authLogin = (0, react_1.useCallback)(async (email, password) => {
-        setAuthLoad(true);
-        try {
-            let accessToken;
-            try {
-                const minted = await shopify_1.shopify.customer.login({ email, password });
-                accessToken = minted.accessToken;
-            }
-            catch (loginError) {
-                // Only a credential problem is a "Login Failed" toast; a network failure
-                // is not the shopper's mistake, so it propagates instead.
-                if ((0, errors_1.classifyAuthFailure)(loginError) === "unknown")
-                    throw loginError;
-                emit("auth:loginFailed", loginError);
-                return false;
-            }
-            const profile = await shopify_1.shopify.customer.profile(accessToken);
-            await persistToken(accessToken);
-            setCustomer(profile);
-            emit("auth:loginSuccess");
-            return true;
-        }
-        finally {
-            setAuthLoad(false);
-        }
-    }, [emit, persistToken]);
-    const authSignup = (0, react_1.useCallback)(async (input) => {
-        setAuthLoad(true);
-        try {
-            let created;
-            try {
-                created = await shopify_1.shopify.customer.signup(input);
-            }
-            catch (signupError) {
-                if ((0, errors_1.classifyAuthFailure)(signupError) === "unknown")
-                    throw signupError;
-                emit("auth:loginFailed", signupError);
-                return false;
-            }
-            await persistToken(created.accessToken.accessToken);
-            setCustomer(created.customer);
-            // Signup mints a token, so the shopper IS logged in — both events fire, and
-            // a host that only toasts on `auth:loginSuccess` still says the right thing.
-            emit("auth:signup");
-            emit("auth:loginSuccess");
-            return true;
-        }
-        finally {
-            setAuthLoad(false);
-        }
-    }, [emit, persistToken]);
-    const authLogout = (0, react_1.useCallback)(async () => {
-        const current = token;
-        setAuthLoad(true);
-        try {
-            if (current) {
-                try {
-                    await shopify_1.shopify.customer.logout(current);
-                }
-                catch (logoutError) {
-                    // The local session ends regardless — leaving a shopper "logged in"
-                    // because Shopify was unreachable is the worse failure.
-                    console.warn("[ShopifyProvider] token delete failed; clearing locally", logoutError);
-                }
-            }
-            await persistToken(null);
-            setCustomer(null);
-            emit("auth:logout");
-        }
-        finally {
-            setAuthLoad(false);
-        }
-    }, [token, emit, persistToken]);
-    const authRecover = (0, react_1.useCallback)(async (email) => {
-        setAuthLoad(true);
-        try {
-            await shopify_1.shopify.customer.recoverPassword(email);
-            emit("auth:recoverSent");
-        }
-        finally {
-            setAuthLoad(false);
-        }
+    // The waitlist module owns storage and fetching, as the wishlist's does.
+    const wtAdd = (0, react_1.useCallback)(async (entry) => { await shopify_1.shopify.waitlist.add(entry); emit("waitlist:add"); }, [emit]);
+    const wtRemove = (0, react_1.useCallback)(async (variantId) => {
+        if (await shopify_1.shopify.waitlist.remove(variantId))
+            emit("waitlist:remove");
     }, [emit]);
-    const authRefresh = (0, react_1.useCallback)(async () => {
-        if (!token)
-            return null;
-        const profile = await shopify_1.shopify.customer.profile(token);
-        if (!profile) {
-            // Token expired or revoked. Clear it silently — see the mount restore.
-            await persistToken(null);
-            setCustomer(null);
-            return null;
-        }
-        setCustomer(profile);
-        return profile;
-    }, [token, persistToken]);
+    const wtRefresh = (0, react_1.useCallback)(async () => { await shopify_1.shopify.waitlist.refresh(); }, []);
+    const wtHas = (0, react_1.useCallback)((variantId) => shopify_1.shopify.waitlist.has(variantId), []);
+    const wtIds = (0, react_1.useMemo)(() => wtItems.map((item) => item.variantId), [wtItems]);
     // ── Checkout outcome ────────────────────────────────────────────────────────
     const checkoutOrderPlaced = (0, react_1.useCallback)(async (details) => {
-        emit("checkout:orderPlaced", details);
+        // The order's details travel in `error`, where hosts have always read them.
+        emit("checkout:orderPlaced", { error: details });
         // The old cart is spent once an order exists; keeping it would show the
         // shopper their purchased items still sitting in the bag.
         try {
@@ -961,13 +1028,35 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
         }
     }, []);
     const checkoutPaymentFailed = (0, react_1.useCallback)((paymentError) => {
-        emit("checkout:paymentFailed", paymentError);
+        emit("checkout:paymentFailed", { error: paymentError });
     }, [emit]);
+    // Every step handed in from here, so `prepareCheckout` is tested without React (test/checkout-prepare).
+    const checkoutPrepare = (0, react_1.useCallback)((options) => {
+        var _a, _b;
+        return (0, checkout_1.prepareCheckout)({
+            readCartAgain: cartRefresh,
+            // A read that fails carries on with the cart in hand ("Carry on", 2026-10-06).
+            cartAlreadyLoaded: () => latestCart.current,
+            signedIn: sessionState.kind !== null,
+            email: (_b = (_a = sessionState.customer) === null || _a === void 0 ? void 0 : _a.email) !== null && _b !== void 0 ? _b : null,
+            getAccessToken: session.getAccessToken,
+            setBuyerIdentity: cartSetBuyerIdentity,
+            reportCheckoutStarted: checkoutStarted,
+            // The cart's attribution lands first, then the provider's own cartAttributes (Freckled Poppy's
+            // labelCartForCheckout). Each queued behind pending cart writes.
+            flushAttribution: cartFlushAttribution,
+            ensureCartAttributes: () => { var _a; return (((_a = cartAttrsRef.current) === null || _a === void 0 ? void 0 : _a.length) ? cartEnsureAttributes(cartAttrsRef.current) : Promise.resolve(true)); },
+        }, options);
+    }, [cartRefresh, cartSetBuyerIdentity, cartFlushAttribution, cartEnsureAttributes, checkoutStarted, sessionState.kind, (_a = sessionState.customer) === null || _a === void 0 ? void 0 : _a.email, session]);
+    const authMethod = (_b = auth === null || auth === void 0 ? void 0 : auth.method) !== null && _b !== void 0 ? _b : "password";
+    // By its fields, so a host passing a fresh object each render doesn't rebuild the context.
+    const storeCreditOptions = (0, react_1.useMemo)(() => (storeCredit ? { source: storeCredit.source, tileCreditBaseUrl: storeCredit.tileCreditBaseUrl } : null), [storeCredit === null || storeCredit === void 0 ? void 0 : storeCredit.source, storeCredit === null || storeCredit === void 0 ? void 0 : storeCredit.tileCreditBaseUrl]);
     const value = (0, react_1.useMemo)(() => {
         var _a, _b;
         return ({
             ready, error,
             message: messages_1.message,
+            events,
             cart: {
                 cart, loading: cartLoading, itemCount: (_a = cart === null || cart === void 0 ? void 0 : cart.totalQuantity) !== null && _a !== void 0 ? _a : 0,
                 lineCount: (_b = cart === null || cart === void 0 ? void 0 : cart.lines.length) !== null && _b !== void 0 ? _b : 0,
@@ -979,6 +1068,8 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
                 applyDiscountCodes: cartApplyDiscounts,
                 updateNote: cartUpdateNote,
                 setBuyerIdentity: cartSetBuyerIdentity,
+                addGiftCardCodes: cartAddGiftCardCodes,
+                removeGiftCards: cartRemoveGiftCards,
                 refresh: cartRefresh,
                 adopt: cartAdopt,
                 reset: cartReset,
@@ -997,32 +1088,52 @@ function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishli
                 clear: wlClear,
                 refresh: wlRefresh,
             },
+            waitlist: {
+                items: wtItems,
+                ids: wtIds,
+                count: wtItems.length,
+                has: wtHas,
+                add: wtAdd,
+                remove: wtRemove,
+                refresh: wtRefresh,
+            },
             customer: {
-                customer,
-                loggedIn: !!customer,
-                accessToken: token,
-                loading: authLoading,
-                restoring,
-                login: authLogin,
-                signup: authSignup,
-                logout: authLogout,
-                recoverPassword: authRecover,
-                refresh: authRefresh,
+                customer: sessionState.customer,
+                loggedIn: sessionState.kind !== null,
+                accessToken: sessionState.accessToken,
+                loading: sessionState.loading,
+                restoring: sessionState.restoring,
+                method: authMethod,
+                sessionKind: sessionState.kind,
+                login: session.login,
+                signup: session.signup,
+                logout: session.logout,
+                recoverPassword: session.recoverPassword,
+                refresh: session.refresh,
+                updateProfile: session.updateProfile,
+                signIn: session.signIn,
+                startSignIn: session.startSignIn,
+                getAccessToken: session.getAccessToken,
+                renewAccessToken: session.renewAccessToken,
+                request: session.customerAccountRequest,
             },
             checkout: {
+                prepare: checkoutPrepare,
                 reportCheckoutStarted: checkoutStarted,
                 reportOrderPlaced: checkoutOrderPlaced,
                 reportPaymentFailed: checkoutPaymentFailed,
             },
+            storeCredit: storeCreditOptions,
         });
     }, [
-        ready, error,
+        ready, error, events,
         // A new policy changes `cart.maxLineItems`, so the memo must see it.
         resolvedPolicy,
-        cart, cartLoading, cartAddLine, cartAddLines, cartUpdateLine, cartRemoveLine, cartApplyDiscounts, cartUpdateNote, cartSetBuyerIdentity, cartRefresh, cartAdopt, cartReset, cartFlushAttribution, cartEnsureAttributes,
+        cart, cartLoading, cartAddLine, cartAddLines, cartUpdateLine, cartRemoveLine, cartApplyDiscounts, cartUpdateNote, cartSetBuyerIdentity, cartAddGiftCardCodes, cartRemoveGiftCards, cartRefresh, cartAdopt, cartReset, cartFlushAttribution, cartEnsureAttributes,
         wlItems, wlIds, wlHas, wlAdd, wlRemove, wlToggle, wlClear, wlRefresh,
-        customer, token, authLoading, restoring, authLogin, authSignup, authLogout, authRecover, authRefresh,
-        checkoutStarted, checkoutOrderPlaced, checkoutPaymentFailed,
+        wtItems, wtIds, wtHas, wtAdd, wtRemove, wtRefresh,
+        sessionState, session, authMethod, storeCreditOptions,
+        checkoutStarted, checkoutOrderPlaced, checkoutPaymentFailed, checkoutPrepare,
     ]);
     return (0, jsx_runtime_1.jsx)(ShopifyContext.Provider, { value: value, children: children });
 }
@@ -1038,13 +1149,47 @@ function useCart() {
 function useWishlist() {
     return useShopify().wishlist;
 }
+function useWaitlist() {
+    return useShopify().waitlist;
+}
 /** Customer session — the source of the four Login alerts. */
 function useCustomer() {
     return useShopify().customer;
 }
-/** Reports a hosted-checkout outcome so the two Checkout alerts can fire. */
+/**
+ * Gets the cart ready before checkout opens (`prepare`, with this caller's own `preparing`), and
+ * reports a hosted-checkout outcome so the two Checkout alerts can fire.
+ */
 function useCheckout() {
-    return useShopify().checkout;
+    const checkout = useShopify().checkout;
+    // Each caller's own, so only the button that started it shows a spinner.
+    const [preparing, setPreparing] = (0, react_1.useState)(false);
+    // Read when called, so `prepare` keeps one identity while the cart changes.
+    const latestPrepare = (0, react_1.useRef)(checkout.prepare);
+    latestPrepare.current = checkout.prepare;
+    const prepare = (0, react_1.useCallback)(async (options) => {
+        setPreparing(true);
+        try {
+            return await latestPrepare.current(options);
+        }
+        finally {
+            setPreparing(false);
+        }
+    }, []);
+    return (0, react_1.useMemo)(() => ({ ...checkout, prepare, preparing }), [checkout, prepare, preparing]);
+}
+/**
+ * Hears every event the provider raises, from anywhere inside it (0.10): the same events `onEvent`
+ * gets, told right after it, in the order they happen. Cart events carry the cart and the lines they
+ * changed, so a listener reports from the event rather than waiting for `useCart()` to catch up. The
+ * listener is read when an event fires, so a new function each render is fine. It starts hearing once
+ * the component has mounted and stops when it unmounts.
+ */
+function useShopifyEvents(listener) {
+    const { events } = useShopify();
+    const latestListener = (0, react_1.useRef)(listener);
+    latestListener.current = listener;
+    (0, react_1.useEffect)(() => events.subscribe((event) => latestListener.current(event)), [events]);
 }
 /**
  * Resolved alert copy, for UI that isn't a toast — the empty-wishlist