@replohq/sdk 2.19.0 → 2.20.0

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

@@ -1,6 +1,7 @@
 import type { QueryClient } from "@tanstack/react-query";
 import type { CartError } from "../cart-provider";
 import type { CartLineAdjustment, CartLineAttribute, CartLineMerchandise } from "../cart-types";
+import type { CheckoutCatalog } from "./use-checkout-availability";
 /**
  * Describes a single item to add to the cart. Uses the merchandiseId
  * (e.g. a variant GID) directly from data loader output. Product
@@ -56,27 +57,39 @@ export declare function findMerchandiseInQueryCache({ queryClient, merchandiseId
  * and opens the cart UI, which renders it, so a click handler needs no
  * handling of its own.
  *
+ * `checkoutAvailability` is `"unavailable"` while the store can't take
+ * payments yet, or when the `catalog` passed is one this site's checkout
+ * can't sell. Show the button disabled with "Coming soon" then: a shopper
+ * could fill a cart but never check out.
+ *
  * @example
  * ```tsx
  * import { useAddToCart } from "@replohq/sdk/cart/hooks/use-add-to-cart";
  *
  * function AddToCartButton({ variant }) {
- *   const { addToCart, isAdding } = useAddToCart();
+ *   const { addToCart, isAdding, checkoutAvailability } = useAddToCart({
+ *     catalog: "shopify",
+ *   });
+ *   const isComingSoon = checkoutAvailability === "unavailable";
  *
  *   return (
  *     <button
- *       disabled={!variant.availableForSale || isAdding}
+ *       disabled={!variant.availableForSale || isAdding || isComingSoon}
  *       onClick={() => {
  *         void addToCart([{ merchandiseId: variant.id, quantity: 1 }]);
  *       }}
  *     >
- *       {isAdding ? "Adding..." : "Add to Cart"}
+ *       {isComingSoon ? "Coming soon" : isAdding ? "Adding..." : "Add to Cart"}
  *     </button>
  *   );
  * }
  * ```
  */
