@replohq/sdk 0.1.0

package/cart/hooks/use-add-to-cart.d.ts

@@ -0,0 +1,63 @@
+import type { QueryClient } from "@tanstack/react-query";
+import type { CartLineAttribute, CartLineMerchandise } from "../cart-types";
+/**
+ * Describes a single item to add to the cart. Uses the merchandiseId
+ * (e.g. a variant GID) directly from data loader output. Product
+ * display data for optimistic UI is resolved automatically from the
+ * React Query cache for both single-product loaders (e.g. ProductLoader)
+ * and product-list loaders (e.g. CollectionProductsLoader,
+ * RebuyRecommendationsLoader). Pass `merchandise` explicitly to bypass
+ * the cache lookup when the variant is known but its product was not
+ * loaded via a supported loader.
+ */
+export interface AddToCartItem {
+    /** The cart-addressable merchandise ID (e.g. `product.variants[N].id` from loader output). */
+    merchandiseId: string;
+    quantity?: number;
+    sellingPlanId?: string | null;
+    /** Custom line item properties (appear on the order). */
+    properties?: CartLineAttribute[];
+    merchandise?: CartLineMerchandise;
+}
+export declare function findMerchandiseInQueryCache({ queryClient, merchandiseId, }: {
+    queryClient: QueryClient;
+    merchandiseId: string;
+}): CartLineMerchandise | undefined;
+/**
+ * Hook for adding items to cart using merchandise IDs from data loader output.
+ *
+ * This is the primary hook for adding items to cart in the data-loader
+ * architecture. It works with the resolver-backed CartGateway so the scaffold
+ * never needs direct integration credentials.
+ *
+ * Merchandise display data (title, price, image) for optimistic cart UI is
+ * auto-resolved from the React Query cache for both single-product loaders
+ * (e.g. `ProductLoader`) and product-list loaders (e.g.
+ * `CollectionProductsLoader`, `RebuyRecommendationsLoader`). Just pass the
+ * merchandiseId. Pass `merchandise` explicitly only when the variant is
+ * known but its product was not loaded via a supported loader.
+ *
+ * @example
+ * ```tsx
+ * import { useAddToCart } from "@replohq/sdk/cart/hooks/use-add-to-cart";
+ *
+ * function AddToCartButton({ variant }) {
+ *   const { addToCart, isAdding } = useAddToCart();
+ *
+ *   return (
+ *     <button
+ *       disabled={!variant.availableForSale || isAdding}
+ *       onClick={() => {
+ *         addToCart([{ merchandiseId: variant.id, quantity: 1 }]);
+ *       }}
+ *     >
+ *       {isAdding ? "Adding..." : "Add to Cart"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAddToCart(): {
+    addToCart: (items: AddToCartItem[], openCartAfterAdd?: boolean) => Promise<void>;
+    isAdding: boolean;
+};

package/cart/hooks/use-add-to-cart.js

@@ -0,0 +1,124 @@
+"use client";
+import React from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { fromMajorUnitsToMinorUnits } from "../../_vendor/schemas/money.mjs";
+import { DATA_LOADER_KEYS } from "../../loaders/loader-keys";
+import { useCartInternal } from "../cart-provider";
+import { REPLO_ATTRIBUTION_PROPERTY } from "../cart-types";
+const PRODUCT_LOADER_KEYS = [
+  DATA_LOADER_KEYS.SHOPIFY_PRODUCT,
+  DATA_LOADER_KEYS.REPLO_PRODUCT
+];
+const PRODUCT_LIST_LOADER_KEYS = [
+  DATA_LOADER_KEYS.SHOPIFY_COLLECTION_PRODUCTS,
+  DATA_LOADER_KEYS.REBUY_RECOMMENDATIONS
+];
+function getMerchandiseFromProduct({
+  product,
+  merchandiseId
+}) {
+  if (!product.variants) {
+    return void 0;
+  }
+  const matchingVariant = product.variants.find(
+    (variant) => variant.id === merchandiseId
+  );
+  if (!matchingVariant) {
+    return void 0;
+  }
+  const image = matchingVariant.image ?? product.featuredImage ?? null;
+  return {
+    id: merchandiseId,
+    product: {
+      id: product.id,
+      title: product.title ?? "",
+      sellingPlanGroups: product.sellingPlanGroups ?? []
+    },
+    title: matchingVariant.title ?? "",
+    // NOTE (Max, 2026-08-03): loader prices are decimal MoneyV2 strings, but the
+    // cart is integer minor units, so convert at this storefront→cart boundary —
+    // a raw parseFloat would store "19.99" as 19 minor units (~100× too cheap).
+    price: matchingVariant.price ? fromMajorUnitsToMinorUnits(matchingVariant.price) : 0,
+    compareAtPrice: matchingVariant.compareAtPrice ? fromMajorUnitsToMinorUnits(matchingVariant.compareAtPrice) : null,
+    image: image ? { url: image.url, altText: image.altText } : null,
+    selectedOptions: matchingVariant.selectedOptions ?? []
+  };
+}
+function findMerchandiseInQueryCache({
+  queryClient,
+  merchandiseId
+}) {
+  for (const loaderKey of PRODUCT_LOADER_KEYS) {
+    const productQueries = queryClient.getQueriesData({
+      queryKey: [loaderKey]
+    });
+    for (const [, productData] of productQueries) {
+      if (!productData) {
+        continue;
+      }
+      const merchandise = getMerchandiseFromProduct({
+        product: productData,
+        merchandiseId
+      });
+      if (merchandise) {
+        return merchandise;
+      }
+    }
+  }
+  for (const loaderKey of PRODUCT_LIST_LOADER_KEYS) {
+    const productListQueries = queryClient.getQueriesData({
+      queryKey: [loaderKey]
+    });
+    for (const [, productListData] of productListQueries) {
+      for (const product of productListData?.products ?? []) {
+        const merchandise = getMerchandiseFromProduct({
+          product,
+          merchandiseId
+        });
+        if (merchandise) {
+          return merchandise;
+        }
+      }
+    }
+  }
+  return void 0;
+}
+function useAddToCart() {
+  const cart = useCartInternal();
+  const queryClient = useQueryClient();
+  const [isAdding, setIsAdding] = React.useState(false);
+  const addToCart = React.useCallback(
+    async (items, openCartAfterAdd = true) => {
+      setIsAdding(true);
+      try {
+        const cartLines = items.map((item) => {
+          const hasReploAttribution = item.properties?.some(
+            (prop) => prop.key === REPLO_ATTRIBUTION_PROPERTY.key
+          );
+          const properties = hasReploAttribution ? item.properties ?? [] : [REPLO_ATTRIBUTION_PROPERTY, ...item.properties ?? []];
+          const merchandise = item.merchandise ?? findMerchandiseInQueryCache({
+            queryClient,
+            merchandiseId: item.merchandiseId
+          });
+          return {
+            id: item.merchandiseId,
+            quantity: item.quantity ?? 1,
+            sellingPlanId: item.sellingPlanId ?? void 0,
+            properties,
+            merchandise
+          };
+        });
+        await cart.addToCart(cartLines, openCartAfterAdd);
+      } finally {
+        setIsAdding(false);
+      }
+    },
+    [cart, queryClient]
+  );
+  return { addToCart, isAdding };
+}
+export {
+  findMerchandiseInQueryCache,
+  useAddToCart
+};
+//# sourceMappingURL=use-add-to-cart.js.map

package/cart/hooks/use-add-to-cart.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../cart/hooks/use-add-to-cart.ts"],
+  "sourcesContent": ["/**\n * Hook for adding items to cart using merchandiseId directly (e.g. variant GIDs from data loaders).\n * Merchandise display data for optimistic UI is auto-resolved from the React Query cache.\n * @module\n */\n\"use client\";\n\nimport type { QueryClient } from \"@tanstack/react-query\";\nimport type { Product } from \"../../loaders/loader-schemas\";\nimport type { CartLineAttribute, CartLineMerchandise } from \"../cart-types\";\n\nimport React from \"react\";\n\nimport { useQueryClient } from \"@tanstack/react-query\";\nimport { fromMajorUnitsToMinorUnits } from \"schemas/money\";\n\nimport { DATA_LOADER_KEYS } from \"../../loaders/loader-keys\";\nimport { useCartInternal } from \"../cart-provider\";\nimport { REPLO_ATTRIBUTION_PROPERTY } from \"../cart-types\";\n\ntype ProductListLike = { products: Product[] };\n\n/**\n * Describes a single item to add to the cart. Uses the merchandiseId\n * (e.g. a variant GID) directly from data loader output. Product\n * display data for optimistic UI is resolved automatically from the\n * React Query cache for both single-product loaders (e.g. ProductLoader)\n * and product-list loaders (e.g. CollectionProductsLoader,\n * RebuyRecommendationsLoader). Pass `merchandise` explicitly to bypass\n * the cache lookup when the variant is known but its product was not\n * loaded via a supported loader.\n */\nexport interface AddToCartItem {\n  /** The cart-addressable merchandise ID (e.g. `product.variants[N].id` from loader output). */\n  merchandiseId: string;\n  quantity?: number;\n  sellingPlanId?: string | null;\n  /** Custom line item properties (appear on the order). */\n  properties?: CartLineAttribute[];\n  merchandise?: CartLineMerchandise;\n}\n\n/**\n * Loaders whose cached value is a single Product. Scanned for variant\n * matches first since they carry the richest product data.\n */\nconst PRODUCT_LOADER_KEYS = [\n  DATA_LOADER_KEYS.SHOPIFY_PRODUCT,\n  DATA_LOADER_KEYS.REPLO_PRODUCT,\n] as const;\n\nconst PRODUCT_LIST_LOADER_KEYS = [\n  DATA_LOADER_KEYS.SHOPIFY_COLLECTION_PRODUCTS,\n  DATA_LOADER_KEYS.REBUY_RECOMMENDATIONS,\n] as const;\n\nfunction getMerchandiseFromProduct({\n  product,\n  merchandiseId,\n}: {\n  product: Product;\n  merchandiseId: string;\n}): CartLineMerchandise | undefined {\n  if (!product.variants) {\n    return undefined;\n  }\n\n  const matchingVariant = product.variants.find(\n    (variant) => variant.id === merchandiseId,\n  );\n\n  if (!matchingVariant) {\n    return undefined;\n  }\n\n  const image = matchingVariant.image ?? product.featuredImage ?? null;\n  return {\n    id: merchandiseId,\n    product: {\n      id: product.id,\n      title: product.title ?? \"\",\n      sellingPlanGroups: product.sellingPlanGroups ?? [],\n    },\n    title: matchingVariant.title ?? \"\",\n    // NOTE (Max, 2026-08-03): loader prices are decimal MoneyV2 strings, but the\n    // cart is integer minor units, so convert at this storefront\u2192cart boundary \u2014\n    // a raw parseFloat would store \"19.99\" as 19 minor units (~100\u00D7 too cheap).\n    price: matchingVariant.price\n      ? fromMajorUnitsToMinorUnits(matchingVariant.price)\n      : 0,\n    compareAtPrice: matchingVariant.compareAtPrice\n      ? fromMajorUnitsToMinorUnits(matchingVariant.compareAtPrice)\n      : null,\n    image: image ? { url: image.url, altText: image.altText } : null,\n    selectedOptions: matchingVariant.selectedOptions ?? [],\n  };\n}\n\nexport function findMerchandiseInQueryCache({\n  queryClient,\n  merchandiseId,\n}: {\n  queryClient: QueryClient;\n  merchandiseId: string;\n}): CartLineMerchandise | undefined {\n  for (const loaderKey of PRODUCT_LOADER_KEYS) {\n    const productQueries = queryClient.getQueriesData<Product>({\n      queryKey: [loaderKey],\n    });\n\n    for (const [, productData] of productQueries) {\n      if (!productData) {\n        continue;\n      }\n\n      const merchandise = getMerchandiseFromProduct({\n        product: productData,\n        merchandiseId,\n      });\n      if (merchandise) {\n        return merchandise;\n      }\n    }\n  }\n\n  for (const loaderKey of PRODUCT_LIST_LOADER_KEYS) {\n    const productListQueries = queryClient.getQueriesData<ProductListLike>({\n      queryKey: [loaderKey],\n    });\n\n    for (const [, productListData] of productListQueries) {\n      for (const product of productListData?.products ?? []) {\n        const merchandise = getMerchandiseFromProduct({\n          product,\n          merchandiseId,\n        });\n        if (merchandise) {\n          return merchandise;\n        }\n      }\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Hook for adding items to cart using merchandise IDs from data loader output.\n *\n * This is the primary hook for adding items to cart in the data-loader\n * architecture. It works with the resolver-backed CartGateway so the scaffold\n * never needs direct integration credentials.\n *\n * Merchandise display data (title, price, image) for optimistic cart UI is\n * auto-resolved from the React Query cache for both single-product loaders\n * (e.g. `ProductLoader`) and product-list loaders (e.g.\n * `CollectionProductsLoader`, `RebuyRecommendationsLoader`). Just pass the\n * merchandiseId. Pass `merchandise` explicitly only when the variant is\n * known but its product was not loaded via a supported loader.\n *\n * @example\n * ```tsx\n * import { useAddToCart } from \"@replohq/sdk/cart/hooks/use-add-to-cart\";\n *\n * function AddToCartButton({ variant }) {\n *   const { addToCart, isAdding } = useAddToCart();\n *\n *   return (\n *     <button\n *       disabled={!variant.availableForSale || isAdding}\n *       onClick={() => {\n *         addToCart([{ merchandiseId: variant.id, quantity: 1 }]);\n *       }}\n *     >\n *       {isAdding ? \"Adding...\" : \"Add to Cart\"}\n *     </button>\n *   );\n * }\n * ```\n */\nexport function useAddToCart() {\n  const cart = useCartInternal();\n  const queryClient = useQueryClient();\n  const [isAdding, setIsAdding] = React.useState(false);\n\n  const addToCart = React.useCallback(\n    async (items: AddToCartItem[], openCartAfterAdd = true) => {\n      setIsAdding(true);\n      try {\n        const cartLines = items.map((item) => {\n          const hasReploAttribution = item.properties?.some(\n            (prop) => prop.key === REPLO_ATTRIBUTION_PROPERTY.key,\n          );\n          const properties = hasReploAttribution\n            ? item.properties ?? []\n            : [REPLO_ATTRIBUTION_PROPERTY, ...(item.properties ?? [])];\n\n          const merchandise =\n            item.merchandise ??\n            findMerchandiseInQueryCache({\n              queryClient,\n              merchandiseId: item.merchandiseId,\n            });\n\n          return {\n            id: item.merchandiseId,\n            quantity: item.quantity ?? 1,\n            sellingPlanId: item.sellingPlanId ?? undefined,\n            properties,\n            merchandise,\n          };\n        });\n\n        await cart.addToCart(cartLines, openCartAfterAdd);\n      } finally {\n        setIsAdding(false);\n      }\n    },\n    [cart, queryClient],\n  );\n\n  return { addToCart, isAdding };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/cart/hooks/use-buy-now.d.ts

