@rebuy/rebuy-hydrogen 3.0.0-beta.13 → 3.0.0-beta.15

package/README.md

@@ -2,9 +2,20 @@
 
 ## Overview
 
-The new beta version of our Rebuy Hydrogen package is designed to work with both Hydrogen and Hydrogen React versions 2.0. We've streamlined this package to be as plug-and-play as possible, with the package handling most of the work. Below you'll find descriptions of each component and implementation instructions for your application.
+The new beta version of our Rebuy Hydrogen package is designed to work with both Hydrogen and Hydrogen React versions 2.0. We've streamlined this package to be as plug-and-play as possible, with the package handling most of the work.
 
-## Initial Setup
+## Quick Reference
+
+This documentation covers:
+
+- **Installation** - Setup for Hydrogen and Hydrogen React applications
+- **Themed Styles** - Automatic styling integration with your Rebuy admin settings
+- **Components** - WidgetContainer, product recommendations, bundles, and more
+- **Smart Cart** - Advanced cart features including discount codes and subscriptions
+
+---
+
+# 📦 Installation Guide
 
 ### Prerequisites
 
@@ -19,38 +30,36 @@ This distinction is important as different hooks/functions are used in each case
 
 1. Install the beta version of our package from npm:
 
+```bash
+npm i @rebuy/rebuy-hydrogen@3.0.0-beta.15
 ```