-export declare function useAddToCart(): {
+export declare function useAddToCart({ catalog, }?: {
+    /** The catalog this control sells from, so `checkoutAvailability` can say whether this site's checkout sells it. */
+    catalog?: CheckoutCatalog | null;
+}): {
     addToCart: (items: AddToCartItem[], openCartAfterAdd?: boolean) => Promise<AddToCartResult>;
     isAdding: boolean;
+    checkoutAvailability: import("./use-checkout-availability").CheckoutAvailability;
 };

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

@@ -6,6 +6,7 @@ import { DATA_LOADER_KEYS } from "../../loaders/loader-keys";
 import { isPlaceholderMerchandiseId } from "../../loaders/placeholder-product";
 import { useCartInternal } from "../cart-provider";
 import { toCartError } from "../utils/cart-error";
+import { useCheckoutAvailability } from "./use-checkout-availability";
 const PRODUCT_LOADER_KEYS = [
   DATA_LOADER_KEYS.SHOPIFY_PRODUCT,
   DATA_LOADER_KEYS.REPLO_PRODUCT
@@ -81,10 +82,13 @@ function findMerchandiseInQueryCache({
   }
   return void 0;
 }
-function useAddToCart() {
+function useAddToCart({
+  catalog = null
+} = {}) {
   const cart = useCartInternal();
   const queryClient = useQueryClient();
   const [isAdding, setIsAdding] = React.useState(false);
+  const checkoutAvailability = useCheckoutAvailability({ catalog });
   const addToCart = React.useCallback(
     async (items, openCartAfterAdd = true) => {
       const buyableItems = items.filter((item) => {
@@ -121,7 +125,7 @@ function useAddToCart() {
     },
     [cart, queryClient]
   );
-  return { addToCart, isAdding };
+  return { addToCart, isAdding, checkoutAvailability };
 }
 export {
   findMerchandiseInQueryCache,

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

@@ -1,4 +1,5 @@
 import type { CartLineAttribute } from "../cart-types";
+import type { CheckoutCatalog } from "./use-checkout-availability";
 /**
  * What a `buyNow` call did. Out of stock is an expected storefront outcome
  * (a buyer can race the last unit), so it rides the return value rather than
@@ -34,18 +35,25 @@ export interface VariantBuyNowInfo {
  * the browser to checkout. Stripe checkout ignores selling plans and discount
  * codes, logging a server-side warning when either is supplied.
  *
+ * `checkoutAvailability` is `"unavailable"` while the store can't take
+ * payments yet (Replo checkout not set up, or checkout turned off), or when
+ * the `catalog` passed is one this site's checkout can't sell. Show the button
+ * disabled with "Coming soon" then, instead of letting the shopper hit a
+ * failed checkout.
+ *
  * @example
  *
  * ```tsx
  * import { useBuyNow } from "@replohq/sdk/cart/hooks/use-buy-now";
  *
  * function MyComponent({ selectedVariant, selectedSellingPlan, quantity }) {
- *   const { buyNow } = useBuyNow();
+ *   const { buyNow, checkoutAvailability } = useBuyNow();
  *   const [isSoldOut, setIsSoldOut] = React.useState(false);
+ *   const isComingSoon = checkoutAvailability === "unavailable";
  *
  *   return (
  *     <Button
- *       disabled={!selectedVariant?.availableForSale || isSoldOut}
+ *       disabled={!selectedVariant?.availableForSale || isSoldOut || isComingSoon}
  *       onClick={async () => {
  *         if (selectedVariant) {
  *           const outcome = await buyNow(
@@ -70,15 +78,18 @@ export interface VariantBuyNowInfo {
  *         }
  *       }}
  *     >
- *       {isSoldOut ? "Sold out" : "Shop Now"}
+ *       {isComingSoon ? "Coming soon" : isSoldOut ? "Sold out" : "Shop Now"}
  *     </Button>
  *   );
  * }
  * ```
  *
- * @returns Object containing the buyNow function
+ * @returns Object containing the buyNow function and whether checkout can take payments
  */
-export declare function useBuyNow(): {
+export declare function useBuyNow({ catalog, }?: {
+    /** The catalog this control sells from, so `checkoutAvailability` can say whether this site's checkout sells it. */
+    catalog?: CheckoutCatalog | null;
+}): {
     buyNow: (variants: VariantBuyNowInfo[], options?: {
         discountCodes?: string[];
         /** Order-level Shopify cart attributes, including experiment attribution. */
@@ -87,4 +98,5 @@ export declare function useBuyNow(): {
             value: string;
         }[];
     }) => Promise<BuyNowOutcome>;
+    checkoutAvailability: import("./use-checkout-availability").CheckoutAvailability;
 };

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

@@ -5,6 +5,7 @@ import { CanopyError } from "../../lib/canopy-error";
 import { navigateExternal } from "../../lib/external-navigation";
 import { buyNowWithRecoveryAction } from "../buy-now-action";
 import { CartCountryContext } from "../cart-country-context";
+import { useCheckoutAvailability } from "./use-checkout-availability";
 const REPLO_LOCAL_STORAGE_SESSION_KEY = "_replo_sid";
 const REPLO_SESSION_ID_KEY = "rsid";
 const REPLO_CLIENT_ID_KEY = "rclid";
@@ -13,8 +14,11 @@ class ProductHasNoVariantsError extends CanopyError {
 class CheckoutAttemptError extends CanopyError {
 }
 const checkoutAttempts = /* @__PURE__ */ new Map();
-function useBuyNow() {
+function useBuyNow({
+  catalog = null
+} = {}) {
   const country = React.useContext(CartCountryContext);
+  const checkoutAvailability = useCheckoutAvailability({ catalog });
   const reploSessionString = useClientValue(
     () => localStorage.getItem(REPLO_LOCAL_STORAGE_SESSION_KEY),
     null
@@ -88,7 +92,7 @@ function useBuyNow() {
     },
     [reploSessionString, country]
   );
-  return { buyNow };
+  return { buyNow, checkoutAvailability };
 }
 export {
   useBuyNow

package/cart/hooks/use-checkout-availability.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether shoppers can check out on this site right now. `"checking"` while
+ * the store's payments are being confirmed; buy controls stay usable then, so
+ * a store that can sell never flashes an unavailable state.
+ */
+export type CheckoutAvailability = "checking" | "available" | "unavailable";
+/**
+ * Which catalog a buy control sells from: `"shopify"` for Shopify loader
+ * output, `"replo"` for Replo products. Shopify checkout can't sell Replo
+ * products and Replo checkout can't sell Shopify ones.
+ */
+export type CheckoutCatalog = "shopify" | "replo";
+/**
+ * Replo checkout can only sell once the store's payments are set up, which
+ * can finish or lapse long after a publish, so it is read live. Shopify
+ * checkout is the store's own and is treated as available. Without a
+ * `catalog` only the site's checkout is judged, as before the option existed.
+ */
+export declare function useCheckoutAvailability({ catalog, }: {
+    catalog: CheckoutCatalog | null;
+}): CheckoutAvailability;

package/cart/hooks/use-checkout-availability.js

@@ -0,0 +1,71 @@
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import { CanopyError } from "../../lib/canopy-error";
+import { useCanopyClientConfig } from "../../providers/canopy-client-config";
+class CheckoutAvailabilityError extends CanopyError {
+}
+const CHECKOUT_AVAILABILITY_STALE_MS = 6e4;
+async function fetchCanAcceptPayments(config) {
+  const response = await fetch(
+    `${config.canopyApiBaseUrl}/api/v1/stripe-checkout/availability`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ projectId: config.projectId })
+    }
+  );
+  if (!response.ok) {
+    throw new CheckoutAvailabilityError({
+      message: `Checkout availability check failed with status ${response.status}`
+    });
+  }
+  const body = await response.json();
+  if (typeof body !== "object" || body === null || !("canAcceptPayments" in body) || typeof body.canAcceptPayments !== "boolean") {
+    throw new CheckoutAvailabilityError({
+      message: "Checkout availability check returned an unexpected response"
+    });
+  }
+  return body.canAcceptPayments;
+}
+function useCheckoutAvailability({
+  catalog
+}) {
+  const config = useCanopyClientConfig();
+  const checkoutProvider = config?.checkoutProvider ?? null;
+  const query = useQuery({
+    queryKey: ["replo", "checkout-availability", config?.projectId ?? null],
+    queryFn: () => {
+      if (!config) {
+        throw new CheckoutAvailabilityError({
+          message: "This site has no canopy-api config"
+        });
+      }
+      return fetchCanAcceptPayments(config);
+    },
+    enabled: checkoutProvider === "stripe" && catalog !== "shopify",
+    staleTime: CHECKOUT_AVAILABILITY_STALE_MS,
+    retry: 1
+  });
+  if (checkoutProvider === null) {
+    return "available";
+  }
+  if (checkoutProvider === "none") {
+    return "unavailable";
+  }
+  if (checkoutProvider === "shopify") {
+    return catalog === "replo" ? "unavailable" : "available";
+  }
+  if (catalog === "shopify") {
+    return "unavailable";
+  }
+  if (query.isPending) {
+    return "checking";
+  }
+  if (query.isError) {
+    return "available";
+  }
+  return query.data ? "available" : "unavailable";
+}
+export {
+  useCheckoutAvailability
+};

package/lib/buildMetadata.js

@@ -1,7 +1,7 @@
 export const BUILD_METADATA = {
   "packageName": "@replohq/sdk",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "branch": "HEAD",
-  "commit": "377fd6358bd4e3d0d32ff03942701a9cede4e0e9",
-  "builtAt": "2026-11-06T19:28:13.532Z"
+  "commit": "20365c00f7144702c4a7438ac5d907dc97b5b62a",
+  "builtAt": "2026-11-06T20:15:11.914Z"
 };

package/loaders/integration-loader-schemas.d.ts

@@ -210,6 +210,7 @@ export declare const rebuyRecommendationsOutputSchema: z.ZodObject<{
                 previewUrl: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>], "kind">>>;
         }, z.core.$strip>>>;
+        externalCheckoutUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const smileEarningRuleSchema: z.ZodObject<{

package/loaders/loader-schemas.d.ts

@@ -389,6 +389,7 @@ export declare const productSchema: z.ZodObject<{
             previewUrl: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>], "kind">>>;
     }, z.core.$strip>>>;
+    externalCheckoutUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type Product = z.infer<typeof productSchema>;
 export declare const okendoReviewMediaSchema: z.ZodObject<{
@@ -640,6 +641,7 @@ export declare const fullProductSchema: z.ZodObject<{
             previewUrl: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>], "kind">>>;
     }, z.core.$strip>>;
+    externalCheckoutUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export declare const fullCollectionSchema: z.ZodObject<{
     id: z.ZodString;
@@ -834,6 +836,7 @@ export declare const paginatedProductsSchema: z.ZodObject<{
                 previewUrl: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>], "kind">>>;
         }, z.core.$strip>>>;
+        externalCheckoutUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
     pageInfo: z.ZodObject<{
         hasNextPage: z.ZodBoolean;

package/loaders/loader-schemas.js

@@ -145,7 +145,8 @@ const productSchema = z.object({
   tags: z.array(z.string()).optional(),
   sellingPlanGroups: z.array(sellingPlanGroupSchema).optional(),
   requiresSellingPlan: z.boolean().optional(),
-  metafields: z.array(metafieldSchema).optional()
+  metafields: z.array(metafieldSchema).optional(),
+  externalCheckoutUrl: z.string().nullish()
 });
 const okendoReviewMediaSchema = z.object({
   type: z.string().describe('Okendo media type, e.g. "image" or "video"'),
@@ -216,7 +217,8 @@ const fullProductSchema = z.object({
   tags: z.array(z.string()),
   sellingPlanGroups: z.array(sellingPlanGroupSchema),
   requiresSellingPlan: productSchema.shape.requiresSellingPlan,
-  metafields: z.array(metafieldSchema)
+  metafields: z.array(metafieldSchema),
+  externalCheckoutUrl: productSchema.shape.externalCheckoutUrl
 });
 const fullCollectionSchema = z.object({
   id: z.string(),

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@replohq/sdk",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "reploBuild": {
     "packageName": "@replohq/sdk",
-    "version": "2.19.0",
+    "version": "2.20.0",
     "branch": "HEAD",
-    "commit": "377fd6358bd4e3d0d32ff03942701a9cede4e0e9",
-    "builtAt": "2026-11-06T19:28:13.532Z"
+    "commit": "20365c00f7144702c4a7438ac5d907dc97b5b62a",
+    "builtAt": "2026-11-06T20:15:11.914Z"
   },
   "description": "Replo SDK — cart, analytics, and data loaders for agent-built Next.js sites.",
   "license": "SEE LICENSE IN LICENSE",

package/providers/canopy-client-config.d.ts

@@ -1,3 +1,4 @@
+import type { CheckoutProvider } from "../lib/integration-utils";
 import React from "react";
 /**
  * What browser code needs to call canopy-api directly. Resolved from the worker
@@ -7,6 +8,7 @@ import React from "react";
 export type CanopyClientConfig = {
     canopyApiBaseUrl: string;
     projectId: string;
+    checkoutProvider: CheckoutProvider;
 };
 export declare function CanopyClientConfigProvider({ config, children, }: React.PropsWithChildren<{
     config: CanopyClientConfig | null;

package/providers/replo-provider.js

@@ -19,7 +19,8 @@ async function ReploProvider({
     checkoutProvider = env.CHECKOUT_PROVIDER ?? "none";
     canopyClientConfig = {
       canopyApiBaseUrl: buildBaseUrl(env.CANOPY_API_HOST),
-      projectId: env.PROJECT_ID
+      projectId: env.PROJECT_ID,
+      checkoutProvider
     };
   } catch {
     checkoutProvider = "none";