@rebuy/rebuy-hydrogen 3.0.0-beta.2 → 3.0.0-beta.20

package/README.md

@@ -1,28 +1,1000 @@
-# Rebuy + Hydrogen Overview
+# Beta Documentation: Rebuy Hydrogen 2.0
 
-Rebuy + Hydrogen package is a web development framework used for building Shopify custom storefronts. It includes providers, components, and tooling you need to get started so you can spend your time creating intelligent shopping experiences.
+## Overview
 
-## Rebuy + Hydrogen 2
+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.
 
-Rebuy makes it incredibly easy to bring powerful personalized product recommendations and smart search to your Shopify Hydrogen 2.0 Storefront. For more details on this, please check out our [Rebuy + Shopify Hydrogen 2.0 documentation](https://developers.rebuyengine.com/reference/rebuy-shopify-hydrogen-2).
+## Quick Reference
 
-## How Rebuy + Hydrogen Works
+This documentation covers:
 
-Rebuy + Hydrogen is a lightweight framework for creating personalized shopping experiences that are lightening fast. The framework is composed of:
+- **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
 
-1. **Providers** - these components build contextual objects that are used during network calls.
-2. **Containers** - these components get personalized data from Rebuy and pass the resulting information to children components via props.
-3. **Components** - these components can be used to render various merchandising UI.
-4. **Events** - these components automatically track user behaviors.
+---
 
-### Data Sources
+# 📦 Installation Guide
 
-Rebuy + Hydrogen is powered by Rebuy's Data Sources, which allows for AI-powered product recommendations, custom defined rulesets, or mixture of human and computer derived output. Data Sources are created in Rebuy's App Admin, and the data source URL is used in your Hydrogen project. Separating the logic from the codebase allows non-technical team members to manage the merchandising rules without the need for costly code changes or redeployments.
+### Prerequisites
 
-### User Interfaces
+First, determine whether your application uses:
 
-Rebuy + Hydrogen uses a React container pattern to separate the data fetching logic and state management from the presentational components. As such, container components do not render user interface elements. They simply pass their own properties, as well as data received from Rebuy, to their children components for consumption. This allows you to build your own user interface with your existing components, or use Rebuy's out of the box components to get up and running quickly.
+- Hydrogen only
+- Both Hydrogen and Hydrogen React
 
-### Getting Started
+This distinction is important as different hooks/functions are used in each case. Note that if you're using Hydrogen React, Hydrogen is also being used by default. Our components will call the appropriate hooks/functions/components for Hydrogen React applications.
 
-To get started, please visit our [Rebuy + Shopify Hydrogen documentation](https://developers.rebuyengine.com/reference/shopify-hydrogen-getting-started).
+### Prerequisites
+
+- "@shopify/hydrogen": ">=2025.5.0",
+- If you are also using hydrogen-react along with just hydrogen: "@shopify/hydrogen-react": ">=2025.4.0"
+- Smart Cart V2. Legacy Smart Carts are not supported
+
+### Installation Steps
+
+1. Install the beta version of our package from npm:
+
+Package URL: [https://www.npmjs.com/package/@rebuy/rebuy-hydrogen](https://www.npmjs.com/package/@rebuy/rebuy-hydrogen)
+
+2. In your server entry file (typically `app/entry.server.tsx`), update the `createContentSecurityPolicy` to have `rebuyengine.com` in the `connectSrc`.
+
+```typescript
+const { nonce, header, NonceProvider } = createContentSecurityPolicy({
+    shop: {
+        checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
+        storeDomain: context.env.PUBLIC_STORE_DOMAIN,
+    },
+    connectSrc: ['*.rebuyengine.com', 'rebuyengine.com'],
+});
+```
+
+### For Hydrogen-only Applications
+
+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`, `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"
+>
+    <Analytics.Provider
+      cart={data.cart}
+      shop={data.shop}
+      consent={data.consent}
+    >
+      <PageLayout {...data}>
+        {children}
+      </PageLayout>
+    </Analytics.Provider>
+  </RebuyHydrogenContextProvider>
+) : (
+  children
+)}
+```
+
+### For Hydrogen React Applications
+
+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: `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`:
+
+```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.
+
+### 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.
+
+### WidgetContainer
+
+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" }`) |
+
+### 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                                                                             |
+
+### 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                                                                             |
+
+### 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                                                                             |
+
+### 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 |
+
+### RebuyWidget
+
+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.                                                                |
+| `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.                                                                                                                      |
+
+### RebuyGiftWithPurchase
+
+A headless widget that automatically manages Gift With Purchase functionality. This component monitors cart state and automatically adds/removes free gifts based on data source rules configured in the Rebuy Admin. No UI is rendered - all gift management happens automatically in the background.
+
+**Properties:**
+
+| Property   | Description                                                                 |
+| :--------- | :-------------------------------------------------------------------------- |
+| `widgetId` | The widget ID for the gift with purchase widget (found in the Rebuy Admin). |
+
+**Usage Example:**
+
+```typescript
+// Place in your root layout
+<RebuyGiftWithPurchase widgetId="12345" />
+```
+
+**Notes:**
+
+- This component is best suited for single-variant gift products.
+- If your gift qualifier is the cart subtotal, we recommend using the Tiered Progress Bar as it can be used for selectable multi-variant gifts.
+
+### RebuyProductViewed
+
+Place this component on any page or element where you would like to record that a customer has viewed one of your products. You will need to pass in either the entire product object, productID, or just the productHandle. This component will generate a UUID for registering the viewed products if a customerId is not passed along as well. To record a customer viewing a product and have that record attached to their customerID you will need to pass in the customerId as a sting.
+
+**Properties:**
+
+| Property        | Description                                                                                                 |
+| :-------------- | :---------------------------------------------------------------------------------------------------------- |
+| `productId`     | The Shopify product ID                                                                                      |
+| `product`       | The entire product object                                                                                   |
+| `productHandle` | The product's handle                                                                                        |
+| `customerId`    | The ID of the customer viewing the product. If no customerId is passed a UUID will be used locally instead. |
+
+### RebuyRecentlyViewedProducts
+
+Component returns a list of the products that a customer has recently viewed based on either their customerId or the generated UUID
+
+**Properties:**
+
+| `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                                                                                                                                                                                                                    |
+| `productId`         | If you pass in a shopify productId, then that product will be excluded from the list of returned products. Use case would be if on a product page and you do not want the product on that page also displaying in the recently viewed products component. |
+
+### Using useRebuyWidget in Custom Components
+
+You can create custom components that access Rebuy widget data by using the `useRebuyWidget` hook within a `RebuyWidgetContainer`. This allows you to build custom UIs while maintaining access to all Rebuy widget functionality.
+
+```typescript
+import { useRebuyWidget } from '@rebuy/rebuy-hydrogen';
+
+// In your page/layout:
+<RebuyWidgetContainer dataSource="/api/v1/products/recommended" limit={4}>
+    <MyCustomComponent />
+    <RebuyProductRecommendations />
+</RebuyWidgetContainer>
+
+// In your custom component:
+const MyCustomComponent = () => {
+    const {
+        products,
+        isHydrogenReact,
+        metadata,
+        product,
+        variant
+    } = useRebuyWidget();
+
+    return (
+        <div>
+            {/* Custom implementation using Rebuy data */}
+        </div>
+    );
+};
+```
+
+**Available Context Properties:**
+
+| Property          | Type                               | Description                             |
+| :---------------- | :--------------------------------- | :-------------------------------------- |
+| `products`        | `RebuyProduct[]`                   | Array of recommended products           |
+| `isHydrogenReact` | `boolean`                          | Whether the app is using Hydrogen React |
+| `metadata`        | `RebuyWidgetMetadata`              | Widget metadata from Rebuy              |
+| `product`         | `HydrogenProduct \| undefined`     | The main product if provided            |
+| `variant`         | `RebuyProductVariant \| undefined` | The selected variant if provided        |
+| `productId`       | `string \| undefined`              | The product ID if provided              |
+| `variantId`       | `string \| undefined`              | The variant ID if provided              |
+| `dataSource`      | `string`                           | The Rebuy API endpoint being used       |
+| `limit`           | `number`                           | Maximum number of products to return    |
+| `options`         | `Record<string, unknown>`          | Additional Rebuy API options            |
+| `key`             | `string`                           | Unique key for the widget instance      |
+| `cacheKey`        | `string \| undefined`              | The shop's cache key for Rebuy          |
+| `apiKey`          | `string \| undefined`              | The Rebuy API key for the shop          |
+
+---
+
+# 🛒 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.
+
+## Enabling Smart Cart Toggle
+
+To replace Hydrogen's native cart drawer with Rebuy's Smart Cart, follow these steps:
+
+### 1. Enable Smart Cart in the Provider
+
+In your root layout file (`app/root.tsx`), add the `enableSmartCart` prop to your context provider and include the `RebuySmartCart` component:
+
+**For Hydrogen-only Applications:**
+
+```typescript
+<RebuyHydrogenContextProvider
+  cart={data.cart}
+  shop="example.com"
+  publicStoreDomain="example.myshopify.com"
+  enableSmartCart={true}
+>
+  {/* Your app content */}
+  <RebuySmartCart />
+</RebuyHydrogenContextProvider>
+```
+
+**For Hydrogen React Applications:**
+
+```typescript
+<RebuyHydrogenReactContextProvider
+  publicPrimaryDomain="example.com"
+  publicStoreDomain="example.myshopify.com"
+  publicStorefrontToken="1233456"
+  publicStorefrontId="12345678"
+  enableSmartCart={true}
+>
+  {/* Your app content */}
+  <RebuySmartCart />
+</RebuyHydrogenReactContextProvider>
+```
+
+### 2. Disable the Native Cart Aside
+
+Comment out or remove the native `CartAside` component in your layout file (typically in `PageLayout.tsx` or similar):
+
+```typescript
+// Before
+<CartAside cart={cart} />
+
+// After - Comment out or remove
+{/* <CartAside cart={cart} /> */}
+```
+
+### 3. Update Cart Toggle Interactions
+
+Replace the native cart toggle functionality with Rebuy's Smart Cart:
+
+**In your Header component:**
+
+```typescript
+import { useSmartCart } from '@rebuy/rebuy-hydrogen';
+
+export function Header() {
+  const { toggleCart } = useSmartCart();
+
+  // In your cart button/icon
+  return (
+    <button
+      onClick={(e) => {
+        e.preventDefault();
+        toggleCart();
+      }}
+    >
+      Cart ({itemCount})
+    </button>
+  );
+}
+```
+
+### 4. Update Add to Cart Actions
+
+After successful add to cart actions, open the Smart Cart:
+
+```typescript
+import { useSmartCart } from '@rebuy/rebuy-hydrogen';
+
+export function ProductForm() {
+    const { toggleCart } = useSmartCart();
+
+    // After successful add to cart
+    const handleAddToCart = async () => {
+        // ... add to cart logic
+        toggleCart(); // Opens Smart Cart after adding item
+    };
+}
+```
+
+### Complete Example
+
+Here's a complete example of converting a cart badge component:
+
+**Before (Hydrogen):**
+
+```typescript
+function CartBadge() {
+  const { open } = useAside();
+
+  return (
+    <a href="/cart" onClick={(e) => {
+      e.preventDefault();
+      open('cart');
+    }}>
+      Cart
+    </a>
+  );
+}
+```
+
+**After (Rebuy Smart Cart):**
+
+```typescript
+import { useSmartCart } from '@rebuy/rebuy-hydrogen';
+
+function CartBadge() {
+  const { toggleCart } = useSmartCart();
+
+  return (
+    <a href="/cart" onClick={(e) => {
+      e.preventDefault();
+      toggleCart();
+    }}>
+      Cart
+    </a>
+  );
+}
+```
+
+> **Note:** The `useSmartCart` hook provides `toggleCart()` to toggle the cart open/closed, along with other cart state management functions.
+
+## 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