personalize-connect-sdk 1.1.0 → 1.2.1

package/dist/index.d.mts

@@ -24,13 +24,13 @@ interface PersonalizeConnectConfig {
 interface PersonalizeConnectResponse {
     contentKey: string;
 }
-/** What the SDK sends to Personalize /v2/callFlows */
+/** What the SDK sends to Personalize /v2/callFlows (legacy direct mode) */
 interface CallFlowsRequest {
-    clientKey: string;
+    clientKey?: string;
     channel: string;
     language: string;
     currencyCode: string;
-    pointOfSale: string;
+    pointOfSale?: string;
     browserId: string;
     friendlyId: string;
     params?: {
@@ -41,20 +41,30 @@ interface CallFlowsRequest {
 }
 /** Provider configuration */
 interface PersonalizeConnectProviderProps {
-    clientKey: string;
-    pointOfSale: string;
+    /** Sitecore Edge Context ID. When provided, all calls route through the Edge proxy. */
+    sitecoreEdgeContextId?: string;
+    /** Edge platform base URL. Defaults to https://edge-platform.sitecorecloud.io */
+    sitecoreEdgeUrl?: string;
+    /** XM Cloud site name, used with Context ID for personalize and init calls. */
+    siteName?: string;
+    /** Personalize API client key (legacy mode). Not needed when using sitecoreEdgeContextId. */
+    clientKey?: string;
+    /** Point of sale identifier (legacy mode). Not needed when using sitecoreEdgeContextId. */
+    pointOfSale?: string;
+    /** Experience Edge GraphQL endpoint for direct access (legacy). Not needed with Context ID. */
+    edgeUrl?: string;
+    /** Sitecore API key for Experience Edge (legacy). Not needed with Context ID. */
+    apiKey?: string;
     channel?: string;
     language?: string;
     currencyCode?: string;
     timeout?: number;
-    /** Custom function to fetch datasource fields by item ID. When omitted and edgeUrl + apiKey are set, the SDK resolves via Experience Edge. */
+    /** Custom function to fetch datasource fields by item ID. When omitted the SDK resolves via Edge. */
     resolveDatasource?: (datasourceId: string) => Promise<ComponentFields>;
-    /** Experience Edge GraphQL endpoint (e.g. GRAPH_QL_ENDPOINT). Enables built-in datasource resolution when resolveDatasource is not provided. */
-    edgeUrl?: string;
-    /** Sitecore API key for Experience Edge (e.g. SITECORE_API_KEY). Required alongside edgeUrl for built-in resolution. */
-    apiKey?: string;
-    /** Override editing mode detection. When true the HOC renders a visual indicator. When omitted the SDK auto-detects Page Builder / Experience Editor. */
+    /** Override editing mode detection. When true the HOC renders a visual indicator. */
     isEditing?: boolean;
+    /** Enable debug logging to the browser console. */
+    debug?: boolean;
     children: ReactNode;
 }
 /** Resolved datasource fields passed as component props */
@@ -70,30 +80,34 @@ interface PersonalizeContextValue {
     browserId: string;
     resolveDatasource: (datasourceId: string) => Promise<ComponentFields>;
     isEditing: boolean;
+    /** True when operating in Edge Context ID mode */
+    useEdgeProxy: boolean;
+    /** Edge proxy base URL (only set in Context ID mode) */
+    edgeProxyUrl: string;
+    /** Context ID (only set in Context ID mode) */
+    sitecoreEdgeContextId: string;
+    /** Site name (only set in Context ID mode) */
+    siteName: string;
 }
 
-declare function PersonalizeProvider({ children, clientKey, pointOfSale, channel, language, currencyCode, timeout, resolveDatasource, edgeUrl, apiKey, isEditing: isEditingProp, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
+declare function PersonalizeProvider({ children, sitecoreEdgeContextId, sitecoreEdgeUrl, siteName, clientKey, pointOfSale, edgeUrl, apiKey, channel, language, currencyCode, timeout, resolveDatasource, isEditing: isEditingProp, debug, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePersonalizeContext(): PersonalizeContextValue | null;
 
 /**
- * Thin async wrapper around POST /v2/callFlows.
- * Enforces timeout, parses response, validates contentKey.
+ * Calls Sitecore Personalize to resolve the active content key.
+ *
+ * Legacy mode:  POST https://api.boxever.com/v2/callFlows
+ * Context ID:   POST {edgeUrl}/v1/personalize?sitecoreContextId=...&siteName=...
  */
 
 interface CallPersonalizeOptions {
     config: PersonalizeConnectConfig;
     context: PersonalizeContextValue;
-    /** Optional: override API base URL (e.g. region-specific) */
+    /** Override API base URL (legacy mode only) */
     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>;
 
 /**
@@ -119,13 +133,13 @@ declare function resolveContent(options: ResolveContentOptions): Promise<Resolve
 
 type GetConfigFromProps<P> = (props: P) => PersonalizeConnectConfig | undefined;
 /**
- * HOC that wraps any JSS/Content SDK component.
+ * HOC that wraps any JSS 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.
  *
- * In editing mode (Page Builder / Experience Editor), renders a visual
- * indicator (border + badge) on components that have personalization configured.
+ * In Page Builder, renders a visual indicator (border + badge) on
+ * components that have personalization configured.
  */
 declare function withPersonalizeConnect<P extends object>(WrappedComponent: ComponentType<P>, getConfig?: GetConfigFromProps<P>): ComponentType<P>;
 
@@ -143,36 +157,63 @@ declare function usePersonalizeExperience(config: PersonalizeConnectConfig | und
 
 /**
  * Built-in Experience Edge datasource resolver.
- * Queries Experience Edge GraphQL by item GUID, returns fields in JSS shape.
+ *
+ * Legacy mode:    Direct Edge GraphQL with sc_apikey header.
+ * Context ID mode: Edge proxy GraphQL — Context ID is the auth, no API key needed.
  */
 
 /**
- * Creates a datasource resolver backed by Experience Edge GraphQL.
- * When passed as (or used in place of) `resolveDatasource`, allows the SDK
- * to fetch datasource fields without the consuming app providing any resolver.
+ * Legacy: creates a resolver that calls Experience Edge directly with an API key.
  */
 declare function createEdgeResolver(edgeUrl: string, apiKey: string, language?: string): (datasourceId: string) => Promise<ComponentFields>;
+/**
+ * Context ID mode: creates a resolver that calls the Edge proxy GraphQL endpoint.
+ * No API key header — the Context ID in the URL is the auth.
+ */
+declare function createEdgeProxyResolver(edgeBaseUrl: string, contextId: string, language?: string): (datasourceId: string) => Promise<ComponentFields>;
 
 /**
- * Lightweight Sitecore editing mode detection.
- * Works in Experience Editor and XM Cloud Pages without importing JSS.
+ * XM Cloud Pages (Page Builder) editing mode detection.
+ * Uses the same Sitecore context shape that JSS for XMC writes to __NEXT_DATA__.
  */
 /**
- * Detects whether the page is currently rendered inside a Sitecore editor
- * (Experience Editor or XM Cloud Pages). Result is cached after the first call.
+ * Detects whether the page is rendered inside XM Cloud Pages (Page Builder).
+ * Checks the JSS Sitecore context for pageEditing / pageState, and whether
+ * the rendering host is loaded in an iframe (Pages always iframes the site).
+ * Result is cached after the first call.
  */
 declare function isEditingMode(): boolean;
 /** Reset the cached result (useful for testing). */
 declare function resetEditingDetectionCache(): void;
 
 /**
- * Manages the Sitecore CDP browser ID cookie (bid_<clientKey>).
- * Used for session continuity across Personalize decisions.
+ * SDK debug logger. All output is prefixed with [PersonalizeConnect].
+ * Enable by passing debug={true} on PersonalizeProvider.
  */
+declare function setDebug(on: boolean): void;
+declare function isDebugEnabled(): boolean;
+
 /**
- * Get or create the browser ID for the given client key.
- * Reads from cookie bid_<clientKey>, writes if missing, and returns the value.
+ * Manages the Sitecore CDP browser ID.
+ *
+ * Legacy mode:  cookie bid_<clientKey>, generated locally.
+ * Context ID mode: fetched from Edge proxy /v1/init, stored in cookie sc_<contextId>_personalize.
+ */
+/**
+ * Legacy: get or create browser ID from a local cookie keyed by clientKey.
  */
 declare function getBrowserId(clientKey: string): string;
+/** Response shape from the Edge proxy /v1/init endpoint */
+interface EdgeInitResponse {
+    browserId: string;
+    guestId?: string;
+}
+/**
+ * Context ID mode: fetch browser ID from the Edge proxy init endpoint.
+ * Checks cookie first; if missing, calls /v1/init and caches the result.
+ */
+declare function getEdgeBrowserId(edgeUrl: string, contextId: string, siteName: string): Promise<string>;
+/** Reset the cached init promise (for testing). */
+declare function resetEdgeInitCache(): void;
 
-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, createEdgeResolver, getBrowserId, isEditingMode, resetEditingDetectionCache, resolveContent, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };
+export { type CallFlowsRequest, type CallPersonalizeOptions, type ComponentFields, type EdgeInitResponse, type GetConfigFromProps, type PersonalizeConnectConfig, type PersonalizeConnectProviderProps, type PersonalizeConnectResponse, type PersonalizeContextValue, PersonalizeProvider, type ResolveContentOptions, type ResolvedContent, type UsePersonalizeExperienceResult, callPersonalize, createEdgeProxyResolver, createEdgeResolver, getBrowserId, getEdgeBrowserId, isDebugEnabled, isEditingMode, resetEdgeInitCache, resetEditingDetectionCache, resolveContent, setDebug, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };

package/dist/index.d.ts

@@ -24,13 +24,13 @@ interface PersonalizeConnectConfig {
 interface PersonalizeConnectResponse {
     contentKey: string;
 }
-/** What the SDK sends to Personalize /v2/callFlows */
+/** What the SDK sends to Personalize /v2/callFlows (legacy direct mode) */
 interface CallFlowsRequest {
-    clientKey: string;
+    clientKey?: string;
     channel: string;
     language: string;
     currencyCode: string;
-    pointOfSale: string;
+    pointOfSale?: string;
     browserId: string;
     friendlyId: string;
     params?: {
@@ -41,20 +41,30 @@ interface CallFlowsRequest {
 }
 /** Provider configuration */
 interface PersonalizeConnectProviderProps {
-    clientKey: string;
-    pointOfSale: string;
+    /** Sitecore Edge Context ID. When provided, all calls route through the Edge proxy. */
+    sitecoreEdgeContextId?: string;
+    /** Edge platform base URL. Defaults to https://edge-platform.sitecorecloud.io */
+    sitecoreEdgeUrl?: string;
+    /** XM Cloud site name, used with Context ID for personalize and init calls. */
+    siteName?: string;
+    /** Personalize API client key (legacy mode). Not needed when using sitecoreEdgeContextId. */
+    clientKey?: string;
+    /** Point of sale identifier (legacy mode). Not needed when using sitecoreEdgeContextId. */
+    pointOfSale?: string;
+    /** Experience Edge GraphQL endpoint for direct access (legacy). Not needed with Context ID. */
+    edgeUrl?: string;
+    /** Sitecore API key for Experience Edge (legacy). Not needed with Context ID. */
+    apiKey?: string;
     channel?: string;
     language?: string;
     currencyCode?: string;
     timeout?: number;
-    /** Custom function to fetch datasource fields by item ID. When omitted and edgeUrl + apiKey are set, the SDK resolves via Experience Edge. */
+    /** Custom function to fetch datasource fields by item ID. When omitted the SDK resolves via Edge. */
     resolveDatasource?: (datasourceId: string) => Promise<ComponentFields>;
-    /** Experience Edge GraphQL endpoint (e.g. GRAPH_QL_ENDPOINT). Enables built-in datasource resolution when resolveDatasource is not provided. */
-    edgeUrl?: string;
-    /** Sitecore API key for Experience Edge (e.g. SITECORE_API_KEY). Required alongside edgeUrl for built-in resolution. */
-    apiKey?: string;
-    /** Override editing mode detection. When true the HOC renders a visual indicator. When omitted the SDK auto-detects Page Builder / Experience Editor. */
+    /** Override editing mode detection. When true the HOC renders a visual indicator. */
     isEditing?: boolean;
+    /** Enable debug logging to the browser console. */
+    debug?: boolean;
     children: ReactNode;
 }
 /** Resolved datasource fields passed as component props */
@@ -70,30 +80,34 @@ interface PersonalizeContextValue {
     browserId: string;
     resolveDatasource: (datasourceId: string) => Promise<ComponentFields>;
     isEditing: boolean;
+    /** True when operating in Edge Context ID mode */
+    useEdgeProxy: boolean;
+    /** Edge proxy base URL (only set in Context ID mode) */
+    edgeProxyUrl: string;
+    /** Context ID (only set in Context ID mode) */
+    sitecoreEdgeContextId: string;
+    /** Site name (only set in Context ID mode) */
+    siteName: string;
 }
 
-declare function PersonalizeProvider({ children, clientKey, pointOfSale, channel, language, currencyCode, timeout, resolveDatasource, edgeUrl, apiKey, isEditing: isEditingProp, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
+declare function PersonalizeProvider({ children, sitecoreEdgeContextId, sitecoreEdgeUrl, siteName, clientKey, pointOfSale, edgeUrl, apiKey, channel, language, currencyCode, timeout, resolveDatasource, isEditing: isEditingProp, debug, }: PersonalizeConnectProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePersonalizeContext(): PersonalizeContextValue | null;
 
 /**
- * Thin async wrapper around POST /v2/callFlows.
- * Enforces timeout, parses response, validates contentKey.
+ * Calls Sitecore Personalize to resolve the active content key.
+ *
+ * Legacy mode:  POST https://api.boxever.com/v2/callFlows
+ * Context ID:   POST {edgeUrl}/v1/personalize?sitecoreContextId=...&siteName=...
  */
 
 interface CallPersonalizeOptions {
     config: PersonalizeConnectConfig;
     context: PersonalizeContextValue;
-    /** Optional: override API base URL (e.g. region-specific) */
+    /** Override API base URL (legacy mode only) */
     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>;
 
 /**
@@ -119,13 +133,13 @@ declare function resolveContent(options: ResolveContentOptions): Promise<Resolve
 
 type GetConfigFromProps<P> = (props: P) => PersonalizeConnectConfig | undefined;
 /**
- * HOC that wraps any JSS/Content SDK component.
+ * HOC that wraps any JSS 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.
  *
- * In editing mode (Page Builder / Experience Editor), renders a visual
- * indicator (border + badge) on components that have personalization configured.
+ * In Page Builder, renders a visual indicator (border + badge) on
+ * components that have personalization configured.
  */
 declare function withPersonalizeConnect<P extends object>(WrappedComponent: ComponentType<P>, getConfig?: GetConfigFromProps<P>): ComponentType<P>;
 
@@ -143,36 +157,63 @@ declare function usePersonalizeExperience(config: PersonalizeConnectConfig | und
 
 /**
  * Built-in Experience Edge datasource resolver.
- * Queries Experience Edge GraphQL by item GUID, returns fields in JSS shape.
+ *
+ * Legacy mode:    Direct Edge GraphQL with sc_apikey header.
+ * Context ID mode: Edge proxy GraphQL — Context ID is the auth, no API key needed.
  */
 
 /**
- * Creates a datasource resolver backed by Experience Edge GraphQL.
- * When passed as (or used in place of) `resolveDatasource`, allows the SDK
- * to fetch datasource fields without the consuming app providing any resolver.
+ * Legacy: creates a resolver that calls Experience Edge directly with an API key.
  */
 declare function createEdgeResolver(edgeUrl: string, apiKey: string, language?: string): (datasourceId: string) => Promise<ComponentFields>;
+/**
+ * Context ID mode: creates a resolver that calls the Edge proxy GraphQL endpoint.
+ * No API key header — the Context ID in the URL is the auth.
+ */
+declare function createEdgeProxyResolver(edgeBaseUrl: string, contextId: string, language?: string): (datasourceId: string) => Promise<ComponentFields>;
 
 /**
- * Lightweight Sitecore editing mode detection.
- * Works in Experience Editor and XM Cloud Pages without importing JSS.
+ * XM Cloud Pages (Page Builder) editing mode detection.
+ * Uses the same Sitecore context shape that JSS for XMC writes to __NEXT_DATA__.
  */
 /**
- * Detects whether the page is currently rendered inside a Sitecore editor
- * (Experience Editor or XM Cloud Pages). Result is cached after the first call.
+ * Detects whether the page is rendered inside XM Cloud Pages (Page Builder).
+ * Checks the JSS Sitecore context for pageEditing / pageState, and whether
+ * the rendering host is loaded in an iframe (Pages always iframes the site).
+ * Result is cached after the first call.
  */
 declare function isEditingMode(): boolean;
 /** Reset the cached result (useful for testing). */
 declare function resetEditingDetectionCache(): void;
 
 /**
- * Manages the Sitecore CDP browser ID cookie (bid_<clientKey>).
- * Used for session continuity across Personalize decisions.
+ * SDK debug logger. All output is prefixed with [PersonalizeConnect].
+ * Enable by passing debug={true} on PersonalizeProvider.
  */
+declare function setDebug(on: boolean): void;
+declare function isDebugEnabled(): boolean;
+
 /**
- * Get or create the browser ID for the given client key.
- * Reads from cookie bid_<clientKey>, writes if missing, and returns the value.
+ * Manages the Sitecore CDP browser ID.
+ *
+ * Legacy mode:  cookie bid_<clientKey>, generated locally.
+ * Context ID mode: fetched from Edge proxy /v1/init, stored in cookie sc_<contextId>_personalize.
+ */
+/**
+ * Legacy: get or create browser ID from a local cookie keyed by clientKey.
  */
 declare function getBrowserId(clientKey: string): string;
+/** Response shape from the Edge proxy /v1/init endpoint */
+interface EdgeInitResponse {
+    browserId: string;
+    guestId?: string;
+}
+/**
+ * Context ID mode: fetch browser ID from the Edge proxy init endpoint.
+ * Checks cookie first; if missing, calls /v1/init and caches the result.
+ */
+declare function getEdgeBrowserId(edgeUrl: string, contextId: string, siteName: string): Promise<string>;
+/** Reset the cached init promise (for testing). */
+declare function resetEdgeInitCache(): void;
 
-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, createEdgeResolver, getBrowserId, isEditingMode, resetEditingDetectionCache, resolveContent, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };
+export { type CallFlowsRequest, type CallPersonalizeOptions, type ComponentFields, type EdgeInitResponse, type GetConfigFromProps, type PersonalizeConnectConfig, type PersonalizeConnectProviderProps, type PersonalizeConnectResponse, type PersonalizeContextValue, PersonalizeProvider, type ResolveContentOptions, type ResolvedContent, type UsePersonalizeExperienceResult, callPersonalize, createEdgeProxyResolver, createEdgeResolver, getBrowserId, getEdgeBrowserId, isDebugEnabled, isEditingMode, resetEdgeInitCache, resetEditingDetectionCache, resolveContent, setDebug, usePersonalizeContext, usePersonalizeExperience, withPersonalizeConnect };