@@ -0,0 +1,49 @@
+export interface VariantBuyNowInfo {
+    variantId: string;
+    quantity?: number;
+    sellingPlanId?: string | null;
+}
+/**
+ * React hook that returns a `buyNow` function for express checkout flows.
+ * Handles creating the cart/checkout session server-side and redirecting
+ * the browser to checkout.
+ *
+ * @example
+ *
+ * ```tsx
+ * import { useBuyNow } from "@replohq/sdk/cart/hooks/use-buy-now";
+ *
+ * function MyComponent({ selectedVariant, selectedSellingPlan, quantity }) {
+ *   const { buyNow } = useBuyNow();
+ *
+ *   return (
+ *     <Button
+ *       disabled={!selectedVariant?.availableForSale}
+ *       onClick={async () => {
+ *         if (selectedVariant) {
+ *           await buyNow(
+ *             [
+ *               {
+ *                 variantId: selectedVariant.id,
+ *                 quantity,
+ *                 sellingPlanId: selectedSellingPlan?.id,
+ *               },
+ *             ],
+ *             { discountCodes: ["SUMMER2024"] }
+ *           );
+ *         }
+ *       }}
+ *     >
+ *       Shop Now
+ *     </Button>
+ *   );
+ * }
+ * ```
+ *
+ * @returns Object containing the buyNow function
+ */
+export declare function useBuyNow(): {
+    buyNow: (variants: VariantBuyNowInfo[], options?: {
+        discountCodes?: string[];
+    }) => Promise<void>;
+};

