@replohq/sdk 1.7.3 → 1.8.0

package/analytics/hooks/use-collection-viewed-analytics.d.ts

@@ -0,0 +1,19 @@
+import type { AnalyticsCollection, AnalyticsCollectionProduct } from "../utils/collection-analytics";
+interface UseCollectionViewedAnalyticsProps {
+    collection: AnalyticsCollection | null | undefined;
+    /**
+     * The collection's products as the collection-products loader returns them.
+     * Pass `undefined` while they are still loading so the event carries the
+     * list when it fires.
+     */
+    products: AnalyticsCollectionProduct[] | null | undefined;
+}
+/**
+ * Fires a `viewCollection` analytics event carrying the collection's products
+ * once the collection and its product list are both available. Re-renders
+ * and product-list updates for the same collection do not fire again; a
+ * different collection does, and returning to an earlier one counts as a new
+ * view, matching `useProductViewedAnalytics`.
+ */
+export declare function useCollectionViewedAnalytics({ collection, products, }: UseCollectionViewedAnalyticsProps): void;
+export {};

package/analytics/hooks/use-collection-viewed-analytics.js

@@ -0,0 +1,26 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { useAnalytics } from "../analytics-provider";
+import { buildCollectionViewedAnalyticsData } from "../utils/collection-analytics";
+function useCollectionViewedAnalytics({
+  collection,
+  products
+}) {
+  const analytics = useAnalytics();
+  const lastTrackedRef = useRef(null);
+  useEffect(() => {
+    if (!analytics || !collection || !products) {
+      return;
+    }
+    if (lastTrackedRef.current === collection.id) {
+      return;
+    }
+    lastTrackedRef.current = collection.id;
+    void analytics.viewCollection({
+      data: buildCollectionViewedAnalyticsData({ collection, products })
+    });
+  }, [analytics, collection, products]);
+}
+export {
+  useCollectionViewedAnalytics
+};

package/analytics/sinks/elevar-sink.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { legacyResourceId } from "../utils/analytics-products";
 const GUEST_USER_PROPERTIES = { visitor_type: "guest" };
 const FALLBACK_CURRENCY_CODE = "USD";
 const nonEmptyStringSchema = z.union([z.string().min(1), z.number().finite().transform(String)]).optional().catch(void 0);
@@ -45,9 +46,6 @@ const collectionPayloadSchema = z.object({
 function formatMoney(amount) {
   return amount.toFixed(2);
 }
-function legacyResourceId(id) {
-  return id.replace(/^gid:\/\/shopify\/\w+\//, "");
-}
 function parseCheckoutLine(line) {
   const parsed = checkoutLineSchema.safeParse(line);
   if (!parsed.success || !parsed.data.merchandise) {

package/analytics/sinks/ga4-sink.js

@@ -1,3 +1,8 @@
+import {
+  legacyResourceId,
+  splitCollectionProducts,
+  withoutUndefined
+} from "../utils/analytics-products";
 import { createEventQueue } from "../utils/analytics-utils";
 class GA4Sink {
   send;
@@ -48,7 +53,24 @@ class GA4Sink {
     this.send("begin_checkout", data);
   }
   async viewCollection({ data }) {
-    this.send("view_item_list", data);
+    const { products, rest } = splitCollectionProducts(data);
+    this.send("view_item_list", {
+      item_list_id: data.collectionId,
+      item_list_name: data.collectionTitle,
+      currency: data.currency,
+      ...products.length > 0 ? {
+        items: products.map((product, index) => {
+          return withoutUndefined({
+            item_id: legacyResourceId(product.productId),
+            item_name: product.productTitle,
+            item_variant: product.variantTitle,
+            price: product.price,
+            index
+          });
+        })
+      } : {},
+      ...rest
+    });
   }
 }
 export {

package/analytics/sinks/pinterest-sink.js

@@ -1,3 +1,8 @@
+import {
+  legacyResourceId,
+  splitCollectionProducts,
+  withoutUndefined
+} from "../utils/analytics-products";
 import { createEventQueue } from "../utils/analytics-utils";
 class PinterestSink {
   track;
@@ -61,9 +66,22 @@ class PinterestSink {
     });
   }
   async viewCollection({ data }) {
+    const { products, rest } = splitCollectionProducts(data);
     this.track("viewcategory", {
       product_category: data.category,
-      ...data
+      currency: data.currency,
+      ...products.length > 0 ? {
+        line_items: products.map((product) => {
+          return withoutUndefined({
+            product_id: legacyResourceId(product.productId),
+            product_name: product.productTitle,
+            product_price: product.price,
+            product_variant_id: product.variantId === void 0 ? void 0 : legacyResourceId(product.variantId),
+            product_variant: product.variantTitle
+          });
+        })
+      } : {},
+      ...rest
     });
   }
 }

package/analytics/sinks/reddit-sink.js

@@ -1,3 +1,8 @@
+import {
+  legacyResourceId,
+  splitCollectionProducts,
+  withoutUndefined
+} from "../utils/analytics-products";
 import { createEventQueue } from "../utils/analytics-utils";
 class RedditSink {
   track;
@@ -64,10 +69,20 @@ class RedditSink {
     });
   }
   async viewCollection({ data }) {
+    const { products, rest } = splitCollectionProducts(data);
     this.track("ViewContent", {
       content_category: data.category,
       content_type: "category",
-      ...data
+      currency: data.currency,
+      ...products.length > 0 ? {
+        products: products.map((product) => {
+          return withoutUndefined({
+            id: legacyResourceId(product.productId),
+            name: product.productTitle
+          });
+        })
+      } : {},
+      ...rest
     });
   }
 }

package/analytics/sinks/tiktok-sink.js

@@ -1,3 +1,8 @@
+import {
+  legacyResourceId,
+  splitCollectionProducts,
+  withoutUndefined
+} from "../utils/analytics-products";
 import { createEventQueue } from "../utils/analytics-utils";
 class TikTokSink {
   track;
@@ -63,10 +68,22 @@ class TikTokSink {
     });
   }
   async viewCollection({ data }) {
+    const { products, rest } = splitCollectionProducts(data);
     this.track("ViewContent", {
       content_type: "product_group",
       content_category: data.category,
-      ...data
+      currency: data.currency,
+      ...products.length > 0 ? {
+        contents: products.map((product) => {
+          return withoutUndefined({
+            content_id: legacyResourceId(product.productId),
+            content_type: "product_group",
+            content_name: product.productTitle,
+            price: product.price
+          });
+        })
+      } : {},
+      ...rest
     });
   }
 }