-npm i @rebuy/rebuy-hydrogen@3.0.0-beta.13
-```
-
-   Package URL: [https://www.npmjs.com/package/@rebuy/rebuy-hydrogen](https://www.npmjs.com/package/@rebuy/rebuy-hydrogen)
-
 
+Package URL: [https://www.npmjs.com/package/@rebuy/rebuy-hydrogen](https://www.npmjs.com/package/@rebuy/rebuy-hydrogen)
 
-    2\. In your entry.server.tsx add update the creatContentSecurityPolicy to have the [rebuyengine.com](http://rebuyengine.com) in the connectSrc
+2. In your server entry file (typically `app/entry.server.tsx`), update the `createContentSecurityPolicy` to have `rebuyengine.com` in the `connectSrc`.
 
-```
-const {nonce, header, NonceProvider} = createContentSecurityPolicy({
+```typescript
+const { nonce, header, NonceProvider } = createContentSecurityPolicy({
     shop: {
-      checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
-      storeDomain: context.env.PUBLIC_STORE_DOMAIN,
+        checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
+        storeDomain: context.env.PUBLIC_STORE_DOMAIN,
     },
-    connectSrc: ['*.rebuyengine.com', 'rebuyengine.com']
-  });
+    connectSrc: ['*.rebuyengine.com', 'rebuyengine.com'],
+});
 ```
 
-### For Hydrogen-only Applications:
+### For Hydrogen-only Applications
 
-1. Navigate to your `app/root.tsx` file and add the following imports:
+1. Navigate to your root layout file (typically `app/root.tsx`) and add the following imports:
 
-```
+```typescript
 import { RebuyHydrogenContextProvider } from '@rebuy/rebuy-hydrogen';
 import '@rebuy/rebuy-hydrogen/dist/index.css';
 ```
 
-2. Place the `<RebuyHydrogenContextProvider>` component as the parent component after the body. Required props: `cart.data` and `shop(domain) and publicStoreDomain (domain.myshopify.com)`.
+2. Place the `<RebuyHydrogenContextProvider>` component as the parent component after the body. Required props: `cart.data`, `shop` (your store's domain), and `publicStoreDomain` (e.g., "example.myshopify.com").
 
-```
+```typescript
 {data ? (
   <RebuyHydrogenContextProvider cart={data.cart} shop="example.com" publicStoreDomain="example.myshopify.com"
 >
@@ -69,57 +78,109 @@ import '@rebuy/rebuy-hydrogen/dist/index.css';
 )}
 ```
 
-### For Hydrogen React Applications:
+### For Hydrogen React Applications
 
-1. Navigate to your `app/root.tsx` file and add the import for the CSS:
+1. Navigate to your root layout file (typically `app/root.tsx`) and add the import for the CSS:
 
-```
+```typescript
 import '@rebuy/rebuy-hydrogen/dist/index.css';
 ```
 
-2. Navigate to where your context providers are located and wrap the `RebuyHydrogenReactContextProvider` around the children. Required Props: `shop(domain) and publicStoreDomain (domain.myshopify.com)` For Pack Digital users, this would be in `app/context/ContextProvider.tsx`:
+2. Navigate to where your context providers are located and wrap the `RebuyHydrogenReactContextProvider` around the children. Required Props: `publicPrimaryDomain` (your shop's main domain, e.g., "example.com"), `publicStoreDomain` (your Shopify domain, e.g., "example.myshopify.com"), `publicStorefrontToken` (your public storefront API token), and `publicStorefrontId` (your storefront ID). For Pack Digital users, this would typically be in `app/context/ContextProvider.tsx`:
 
-```
-<RebuyHydrogenReactContextProvider publicPrimaryDomian="example.com" publicStoreDomain="example.myshopify.com" publicStorefrontApiToken="1233456" publicStorefrontId="12345678" >
+```typescript
+<RebuyHydrogenReactContextProvider publicPrimaryDomain="example.com" publicStoreDomain="example.myshopify.com" publicStorefrontToken="1233456" publicStorefrontId="12345678" >
   {children}
 </RebuyHydrogenReactContextProvider>
 ```
 
-3. With this you can also pass in any CartProvider props that you need to pass in.
-
-   - # Cart Provider Properties
-
-| Property | Type | Required | Description |
-| :---- | :---- | :---- | :---- |
-| `children` | `React.ReactNode` | Yes | Any `ReactNode` elements. |
-| `numCartLines` | `number` | No | Maximum number of cart lines to fetch. Defaults to 250 cart lines. |
-| `onCreate` | `() => void` | No | A callback that is invoked when the process to create a cart begins, but before the cart is created in the Storefront API. |
-| `onLineAdd` | `() => void` | No | A callback that is invoked when the process to add a line item to the cart begins, but before the line item is added to the Storefront API. |
-| `onLineRemove` | `() => void` | No | A callback that is invoked when the process to remove a line item to the cart begins, but before the line item is removed from the Storefront API. |
-| `onLineUpdate` | `() => void` | No | A callback that is invoked when the process to update a line item in the cart begins, but before the line item is updated in the Storefront API. |
-| `onNoteUpdate` | `() => void` | No | A callback that is invoked when the process to add or update a note in the cart begins, but before the note is added or updated in the Storefront API. |
-| `onBuyerIdentityUpdate` | `() => void` | No | A callback that is invoked when the process to update the buyer identity begins, but before the buyer identity is updated in the Storefront API. |
-| `onAttributesUpdate` | `() => void` | No | A callback that is invoked when the process to update the cart attributes begins, but before the attributes are updated in the Storefront API. |
-| `onDiscountCodesUpdate` | `() => void` | No | A callback that is invoked when the process to update the cart discount codes begins, but before the discount codes are updated in the Storefront API. |
-| `onCreateComplete` | `() => void` | No | A callback that is invoked when the process to create a cart completes. |
-| `onLineAddComplete` | `() => void` | No | A callback that is invoked when the process to add a line item to the cart completes. |
-| `onLineRemoveComplete` | `() => void` | No | A callback that is invoked when the process to remove a line item to the cart completes. |
-| `onLineUpdateComplete` | `() => void` | No | A callback that is invoked when the process to update a line item in the cart completes. |
-| `onNoteUpdateComplete` | `() => void` | No | A callback that is invoked when the process to add or update a note in the cart completes. |
-| `onBuyerIdentityUpdateComplete` | `() => void` | No | A callback that is invoked when the process to update the buyer identity completes. |
-| `onAttributesUpdateComplete` | `() => void` | No | A callback that is invoked when the process to update the cart attributes completes. |
-| `onDiscountCodesUpdateComplete` | `() => void` | No | A callback that is invoked when the process to update the cart discount codes completes. |
-| `data` | `PartialDeep<CartType, {recurseIntoArrays: true}>` | No | An object with fields that correspond to the Storefront API's Cart object. |
-| `cartFragment` | `string` | No | A fragment used to query the Storefront API's Cart object for all queries and mutations. A default value is used if no argument is provided. |
-| `customerAccessToken` | `string` | No | A customer access token that's accessible on the server if there's a customer login. |
-| `countryCode` | `CountryCode` | No | The ISO country code for i18n. |
-
-   -
-
-## Override key
-If you need to pass in a different Rebuy Api key from the one that we dynamically use for your store, you can pass it in as a prop on either of the provider components. ie `overrideApiKey="123456"`
-
-## Components
+3. With this, you can also pass in any CartProvider props that you need.
+
+### Cart Provider Properties
+
+| Property                        | Type                                               | Required | Description                                                                                                                                            |
+| :------------------------------ | :------------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`                      | `React.ReactNode`                                  | Yes      | Any `ReactNode` elements.                                                                                                                              |
+| `numCartLines`                  | `number`                                           | No       | Maximum number of cart lines to fetch. Defaults to 250 cart lines.                                                                                     |
+| `onCreate`                      | `() => void`                                       | No       | A callback that is invoked when the process to create a cart begins, but before the cart is created in the Storefront API.                             |
+| `onLineAdd`                     | `() => void`                                       | No       | A callback that is invoked when the process to add a line item to the cart begins, but before the line item is added to the Storefront API.            |
+| `onLineRemove`                  | `() => void`                                       | No       | A callback that is invoked when the process to remove a line item to the cart begins, but before the line item is removed from the Storefront API.     |
+| `onLineUpdate`                  | `() => void`                                       | No       | A callback that is invoked when the process to update a line item in the cart begins, but before the line item is updated in the Storefront API.       |
+| `onNoteUpdate`                  | `() => void`                                       | No       | A callback that is invoked when the process to add or update a note in the cart begins, but before the note is added or updated in the Storefront API. |
+| `onBuyerIdentityUpdate`         | `() => void`                                       | No       | A callback that is invoked when the process to update the buyer identity begins, but before the buyer identity is updated in the Storefront API.       |
+| `onAttributesUpdate`            | `() => void`                                       | No       | A callback that is invoked when the process to update the cart attributes begins, but before the attributes are updated in the Storefront API.         |
+| `onDiscountCodesUpdate`         | `() => void`                                       | No       | A callback that is invoked when the process to update the cart discount codes begins, but before the discount codes are updated in the Storefront API. |
+| `onCreateComplete`              | `() => void`                                       | No       | A callback that is invoked when the process to create a cart completes.                                                                                |
+| `onLineAddComplete`             | `() => void`                                       | No       | A callback that is invoked when the process to add a line item to the cart completes.                                                                  |
+| `onLineRemoveComplete`          | `() => void`                                       | No       | A callback that is invoked when the process to remove a line item to the cart completes.                                                               |
+| `onLineUpdateComplete`          | `() => void`                                       | No       | A callback that is invoked when the process to update a line item in the cart completes.                                                               |
+| `onNoteUpdateComplete`          | `() => void`                                       | No       | A callback that is invoked when the process to add or update a note in the cart completes.                                                             |
+| `onBuyerIdentityUpdateComplete` | `() => void`                                       | No       | A callback that is invoked when the process to update the buyer identity completes.                                                                    |
+| `onAttributesUpdateComplete`    | `() => void`                                       | No       | A callback that is invoked when the process to update the cart attributes completes.                                                                   |
+| `onDiscountCodesUpdateComplete` | `() => void`                                       | No       | A callback that is invoked when the process to update the cart discount codes completes.                                                               |
+| `data`                          | `PartialDeep<CartType, {recurseIntoArrays: true}>` | No       | An object with fields that correspond to the Storefront API's Cart object.                                                                             |
+| `cartFragment`                  | `string`                                           | No       | A fragment used to query the Storefront API's Cart object for all queries and mutations. A default value is used if no argument is provided.           |
+| `customerAccessToken`           | `string`                                           | No       | A customer access token that's accessible on the server if there's a customer login.                                                                   |
+| `countryCode`                   | `CountryCode`                                      | No       | The ISO country code for i18n.                                                                                                                         |
+
+### Override Key
+
+If you need to pass in a different Rebuy API key from the one that we dynamically use for your store, you can pass it in as a prop on either of the provider components, e.g., `overrideApiKey="123456"`.
+
+---
+
+# 🎨 Themed Styles
+
+Rebuy provides themed stylesheets that automatically synchronize your components with the design settings configured in your Rebuy admin panel. This ensures that button colors, widget text colors, typography, spacing, and other visual elements match your brand preferences without requiring manual CSS customization.
+
+### For Remix/Hydrogen Users
+
+Use the `getRebuyThemeStylesLink` function in your root layout file's `links()` function for optimal performance:
+
+1. Import the function in your root layout file (typically `app/root.tsx`):
+
+```typescript
+import { getRebuyThemeStylesLink } from '@rebuy/rebuy-hydrogen';
+```
+
+2. Add the theme styles to your `links()` function:
+
+```typescript
+export function links() {
+    const links = [
+        {
+            rel: 'preconnect',
+            href: 'https://cdn.shopify.com',
+        },
+        // ... other links
+    ];
+
+    // Add Rebuy theme styles
+    links.push(
+        ...getRebuyThemeStylesLink({
+            apiKey: 'your-rebuy-api-key-here',
+        })
+    );
+
+    return links;
+}
+```
+
+### For Other Frameworks
+
+If you're not using Remix, you can include the stylesheet directly in your HTML `<head>` or via your framework's preferred method:
+
+```html
+<link rel="stylesheet" href="https://rebuyengine.com/api/v1/theme-styles?key=your-rebuy-api-key-here" />
+```
+
+### Finding Your API Key
+
+You can find your Rebuy API key in your [Rebuy admin account settings](https://rebuyengine.com/account/keys) (login required).
+
+---
+
+# 🧩 Components Reference
 
 Our components work seamlessly in both Hydrogen-only and Hydrogen React applications by using the existing context to call the correct hooks/functions.
 
@@ -129,80 +190,577 @@ This is the parent component that provides the needed context to child widgets.
 
 **Properties:**
 
-| Property | Description |
-| :---- | :---- |
-| `dataSource` | The Rebuy API endpoint to use for product recommendations |
-| `productId` | The Shopify product ID |
-| `product` | The entire product object |
-| `variantID` | The selected variant ID |
-| `variant` | The selected variant object |
-| `limit` | How many product recommendations to return |
-| `options` | An object with key-value pairs of Rebuy REST API arguments (e.g., `{ metafields: "yes" }`) |
+| Property     | Description                                                                                |
+| :----------- | :----------------------------------------------------------------------------------------- |
+| `dataSource` | The Rebuy API endpoint to use for product recommendations                                  |
+| `productId`  | The Shopify product ID                                                                     |
+| `product`    | The entire product object                                                                  |
+| `variantID`  | The selected variant ID                                                                    |
+| `variant`    | The selected variant object                                                                |
+| `limit`      | How many product recommendations to return                                                 |
+| `options`    | An object with key-value pairs of Rebuy REST API arguments (e.g., `{ metafields: "yes" }`) |
 
 ### RebuyCompleteTheLook
 
 **Properties:**
 
-| Property | Description |
-| :---- | :---- |
-| `customTitle` | A custom title displayed above the component |
-| `customTitleLevel` | Sets the initial title level (e.g., if set to `h2`, other titles in the component will adjust to `h3` accordingly) |
-| `customTitleStyle` | An object of custom styles for the title (e.g., text color, text align) |
-| `addToCartCallBack` | A callback function for custom functionality when items are added to the cart |
-| `addToCartBtnText` | Custom text for the Add To Cart button |
+| Property            | Description                                                                                                        |
+| :------------------ | :----------------------------------------------------------------------------------------------------------------- |
+| `customTitle`       | A custom title displayed above the component                                                                       |
+| `customTitleLevel`  | Sets the initial title level (e.g., if set to `h2`, other titles in the component will adjust to `h3` accordingly) |
+| `customTitleStyle`  | An object of custom styles for the title (e.g., text color, text align)                                            |
+| `addToCartCallback` | A callback function for custom functionality when items are added to the cart                                      |
+| `addToCartBtnText`  | Custom text for the Add To Cart button                                                                             |
 
 ### RebuyDynamicBundleProducts
 
 **Properties:**
 
-| Property | Description |
-| :---- | :---- |
-| `customTitle` | A custom title displayed above the component |
-| `customTitleLevel` | Sets the initial title level (e.g., if set to `h2`, other titles in the component will adjust to `h3` accordingly) |
-| `customTitleStyle` | An object of custom styles for the title (e.g., text color, text align) |
-| `addToCartCallBack` | A callback function for custom functionality when items are added to the cart |
-| `addToCartBtnText` | Custom text for the Add To Cart button |
+| Property            | Description                                                                                                        |
+| :------------------ | :----------------------------------------------------------------------------------------------------------------- |
+| `customTitle`       | A custom title displayed above the component                                                                       |
+| `customTitleLevel`  | Sets the initial title level (e.g., if set to `h2`, other titles in the component will adjust to `h3` accordingly) |
+| `customTitleStyle`  | An object of custom styles for the title (e.g., text color, text align)                                            |
+| `addToCartCallback` | A callback function for custom functionality when items are added to the cart                                      |
+| `addToCartBtnText`  | Custom text for the Add To Cart button                                                                             |
 
 ### RebuyProductRecommendations
 
 **Properties:**
 
-| Property | Description |
-| :---- | :---- |
-| `customTitle` | A custom title displayed above the component |
-| `customTitleLevel` | Sets the initial title level (e.g., if set to `h2`, other titles in the component will adjust to `h3` accordingly) |
-| `customTitleStyle` | An object of custom styles for the title (e.g., text color, text align) |
-| `addToCartCallBack` | A callback function for custom functionality when items are added to the cart |
-| `addToCartBtnText` | Custom text for the Add To Cart button |
+| Property            | Description                                                                                                        |
+| :------------------ | :----------------------------------------------------------------------------------------------------------------- |
+| `customTitle`       | A custom title displayed above the component                                                                       |
+| `customTitleLevel`  | Sets the initial title level (e.g., if set to `h2`, other titles in the component will adjust to `h3` accordingly) |
+| `customTitleStyle`  | An object of custom styles for the title (e.g., text color, text align)                                            |
+| `addToCartCallback` | A callback function for custom functionality when items are added to the cart                                      |
+| `addToCartBtnText`  | Custom text for the Add To Cart button                                                                             |
 
 ### RebuyProductAddOns
 
 **Properties:**
 
-| Property | Description |
-| :---- | :---- |
-| `customTitle` | A custom title displayed above the component |
-| `customTitleLevel` | Sets the initial title level (e.g., if set to `h2`, other titles in the component will adjust to `h3` accordingly) |
-| `customTitleStyle` | An object of custom styles for the title (e.g., text color, text align) |
-| `addToCartCallBack` | A callback function for custom functionality when items are added to the cart |
-| `addToCartBtnText` | Custom text for the Add To Cart button |
-| `includeMainProduct` | Option to include the product passed from the `WidgetContainer` in the add to cart functionality |
-| `learnMoreText` | Text displayed in a CTA that takes users to the product page |
-| `subtotalText` | Text that appears before the subtotal of all add-ons |
-| `withProductText` | Text that appears before the total if the product from `WidgetContainer` is included in the add to cart functionality |
+| Property             | Description                                                                                                           |
+| :------------------- | :-------------------------------------------------------------------------------------------------------------------- |
+| `customTitle`        | A custom title displayed above the component                                                                          |
+| `customTitleLevel`   | Sets the initial title level (e.g., if set to `h2`, other titles in the component will adjust to `h3` accordingly)    |
+| `customTitleStyle`   | An object of custom styles for the title (e.g., text color, text align)                                               |
+| `addToCartCallback`  | A callback function for custom functionality when items are added to the cart                                         |
+| `addToCartBtnText`   | Custom text for the Add To Cart button                                                                                |
+| `includeMainProduct` | Option to include the product passed from the `WidgetContainer` in the add to cart functionality                      |
+| `learnMoreText`      | Text displayed in a CTA that takes users to the product page                                                          |
+| `subtotalText`       | Text that appears before the subtotal of all add-ons                                                                  |
+| `withProductText`    | Text that appears before the total if the product from `WidgetContainer` is included in the add to cart functionality |
 
 ### RebuyWidget
 
-## Dynamic widget that can be set up to display a widget that you have created in the Rebuy Admin
+Dynamic widget that can be set up to display a widget that you have created in the Rebuy Admin.
 
 **Properties:**
 
-| Property | Description |
-| :---- | :---- |
-| `widgetId` | The widget Id for the widget that you want to display (can be found in the Rebuy Admin) |
-| `addToCartCallBack` | A callback function for custom functionality when items are added to the cart |
-| `productId` | The Shopify product ID |
-| `product` | The entire product object |
-| `variantID` | The selected variant ID |
-| `variant` | The selected variant object |
-| `popupTriggerid` | If you have configured this to be a popup that is triggered on a button click then you need to pass the id of the element that you want to trigger the popup to appear on |
+| Property            | Description                                                                                                                                   |
+| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------- |
+| `widgetId`          | The widget ID for the widget that you want to display (can be found in the Rebuy Admin).                                                      |
+| `addToCartCallback` | A callback function for custom functionality when items are added to the cart.                                                                |
+| `customTitle`       | A custom title displayed above the component.                                                                                                 |
+| `customTitleLevel`  | Sets the initial title level (e.g., if set to `h2`, other titles in the component will adjust to `h3` accordingly). Defaults to `h2`.         |
+| `customTitleStyle`  | An object of custom styles for the title (e.g., text color, text align).                                                                      |
+| `isHydrogenReact`   | A boolean indicating if the application is using Hydrogen React. This helps the component use the correct hooks/functions.                    |
+| `popupTriggerId`    | If you have configured this to be a popup that is triggered on a button click, pass the ID of the element that you want to trigger the popup. |
+| `product`           | The entire product object.                                                                                                                    |
+| `productId`         | The Shopify product ID.                                                                                                                       |
+| `variant`           | The selected variant object.                                                                                                                  |
+| `variantId`         | The selected variant ID.                                                                                                                      |
+
+---
+
+# 🛒 Smart Cart Guide
+
+🚀 **Smart Cart: Supercharge Your Shopify Cart**
+
+Welcome to the Rebuy Smart Cart! This powerful suite of features is designed to enhance your Shopify cart experience, boost conversions, and provide seamless integration with Rebuy's personalization engine.
+
+> **📘 Framework Compatibility Note**
+>
+> This documentation covers Hydrogen projects using both Remix and React Router frameworks. If you're using React Router 7 (the newer standard), ensure you're importing from the correct packages:
+>
+> - Use `react-router` instead of `@remix-run/react`
+> - Use `@react-router/dev` instead of `@remix-run/dev`
+>
+> The core functionality remains the same regardless of framework choice.
+
+> **A Note on Hydrogen Versions**
+>
+> The instructions and examples in this guide are tailored for Shopify Hydrogen projects built with the **Remix framework (Hydrogen v2 and later)**. File paths like `app/root.tsx` and concepts such as route `action` functions are specific to this architecture.
+>
+> If you are using a non-Remix Hydrogen setup or a different React framework, you will need to adapt these instructions. While the core GraphQL fragments for the cart query are reusable, your project's methods for fetching data and handling cart mutations will be different.
+
+## Prerequisites
+
+Before implementing Smart Cart features, ensure your cart route can handle JSON payloads and your GraphQL queries include the necessary fields for discount and subscription functionality.
+
+### JSON Cart Action Support
+
+Smart Cart components send updates as JSON payloads to your cart route. Your cart route file (e.g., `app/routes/cart.tsx` or `app/routes/($locale).cart.tsx`) must be able to parse both JSON and form data requests.
+
+**Update your cart route's action function:**
+
+```typescript
+export async function action({ request, context }: ActionFunctionArgs) {
+    const { cart } = context;
+
+    let formData;
+    let action;
+    let inputs;
+
+    const contentType = request.headers.get('Content-Type') || '';
+    if (contentType.includes('application/json')) {
+        const jsonData = (await request.json()) as { action: string; data: any };
+
+        const actionMap = {
+            cartLinesAdd: CartForm.ACTIONS.LinesAdd,
+            cartLinesUpdate: CartForm.ACTIONS.LinesUpdate,
+            cartLinesRemove: CartForm.ACTIONS.LinesRemove,
+            discountCodesUpdate: CartForm.ACTIONS.DiscountCodesUpdate,
+            giftCardCodesUpdate: CartForm.ACTIONS.GiftCardCodesUpdate,
+            buyerIdentityUpdate: CartForm.ACTIONS.BuyerIdentityUpdate,
+            cartAttributesUpdate: CartForm.ACTIONS.AttributesUpdateInput,
+        };
+
+        const actionKey = jsonData.action as string;
+        action = actionKey in actionMap ? actionMap[actionKey as keyof typeof actionMap] : actionKey;
+        inputs = jsonData.data;
+    } else {
+        formData = await request.formData();
+        const formInput = CartForm.getFormInput(formData);
+        action = formInput.action;
+        inputs = formInput.inputs;
+    }
+
+    if (!action) {
+        throw new Error('No action provided');
+    }
+
+    let status = 200;
+    let result: CartQueryDataReturn;
+
+    switch (action) {
+        case CartForm.ACTIONS.LinesAdd:
+            result = await cart.addLines(inputs.lines);
+            break;
+        case CartForm.ACTIONS.LinesUpdate:
+            result = await cart.updateLines(inputs.lines);
+            break;
+        case CartForm.ACTIONS.LinesRemove:
+            result = await cart.removeLines(inputs.lineIds);
+            break;
+        case CartForm.ACTIONS.DiscountCodesUpdate: {
+            const formDiscountCode = inputs.discountCode;
+            const discountCodes = (formDiscountCode ? [formDiscountCode] : []) as string[];
+            discountCodes.push(...(inputs.discountCodes || []));
+            result = await cart.updateDiscountCodes(discountCodes);
+            break;
+        }
+        case CartForm.ACTIONS.GiftCardCodesUpdate: {
+            const formGiftCardCode = inputs.giftCardCode;
+            const giftCardCodes = (formGiftCardCode ? [formGiftCardCode] : []) as string[];
+            giftCardCodes.push(...(inputs.giftCardCodes || []));
+            result = await cart.updateGiftCardCodes(giftCardCodes);
+            break;
+        }
+        case CartForm.ACTIONS.BuyerIdentityUpdate: {
+            result = await cart.updateBuyerIdentity({ ...inputs.buyerIdentity });
+            break;
+        }
+        case CartForm.ACTIONS.AttributesUpdateInput: {
+            result = await cart.updateAttributes(inputs.attributes || []);
+            break;
+        }
+        default:
+            throw new Error(`${action} cart action is not defined`);
+    }
+
+    const cartId = result?.cart?.id;
+    const headers = cartId ? cart.setCartId(result.cart.id) : new Headers();
+    const { cart: cartResult, errors, warnings } = result;
+
+    const redirectTo = formData ? (formData.get('redirectTo') ?? null) : null;
+    if (typeof redirectTo === 'string') {
+        status = 303;
+        headers.set('Location', redirectTo);
+    }
+
+    return data(
+        {
+            cart: cartResult,
+            errors,
+            warnings,
+            analytics: { cartId },
+        },
+        { status, headers }
+    );
+}
+```
+
+**Note:** Cart route file names may vary based on your project setup. Common variations include `cart.tsx`, `($locale).cart.tsx`, or `[locale].cart.tsx`.
+
+### Enhanced Cart Query for Smart Cart Features
+
+To enable full discount and subscription functionality, your cart query must include specific GraphQL fields. Update your cart query fragment to include these essential fields:
+
+```graphql
+#graphql
+fragment Money on MoneyV2 {
+    currencyCode
+    amount
+}
+
+fragment CartLine on CartLine {
+    id
+    quantity
+    attributes {
+        key
+        value
+    }
+    cost {
+        totalAmount {
+            ...Money
+        }
+        amountPerQuantity {
+            ...Money
+        }
+        compareAtAmountPerQuantity {
+            ...Money
+        }
+    }
+    merchandise {
+        ... on ProductVariant {
+            id
+            availableForSale
+            compareAtPrice {
+                ...Money
+            }
+            price {
+                ...Money
+            }
+            requiresShipping
+            title
+            image {
+                id
+                url
+                altText
+                width
+                height
+            }
+            product {
+                handle
+                title
+                id
+                vendor
+                # Required for subscription functionality
+                requiresSellingPlan
+                sellingPlanGroups(first: 100) {
+                    edges {
+                        node {
+                            appName
+                            name
+                            options {
+                                name
+                                values
+                            }
+                            sellingPlans(first: 100) {
+                                edges {
+                                    node {
+                                        id
+                                        name
+                                        options {
+                                            name
+                                            value
+                                        }
+                                        priceAdjustments {
+                                            adjustmentValue {
+                                                ... on SellingPlanFixedAmountPriceAdjustment {
+                                                    adjustmentAmount {
+                                                        amount
+                                                        currencyCode
+                                                    }
+                                                }
+                                                ... on SellingPlanFixedPriceAdjustment {
+                                                    price {
+                                                        amount
+                                                        currencyCode
+                                                    }
+                                                }
+                                                ... on SellingPlanPercentagePriceAdjustment {
+                                                    adjustmentPercentage
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            selectedOptions {
+                name
+                value
+            }
+        }
+    }
+    # Required for subscription functionality
+    sellingPlanAllocation {
+        sellingPlan {
+            id
+            name
+        }
+    }
+}
+
+fragment CartApiQuery on Cart {
+    updatedAt
+    id
+    appliedGiftCards {
+        lastCharacters
+        amountUsed {
+            ...Money
+        }
+    }
+    checkoutUrl
+    totalQuantity
+    buyerIdentity {
+        countryCode
+        customer {
+            id
+            email
+            firstName
+            lastName
+            displayName
+        }
+        email
+        phone
+    }
+    lines(first: $numCartLines) {
+        nodes {
+            ...CartLine
+        }
+    }
+    cost {
+        subtotalAmount {
+            ...Money
+        }
+        totalAmount {
+            ...Money
+        }
+        totalDutyAmount {
+            ...Money
+        }
+        totalTaxAmount {
+            ...Money
+        }
+    }
+    note
+    attributes {
+        key
+        value
+    }
+    discountCodes {
+        code
+        applicable
+    }
+    # Required for discount functionality
+    discountAllocations {
+        discountedAmount {
+            ...Money
+        }
+        ... on CartCodeDiscountAllocation {
+            code
+        }
+        ... on CartAutomaticDiscountAllocation {
+            title
+        }
+    }
+}
+```
+
+**Important:** After updating your cart query fragments, regenerate your Hydrogen types:
+
+```bash
+npm run dev -- --codegen
+# OR
+npm run codegen
+```
+
+This updates your `storefrontapi.generated.d.ts` file with the new TypeScript types for Smart Cart fields.
+
+### Using Smart Cart Apps & Custom Code
+
+Features like **Smart Cart Apps** and **Custom Code Blocks** inject dynamic content and scripts directly into the cart. To enable these features, you must configure your Content Security Policy (CSP) and provide the nonce to the DOM.
+
+#### Step 1: Configure Content Security Policy
+
+Update your server entry file (typically `app/entry.server.tsx`) to include Rebuy domains and script sources:
+
+```typescript
+import type {AppLoadContext} from '@shopify/remix-oxygen';
+import {ServerRouter} from 'react-router';
+import {isbot} from 'isbot';
+import {renderToReadableStream} from 'react-dom/server';
+import {createContentSecurityPolicy} from '@shopify/hydrogen';
+import type {EntryContext} from 'react-router';
+
+export default async function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  reactRouterContext: EntryContext,
+  context: AppLoadContext,
+) {
+  const {nonce, header, NonceProvider} = createContentSecurityPolicy({
+    shop: {
+      checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
+      storeDomain: context.env.PUBLIC_STORE_DOMAIN,
+    },
+    scriptSrc: [
+      "'self'",
+      'https://cdn.shopify.com',
+      '*.rebuyengine.com',
+      'rebuyengine.com',
+    ],
+    styleSrc: [
+      "'self'",
+      'https://cdn.shopify.com',
+      '*.rebuyengine.com',
+      'rebuyengine.com',
+    ],
+    connectSrc: [
+      "'self'",
+      '*.rebuyengine.com',
+      'rebuyengine.com',
+      'https://monorail-edge.shopifysvc.com',
+    ],
+    imgSrc: ["'self'", "data:", "https://cdn.shopify.com", "*.rebuyengine.com"],
+    fontSrc: ["'self'", "data:", "https://cdn.shopify.com"],
+  });
+
+  const body = await renderToReadableStream(
+    <NonceProvider>
+      <ServerRouter
+        context={reactRouterContext}
+        url={request.url}
+        nonce={nonce}
+      />
+    </NonceProvider>,
+    {
+      nonce,
+      signal: request.signal,
+      onError(error) {
+        console.error(error);
+        responseStatusCode = 500;
+      },
+    },
+  );
+
+  if (isbot(request.headers.get('user-agent'))) {
+    await body.allReady;
+  }
+
+  responseHeaders.set('Content-Type', 'text/html');
+  responseHeaders.set('Content-Security-Policy', header);
+
+  return new Response(body, {
+    headers: responseHeaders,
+    status: responseStatusCode,
+  });
+}
+```
+
+#### Step 2: Provide Nonce to DOM
+
+Update your root layout file (typically `app/root.tsx`) to attach the nonce to the body element:
+
+```tsx
+import { useNonce } from '@shopify/hydrogen';
+
+export function Layout({ children }: { children?: React.ReactNode }) {
+    const nonce = useNonce();
+
+    return (
+        <html lang="en">
+            <head>{/* ... */}</head>
+            <body data-nonce={nonce} suppressHydrationWarning>
+                {/* ... your providers and app content ... */}
+            </body>
+        </html>
+    );
+}
+```
+
+### Login Button
+
+The Login Button component provides a link to your store's login page and automatically hides when a customer is logged in. Configure the login URL in your Rebuy admin (defaults to `/account/login`).
+
+---
+
+## 🔧 Troubleshooting
+
+### GraphQL Type Errors
+
+If you encounter TypeScript errors after updating fragments:
+
+1. Run the codegen command: `npm run codegen`
+2. Restart your development server
+3. Verify `storefrontapi.generated.d.ts` has been updated
+
+### Cart Route Issues
+
+If Smart Cart features aren't working:
+
+1. Verify your cart route handles JSON payloads
+2. Check your cart route file name matches your project structure
+3. Ensure your action function processes both JSON and FormData requests
+
+### CSP Issues
+
+If Smart Cart Apps or Custom Code Blocks aren't working:
+
+1. Verify Rebuy domains are in your CSP configuration
+2. Ensure the nonce is set on the `<body>` element
+3. Check browser console for CSP violation errors
+
+---
+
+## 📋 Compatibility
+
+### Hydrogen Versions
+
+- ✅ Hydrogen 2025.5.0+
+- ✅ React Router 7.x
+- ✅ Remix-based Hydrogen projects
+- ✅ Hydrogen React 2.0+
+
+### Node.js Requirements
+
+- Node.js 18.0.0 or higher
+- npm 8.0.0 or higher
+
+### Framework Support
+
+- **Remix Framework**: Full support
+- **React Router 7**: Full support
+- **Hydrogen React**: Enhanced cart provider with additional props
+
+### Browser Support
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+### Shopify Compatibility
+
+- Storefront API 2024-01+
+- Checkout API compatibility
+- Multi-language/locale support
+- Customer account integration