@replohq/sdk 1.12.0 → 1.13.1

package/_vendor/replo-utils/lib/errors.d.ts

@@ -80,4 +80,5 @@ export declare function isNetworkErrorMessage(message: string): boolean;
  * fallback string or `String(error)`.
  */
 export declare function getErrorMessage(error: unknown, fallback?: string): string;
+export declare function appendErrorId(detail: string, errorId: string | null | undefined): string;
 export {};

package/_vendor/schemas/errors.d.ts

@@ -436,6 +436,12 @@ export declare class IframeRpcChannelTimeoutError extends IframeRpcChannelError
         timeoutMs: number;
     });
 }
+export declare class IframeRpcChannelTargetUnavailableError extends IframeRpcChannelError {
+    constructor({ callType, method, }: {
+        callType: "notify" | "request" | "response";
+        method?: string;
+    });
+}
 export declare class IframeRpcChannelRemoteError extends IframeRpcChannelError {
     constructor({ method, message }: {
         method: string;

package/cart/cart-actions.d.ts

@@ -1,13 +1,6 @@
 import type { StorefrontCountryCode } from "../loaders/markets";
-import type { AddToCartPayload, Cart, CartLinePayload, RemoveFromCartPayload, UpdateCartLineItemPayload } from "./cart-types";
-/**
- * Gets the existing cart or creates a new one if none exists. This is necessary
- * because we may not have cookies in the server context during initial load.
- *
- * See: https://nextjs.org/docs/app/api-reference/functions/cookies#understanding-cookie-behavior-in-server-components
- *
- * @returns The existing cart or a newly created cart
- */
+import type { AddToCartPayload, Cart, CartLineAttribute, CartLinePayload, RemoveFromCartPayload, UpdateCartLineItemPayload } from "./cart-types";
+/** Gets the existing cart or creates a new one if none exists. */
 export declare function getOrCreateCartAction(options?: {
     country?: StorefrontCountryCode;
 }): Promise<Cart | null>;
@@ -73,3 +66,19 @@ export declare function removeCartLineItemsAction(lineIds: RemoveFromCartPayload
  * @returns The updated cart
  */
 export declare function updateCartDiscountCodesAction(discountCodes: string[], cartId: string): Promise<Cart | null>;
+/**
+ * Sets the order-level note on a cart. Pass an empty string to clear it.
+ *
+ * @param note - The note text
+ * @param cartId - The ID of the cart to update
+ * @returns The updated cart
+ */
+export declare function updateCartNoteAction(note: string, cartId: string): Promise<Cart | null>;
+/**
+ * Replaces the order-level attributes on a cart.
+ *
+ * @param attributes - The full attribute list to store on the cart
+ * @param cartId - The ID of the cart to update
+ * @returns The updated cart
+ */
+export declare function replaceCartAttributesAction(attributes: CartLineAttribute[], cartId: string): Promise<Cart | null>;

package/cart/cart-actions.js

@@ -108,6 +108,14 @@ async function updateCartDiscountCodesAction(discountCodes, cartId) {
   const cartGateway = await getCartGateway();
   return await cartGateway.updateCartDiscountCodes({ discountCodes, cartId });
 }
+async function updateCartNoteAction(note, cartId) {
+  const cartGateway = await getCartGateway();
+  return await cartGateway.updateCartNote({ note, cartId });
+}
+async function replaceCartAttributesAction(attributes, cartId) {
+  const cartGateway = await getCartGateway();
+  return await cartGateway.replaceCartAttributes({ attributes, cartId });
+}
 export {
   addToCartAction,
   createCartAction,
@@ -115,6 +123,8 @@ export {
   getOrCreateCartAction,
   reconcileCartAction,
   removeCartLineItemsAction,
+  replaceCartAttributesAction,
   updateCartDiscountCodesAction,
-  updateCartLineItemAction
+  updateCartLineItemAction,
+  updateCartNoteAction
 };

package/cart/cart-provider.d.ts

@@ -1,7 +1,7 @@
 import type { StorefrontCountryCode } from "../loaders/markets";
-import type { Cart, CartLine, CartLineAdjustment, CartLinePayload } from "./cart-types";
+import type { Cart, CartLine, CartLineAdjustment, CartLineAttribute, CartLinePayload } from "./cart-types";
 import React from "react";
-export type CartOperation = "add" | "update" | "remove" | "discount";
+export type CartOperation = "add" | "update" | "remove" | "discount" | "note" | "attributes";
 /**
  * The most recent cart change that could not be saved. `message` is written
  * for the shopper, so a cart UI can render it as-is next to a retry.
@@ -39,6 +39,10 @@ export interface CartContextTypeInternal {
     removeCartItem: (lineId: string) => Promise<void>;
     /** Function to update discount codes on cart */
     updateDiscountCodes: (discountCodes: string[]) => Promise<void>;
+    /** Function to set the order-level cart note (empty string clears it) */
+    updateNote: (note: string) => Promise<void>;
+    /** Function to replace the order-level cart attributes */
+    replaceAttributes: (attributes: CartLineAttribute[]) => Promise<void>;
     /** Re-read the persisted cart and adopt it if no mutations are in flight */
     refreshCart: () => Promise<void>;
     /** Function to create cart and checkout immediately */
@@ -72,6 +76,24 @@ export interface CartContextType {
     closeCart: () => void;
     /** Function to update discount codes on cart */
     updateDiscountCodes: (discountCodes: string[]) => Promise<void>;
+    /**
+     * Set the order-level cart note (Shopify `cart.note`, the "special
+     * instructions" field on the order). Pass an empty string to clear it.
+     * Each call is one Shopify mutation: save on blur or after the shopper
+     * stops typing, never on every keystroke. Shopify checkout only; on Replo
+     * Products (Stripe) sites the note is kept on the cart but is not
+     * forwarded to the order.
+     */
+    updateNote: (note: string) => Promise<void>;
+    /**
+     * Replace the order-level cart attributes (Shopify `cart.attributes`), the
+     * key/value pairs gift-message and fulfillment apps read off the order.
+     * These are distinct from per-line `properties`. The full list is replaced
+     * on every call, so a key left out is removed; values are stored as
+     * strings. Shopify checkout only; on Replo Products (Stripe) sites the
+     * attributes are kept on the cart but are not forwarded to the order.
+     */
+    replaceAttributes: (attributes: CartLineAttribute[]) => Promise<void>;
     /**
      * Re-read the persisted cart and adopt it if no mutations are in flight.
      * Call after something outside the provider rewrote the cart — e.g. the

package/cart/cart-provider.js

@@ -10,8 +10,10 @@ import {
   getOrCreateCartAction,
   reconcileCartAction,
   removeCartLineItemsAction,
+  replaceCartAttributesAction,
   updateCartDiscountCodesAction,
-  updateCartLineItemAction
+  updateCartLineItemAction,
+  updateCartNoteAction
 } from "./cart-actions";
 import { CartCountryContext } from "./cart-country-context";
 import { useShouldReconcileSuppliedCart } from "./supplied-cart-reconciliation";
@@ -26,8 +28,25 @@ import {
 import { CartContextError, toCartError } from "./utils/cart-error";
 import { recalculateCartCost } from "./utils/cart-utils";
 import { createOptimisticSellingPlanAllocation } from "./utils/variant-to-cart-line";
+let cartLoadPromise = null;
+let cartLoadCountry;
 let cartCreationPromise = null;
 let cartCreationCountry;
+function getSharedReconciledCart(country) {
+  if (cartLoadPromise && cartLoadCountry === country) {
+    return cartLoadPromise;
+  }
+  const previousLoad = cartLoadPromise;
+  const load = (async () => {
+    if (previousLoad) await previousLoad.catch(() => null);
+    return await reconcileCartAction({ country });
+  })().finally(() => {
+    if (cartLoadPromise === load) cartLoadPromise = null;
+  });
+  cartLoadCountry = country;
+  cartLoadPromise = load;
+  return load;
+}
 function getOrCreateSharedCart(country) {
   if (cartCreationPromise && cartCreationCountry === country) {
     return cartCreationPromise;
@@ -159,6 +178,7 @@ function CartProvider({
   const mutationQueue = React.useRef(Promise.resolve());
   const pendingMutations = React.useRef(0);
   const optimisticLines = React.useRef(/* @__PURE__ */ new Map());
+  const cartInitialization = React.useRef(null);
   const lastReconciliationCountry = React.useRef(false);
   const startSuppliedCartReconciliation = React.useCallback(() => {
     if (!shouldReconcileSuppliedCart || lastReconciliationCountry.current === country) {
@@ -185,6 +205,7 @@ function CartProvider({
       startSuppliedCartReconciliation();
       pendingMutations.current += 1;
       const request = mutationQueue.current.then(async () => {
+        await cartLoadPromise?.catch(() => null);
         await cartCreationPromise?.catch(() => null);
         if (needsRefresh.current) {
           const restoredCart = await getCartAction();
@@ -244,34 +265,59 @@ function CartProvider({
     },
     []
   );
-  const initializeCart = React.useCallback(async () => {
+  const reconcilePersistedCart = React.useCallback(() => {
+    const currentInitialization = cartInitialization.current;
+    if (currentInitialization && currentInitialization.country === country) {
+      return currentInitialization.promise;
+    }
+    const selection = marketSelection.current;
+    const initialization = (async () => {
+      const loadedCart = await getSharedReconciledCart(country);
+      if (!isMounted.current || marketSelection.current !== selection) {
+        throw new DOMException(
+          "Cart initialization was superseded",
+          "AbortError"
+        );
+      }
+      serverCart.current = loadedCart;
+      if (pendingMutations.current === 0) updateCartData(loadedCart);
+      return loadedCart;
+    })();
+    cartInitialization.current = { country, promise: initialization };
+    void initialization.catch(() => {
+      if (cartInitialization.current?.promise === initialization) {
+        cartInitialization.current = null;
+      }
+    });
+    return initialization;
+  }, [country, updateCartData]);
+  const getOrCreateCartForMutation = React.useCallback(async () => {
+    const loadedCart = await reconcilePersistedCart();
+    if (loadedCart) return loadedCart;
     const selection = marketSelection.current;
-    const loadedCart = await getOrCreateSharedCart(country);
+    const createdCart = await getOrCreateSharedCart(country);
     if (!isMounted.current || marketSelection.current !== selection) {
-      throw new DOMException(
-        "Cart initialization was superseded",
-        "AbortError"
-      );
+      throw new DOMException("Cart creation was superseded", "AbortError");
     }
-    serverCart.current = loadedCart;
-    if (pendingMutations.current === 0) updateCartData(loadedCart);
-    return loadedCart;
-  }, [country, updateCartData]);
+    serverCart.current = createdCart;
+    if (pendingMutations.current === 0) updateCartData(createdCart);
+    return createdCart;
+  }, [country, reconcilePersistedCart, updateCartData]);
   React.useEffect(() => {
     isMounted.current = true;
     if (isSuppliedCart) {
       startSuppliedCartReconciliation();
     } else {
-      void initializeCart().catch((error2) => {
+      void reconcilePersistedCart().catch((error2) => {
         if (isMounted.current && !(error2 instanceof DOMException && error2.name === "AbortError")) {
-          console.error("[Replo] Error getting or creating cart:", error2);
+          console.error("[Replo] Error loading cart:", error2);
         }
       });
     }
     return () => {
       isMounted.current = false;
     };
-  }, [initializeCart, isSuppliedCart, startSuppliedCartReconciliation]);
+  }, [isSuppliedCart, reconcilePersistedCart, startSuppliedCartReconciliation]);
   const subtotal = cartData?.lines.reduce((sum, lineItem) => {
     if (lineItem.quantity > 0 && lineItem.merchandise) {
       sum += lineItem.merchandise.price * lineItem.quantity;
@@ -311,7 +357,7 @@ function CartProvider({
   const addToCart = React.useCallback(
     (lines, openCartAfterAdd = true) => {
       return runWithErrorState("add", async () => {
-        const readyCart = cartData ?? serverCart.current ?? await initializeCart().catch((caught) => {
+        const readyCart = cartData ?? serverCart.current ?? await getOrCreateCartForMutation().catch((caught) => {
           if (openCartAfterAdd) setIsCartOpen(true);
           throw caught;
         });
@@ -371,7 +417,7 @@ function CartProvider({
       cartData,
       emitCartView,
       enqueueMutation,
-      initializeCart,
+      getOrCreateCartForMutation,
       runWithErrorState,
       updateCartData
     ]
@@ -379,13 +425,14 @@ function CartProvider({
   const updateCartItem = React.useCallback(
     (line) => {
       return runWithErrorState("update", async () => {
-        if (!cartData) {
+        const readyCart = cartData ?? serverCart.current ?? await reconcilePersistedCart();
+        if (!readyCart) {
           console.warn(
             "[Replo] Cannot update cart item: no cart exists. Reach out to support@replo.app if this persists."
           );
           return { adjustments: [] };
         }
-        const currentLine = cartData.lines.find((item) => item.id === line.id);
+        const currentLine = readyCart.lines.find((item) => item.id === line.id);
         const merchandise = currentLine?.merchandise ?? line.merchandise;
         const quantityDelta = line.quantity - (reportedLineQuantities.current.get(line.id) ?? currentLine?.quantity ?? 0);
         reportedLineQuantities.current.set(line.id, line.quantity);
@@ -393,15 +440,12 @@ function CartProvider({
           const data = buildCartLineAnalyticsData({
             merchandise,
             quantity: Math.abs(quantityDelta),
-            currencyCode: cartData.cost.currencyCode
+            currencyCode: readyCart.cost.currencyCode
           });
           void (quantityDelta > 0 ? analytics.addToCart({ data }) : analytics.removeFromCart({ data }));
         }
         updateCartData((currentCart) => {
-          if (!currentCart) {
-            return null;
-          }
-          return updateLineInCart(currentCart, line);
+          return updateLineInCart(currentCart ?? readyCart, line);
         });
         const adjustments = [];
         await enqueueMutation(async (currentCart) => {
@@ -438,6 +482,7 @@ function CartProvider({
       cartData,
       enqueueMutation,
       findLine,
+      reconcilePersistedCart,
       runWithErrorState,
       updateCartData
     ]
@@ -445,28 +490,26 @@ function CartProvider({
   const removeCartItem = React.useCallback(
     (lineId) => {
       return runWithErrorState("remove", async () => {
-        if (!cartData) {
+        const readyCart = cartData ?? serverCart.current ?? await reconcilePersistedCart();
+        if (!readyCart) {
           console.warn(
             "[Replo] Cannot remove cart item: no cart exists. Reach out to support@replo.app if this persists."
           );
           return;
         }
-        const itemToRemove = cartData.lines.find((item) => item.id === lineId);
+        const itemToRemove = readyCart.lines.find((item) => item.id === lineId);
         reportedLineQuantities.current.delete(lineId);
         if (analytics && itemToRemove && itemToRemove.merchandise) {
           void analytics.removeFromCart({
             data: buildCartLineAnalyticsData({
               merchandise: itemToRemove.merchandise,
               quantity: itemToRemove.quantity,
-              currencyCode: cartData.cost.currencyCode
+              currencyCode: readyCart.cost.currencyCode
             })
           });
         }
         updateCartData((currentCart) => {
-          if (!currentCart) {
-            return null;
-          }
-          return removeLineFromCart(currentCart, lineId);
+          return removeLineFromCart(currentCart ?? readyCart, lineId);
         });
         await enqueueMutation(async (currentCart) => {
           const savedLine = findLine({
@@ -483,36 +526,67 @@ function CartProvider({
       cartData,
       enqueueMutation,
       findLine,
+      reconcilePersistedCart,
       runWithErrorState,
       updateCartData
     ]
   );
-  const updateDiscountCodes = React.useCallback(
-    (discountCodes) => {
-      return runWithErrorState("discount", async () => {
-        const readyCart = cartData ?? serverCart.current ?? await initializeCart();
-        updateCartData((currentCart) => {
-          return {
-            ...currentCart ?? readyCart,
-            discountCodes: discountCodes.map((code) => ({
-              code,
-              applicable: true
-            }))
-          };
-        });
-        await enqueueMutation((currentCart) => {
-          return updateCartDiscountCodesAction(discountCodes, currentCart.id);
-        });
+  const updateCartField = React.useCallback(
+    (operation, patch, save) => {
+      return runWithErrorState(operation, async () => {
+        const readyCart = cartData ?? serverCart.current ?? await getOrCreateCartForMutation();
+        updateCartData((currentCart) => ({
+          ...currentCart ?? readyCart,
+          ...patch
+        }));
+        await enqueueMutation((currentCart) => save(currentCart.id));
       });
     },
     [
       cartData,
       enqueueMutation,
-      initializeCart,
+      getOrCreateCartForMutation,
       runWithErrorState,
       updateCartData
     ]
   );
+  const updateDiscountCodes = React.useCallback(
+    (discountCodes) => {
+      return updateCartField(
+        "discount",
+        {
+          discountCodes: discountCodes.map((code) => ({
+            code,
+            applicable: true
+          }))
+        },
+        (cartId) => updateCartDiscountCodesAction(discountCodes, cartId)
+      );
+    },
+    [updateCartField]
+  );
+  const updateNote = React.useCallback(
+    (note) => {
+      return updateCartField("note", { note }, (cartId) => {
+        return updateCartNoteAction(note, cartId);
+      });
+    },
+    [updateCartField]
+  );
+  const replaceAttributes = React.useCallback(
+    (attributes) => {
+      const stringAttributes = attributes.map((attribute) => ({
+        key: attribute.key,
+        value: String(attribute.value)
+      }));
+      return updateCartField(
+        "attributes",
+        { attributes: stringAttributes },
+        (cartId) => replaceCartAttributesAction(stringAttributes, cartId)
+      );
+    },
+    [updateCartField]
+  );
   const buyNow = React.useCallback(
     (lines, discountCodes) => {
       return createBuyNowCart({ lines, discountCodes, country });
@@ -530,6 +604,8 @@ function CartProvider({
       updateCartItem,
       removeCartItem,
       updateDiscountCodes,
+      updateNote,
+      replaceAttributes,
       refreshCart,
       buyNow,
       checkoutUrl: cartData?.checkoutUrl ?? "/",
@@ -552,8 +628,10 @@ function CartProvider({
       refreshCart,
       removeCartItem,
       subtotal,
+      replaceAttributes,
       updateCartItem,
-      updateDiscountCodes
+      updateDiscountCodes,
+      updateNote
     ]
   );
   return /* @__PURE__ */ jsx(CartCountryContext.Provider, { value: country, children: /* @__PURE__ */ jsx(CartContext.Provider, { value: contextValue, children }) });
@@ -580,6 +658,8 @@ function useCart() {
     openCart: context.openCart,
     closeCart: context.closeCart,
     updateDiscountCodes: context.updateDiscountCodes,
+    updateNote: context.updateNote,
+    replaceAttributes: context.replaceAttributes,
     refreshCart: context.refreshCart,
     error: context.error,
     clearError: context.clearError

package/cart/cart-schema.d.ts

@@ -77,6 +77,11 @@ export declare const cartSchema: z.ZodObject<{
     buyerIdentity: z.ZodOptional<z.ZodObject<{
         country: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
+    note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    attributes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const clientCartSchema: z.ZodObject<{
     id: z.ZodString;
@@ -97,6 +102,11 @@ export declare const clientCartSchema: z.ZodObject<{
     buyerIdentity: z.ZodOptional<z.ZodObject<{
         country: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
+    note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    attributes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strip>>>;
     lines: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         quantity: z.ZodNumber;

package/cart/cart-schema.js

@@ -67,7 +67,9 @@ const cartSchema = z.object({
   checkoutUrl: z.string().optional(),
   discountCodes: z.array(cartDiscountCodeSchema).optional(),
   discountAllocations: z.array(cartDiscountAllocationSchema).optional(),
-  buyerIdentity: z.object({ country: z.string().nullable() }).optional()
+  buyerIdentity: z.object({ country: z.string().nullable() }).optional(),
+  note: z.string().nullish(),
+  attributes: z.array(cartLineAttributeSchema).optional()
 });
 const clientCartSchema = cartSchema.extend({
   lines: z.array(

package/cart/cart-types.d.ts

@@ -127,6 +127,10 @@ export interface Cart {
     buyerIdentity?: {
         country: string | null;
     };
+    /** Order-level note the shopper attached to the cart (Shopify `cart.note`) */
+    note?: string | null;
+    /** Order-level attributes (Shopify `cart.attributes`), distinct from line properties */
+    attributes?: CartLineAttribute[];
 }
 /**
  * How a cart write differed from what the shopper asked for, derived by
@@ -166,6 +170,14 @@ export interface UpdateCartDiscountCodesPayload {
     cartId: string;
     discountCodes: string[];
 }
+export interface UpdateCartNotePayload {
+    cartId: string;
+    note: string;
+}
+export interface ReplaceCartAttributesPayload {
+    cartId: string;
+    attributes: CartLineAttribute[];
+}
 export interface CartBuyerIdentity {
     country: StorefrontCountryCode;
 }

package/cart/gateways/cart-gateway.d.ts

@@ -1,4 +1,4 @@
-import type { AddToCartPayload, Cart, CartBuyerIdentity, CartLinePayload, RemoveFromCartPayload, UpdateCartDiscountCodesPayload, UpdateCartLineItemPayload } from "../cart-types";
+import type { AddToCartPayload, Cart, CartBuyerIdentity, CartLinePayload, RemoveFromCartPayload, ReplaceCartAttributesPayload, UpdateCartDiscountCodesPayload, UpdateCartLineItemPayload, UpdateCartNotePayload } from "../cart-types";
 export interface CartGateway {
     getCart(cartId: string): Promise<Cart | null>;
     /**
@@ -21,5 +21,7 @@ export interface CartGateway {
     updateCartLineItem(cartPayload: UpdateCartLineItemPayload): Promise<Cart | null>;
     removeCartLineItems(cartPayload: RemoveFromCartPayload): Promise<Cart | null>;
     updateCartDiscountCodes(cartPayload: UpdateCartDiscountCodesPayload): Promise<Cart | null>;
+    updateCartNote(cartPayload: UpdateCartNotePayload): Promise<Cart | null>;
+    replaceCartAttributes(cartPayload: ReplaceCartAttributesPayload): Promise<Cart | null>;
 }
 export declare function getCartGateway(): Promise<CartGateway>;

package/cart/gateways/cookie-cart-gateway.d.ts

@@ -1,5 +1,5 @@
 import type { ReconciledCartLine } from "../../gateways/canopy-api";
-import type { AddToCartPayload, Cart, CartBuyerIdentity, CartLinePayload, RemoveFromCartPayload, UpdateCartDiscountCodesPayload, UpdateCartLineItemPayload } from "../cart-types";
+import type { AddToCartPayload, Cart, CartBuyerIdentity, CartLinePayload, RemoveFromCartPayload, ReplaceCartAttributesPayload, UpdateCartDiscountCodesPayload, UpdateCartLineItemPayload, UpdateCartNotePayload } from "../cart-types";
 import type { LineMergeFn } from "../utils/cookie-cart-persistence";
 import type { CartGateway } from "./cart-gateway";
 /**
@@ -41,5 +41,8 @@ export declare abstract class CookieBasedCartGateway implements CartGateway {
         cartId: string;
         buyerIdentity: CartBuyerIdentity;
     }): Promise<Cart | null>;
+    updateCartNote({ cartId, note, }: UpdateCartNotePayload): Promise<Cart | null>;
+    replaceCartAttributes({ cartId, attributes, }: ReplaceCartAttributesPayload): Promise<Cart | null>;
+    private patchCart;
 }
 export {};

package/cart/gateways/cookie-cart-gateway.js

@@ -5,6 +5,7 @@ import {
   loadCartFromCookie,
   removeCartLineItemsWithPersistence,
   saveCartToCookie,
+  updateCartInCookie,
   updateCartLineItemWithPersistence
 } from "../utils/cookie-cart-persistence";
 class CookieBasedCartGateway {
@@ -156,6 +157,45 @@ class CookieBasedCartGateway {
   }) {
     return this.getCart(cartId);
   }
+  async updateCartNote({
+    cartId,
+    note
+  }) {
+    return this.patchCart(cartId, { note });
+  }
+  async replaceCartAttributes({
+    cartId,
+    attributes
+  }) {
+    return this.patchCart(cartId, {
+      attributes: attributes.map((attribute) => ({
+        key: attribute.key,
+        value: String(attribute.value)
+      }))
+    });
+  }
+  async patchCart(cartId, patch) {
+    console.warn(
+      `${this.config.gatewayName} cart gateway keeps cart note/attributes on the cart but does not forward them to checkout`
+    );
+    try {
+      return await updateCartInCookie(
+        cartId,
+        this.config.cookieName,
+        (cart) => ({
+          ...cart,
+          ...patch
+        })
+      );
+    } catch (error) {
+      console.warn(`Failed to update ${this.config.gatewayName} cart:`, {
+        error: error instanceof Error ? error.message : String(error),
+        cartId,
+        patch
+      });
+      return null;
+    }
+  }
 }
 export {
   CookieBasedCartGateway

package/cart/gateways/resolver-cart-gateway.js

@@ -117,6 +117,33 @@ class ResolverCartGateway {
       return null;
     }
   }
+  async updateCartNote(cartPayload) {
+    try {
+      const gateway = await getCanopyApiGateway();
+      return await gateway.cartUpdateNote({
+        cartId: cartPayload.cartId,
+        note: cartPayload.note
+      });
+    } catch (error) {
+      console.warn("Failed to update cart note via canopy-api:", error);
+      return null;
+    }
+  }
+  async replaceCartAttributes(cartPayload) {
+    try {
+      const gateway = await getCanopyApiGateway();
+      return await gateway.cartReplaceAttributes({
+        cartId: cartPayload.cartId,
+        attributes: cartPayload.attributes.map((attribute) => ({
+          key: attribute.key,
+          value: String(attribute.value)
+        }))
+      });
+    } catch (error) {
+      console.warn("Failed to update cart attributes via canopy-api:", error);
+      return null;
+    }
+  }
 }
 async function createResolverCartGateway() {
   return new ResolverCartGateway();

package/cart/utils/cart-error.js

@@ -5,7 +5,9 @@ const FALLBACK_MESSAGES = {
   add: "Could not add to your cart. Please try again.",
   update: "Could not update your cart. Please try again.",
   remove: "Could not remove that item. Please try again.",
-  discount: "Could not apply that discount. Please try again."
+  discount: "Could not apply that discount. Please try again.",
+  note: "Could not save your note. Please try again.",
+  attributes: "Could not save your cart details. Please try again."
 };
 function toCartError(operation, caught) {
   return {

package/gateways/canopy-api.d.ts

@@ -110,6 +110,17 @@ declare class CanopyApiGateway {
         cartId: string;
         country: StorefrontCountryCode;
     }): Promise<Cart>;
+    cartUpdateNote({ cartId, note, }: {
+        cartId: string;
+        note: string;
+    }): Promise<Cart>;
+    cartReplaceAttributes({ cartId, attributes, }: {
+        cartId: string;
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+    }): Promise<Cart>;
 }
 export declare function getCanopyApiGateway(): Promise<CanopyApiGateway>;
 export {};

package/gateways/canopy-api.js

@@ -228,6 +228,18 @@ If you're running locally, make sure the canopy-api cloudflare worker is running
   }) {
     return this._cartPost("/update-buyer-identity", { cartId, country });
   }
+  async cartUpdateNote({
+    cartId,
+    note
+  }) {
+    return this._cartPost("/update-note", { cartId, note });
+  }
+  async cartReplaceAttributes({
+    cartId,
+    attributes
+  }) {
+    return this._cartPost("/replace-attributes", { cartId, attributes });
+  }
 }
 async function getCanopyApiGateway() {
   return CanopyApiGateway.setup();

package/lib/buildMetadata.js

@@ -1,7 +1,7 @@
 export const BUILD_METADATA = {
   "packageName": "@replohq/sdk",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "branch": "HEAD",
-  "commit": "3d57d078085b1361b40fd9feb54651a1fca5a985",
-  "builtAt": "2026-09-22T02:12:30.362Z"
+  "commit": "60a5a41bd113ba1be5e99d2726cc080d3e6015f0",
+  "builtAt": "2026-09-22T21:16:06.717Z"
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@replohq/sdk",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "reploBuild": {
     "packageName": "@replohq/sdk",
-    "version": "1.12.0",
+    "version": "1.13.1",
     "branch": "HEAD",
-    "commit": "3d57d078085b1361b40fd9feb54651a1fca5a985",
-    "builtAt": "2026-09-22T02:12:30.362Z"
+    "commit": "60a5a41bd113ba1be5e99d2726cc080d3e6015f0",
+    "builtAt": "2026-09-22T21:16:06.717Z"
   },
   "description": "Replo SDK — cart, analytics, and data loaders for agent-built Next.js sites.",
   "license": "SEE LICENSE IN LICENSE",