@replohq/sdk 1.8.0 → 1.8.2

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/cart/cart-loader.js

@@ -1,8 +1,13 @@
 import { jsx } from "react/jsx-runtime";
+import { unstable_rethrow } from "next/navigation";
 import { getCartAction } from "./cart-actions";
 import { CartProvider } from "./cart-provider";
 async function CartLoader({ children }) {
-  const cart = process.env.NODE_ENV === "development" ? null : await getCartAction();
+  const cart = process.env.NODE_ENV === "development" ? null : await getCartAction().catch((error) => {
+    unstable_rethrow(error);
+    console.warn("[Replo] Failed to load cart:", error);
+    return null;
+  });
   return /* @__PURE__ */ jsx(CartProvider, { cart, children });
 }
 export {

package/cart/cart-provider.js

@@ -223,7 +223,7 @@ function CartProvider({
     setIsCartOpen(false);
   }, []);
   const refreshCart = React.useCallback(async () => {
-    const refreshedCart = await getCartAction();
+    const refreshedCart = await getCartAction().catch(() => null);
     if (!isMounted.current || !refreshedCart || pendingMutations.current !== 0) {
       return;
     }

package/cart/gateways/resolver-cart-gateway.js

@@ -5,13 +5,8 @@ class ResolverCartGateway {
     return cart;
   }
   async getCart(cartId) {
-    try {
-      const gateway = await getCanopyApiGateway();
-      return await gateway.cartGet({ cartId });
-    } catch (error) {
-      console.warn(`Cart ${cartId} not found via canopy-api:`, error);
-      return null;
-    }
+    const gateway = await getCanopyApiGateway();
+    return await gateway.cartGet({ cartId });
   }
   async createCart(lines, discountCodes) {
     try {

package/lib/buildMetadata.js

@@ -1,7 +1,7 @@
 export const BUILD_METADATA = {
   "packageName": "@replohq/sdk",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "branch": "HEAD",
-  "commit": "b651d52d898d9c6fc4fdca33165feed30505e056",
-  "builtAt": "2026-09-15T18:43:12.533Z"
+  "commit": "7407a78e134aa5a47d0a2f79e9a559ace18e6b9a",
+  "builtAt": "2026-09-16T19:55:10.518Z"
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@replohq/sdk",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "reploBuild": {
     "packageName": "@replohq/sdk",
-    "version": "1.8.0",
+    "version": "1.8.2",
     "branch": "HEAD",
-    "commit": "b651d52d898d9c6fc4fdca33165feed30505e056",
-    "builtAt": "2026-09-15T18:43:12.533Z"
+    "commit": "7407a78e134aa5a47d0a2f79e9a559ace18e6b9a",
+    "builtAt": "2026-09-16T19:55:10.518Z"
   },
   "description": "Replo SDK — cart, analytics, and data loaders for agent-built Next.js sites.",
   "license": "SEE LICENSE IN LICENSE",