@coveo/shopify 1.2.2-pre.e593f8f8f7 → 1.3.0-pre.49914cd105

package/README.md

@@ -6,7 +6,7 @@ It includes functions to fetch app proxy configurations and build a commerce eng
 
 ## Benefits
 
-Using the `@coveo/shopify` package ensures that the commerce engine will emit events using the same `clientId` both inside and outside Shopify Web Pixels. This provides consistent tracking and analytics across the entire Shopify ecosystem.
+Using the `@coveo/shopify` package ensures that the commerce engine will emit events using the same `clientId` both inside and outside Shopify Web Pixels. This provides consistent tracking and analytics across the entire Shopify ecosystem. When initializing the commerce engine, a custom event is emitted using the `coveo_shopify_config` key. This event enables Shopify Web Pixels to access the app proxy configuration, ensuring consistent tracking and personalization across storefronts and pixels.
 
 ## Installation
 
@@ -41,7 +41,7 @@ A promise that resolves to an object containing:
 #### Example
 
 ```typescript
-import {fetchAppProxyConfig} from '@coveo/shopify/headless';
+import {fetchAppProxyConfig} from '@coveo/shopify/headless/commerce';
 
 const config = await fetchAppProxyConfig({
   marketId: 'market_123432',
@@ -67,7 +67,7 @@ A configured commerce engine instance.
 
 ```typescript
 <script type="module">
