@coveo/shopify 0.0.1

package/README.md

@@ -0,0 +1,126 @@
+# @coveo/shopify
+
+The `@coveo/shopify` package provides utilities to integrate Shopify with Coveo's commerce engine.
+
+It includes functions to fetch app proxy configurations and build a commerce engine tailored for Shopify.
+
+## 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.
+
+## Installation
+
+Install the package using npm or yarn:
+
+```bash
+npm install @coveo/shopify
+# or
+yarn add @coveo/shopify
+```
+
+## Features
+
+### `fetchAppProxyConfig`
+
+Fetches the app proxy configuration for a given Shopify market.
+
+#### Parameters
+
+- `marketId` (required): The market identifier.
+- `appProxyUrl` (optional): The URL of the app proxy. Defaults to `'/apps/coveo'`. Useful if implementing your own custom proxy.
+
+#### Returns
+
+A promise that resolves to an object containing:
+
+- `accessToken`: The access token for the app proxy.
+- `organizationId`: The organization ID.
+- `environment`: The environment configuration.
+- `trackingId`: The tracking ID.
+
+#### Example
+
+```typescript
+import {fetchAppProxyConfig} from '@coveo/shopify/headless';
+
+const config = await fetchAppProxyConfig({
+  marketId: 'market_123432',
+});
+console.log(config);
+```
+
+### `buildShopifyCommerceEngine`
+
+Builds a commerce engine instance configured for Shopify.
+
+#### Parameters
+
+- `commerceEngineOptions` (required): Options for the commerce engine.
+- `shopifyCookie` (optional): The value of the Shopify `_shopify_y` cookie. If not provided, it will attempt to retrieve it from the browser's cookies.
+- `environment` (optional): A custom environment configuration (useful for testing & SSR).
+
+#### Returns
+
+A configured commerce engine instance.
+
+#### Example
+
+```typescript
+<script type="module">
+import {buildShopifyCommerceEngine, fetchAppProxyConfig} from 'https://static.cloud.coveo.com/shopify/v1/headless.esm.js';
+
+const config = await fetchAppProxyConfig({marketId: 'market_123432'});
+const engine = buildShopifyCommerceEngine({
+  commerceEngineOptions: {
+    configuration : {
+      accessToken: config.accessToken,
+      organizationId: config.organizationId,
+      environment: config.environment,
+      analytics: {
+        enabled: true,
+        trackingId: config.trackingId,
+      },
+      context: {
+        country: {{ localization.country.iso_code | json }},
+        currency: {{  localization.country.currency.iso_code | json }},
+        view: {
+          url: {{ canonical_url | json }},
+        },
+        language: {{ request.locale.iso_code | json }},
+        cart: {{ cart.items | json }}.map(function (item) {
+          return {
+            productId: item.product_id,
+            name: item.title,
+            price: item.final_price,
+            quantity: item.quantity,
+          };
+        }),
+      }
+  },
+});
+console.log(engine);
+</script>
+```
+
+### `getShopifyCookie`
+
+Retrieves the value of a specified Shopify cookie by its name.
+
+#### Returns
+
+The value of the specified cookie, or `null` if the cookie is not found.
+
+#### Notes
+
+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.
+
+#### Example
+
+```typescript
+import {getShopifyCookie} from '@coveo/shopify';
+
+const shopifyCookie = getShopifyCookie();
+console.log(shopifyCookie);
+```
+
+---

package/dist/headless.esm.js

@@ -0,0 +1,73 @@
+/**
+ * @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.ts
+import {
+  buildCommerceEngine
+} from "@coveo/headless/commerce";
+import {
+  buildBrowserEnvironment,
+  clientIdKey
+} from "@coveo/relay";
+
+// src/utilities.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";
+async function fetchAppProxyConfig({
+  appProxyUrl = "/apps/coveo",
+  marketId
+}) {
+  const response = await fetch(`${appProxyUrl}?marketId=${marketId}]`);
+  return response.json();
+}
+function buildShopifyCommerceEngine({
+  commerceEngineOptions,
+  shopifyCookie,
+  environment
+}) {
+  const browserEnvironment = environment || buildBrowserEnvironment();
+  const cookie = shopifyCookie || getShopifyCookie();
+  if (!cookie) {
+    throw new Error(
+      "Unable to find the _shopify_y cookie. Please ensure you are running this code in a Shopify store."
+    );
+  }
+  browserEnvironment.storage.setItem(clientIdKey, getClientId(cookie));
+  return buildCommerceEngine(commerceEngineOptions);
+}
+function getShopifyCookie(name = SHOPIFY_COOKIE_KEY) {
+  const match = document.cookie.match(
+    new RegExp("(?:^|;\\s*)" + name + "=([^;]*)")
+  );
+  return match ? decodeURIComponent(match[1]) : null;
+}
+export {
+  SHOPIFY_COOKIE_KEY,
+  UUID_NAMESPACE,
+  buildShopifyCommerceEngine,
+  fetchAppProxyConfig,
+  getClientId,
+  getShopifyCookie
+};

package/dist/utilities.esm.js

@@ -0,0 +1,28 @@
+/**
+ * @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/utilities.ts
+import { v5 } from "uuid";
+var UUID_NAMESPACE = "c2db3701-991e-424d-b117-03e30d43b651";
+function getClientId(shopifyCookie) {
+  return v5(shopifyCookie, UUID_NAMESPACE);
+}
+export {
+  UUID_NAMESPACE,
+  getClientId
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@coveo/shopify",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coveo/ui-kit.git",
+    "directory": "packages/shopify"
+  },
+  "main": "./dist/headless.esm.js",
+  "module": "./dist/headless.esm.js",
+  "types": "./dist/definitions/index.d.ts",
+  "license": "Apache-2.0",
+  "version": "0.0.1",
+  "files": [
+    "dist/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/headless.esm.js",
+      "default": "./dist/headless.esm.js"
+    },
+    "./headless": {
+      "import": "./dist/headless.esm.js",
+      "default": "./dist/headless.esm.js"
+    },
+    "./utilities": {
+      "import": "./dist/utilities.esm.js",
+      "default": "./dist/utilities.esm.js"
+    }
+  },
+  "scripts": {
+    "dev": "npm run build:bundles -- dev",
+    "build": "nx build",
+    "build:bundles": "node esbuild.mjs",
+    "test": "vitest run",
+    "clean": "rimraf -rf dist/* && rimraf -rf cdn/",
+    "publish:npm": "npm run-script -w=@coveo/ci npm-publish",
+    "publish:bump": "npm run-script -w=@coveo/ci bump",
+    "promote:npm:latest": "npm run-script -w=@coveo/ci promote-npm-prod"
+  },
+  "devDependencies": {
+    "@coveo/ci": "1.0.0",
+    "vitest": "3.1.2"
+  },
+  "dependencies": {
+    "@coveo/headless": "3.22.4",
+    "@coveo/relay": "1.1.3",
+    "uuid": "^11.0.0"
+  },
+  "engines": {
+    "node": "^20.9.0 || ^22.11.0"
+  }
+}