personalize-connect-sdk 1.3.1 → 1.3.2

package/README.md

@@ -1,6 +1,8 @@
 # Personalize Connect SDK
 
-A lightweight Next.js package that bridges Sitecore Personalize Interactive Experiences with XM Cloud component datasources at runtime. The SDK reads configuration authored by the Marketplace app, calls Personalize for a decision, and swaps component content accordingly — with zero per-component code.
+Runtime SDK for [Personalize Connect](https://github.com/Sitecore-Hackathon/2026-Team-Solo) — a zero-code bridge between Sitecore XM Cloud components and Sitecore Personalize Full Stack Interactive Experiences.
+
+The SDK reads configuration authored by the Marketplace app (stored in the content tree), calls Personalize for a decision via the Edge proxy, resolves the matching datasource from Experience Edge, and swaps component content — with zero per-component code. In Page Builder, components with personalization get a visual indicator.
 
 ## Installation
 
@@ -10,23 +12,21 @@ npm install personalize-connect-sdk
 
 Peer dependency: `react` >= 18.
 
-## Usage
+## Quick Start (XM Cloud)
 
 ### 1. Wrap your app with `PersonalizeProvider`
 
+In `_app.tsx` (Pages Router) or `layout.tsx` (App Router):
+
 ```tsx
 import { PersonalizeProvider } from "personalize-connect-sdk";
 
-export default function RootLayout({ children }) {
+export default function App({ children }) {
   return (
     <PersonalizeProvider
-      clientKey={process.env.NEXT_PUBLIC_PERSONALIZE_CLIENT_KEY!}
-      pointOfSale={process.env.NEXT_PUBLIC_PERSONALIZE_POINT_OF_SALE!}
-      resolveDatasource={async (datasourceId) => {
-        // Fetch datasource fields via Experience Edge GraphQL or Layout Service
-        const res = await fetch(`/api/datasource/${datasourceId}`);
-        return res.json();
-      }}
+      sitecoreEdgeContextId={process.env.SITECORE_EDGE_CONTEXT_ID}
+      siteName={process.env.SITECORE_SITE_NAME}
+      debug // remove in production
     >
       {children}
     </PersonalizeProvider>
@@ -34,49 +34,152 @@ export default function RootLayout({ children }) {
 }
 ```
 
+That's it for provider setup. One prop (`sitecoreEdgeContextId`) drives everything:
+
+- **Browser ID** — fetched from `edge-platform.sitecorecloud.io/v1/init`
+- **Personalize calls** — routed through the Edge proxy (`/v1/personalize`)
+- **Datasource resolution** — built-in via Edge proxy GraphQL
+- **Config loading** — auto-discovered from the content tree via Edge
+- **Editing detection** — auto-detected from JSS Sitecore context
+
 ### 2. Wrap components with `withPersonalizeConnect`
 
 ```tsx
 import { withPersonalizeConnect } from "personalize-connect-sdk";
-import MyComponent from "./MyComponent";
 
-// Config is read from props.rendering.personalizeConnect (or customize via getConfig)
-export default withPersonalizeConnect(MyComponent);
+const PromoCard = ({ fields }) => (
+  <div>
+    <h2>{fields?.title?.value}</h2>
+    <p>{fields?.body?.value}</p>
+  </div>
+);
+
+export default withPersonalizeConnect(PromoCard);
 ```
 
-The HOC renders immediately with the default datasource, calls Personalize asynchronously, and re-renders with personalized content when resolved. No changes needed inside the component.
+The HOC:
+1. Looks up config from the content tree (loaded by the provider on mount)
+2. Renders with the default datasource immediately
+3. Calls Personalize asynchronously for a content decision
+4. Resolves the matching datasource from Experience Edge
+5. Re-renders with personalized `fields`
+6. In Page Builder, shows a visual indicator (purple border + badge)
 
 ### 3. Or use the `usePersonalizeExperience` hook
 
 ```tsx
 import { usePersonalizeExperience } from "personalize-connect-sdk";
 
-function MyComponent({ personalizeConnect }) {
-  const { contentKey, resolvedFields, isLoading, error } = usePersonalizeExperience(personalizeConnect);
+function MyComponent({ rendering }) {
+  const config = /* get config from context or props */;
+  const { contentKey, resolvedFields, isLoading, error } = usePersonalizeExperience(config);
 
   if (isLoading) return <Skeleton />;
-  return <div>{resolvedFields?.heading}</div>;
+  return <div>{resolvedFields?.heading?.value}</div>;
 }
 ```
 
-## Config shape
+## Provider Props
+
+### XM Cloud (recommended)
+
+| Prop | Required | Description |
+|------|----------|-------------|
+| `sitecoreEdgeContextId` | Yes | Edge Context ID — drives all Edge proxy calls |
+| `siteName` | Yes | XM Cloud site name |
+| `sitecoreEdgeUrl` | No | Edge platform URL (defaults to `https://edge-platform.sitecorecloud.io`) |
+
+### Legacy (direct credentials)
+
+| Prop | Required | Description |
+|------|----------|-------------|
+| `clientKey` | Yes | Personalize API client key |
+| `pointOfSale` | Yes | Point of sale identifier |
+| `edgeUrl` | No | Experience Edge GraphQL endpoint |
+| `apiKey` | No | Sitecore API key for Edge |
+
+### Common
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `channel` | `"WEB"` | Channel for Personalize calls |
+| `language` | `"EN"` | Language code |
+| `currencyCode` | `"USD"` | Currency code |
+| `timeout` | `600` | Personalize call timeout (ms) |
+| `debug` | `false` | Enable `[PersonalizeConnect]` console logging |
+| `isEditing` | auto | Override Page Builder editing detection |
+| `sitePath` | auto | Override site root path auto-discovery |
+| `resolveDatasource` | built-in | Custom datasource resolver (overrides built-in Edge resolution) |
+
+## How Config Loading Works
+
+The Marketplace app stores configs in the content tree at:
+
+```
+{sitePath}/Data/PersonalizeConnect/{pageItemId}/config-{renderingId}
+```
 
-Config is attached to each rendering in XMC layout data (authored by the Marketplace app):
+On mount, the SDK:
+1. Reads the page item ID from `__NEXT_DATA__` (JSS layout data)
+2. Queries Edge for the page item's content tree path
+3. Derives the site root path (first 4 path segments)
+4. Fetches all config children for that page in one GraphQL query
+5. Caches them in context, keyed by rendering instance ID
+
+Each HOC looks up its config via `props.rendering.uid`. No config on the rendering means no personalization — the component renders normally.
+
+## Config Shape
+
+Authored by the Marketplace app, stored as JSON in the content tree:
 
 ```ts
 interface PersonalizeConnectConfig {
-  friendlyId: string;           // Personalize Interactive Experience ID
+  friendlyId: string;                  // Personalize Interactive Experience ID
   contentMap: Record<string, string>;  // contentKey -> datasource GUID
-  defaultKey: string;           // Fallback key if experience fails
+  defaultKey: string;                  // Fallback key
 }
 ```
 
+## Debug Logging
+
+Pass `debug` to the provider to trace the full flow in the browser console:
+
+```
+[PersonalizeConnect] Provider mounting { mode: 'Context ID', ... }
+[PersonalizeConnect] BrowserId (edge): from cookie abc123...
+[PersonalizeConnect] Config loader: Auto-discovered site path: /sitecore/content/company/company
+[PersonalizeConnect] Config loader: loaded config for rendering xyz → experience homepage_promo
+[PersonalizeConnect] [PromoCard] Config active: { friendlyId: 'homepage_promo', ... }
+[PersonalizeConnect] callPersonalize [homepage_promo] → contentKey: returning-visitor
+[PersonalizeConnect] [PromoCard] Fields resolved — swapping props.fields
+```
+
 ## Exports
 
-- `PersonalizeProvider`, `usePersonalizeContext` — Provider and context
-- `withPersonalizeConnect` — HOC for zero-code personalization
+**Provider & Context**
+- `PersonalizeProvider` — Wrap your app
+- `usePersonalizeContext` — Access context directly
+
+**HOC & Hook**
+- `withPersonalizeConnect` — Zero-code personalization HOC
 - `usePersonalizeExperience` — Hook for manual control
-- `callPersonalize` — Low-level API client
-- `resolveContent` — Map contentKey to datasource fields
-- `getBrowserId` — Browser ID cookie helper
-- Types: `PersonalizeConnectConfig`, `PersonalizeConnectProviderProps`, etc.
+
+**Config**
+- `loadPageConfigs` — Load configs from Edge (used internally, exported for advanced use)
+
+**Edge Resolution**
+- `createEdgeResolver` — Direct Edge GraphQL resolver (legacy)
+- `createEdgeProxyResolver` — Edge proxy resolver (Context ID mode)
+
+**Browser ID**
+- `getBrowserId` — Legacy local cookie
+- `getEdgeBrowserId` — Edge proxy init
+
+**Editing**
+- `isEditingMode` — Page Builder detection
+
+**Debug**
+- `setDebug`, `isDebugEnabled` — Control logging
+
+**Types**
+- `PersonalizeConnectConfig`, `PersonalizeConnectProviderProps`, `PersonalizeContextValue`, `ComponentFields`, `CallFlowsRequest`, etc.

package/dist/index.js

@@ -43,7 +43,7 @@ module.exports = __toCommonJS(index_exports);
 var import_react = require("react");
 
 // src/logger.ts
-var PREFIX = "[PersonalizeConnect]";
+var PREFIX = "[PersonalizeConnectSDK]";
 var enabled = false;
 function setDebug(on) {
   enabled = on;
@@ -397,6 +397,7 @@ async function loadPageConfigs(edgeUrl, pageItemId, language, headers = {}, site
     error("Config loader fetch error:", e);
   }
   groupEnd();
+  log("Config loader: result", Object.fromEntries(configs));
   return configs;
 }
 
@@ -778,7 +779,7 @@ function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG
           });
           config = fromContext;
         } else if (context.configsLoaded) {
-          log(`[${componentName}] No config in context for rendering uid ${normalizedUid} \u2014 passthrough`);
+          log(`[${componentName}] No config match for uid "${normalizedUid}". All configs:`, Object.fromEntries(context.configs));
         } else {
           log(`[${componentName}] Configs still loading for uid ${normalizedUid}...`);
         }