package/cart/hooks/use-buy-now.js

@@ -0,0 +1,62 @@
+"use client";
+import React from "react";
+import { useClientValue } from "../../hooks/use-client-value";
+import { CanopyError } from "../../lib/canopy-error";
+import { buyNowAction } from "../buy-now-action";
+const REPLO_LOCAL_STORAGE_SESSION_KEY = "_replo_sid";
+const REPLO_SESSION_ID_KEY = "rsid";
+const REPLO_CLIENT_ID_KEY = "rclid";
+class ProductHasNoVariantsError extends CanopyError {
+}
+function useBuyNow() {
+  const reploSessionString = useClientValue(
+    () => localStorage.getItem(REPLO_LOCAL_STORAGE_SESSION_KEY),
+    null
+  );
+  const buyNow = React.useCallback(
+    async (variants, options) => {
+      if (!variants || variants.length === 0) {
+        throw new ProductHasNoVariantsError({
+          message: "No variants provided"
+        });
+      }
+      const { redirectUrl } = await buyNowAction({
+        lineItems: variants.map((variant) => ({
+          variantId: variant.variantId,
+          quantity: variant.quantity ?? 1,
+          sellingPlanId: variant.sellingPlanId ?? null,
+          properties: []
+        })),
+        discountCodes: options?.discountCodes ?? [],
+        pageUrl: window.location.href
+      });
+      const url = new URL(redirectUrl);
+      const isStripeCheckout = url.hostname.endsWith("stripe.com");
+      if (!isStripeCheckout) {
+        const currentParams = new URLSearchParams(window.location.search);
+        for (const [key, value] of currentParams.entries()) {
+          if (!url.searchParams.has(key)) {
+            url.searchParams.set(key, value);
+          }
+        }
+        if (reploSessionString) {
+          try {
+            const sessionData = JSON.parse(reploSessionString);
+            if (sessionData.sessionId && sessionData.reploId) {
+              url.searchParams.set(REPLO_SESSION_ID_KEY, sessionData.sessionId);
+              url.searchParams.set(REPLO_CLIENT_ID_KEY, sessionData.reploId);
+            }
+          } catch {
+          }
+        }
+      }
+      window.location.href = url.toString();
+    },
+    [reploSessionString]
+  );
+  return { buyNow };
+}
+export {
+  useBuyNow
+};
+//# sourceMappingURL=use-buy-now.js.map

