@dutchiesdk/ecommerce-extensions-sdk 0.16.0 → 0.18.0

package/README.md

@@ -26,11 +26,7 @@ yarn add @dutchie/ecommerce-extensions-sdk
 
 ```tsx
 import React from "react";
-import {
-  useDataBridge,
-  RemoteBoundaryComponent,
-  DataBridgeVersion,
-} from "@dutchie/ecommerce-extensions-sdk";
+import { useDataBridge, RemoteBoundaryComponent, DataBridgeVersion } from "@dutchie/ecommerce-extensions-sdk";
 
 const MyExtension: RemoteBoundaryComponent = () => {
   const { dataLoaders, actions, location, user, cart } = useDataBridge();
@@ -78,10 +74,7 @@ const MyComponent = () => {
 A utility hook for handling async data loading with loading states.
 
 ```tsx
-import {
-  useAsyncLoader,
-  useDataBridge,
-} from "@dutchie/ecommerce-extensions-sdk";
+import { useAsyncLoader, useDataBridge } from "@dutchie/ecommerce-extensions-sdk";
 
 const ProductList = () => {
   const { dataLoaders } = useDataBridge();
@@ -125,11 +118,7 @@ All extension components that integrate with the Dutchie platform should satisfy
 **Example:**
 
 ```tsx
-import {
-  RemoteBoundaryComponent,
-  useDataBridge,
-  DataBridgeVersion,
-} from "@dutchie/ecommerce-extensions-sdk";
+import { RemoteBoundaryComponent, useDataBridge, DataBridgeVersion } from "@dutchie/ecommerce-extensions-sdk";
 
 const MyCustomHeader: RemoteBoundaryComponent = () => {
   const { location, user, actions } = useDataBridge();
@@ -137,11 +126,7 @@ 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>
   );
 };
@@ -191,6 +176,231 @@ const currentLocations = await dataLoaders.locations(); // Current context locat
 
 You can register callback functions that will be triggered by certain events in the Dutchie platform in your extension's `RemoteModuleRegistry` object.
 
+## Meta Fields Function
+
+### Overview
+
+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.
+
+**Why use this approach:**
+
+- ✅ **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
+
+> **🚀 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
+
+> **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
+
+### Function Signature
+
+```typescript
+export type StoreFrontMetaFieldsFunction = (data: CommerceComponentsDataInterface) => MetaFields | Promise<MetaFields>;
+```
+
+The function receives the full data bridge interface and can return meta fields synchronously or asynchronously.
+
+### 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;
+  }>;
+};
+```
+
+### Implementation
+
+Create a file in your theme (e.g., `get-meta-fields.ts`):
+
+```typescript
+import { CommerceComponentsDataInterface, MetaFields } 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 : "";
+
+  // Access data loaders for dynamic content
+  const product = await dataLoaders.product();
+  const categories = await dataLoaders.categories();
+
+  // Generate page-specific metadata
+  let pageTitle = location?.name || "Shop Cannabis";
+  let pageDescription = `Browse our selection at ${location?.name}`;
+
+  if (product) {
+    pageTitle = `${product.name} | ${location?.name}`;
+    pageDescription = `${product.description?.substring(0, 155)}...`;
+  }
+
+  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",
+      },
+    ],
+  };
+};
+```
+
+### Register in Module Registry
+
+Add the function to your theme's `index.tsx`:
+
+```typescript
+import { RemoteModuleRegistry } from "@dutchiesdk/ecommerce-extensions-sdk";
+import { getStoreFrontMetaFields } from "./get-meta-fields";
+
+export default {
+  StoreFrontHeader: createLazyRemoteBoundaryComponent(() => import("./header")),
+  StoreFrontFooter: createLazyRemoteBoundaryComponent(() => import("./footer")),
+  getStoreFrontMetaFields, // Register the function
+} satisfies RemoteModuleRegistry;
+```
+
+You may also register components for only specific menu contexts:
+
+```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;
+```
+
+### Available Data
+
+The function receives the full `CommerceComponentsDataInterface`:
+
+```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
+  }
+}
+```
+
+### Example Use Cases
+
+**Product Pages:**
+
+```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",
+      },
+    },
+  };
+}
+```
+
+**Category Pages:**
+
+```typescript
+const categories = await dataLoaders.categories();
+const pathname = window.location.pathname;
+const categorySlug = pathname.split("/").pop();
+const category = categories.find((c) => c.slug === categorySlug);
+
+if (category) {
+  return {
+    title: `${category.name} | ${location?.name}`,
+    description: `Shop ${category.name} products at ${location?.name}`,
+  };
+}
+```
+
+**Home Page:**
+
+```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,
+    },
+  };
+}
+```
+
+### Notes
+
+- 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
+
+### Migration Strategy
+
+If you have an existing theme using the `StoreFrontMeta` component:
+
+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
+
 ## Best Practices
 
 ### Data Loading
@@ -218,11 +428,7 @@ Any uncaught errors will be caught by a Dutchie error boundary, and the fallback
 Leverage the provided types for better development experience:
 
 ```tsx
-import {
-  Product,
-  Category,
-  useDataBridge,
-} from "@dutchie/ecommerce-extensions-sdk";
+import { Product, Category, useDataBridge } from "@dutchie/ecommerce-extensions-sdk";
 
 interface ProductFilterProps {
   products: Product[];
@@ -230,11 +436,7 @@ interface ProductFilterProps {
   onFilterChange: (categoryId: string) => void;
 }
 
-const ProductFilter: React.FC<ProductFilterProps> = ({
-  products,
-  categories,
-  onFilterChange,
-}) => {
+const ProductFilter: React.FC<ProductFilterProps> = ({ products, categories, onFilterChange }) => {
   // Implementation
 };
 ```
@@ -312,3 +514,11 @@ 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 here for changes, and updating to the latest version with:
+
+```bash
+npm install @dutchiesdk/ecommerce-extensions-sdk@latest
+```

package/dist/context/ecommerce-data-bridge.cjs

@@ -30,7 +30,7 @@ __webpack_require__.d(__webpack_exports__, {
     useDataBridge: ()=>useDataBridge
 });
 const external_react_namespaceObject = require("react");
-const DataBridgeVersion = '0.16.0';
+const DataBridgeVersion = '0.18.0';
 const DataBridgeContext = (0, external_react_namespaceObject.createContext)(void 0);
 const useDataBridge = ()=>{
     const context = (0, external_react_namespaceObject.useContext)(DataBridgeContext);

package/dist/esm/context/ecommerce-data-bridge.js

@@ -1,5 +1,5 @@
 import { createContext, useContext, useEffect, useState } from "react";
-const DataBridgeVersion = '0.16.0';
+const DataBridgeVersion = '0.18.0';
 const DataBridgeContext = createContext(void 0);
 const useDataBridge = ()=>{
     const context = useContext(DataBridgeContext);

package/dist/esm/types/ecommerce-extension.d.ts

@@ -1,21 +1,71 @@
 import type React from 'react';
+import type { MenuContext } from './data';
 import type { Events } from './events';
+import type { CommerceComponentsDataInterface } from './interface';
 export type RemoteBoundaryComponent<P = {}> = React.FC<P> & {
     DataBridgeVersion: string;
 };
+export type MenuSpecificRemoteComponent = {
+    [key in MenuContext]?: RemoteBoundaryComponent;
+};
+export type ModuleRegistryEntry = MenuSpecificRemoteComponent | RemoteBoundaryComponent;
 export type RoutablePageRegistryEntry = {
     component: RemoteBoundaryComponent;
     path: string;
 };
+/**
+ * Meta fields for page metadata (SEO, social sharing, etc.)
+ */
+export type MetaFields = {
+    /** Page title (rendered in <title> tag) */
+    title?: string;
+    /** Page description (rendered in <meta name="description"> tag) */
+    description?: string;
+    /** Open Graph image URL */
+    ogImage?: string;
+    /** Canonical URL */
+    canonical?: string;
+    /** JSON-LD structured data for rich snippets */
+    structuredData?: Record<string, any>;
+    /** Additional custom meta tags */
+    customMeta?: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+    }>;
+};
+/**
+ * Function that returns meta fields for the current page.
+ * Receives the data bridge context as a parameter, allowing access to
+ * data loaders, cart, user, location, and actions.
+ *
+ * @param data - The commerce components data interface with loaders and state
+ * @returns Meta fields for the current page (title, description, OG tags, etc.)
+ */
+export type StoreFrontMetaFieldsFunction = (data: CommerceComponentsDataInterface) => MetaFields | Promise<MetaFields>;
 export type RemoteModuleRegistry = {
     RouteablePages?: RoutablePageRegistryEntry[];
-    StoreFrontHeader?: RemoteBoundaryComponent;
+    StoreFrontHeader?: ModuleRegistryEntry;
+    StoreFrontNavigation?: ModuleRegistryEntry;
+    StoreFrontFooter?: ModuleRegistryEntry;
+    StoreFrontCarouselInterstitials?: ModuleRegistryEntry[];
+    StoreFrontHero?: ModuleRegistryEntry;
+    ProductDetailsPrimary?: ModuleRegistryEntry;
+    /**
+     * Function that provides meta fields for the current page.
+     * Replaces the StoreFrontMeta component approach.
+     *
+     * Called by the host app with the full data bridge context:
+     * `const metaFields = registry.getStoreFrontMetaFields?.(dataBridgeData)`
+     */
+    getStoreFrontMetaFields?: StoreFrontMetaFieldsFunction;
+    events?: Events;
+    /**
+     * @deprecated Use getStoreFrontMetaFields instead
+     */
     StoreFrontMeta?: RemoteBoundaryComponent;
-    StoreFrontNavigation?: RemoteBoundaryComponent;
-    StoreFrontFooter?: RemoteBoundaryComponent;
-    StoreFrontCarouselInterstitials?: RemoteBoundaryComponent[];
-    StoreFrontHero?: RemoteBoundaryComponent;
+    /**
+     * @deprecated Use getStoreFrontMetaFields instead
+     */
     ProductDetailsMeta?: RemoteBoundaryComponent;
-    ProductDetailsPrimary?: RemoteBoundaryComponent;
-    events?: Events;
 };

package/dist/types/ecommerce-extension.d.ts

@@ -1,21 +1,71 @@
 import type React from 'react';
+import type { MenuContext } from './data';
 import type { Events } from './events';
+import type { CommerceComponentsDataInterface } from './interface';
 export type RemoteBoundaryComponent<P = {}> = React.FC<P> & {
     DataBridgeVersion: string;
 };
+export type MenuSpecificRemoteComponent = {
+    [key in MenuContext]?: RemoteBoundaryComponent;
+};
+export type ModuleRegistryEntry = MenuSpecificRemoteComponent | RemoteBoundaryComponent;
 export type RoutablePageRegistryEntry = {
     component: RemoteBoundaryComponent;
     path: string;
 };
+/**
+ * Meta fields for page metadata (SEO, social sharing, etc.)
+ */
+export type MetaFields = {
+    /** Page title (rendered in <title> tag) */
+    title?: string;
+    /** Page description (rendered in <meta name="description"> tag) */
+    description?: string;
+    /** Open Graph image URL */
+    ogImage?: string;
+    /** Canonical URL */
+    canonical?: string;
+    /** JSON-LD structured data for rich snippets */
+    structuredData?: Record<string, any>;
+    /** Additional custom meta tags */
+    customMeta?: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+    }>;
+};
+/**
+ * Function that returns meta fields for the current page.
+ * Receives the data bridge context as a parameter, allowing access to
+ * data loaders, cart, user, location, and actions.
+ *
+ * @param data - The commerce components data interface with loaders and state
+ * @returns Meta fields for the current page (title, description, OG tags, etc.)
+ */
+export type StoreFrontMetaFieldsFunction = (data: CommerceComponentsDataInterface) => MetaFields | Promise<MetaFields>;
 export type RemoteModuleRegistry = {
     RouteablePages?: RoutablePageRegistryEntry[];
-    StoreFrontHeader?: RemoteBoundaryComponent;
+    StoreFrontHeader?: ModuleRegistryEntry;
+    StoreFrontNavigation?: ModuleRegistryEntry;
+    StoreFrontFooter?: ModuleRegistryEntry;
+    StoreFrontCarouselInterstitials?: ModuleRegistryEntry[];
+    StoreFrontHero?: ModuleRegistryEntry;
+    ProductDetailsPrimary?: ModuleRegistryEntry;
+    /**
+     * Function that provides meta fields for the current page.
+     * Replaces the StoreFrontMeta component approach.
+     *
+     * Called by the host app with the full data bridge context:
+     * `const metaFields = registry.getStoreFrontMetaFields?.(dataBridgeData)`
+     */
+    getStoreFrontMetaFields?: StoreFrontMetaFieldsFunction;
+    events?: Events;
+    /**
+     * @deprecated Use getStoreFrontMetaFields instead
+     */
     StoreFrontMeta?: RemoteBoundaryComponent;
-    StoreFrontNavigation?: RemoteBoundaryComponent;
-    StoreFrontFooter?: RemoteBoundaryComponent;
-    StoreFrontCarouselInterstitials?: RemoteBoundaryComponent[];
-    StoreFrontHero?: RemoteBoundaryComponent;
+    /**
+     * @deprecated Use getStoreFrontMetaFields instead
+     */
     ProductDetailsMeta?: RemoteBoundaryComponent;
-    ProductDetailsPrimary?: RemoteBoundaryComponent;
-    events?: Events;
 };

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.16.0",
+  "version": "0.18.0",
   "license": "MIT",
   "type": "module",
   "module": "./dist/esm/index.js",