package/analytics/utils/analytics-products.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+/**
+ * The flat per-product line the cart provider and the viewed hooks emit.
+ * Prices are decimal major units.
+ */
+declare const analyticsProductLineSchema: z.ZodObject<{
+    productId: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>>>;
+    productTitle: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>>>;
+    variantId: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>>>;
+    variantTitle: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>>>;
+    variantSku: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>>>;
+    price: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>>>;
+    currency: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodNumber, z.ZodTransform<string, number>>]>>>;
+    quantity: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>>>;
+}, z.core.$strip>;
+export type AnalyticsProductLine = z.infer<typeof analyticsProductLineSchema> & {
+    productId: string;
+};
+export declare function parseAnalyticsProductLines(value: unknown): AnalyticsProductLine[];
+/**
+ * Separates a collection-view payload's `products` list from the scalar
+ * fields, so a sink can map the list into its own item shape and forward the
+ * rest untouched.
+ */
+export declare function splitCollectionProducts(data: Record<string, unknown>): {
+    products: AnalyticsProductLine[];
+    rest: Record<string, unknown>;
+};
+/**
+ * Shopify catalogs synced into ad platforms key on legacy numeric ids, while
+ * the Storefront API hands sites GIDs (`gid://shopify/Product/123`). Pixel
+ * catalog matching is an exact string match, so ids are sent bare.
+ */
+export declare function legacyResourceId(id: string): string;
+export declare function withoutUndefined<RecordType extends Record<string, unknown>>(record: RecordType): Partial<RecordType>;
+export {};