package/cart/hooks/use-buy-now.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../cart/hooks/use-buy-now.ts"],
+  "sourcesContent": ["/**\n * Use useBuyNow() hook to create \"Buy Now\" buttons that skip the cart and go directly to checkout.\n * Calls a server action to create the cart/checkout session, then redirects the browser.\n * @module\n */\n\"use client\";\n\nimport React from \"react\";\n\nimport { useClientValue } from \"../../hooks/use-client-value\";\nimport { CanopyError } from \"../../lib/canopy-error\";\nimport { buyNowAction } from \"../buy-now-action\";\n\n// Analytics constants - defined locally to avoid dependency on analytics-client package\nconst REPLO_LOCAL_STORAGE_SESSION_KEY = \"_replo_sid\";\nconst REPLO_SESSION_ID_KEY = \"rsid\";\nconst REPLO_CLIENT_ID_KEY = \"rclid\";\n\n// Analytics session data type - defined locally to avoid dependency\ninterface AnalyticsSessionData {\n  sessionId: string;\n  reploId: string;\n  expiresAt: number;\n  createdAt: number;\n  conversionsCounter: number;\n  isEntryPage: boolean;\n}\n\nclass ProductHasNoVariantsError extends CanopyError {}\n\nexport interface VariantBuyNowInfo {\n  variantId: string;\n  quantity?: number;\n  sellingPlanId?: string | null;\n}\n\n/**\n * React hook that returns a `buyNow` function for express checkout flows.\n * Handles creating the cart/checkout session server-side and redirecting\n * the browser to checkout.\n *\n * @example\n *\n * ```tsx\n * import { useBuyNow } from \"@replohq/sdk/cart/hooks/use-buy-now\";\n *\n * function MyComponent({ selectedVariant, selectedSellingPlan, quantity }) {\n *   const { buyNow } = useBuyNow();\n *\n *   return (\n *     <Button\n *       disabled={!selectedVariant?.availableForSale}\n *       onClick={async () => {\n *         if (selectedVariant) {\n *           await buyNow(\n *             [\n *               {\n *                 variantId: selectedVariant.id,\n *                 quantity,\n *                 sellingPlanId: selectedSellingPlan?.id,\n *               },\n *             ],\n *             { discountCodes: [\"SUMMER2024\"] }\n *           );\n *         }\n *       }}\n *     >\n *       Shop Now\n *     </Button>\n *   );\n * }\n * ```\n *\n * @returns Object containing the buyNow function\n */\nexport function useBuyNow() {\n  const reploSessionString = useClientValue(\n    () => localStorage.getItem(REPLO_LOCAL_STORAGE_SESSION_KEY),\n    null,\n  );\n\n  const buyNow = React.useCallback(\n    async (\n      variants: VariantBuyNowInfo[],\n      options?: { discountCodes?: string[] },\n    ) => {\n      if (!variants || variants.length === 0) {\n        throw new ProductHasNoVariantsError({\n          message: \"No variants provided\",\n        });\n      }\n\n      const { redirectUrl } = await buyNowAction({\n        lineItems: variants.map((variant) => ({\n          variantId: variant.variantId,\n          quantity: variant.quantity ?? 1,\n          sellingPlanId: variant.sellingPlanId ?? null,\n          properties: [],\n        })),\n        discountCodes: options?.discountCodes ?? [],\n        pageUrl: window.location.href,\n      });\n\n      const url = new URL(redirectUrl);\n\n      // Only append tracking params for non-Stripe checkout URLs (e.g. Shopify).\n      // Stripe checkout URLs should not be modified with extra query params.\n      const isStripeCheckout = url.hostname.endsWith(\"stripe.com\");\n      if (!isStripeCheckout) {\n        const currentParams = new URLSearchParams(window.location.search);\n        for (const [key, value] of currentParams.entries()) {\n          if (!url.searchParams.has(key)) {\n            url.searchParams.set(key, value);\n          }\n        }\n\n        if (reploSessionString) {\n          try {\n            const sessionData: AnalyticsSessionData =\n              JSON.parse(reploSessionString);\n            if (sessionData.sessionId && sessionData.reploId) {\n              url.searchParams.set(REPLO_SESSION_ID_KEY, sessionData.sessionId);\n              url.searchParams.set(REPLO_CLIENT_ID_KEY, sessionData.reploId);\n            }\n          } catch {\n            // Ignore invalid session data\n          }\n        }\n      }\n\n      window.location.href = url.toString();\n    },\n    [reploSessionString],\n  );\n\n  return { buyNow };\n}\n"],
+  "mappings": ";AAOA,OAAO,WAAW;AAElB,SAAS,sBAAsB;AAC/B,SAAS,mBAAmB;AAC5B,SAAS,oBAAoB;AAG7B,MAAM,kCAAkC;AACxC,MAAM,uBAAuB;AAC7B,MAAM,sBAAsB;AAY5B,MAAM,kCAAkC,YAAY;AAAC;AA+C9C,SAAS,YAAY;AAC1B,QAAM,qBAAqB;AAAA,IACzB,MAAM,aAAa,QAAQ,+BAA+B;AAAA,IAC1D;AAAA,EACF;AAEA,QAAM,SAAS,MAAM;AAAA,IACnB,OACE,UACA,YACG;AACH,UAAI,CAAC,YAAY,SAAS,WAAW,GAAG;AACtC,cAAM,IAAI,0BAA0B;AAAA,UAClC,SAAS;AAAA,QACX,CAAC;AAAA,MACH;AAEA,YAAM,EAAE,YAAY,IAAI,MAAM,aAAa;AAAA,QACzC,WAAW,SAAS,IAAI,CAAC,aAAa;AAAA,UACpC,WAAW,QAAQ;AAAA,UACnB,UAAU,QAAQ,YAAY;AAAA,UAC9B,eAAe,QAAQ,iBAAiB;AAAA,UACxC,YAAY,CAAC;AAAA,QACf,EAAE;AAAA,QACF,eAAe,SAAS,iBAAiB,CAAC;AAAA,QAC1C,SAAS,OAAO,SAAS;AAAA,MAC3B,CAAC;AAED,YAAM,MAAM,IAAI,IAAI,WAAW;AAI/B,YAAM,mBAAmB,IAAI,SAAS,SAAS,YAAY;AAC3D,UAAI,CAAC,kBAAkB;AACrB,cAAM,gBAAgB,IAAI,gBAAgB,OAAO,SAAS,MAAM;AAChE,mBAAW,CAAC,KAAK,KAAK,KAAK,cAAc,QAAQ,GAAG;AAClD,cAAI,CAAC,IAAI,aAAa,IAAI,GAAG,GAAG;AAC9B,gBAAI,aAAa,IAAI,KAAK,KAAK;AAAA,UACjC;AAAA,QACF;AAEA,YAAI,oBAAoB;AACtB,cAAI;AACF,kBAAM,cACJ,KAAK,MAAM,kBAAkB;AAC/B,gBAAI,YAAY,aAAa,YAAY,SAAS;AAChD,kBAAI,aAAa,IAAI,sBAAsB,YAAY,SAAS;AAChE,kBAAI,aAAa,IAAI,qBAAqB,YAAY,OAAO;AAAA,YAC/D;AAAA,UACF,QAAQ;AAAA,UAER;AAAA,QACF;AAAA,MACF;AAEA,aAAO,SAAS,OAAO,IAAI,SAAS;AAAA,IACtC;AAAA,IACA,CAAC,kBAAkB;AAAA,EACrB;AAEA,SAAO,EAAE,OAAO;AAClB;",
+  "names": []
+}

