@getcontextual/shopify-sdk 1.1.0

package/dist/vanilla/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/vanilla/react/index.d.ts

@@ -0,0 +1,49 @@
+import { trackPageView, trackProductView, trackCollectionView, trackAddToCart, trackCheckoutStarted, trackCheckoutCompleted, trackSearch, identify } from "../vanilla";
+import type { ShopifyProductVariant, ShopifyCartLine, ShopifyCheckout, ShopifyCollection, ShopifySearchResult } from "../types";
+import type { HeadlessShopifyConfig } from "../tracker";
+interface TrackerContextValue {
+    trackPageView: typeof trackPageView;
+    trackProductView: typeof trackProductView;
+    trackCollectionView: typeof trackCollectionView;
+    trackAddToCart: typeof trackAddToCart;
+    trackCheckoutStarted: typeof trackCheckoutStarted;
+    trackCheckoutCompleted: typeof trackCheckoutCompleted;
+    trackSearch: typeof trackSearch;
+    identify: typeof identify;
+}
+export declare function TrackerProvider({ config, children, }: {
+    config: HeadlessShopifyConfig;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useTracker(): TrackerContextValue;
+export declare function PageViewTracker({ pathname }: {
+    pathname: string;
+}): null;
+export declare function ProductTracking({ productVariant, }: {
+    productVariant: ShopifyProductVariant;
+}): null;
+export declare function CollectionTracking({ collection, }: {
+    collection: ShopifyCollection;
+}): null;
+export declare function AddToCartTracking({ cartLine }: {
+    cartLine: ShopifyCartLine;
+}): null;
+export declare function CheckoutStartedTracking({ checkout, }: {
+    checkout: ShopifyCheckout;
+}): null;
+export declare function CheckoutCompletedTracking({ checkout, }: {
+    checkout: ShopifyCheckout;
+}): null;
+export declare function SearchTracking({ search, searchResult, }: {
+    search: string;
+    searchResult: ShopifySearchResult;
+}): void;
+export declare function IdentifyTracking({ userProperties, }: {
+    userProperties: {
+        email?: string;
+        phone?: string;
+        firstName?: string;
+        lastName?: string;
+    };
+}): null;
+export {};

package/dist/vanilla/tracker.d.ts

@@ -0,0 +1,71 @@
+import type { ShopifyProductVariant, ShopifyCartLine, ShopifyCheckout, ShopifyCollection, ShopifySearchResult } from "./types";
+export interface HeadlessShopifyConfig {
+    merchantId: string;
+    version?: string;
+    autoFlush?: boolean;
+    flushInterval?: number;
+    gtmContainerId?: string;
+}
+export declare class HeadlessShopifyTracker {
+    private tracking;
+    private merchantId;
+    private gtmManager;
+    private gtmContainerId?;
+    private autoFlushInterval?;
+    constructor(config: HeadlessShopifyConfig);
+    /**
+     * Track page view
+     */
+    trackPageView(url?: string): Promise<void>;
+    /**
+     * Track product view
+     */
+    trackProductView(productVariant: ShopifyProductVariant): Promise<void>;
+    /**
+     * Track collection view
+     */
+    trackCollectionView(collection: ShopifyCollection): Promise<void>;
+    /**
+     * Track add to cart
+     */
+    trackAddToCart(cartLine: ShopifyCartLine): Promise<void>;
+    /**
+     * Track cart view
+     */
+    trackCartView(cart: {
+        lines: ShopifyCartLine[];
+    }): Promise<void>;
+    /**
+     * Track checkout started
+     */
+    trackCheckoutStarted(checkout: ShopifyCheckout): Promise<void>;
+    /**
+     * Track checkout completed
+     */
+    trackCheckoutCompleted(checkout: ShopifyCheckout): Promise<void>;
+    /**
+     * Track search
+     */
+    trackSearch(query: string, results: ShopifySearchResult): Promise<void>;
+    /**
+     * Update user properties (email, phone, etc.)
+     */
+    identify(userProperties: {
+        email?: string;
+        phone?: string;
+        firstName?: string;
+        lastName?: string;
+    }): Promise<void>;
+    private track;
+    /**
+     * Manually flush events
+     */
+    flush(): Promise<void>;
+    private startAutoFlush;
+    /**
+     * Clean up resources (call on component unmount in React)
+     *
+     * Clears auto-flush interval to prevent memory leaks
+     */
+    destroy(): void;
+}

package/dist/vanilla/tracking-proxy.d.ts

@@ -0,0 +1,5 @@
+import { BrowserEvent, Tracking } from "@contextual/browser";
+export interface TrackingWithSource extends Omit<Tracking, "makeEvent"> {
+    makeEvent: (source: "sap" | "scp" | "ses", event: Parameters<Tracking["makeEvent"]>[0], options?: Parameters<Tracking["makeEvent"]>[1]) => Promise<BrowserEvent>;
+}
+export declare function createTrackingWithSourceProxy(tracking: Tracking): TrackingWithSource;

package/dist/vanilla/types.d.ts

@@ -0,0 +1,12 @@
+import type { PixelEventsProductViewedData, PixelEventsProductAddedToCartData, PixelEventsCheckoutCompletedData, PixelEventsCollectionViewedData, PixelEventsSearchSubmittedData } from "@shopify/web-pixels-extension";
+/**
+ * Shopify types for headless integration
+ *
+ * Uses Shopify's web-pixels-extension types directly (same as web-pixel.ts)
+ * for consistency and type safety.
+ */
+export type ShopifyProductVariant = PixelEventsProductViewedData["productVariant"];
+export type ShopifyCartLine = PixelEventsProductAddedToCartData["cartLine"];
+export type ShopifyCheckout = PixelEventsCheckoutCompletedData["checkout"];
+export type ShopifyCollection = PixelEventsCollectionViewedData["collection"];
+export type ShopifySearchResult = PixelEventsSearchSubmittedData["searchResult"];

package/dist/vanilla/vanilla/index.d.ts

@@ -0,0 +1,40 @@
+import { HeadlessShopifyTracker } from "../tracker";
+import type { HeadlessShopifyConfig } from "../tracker";
+import type { ShopifyProductVariant, ShopifyCartLine, ShopifyCheckout, ShopifyCollection, ShopifySearchResult } from "../types";
+interface VanillaShopifyConfig extends HeadlessShopifyConfig {
+    autoTrackPageView: boolean;
+}
+/**
+ * Initialize tracker (call once on page load)
+ *
+ * SSR-safe: Returns immediately on server-side
+ * Use in useEffect or with browser check for SSR environments
+ */
+export declare function init(config: VanillaShopifyConfig): HeadlessShopifyTracker | null;
+/**
+ * Get tracker instance
+ *
+ * SSR-safe: Returns null on server-side
+ */
+export declare function getTracker(): HeadlessShopifyTracker | null;
+/**
+ * Convenience functions
+ * All functions are SSR-safe: No-op on server-side
+ */
+export declare const trackProductView: (product: ShopifyProductVariant) => void;
+export declare const trackCollectionView: (collection: ShopifyCollection) => void;
+export declare const trackPageView: () => void;
+export declare const trackAddToCart: (cartLine: ShopifyCartLine) => void;
+export declare const trackCartView: (cart: {
+    lines: ShopifyCartLine[];
+}) => void;
+export declare const trackCheckoutStarted: (checkout: ShopifyCheckout) => void;
+export declare const trackCheckoutCompleted: (checkout: ShopifyCheckout) => void;
+export declare const trackSearch: (query: string, results: ShopifySearchResult) => void;
+export declare const identify: (userProperties: {
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+}) => void;
+export {};

package/dist/vanilla/vanilla/index.e2e.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * End-to-end tests for vanilla/index.ts
+ *
+ * Tests:
+ * - GTM initialization and loading
+ * - LiveIntent initialization and loading
+ * - Event payloads sent to backend match expected structure
+ */
+export {};

package/dist/vanilla/vanilla/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@getcontextual/shopify-sdk",
+  "version": "1.1.0",
+  "description": "Easy integration for tracking on headless Shopify sites",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    },
+    "./vanilla": {
+      "types": "./dist/vanilla/index.d.ts",
+      "import": "./dist/vanilla/index.js",
+      "default": "./dist/vanilla/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@shopify/web-pixels-extension": "^2.18.0",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^18.0.0",
+    "eslint": "^9.36.0",
+    "nock": "^13.5.5",
+    "prettier": "^3.6.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rollup": "^4.52.2",
+    "rollup-plugin-filesize": "^10.0.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4",
+    "@contextual/typescript-config": "0.0.0",
+    "@contextual/prettier-config": "1.0.0",
+    "@contextual/eslint-config": "1.0.0"
+  },
+  "scripts": {
+    "prettier": "prettier . --write",
+    "prettier:ci": "prettier . --check",
+    "test:unit": "vitest --run",
+    "test:e2e": "vitest --run ./src/**/*.e2e.test.ts",
+    "test:integration": "",
+    "lint": "eslint .",
+    "lint:ci": "eslint .",
+    "tsc": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prebuild": "pnpm run --filter=@contextual/browser build && pnpm clean",
+    "build": "rollup -c"
+  }
+}