@replohq/sdk 1.14.0 → 1.15.0

package/_vendor/schemas/generated/consent.d.ts

@@ -1,4 +1,4 @@
-export type ReploScriptType = "GA4" | "GoogleTagManager" | "Meta" | "TikTok" | "Pinterest" | "Reddit" | "Snapchat" | "Hotjar" | "MicrosoftClarity" | "Contentsquare" | "Segment" | "Northbeam" | "Gorgias" | "Converge" | "Cookiebot" | "snippet" | "custom" | "consentPlatform";
+export type ReploScriptType = "GA4" | "GoogleTagManager" | "Meta" | "TikTok" | "Pinterest" | "Reddit" | "Snapchat" | "X" | "Hotjar" | "MicrosoftClarity" | "Contentsquare" | "Segment" | "Northbeam" | "Gorgias" | "Converge" | "Cookiebot" | "snippet" | "custom" | "consentPlatform";
 export type ConsentCategory = "necessary" | "analytics" | "marketing" | "preferences" | "sale_of_data";
 export type ConsentMode = "off" | "simple" | "per-category";
 export type ScriptTagDescriptor = {
@@ -12,10 +12,22 @@ export type ScriptTagDescriptor = {
     body: string;
     module?: boolean;
 };
+export type XPixelEvents = {
+    pageView?: string;
+    productViewed?: string;
+    addToCart?: string;
+    startCheckout?: string;
+    purchase?: string;
+};
 export type ReploScriptEntry = {
     type: "GA4" | "GoogleTagManager" | "Meta" | "TikTok" | "Pinterest" | "Reddit" | "Snapchat" | "Hotjar" | "MicrosoftClarity" | "Contentsquare" | "Segment" | "Northbeam" | "Gorgias" | "Converge";
     identifier: string;
     requiredConsent?: ConsentCategory[];
+} | {
+    type: "X";
+    identifier: string;
+    events?: Partial<XPixelEvents>;
+    requiredConsent?: ConsentCategory[];
 } | {
     type: "Cookiebot";
     identifier: string;

package/analytics/get-analytics-sinks.js

@@ -11,6 +11,7 @@ import { ReploSink } from "./sinks/replo-sink";
 import { SnapchatSink } from "./sinks/snapchat-sink";
 import { TikTokSink } from "./sinks/tiktok-sink";
 import { WindowSink } from "./sinks/window-sink";
+import { XSink } from "./sinks/x-sink";
 import { gateShopifyOwnedFunnelEvents } from "./utils/shopify-funnel-gate";
 const PROVIDER_SINK_FACTORIES = {
   GA4: () => new GA4Sink(),
@@ -26,6 +27,14 @@ const SNIPPET_PROVIDER_SINK_FACTORIES = {
   [snippetScriptId("Elevar")]: () => new ElevarSink()
 };
 function findSinkFactory(script) {
+  if (script.type === "X") {
+    return () => {
+      return new XSink({
+        pixelId: script.pixelId,
+        events: script.events
+      });
+    };
+  }
   if (script.type === "snippet") {
     return SNIPPET_PROVIDER_SINK_FACTORIES[script.id] ?? null;
   }

package/analytics/sinks/x-sink.d.ts

@@ -0,0 +1,32 @@
+import type { XPixelEvents } from "../../_vendor/schemas/generated/consent";
+import type { AnalyticsSink, DataPayload, PurchasePayload } from "../analytics-sink";
+import type { PageMetadata } from "../utils/navigation-tracker";
+declare global {
+    interface Window {
+        twq?: (command: "config" | "event", ...args: unknown[]) => void;
+    }
+}
+/**
+ * Sends storefront events to X as the conversion events the merchant created
+ * in X Ads Events Manager. X has no named events in code, so an event without
+ * a mapped ID sends nothing. The consent-gated base code's `twq('config')`
+ * already records the site visit and landing page view on load.
+ */
+export declare class XSink implements AnalyticsSink {
+    private readonly events;
+    private send;
+    constructor({ pixelId, events }: {
+        pixelId: string;
+        events: XPixelEvents;
+    });
+    private track;
+    pageView(metadata: PageMetadata | undefined): Promise<void>;
+    purchase({ amount, currency, data }: PurchasePayload): Promise<void>;
+    click(): Promise<void>;
+    productViewed({ data }: DataPayload): Promise<void>;
+    addToCart({ data }: DataPayload): Promise<void>;
+    removeFromCart(): Promise<void>;
+    viewCart(): Promise<void>;
+    startCheckout({ data }: DataPayload): Promise<void>;
+    viewCollection(): Promise<void>;
+}

package/analytics/sinks/x-sink.js

@@ -0,0 +1,126 @@
+import { filterUndefined } from "../../_vendor/replo-utils/lib/object.mjs";
+import { z } from "zod";
+import { isXEventIdForPixel } from "../../consent/script-snippets";
+import { legacyResourceId } from "../utils/analytics-products";
+import { createEventQueue } from "../utils/analytics-utils";
+const analyticsRecordSchema = z.record(z.string(), z.unknown());
+const nonEmptyStringSchema = z.union([
+  z.string().min(1),
+  z.number().finite().transform(String)
+]);
+const finiteNumberSchema = z.union([
+  z.number().finite(),
+  z.string().trim().min(1).transform(Number).pipe(z.number().finite())
+]);
+function parseRecord(value) {
+  const result = analyticsRecordSchema.safeParse(value);
+  return result.success ? result.data : {};
+}
+function parseString(value) {
+  const result = nonEmptyStringSchema.safeParse(value);
+  return result.success ? result.data : void 0;
+}
+function parseNumber(value) {
+  const result = finiteNumberSchema.safeParse(value);
+  return result.success ? result.data : void 0;
+}
+function mapContent(value, defaultQuantity) {
+  const line = parseRecord(value);
+  const variant = parseRecord(line.variant);
+  const product = parseRecord(variant.product);
+  const productId = parseString(line.productId) ?? parseString(product.id);
+  if (!productId) {
+    return null;
+  }
+  return filterUndefined({
+    content_id: legacyResourceId(productId),
+    content_name: parseString(line.productTitle) ?? parseString(product.title) ?? parseString(line.title),
+    content_price: parseNumber(line.price) ?? parseNumber(parseRecord(variant.price).amount),
+    num_items: parseNumber(line.quantity) ?? defaultQuantity
+  });
+}
+function mapContents(lines) {
+  const result = z.array(z.unknown()).safeParse(lines);
+  if (!result.success) {
+    return void 0;
+  }
+  const contents = result.data.map((line) => mapContent(line, void 0)).filter((content) => content !== null);
+  return contents.length > 0 ? contents : void 0;
+}
+function lineValue(content) {
+  if (content?.content_price === void 0) {
+    return void 0;
+  }
+  return content.content_price * (content.num_items ?? 1);
+}
+class XSink {
+  events;
+  send = createEventQueue(
+    () => typeof window !== "undefined" && Boolean(window.twq),
+    (eventId, parameters) => window.twq?.("event", eventId, parameters),
+    "X"
+  );
+  constructor({ pixelId, events }) {
+    this.events = Object.fromEntries(
+      Object.entries(events).flatMap(([event, eventId]) => {
+        const trimmed = eventId?.trim();
+        return trimmed && isXEventIdForPixel({ eventId: trimmed, pixelId }) ? [[event, trimmed]] : [];
+      })
+    );
+  }
+  track(event, parameters) {
+    const eventId = this.events[event];
+    if (eventId) {
+      this.send(eventId, filterUndefined(parameters));
+    }
+  }
+  async pageView(metadata) {
+    if (metadata?.navigationType === "initial") {
+      return;
+    }
+    this.track("pageView", {});
+  }
+  async purchase({ amount, currency, data }) {
+    this.track("purchase", {
+      value: amount,
+      currency,
+      conversion_id: parseString(data.order_id) ?? parseString(data.orderId) ?? parseString(data.id),
+      contents: mapContents(data.lineItems)
+    });
+  }
+  async click() {
+  }
+  async productViewed({ data }) {
+    const content = mapContent(data, 1);
+    this.track("productViewed", {
+      value: lineValue(content),
+      currency: parseString(data.currency),
+      contents: content ? [content] : void 0
+    });
+  }
+  async addToCart({ data }) {
+    const content = mapContent(data, 1);
+    this.track("addToCart", {
+      value: lineValue(content),
+      currency: parseString(data.currency),
+      contents: content ? [content] : void 0
+    });
+  }
+  async removeFromCart() {
+  }
+  async viewCart() {
+  }
+  async startCheckout({ data }) {
+    const totalPrice = parseRecord(data.totalPrice);
+    this.track("startCheckout", {
+      value: parseNumber(totalPrice.amount),
+      currency: parseString(data.currencyCode) ?? parseString(totalPrice.currencyCode),
+      contents: mapContents(data.lineItems)
+    });
+  }
+  async viewCollection() {
+  }
+}
+export {
+  XSink
+};

package/cart/buy-now-action.js

@@ -9,6 +9,7 @@ import { buildBaseUrl } from "../lib/url-utils";
 import { createCartAction } from "./cart-actions";
 import { REPLO_ATTRIBUTION_PROPERTY } from "./cart-types";
 import { getReturnUrls } from "./return-urls";
+const REPLO_PROJECT_ID_KEY = "rpid";
 class BuyNowError extends CanopyError {
 }
 class BuyNowCartCreationError extends CanopyError {
@@ -53,7 +54,7 @@ async function buyNowWithRecoveryAction(input) {
         "[Replo] Stripe buy now does not support selling plans or discount codes; those options were ignored."
       );
     }
-    const env = await getEnv();
+    const env2 = await getEnv();
     const temporaryCartId = input.checkoutAttemptId ?? uuidv4();
     const body = {
       cartId: temporaryCartId,
@@ -63,11 +64,11 @@ async function buyNowWithRecoveryAction(input) {
         quantity: line.quantity,
         properties: line.properties
       })),
-      projectId: env.PROJECT_ID,
+      projectId: env2.PROJECT_ID,
       successUrl: `${origin}/checkout/success`,
       cancelUrl
     };
-    const canopyApiUrl = `${buildBaseUrl(env.CANOPY_API_HOST)}/api/v1/stripe-checkout/create-session`;
+    const canopyApiUrl = `${buildBaseUrl(env2.CANOPY_API_HOST)}/api/v1/stripe-checkout/create-session`;
     const response = await fetch(canopyApiUrl, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -130,6 +131,8 @@ async function buyNowWithRecoveryAction(input) {
     });
   }
   const checkoutUrl = new URL(cart.checkoutUrl, origin);
+  const env = await getEnv();
+  checkoutUrl.searchParams.set(REPLO_PROJECT_ID_KEY, env.PROJECT_ID);
   return { result: "created", redirectUrl: checkoutUrl.toString() };
 }
 export {

package/consent/replo-scripts.js

@@ -57,7 +57,7 @@ function descriptorsFor(entry) {
   if (entry.type === "consentPlatform" || entry.type === "Cookiebot") {
     return [];
   }
-  return buildScriptTags({ type: entry.type, identifier: entry.identifier });
+  return buildScriptTags(entry);
 }
 class InjectedScript extends Component {
   componentDidMount() {
@@ -89,17 +89,31 @@ class ScriptRegistration extends Component {
     return null;
   }
 }
-function ManagedScript({ entry }) {
-  const requiredConsent = requiredConsentFor(entry);
+function registrationFor(entry) {
   const id = scriptId(entry);
+  const requiredConsent = requiredConsentFor(entry);
+  if (entry.type === "X") {
+    return {
+      id,
+      type: "X",
+      requiredConsent,
+      pixelId: entry.identifier,
+      events: entry.events ?? {}
+    };
+  }
+  return { id, type: entry.type, requiredConsent };
+}
+function ManagedScript({ entry }) {
+  const registration = registrationFor(entry);
+  const { id, requiredConsent } = registration;
   const isBlockedByNativeConsent = useIsBlockedByNativeConsent(requiredConsent);
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx(
       ScriptRegistration,
       {
-        script: { id, type: entry.type, requiredConsent }
+        script: registration
       },
-      `${id}:${requiredConsent.join(",")}`
+      JSON.stringify(registration)
     ),
     !isBlockedByNativeConsent && /* @__PURE__ */ jsx(
       InjectedScript,

package/consent/script-registration-store.d.ts

@@ -1,4 +1,4 @@
-import type { ConsentCategory, ReploScriptType } from "../_vendor/schemas/generated/consent";
+import type { ConsentCategory, ReploScriptType, XPixelEvents } from "../_vendor/schemas/generated/consent";
 /**
  * Tracks which managed scripts are currently mounted on the page. Each
  * `ReploScripts` entry registers itself here on mount, so the analytics provider
@@ -6,11 +6,16 @@ import type { ConsentCategory, ReploScriptType } from "../_vendor/schemas/genera
  * without importing a static list. Like the consent store, this is a singleton
  * rather than React context so it works regardless of tree position.
  */
-export interface RegisteredScript {
+export type RegisteredScript = {
     id: string;
-    type: ReploScriptType;
     requiredConsent: ConsentCategory[];
-}
+} & ({
+    type: Exclude<ReploScriptType, "X">;
+} | {
+    type: "X";
+    pixelId: string;
+    events: XPixelEvents;
+});
 /**
  * Registration id of a `snippet` entry. Snippet providers have no distinct
  * `type`, so both `ReploScripts` (registering) and the analytics sink factory

package/consent/script-snippets.d.ts

@@ -1,19 +1,19 @@
-import type { ConsentCategory, ReploScriptType, ScriptTagDescriptor } from "../_vendor/schemas/generated/consent";
+import type { ConsentCategory, ReploScriptEntry, ReploScriptType, ScriptTagDescriptor } from "../_vendor/schemas/generated/consent";
 type ProviderType = Exclude<ReploScriptType, "custom" | "snippet" | "consentPlatform" | "Cookiebot">;
 /**
  * Snippet providers don't synthesize tags (the user pastes the provider-issued
  * snippet as the entry's `body`), but they still get a first-class default
  * consent categorization like identifier providers.
  */
-/**
- * Returns the structured tag descriptors for a named provider. A single provider
- * can produce multiple tags (e.g. GA4 = external loader + inline config), which
- * the runtime injects in order.
- */
-export declare function buildScriptTags({ type, identifier, }: {
+/** IDs for another pixel would credit a different advertiser. */
+export declare function isXEventIdForPixel({ eventId, pixelId, }: {
+    eventId: string;
+    pixelId: string;
+}): boolean;
+/** The runtime injects these tags in order after consent allows tracking. */
+export declare function buildScriptTags(entry: Extract<ReploScriptEntry, {
     type: ProviderType;
-    identifier: string;
-}): ScriptTagDescriptor[];
+}>): ScriptTagDescriptor[];
 /**
  * The default consent categories that gate an identifier-provider script when an
  * entry does not specify `requiredConsent`. `snippet` and `custom` entries carry

package/consent/script-snippets.js

@@ -69,6 +69,15 @@ gtag('config', '${id}');`
       }
     ]
   },
+  X: {
+    defaultConsent: ["marketing"],
+    buildTags: (id) => [
+      {
+        kind: "inline",
+        body: `!function(e,t,n,s,u,a){e.twq||(s=e.twq=function(){s.exe?s.exe.apply(s,arguments):s.queue.push(arguments);},s.version='1.1',s.queue=[],u=t.createElement(n),u.async=!0,u.src='https://static.ads-twitter.com/uwt.js',a=t.getElementsByTagName(n)[0],a.parentNode.insertBefore(u,a))}(window,document,'script');twq('config','${id}');`
+      }
+    ]
+  },
   Hotjar: {
     defaultConsent: ["analytics"],
     buildTags: (id) => [
@@ -140,16 +149,33 @@ gtag('config', '${id}');`
     ]
   }
 };
-function buildScriptTags({
-  type,
-  identifier
+function isXEventIdForPixel({
+  eventId,
+  pixelId
 }) {
-  return PROVIDER_SNIPPETS[type].buildTags(identifier);
+  const match = /^tw-([a-z0-9]+)-[a-z0-9]+$/i.exec(eventId);
+  return match?.[1]?.toLowerCase() === pixelId.toLowerCase();
+}
+function buildScriptTags(entry) {
+  const tags = PROVIDER_SNIPPETS[entry.type].buildTags(entry.identifier);
+  if (entry.type === "X") {
+    const pageViewId = entry.events?.pageView?.trim();
+    if (pageViewId && isXEventIdForPixel({ eventId: pageViewId, pixelId: entry.identifier })) {
+      return tags.map((tag) => {
+        return tag.kind === "inline" ? {
+          ...tag,
+          body: `${tag.body}twq('event',${JSON.stringify(pageViewId)},{});`
+        } : tag;
+      });
+    }
+  }
+  return tags;
 }
 function defaultConsentFor(type) {
   return PROVIDER_SNIPPETS[type].defaultConsent;
 }
 export {
   buildScriptTags,
-  defaultConsentFor
+  defaultConsentFor,
+  isXEventIdForPixel
 };

package/consent/types.d.ts

@@ -1,4 +1,4 @@
-export type ReploScriptType = "GA4" | "GoogleTagManager" | "Meta" | "TikTok" | "Pinterest" | "Reddit" | "Snapchat" | "Hotjar" | "MicrosoftClarity" | "Contentsquare" | "Segment" | "Northbeam" | "Gorgias" | "Converge" | "Cookiebot" | "snippet" | "custom" | "consentPlatform";
+export type ReploScriptType = "GA4" | "GoogleTagManager" | "Meta" | "TikTok" | "Pinterest" | "Reddit" | "Snapchat" | "X" | "Hotjar" | "MicrosoftClarity" | "Contentsquare" | "Segment" | "Northbeam" | "Gorgias" | "Converge" | "Cookiebot" | "snippet" | "custom" | "consentPlatform";
 export type ConsentCategory = "necessary" | "analytics" | "marketing" | "preferences" | "sale_of_data";
 export type ConsentMode = "off" | "simple" | "per-category";
 declare module "react" {
@@ -16,10 +16,22 @@ export type ScriptTagDescriptor = {
     kind: "inline";
     body: string;
 };
+export type XPixelEvents = {
+    pageView?: string;
+    productViewed?: string;
+    addToCart?: string;
+    startCheckout?: string;
+    purchase?: string;
+};
 export type ReploScriptEntry = {
     type: "GA4" | "GoogleTagManager" | "Meta" | "TikTok" | "Pinterest" | "Reddit" | "Snapchat" | "Hotjar" | "MicrosoftClarity" | "Contentsquare" | "Segment" | "Northbeam" | "Gorgias" | "Converge" | "Cookiebot";
     identifier: string;
     requiredConsent?: ConsentCategory[];
+} | {
+    type: "X";
+    identifier: string;
+    events?: XPixelEvents;
+    requiredConsent?: ConsentCategory[];
 } | {
     type: "snippet";
     id: string;

package/lib/buildMetadata.js

@@ -1,7 +1,7 @@
 export const BUILD_METADATA = {
   "packageName": "@replohq/sdk",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "branch": "HEAD",
-  "commit": "3a43b7ccb4b4143e6b0cbe1c5678c4702deb8b9d",
-  "builtAt": "2026-10-07T15:54:24.638Z"
+  "commit": "3759f7d83c0c4991b7ccbafed0d1b55da1ed48b4",
+  "builtAt": "2026-10-09T21:52:34.432Z"
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@replohq/sdk",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "reploBuild": {
     "packageName": "@replohq/sdk",
-    "version": "1.14.0",
+    "version": "1.15.0",
     "branch": "HEAD",
-    "commit": "3a43b7ccb4b4143e6b0cbe1c5678c4702deb8b9d",
-    "builtAt": "2026-10-07T15:54:24.638Z"
+    "commit": "3759f7d83c0c4991b7ccbafed0d1b55da1ed48b4",
+    "builtAt": "2026-10-09T21:52:34.432Z"
   },
   "description": "Replo SDK — cart, analytics, and data loaders for agent-built Next.js sites.",
   "license": "SEE LICENSE IN LICENSE",