package/cart/utils/cart-utils.d.ts

@@ -0,0 +1,43 @@
+import type { Cart, CartLine } from "../cart-types";
+export interface CartTotals {
+    subtotal: number;
+    discountAmount: number;
+    totalSavings: number;
+    total: number;
+}
+/**
+ * Sum the final (post selling-plan) price of every line item in the cart.
+ * This is the authoritative subtotal for cookie-based carts, which have no
+ * server-computed cost to rely on.
+ */
+export declare function calculateLineItemsSubtotal(lineItems: CartLine[]): number;
+/**
+ * Calculate cart totals including subtotal, discounts, and final total.
+ * When cart cost data is provided (from Shopify), uses the actual totalAmount
+ * which includes cart-level discounts from discount codes.
+ *
+ * @param options - Object containing lineItems and cart
+ * @param options.lineItems - Array of cart line items
+ * @param options.cart - Optional cart data from Shopify (includes discount codes)
+ */
+export declare function calculateCartTotals({ lineItems, cart, }: {
+    lineItems: CartLine[];
+    cart: Cart | null;
+}): CartTotals;
+/**
+ * @deprecated Back-compat shim kept for surface parity with canopy-sdk, so
+ * sites migrating off `import { formatPrice } from
+ * "canopy-sdk/cart/utils/cart-utils"` keep rendering with only the package
+ * specifier renamed. It formats INTEGER MINOR UNITS — the units every cart
+ * value uses (`calculateCartTotals`, `getCartLinePricing`, `CartCost`):
+ * passing 1999 yields "$19.99", not "$1,999.00". New code should call
+ * `formatAmount({ amount, currencyCode })` from `@replohq/sdk/money` directly.
+ */
+export declare function formatPrice(price: number, currency?: string): string;
+/**
+ * Validates and formats a Shopify selling plan ID to ensure it has the correct GID format.
+ *
+ * @param sellingPlanId - The selling plan ID to validate and format
+ * @returns The formatted selling plan ID with GID prefix, or null if no ID provided
+ */
+export declare function formatSellingPlanId(sellingPlanId: string | null | undefined): string | null;

