personalize-connect-sdk 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# 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.
+
+## Installation
+
+```bash
+npm install personalize-connect-sdk
+```
+
+Peer dependency: `react` >= 18.
+
+## Usage
+
+### 1. Wrap your app with `PersonalizeProvider`
+
+```tsx
+import { PersonalizeProvider } from "personalize-connect-sdk";
+
+export default function RootLayout({ 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();
+      }}
+    >
+      {children}
+    </PersonalizeProvider>
+  );
+}
+```
+
+### 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);
+```
+
+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.
+
+### 3. Or use the `usePersonalizeExperience` hook
+
+```tsx
+import { usePersonalizeExperience } from "personalize-connect-sdk";
+
+function MyComponent({ personalizeConnect }) {
+  const { contentKey, resolvedFields, isLoading, error } = usePersonalizeExperience(personalizeConnect);
+
+  if (isLoading) return <Skeleton />;
+  return <div>{resolvedFields?.heading}</div>;
+}
+```
+
+## Config shape
+
+Config is attached to each rendering in XMC layout data (authored by the Marketplace app):
+
+```ts
+interface PersonalizeConnectConfig {
+  friendlyId: string;           // Personalize Interactive Experience ID
+  contentMap: Record<string, string>;  // contentKey -> datasource GUID
+  defaultKey: string;           // Fallback key if experience fails
+}
+```
+
+## Exports
+
+- `PersonalizeProvider`, `usePersonalizeContext` — Provider and context
+- `withPersonalizeConnect` — HOC for zero-code personalization
+- `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.

package/dist/index.d.mts