-import {buildShopifyCommerceEngine, fetchAppProxyConfig} from 'https://static.cloud.coveo.com/shopify/v1/headless.esm.js';
+import {buildShopifyCommerceEngine, fetchAppProxyConfig} from 'https://static.cloud.coveo.com/shopify/v1/headless/commerce.esm.js';
 
 const config = await fetchAppProxyConfig({marketId: 'market_123432'});
 const engine = buildShopifyCommerceEngine({
@@ -102,25 +102,31 @@ console.log(engine);
 </script>
 ```
 
-### `getShopifyCookie`
+### `getClientId`
 
-Retrieves the value of a specified Shopify cookie by its name.
+Generates a unique client identifier for the Shopify store, based on the value of the Shopify `_shopify_y` cookie. This ensures consistent identification of users across storefronts and Shopify Web Pixels.
 
-#### Returns
+#### Parameters
 
-The value of the specified cookie, or `null` if the cookie is not found.
+- `shopifyCookie` (required): The value of the Shopify `_shopify_y` cookie.
 
-#### Notes
+#### Returns
 
-This function is intended for use in **browser environments only**, as it relies on the `document.cookie` API. Attempting to use this function in non-browser environments will result in an error or undefined behavior.
+A version 5 UUID string uniquely representing the client.
 
 #### Example
 
 ```typescript
-import {getShopifyCookie} from '@coveo/shopify';
+import {getClientId, getShopifyCookie} from '@coveo/shopify/utilities';
 
 const shopifyCookie = getShopifyCookie();
-console.log(shopifyCookie);
+const clientId = getClientId(shopifyCookie!);
+console.log(clientId);
 ```
 
+**Key constants:**
+
+- `SHOPIFY_COOKIE_KEY`: The name of the Shopify cookie used for client identification (`_shopify_y`).
+- `COVEO_SHOPIFY_CONFIG_KEY`: The key for the custom event and cookie used to share app proxy configuration (`coveo_shopify_config`).
+
 ---

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const SHOPIFY_COOKIE_KEY = "_shopify_y";
+/**
+ * The key used for storing and emitting the app proxy configuration.
+ *
+ * This constant serves two purposes:
+ * - It is the name of the custom event emitted to pass app proxy configuration to the web pixel.
+ * - It is also the name of the cookie where the app proxy configuration information is stored.
+ */
+export declare const COVEO_SHOPIFY_CONFIG_KEY = "coveo_shopify_config";

package/dist/constants.js

@@ -0,0 +1,9 @@
+export const SHOPIFY_COOKIE_KEY = '_shopify_y';
+/**
+ * The key used for storing and emitting the app proxy configuration.
+ *
+ * This constant serves two purposes:
+ * - It is the name of the custom event emitted to pass app proxy configuration to the web pixel.
+ * - It is also the name of the cookie where the app proxy configuration information is stored.
+ */
+export const COVEO_SHOPIFY_CONFIG_KEY = 'coveo_shopify_config';

package/dist/{headless.d.ts → headless/commerce.d.ts}

@@ -1,32 +1,24 @@
 import { CommerceEngineOptions } from '@coveo/headless/commerce';
-import { CustomEnvironment } from '@coveo/relay';
+import { ShopifyCustomEnvironment } from '../types';
+export { SHOPIFY_COOKIE_KEY, COVEO_SHOPIFY_CONFIG_KEY } from '../constants';
 export * from '@coveo/headless/commerce';
-export * from './utilities';
-export declare const SHOPIFY_COOKIE_KEY = "_shopify_y";
-export interface AppProxyOptions {
-    appProxyUrl?: string;
-    marketId: string;
-}
-export interface AppProxyResponse {
-    accessToken: string;
-    organizationId: string;
-    environment: CommerceEngineOptions['configuration']['environment'];
-    trackingId: string;
-}
+export * from '../utilities';
+export type { AppProxyConfig, AppProxyResponse, ShopifyCustomEnvironment, } from '../types';
 /**
- * Fetches configuration from the app proxy.
+ * Options for building a Shopify commerce engine.
+ *
+ * @typedef BuildShopifyCommerceEngineOptions
+ * @property {CommerceEngineOptions} commerceEngineOptions - The core options for configuring the commerce engine.
+ * @property {ShopifyCustomEnvironment} [environment] - Optional browser environment; if not provided, a default one is created. Mainly useful when not running in a browser environment.
+ * @property {string} [shopifyCookie] - Optional value of the "_shopify_y" cookie. If not provided, it will attempt to retrieve it from the browser's cookies.
  *
- * Performs an HTTP GET request to retrieve the app proxy configuration using the provided marketId.
- * The fetched response is parsed as JSON and returned.
+ * @remarks
+ * The `generateUUID` and `storage` properties are omitted from the custom environment for Shopify
+ * to ensure that client IDs are generated consistently across web pixels and storefronts. This is
+ * critical for maintaining a unified tracking and personalization experience.
  *
- * @param appProxyUrl - The URL template for the app proxy endpoint. Defaults to '/apps/coveo'.
- * @param marketId - The unique market identifier used as a query parameter.
- * @returns A promise that resolves to an object containing the access token, organization ID,
- *          environment, and tracking ID.
  */
-export declare function fetchAppProxyConfig({ appProxyUrl, marketId, }: AppProxyOptions): Promise<AppProxyResponse>;
-type ShopifyCustomEnvironment = Omit<CustomEnvironment, 'storage' | 'generateUUID'>;
-interface BuildShopifyCommerceEngineOptions {
+export interface BuildShopifyCommerceEngineOptions {
     commerceEngineOptions: CommerceEngineOptions;
     shopifyCookie?: string;
     environment?: ShopifyCustomEnvironment;
@@ -37,6 +29,7 @@ interface BuildShopifyCommerceEngineOptions {
  * This function initializes a commerce engine instance specific to a Shopify store by:
  * - Creating or using an existing browser environment.
  * - Retrieving the "_shopify_y" cookie to confirm it is running in a Shopify context.
+ * - Emitting a custom event with the app proxy response to enable tracking and analytics with shopify webpixels.
  * - Storing a client identifier derived from the shop and cookie value in the browser environment's storage.
  * - Building and returning the commerce engine with the provided options.
  *
@@ -52,14 +45,3 @@ interface BuildShopifyCommerceEngineOptions {
  * @throws Error if the required "_shopify_y" cookie is not found, ensuring the code runs within a Shopify store.
  */
 export declare function buildShopifyCommerceEngine({ commerceEngineOptions, shopifyCookie, environment, }: BuildShopifyCommerceEngineOptions): import("@coveo/headless/commerce").CommerceEngine<{}>;
-/**
- * Retrieves the value of a specified Shopify cookie by its name.
- *
- * @remarks
- * This function is intended for use in browser environments only, as it relies on the `document.cookie` API.
- * Attempting to use this function in non-browser environments will result in an error or undefined behavior.
- *
- * @param name - The name of the Shopify cookie to retrieve. Defaults to `'_shopify_y'`.
- * @returns The value of the specified cookie, or `null` if the cookie is not found.
- */
-export declare function getShopifyCookie(name?: string): string | null;

package/dist/headless/commerce.esm.js

@@ -0,0 +1,112 @@
+/**
+ * @license
+ *
+ * Copyright 2025 Coveo Solutions Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// src/headless/commerce.ts
+import {
+  buildCommerceEngine
+} from "@coveo/headless/commerce";
+import { buildBrowserEnvironment } from "@coveo/relay";
+
+// src/constants.ts
+var SHOPIFY_COOKIE_KEY = "_shopify_y";
+var COVEO_SHOPIFY_CONFIG_KEY = "coveo_shopify_config";
+
+// src/types.ts
+function getShopifyCustomEnvironment(environment) {
+  const { storage, generateUUID, ...rest } = environment;
+  return rest;
+}
+
+// src/utilities/clientid.ts
+import { v5 } from "uuid";
+var UUID_NAMESPACE = "c2db3701-991e-424d-b117-03e30d43b651";
+function getClientId(shopifyCookie) {
+  return v5(shopifyCookie, UUID_NAMESPACE);
+}
+
+// src/utilities/shopify.ts
+function getShopifyCookie(name = SHOPIFY_COOKIE_KEY) {
+  const match = document.cookie.match(
+    new RegExp("(?:^|;\\s*)" + name + "=([^;]*)")
+  );
+  return match ? decodeURIComponent(match[1]) : null;
+}
+function publishCustomShopifyEvent(key, customData) {
+  if (typeof window.Shopify?.analytics?.publish === "function") {
+    window.Shopify.analytics.publish(key, customData);
+  }
+}
+
+// src/headless/commerce.ts
+export * from "@coveo/headless/commerce";
+
+// src/utilities/app-proxy.ts
+async function fetchAppProxyConfig({
+  appProxyUrl = "/apps/coveo",
+  marketId
+}) {
+  const response = await fetch(`${appProxyUrl}?marketId=${marketId}]`);
+  return response.json();
+}
+
+// src/headless/commerce.ts
+function buildShopifyCommerceEngine({
+  commerceEngineOptions,
+  shopifyCookie,
+  environment
+}) {
+  const customEnvironment = environment ?? getShopifyCustomEnvironment(buildBrowserEnvironment());
+  const cookie = shopifyCookie || getShopifyCookie();
+  if (!commerceEngineOptions.configuration.analytics.trackingId) {
+    throw new Error(
+      "The configuration for the commerce engine must include an analytics tracking ID."
+    );
+  }
+  if (!cookie) {
+    throw new Error(
+      "Unable to find the _shopify_y cookie. Please ensure you are running this code in a Shopify store."
+    );
+  }
+  const appProxyResponse = {
+    accessToken: commerceEngineOptions.configuration.accessToken,
+    organizationId: commerceEngineOptions.configuration.organizationId,
+    environment: commerceEngineOptions.configuration.environment,
+    trackingId: commerceEngineOptions.configuration.analytics.trackingId
+  };
+  publishCustomShopifyEvent(
+    COVEO_SHOPIFY_CONFIG_KEY,
+    appProxyResponse
+  );
+  const clientId = getClientId(cookie);
+  const engine = buildCommerceEngine(commerceEngineOptions);
+  engine.relay.updateConfig({
+    environment: {
+      ...customEnvironment,
+      generateUUID: () => clientId
+    }
+  });
+  return engine;
+}
+export {
+  COVEO_SHOPIFY_CONFIG_KEY,
+  SHOPIFY_COOKIE_KEY,
+  buildShopifyCommerceEngine,
+  fetchAppProxyConfig,
+  getClientId,
+  getShopifyCookie
+};

package/dist/{headless.js → headless/commerce.js}

@@ -1,30 +1,20 @@
 import { buildCommerceEngine, } from '@coveo/headless/commerce';
 import { buildBrowserEnvironment } from '@coveo/relay';
-import { getClientId } from './utilities';
+import { COVEO_SHOPIFY_CONFIG_KEY } from '../constants';
+import { getShopifyCustomEnvironment, } from '../types';
+import { getClientId } from '../utilities/clientid';
+import { publishCustomShopifyEvent } from '../utilities/shopify';
+import { getShopifyCookie } from '../utilities/shopify';
+export { SHOPIFY_COOKIE_KEY, COVEO_SHOPIFY_CONFIG_KEY } from '../constants';
 export * from '@coveo/headless/commerce';
-export * from './utilities';
-export const SHOPIFY_COOKIE_KEY = '_shopify_y';
-/**
- * Fetches configuration from the app proxy.
- *
- * Performs an HTTP GET request to retrieve the app proxy configuration using the provided marketId.
- * The fetched response is parsed as JSON and returned.
- *
- * @param appProxyUrl - The URL template for the app proxy endpoint. Defaults to '/apps/coveo'.
- * @param marketId - The unique market identifier used as a query parameter.
- * @returns A promise that resolves to an object containing the access token, organization ID,
- *          environment, and tracking ID.
- */
-export async function fetchAppProxyConfig({ appProxyUrl = '/apps/coveo', marketId, }) {
-    const response = await fetch(`${appProxyUrl}?marketId=${marketId}]`);
-    return response.json();
-}
+export * from '../utilities';
 /**
  * Builds the commerce engine for a Shopify store.
  *
  * This function initializes a commerce engine instance specific to a Shopify store by:
  * - Creating or using an existing browser environment.
  * - Retrieving the "_shopify_y" cookie to confirm it is running in a Shopify context.
+ * - Emitting a custom event with the app proxy response to enable tracking and analytics with shopify webpixels.
  * - Storing a client identifier derived from the shop and cookie value in the browser environment's storage.
  * - Building and returning the commerce engine with the provided options.
  *
@@ -42,9 +32,19 @@ export async function fetchAppProxyConfig({ appProxyUrl = '/apps/coveo', marketI
 export function buildShopifyCommerceEngine({ commerceEngineOptions, shopifyCookie, environment, }) {
     const customEnvironment = environment ?? getShopifyCustomEnvironment(buildBrowserEnvironment());
     const cookie = shopifyCookie || getShopifyCookie();
+    if (!commerceEngineOptions.configuration.analytics.trackingId) {
+        throw new Error('The configuration for the commerce engine must include an analytics tracking ID.');
+    }
     if (!cookie) {
         throw new Error('Unable to find the _shopify_y cookie. Please ensure you are running this code in a Shopify store.');
     }
+    const appProxyResponse = {
+        accessToken: commerceEngineOptions.configuration.accessToken,
+        organizationId: commerceEngineOptions.configuration.organizationId,
+        environment: commerceEngineOptions.configuration.environment,
+        trackingId: commerceEngineOptions.configuration.analytics.trackingId,
+    };
+    publishCustomShopifyEvent(COVEO_SHOPIFY_CONFIG_KEY, appProxyResponse);
     const clientId = getClientId(cookie);
     const engine = buildCommerceEngine(commerceEngineOptions);
     engine.relay.updateConfig({
@@ -55,21 +55,3 @@ export function buildShopifyCommerceEngine({ commerceEngineOptions, shopifyCooki
     });
     return engine;
 }
-function getShopifyCustomEnvironment(environment) {
-    const { storage, generateUUID, ...rest } = environment;
-    return rest;
-}
-/**
- * Retrieves the value of a specified Shopify cookie by its name.
- *
- * @remarks
- * This function is intended for use in browser environments only, as it relies on the `document.cookie` API.
- * Attempting to use this function in non-browser environments will result in an error or undefined behavior.
- *
- * @param name - The name of the Shopify cookie to retrieve. Defaults to `'_shopify_y'`.
- * @returns The value of the specified cookie, or `null` if the cookie is not found.
- */
-export function getShopifyCookie(name = SHOPIFY_COOKIE_KEY) {
-    const match = document.cookie.match(new RegExp('(?:^|;\\s*)' + name + '=([^;]*)'));
-    return match ? decodeURIComponent(match[1]) : null;
-}

package/dist/headless/index.d.ts

@@ -0,0 +1 @@
+export * from './commerce';

package/dist/headless/index.js

@@ -0,0 +1 @@
+export * from './commerce';

package/dist/headless/search.d.ts

@@ -0,0 +1,47 @@
+import { SearchEngineOptions } from '@coveo/headless';
+import { ShopifyCustomEnvironment } from '../types';
+export { SHOPIFY_COOKIE_KEY, COVEO_SHOPIFY_CONFIG_KEY } from '../constants';
+export type { AppProxyConfig, AppProxyResponse, ShopifyCustomEnvironment, } from '../types';
+export * from '@coveo/headless';
+export * from '../utilities';
+/**
+ * Options for building a Shopify search engine instance.
+ *
+ * @typedef BuildShopifySearchEngineOptions
+ * @property {SearchEngineOptions} searchEngineOptions - The core options for configuring the search engine.
+ * @property {ShopifyCustomEnvironment} [environment] - Optional browser environment; if not provided, a default one is created. Mainly useful when not running in a browser environment.
+ * @property {string} [shopifyCookie] - Optional value of the "_shopify_y" cookie. If not provided, it will attempt to retrieve it from the browser's cookies.
+ *
+ * @remarks
+ * The `generateUUID` and `storage` properties are omitted from the custom environment for Shopify
+ * to ensure that client IDs are generated consistently across web pixels and storefronts. This is
+ * critical for maintaining a unified tracking and personalization experience.
+ *
+ */
+export interface BuildShopifySearchEngineOptions {
+    searchEngineOptions: SearchEngineOptions;
+    environment?: ShopifyCustomEnvironment;
+    shopifyCookie?: string;
+}
+/**
+ * Builds the search engine for a Shopify store.
+ *
+ * This function initializes a search engine instance specific to a Shopify store by:
+ * - Creating or using an existing browser environment.
+ * - Retrieving the "_shopify_y" cookie to confirm it is running in a Shopify context.
+ * - Emitting a custom event with the app proxy response to enable tracking and analytics with shopify webpixels.
+ * - Storing a client identifier derived from the shop and cookie value in the browser environment's storage.
+ * - Building and returning the search engine with the provided options.
+ *
+ * @remarks
+ * The `generateUUID` and `storage` properties are omitted from the custom environment for Shopify
+ * to ensure that client IDs are generated consistently across web pixels and storefronts. This is
+ * critical for maintaining a unified tracking and personalization experience.
+ *
+ * @param searchEngineOptions - Options to configure the search engine.
+ * @param shopifyCookie - Optional value of the "_shopify_y" cookie. If not provided, it will attempt to retrieve it from the browser's cookies.
+ * @param environment - Optional browser environment; if not provided, a default one is created. Mainly useful when not running in a browser environment.
+ * @returns The constructed search engine instance.
+ * @throws Error if the required "_shopify_y" cookie is not found, ensuring the code runs within a Shopify store.
+ */
+export declare function buildShopifySearchEngine({ searchEngineOptions, environment, shopifyCookie, }: BuildShopifySearchEngineOptions): import("@coveo/headless").SearchEngine<{}>;

package/dist/headless/search.esm.js

@@ -0,0 +1,110 @@
+/**
+ * @license
+ *
+ * Copyright 2025 Coveo Solutions Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// src/headless/search.ts
+import { buildSearchEngine } from "@coveo/headless";
+import { buildBrowserEnvironment } from "@coveo/relay";
+
+// src/constants.ts
+var SHOPIFY_COOKIE_KEY = "_shopify_y";
+var COVEO_SHOPIFY_CONFIG_KEY = "coveo_shopify_config";
+
+// src/types.ts
+function getShopifyCustomEnvironment(environment) {
+  const { storage, generateUUID, ...rest } = environment;
+  return rest;
+}
+
+// src/utilities/clientid.ts
+import { v5 } from "uuid";
+var UUID_NAMESPACE = "c2db3701-991e-424d-b117-03e30d43b651";
+function getClientId(shopifyCookie) {
+  return v5(shopifyCookie, UUID_NAMESPACE);
+}
+
+// src/utilities/shopify.ts
+function getShopifyCookie(name = SHOPIFY_COOKIE_KEY) {
+  const match = document.cookie.match(
+    new RegExp("(?:^|;\\s*)" + name + "=([^;]*)")
+  );
+  return match ? decodeURIComponent(match[1]) : null;
+}
+function publishCustomShopifyEvent(key, customData) {
+  if (typeof window.Shopify?.analytics?.publish === "function") {
+    window.Shopify.analytics.publish(key, customData);
+  }
+}
+
+// src/headless/search.ts
+export * from "@coveo/headless";
+
+// src/utilities/app-proxy.ts
+async function fetchAppProxyConfig({
+  appProxyUrl = "/apps/coveo",
+  marketId
+}) {
+  const response = await fetch(`${appProxyUrl}?marketId=${marketId}]`);
+  return response.json();
+}
+
+// src/headless/search.ts
+function buildShopifySearchEngine({
+  searchEngineOptions,
+  environment,
+  shopifyCookie
+}) {
+  const customEnvironment = environment ?? getShopifyCustomEnvironment(buildBrowserEnvironment());
+  const cookie = shopifyCookie || getShopifyCookie();
+  if (!searchEngineOptions.configuration.analytics?.trackingId) {
+    throw new Error(
+      "The configuration for the search engine must include an analytics tracking ID."
+    );
+  }
+  if (!cookie) {
+    throw new Error(
+      "Unable to find the _shopify_y cookie. Please ensure you are running this code in a Shopify store."
+    );
+  }
+  const appProxyResponse = {
+    accessToken: searchEngineOptions.configuration.accessToken,
+    organizationId: searchEngineOptions.configuration.organizationId,
+    environment: searchEngineOptions.configuration.environment,
+    trackingId: searchEngineOptions.configuration.analytics.trackingId
+  };
+  publishCustomShopifyEvent(
+    COVEO_SHOPIFY_CONFIG_KEY,
+    appProxyResponse
+  );
+  const clientId = getClientId(cookie);
+  const engine = buildSearchEngine(searchEngineOptions);
+  engine.relay.updateConfig({
+    environment: {
+      ...customEnvironment,
+      generateUUID: () => clientId
+    }
+  });
+  return engine;
+}
+export {
+  COVEO_SHOPIFY_CONFIG_KEY,
+  SHOPIFY_COOKIE_KEY,
+  buildShopifySearchEngine,
+  fetchAppProxyConfig,
+  getClientId,
+  getShopifyCookie
+};

package/dist/headless/search.js

@@ -0,0 +1,57 @@
+import { buildSearchEngine } from '@coveo/headless';
+import { buildBrowserEnvironment } from '@coveo/relay';
+import { COVEO_SHOPIFY_CONFIG_KEY } from '../constants';
+import { getShopifyCustomEnvironment, } from '../types';
+import { getClientId } from '../utilities/clientid';
+import { publishCustomShopifyEvent } from '../utilities/shopify';
+import { getShopifyCookie } from '../utilities/shopify';
+export { SHOPIFY_COOKIE_KEY, COVEO_SHOPIFY_CONFIG_KEY } from '../constants';
+export * from '@coveo/headless';
+export * from '../utilities';
+/**
+ * Builds the search engine for a Shopify store.
+ *
+ * This function initializes a search engine instance specific to a Shopify store by:
+ * - Creating or using an existing browser environment.
+ * - Retrieving the "_shopify_y" cookie to confirm it is running in a Shopify context.
+ * - Emitting a custom event with the app proxy response to enable tracking and analytics with shopify webpixels.
+ * - Storing a client identifier derived from the shop and cookie value in the browser environment's storage.
+ * - Building and returning the search engine with the provided options.
+ *
+ * @remarks
+ * The `generateUUID` and `storage` properties are omitted from the custom environment for Shopify
+ * to ensure that client IDs are generated consistently across web pixels and storefronts. This is
+ * critical for maintaining a unified tracking and personalization experience.
+ *
+ * @param searchEngineOptions - Options to configure the search engine.
+ * @param shopifyCookie - Optional value of the "_shopify_y" cookie. If not provided, it will attempt to retrieve it from the browser's cookies.
+ * @param environment - Optional browser environment; if not provided, a default one is created. Mainly useful when not running in a browser environment.
+ * @returns The constructed search engine instance.
+ * @throws Error if the required "_shopify_y" cookie is not found, ensuring the code runs within a Shopify store.
+ */
+export function buildShopifySearchEngine({ searchEngineOptions, environment, shopifyCookie, }) {
+    const customEnvironment = environment ?? getShopifyCustomEnvironment(buildBrowserEnvironment());
+    const cookie = shopifyCookie || getShopifyCookie();
+    if (!searchEngineOptions.configuration.analytics?.trackingId) {
+        throw new Error('The configuration for the search engine must include an analytics tracking ID.');
+    }
+    if (!cookie) {
+        throw new Error('Unable to find the _shopify_y cookie. Please ensure you are running this code in a Shopify store.');
+    }
+    const appProxyResponse = {
+        accessToken: searchEngineOptions.configuration.accessToken,
+        organizationId: searchEngineOptions.configuration.organizationId,
+        environment: searchEngineOptions.configuration.environment,
+        trackingId: searchEngineOptions.configuration.analytics.trackingId,
+    };
+    publishCustomShopifyEvent(COVEO_SHOPIFY_CONFIG_KEY, appProxyResponse);
+    const clientId = getClientId(cookie);
+    const engine = buildSearchEngine(searchEngineOptions);
+    engine.relay.updateConfig({
+        environment: {
+            ...customEnvironment,
+            generateUUID: () => clientId,
+        },
+    });
+    return engine;
+}

package/dist/headless.esm.js

@@ -15,23 +15,85 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+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 __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
 
-// src/headless.ts
+// src/headless/index.ts
+var index_exports = {};
+__export(index_exports, {
+  COVEO_SHOPIFY_CONFIG_KEY: () => COVEO_SHOPIFY_CONFIG_KEY,
+  SHOPIFY_COOKIE_KEY: () => SHOPIFY_COOKIE_KEY,
+  buildShopifyCommerceEngine: () => buildShopifyCommerceEngine,
+  fetchAppProxyConfig: () => fetchAppProxyConfig,
+  getClientId: () => getClientId,
+  getShopifyCookie: () => getShopifyCookie
+});
+
+// src/headless/commerce.ts
+var commerce_exports = {};
+__export(commerce_exports, {
+  COVEO_SHOPIFY_CONFIG_KEY: () => COVEO_SHOPIFY_CONFIG_KEY,
+  SHOPIFY_COOKIE_KEY: () => SHOPIFY_COOKIE_KEY,
+  buildShopifyCommerceEngine: () => buildShopifyCommerceEngine,
+  fetchAppProxyConfig: () => fetchAppProxyConfig,
+  getClientId: () => getClientId,
+  getShopifyCookie: () => getShopifyCookie
+});
 import {
   buildCommerceEngine
 } from "@coveo/headless/commerce";
 import { buildBrowserEnvironment } from "@coveo/relay";
 
-// src/utilities.ts
+// src/constants.ts
+var SHOPIFY_COOKIE_KEY = "_shopify_y";
+var COVEO_SHOPIFY_CONFIG_KEY = "coveo_shopify_config";
+
+// src/types.ts
+function getShopifyCustomEnvironment(environment) {
+  const { storage, generateUUID, ...rest } = environment;
+  return rest;
+}
+
+// src/utilities/clientid.ts
 import { v5 } from "uuid";
 var UUID_NAMESPACE = "c2db3701-991e-424d-b117-03e30d43b651";
 function getClientId(shopifyCookie) {
   return v5(shopifyCookie, UUID_NAMESPACE);
 }
 
-// src/headless.ts
-export * from "@coveo/headless/commerce";
-var SHOPIFY_COOKIE_KEY = "_shopify_y";
+// src/utilities/shopify.ts
+function getShopifyCookie(name = SHOPIFY_COOKIE_KEY) {
+  const match = document.cookie.match(
+    new RegExp("(?:^|;\\s*)" + name + "=([^;]*)")
+  );
+  return match ? decodeURIComponent(match[1]) : null;
+}
+function publishCustomShopifyEvent(key, customData) {
+  if (typeof window.Shopify?.analytics?.publish === "function") {
+    window.Shopify.analytics.publish(key, customData);
+  }
+}
+
+// src/headless/commerce.ts
+__reExport(commerce_exports, commerce_star);
+import * as commerce_star from "@coveo/headless/commerce";
+
+// src/utilities/app-proxy.ts
 async function fetchAppProxyConfig({
   appProxyUrl = "/apps/coveo",
   marketId
@@ -39,6 +101,8 @@ async function fetchAppProxyConfig({
   const response = await fetch(`${appProxyUrl}?marketId=${marketId}]`);
   return response.json();
 }
+
+// src/headless/commerce.ts
 function buildShopifyCommerceEngine({
   commerceEngineOptions,
   shopifyCookie,
@@ -46,11 +110,26 @@ function buildShopifyCommerceEngine({
 }) {
   const customEnvironment = environment ?? getShopifyCustomEnvironment(buildBrowserEnvironment());
   const cookie = shopifyCookie || getShopifyCookie();
+  if (!commerceEngineOptions.configuration.analytics.trackingId) {
+    throw new Error(
+      "The configuration for the commerce engine must include an analytics tracking ID."
+    );
+  }
   if (!cookie) {
     throw new Error(
       "Unable to find the _shopify_y cookie. Please ensure you are running this code in a Shopify store."
     );
   }
+  const appProxyResponse = {
+    accessToken: commerceEngineOptions.configuration.accessToken,
+    organizationId: commerceEngineOptions.configuration.organizationId,
+    environment: commerceEngineOptions.configuration.environment,
+    trackingId: commerceEngineOptions.configuration.analytics.trackingId
+  };
+  publishCustomShopifyEvent(
+    COVEO_SHOPIFY_CONFIG_KEY,
+    appProxyResponse
+  );
   const clientId = getClientId(cookie);
   const engine = buildCommerceEngine(commerceEngineOptions);
   engine.relay.updateConfig({
@@ -61,19 +140,12 @@ function buildShopifyCommerceEngine({
   });
   return engine;
 }
-function getShopifyCustomEnvironment(environment) {
-  const { storage, generateUUID, ...rest } = environment;
-  return rest;
-}
-function getShopifyCookie(name = SHOPIFY_COOKIE_KEY) {
-  const match = document.cookie.match(
-    new RegExp("(?:^|;\\s*)" + name + "=([^;]*)")
-  );
-  return match ? decodeURIComponent(match[1]) : null;
-}
+
+// src/headless/index.ts
+__reExport(index_exports, commerce_exports);
 export {
+  COVEO_SHOPIFY_CONFIG_KEY,
   SHOPIFY_COOKIE_KEY,
-  UUID_NAMESPACE,
   buildShopifyCommerceEngine,
   fetchAppProxyConfig,
   getClientId,

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+import { CommerceEngineOptions } from '@coveo/headless/commerce';
+import { CustomEnvironment } from '@coveo/relay';
+export interface AppProxyConfig {
+    appProxyUrl?: string;
+    marketId: string;
+}
+export interface AppProxyResponse {
+    accessToken: string;
+    organizationId: string;
+    environment: CommerceEngineOptions['configuration']['environment'];
+    trackingId: string;
+}
+export type ShopifyCustomEnvironment = Omit<CustomEnvironment, 'storage' | 'generateUUID'>;
+export declare function getShopifyCustomEnvironment(environment: CustomEnvironment): ShopifyCustomEnvironment;

package/dist/types.js

@@ -0,0 +1,4 @@
+export function getShopifyCustomEnvironment(environment) {
+    const { storage, generateUUID, ...rest } = environment;
+    return rest;
+}

package/dist/utilities/app-proxy.d.ts

@@ -0,0 +1,13 @@
+import { AppProxyConfig, AppProxyResponse } from '../types';
+/**
+ * Fetches configuration from the app proxy.
+ *
+ * Performs an HTTP GET request to retrieve the app proxy configuration using the provided marketId.
+ * The fetched response is parsed as JSON and returned.
+ *
+ * @param appProxyUrl - The URL template for the app proxy endpoint. Defaults to '/apps/coveo'.
+ * @param marketId - The unique market identifier used as a query parameter.
+ * @returns A promise that resolves to an object containing the access token, organization ID,
+ *          environment, and tracking ID.
+ */
+export declare function fetchAppProxyConfig({ appProxyUrl, marketId, }: AppProxyConfig): Promise<AppProxyResponse>;

package/dist/utilities/app-proxy.js

@@ -0,0 +1,15 @@
+/**
+ * Fetches configuration from the app proxy.
+ *
+ * Performs an HTTP GET request to retrieve the app proxy configuration using the provided marketId.
+ * The fetched response is parsed as JSON and returned.
+ *
+ * @param appProxyUrl - The URL template for the app proxy endpoint. Defaults to '/apps/coveo'.
+ * @param marketId - The unique market identifier used as a query parameter.
+ * @returns A promise that resolves to an object containing the access token, organization ID,
+ *          environment, and tracking ID.
+ */
+export async function fetchAppProxyConfig({ appProxyUrl = '/apps/coveo', marketId, }) {
+    const response = await fetch(`${appProxyUrl}?marketId=${marketId}]`);
+    return response.json();
+}

package/dist/utilities/index.d.ts

@@ -0,0 +1,3 @@
+export { getClientId } from './clientid';
+export { getShopifyCookie } from './shopify';
+export { fetchAppProxyConfig } from './app-proxy';

package/dist/utilities/index.js

@@ -0,0 +1,3 @@
+export { getClientId } from './clientid';
+export { getShopifyCookie } from './shopify';
+export { fetchAppProxyConfig } from './app-proxy';

package/dist/utilities/shopify.d.ts

@@ -0,0 +1,22 @@
+export type CustomEvent = Record<string, string>;
+/**
+ * Retrieves the value of a specified Shopify cookie by its name.
+ *
+ * @remarks
+ * This function is intended for use in browser environments only, as it relies on the `document.cookie` API.
+ * Attempting to use this function in non-browser environments will result in an error or undefined behavior.
+ *
+ * @param name - The name of the Shopify cookie to retrieve. Defaults to `'_shopify_y'`.
+ * @returns The value of the specified cookie, or `null` if the cookie is not found.
+ */
+export declare function getShopifyCookie(name?: string): string | null;
+declare global {
+    interface Window {
+        Shopify?: {
+            analytics: {
+                publish: (eventName: string, eventData: CustomEvent) => void;
+            };
+        };
+    }
+}
+export declare function publishCustomShopifyEvent(key: string, customData: CustomEvent): void;

package/dist/utilities/shopify.js

@@ -0,0 +1,20 @@
+import { SHOPIFY_COOKIE_KEY } from '../constants';
+/**
+ * Retrieves the value of a specified Shopify cookie by its name.
+ *
+ * @remarks
+ * This function is intended for use in browser environments only, as it relies on the `document.cookie` API.
+ * Attempting to use this function in non-browser environments will result in an error or undefined behavior.
+ *
+ * @param name - The name of the Shopify cookie to retrieve. Defaults to `'_shopify_y'`.
+ * @returns The value of the specified cookie, or `null` if the cookie is not found.
+ */
+export function getShopifyCookie(name = SHOPIFY_COOKIE_KEY) {
+    const match = document.cookie.match(new RegExp('(?:^|;\\s*)' + name + '=([^;]*)'));
+    return match ? decodeURIComponent(match[1]) : null;
+}
+export function publishCustomShopifyEvent(key, customData) {
+    if (typeof window.Shopify?.analytics?.publish === 'function') {
+        window.Shopify.analytics.publish(key, customData);
+    }
+}

package/dist/utilities.esm.js

@@ -16,13 +16,34 @@
  * limitations under the License.
  */
 
-// src/utilities.ts
+// src/utilities/clientid.ts
 import { v5 } from "uuid";
 var UUID_NAMESPACE = "c2db3701-991e-424d-b117-03e30d43b651";
 function getClientId(shopifyCookie) {
   return v5(shopifyCookie, UUID_NAMESPACE);
 }
+
+// src/constants.ts
+var SHOPIFY_COOKIE_KEY = "_shopify_y";
+
+// src/utilities/shopify.ts
+function getShopifyCookie(name = SHOPIFY_COOKIE_KEY) {
+  const match = document.cookie.match(
+    new RegExp("(?:^|;\\s*)" + name + "=([^;]*)")
+  );
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+// src/utilities/app-proxy.ts
+async function fetchAppProxyConfig({
+  appProxyUrl = "/apps/coveo",
+  marketId
+}) {
+  const response = await fetch(`${appProxyUrl}?marketId=${marketId}]`);
+  return response.json();
+}
 export {
-  UUID_NAMESPACE,
-  getClientId
+  fetchAppProxyConfig,
+  getClientId,
+  getShopifyCookie
 };

package/package.json

@@ -8,24 +8,34 @@
   "main": "./dist/headless.esm.js",
   "module": "./dist/headless.esm.js",
   "license": "Apache-2.0",
-  "version": "1.2.2-pre.e593f8f8f7",
+  "version": "1.3.0-pre.49914cd105",
   "files": [
     "dist/"
   ],
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/headless.d.ts",
+      "types": "./dist/headless/index.d.ts",
       "import": "./dist/headless.esm.js",
       "default": "./dist/headless.esm.js"
     },
     "./headless": {
-      "types": "./dist/headless.d.ts",
+      "types": "./dist/headless/index.d.ts",
       "import": "./dist/headless.esm.js",
       "default": "./dist/headless.esm.js"
     },
+    "./headless/commerce": {
+      "types": "./dist/headless/commerce.d.ts",
+      "import": "./dist/headless/commerce.esm.js",
+      "default": "./dist/headless/commerce.esm.js"
+    },
+    "./headless/search": {
+      "types": "./dist/headless/search.d.ts",
+      "import": "./dist/headless/search.esm.js",
+      "default": "./dist/headless/search.esm.js"
+    },
     "./utilities": {
-      "types": "./dist/utilities.d.ts",
+      "types": "./dist/utilities/index.d.ts",
       "import": "./dist/utilities.esm.js",
       "default": "./dist/utilities.esm.js"
     }
@@ -46,7 +56,7 @@
     "vitest": "3.1.2"
   },
   "dependencies": {
-    "@coveo/headless": "3.24.2-pre.e593f8f8f7",
+    "@coveo/headless": "3.25.0-pre.49914cd105",
     "@coveo/relay": "1.2.0",
     "uuid": "^11.0.0"
   },