@dutchiesdk/ecommerce-extensions-sdk 0.18.0 → 0.19.3

package/README.md

@@ -2,31 +2,68 @@
 
 # @dutchiesdk/ecommerce-extensions-sdk
 
-This SDK provides certified agency partners with the tools needed to create powerful, integrated e-commerce experiences for cannabis retailers on the Dutchie Ecommerce Pro platform.
+A comprehensive SDK for building e-commerce extensions for cannabis retailers on the Dutchie Ecommerce Pro platform. This SDK provides certified agency partners with type-safe access to platform data, cart management, navigation, and customizable UI components.
 
 > ⚠️ **Alpha Release Warning**
 >
 > This SDK is currently in **alpha** and is subject to breaking changes. APIs, types, and functionality may change significantly between versions. Please use with caution in production environments and be prepared to update your extensions as the SDK evolves.
 
-## Development Environment Access
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [API Reference](#api-reference)
+  - [Hooks](#hooks)
+  - [Components & HOCs](#components--hocs)
+  - [Context](#context)
+  - [Types](#types)
+- [Data Interface](#data-interface)
+  - [Actions API](#actions-api)
+  - [Data Loaders](#data-loaders)
+  - [Data Types](#data-types)
+- [Extension Development](#extension-development)
+  - [Creating Components](#creating-components)
+  - [Module Registry](#module-registry)
+  - [Meta Fields & SEO](#meta-fields--seo)
+  - [Event Handlers](#event-handlers)
+- [Best Practices](#best-practices)
+- [Examples](#examples)
+- [Support](#support)
+
+## Prerequisites
+
+### Development Environment Access
 
 This SDK requires a **Dutchie-provided development environment** to build, test, and deploy extensions. The SDK alone is not sufficient for development - you must have access to the complete Dutchie Pro development and deployment infrastructure.
 
 To request access to the development environment contact: **partners@dutchie.com**. Please include your agency information and intended use case when requesting access.
 
+### Requirements
+
+- Node.js >= 18.0.0
+- React ^17.0.0 or ^18.0.0
+- react-dom ^17.0.0 or ^18.0.0
+- react-shadow ^20.5.0
+
 ## Installation
 
 ```bash
-npm install @dutchie/ecommerce-extensions-sdk
+npm install @dutchiesdk/ecommerce-extensions-sdk
 # or
-yarn add @dutchie/ecommerce-extensions-sdk
+yarn add @dutchiesdk/ecommerce-extensions-sdk
 ```
 
 ## Quick Start
 
 ```tsx
 import React from "react";
-import { useDataBridge, RemoteBoundaryComponent, DataBridgeVersion } from "@dutchie/ecommerce-extensions-sdk";
+import {
+  useDataBridge,
+  RemoteBoundaryComponent,
+  DataBridgeVersion,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
 
 const MyExtension: RemoteBoundaryComponent = () => {
   const { dataLoaders, actions, location, user, cart } = useDataBridge();
@@ -44,14 +81,49 @@ MyExtension.DataBridgeVersion = DataBridgeVersion;
 export default MyExtension;
 ```
 
-## React Context & Hooks
+## Core Concepts
+
+The Dutchie Ecommerce Extensions SDK is built around several key concepts:
+
+1. **Data Bridge**: A unified interface for accessing dispensary data, user information, and cart state through React Context
+2. **Actions**: Pre-built navigation and cart management functions that interact with the platform
+3. **Remote Components**: Extension components that integrate seamlessly with the Dutchie platform using module federation
+4. **Data Loaders**: Async functions for fetching product catalogs, categories, brands, and other platform data
+5. **Type Safety**: Comprehensive TypeScript types for all data structures and APIs
+
+## API Reference
+
+### Hooks
 
-### `useDataBridge()`
+#### `useDataBridge()`
 
 The primary hook for accessing the Dutchie platform data and functionality.
 
+**Signature:**
+
+```typescript
+function useDataBridge(): CommerceComponentsDataInterface;
+```
+
+**Returns:**
+
+```typescript
+{
+  menuContext: 'store-front' | 'kiosk';
+  location?: Dispensary;
+  user?: User;
+  cart?: Cart;
+  dataLoaders: DataLoaders;
+  actions: Actions;
+}
+```
+
+**Throws:** Error if used outside of a `DataBridgeProvider` or `RemoteBoundaryComponent`
+
+**Example:**
+
 ```tsx
-import { useDataBridge } from "@dutchie/ecommerce-extensions-sdk";
+import { useDataBridge } from "@dutchiesdk/ecommerce-extensions-sdk";
 
 const MyComponent = () => {
   const {
@@ -63,18 +135,40 @@ const MyComponent = () => {
     actions, // Navigation and cart actions
   } = useDataBridge();
 
-  // Component logic here
+  return <div>{location?.name}</div>;
 };
 ```
 
-**Throws**: Error if used outside of a `DataBridgeProvider`
-
-### `useAsyncLoader(fn)`
+#### `useAsyncLoader(fn, params?)`
 
 A utility hook for handling async data loading with loading states.
 
+**Signature:**
+
+```typescript
+function useAsyncLoader<S, P = void>(
+  fn: (params: P) => Promise<S>,
+  params?: P
+): { data: S | null; isLoading: boolean };
+```
+
+**Parameters:**
+
+- `fn` - An async function that returns a promise (typically a data loader)
+- `params` - Optional parameters to pass to the function
+
+**Returns:**
+
+- `data` - The loaded data, or `null` if still loading
+- `isLoading` - `true` while data is being fetched, `false` once complete
+
+**Example:**
+
 ```tsx
-import { useAsyncLoader, useDataBridge } from "@dutchie/ecommerce-extensions-sdk";
+import {
+  useAsyncLoader,
+  useDataBridge,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
 
 const ProductList = () => {
   const { dataLoaders } = useDataBridge();
@@ -92,33 +186,33 @@ const ProductList = () => {
 };
 ```
 
-## Data Types
+### Components & HOCs
+
+#### `RemoteBoundaryComponent<P>`
 
-### `CommerceComponentsDataInterface`
+A type that all extension components must satisfy to integrate with the Dutchie platform. This ensures proper data bridge version compatibility and context provision.
 
-The main interface providing access to all platform data and functionality. [Full interface can be found here](./src/types/interface.ts).
+**Type Signature:**
 
 ```typescript
-interface CommerceComponentsDataInterface {
-  menuContext: "store-front" | "kiosk";
-  location?: Dispensary;
-  user?: User;
-  cart?: Cart;
-  dataLoaders: DataLoaders;
-  actions: Actions;
-}
+type RemoteBoundaryComponent<P = {}> = React.FC<P> & {
+  DataBridgeVersion: string;
+};
 ```
 
-## Extension Components
-
-### `RemoteBoundaryComponent`
+**Properties:**
 
-All extension components that integrate with the Dutchie platform should satisfy the `RemoteBoundaryComponent` type.
+- Component must be a functional React component
+- Must have a `DataBridgeVersion` static property matching the SDK version
 
 **Example:**
 
 ```tsx
-import { RemoteBoundaryComponent, useDataBridge, DataBridgeVersion } from "@dutchie/ecommerce-extensions-sdk";
+import {
+  RemoteBoundaryComponent,
+  DataBridgeVersion,
+  useDataBridge,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
 
 const MyCustomHeader: RemoteBoundaryComponent = () => {
   const { location, user, actions } = useDataBridge();
@@ -126,399 +220,1402 @@ const MyCustomHeader: RemoteBoundaryComponent = () => {
   return (
     <header>
       <h1>{location?.name}</h1>
-      {user ? <span>Welcome, {user.firstName}!</span> : <button onClick={actions.goToLogin}>Login</button>}
+      {user ? (
+        <span>Welcome, {user.firstName}!</span>
+      ) : (
+        <button onClick={actions.goToLogin}>Login</button>
+      )}
     </header>
   );
 };
 
+// Required: Set the DataBridgeVersion
 MyCustomHeader.DataBridgeVersion = DataBridgeVersion;
+
+export default MyCustomHeader;
 ```
 
-## Actions API
+#### `withRemoteBoundary(WrappedComponent)`
 
-The actions object provides pre-built functions for common e-commerce operations.
+A higher-order component (HOC) that wraps a component with the Data Bridge context provider.
 
-It can be used to route:
+**Signature:**
 
 ```typescript
-const { actions } = useDataBridge();
+function withRemoteBoundary(
+  WrappedComponent: ComponentType
+): RemoteBoundaryComponent;
+```
 
-actions.goToLogin(); // Navigate to login page
+**Parameters:**
 
-// Product & category navigation
-actions.goToProductDetails("product-123"); // Navigate to product details
-```
+- `WrappedComponent` - The component to wrap with Data Bridge context
 
-Or to update state:
+**Returns:** A `RemoteBoundaryComponent` with Data Bridge context
 
-```typescript
-const { actions } = useDataBridge();
+**Example:**
+
+```tsx
+import { withRemoteBoundary } from "@dutchiesdk/ecommerce-extensions-sdk";
 
-actions.addToCart("product-123", 2); // Add 2 items to cart
-actions.clearCart(); // Remove all items from cart
+const MyComponent = () => {
+  return <div>My Component</div>;
+};
+
+export default withRemoteBoundary(MyComponent);
 ```
 
-## Data Loaders
+#### `createLazyRemoteBoundaryComponent(importFn, options?)`
 
-Async functions for loading platform data. All loaders return promises that resolve to arrays.
+Creates a lazy-loaded remote boundary component with automatic code splitting and error handling.
 
-```typescript
-const { dataLoaders } = useDataBridge();
+**Signature:**
 
-// Location data
-const locations = await dataLoaders.getAllLocations(); // All dispensary locations
-const currentLocations = await dataLoaders.locations(); // Current context locations
+```typescript
+function createLazyRemoteBoundaryComponent<P = WithRemoteBoundaryProps>(
+  importFn: () => Promise<{ default: ComponentType }>,
+  options?: LazyRemoteBoundaryOptions
+): RemoteBoundaryComponent<P>;
 ```
 
-**Note:** All data loaders return empty arrays (`[]`) when no data is available.
+**Parameters:**
+
+- `importFn` - A function that returns a dynamic import promise
+- `options` - Optional configuration object:
+  - `fallback?: ReactNode` - Component to show while loading
+  - `onError?: (error: Error) => void` - Error handler callback
+
+**Returns:** A lazy-loaded `RemoteBoundaryComponent`
+
+**Example:**
 
-## Events
+```tsx
+import { createLazyRemoteBoundaryComponent } from "@dutchiesdk/ecommerce-extensions-sdk";
+
+// Basic usage
+const LazyHeader = createLazyRemoteBoundaryComponent(
+  () => import("./components/Header")
+);
+
+// With options
+const LazyFooter = createLazyRemoteBoundaryComponent(
+  () => import("./components/Footer"),
+  {
+    fallback: <div>Loading footer...</div>,
+    onError: (error) => console.error("Failed to load footer:", error),
+  }
+);
+```
 
-You can register callback functions that will be triggered by certain events in the Dutchie platform in your extension's `RemoteModuleRegistry` object.
+### Context
 
-## Meta Fields Function
+#### `DataBridgeContext`
 
-### Overview
+The React context that provides the Data Bridge interface to all components.
 
-The `getStoreFrontMetaFields` function is the **recommended approach** for generating page metadata (title tags, meta descriptions, Open Graph tags, etc.) in your theme. This function-based approach replaces the `StoreFrontMeta` component pattern.
+**Type:**
 
-**Why use this approach:**
+```typescript
+React.Context<CommerceComponentsDataInterface | undefined>;
+```
 
-- ✅ **Full data access** - Direct access to data loaders (products, categories, etc.)
-- ✅ **Async support** - Make API calls to fetch data for dynamic meta tags
-- ✅ **Centralized control** - Single function handles all page metadata logic
-- ✅ **Better performance** - Called once per navigation, not re-rendered on state changes
+**Usage:**
 
-> **🚀 Rollout Status:** The Dutchie platform is currently rolling out support for `getStoreFrontMetaFields` via a feature flag. During the transition period:
->
-> - When the flag is **enabled**: Your `getStoreFrontMetaFields` function will be used (recommended)
-> - When the flag is **disabled**: The legacy `StoreFrontMeta` component will be used
-> - Both implementations can coexist in your theme during migration
-> - The component approach will be deprecated once the rollout is complete
+Typically you'll use the `useDataBridge()` hook instead of accessing the context directly. However, you can use it for testing or advanced scenarios:
 
-> **Note:** When you provide `getStoreFrontMetaFields` and the feature flag is enabled, the `StoreFrontMeta` component will not be used. We recommend implementing the function approach now to prepare for the full migration
+```tsx
+import { DataBridgeContext } from "@dutchiesdk/ecommerce-extensions-sdk";
 
-### Function Signature
+// Testing example
+const mockDataBridge = {
+  menuContext: "store-front" as const,
+  location: { id: "1", name: "Test Dispensary" },
+  dataLoaders: {
+    /* ... */
+  },
+  actions: {
+    /* ... */
+  },
+};
 
-```typescript
-export type StoreFrontMetaFieldsFunction = (data: CommerceComponentsDataInterface) => MetaFields | Promise<MetaFields>;
+render(
+  <DataBridgeContext.Provider value={mockDataBridge}>
+    <MyComponent />
+  </DataBridgeContext.Provider>
+);
 ```
 
-The function receives the full data bridge interface and can return meta fields synchronously or asynchronously.
+#### `DataBridgeVersion`
 
-### Meta Fields Type
+A string constant representing the current SDK version, used for compatibility checking.
 
-```typescript
-type MetaFields = {
-  title?: string; // Page title
-  description?: string; // Meta description
-  ogImage?: string; // Open Graph image URL
-  canonical?: string; // Canonical URL
-  structuredData?: Record<string, any>; // JSON-LD structured data
-  customMeta?: Array<{
-    // Additional meta tags
-    name?: string;
-    property?: string;
-    content: string;
-  }>;
+**Type:** `string`
+
+**Usage:**
+
+```tsx
+import {
+  DataBridgeVersion,
+  RemoteBoundaryComponent,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
+
+const MyComponent: RemoteBoundaryComponent = () => {
+  return <div>Component</div>;
 };
+
+MyComponent.DataBridgeVersion = DataBridgeVersion;
 ```
 
-### Implementation
+### Types
 
-Create a file in your theme (e.g., `get-meta-fields.ts`):
+The SDK exports comprehensive TypeScript types for all data structures. Here are the key types:
+
+#### Core Interface Types
 
 ```typescript
-import { CommerceComponentsDataInterface, MetaFields } from "@dutchiesdk/ecommerce-extensions-sdk";
+import type {
+  // Main interface
+  CommerceComponentsDataInterface,
+
+  // Component types
+  RemoteBoundaryComponent,
+  RemoteModuleRegistry,
+
+  // Data types
+  Actions,
+  DataLoaders,
+  Cart,
+  CartItem,
+  User,
+  Dispensary,
+  Product,
+  Brand,
+  Category,
+  Collection,
+  Special,
+
+  // Metadata
+  MetaFields,
+  StoreFrontMetaFieldsFunction,
+
+  // Events
+  Events,
+  OnAfterCheckoutData,
+
+  // Context
+  MenuContext,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
+```
 
-export const getStoreFrontMetaFields = async (data: CommerceComponentsDataInterface): Promise<MetaFields> => {
-  const { location, dataLoaders } = data;
-  const page = typeof window !== "undefined" ? window.location.pathname : "";
+## Data Interface
 
-  // Access data loaders for dynamic content
-  const product = await dataLoaders.product();
-  const categories = await dataLoaders.categories();
+### Actions API
 
-  // Generate page-specific metadata
-  let pageTitle = location?.name || "Shop Cannabis";
-  let pageDescription = `Browse our selection at ${location?.name}`;
+The `actions` object provides pre-built functions for common e-commerce operations. All actions are accessible via the `useDataBridge()` hook.
 
-  if (product) {
-    pageTitle = `${product.name} | ${location?.name}`;
-    pageDescription = `${product.description?.substring(0, 155)}...`;
-  }
+#### Navigation Actions
 
-  return {
-    title: pageTitle,
-    description: pageDescription,
-    ogImage: location?.images?.logo,
-    canonical: `${location?.links?.storeFrontRoot}${page}`,
-    structuredData: {
-      "@context": "https://schema.org",
-      "@type": "WebPage",
-      name: pageTitle,
-      description: pageDescription,
-    },
-    customMeta: [
-      {
-        name: "robots",
-        content: "index, follow",
-      },
-    ],
-  };
-};
+```typescript
+// Store navigation
+actions.goToStoreFront(params?: { query?: Record<string, string> }): void
+actions.goToStore(params: { id?: string; cname?: string; query?: Record<string, string> }): void
+actions.goToInfoPage(params?: { query?: Record<string, string> }): void
+
+// Browse and search
+actions.goToStoreBrowser(params?: { query?: Record<string, string> }): void
+actions.goToStoreLocator(params?: { query?: Record<string, string> }): void
+actions.goToSearch(query?: string, params?: { query?: Record<string, string> }): void
 ```
 
-### Register in Module Registry
+**Example:**
 
-Add the function to your theme's `index.tsx`:
+```tsx
+const { actions } = useDataBridge();
 
-```typescript
-import { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
-import { getStoreFrontMetaFields } from "./get-meta-fields";
+// Navigate to home page
+actions.goToStoreFront();
 
-export default {
-  StoreFrontHeader: createLazyRemoteBoundaryComponent(() => import("./header")),
-  StoreFrontFooter: createLazyRemoteBoundaryComponent(() => import("./footer")),
-  getStoreFrontMetaFields, // Register the function
-} satisfies RemoteModuleRegistry;
+// Navigate with query params
+actions.goToSearch("edibles", { query: { sort: "price-asc" } });
 ```
 
-You may also register components for only specific menu contexts:
+#### Product & Category Navigation
 
 ```typescript
-import { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
-
-export default {
-  StoreFrontHeader: {
-    // use one component for storefront and a different one for kiosk
-    'store-front': createLazyRemoteBoundaryComponent(() => import("./store-header")),
-    kiosk: createLazyRemoteBoundaryComponent(() => import("./kiosk-header")),
-  },
-  StoreFrontFooter: {
-    // only override storefront but not kiosk, kiosk will have default dutchie footer
-    'store-front': createLazyRemoteBoundaryComponent(() => import("./footer")),
-  },
-} satisfies RemoteModuleRegistry;
+// Product details
+actions.goToProductDetails(params: {
+  id?: string;
+  cname?: string;
+  query?: Record<string, string>;
+}): void
+
+// Category pages
+actions.goToCategory(params: {
+  id?: string;
+  cname?: string;
+  query?: Record<string, string>;
+}): void
+
+// Brand pages
+actions.goToBrand(params: {
+  id?: string;
+  cname?: string;
+  query?: Record<string, string>;
+}): void
+
+// Collection pages
+actions.goToCollection(params: {
+  id?: string;
+  cname?: string;
+  query?: Record<string, string>;
+}): void
+
+// Special pages
+actions.goToSpecial(params: {
+  id: string;
+  type: 'offer' | 'sale';
+  query?: Record<string, string>;
+}): void
 ```
 
-### Available Data
+**Example:**
 
-The function receives the full `CommerceComponentsDataInterface`:
+```tsx
+const { actions } = useDataBridge();
 
-```typescript
-{
-  menuContext: 'store-front' | 'kiosk',
-  location?: Dispensary,
-  user?: User,
-  cart?: Cart,
-  dataLoaders: {
-    product: () => Promise<Product | null>,
-    products: () => Promise<Product[]>,
-    categories: () => Promise<Category[]>,
-    // ... other loaders
-  },
-  actions: {
-    // Navigation and cart actions
-  }
-}
-```
+// Navigate by ID
+actions.goToProductDetails({ id: "product-123" });
 
-### Example Use Cases
+// Navigate by cname (URL-friendly name)
+actions.goToCategory({ cname: "edibles" });
+
+// With query params
+actions.goToBrand({
+  cname: "kiva-confections",
+  query: { filter: "chocolate" },
+});
+```
 
-**Product Pages:**
+#### List Page Actions
 
 ```typescript
-const product = await dataLoaders.product();
-if (product) {
-  return {
-    title: `${product.name} - ${location?.name}`,
-    description: product.description,
-    ogImage: product.images?.[0]?.url,
-    structuredData: {
-      "@context": "https://schema.org",
-      "@type": "Product",
-      name: product.name,
-      description: product.description,
-      offers: {
-        "@type": "Offer",
-        price: product.variants?.[0]?.priceRec,
-        priceCurrency: "USD",
-      },
-    },
-  };
-}
+// Product list with filters
+actions.goToProductList(params: {
+  brandId?: string;
+  brandCname?: string;
+  categoryId?: string;
+  categoryCname?: string;
+  collectionId?: string;
+  collectionCname?: string;
+  query?: Record<string, string>;
+}): void
+
+// List pages
+actions.goToBrandList(params?: { query?: Record<string, string> }): void
+actions.goToSpecialsList(params?: { query?: Record<string, string> }): void
 ```
 
-**Category Pages:**
+**Example:**
 
-```typescript
-const categories = await dataLoaders.categories();
-const pathname = window.location.pathname;
-const categorySlug = pathname.split("/").pop();
-const category = categories.find((c) => c.slug === categorySlug);
+```tsx
+const { actions } = useDataBridge();
 
-if (category) {
-  return {
-    title: `${category.name} | ${location?.name}`,
-    description: `Shop ${category.name} products at ${location?.name}`,
-  };
-}
-```
+// Show products in a category
+actions.goToProductList({ categoryCname: "edibles" });
 
-**Home Page:**
+// Show products by brand and category
+actions.goToProductList({
+  brandCname: "kiva-confections",
+  categoryCname: "chocolate",
+  query: { sort: "popular" },
+});
 
-```typescript
-if (pathname === "/" || pathname === "") {
-  return {
-    title: `${location?.name} - Cannabis Dispensary`,
-    description: `Shop cannabis products online at ${location?.name}`,
-    structuredData: {
-      "@context": "https://schema.org",
-      "@type": "Organization",
-      name: location?.name,
-      url: location?.links?.storeFrontRoot,
-      logo: location?.images?.logo,
-    },
-  };
-}
+// Show all brands
+actions.goToBrandList();
 ```
 
-### Notes
+#### Cart Actions
 
-- The function is called on every page navigation
-- Async operations (like `dataLoaders.product()`) are supported
-- Return values are rendered into `<head>` tags automatically
-- The title tag will update dynamically as meta fields load
-- All fields are optional - return only what's needed for each page
+```typescript
+// Add items to cart
+actions.addToCart(item: CartItem): Promise<void>
 
-### Migration Strategy
+// Remove items from cart
+actions.removeFromCart(item: CartItem): void
 
-If you have an existing theme using the `StoreFrontMeta` component:
+// Update cart item
+actions.updateCartItem(existingItem: CartItem, newItem: CartItem): void
 
-1. **Implement the function**: Add `getStoreFrontMetaFields` to your theme's module registry
-2. **Test both approaches**: Keep your existing `StoreFrontMeta` component during the transition
-3. **Feature flag controls behavior**: Dutchie's feature flag determines which implementation is used
-4. **Future-proof**: Once the rollout completes, only the function approach will be supported
+// Clear cart
+actions.clearCart(): void
 
-## Best Practices
+// Cart visibility
+actions.showCart(): void
+actions.hideCart(): void
 
-### Data Loading
+// Checkout
+actions.goToCheckout(): void
+
+// Pricing type
+actions.updatePricingType(pricingType: 'med' | 'rec'): void
+```
 
-When using the `useDataBridge()` hook in a component, always handle loading states:
+**Example:**
 
 ```tsx
-const MyComponent = () => {
-  const { dataLoaders } = useDataBridge();
-  const { data, isLoading } = useAsyncLoader(dataLoaders.products);
+const { actions } = useDataBridge();
 
-  if (isLoading) return <LoadingSpinner />;
-  if (!data) return <EmptyProducts message="No products found" />;
+// Add product to cart
+await actions.addToCart({
+  productId: "product-123",
+  name: "Chocolate Bar",
+  option: "10mg",
+  price: 25.0,
+  quantity: 2,
+});
 
-  return <ProductList products={data} />;
-};
+// Update quantity
+actions.updateCartItem(existingItem, { ...existingItem, quantity: 3 });
+
+// Show cart sidebar
+actions.showCart();
+
+// Proceed to checkout
+actions.goToCheckout();
 ```
 
-### Error Handling
+#### Authentication Actions
 
-Any uncaught errors will be caught by a Dutchie error boundary, and the fallback will be rendered.
+```typescript
+// Navigate to login page
+actions.goToLogin(): void
+
+// Navigate to registration page
+actions.goToRegister(): void
 
-### TypeScript Best Practices
+// Navigate to loyalty page (redirects to home if not logged in)
+actions.goToLoyalty(params?: { query?: Record<string, string> }): void
+```
 
-Leverage the provided types for better development experience:
+**Example:**
 
 ```tsx
-import { Product, Category, useDataBridge } from "@dutchie/ecommerce-extensions-sdk";
+const { user, actions } = useDataBridge();
 
-interface ProductFilterProps {
-  products: Product[];
-  categories: Category[];
-  onFilterChange: (categoryId: string) => void;
+if (!user) {
+  return (
+    <div>
+      <button onClick={actions.goToLogin}>Login</button>
+      <button onClick={actions.goToRegister}>Sign Up</button>
+    </div>
+  );
 }
+```
 
-const ProductFilter: React.FC<ProductFilterProps> = ({ products, categories, onFilterChange }) => {
-  // Implementation
-};
+### Data Loaders
+
+Async functions for loading platform data. All loaders return promises and are accessible via `useDataBridge()`.
+
+#### Available Data Loaders
+
+```typescript
+interface DataLoaders {
+  // Product catalog
+  products(): Promise<Product[]>;
+  product(): Promise<Product | null>; // Only populated on product detail pages
+
+  // Taxonomy
+  categories(): Promise<Category[]>;
+  brands(): Promise<Brand[]>;
+  collections(): Promise<Collection[]>;
+
+  // Promotions
+  specials(): Promise<Special[]>;
+
+  // Store locations
+  locations(): Promise<Dispensary[]>;
+
+  // Integration data
+  integrationValue(key: string): Promise<string | undefined>;
+}
 ```
 
-### Context Usage
+**Return Values:**
+
+- All list loaders return empty arrays (`[]`) when no data is available
+- `product()` returns `null` when not on a product details page
+- `integrationValue()` returns `undefined` when key is not found
 
-Always check for data availability before using:
+**Example:**
 
 ```tsx
-const UserProfile = () => {
-  const { user, actions } = useDataBridge();
+import {
+  useDataBridge,
+  useAsyncLoader,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
 
-  if (!user) {
-    return (
-      <div className="login-prompt">
-        <p>Please log in to view your profile</p>
-        <button onClick={actions.goToLogin}>Login</button>
-      </div>
-    );
-  }
+const ProductCatalog = () => {
+  const { dataLoaders } = useDataBridge();
+
+  // Load products with loading state
+  const { data: products, isLoading } = useAsyncLoader(dataLoaders.products);
+
+  // Load categories
+  const { data: categories } = useAsyncLoader(dataLoaders.categories);
+
+  if (isLoading) return <div>Loading...</div>;
 
   return (
-    <div className="user-profile">
-      <h2>Welcome, {user.firstName}!</h2>
-      {/* Profile content */}
+    <div>
+      <h1>Products ({products?.length || 0})</h1>
+      {/* Render products */}
     </div>
   );
 };
 ```
 
-### Testing
+**Direct usage (async/await):**
 
 ```tsx
-import { render, screen } from "@testing-library/react";
-import { DataBridgeContext } from "@dutchie/ecommerce-extensions-sdk";
-import MyExtension from "./MyExtension";
-
-const mockDataBridge = {
-  menuContext: "store-front" as const,
-  location: { id: "1", name: "Test Dispensary" },
-  dataLoaders: {
-    products: jest.fn().mockResolvedValue([]),
-    // ... other loaders
-  },
-  actions: {
-    addToCart: jest.fn(),
-    // ... other actions
-  },
-};
+const MyComponent = () => {
+  const { dataLoaders } = useDataBridge();
+  const [products, setProducts] = useState<Product[]>([]);
 
-test("renders extension correctly", () => {
-  render(
-    <DataBridgeContext.Provider value={mockDataBridge}>
-      <MyExtension />
-    </DataBridgeContext.Provider>
-  );
+  useEffect(() => {
+    dataLoaders.products().then(setProducts);
+  }, [dataLoaders]);
 
-  expect(screen.getByText("Test Dispensary")).toBeInTheDocument();
-});
+  return <ProductList products={products} />;
+};
 ```
 
-## Core Concepts
+### Data Types
 
-The Dutchie Ecommerce Extensions SDK is built around several key concepts:
+#### Cart
 
-1. **Data Bridge**: A unified interface for accessing dispensary data, user information, and cart state
-2. **Actions**: Pre-built navigation and cart management functions
-3. **Remote Components**: Extension components that integrate seamlessly with the Dutchie platform
-4. **Context-Driven Architecture**: React context provides data and actions throughout your extension
+```typescript
+type Cart = {
+  discount: number; // Total discount amount
+  items: CartItem[]; // Array of cart items
+  subtotal: number; // Subtotal before tax and discounts
+  tax: number; // Tax amount
+  total: number; // Final total
+};
 
-## Support
+type CartItem = {
+  productId: string; // Unique product identifier
+  name: string; // Product name
+  price: number; // Price per unit
+  quantity: number; // Quantity in cart
+  option?: string; // Variant option (e.g., "10mg", "1g")
+  additionalOption?: string; // Advanced use only
+};
+```
 
-For technical support and questions about the Dutchie Ecommerce Extensions SDK:
+#### User
 
-- 📧 Contact your Dutchie agency partner representative
-- 📚 Refer to the Dutchie Pro platform documentation
-- 🐛 Report issues through the official Dutchie support channels
+```typescript
+type User = {
+  email: string;
+  firstName: string;
+  lastName: string;
+  birthday: string; // ISO date string
+};
+```
 
-## Updates
+#### Dispensary
 
-Stay up to date with this SDK by checking here for changes, and updating to the latest version with:
+```typescript
+type Dispensary = {
+  id: string;
+  name: string;
+  cname: string; // URL-friendly name
+  chain: string; // Chain/brand name
+  email: string;
+  phone: string;
+  status: string; // Operating status
+  medDispensary: boolean; // Supports medical
+  recDispensary: boolean; // Supports recreational
+
+  address: {
+    street1: string;
+    street2: string;
+    city: string;
+    state: string;
+    stateAbbreviation: string;
+    zip: string;
+  };
+
+  images: {
+    logo: string; // Logo URL
+  };
+
+  links: {
+    website: string; // Dispensary website
+    storeFrontRoot: string; // Store front base URL
+  };
+
+  orderTypes: {
+    pickup: boolean;
+    delivery: boolean;
+    curbsidePickup: boolean;
+    inStorePickup: boolean;
+    driveThruPickup: boolean;
+    kiosk: boolean;
+  };
+
+  orderTypesConfig: {
+    offerAnyPickupService?: boolean;
+    offerDeliveryService?: boolean;
+    curbsidePickup?: OrderTypeConfig;
+    delivery?: OrderTypeConfig;
+    driveThruPickup?: OrderTypeConfig;
+    inStorePickup?: OrderTypeConfig;
+  };
+
+  hours: {
+    curbsidePickup?: HoursSettingsForOrderType;
+    delivery?: HoursSettingsForOrderType;
+    driveThruPickup?: HoursSettingsForOrderType;
+    inStorePickup?: HoursSettingsForOrderType;
+  };
+};
+
+type OrderTypeConfig = {
+  enableAfterHoursOrdering?: boolean;
+  enableASAPOrdering?: boolean;
+  enableScheduledOrdering?: boolean;
+};
+
+type HoursSettingsForOrderType = {
+  enabled: boolean;
+  effectiveHours?: {
+    Monday?: DayHours;
+    Tuesday?: DayHours;
+    Wednesday?: DayHours;
+    Thursday?: DayHours;
+    Friday?: DayHours;
+    Saturday?: DayHours;
+    Sunday?: DayHours;
+  };
+};
+
+type DayHours = {
+  active?: boolean;
+  start?: string; // Time string (e.g., "09:00")
+  end?: string; // Time string (e.g., "21:00")
+};
+```
+
+#### Product
+
+```typescript
+type Product = {
+  id: string;
+  cname: string; // URL-friendly name
+  name: string;
+  description: string;
+  image: string; // Primary image URL
+  price: number;
+};
+```
+
+#### Brand
+
+```typescript
+type Brand = {
+  id: string;
+  cname: string; // URL-friendly name
+  name: string;
+  image?: string | null; // Brand logo URL
+};
+```
+
+#### Category
+
+```typescript
+type Category = {
+  id: string;
+  cname: string; // URL-friendly name (e.g., "edibles")
+  name: string; // Display name (e.g., "Edibles")
+};
+```
+
+#### Collection
+
+```typescript
+type Collection = {
+  id: string;
+  cname: string; // URL-friendly name
+  name: string;
+};
+```
+
+#### Special
+
+```typescript
+type Special = {
+  id: string;
+  cname: string;
+  name: string;
+  description: string;
+  image: string;
+};
+```
+
+#### Menu Context
+
+```typescript
+type MenuContext = "store-front" | "kiosk";
+```
+
+The menu context indicates which interface the extension is running in:
+
+- `'store-front'` - Online storefront for customers
+- `'kiosk'` - In-store kiosk interface
+
+## Extension Development
+
+### Creating Components
+
+All extension components should satisfy the `RemoteBoundaryComponent` type and set the `DataBridgeVersion` property.
+
+**Basic Component:**
+
+```tsx
+import {
+  RemoteBoundaryComponent,
+  DataBridgeVersion,
+  useDataBridge,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
+
+const Header: RemoteBoundaryComponent = () => {
+  const { location, user, actions } = useDataBridge();
+
+  return (
+    <header>
+      <h1>{location?.name}</h1>
+      {user && <span>Welcome, {user.firstName}</span>}
+    </header>
+  );
+};
+
+Header.DataBridgeVersion = DataBridgeVersion;
+
+export default Header;
+```
+
+**Component with Props:**
+
+```tsx
+import type { RemoteBoundaryComponent } from "@dutchiesdk/ecommerce-extensions-sdk";
+import {
+  DataBridgeVersion,
+  useDataBridge,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
+
+interface CustomHeaderProps {
+  showLogo?: boolean;
+  className?: string;
+}
+
+const CustomHeader: RemoteBoundaryComponent<CustomHeaderProps> = ({
+  showLogo = true,
+  className,
+}) => {
+  const { location } = useDataBridge();
+
+  return (
+    <header className={className}>
+      {showLogo && <img src={location?.images.logo} alt={location?.name} />}
+      <h1>{location?.name}</h1>
+    </header>
+  );
+};
+
+CustomHeader.DataBridgeVersion = DataBridgeVersion;
+
+export default CustomHeader;
+```
+
+### Module Registry
+
+The `RemoteModuleRegistry` type defines all available extension points in the Dutchie platform.
+
+```typescript
+type RemoteModuleRegistry = {
+  // UI Components
+  StoreFrontHeader?: ModuleRegistryEntry;
+  StoreFrontNavigation?: ModuleRegistryEntry;
+  StoreFrontFooter?: ModuleRegistryEntry;
+  StoreFrontHero?: ModuleRegistryEntry;
+  StoreFrontCarouselInterstitials?: ModuleRegistryEntry[];
+  ProductDetailsPrimary?: ModuleRegistryEntry;
+
+  // Custom routable pages
+  RouteablePages?: RoutablePageRegistryEntry[];
+
+  // Metadata function
+  getStoreFrontMetaFields?: StoreFrontMetaFieldsFunction;
+
+  // Event handlers
+  events?: Events;
+
+  // Deprecated - use getStoreFrontMetaFields instead
+  StoreFrontMeta?: RemoteBoundaryComponent;
+  ProductDetailsMeta?: RemoteBoundaryComponent;
+};
+
+type ModuleRegistryEntry =
+  | RemoteBoundaryComponent
+  | MenuSpecificRemoteComponent;
+
+type MenuSpecificRemoteComponent = {
+  "store-front"?: RemoteBoundaryComponent;
+  kiosk?: RemoteBoundaryComponent;
+};
+
+type RoutablePageRegistryEntry = {
+  path: string;
+  component: RemoteBoundaryComponent;
+};
+```
+
+**Basic Registry:**
+
+```tsx
+import type { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
+import { createLazyRemoteBoundaryComponent } from "@dutchiesdk/ecommerce-extensions-sdk";
+
+export default {
+  StoreFrontHeader: createLazyRemoteBoundaryComponent(() => import("./Header")),
+  StoreFrontFooter: createLazyRemoteBoundaryComponent(() => import("./Footer")),
+} satisfies RemoteModuleRegistry;
+```
+
+**Menu-Specific Components:**
+
+```tsx
+import type { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
+import { createLazyRemoteBoundaryComponent } from "@dutchiesdk/ecommerce-extensions-sdk";
+
+export default {
+  StoreFrontHeader: {
+    // Different header for storefront vs kiosk
+    "store-front": createLazyRemoteBoundaryComponent(
+      () => import("./StoreHeader")
+    ),
+    kiosk: createLazyRemoteBoundaryComponent(() => import("./KioskHeader")),
+  },
+  StoreFrontFooter: {
+    // Only override storefront, use default Dutchie footer for kiosk
+    "store-front": createLazyRemoteBoundaryComponent(() => import("./Footer")),
+  },
+} satisfies RemoteModuleRegistry;
+```
+
+**Custom Routable Pages:**
+
+```tsx
+import type { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
+import { createLazyRemoteBoundaryComponent } from "@dutchiesdk/ecommerce-extensions-sdk";
+
+export default {
+  RouteablePages: [
+    {
+      path: "/about",
+      component: createLazyRemoteBoundaryComponent(
+        () => import("./pages/About")
+      ),
+    },
+    {
+      path: "/contact",
+      component: createLazyRemoteBoundaryComponent(
+        () => import("./pages/Contact")
+      ),
+    },
+  ],
+} satisfies RemoteModuleRegistry;
+```
+
+### Meta Fields & SEO
+
+The `getStoreFrontMetaFields` function allows you to dynamically generate page metadata (title, description, Open Graph tags, structured data) based on the current page and available data.
+
+> **🚀 Rollout Status:** The Dutchie platform is currently rolling out support for `getStoreFrontMetaFields` via a feature flag. During the transition period:
+>
+> - When the flag is **enabled**: Your `getStoreFrontMetaFields` function will be used (recommended)
+> - When the flag is **disabled**: The legacy `StoreFrontMeta` component will be used
+> - Both implementations can coexist in your theme during migration
+> - The component approach will be deprecated once the rollout is complete
+
+#### Meta Fields Type
+
+```typescript
+type MetaFields = {
+  title?: string; // Page title
+  description?: string; // Meta description
+  ogImage?: string; // Open Graph image URL
+  canonical?: string; // Canonical URL
+  structuredData?: Record<string, any>; // JSON-LD structured data
+  customMeta?: Array<{
+    // Additional meta tags
+    name?: string;
+    property?: string;
+    content: string;
+  }>;
+};
+
+type StoreFrontMetaFieldsFunction = (
+  data: CommerceComponentsDataInterface
+) => MetaFields | Promise<MetaFields>;
+```
+
+#### Implementation
+
+Create a meta fields function (e.g., `get-meta-fields.ts`):
+
+```typescript
+import type {
+  CommerceComponentsDataInterface,
+  MetaFields,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
+
+export const getStoreFrontMetaFields = async (
+  data: CommerceComponentsDataInterface
+): Promise<MetaFields> => {
+  const { location, dataLoaders } = data;
+  const pathname =
+    typeof window !== "undefined" ? window.location.pathname : "";
+
+  // Load data for current page
+  const product = await dataLoaders.product();
+  const categories = await dataLoaders.categories();
+
+  // Product detail page
+  if (product) {
+    return {
+      title: `${product.name} | ${location?.name}`,
+      description: product.description.substring(0, 155),
+      ogImage: product.image,
+      canonical: `${location?.links.storeFrontRoot}${pathname}`,
+      structuredData: {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        name: product.name,
+        description: product.description,
+        image: product.image,
+        offers: {
+          "@type": "Offer",
+          price: product.price,
+          priceCurrency: "USD",
+        },
+      },
+    };
+  }
+
+  // Category page
+  const categorySlug = pathname.split("/").pop();
+  const category = categories.find((c) => c.cname === categorySlug);
+  if (category) {
+    return {
+      title: `${category.name} | ${location?.name}`,
+      description: `Shop ${category.name} products at ${location?.name}`,
+      canonical: `${location?.links.storeFrontRoot}${pathname}`,
+    };
+  }
+
+  // Home page
+  if (pathname === "/" || pathname === "") {
+    return {
+      title: `${location?.name} - Cannabis Dispensary`,
+      description: `Shop cannabis products online at ${location?.name}`,
+      ogImage: location?.images.logo,
+      canonical: location?.links.storeFrontRoot,
+      structuredData: {
+        "@context": "https://schema.org",
+        "@type": "Organization",
+        name: location?.name,
+        url: location?.links.storeFrontRoot,
+        logo: location?.images.logo,
+      },
+      customMeta: [
+        {
+          name: "robots",
+          content: "index, follow",
+        },
+      ],
+    };
+  }
+
+  // Default fallback
+  return {
+    title: location?.name || "Shop Cannabis",
+    description: `Browse our selection at ${location?.name}`,
+  };
+};
+```
+
+Register in your module registry:
+
+```typescript
+import type { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
+import { getStoreFrontMetaFields } from "./get-meta-fields";
+
+export default {
+  StoreFrontHeader: createLazyRemoteBoundaryComponent(() => import("./Header")),
+  StoreFrontFooter: createLazyRemoteBoundaryComponent(() => import("./Footer")),
+  getStoreFrontMetaFields,
+} satisfies RemoteModuleRegistry;
+```
+
+### Event Handlers
+
+Register callbacks that are triggered by platform events.
+
+```typescript
+type Events = {
+  onAfterCheckout?: (data: OnAfterCheckoutData) => void;
+};
+
+type OnAfterCheckoutData = {
+  orderNumber: string;
+};
+```
+
+**Example:**
+
+```typescript
+import type { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
+
+export default {
+  // ... components
+
+  events: {
+    onAfterCheckout: (data) => {
+      console.log("Order completed:", data.orderNumber);
+
+      // Track conversion in analytics
+      gtag("event", "purchase", {
+        transaction_id: data.orderNumber,
+      });
+    },
+  },
+} satisfies RemoteModuleRegistry;
+```
+
+## Best Practices
+
+### Always Handle Loading States
+
+When using data loaders, always handle loading and empty states:
+
+```tsx
+const ProductList = () => {
+  const { dataLoaders } = useDataBridge();
+  const { data: products, isLoading } = useAsyncLoader(dataLoaders.products);
+
+  if (isLoading) {
+    return <LoadingSpinner />;
+  }
+
+  if (!products || products.length === 0) {
+    return <EmptyState message="No products available" />;
+  }
+
+  return (
+    <div>
+      {products.map((product) => (
+        <ProductCard key={product.id} product={product} />
+      ))}
+    </div>
+  );
+};
+```
+
+### Check Data Availability
+
+Always check if optional data is available before using it:
+
+```tsx
+const UserProfile = () => {
+  const { user, actions } = useDataBridge();
+
+  if (!user) {
+    return (
+      <div className="login-prompt">
+        <p>Please log in to view your profile</p>
+        <button onClick={actions.goToLogin}>Login</button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="user-profile">
+      <h2>Welcome, {user.firstName}!</h2>
+      <p>Email: {user.email}</p>
+    </div>
+  );
+};
+```
+
+### Use TypeScript for Better DX
+
+Leverage the provided types for autocomplete and type safety:
+
+```tsx
+import type {
+  Product,
+  Category,
+  RemoteBoundaryComponent,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
+
+interface ProductFilterProps {
+  products: Product[];
+  categories: Category[];
+  onFilterChange: (categoryId: string) => void;
+}
+
+const ProductFilter: React.FC<ProductFilterProps> = ({
+  products,
+  categories,
+  onFilterChange,
+}) => {
+  return (
+    <div>
+      {categories.map((category) => (
+        <button key={category.id} onClick={() => onFilterChange(category.id)}>
+          {category.name}
+        </button>
+      ))}
+    </div>
+  );
+};
+```
+
+### Error Boundaries
+
+Any uncaught errors in your extension will be caught by Dutchie's error boundary. However, you should still handle expected errors gracefully:
+
+```tsx
+const ProductDetails = () => {
+  const { dataLoaders } = useDataBridge();
+  const [error, setError] = useState<string | null>(null);
+  const { data: product, isLoading } = useAsyncLoader(dataLoaders.product);
+
+  if (error) {
+    return <ErrorMessage message={error} />;
+  }
+
+  if (isLoading) {
+    return <LoadingSpinner />;
+  }
+
+  if (!product) {
+    return <NotFound message="Product not found" />;
+  }
+
+  return <ProductCard product={product} />;
+};
+```
+
+### Optimize Performance
+
+Use lazy loading for large components and routes:
+
+```tsx
+import { createLazyRemoteBoundaryComponent } from "@dutchiesdk/ecommerce-extensions-sdk";
+
+// Components will be code-split and loaded on demand
+export default {
+  StoreFrontHeader: createLazyRemoteBoundaryComponent(
+    () => import("./components/Header"),
+    { fallback: <HeaderSkeleton /> }
+  ),
+  StoreFrontFooter: createLazyRemoteBoundaryComponent(
+    () => import("./components/Footer"),
+    { fallback: <FooterSkeleton /> }
+  ),
+} satisfies RemoteModuleRegistry;
+```
+
+### Testing Components
+
+Test your components using the `DataBridgeContext` provider:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { DataBridgeContext } from "@dutchiesdk/ecommerce-extensions-sdk";
+import MyComponent from "./MyComponent";
+
+const mockDataBridge = {
+  menuContext: "store-front" as const,
+  location: {
+    id: "1",
+    name: "Test Dispensary",
+    cname: "test-dispensary",
+    // ... other required fields
+  },
+  dataLoaders: {
+    products: jest.fn().mockResolvedValue([]),
+    categories: jest.fn().mockResolvedValue([]),
+    brands: jest.fn().mockResolvedValue([]),
+    collections: jest.fn().mockResolvedValue([]),
+    specials: jest.fn().mockResolvedValue([]),
+    locations: jest.fn().mockResolvedValue([]),
+    product: jest.fn().mockResolvedValue(null),
+    integrationValue: jest.fn().mockResolvedValue(undefined),
+  },
+  actions: {
+    addToCart: jest.fn(),
+    goToProductDetails: jest.fn(),
+    goToCategory: jest.fn(),
+    // ... other actions
+  },
+};
+
+test("renders component correctly", () => {
+  render(
+    <DataBridgeContext.Provider value={mockDataBridge}>
+      <MyComponent />
+    </DataBridgeContext.Provider>
+  );
+
+  expect(screen.getByText("Test Dispensary")).toBeInTheDocument();
+});
+
+test("handles cart actions", async () => {
+  render(
+    <DataBridgeContext.Provider value={mockDataBridge}>
+      <MyComponent />
+    </DataBridgeContext.Provider>
+  );
+
+  const addButton = screen.getByRole("button", { name: /add to cart/i });
+  addButton.click();
+
+  expect(mockDataBridge.actions.addToCart).toHaveBeenCalledWith({
+    productId: "123",
+    name: "Test Product",
+    price: 25.0,
+    quantity: 1,
+  });
+});
+```
+
+## Examples
+
+### Custom Product Listing
+
+```tsx
+import {
+  RemoteBoundaryComponent,
+  DataBridgeVersion,
+  useDataBridge,
+  useAsyncLoader,
+  type Product,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
+
+const ProductListing: RemoteBoundaryComponent = () => {
+  const { dataLoaders, actions } = useDataBridge();
+  const { data: products, isLoading } = useAsyncLoader(dataLoaders.products);
+  const { data: categories } = useAsyncLoader(dataLoaders.categories);
+  const [filter, setFilter] = useState<string | null>(null);
+
+  const filteredProducts = products?.filter(
+    (p) => !filter || p.categoryId === filter
+  );
+
+  if (isLoading) {
+    return <div className="loading">Loading products...</div>;
+  }
+
+  return (
+    <div className="product-listing">
+      <div className="filters">
+        <button onClick={() => setFilter(null)}>All</button>
+        {categories?.map((cat) => (
+          <button key={cat.id} onClick={() => setFilter(cat.id)}>
+            {cat.name}
+          </button>
+        ))}
+      </div>
+
+      <div className="products-grid">
+        {filteredProducts?.map((product) => (
+          <div
+            key={product.id}
+            className="product-card"
+            onClick={() => actions.goToProductDetails({ id: product.id })}
+          >
+            <img src={product.image} alt={product.name} />
+            <h3>{product.name}</h3>
+            <p>${product.price.toFixed(2)}</p>
+            <button
+              onClick={(e) => {
+                e.stopPropagation();
+                actions.addToCart({
+                  productId: product.id,
+                  name: product.name,
+                  price: product.price,
+                  quantity: 1,
+                });
+              }}
+            >
+              Add to Cart
+            </button>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+ProductListing.DataBridgeVersion = DataBridgeVersion;
+
+export default ProductListing;
+```
+
+### Custom Header with Cart
+
+```tsx
+import {
+  RemoteBoundaryComponent,
+  DataBridgeVersion,
+  useDataBridge,
+} from "@dutchiesdk/ecommerce-extensions-sdk";
+
+const Header: RemoteBoundaryComponent = () => {
+  const { location, user, cart, actions } = useDataBridge();
+
+  const cartItemCount =
+    cart?.items.reduce((sum, item) => sum + item.quantity, 0) || 0;
+
+  return (
+    <header className="site-header">
+      <div className="logo" onClick={() => actions.goToStoreFront()}>
+        <img src={location?.images.logo} alt={location?.name} />
+        <h1>{location?.name}</h1>
+      </div>
+
+      <nav>
+        <button onClick={() => actions.goToProductList({})}>Shop All</button>
+        <button onClick={() => actions.goToSpecialsList()}>Deals</button>
+        <button onClick={() => actions.goToStoreLocator()}>Locations</button>
+      </nav>
+
+      <div className="user-actions">
+        {user ? (
+          <>
+            <span>Hello, {user.firstName}</span>
+            <button onClick={() => actions.goToLoyalty()}>Rewards</button>
+          </>
+        ) : (
+          <>
+            <button onClick={actions.goToLogin}>Login</button>
+            <button onClick={actions.goToRegister}>Sign Up</button>
+          </>
+        )}
+
+        <button className="cart-button" onClick={actions.showCart}>
+          Cart ({cartItemCount})
+        </button>
+      </div>
+    </header>
+  );
+};
+
+Header.DataBridgeVersion = DataBridgeVersion;
+
+export default Header;
+```
+
+### Complete Module Registry Example
+
+```tsx
+import type { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
+import { createLazyRemoteBoundaryComponent } from "@dutchiesdk/ecommerce-extensions-sdk";
+import { getStoreFrontMetaFields } from "./get-meta-fields";
+
+export default {
+  // Header and footer
+  StoreFrontHeader: createLazyRemoteBoundaryComponent(
+    () => import("./components/Header"),
+    { fallback: <div>Loading...</div> }
+  ),
+
+  StoreFrontFooter: createLazyRemoteBoundaryComponent(
+    () => import("./components/Footer")
+  ),
+
+  // Hero section
+  StoreFrontHero: createLazyRemoteBoundaryComponent(
+    () => import("./components/Hero")
+  ),
+
+  // Custom product page
+  ProductDetailsPrimary: createLazyRemoteBoundaryComponent(
+    () => import("./components/ProductDetails")
+  ),
+
+  // Custom routable pages
+  RouteablePages: [
+    {
+      path: "/about",
+      component: createLazyRemoteBoundaryComponent(
+        () => import("./pages/About")
+      ),
+    },
+    {
+      path: "/contact",
+      component: createLazyRemoteBoundaryComponent(
+        () => import("./pages/Contact")
+      ),
+    },
+  ],
+
+  // Meta fields for SEO
+  getStoreFrontMetaFields,
+
+  // Event handlers
+  events: {
+    onAfterCheckout: (data) => {
+      // Track conversion
+      console.log("Order completed:", data.orderNumber);
+
+      // Send to analytics
+      if (typeof gtag !== "undefined") {
+        gtag("event", "purchase", {
+          transaction_id: data.orderNumber,
+        });
+      }
+    },
+  },
+} satisfies RemoteModuleRegistry;
+```
+
+## Support
+
+For technical support and questions about the Dutchie Ecommerce Extensions SDK:
+
+- 📧 Contact your Dutchie agency partner representative
+- 📚 Refer to the Dutchie Pro platform documentation
+- 🐛 Report issues through the official Dutchie support channels
+
+## Updates
+
+Stay up to date with this SDK by checking the repository for changes and updating to the latest version with:
 
 ```bash
 npm install @dutchiesdk/ecommerce-extensions-sdk@latest
+# or
+yarn upgrade @dutchiesdk/ecommerce-extensions-sdk@latest
 ```
+
+## License
+
+MIT
+
+---
+
+**Made with 💚 by Dutchie**