package/analytics/utils/analytics-products.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+const nonEmptyStringSchema = z.union([z.string().min(1), z.number().finite().transform(String)]).optional().catch(void 0);
+const finiteNumberSchema = z.union([
+  z.number().finite(),
+  z.string().trim().min(1).transform(Number).pipe(z.number().finite())
+]).optional().catch(void 0);
+const analyticsProductLineSchema = z.object({
+  productId: nonEmptyStringSchema,
+  productTitle: nonEmptyStringSchema,
+  variantId: nonEmptyStringSchema,
+  variantTitle: nonEmptyStringSchema,
+  variantSku: nonEmptyStringSchema,
+  price: finiteNumberSchema,
+  currency: nonEmptyStringSchema,
+  quantity: finiteNumberSchema
+});
+function parseAnalyticsProductLines(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((item) => {
+    const parsed = analyticsProductLineSchema.safeParse(item);
+    if (!parsed.success || !parsed.data.productId) {
+      return [];
+    }
+    return [{ ...parsed.data, productId: parsed.data.productId }];
+  });
+}
+function splitCollectionProducts(data) {
+  const { products, ...rest } = data;
+  const lines = parseAnalyticsProductLines(products);
+  if (Array.isArray(products) && products.length > 0 && lines.length === 0) {
+    console.warn(
+      "[analytics] collection view products did not match the per-line shape and were dropped",
+      { products }
+    );
+  }
+  return { products: lines, rest };
+}
+function legacyResourceId(id) {
+  return id.replace(/^gid:\/\/shopify\/\w+\//, "");
+}
+function withoutUndefined(record) {
+  const compacted = {};
+  for (const key in record) {
+    if (record[key] !== void 0) {
+      compacted[key] = record[key];
+    }
+  }
+  return compacted;
+}
+export {
+  legacyResourceId,
+  parseAnalyticsProductLines,
+  splitCollectionProducts,
+  withoutUndefined
+};

package/analytics/utils/collection-analytics.d.ts

@@ -0,0 +1,44 @@
+export interface AnalyticsMoney {
+    amount: number | string;
+    currencyCode: string;
+}
+export interface AnalyticsCollection {
+    id: string;
+    title?: string | null;
+    handle?: string | null;
+}
+export interface AnalyticsCollectionProductVariant {
+    id: string;
+    title?: string | null;
+    sku?: string | null;
+    price?: AnalyticsMoney | null;
+}
+export interface AnalyticsCollectionProduct {
+    id: string;
+    title?: string | null;
+    variants?: AnalyticsCollectionProductVariant[] | null;
+    minPrice?: AnalyticsMoney | null;
+}
+/**
+ * The `viewCollection` payload: collection identity plus one line per product
+ * in the same shape the cart events use, priced from the first variant (or
+ * the product's minimum price) with no quantity.
+ */
+export declare function buildCollectionViewedAnalyticsData({ collection, products, }: {
+    collection: AnalyticsCollection;
+    products: AnalyticsCollectionProduct[];
+}): {
+    collectionTitle?: string | undefined;
+    collectionHandle?: string | undefined;
+    currency?: string | undefined;
+    collectionId: string;
+    products: {
+        productTitle?: string | undefined;
+        variantId?: string | undefined;
+        variantTitle?: string | undefined;
+        variantSku?: string | undefined;
+        price?: number | undefined;
+        currency?: string | undefined;
+        productId: string;
+    }[];
+};

package/analytics/utils/collection-analytics.js

@@ -0,0 +1,41 @@
+import { withoutUndefined } from "./analytics-products";
+function parseAmount(money) {
+  if (!money) {
+    return void 0;
+  }
+  const amount = Number(money.amount);
+  return Number.isFinite(amount) ? amount : void 0;
+}
+function buildCollectionProductLine(product) {
+  const variant = product.variants?.[0];
+  const money = variant?.price ?? product.minPrice ?? void 0;
+  return {
+    productId: product.id,
+    ...withoutUndefined({
+      productTitle: product.title ?? void 0,
+      variantId: variant?.id,
+      variantTitle: variant?.title ?? void 0,
+      variantSku: variant?.sku ?? void 0,
+      price: parseAmount(money),
+      currency: money?.currencyCode
+    })
+  };
+}
+function buildCollectionViewedAnalyticsData({
+  collection,
+  products
+}) {
+  const lines = products.map(buildCollectionProductLine);
+  return {
+    collectionId: collection.id,
+    products: lines,
+    ...withoutUndefined({
+      collectionTitle: collection.title ?? void 0,
+      collectionHandle: collection.handle ?? void 0,
+      currency: lines.find((line) => line.currency)?.currency
+    })
+  };
+}
+export {
+  buildCollectionViewedAnalyticsData
+};

package/lib/buildMetadata.js

@@ -1,7 +1,7 @@
 export const BUILD_METADATA = {
   "packageName": "@replohq/sdk",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "branch": "HEAD",
-  "commit": "d7ee0ec28234216b633c81e1a6d8683591c946f8",
-  "builtAt": "2026-09-15T17:30:06.396Z"
+  "commit": "b651d52d898d9c6fc4fdca33165feed30505e056",
+  "builtAt": "2026-09-15T18:43:12.533Z"
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@replohq/sdk",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "reploBuild": {
     "packageName": "@replohq/sdk",
-    "version": "1.7.3",
+    "version": "1.8.0",
     "branch": "HEAD",
-    "commit": "d7ee0ec28234216b633c81e1a6d8683591c946f8",
-    "builtAt": "2026-09-15T17:30:06.396Z"
+    "commit": "b651d52d898d9c6fc4fdca33165feed30505e056",
+    "builtAt": "2026-09-15T18:43:12.533Z"
   },
   "description": "Replo SDK — cart, analytics, and data loaders for agent-built Next.js sites.",
   "license": "SEE LICENSE IN LICENSE",
@@ -89,6 +89,10 @@
       "types": "./analytics/hooks/use-product-viewed-analytics.d.ts",
       "default": "./analytics/hooks/use-product-viewed-analytics.js"
     },
+    "./analytics/hooks/use-collection-viewed-analytics": {
+      "types": "./analytics/hooks/use-collection-viewed-analytics.d.ts",
+      "default": "./analytics/hooks/use-collection-viewed-analytics.js"
+    },
     "./loaders/collection-loader": {
       "types": "./loaders/collection-loader.d.ts",
       "default": "./loaders/collection-loader.js"