package/dist/index.mjs

@@ -2,7 +2,7 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 
 // src/logger.ts
-var PREFIX = "[PersonalizeConnect]";
+var PREFIX = "[PersonalizeConnectSDK]";
 var enabled = false;
 function setDebug(on) {
   enabled = on;
@@ -356,6 +356,7 @@ async function loadPageConfigs(edgeUrl, pageItemId, language, headers = {}, site
     error("Config loader fetch error:", e);
   }
   groupEnd();
+  log("Config loader: result", Object.fromEntries(configs));
   return configs;
 }
 
@@ -737,7 +738,7 @@ function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG
           });
           config = fromContext;
         } else if (context.configsLoaded) {
-          log(`[${componentName}] No config in context for rendering uid ${normalizedUid} \u2014 passthrough`);
+          log(`[${componentName}] No config match for uid "${normalizedUid}". All configs:`, Object.fromEntries(context.configs));
         } else {
           log(`[${componentName}] Configs still loading for uid ${normalizedUid}...`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "personalize-connect-sdk",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Runtime SDK for Personalize Connect - resolves active experience outcomes and datasources in your rendering host",
   "author": "Dylan Young",
   "keywords": [
@@ -14,7 +14,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/2026-Team-Solo/2026-Team-Solo.git",
+    "url": "https://github.com/Sitecore-Hackathon/2026-Team-Solo.git",
     "directory": "packages/sdk"
   },
   "main": "dist/index.js",