@@ -0,0 +1,144 @@
+import { ReactNode, ComponentType } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Personalize Connect SDK types.
+ * Stored on the rendering in XMC layout data.
+ */
+interface PersonalizeConnectConfig {
+    /** The Personalize Interactive Experience friendly ID */
+    friendlyId: string;
+    /**
+     * Maps contentKey values (returned by the experience)
+     * to XMC datasource item GUIDs
+     */
+    contentMap: Record<string, string>;
+    /**
+     * Which contentMap key to render on initial load
+     * and use as fallback if the experience fails
+     * or returns an unrecognized key
+     */
+    defaultKey: string;
+}
+/** The standardized API response contract from Personalize */
+interface PersonalizeConnectResponse {
+    contentKey: string;
+}
+/** What the SDK sends to Personalize /v2/callFlows */
+interface CallFlowsRequest {
+    clientKey: string;
+    channel: string;
+    language: string;
+    currencyCode: string;
+    pointOfSale: string;
+    browserId: string;
+    friendlyId: string;
+    params?: {
+        componentRef?: string;
+        pageRoute?: string;
+        [key: string]: unknown;
+    };
+}
+/** Provider configuration */
+interface PersonalizeConnectProviderProps {
+    clientKey: string;
+    pointOfSale: string;
+    channel?: string;
+    language?: string;
+    currencyCode?: string;
+    timeout?: number;
+    /** Custom function to fetch datasource fields by item ID (e.g. via GraphQL or Layout Service) */
+    resolveDatasource?: (datasourceId: string) => Promise<ComponentFields>;
+    children: ReactNode;
+}
+/** Resolved datasource fields passed as component props */
+type ComponentFields = Record<string, unknown>;
+/** Value exposed by PersonalizeContext */
+interface PersonalizeContextValue {
+    clientKey: string;
+    pointOfSale: string;
+    channel: string;
+    language: string;
+    currencyCode: string;
+    timeout: number;
+    browserId: string;
+    resolveDatasource: (datasourceId: string) => Promise<ComponentFields>;
+}
+
+declare function PersonalizeProvider({ children, clientKey, pointOfSale, channel, language, currencyCode, timeout, resolveDatasource, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
+declare function usePersonalizeContext(): PersonalizeContextValue | null;
+
+/**
+ * Thin async wrapper around POST /v2/callFlows.
+ * Enforces timeout, parses response, validates contentKey.
+ */
+
+interface CallPersonalizeOptions {
+    config: PersonalizeConnectConfig;
+    context: PersonalizeContextValue;
+    /** Optional: override API base URL (e.g. region-specific) */
+    apiBase?: string;
+    /** Optional: component ref for params */
+    componentRef?: string;
+    /** Optional: page route for params */
+    pageRoute?: string;
+}
+/**
+ * Call Personalize /v2/callFlows to get the active content key.
+ * Returns the contentKey on success, null on any failure.
+ */
+declare function callPersonalize(options: CallPersonalizeOptions): Promise<string | null>;
+
+/**
+ * Maps contentKey to datasource GUID via contentMap,
+ * fetches datasource fields, and falls back to defaultKey on failure.
+ */
+
+interface ResolveContentOptions {
+    contentKey: string | null;
+    config: PersonalizeConnectConfig;
+    resolveDatasource: (datasourceId: string) => Promise<ComponentFields>;
+}
+interface ResolvedContent {
+    datasourceId: string;
+    fields: ComponentFields;
+}
+/**
+ * Resolve content key to datasource fields.
+ * Falls back to defaultKey if contentKey is null or not in contentMap.
+ * Returns null on any fetch failure.
+ */
+declare function resolveContent(options: ResolveContentOptions): Promise<ResolvedContent | null>;
+
+type GetConfigFromProps<P> = (props: P) => PersonalizeConnectConfig | undefined;
+/**
+ * HOC that wraps any JSS/Content SDK component.
+ * If the rendering has a personalizeConnect config, it renders with defaultKey first,
+ * then asynchronously fetches the personalized content and re-renders.
+ * If no config, passes through unchanged.
+ */
+declare function withPersonalizeConnect<P extends object>(WrappedComponent: ComponentType<P>, getConfig?: GetConfigFromProps<P>): ComponentType<P>;
+
+interface UsePersonalizeExperienceResult {
+    contentKey: string | null;
+    resolvedFields: ComponentFields | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+/**
+ * Hook alternative for cases where the HOC pattern doesn't fit.
+ * Returns contentKey, resolvedFields, isLoading, and error.
+ */
+declare function usePersonalizeExperience(config: PersonalizeConnectConfig | undefined): UsePersonalizeExperienceResult;
+
+/**
+ * Manages the Sitecore CDP browser ID cookie (bid_<clientKey>).
+ * Used for session continuity across Personalize decisions.
+ */
+/**
+ * Get or create the browser ID for the given client key.
+ * Reads from cookie bid_<clientKey>, writes if missing, and returns the value.
+ */
+declare function getBrowserId(clientKey: string): string;
+
+export { type CallFlowsRequest, type CallPersonalizeOptions, type ComponentFields, type GetConfigFromProps, type PersonalizeConnectConfig, type PersonalizeConnectProviderProps, type PersonalizeConnectResponse, type PersonalizeContextValue, PersonalizeProvider, type ResolveContentOptions, type ResolvedContent, type UsePersonalizeExperienceResult, callPersonalize, getBrowserId, resolveContent, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+import { ReactNode, ComponentType } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Personalize Connect SDK types.
+ * Stored on the rendering in XMC layout data.
+ */
+interface PersonalizeConnectConfig {
+    /** The Personalize Interactive Experience friendly ID */
+    friendlyId: string;
+    /**
+     * Maps contentKey values (returned by the experience)
+     * to XMC datasource item GUIDs
+     */
+    contentMap: Record<string, string>;
+    /**
+     * Which contentMap key to render on initial load
+     * and use as fallback if the experience fails
+     * or returns an unrecognized key
+     */
+    defaultKey: string;
+}
+/** The standardized API response contract from Personalize */
+interface PersonalizeConnectResponse {
+    contentKey: string;
+}
+/** What the SDK sends to Personalize /v2/callFlows */
+interface CallFlowsRequest {
+    clientKey: string;
+    channel: string;
+    language: string;
+    currencyCode: string;
+    pointOfSale: string;
+    browserId: string;
+    friendlyId: string;
+    params?: {
+        componentRef?: string;
+        pageRoute?: string;
+        [key: string]: unknown;
+    };
+}
+/** Provider configuration */
+interface PersonalizeConnectProviderProps {
+    clientKey: string;
+    pointOfSale: string;
+    channel?: string;
+    language?: string;
+    currencyCode?: string;
+    timeout?: number;
+    /** Custom function to fetch datasource fields by item ID (e.g. via GraphQL or Layout Service) */
+    resolveDatasource?: (datasourceId: string) => Promise<ComponentFields>;
+    children: ReactNode;
+}
+/** Resolved datasource fields passed as component props */
+type ComponentFields = Record<string, unknown>;
+/** Value exposed by PersonalizeContext */
+interface PersonalizeContextValue {
+    clientKey: string;
+    pointOfSale: string;
+    channel: string;
+    language: string;
+    currencyCode: string;
+    timeout: number;
+    browserId: string;
+    resolveDatasource: (datasourceId: string) => Promise<ComponentFields>;
+}
+
+declare function PersonalizeProvider({ children, clientKey, pointOfSale, channel, language, currencyCode, timeout, resolveDatasource, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
+declare function usePersonalizeContext(): PersonalizeContextValue | null;
+
+/**
+ * Thin async wrapper around POST /v2/callFlows.
+ * Enforces timeout, parses response, validates contentKey.
+ */
+
+interface CallPersonalizeOptions {
+    config: PersonalizeConnectConfig;
+    context: PersonalizeContextValue;
+    /** Optional: override API base URL (e.g. region-specific) */
+    apiBase?: string;
+    /** Optional: component ref for params */
+    componentRef?: string;
+    /** Optional: page route for params */
+    pageRoute?: string;
+}
+/**
+ * Call Personalize /v2/callFlows to get the active content key.
+ * Returns the contentKey on success, null on any failure.
+ */
+declare function callPersonalize(options: CallPersonalizeOptions): Promise<string | null>;
+
+/**
+ * Maps contentKey to datasource GUID via contentMap,
+ * fetches datasource fields, and falls back to defaultKey on failure.
+ */
+
+interface ResolveContentOptions {
+    contentKey: string | null;
+    config: PersonalizeConnectConfig;
+    resolveDatasource: (datasourceId: string) => Promise<ComponentFields>;
+}
+interface ResolvedContent {
+    datasourceId: string;
+    fields: ComponentFields;
+}
+/**
+ * Resolve content key to datasource fields.
+ * Falls back to defaultKey if contentKey is null or not in contentMap.
+ * Returns null on any fetch failure.
+ */
+declare function resolveContent(options: ResolveContentOptions): Promise<ResolvedContent | null>;
+
+type GetConfigFromProps<P> = (props: P) => PersonalizeConnectConfig | undefined;
+/**
+ * HOC that wraps any JSS/Content SDK component.
+ * If the rendering has a personalizeConnect config, it renders with defaultKey first,
+ * then asynchronously fetches the personalized content and re-renders.
+ * If no config, passes through unchanged.
+ */
+declare function withPersonalizeConnect<P extends object>(WrappedComponent: ComponentType<P>, getConfig?: GetConfigFromProps<P>): ComponentType<P>;
+
+interface UsePersonalizeExperienceResult {
+    contentKey: string | null;
+    resolvedFields: ComponentFields | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+/**
+ * Hook alternative for cases where the HOC pattern doesn't fit.
+ * Returns contentKey, resolvedFields, isLoading, and error.
+ */
+declare function usePersonalizeExperience(config: PersonalizeConnectConfig | undefined): UsePersonalizeExperienceResult;
+
+/**
+ * Manages the Sitecore CDP browser ID cookie (bid_<clientKey>).
+ * Used for session continuity across Personalize decisions.
+ */
+/**
+ * Get or create the browser ID for the given client key.
+ * Reads from cookie bid_<clientKey>, writes if missing, and returns the value.
+ */
+declare function getBrowserId(clientKey: string): string;
+
+export { type CallFlowsRequest, type CallPersonalizeOptions, type ComponentFields, type GetConfigFromProps, type PersonalizeConnectConfig, type PersonalizeConnectProviderProps, type PersonalizeConnectResponse, type PersonalizeContextValue, PersonalizeProvider, type ResolveContentOptions, type ResolvedContent, type UsePersonalizeExperienceResult, callPersonalize, getBrowserId, resolveContent, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };

package/dist/index.js

@@ -0,0 +1,283 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PersonalizeProvider: () => PersonalizeProvider,
+  callPersonalize: () => callPersonalize,
+  getBrowserId: () => getBrowserId,
+  resolveContent: () => resolveContent,
+  usePersonalizeContext: () => usePersonalizeContext,
+  usePersonalizeExperience: () => usePersonalizeExperience,
+  withPersonalizeConnect: () => withPersonalizeConnect
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/PersonalizeProvider.tsx
+var import_react = require("react");
+
+// src/browserId.ts
+var COOKIE_PREFIX = "bid_";
+var COOKIE_MAX_AGE = 63072e3;
+var COOKIE_PATH = "/";
+var COOKIE_SAME_SITE = "Lax";
+function generateBrowserId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+function getCookie(name) {
+  if (typeof document === "undefined") return null;
+  const match = document.cookie.match(new RegExp("(?:^|; )" + encodeURIComponent(name) + "=([^;]*)"));
+  return match ? decodeURIComponent(match[1]) : null;
+}
+function setCookie(name, value) {
+  if (typeof document === "undefined") return;
+  document.cookie = encodeURIComponent(name) + "=" + encodeURIComponent(value) + "; path=" + COOKIE_PATH + "; max-age=" + COOKIE_MAX_AGE + "; SameSite=" + COOKIE_SAME_SITE;
+}
+function getBrowserId(clientKey) {
+  const cookieName = COOKIE_PREFIX + clientKey;
+  let bid = getCookie(cookieName);
+  if (!bid || typeof bid !== "string" || bid.length < 10) {
+    bid = generateBrowserId();
+    setCookie(cookieName, bid);
+  }
+  return bid;
+}
+
+// src/PersonalizeProvider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var PersonalizeContext = (0, import_react.createContext)(null);
+var DEFAULT_CHANNEL = "WEB";
+var DEFAULT_LANGUAGE = "EN";
+var DEFAULT_CURRENCY = "USD";
+var DEFAULT_TIMEOUT = 600;
+var noopResolver = async () => ({});
+function PersonalizeProvider({
+  children,
+  clientKey,
+  pointOfSale,
+  channel = DEFAULT_CHANNEL,
+  language = DEFAULT_LANGUAGE,
+  currencyCode = DEFAULT_CURRENCY,
+  timeout = DEFAULT_TIMEOUT,
+  resolveDatasource = noopResolver
+}) {
+  const [browserId, setBrowserId] = (0, import_react.useState)("");
+  (0, import_react.useEffect)(() => {
+    setBrowserId(getBrowserId(clientKey));
+  }, [clientKey]);
+  const stableResolveDatasource = (0, import_react.useCallback)(resolveDatasource, [resolveDatasource]);
+  const effectiveBrowserId = browserId || (typeof window !== "undefined" ? getBrowserId(clientKey) : "");
+  const value = (0, import_react.useMemo)(
+    () => ({
+      clientKey,
+      pointOfSale,
+      channel,
+      language,
+      currencyCode,
+      timeout,
+      browserId: effectiveBrowserId,
+      resolveDatasource: stableResolveDatasource
+    }),
+    [
+      clientKey,
+      pointOfSale,
+      channel,
+      language,
+      currencyCode,
+      timeout,
+      effectiveBrowserId,
+      stableResolveDatasource
+    ]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PersonalizeContext.Provider, { value, children });
+}
+function usePersonalizeContext() {
+  return (0, import_react.useContext)(PersonalizeContext);
+}
+
+// src/personalizeClient.ts
+var DEFAULT_API_BASE = "https://api.boxever.com";
+async function callPersonalize(options) {
+  const { config, context, apiBase = DEFAULT_API_BASE, componentRef, pageRoute } = options;
+  const body = {
+    clientKey: context.clientKey,
+    channel: context.channel,
+    language: context.language,
+    currencyCode: context.currencyCode,
+    pointOfSale: context.pointOfSale,
+    browserId: context.browserId,
+    friendlyId: config.friendlyId
+  };
+  if (componentRef || pageRoute) {
+    body.params = {};
+    if (componentRef) body.params.componentRef = componentRef;
+    if (pageRoute) body.params.pageRoute = pageRoute;
+  }
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), context.timeout);
+  try {
+    const res = await fetch(`${apiBase.replace(/\/$/, "")}/v2/callFlows`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (!data || typeof data !== "object") return null;
+    const contentKey = data.contentKey;
+    if (typeof contentKey !== "string" || contentKey.trim() === "") return null;
+    return contentKey;
+  } catch {
+    clearTimeout(timeoutId);
+    return null;
+  }
+}
+
+// src/contentResolver.ts
+async function resolveContent(options) {
+  const { contentKey, config, resolveDatasource } = options;
+  const effectiveKey = contentKey && contentKey in config.contentMap ? contentKey : config.defaultKey;
+  const datasourceId = config.contentMap[effectiveKey];
+  if (!datasourceId || typeof datasourceId !== "string") return null;
+  try {
+    const fields = await resolveDatasource(datasourceId);
+    if (!fields || typeof fields !== "object") return null;
+    return { datasourceId, fields };
+  } catch {
+    return null;
+  }
+}
+
+// src/withPersonalizeConnect.tsx
+var import_react2 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var DEFAULT_GET_CONFIG = (props) => props.rendering?.personalizeConnect;
+function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG) {
+  function PersonalizeConnectWrapper(props) {
+    const context = usePersonalizeContext();
+    const config = getConfig(props);
+    const [resolvedFields, setResolvedFields] = (0, import_react2.useState)(null);
+    const mountedRef = (0, import_react2.useRef)(true);
+    const runPersonalization = (0, import_react2.useCallback)(async () => {
+      if (!config || !context) return;
+      const contentKey = await callPersonalize({ config, context });
+      if (!mountedRef.current) return;
+      const resolved = await resolveContent({
+        contentKey,
+        config,
+        resolveDatasource: context.resolveDatasource
+      });
+      if (!mountedRef.current) return;
+      if (resolved) {
+        setResolvedFields(resolved.fields);
+      }
+    }, [config, context]);
+    (0, import_react2.useEffect)(() => {
+      mountedRef.current = true;
+      if (config && context) {
+        runPersonalization();
+      }
+      return () => {
+        mountedRef.current = false;
+      };
+    }, [config?.friendlyId, context?.clientKey, runPersonalization]);
+    if (!config || !context) {
+      return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(WrappedComponent, { ...props });
+    }
+    const mergedProps = {
+      ...props,
+      ...resolvedFields ?? {}
+    };
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(WrappedComponent, { ...mergedProps });
+  }
+  PersonalizeConnectWrapper.displayName = `WithPersonalizeConnect(${WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"})`;
+  return PersonalizeConnectWrapper;
+}
+
+// src/usePersonalizeExperience.ts
+var import_react3 = require("react");
+function usePersonalizeExperience(config) {
+  const context = usePersonalizeContext();
+  const [contentKey, setContentKey] = (0, import_react3.useState)(null);
+  const [resolvedFields, setResolvedFields] = (0, import_react3.useState)(null);
+  const [isLoading, setIsLoading] = (0, import_react3.useState)(true);
+  const [error, setError] = (0, import_react3.useState)(null);
+  const mountedRef = (0, import_react3.useRef)(true);
+  const runPersonalization = (0, import_react3.useCallback)(async () => {
+    if (!config || !context) {
+      setIsLoading(false);
+      return;
+    }
+    setError(null);
+    setContentKey(null);
+    setResolvedFields(null);
+    setIsLoading(true);
+    try {
+      const key = await callPersonalize({ config, context });
+      if (!mountedRef.current) return;
+      setContentKey(key);
+      const resolved = await resolveContent({
+        contentKey: key,
+        config,
+        resolveDatasource: context.resolveDatasource
+      });
+      if (!mountedRef.current) return;
+      if (resolved) setResolvedFields(resolved.fields);
+    } catch (e) {
+      if (mountedRef.current) {
+        setError(e instanceof Error ? e : new Error(String(e)));
+      }
+    } finally {
+      if (mountedRef.current) setIsLoading(false);
+    }
+  }, [config, context]);
+  (0, import_react3.useEffect)(() => {
+    mountedRef.current = true;
+    runPersonalization();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [runPersonalization]);
+  return {
+    contentKey,
+    resolvedFields,
+    isLoading,
+    error
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PersonalizeProvider,
+  callPersonalize,
+  getBrowserId,
+  resolveContent,
+  usePersonalizeContext,
+  usePersonalizeExperience,
+  withPersonalizeConnect
+});

package/dist/index.mjs

@@ -0,0 +1,250 @@
+// src/PersonalizeProvider.tsx
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+
+// src/browserId.ts
+var COOKIE_PREFIX = "bid_";
+var COOKIE_MAX_AGE = 63072e3;
+var COOKIE_PATH = "/";
+var COOKIE_SAME_SITE = "Lax";
+function generateBrowserId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+function getCookie(name) {
+  if (typeof document === "undefined") return null;
+  const match = document.cookie.match(new RegExp("(?:^|; )" + encodeURIComponent(name) + "=([^;]*)"));
+  return match ? decodeURIComponent(match[1]) : null;
+}
+function setCookie(name, value) {
+  if (typeof document === "undefined") return;
+  document.cookie = encodeURIComponent(name) + "=" + encodeURIComponent(value) + "; path=" + COOKIE_PATH + "; max-age=" + COOKIE_MAX_AGE + "; SameSite=" + COOKIE_SAME_SITE;
+}
+function getBrowserId(clientKey) {
+  const cookieName = COOKIE_PREFIX + clientKey;
+  let bid = getCookie(cookieName);
+  if (!bid || typeof bid !== "string" || bid.length < 10) {
+    bid = generateBrowserId();
+    setCookie(cookieName, bid);
+  }
+  return bid;
+}
+
+// src/PersonalizeProvider.tsx
+import { jsx } from "react/jsx-runtime";
+var PersonalizeContext = createContext(null);
+var DEFAULT_CHANNEL = "WEB";
+var DEFAULT_LANGUAGE = "EN";
+var DEFAULT_CURRENCY = "USD";
+var DEFAULT_TIMEOUT = 600;
+var noopResolver = async () => ({});
+function PersonalizeProvider({
+  children,
+  clientKey,
+  pointOfSale,
+  channel = DEFAULT_CHANNEL,
+  language = DEFAULT_LANGUAGE,
+  currencyCode = DEFAULT_CURRENCY,
+  timeout = DEFAULT_TIMEOUT,
+  resolveDatasource = noopResolver
+}) {
+  const [browserId, setBrowserId] = useState("");
+  useEffect(() => {
+    setBrowserId(getBrowserId(clientKey));
+  }, [clientKey]);
+  const stableResolveDatasource = useCallback(resolveDatasource, [resolveDatasource]);
+  const effectiveBrowserId = browserId || (typeof window !== "undefined" ? getBrowserId(clientKey) : "");
+  const value = useMemo(
+    () => ({
+      clientKey,
+      pointOfSale,
+      channel,
+      language,
+      currencyCode,
+      timeout,
+      browserId: effectiveBrowserId,
+      resolveDatasource: stableResolveDatasource
+    }),
+    [
+      clientKey,
+      pointOfSale,
+      channel,
+      language,
+      currencyCode,
+      timeout,
+      effectiveBrowserId,
+      stableResolveDatasource
+    ]
+  );
+  return /* @__PURE__ */ jsx(PersonalizeContext.Provider, { value, children });
+}
+function usePersonalizeContext() {
+  return useContext(PersonalizeContext);
+}
+
+// src/personalizeClient.ts
+var DEFAULT_API_BASE = "https://api.boxever.com";
+async function callPersonalize(options) {
+  const { config, context, apiBase = DEFAULT_API_BASE, componentRef, pageRoute } = options;
+  const body = {
+    clientKey: context.clientKey,
+    channel: context.channel,
+    language: context.language,
+    currencyCode: context.currencyCode,
+    pointOfSale: context.pointOfSale,
+    browserId: context.browserId,
+    friendlyId: config.friendlyId
+  };
+  if (componentRef || pageRoute) {
+    body.params = {};
+    if (componentRef) body.params.componentRef = componentRef;
+    if (pageRoute) body.params.pageRoute = pageRoute;
+  }
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), context.timeout);
+  try {
+    const res = await fetch(`${apiBase.replace(/\/$/, "")}/v2/callFlows`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (!data || typeof data !== "object") return null;
+    const contentKey = data.contentKey;
+    if (typeof contentKey !== "string" || contentKey.trim() === "") return null;
+    return contentKey;
+  } catch {
+    clearTimeout(timeoutId);
+    return null;
+  }
+}
+
+// src/contentResolver.ts
+async function resolveContent(options) {
+  const { contentKey, config, resolveDatasource } = options;
+  const effectiveKey = contentKey && contentKey in config.contentMap ? contentKey : config.defaultKey;
+  const datasourceId = config.contentMap[effectiveKey];
+  if (!datasourceId || typeof datasourceId !== "string") return null;
+  try {
+    const fields = await resolveDatasource(datasourceId);
+    if (!fields || typeof fields !== "object") return null;
+    return { datasourceId, fields };
+  } catch {
+    return null;
+  }
+}
+
+// src/withPersonalizeConnect.tsx
+import { useCallback as useCallback2, useEffect as useEffect2, useRef, useState as useState2 } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var DEFAULT_GET_CONFIG = (props) => props.rendering?.personalizeConnect;
+function withPersonalizeConnect(WrappedComponent, getConfig = DEFAULT_GET_CONFIG) {
+  function PersonalizeConnectWrapper(props) {
+    const context = usePersonalizeContext();
+    const config = getConfig(props);
+    const [resolvedFields, setResolvedFields] = useState2(null);
+    const mountedRef = useRef(true);
+    const runPersonalization = useCallback2(async () => {
+      if (!config || !context) return;
+      const contentKey = await callPersonalize({ config, context });
+      if (!mountedRef.current) return;
+      const resolved = await resolveContent({
+        contentKey,
+        config,
+        resolveDatasource: context.resolveDatasource
+      });
+      if (!mountedRef.current) return;
+      if (resolved) {
+        setResolvedFields(resolved.fields);
+      }
+    }, [config, context]);
+    useEffect2(() => {
+      mountedRef.current = true;
+      if (config && context) {
+        runPersonalization();
+      }
+      return () => {
+        mountedRef.current = false;
+      };
+    }, [config?.friendlyId, context?.clientKey, runPersonalization]);
+    if (!config || !context) {
+      return /* @__PURE__ */ jsx2(WrappedComponent, { ...props });
+    }
+    const mergedProps = {
+      ...props,
+      ...resolvedFields ?? {}
+    };
+    return /* @__PURE__ */ jsx2(WrappedComponent, { ...mergedProps });
+  }
+  PersonalizeConnectWrapper.displayName = `WithPersonalizeConnect(${WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"})`;
+  return PersonalizeConnectWrapper;
+}
+
+// src/usePersonalizeExperience.ts
+import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef2, useState as useState3 } from "react";
+function usePersonalizeExperience(config) {
+  const context = usePersonalizeContext();
+  const [contentKey, setContentKey] = useState3(null);
+  const [resolvedFields, setResolvedFields] = useState3(null);
+  const [isLoading, setIsLoading] = useState3(true);
+  const [error, setError] = useState3(null);
+  const mountedRef = useRef2(true);
+  const runPersonalization = useCallback3(async () => {
+    if (!config || !context) {
+      setIsLoading(false);
+      return;
+    }
+    setError(null);
+    setContentKey(null);
+    setResolvedFields(null);
+    setIsLoading(true);
+    try {
+      const key = await callPersonalize({ config, context });
+      if (!mountedRef.current) return;
+      setContentKey(key);
+      const resolved = await resolveContent({
+        contentKey: key,
+        config,
+        resolveDatasource: context.resolveDatasource
+      });
+      if (!mountedRef.current) return;
+      if (resolved) setResolvedFields(resolved.fields);
+    } catch (e) {
+      if (mountedRef.current) {
+        setError(e instanceof Error ? e : new Error(String(e)));
+      }
+    } finally {
+      if (mountedRef.current) setIsLoading(false);
+    }
+  }, [config, context]);
+  useEffect3(() => {
+    mountedRef.current = true;
+    runPersonalization();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [runPersonalization]);
+  return {
+    contentKey,
+    resolvedFields,
+    isLoading,
+    error
+  };
+}
+export {
+  PersonalizeProvider,
+  callPersonalize,
+  getBrowserId,
+  resolveContent,
+  usePersonalizeContext,
+  usePersonalizeExperience,
+  withPersonalizeConnect
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "personalize-connect-sdk",
+  "version": "1.0.0",
+  "description": "Runtime SDK for Personalize Connect - resolves active experience outcomes and datasources in your rendering host",
+  "keywords": [
+    "sitecore",
+    "personalize",
+    "personalization",
+    "sitecore-personalize",
+    "rendering",
+    "marketplace"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/2026-Team-Solo.git",
+    "directory": "packages/sdk"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.0",
+    "@types/react": "^18.0.0",
+    "react": "^18.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  }
+}