@replohq/sdk 1.7.3 → 1.8.1

package/README.md

@@ -0,0 +1,165 @@
+# `@replohq/sdk`
+
+The Replo SDK provides the React providers, data loaders, cart utilities,
+analytics, consent handling, routing helpers, and Next.js integrations used by
+Replo-powered storefronts.
+
+## Installation
+
+Install the SDK and its runtime peers in a Next.js application:
+
+```sh
+pnpm add @replohq/sdk @opennextjs/cloudflare @tanstack/react-query
+```
+
+The application must use Next.js 15 or newer and React 18.2 or newer. React,
+React DOM, and their type packages are peer dependencies and are normally
+already present in a Next.js application.
+
+## Set up the provider
+
+Mount `ReploProvider` once around the application. It provides the query
+client, cart state, analytics, and loader error handling used by the rest of
+the SDK. Render managed third-party scripts separately with `ReploScripts` from
+`@replohq/sdk/consent/replo-scripts`.
+
+```tsx
+// app/layout.tsx
+import { ReploProvider } from "@replohq/sdk/providers/replo-provider";
+
+export default function RootLayout({ children }: React.PropsWithChildren) {
+  return (
+    <html lang="en">
+      <body>
+        <ReploProvider>{children}</ReploProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+`ReploProvider` is an async Server Component. Components that use SDK hooks or
+loaders must render beneath it.
+
+## Data loaders
+
+Data loaders retrieve data from integrations configured for the Replo project.
+Use constants from `DATA_LOADER_KEYS` instead of copying loader-key strings.
+The key selects the integration operation and is also the first part of the
+React Query cache key.
+
+Loader components are Client Components that pass data to a render function:
+
+```tsx
+// components/product-title.tsx
+"use client";
+
+import { ProductLoader } from "@replohq/sdk/loaders/product-loader";
+import { DATA_LOADER_KEYS } from "@replohq/sdk/loaders/loader-keys";
+
+export function ProductTitle({ handle }: { handle: string }) {
+  return (
+    <ProductLoader
+      loaderKey={DATA_LOADER_KEYS.SHOPIFY_PRODUCT}
+      handle={handle}
+      loadingFallback={<p>Loading…</p>}
+      fallback={<p>Product unavailable.</p>}
+    >
+      {(product) => <h1>{product.title}</h1>}
+    </ProductLoader>
+  );
+}
+```
+
+### Loader environments and integrations
+
+Loaders fetch on the server: directly during SSR, and through a Server Action
+after hydration. The application needs its Replo project configuration in every
+environment:
+
+- During local development and builds, `wrangler.jsonc` must provide
+  `CANOPY_API_HOST` and `PROJECT_ID` in `vars`.
+- In a deployed OpenNext/Cloudflare environment, provide the same values as
+  runtime bindings.
+- Connect each integration in the Replo project; the site holds no provider
+  credentials.
+
+Use these public loader components and keys for each configured integration:
+
+| Integration | Loader component | `DATA_LOADER_KEYS` value |
+| --- | --- | --- |
+| Shopify Storefront | `ProductLoader` | `SHOPIFY_PRODUCT` |
+| Replo product catalog | `ProductLoader` | `REPLO_PRODUCT` |
+| Shopify Storefront | `CollectionLoader` | `SHOPIFY_COLLECTION` |
+| Shopify Storefront | `CollectionProductsLoader` | `SHOPIFY_COLLECTION_PRODUCTS` |
+| Shopify Storefront | `MetaobjectLoader` | `SHOPIFY_METAOBJECT` |
+| Shopify Storefront | `MetaobjectsLoader` | `SHOPIFY_METAOBJECTS` |
+| Okendo | `OkendoReviewsLoader` | `OKENDO_PRODUCT_REVIEWS` |
+| Okendo | `OkendoReviewAggregateLoader` | `OKENDO_PRODUCT_REVIEW_AGGREGATE` |
+| Rebuy | `RebuyRecommendationsLoader` | `REBUY_RECOMMENDATIONS` |
+| Levanta | `LevantaProductLoader` | `LEVANTA_PRODUCT` |
+| Smile.io | `SmileVipTiersLoader` | `SMILE_IO_VIP_TIERS` |
+| Smile.io | `SmileEarningRulesLoader` | `SMILE_IO_EARNING_RULES` |
+| Smile.io | `SmileRewardsLoader` | `SMILE_IO_REWARDS` |
+| Yotpo | `YotpoReviewsLoader` | `YOTPO_PRODUCT_REVIEWS` |
+| Yotpo | `YotpoReviewAggregateLoader` | `YOTPO_PRODUCT_REVIEW_AGGREGATE` |
+| Reviews.io | `ReviewsIoReviewsLoader` | `REVIEWS_IO_PRODUCT_REVIEWS` |
+| Reviews.io | `ReviewsIoReviewAggregateLoader` | `REVIEWS_IO_PRODUCT_REVIEW_AGGREGATE` |
+| Loox | `LooxReviewsLoader` | `LOOX_PRODUCT_REVIEWS` |
+| Loox | `LooxReviewAggregateLoader` | `LOOX_PRODUCT_REVIEW_AGGREGATE` |
+| Judge.me | `JudgemeReviewsLoader` | `JUDGEME_PRODUCT_REVIEWS` |
+| Judge.me | `JudgemeReviewAggregateLoader` | `JUDGEME_PRODUCT_REVIEW_AGGREGATE` |
+| Statsig | `StatsigExperimentLoader` | `STATSIG_EXPERIMENT` |
+| Contentful | `ContentfulEntryLoader` | `CONTENTFUL_ENTRY` |
+| Contentful | `ContentfulEntriesLoader` | `CONTENTFUL_ENTRIES` |
+
+Import each component from its kebab-case subpath, for example
+`CollectionLoader` from `@replohq/sdk/loaders/collection-loader`.
+
+### Prefetch on the server
+
+`PrefetchedLoaders` is a Server Component that fetches loader data during SSR
+and hydrates the React Query cache. Wrap the matching Client Component to avoid
+a loading state on the first paint:
+
+```tsx
+// app/products/[handle]/page.tsx
+import { PrefetchedLoaders } from "@replohq/sdk/loaders/prefetch-loaders";
+import { DATA_LOADER_KEYS } from "@replohq/sdk/loaders/loader-keys";
+
+import { ProductTitle } from "../../../components/product-title";
+
+export default async function ProductPage({
+  params,
+}: {
+  params: Promise<{ handle: string }>;
+}) {
+  const { handle } = await params;
+
+  return (
+    <PrefetchedLoaders
+      queries={[
+        {
+          loaderKey: DATA_LOADER_KEYS.SHOPIFY_PRODUCT,
+          args: { handle },
+        },
+      ]}
+    >
+      <ProductTitle handle={handle} />
+    </PrefetchedLoaders>
+  );
+}
+```
+
+The `loaderKey` and complete `args` object must exactly match the props used by
+the loader component, including optional locale, pagination, or metafield
+arguments. `PrefetchedLoaders` accepts `revalidateSeconds` per query; it
+defaults to 60 seconds, and `false` enables indefinite tag-based caching.
+
+Server-only code that does not hydrate a loader component can call
+`invokeLoaderServer` from `@replohq/sdk/loaders/invoke-loader-server`.
+
+## License
+
+This package is proprietary software. See [LICENSE](./LICENSE)
+(`SEE LICENSE IN LICENSE`) and the [Replo Terms of Service](https://replo.app/terms).

package/_vendor/replo-utils/lib/crypto.d.ts

@@ -12,14 +12,8 @@ export declare function randomBase64Url(byteLength: number): string;
  * `crypto.getRandomValues`, which carries no such restriction.
  */
 export declare function randomUUID(): string;
-/**
- * Returns the SHA-256 of `input` as a 64-char lowercase hex string.
- *
- * Used for storing opaque secrets (e.g. public API tokens) where we want
- * constant-length hex output suitable for a `VARCHAR(64)` column with a
- * unique index.
- */
-export declare function sha256Hex(input: string): Promise<string>;
+/** Strings use UTF-8; binary inputs are hashed unchanged. */
+export declare function sha256Hex(input: string | Parameters<typeof crypto.subtle.digest>[1]): Promise<string>;
 export declare function constantTimeEqual({ left, right, }: {
     left: Uint8Array;
     right: Uint8Array;

package/_vendor/replo-utils/lib/url.d.ts

@@ -70,4 +70,5 @@ export declare function fileExtensionFromUrl(url: string): string;
 export declare function sanitizePublicHttpUrl(value: string | null, { preserveProtocol }?: {
     preserveProtocol?: boolean;
 }): string | null;
+export declare function isPublicHttpsUrl(value: string): boolean;
 export declare function safeHost(url: string): string | null;

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.1",
   "branch": "HEAD",
-  "commit": "d7ee0ec28234216b633c81e1a6d8683591c946f8",
-  "builtAt": "2026-09-15T17:30:06.396Z"
+  "commit": "769a5347144bb3d6c77b6f06b075c8f6ad45a6b3",
+  "builtAt": "2026-09-16T18:01:00.137Z"
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@replohq/sdk",
-  "version": "1.7.3",
+  "version": "1.8.1",
   "reploBuild": {
     "packageName": "@replohq/sdk",
-    "version": "1.7.3",
+    "version": "1.8.1",
     "branch": "HEAD",
-    "commit": "d7ee0ec28234216b633c81e1a6d8683591c946f8",
-    "builtAt": "2026-09-15T17:30:06.396Z"
+    "commit": "769a5347144bb3d6c77b6f06b075c8f6ad45a6b3",
+    "builtAt": "2026-09-16T18:01:00.137Z"
   },
   "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"