package/cart/utils/cart-utils.js

@@ -0,0 +1,46 @@
+import { formatAmount } from "../../_vendor/schemas/money.mjs";
+import { getCartLinePricing } from "./variant-to-cart-line";
+function calculateLineItemsSubtotal(lineItems) {
+  return lineItems.reduce(
+    (sum, item) => sum + getCartLinePricing(item).finalPrice * item.quantity,
+    0
+  );
+}
+function calculateCartTotals({
+  lineItems,
+  cart
+}) {
+  const lineItemSubtotal = calculateLineItemsSubtotal(lineItems);
+  const compareAtSubtotal = lineItems.reduce((sum, item) => {
+    return sum + getCartLinePricing(item).compareAtPrice * item.quantity;
+  }, 0);
+  const total = cart?.cost.totalAmount ?? lineItemSubtotal;
+  const actualSubtotal = cart?.cost.subtotalAmount ?? lineItemSubtotal;
+  const discountAmount = actualSubtotal - total;
+  const totalSavings = compareAtSubtotal - total;
+  return {
+    subtotal: lineItemSubtotal,
+    discountAmount,
+    totalSavings,
+    total
+  };
+}
+function formatPrice(price, currency = "USD") {
+  return formatAmount({ amount: price, currencyCode: currency });
+}
+function formatSellingPlanId(sellingPlanId) {
+  if (!sellingPlanId) {
+    return null;
+  }
+  if (sellingPlanId.startsWith("gid://shopify/SellingPlan/")) {
+    return sellingPlanId;
+  }
+  return `gid://shopify/SellingPlan/${sellingPlanId}`;
+}
+export {
+  calculateCartTotals,
+  calculateLineItemsSubtotal,
+  formatPrice,
+  formatSellingPlanId
+};
+//# sourceMappingURL=cart-utils.js.map

