@wapitee/typhoonx-hydrogen 0.1.0 → 0.3.0

package/README.md

@@ -1,20 +1,20 @@
-# @wapitee/typhoonx-hydrogen
+# TyphoonX for Shopify Hydrogen
 
-Hydrogen `useAnalytics` subscriber that sends TyphoonX storefront events.
+[![npm package](https://img.shields.io/npm/v/@wapitee/typhoonx-hydrogen?style=flat-square)](https://www.npmjs.com/package/@wapitee/typhoonx-hydrogen)
+[![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-This is not a Shopify Web Pixel. Place it in a Hydrogen storefront, inside `Analytics.Provider`.
+Hydrogen `useAnalytics` subscriber that sends TyphoonX storefront events.
 
 ## Install
 
 ```bash
-pnpm add @wapitee/typhoonx-hydrogen
+npm install --save @wapitee/typhoonx-hydrogen
 ```
 
-Peer dependencies: `react` ^18.3.1 and `@shopify/hydrogen` >=2025.5.1. Node.js 20 or later.
-
 ## Usage
 
 ```tsx
+// app/root.tsx
 import {Analytics} from '@shopify/hydrogen';
 import TyphoonX from '@wapitee/typhoonx-hydrogen';
 
@@ -28,31 +28,25 @@ export function App() {
 }
 ```
 
-The component renders `null`.
-
-### Props
+If your Shopify Hydrogen project sets a Content-Security-Policy, add `https://spell.typhoonx.io` to `connect-src` so event collection is not blocked.
 
-| Prop           | Type     | Required | Description                                                                                                 |
-| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------- |
-| `merchantId`   | `string` | yes      | TyphoonX account key (`TPX-…`)                                                                              |
-| `shopId`       | `string` | yes      | Shopify shop numeric id                                                                                     |
-| `cookieDomain` | `string` | no       | Cookie `Domain` for a first-party client id. Omit for a host-only cookie (recommended on `*.myshopify.com`) |
-
-```ts
-import type {TyphoonXProps} from '@wapitee/typhoonx-hydrogen';
+```javascript
+const {nonce, header, NonceProvider} = createContentSecurityPolicy({
+  shop: {
+    checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
+    storeDomain: context.env.PUBLIC_STORE_DOMAIN,
+  },
+  connectSrc: ['https://spell.typhoonx.io'], // add this line
+});
 ```
 
-### Events
-
-| Hydrogen                | TyphoonX      |
-| ----------------------- | ------------- |
-| `page_viewed`           | `page_view`   |
-| `product_viewed`        | `view_item`   |
-| `product_added_to_cart` | `add_to_cart` |
-
-Beacons go to `https://spell.typhoonx.io/api/v1/receive`. Checkout and purchase are out of scope.
+### Props
 
-Sends are gated by Hydrogen `canTrack()` (Customer Privacy). The anonymous visitor id lives in `__typhoon_client_id` (one year, `SameSite=Lax`, `Secure` on HTTPS).
+| Prop           | Type     | Required | Description                                                              |
+| -------------- | -------- | -------- | ------------------------------------------------------------------------ |
+| `merchantId`   | `string` | yes      | TyphoonX merchant ID (`TPX-…`)                                           |
+| `shopId`       | `string` | yes      | Shopify store ID                                                         |
+| `cookieDomain` | `string` | no       | Cookie `Domain` for a first-party client id. Omit for a host-only cookie |
 
 ## License
 

package/dist/TyphoonX.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { parseGid, useAnalytics } from '@shopify/hydrogen';
+import { flattenConnection, parseGid, useAnalytics } from '@shopify/hydrogen';
 import { useEffect, useRef, useState } from 'react';
 import { getOrCreateClientId } from './client-id.js';
 const COLLECT_ENDPOINT = 'https://spell.typhoonx.io/api/v1/receive';
@@ -44,30 +44,29 @@ function TyphoonXClient({ cookieDomain, merchantId, shopId }) {
             user_agent: window.navigator.userAgent,
             ...(currency === undefined ? {} : { currency }),
         });
-        subscribe('page_viewed', (data) => {
-            send({
-                ...shared(data.url),
-                event: 'page_view',
-            });
-        });
-        subscribe('product_viewed', (data) => {
-            const product = data.products[0];
-            if (product === undefined) {
+        subscribe('cart_viewed', (data) => {
+            const { cart } = data;
+            if (!cart?.lines) {
                 return;
             }
+            const cartLines = flattenConnection(cart.lines);
             send({
                 ...shared(data.url, data.shop?.currency),
-                event: 'view_item',
-                items: [
-                    {
-                        item_brand: product.vendor,
-                        item_id: parseGid(product.id).id,
-                        item_name: product.title,
-                        price: product.price,
-                        quantity: 1,
-                    },
-                ],
-                value: product.price,
+                event: 'view_cart',
+                items: cartLines.map((line) => ({
+                    item_brand: line.merchandise.product.vendor,
+                    item_id: parseGid(line.merchandise.product.id).id,
+                    item_name: line.merchandise.product.title,
+                    price: line.merchandise.price.amount,
+                    quantity: line.quantity,
+                })),
+                value: cart.cost.totalAmount.amount,
+            });
+        });
+        subscribe('page_viewed', (data) => {
+            send({
+                ...shared(data.url),
+                event: 'page_view',
             });
         });
         subscribe('product_added_to_cart', (data) => {
@@ -90,6 +89,48 @@ function TyphoonXClient({ cookieDomain, merchantId, shopId }) {
                 value: currentLine.cost.totalAmount.amount,
             });
         });
+        subscribe('product_removed_from_cart', (data) => {
+            const { currentLine, prevLine } = data;
+            const quantity = (prevLine?.quantity ?? 0) - (currentLine?.quantity ?? 0);
+            if (prevLine === undefined || quantity <= 0) {
+                return;
+            }
+            send({
+                ...shared(window.location.href, data.shop?.currency),
+                event: 'remove_from_cart',
+                items: [
+                    {
+                        item_brand: prevLine.merchandise.product.vendor,
+                        item_id: parseGid(prevLine.merchandise.product.id).id,
+                        item_name: prevLine.merchandise.product.title,
+                        price: prevLine.merchandise.price.amount,
+                        quantity,
+                    },
+                ],
+                value: String(Number(prevLine.cost.totalAmount.amount)
+                    - Number(currentLine?.cost.totalAmount.amount ?? 0)),
+            });
+        });
+        subscribe('product_viewed', (data) => {
+            const product = data.products[0];
+            if (product === undefined) {
+                return;
+            }
+            send({
+                ...shared(data.url, data.shop?.currency),
+                event: 'view_item',
+                items: [
+                    {
+                        item_brand: product.vendor,
+                        item_id: parseGid(product.id).id,
+                        item_name: product.title,
+                        price: product.price,
+                        quantity: 1,
+                    },
+                ],
+                value: product.price,
+            });
+        });
         ready();
         return () => {
             cancelled = true;

package/dist/client-id.d.ts

@@ -1,2 +1,18 @@
+/**
+ * Returns the TyphoonX client id from the `__typhoon_client_id` cookie, or
+ * creates a new UUID and writes it when the cookie is missing.
+ *
+ * The cookie is scoped to `Path=/`, uses `SameSite=Lax`, and expires after
+ * one year. When `cookieDomain` is set, that value is used as the cookie
+ * `Domain` so the id can be shared across subdomains. The `Secure` flag is
+ * added automatically on HTTPS pages.
+ *
+ * @remarks
+ * This helper must run in the browser. It reads and writes `document.cookie`.
+ *
+ * @param cookieDomain - Optional cookie `Domain` attribute, typically the
+ * storefront apex domain.
+ * @returns The existing or newly created client id.
+ */
 export declare function getOrCreateClientId(cookieDomain?: string): string;
 //# sourceMappingURL=client-id.d.ts.map

package/dist/client-id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-id.d.ts","sourceRoot":"","sources":["../src/client-id.ts"],"names":[],"mappings":"AAGA,wBAAgB,mBAAmB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CA8BjE"}
+{"version":3,"file":"client-id.d.ts","sourceRoot":"","sources":["../src/client-id.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CA8BjE"}

package/dist/client-id.js

@@ -1,5 +1,23 @@
+/** Cookie name that stores the anonymous TyphoonX client identifier. */
 const COOKIE = '__typhoon_client_id';
+/** Cookie lifetime in seconds (365 days). */
 const MAX_AGE = 31_536_000;
+/**
+ * Returns the TyphoonX client id from the `__typhoon_client_id` cookie, or
+ * creates a new UUID and writes it when the cookie is missing.
+ *
+ * The cookie is scoped to `Path=/`, uses `SameSite=Lax`, and expires after
+ * one year. When `cookieDomain` is set, that value is used as the cookie
+ * `Domain` so the id can be shared across subdomains. The `Secure` flag is
+ * added automatically on HTTPS pages.
+ *
+ * @remarks
+ * This helper must run in the browser. It reads and writes `document.cookie`.
+ *
+ * @param cookieDomain - Optional cookie `Domain` attribute, typically the
+ * storefront apex domain.
+ * @returns The existing or newly created client id.
+ */
 export function getOrCreateClientId(cookieDomain) {
     const prefix = `${COOKIE}=`;
     const existing = document.cookie

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wapitee/typhoonx-hydrogen",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TyphoonX Hydrogen Analytics subscriber",
   "homepage": "https://github.com/Wapitee-Interactive-Marketing-Limited/typhoonx-js/tree/main/packages/typhoonx-hydrogen",
   "bugs": {