package/cart/utils/cart-utils.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../cart/utils/cart-utils.ts"],
+  "sourcesContent": ["import type { Cart, CartLine } from \"../cart-types\";\n\nimport { formatAmount } from \"schemas/money\";\n\nimport { getCartLinePricing } from \"./variant-to-cart-line\";\n\nexport interface CartTotals {\n  subtotal: number;\n  discountAmount: number;\n  totalSavings: number;\n  total: number;\n}\n\n/**\n * Sum the final (post selling-plan) price of every line item in the cart.\n * This is the authoritative subtotal for cookie-based carts, which have no\n * server-computed cost to rely on.\n */\nexport function calculateLineItemsSubtotal(lineItems: CartLine[]): number {\n  return lineItems.reduce(\n    (sum, item) => sum + getCartLinePricing(item).finalPrice * item.quantity,\n    0,\n  );\n}\n\n/**\n * Calculate cart totals including subtotal, discounts, and final total.\n * When cart cost data is provided (from Shopify), uses the actual totalAmount\n * which includes cart-level discounts from discount codes.\n *\n * @param options - Object containing lineItems and cart\n * @param options.lineItems - Array of cart line items\n * @param options.cart - Optional cart data from Shopify (includes discount codes)\n */\nexport function calculateCartTotals({\n  lineItems,\n  cart,\n}: {\n  lineItems: CartLine[];\n  cart: Cart | null;\n}): CartTotals {\n  const lineItemSubtotal = calculateLineItemsSubtotal(lineItems);\n  const compareAtSubtotal = lineItems.reduce((sum, item) => {\n    return sum + getCartLinePricing(item).compareAtPrice * item.quantity;\n  }, 0);\n\n  // NOTE (Jasmine, 2026-07-22): Trust the provider's authoritative cost when\n  // present. For Shopify this is the server-computed cart cost (including a\n  // legitimate $0 when items aren't purchasable), which we must not\n  // second-guess; cookie carts keep their cost truthful via\n  // cookie-cart-persistence.ts.\n  const total = cart?.cost.totalAmount ?? lineItemSubtotal;\n\n  // If we have provider cost data, use subtotalAmount which doesn't include discounts\n  const actualSubtotal = cart?.cost.subtotalAmount ?? lineItemSubtotal;\n  const discountAmount = actualSubtotal - total;\n\n  const totalSavings = compareAtSubtotal - total;\n\n  return {\n    subtotal: lineItemSubtotal,\n    discountAmount,\n    totalSavings,\n    total,\n  };\n}\n\n/**\n * @deprecated Back-compat shim kept for surface parity with canopy-sdk, so\n * sites migrating off `import { formatPrice } from\n * \"canopy-sdk/cart/utils/cart-utils\"` keep rendering with only the package\n * specifier renamed. It formats INTEGER MINOR UNITS \u2014 the units every cart\n * value uses (`calculateCartTotals`, `getCartLinePricing`, `CartCost`):\n * passing 1999 yields \"$19.99\", not \"$1,999.00\". New code should call\n * `formatAmount({ amount, currencyCode })` from `@replohq/sdk/money` directly.\n */\nexport function formatPrice(price: number, currency: string = \"USD\"): string {\n  return formatAmount({ amount: price, currencyCode: currency });\n}\n\n/**\n * Validates and formats a Shopify selling plan ID to ensure it has the correct GID format.\n *\n * @param sellingPlanId - The selling plan ID to validate and format\n * @returns The formatted selling plan ID with GID prefix, or null if no ID provided\n */\nexport function formatSellingPlanId(\n  sellingPlanId: string | null | undefined,\n): string | null {\n  if (!sellingPlanId) {\n    return null;\n  }\n\n  // Check if it already has the gid format\n  if (sellingPlanId.startsWith(\"gid://shopify/SellingPlan/\")) {\n    return sellingPlanId;\n  }\n\n  // If it doesn't have the gid format, prepend it\n  return `gid://shopify/SellingPlan/${sellingPlanId}`;\n}\n"],
+  "mappings": "AAEA,SAAS,oBAAoB;AAE7B,SAAS,0BAA0B;AAc5B,SAAS,2BAA2B,WAA+B;AACxE,SAAO,UAAU;AAAA,IACf,CAAC,KAAK,SAAS,MAAM,mBAAmB,IAAI,EAAE,aAAa,KAAK;AAAA,IAChE;AAAA,EACF;AACF;AAWO,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA;AACF,GAGe;AACb,QAAM,mBAAmB,2BAA2B,SAAS;AAC7D,QAAM,oBAAoB,UAAU,OAAO,CAAC,KAAK,SAAS;AACxD,WAAO,MAAM,mBAAmB,IAAI,EAAE,iBAAiB,KAAK;AAAA,EAC9D,GAAG,CAAC;AAOJ,QAAM,QAAQ,MAAM,KAAK,eAAe;AAGxC,QAAM,iBAAiB,MAAM,KAAK,kBAAkB;AACpD,QAAM,iBAAiB,iBAAiB;AAExC,QAAM,eAAe,oBAAoB;AAEzC,SAAO;AAAA,IACL,UAAU;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAWO,SAAS,YAAY,OAAe,WAAmB,OAAe;AAC3E,SAAO,aAAa,EAAE,QAAQ,OAAO,cAAc,SAAS,CAAC;AAC/D;AAQO,SAAS,oBACd,eACe;AACf,MAAI,CAAC,eAAe;AAClB,WAAO;AAAA,EACT;AAGA,MAAI,cAAc,WAAW,4BAA4B,GAAG;AAC1D,WAAO;AAAA,EACT;AAGA,SAAO,6BAA6B,aAAa;AACnD;",
+  "names": []
+}

package/cart/utils/cookie-cart-persistence.d.ts

@@ -0,0 +1,55 @@
+import type { AddToCartPayload, Cart, CartLine, CartLinePayload, RemoveFromCartPayload, UpdateCartLineItemPayload } from "../cart-types";
+/**
+ * Line merge function type - returns index of existing line to merge with, or -1 to add as new line
+ */
+export type LineMergeFn = (existingLines: CartLine[], newLine: CartLinePayload) => number;
+/**
+ * Options for creating a cart with persistence
+ */
+interface CreateCartOptions {
+    cookieName: string;
+    lines?: CartLinePayload[];
+    lineIdGenerator: () => string;
+    cartIdGenerator: () => string;
+}
+/**
+ * Options for adding to cart with persistence
+ */
+interface AddToCartOptions {
+    cookieName: string;
+    mergeFn: LineMergeFn;
+    lineIdGenerator: () => string;
+}
+/**
+ * Save cart to cookie
+ */
+export declare function saveCartToCookie(cart: Cart, cookieName: string): Promise<void>;
+/**
+ * Load cart from cookie
+ */
+export declare function loadCartFromCookie(cookieName: string): Promise<Cart | null>;
+/**
+ * Clear cart cookie
+ */
+export declare function clearCartCookie(cookieName: string): Promise<void>;
+/**
+ * Update cart in cookie atomically (load-transform-save pattern)
+ */
+export declare function updateCartInCookie(cartId: string, cookieName: string, updater: (cart: Cart) => Cart): Promise<Cart | null>;
+/**
+ * Create a new cart with persistence
+ */
+export declare function createCartWithPersistence(options: CreateCartOptions): Promise<Cart | null>;
+/**
+ * Add lines to cart with configurable line merging strategy
+ */
+export declare function addToCartWithPersistence(payload: AddToCartPayload, options: AddToCartOptions): Promise<Cart | null>;
+/**
+ * Update cart line item
+ */
+export declare function updateCartLineItemWithPersistence(payload: UpdateCartLineItemPayload, cookieName: string): Promise<Cart | null>;
+/**
+ * Remove cart line items
+ */
+export declare function removeCartLineItemsWithPersistence(payload: RemoveFromCartPayload, cookieName: string): Promise<Cart | null>;
+export {};

package/cart/utils/cookie-cart-persistence.js

@@ -0,0 +1,166 @@
+"use server";
+import { cookies } from "next/headers";
+import { calculateLineItemsSubtotal } from "./cart-utils";
+const CART_COOKIE_MAX_AGE = 60 * 60 * 24 * 30;
+function recalculateCartCost(cart) {
+  const subtotal = calculateLineItemsSubtotal(cart.lines);
+  return {
+    ...cart,
+    cost: {
+      ...cart.cost,
+      subtotalAmount: subtotal,
+      totalAmount: subtotal
+    }
+  };
+}
+async function saveCartToCookie(cart, cookieName) {
+  const cookieStore = await cookies();
+  cookieStore.set(cookieName, JSON.stringify(cart), {
+    maxAge: CART_COOKIE_MAX_AGE,
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/"
+  });
+}
+async function loadCartFromCookie(cookieName) {
+  const cookieStore = await cookies();
+  const cartCookie = cookieStore.get(cookieName);
+  if (!cartCookie?.value) {
+    return null;
+  }
+  try {
+    return JSON.parse(cartCookie.value);
+  } catch (error) {
+    console.warn("Failed to parse cart cookie:", error);
+    await clearCartCookie(cookieName);
+    return null;
+  }
+}
+async function clearCartCookie(cookieName) {
+  const cookieStore = await cookies();
+  cookieStore.delete(cookieName);
+}
+async function updateCartInCookie(cartId, cookieName, updater) {
+  const existingCart = await loadCartFromCookie(cookieName);
+  if (!existingCart || existingCart.id !== cartId) {
+    return null;
+  }
+  const updatedCart = recalculateCartCost(updater(existingCart));
+  await saveCartToCookie(updatedCart, cookieName);
+  return updatedCart;
+}
+async function createCartWithPersistence(options) {
+  const cartId = options.cartIdGenerator();
+  const cart = {
+    id: cartId,
+    lines: [],
+    cost: {
+      subtotalAmount: 0,
+      totalAmount: 0,
+      currencyCode: "USD"
+    },
+    checkoutUrl: "/checkout"
+  };
+  for (const line of options.lines ?? []) {
+    cart.lines.push(
+      convertCartLinePayloadToCartLine(line, options.lineIdGenerator)
+    );
+  }
+  const cartWithCost = recalculateCartCost(cart);
+  await saveCartToCookie(cartWithCost, options.cookieName);
+  return cartWithCost;
+}
+async function addToCartWithPersistence(payload, options) {
+  return await updateCartInCookie(
+    payload.cartId,
+    options.cookieName,
+    (cart) => {
+      for (const linePayload of payload.lines) {
+        const existingLineIndex = options.mergeFn(cart.lines, linePayload);
+        if (existingLineIndex >= 0) {
+          cart.lines[existingLineIndex].quantity += linePayload.quantity;
+        } else {
+          const newLine = convertCartLinePayloadToCartLine(
+            linePayload,
+            options.lineIdGenerator
+          );
+          cart.lines.push(newLine);
+        }
+      }
+      return cart;
+    }
+  );
+}
+async function updateCartLineItemWithPersistence(payload, cookieName) {
+  return await updateCartInCookie(payload.cartId, cookieName, (cart) => {
+    const lineIndex = cart.lines.findIndex(
+      (line) => line.id === payload.line.id
+    );
+    if (lineIndex >= 0) {
+      if (payload.line.quantity <= 0) {
+        cart.lines.splice(lineIndex, 1);
+      } else {
+        cart.lines[lineIndex].quantity = payload.line.quantity;
+        if (payload.line.properties) {
+          cart.lines[lineIndex].attributes = payload.line.properties;
+        }
+        if (payload.line.merchandise) {
+          cart.lines[lineIndex].merchandise = payload.line.merchandise;
+        }
+      }
+    }
+    return cart;
+  });
+}
+async function removeCartLineItemsWithPersistence(payload, cookieName) {
+  return await updateCartInCookie(payload.cartId, cookieName, (cart) => {
+    const removeSet = new Set(payload.lineIds);
+    cart.lines = cart.lines.filter((line) => !removeSet.has(line.id));
+    return cart;
+  });
+}
+function convertCartLinePayloadToCartLine(linePayload, lineIdGenerator) {
+  const fallbackMerchandise = {
+    id: linePayload.id,
+    product: {
+      id: linePayload.merchandise?.product.id ?? linePayload.id,
+      title: linePayload.merchandise?.product.title ?? "Product"
+    },
+    title: linePayload.merchandise?.title ?? "Product Variant",
+    price: linePayload.merchandise?.price ?? 0,
+    compareAtPrice: linePayload.merchandise?.compareAtPrice ?? null,
+    image: linePayload.merchandise?.image ? {
+      url: linePayload.merchandise.image.url,
+      altText: linePayload.merchandise.image.altText
+    } : null,
+    selectedOptions: linePayload.merchandise?.selectedOptions ?? []
+  };
+  return {
+    id: lineIdGenerator(),
+    quantity: linePayload.quantity,
+    merchandise: linePayload.merchandise ?? fallbackMerchandise,
+    attributes: linePayload.properties ?? [],
+    sellingPlanAllocation: linePayload.sellingPlanId ? {
+      sellingPlan: {
+        id: linePayload.sellingPlanId,
+        name: "Subscription Plan",
+        description: null
+      },
+      priceAdjustments: [],
+      checkoutChargeAmount: { amount: 0, currencyCode: "USD" },
+      remainingBalanceChargeAmount: { amount: 0, currencyCode: "USD" }
+    } : null
+  };
+}
+export {
+  addToCartWithPersistence,
+  clearCartCookie,
+  createCartWithPersistence,
+  loadCartFromCookie,
+  removeCartLineItemsWithPersistence,
+  saveCartToCookie,
+  updateCartInCookie,
+  updateCartLineItemWithPersistence
+};
+//# sourceMappingURL=cookie-cart-persistence.js.map