@kiryl.pekarski/payload-plugin-ab 1.1.0 → 1.2.1

package/dist/analytics/adapters/googleAnalytics/index.d.ts

@@ -0,0 +1,30 @@
+import { AnalyticsAdapter } from '../../index.js';
+
+interface GoogleAnalyticsAdapterConfig {
+    /** GA4 Measurement ID, e.g. "G-XXXXXXXXXX" */
+    measurementId: string;
+    /** GA4 Measurement Protocol API secret — enables trackImpressionServer() */
+    apiSecret?: string;
+    /**
+     * GA4 Property resource name for the Data API — enables getStats().
+     * Format: "properties/XXXXXXXXX"
+     */
+    propertyId?: string;
+    /**
+     * Returns a valid OAuth2 access token for the GA4 Data API.
+     * Required for getStats(). Scopes needed: analytics.readonly.
+     * @example
+     *   import { GoogleAuth } from 'google-auth-library'
+     *   const auth = new GoogleAuth({ scopes: ['https://www.googleapis.com/auth/analytics.readonly'] })
+     *   getAccessToken: () => auth.getAccessToken()
+     */
+    getAccessToken?: () => Promise<string>;
+    /** Custom event name for impressions. Default: 'ab_impression' */
+    impressionEventName?: string;
+    /** Custom event name for conversions. Default: 'ab_conversion' */
+    conversionEventName?: string;
+}
+
+declare function googleAnalyticsAdapter(config: GoogleAnalyticsAdapterConfig): AnalyticsAdapter;
+
+export { type GoogleAnalyticsAdapterConfig, googleAnalyticsAdapter };

package/dist/analytics/adapters/googleAnalytics/index.js

@@ -0,0 +1,188 @@
+// src/analytics/adapters/googleAnalytics/constants.ts
+var DEFAULT_IMPRESSION_EVENT_NAME = "ab_impression";
+var DEFAULT_CONVERSION_EVENT_NAME = "ab_conversion";
+var MEASUREMENT_PROTOCOL_URL = "https://www.google-analytics.com/mp/collect";
+var DATA_API_BASE = "https://analyticsdata.googleapis.com/v1beta";
+
+// src/analytics/adapters/googleAnalytics/utils/canUseGtag.ts
+var canUseGtag = (window2) => {
+  return typeof window2 !== "undefined" && typeof window2.gtag === "function";
+};
+
+// src/analytics/adapters/googleAnalytics/utils/waitForGtag.ts
+function waitForGtag(callback, options = {}) {
+  const { interval = 50, timeout = 5e3 } = options;
+  if (canUseGtag(window)) {
+    callback(window.gtag);
+    return;
+  }
+  const start = Date.now();
+  const id = setInterval(() => {
+    if (canUseGtag(window)) {
+      clearInterval(id);
+      callback(window.gtag);
+    } else if (Date.now() - start >= timeout) {
+      clearInterval(id);
+    }
+  }, interval);
+}
+
+// src/analytics/adapters/googleAnalytics/client.ts
+function trackImpressionClient(config, { experimentId, variantBucket, visitorId, locale, metadata }) {
+  waitForGtag((gtag) => {
+    gtag("event", config.impressionEventName ?? DEFAULT_IMPRESSION_EVENT_NAME, {
+      experiment_id: experimentId,
+      variant_bucket: variantBucket,
+      visitor_id: visitorId,
+      ...locale !== void 0 && { locale },
+      ...metadata
+    });
+  });
+}
+function trackConversionClient(config, { experimentId, goalId, variantBucket, visitorId, goalValue, locale, metadata }) {
+  if (!canUseGtag(window)) {
+    return;
+  }
+  window.gtag("event", config.conversionEventName ?? DEFAULT_CONVERSION_EVENT_NAME, {
+    experiment_id: experimentId,
+    variant_bucket: variantBucket,
+    visitor_id: visitorId,
+    goal_id: goalId,
+    ...goalValue !== void 0 && { value: goalValue },
+    ...locale !== void 0 && { locale },
+    ...metadata
+  });
+}
+
+// src/analytics/adapters/googleAnalytics/server.ts
+async function trackImpressionServer(config, { experimentId, variantBucket, visitorId, locale, metadata }) {
+  if (!config.apiSecret) return;
+  const url = `${MEASUREMENT_PROTOCOL_URL}?measurement_id=${config.measurementId}&api_secret=${config.apiSecret}`;
+  await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_id: visitorId,
+      events: [
+        {
+          name: config.impressionEventName ?? DEFAULT_IMPRESSION_EVENT_NAME,
+          params: {
+            experiment_id: experimentId,
+            variant_bucket: variantBucket,
+            visitor_id: visitorId,
+            engagement_time_msec: 1,
+            ...locale !== void 0 && { locale },
+            ...metadata
+          }
+        }
+      ]
+    })
+  });
+}
+
+// src/analytics/adapters/googleAnalytics/stats.ts
+function parseReport(report) {
+  const result = /* @__PURE__ */ new Map();
+  if (!report) return result;
+  for (const row of report.rows ?? []) {
+    const bucket = row.dimensionValues[0]?.value;
+    const raw = row.metricValues[0]?.value;
+    if (bucket != null && raw != null) {
+      result.set(bucket, parseInt(raw, 10));
+    }
+  }
+  return result;
+}
+async function getExperimentStats(config, experimentId, dateRange = { startDate: "30daysAgo", endDate: "today" }) {
+  if (!config.propertyId || !config.getAccessToken) {
+    throw new Error(
+      "payload-plugin-ab: getStats() requires propertyId and getAccessToken to be set in GoogleAnalyticsAdapterConfig."
+    );
+  }
+  const accessToken = await config.getAccessToken();
+  const url = `${DATA_API_BASE}/${config.propertyId}:batchRunReports`;
+  const makeReport = (eventName) => ({
+    dimensions: [{ name: "customEvent:variant_bucket" }],
+    metrics: [{ name: "eventCount" }],
+    dimensionFilter: {
+      andGroup: {
+        expressions: [
+          {
+            filter: {
+              fieldName: "eventName",
+              stringFilter: { matchType: "EXACT", value: eventName }
+            }
+          },
+          {
+            filter: {
+              fieldName: "customEvent:experiment_id",
+              stringFilter: { matchType: "EXACT", value: experimentId }
+            }
+          }
+        ]
+      }
+    },
+    dateRanges: [dateRange]
+  });
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      requests: [
+        makeReport(config.impressionEventName ?? DEFAULT_IMPRESSION_EVENT_NAME),
+        makeReport(config.conversionEventName ?? DEFAULT_CONVERSION_EVENT_NAME)
+      ]
+    })
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`payload-plugin-ab: GA4 Data API responded with ${res.status}: ${body}`);
+  }
+  const data = await res.json();
+  const impressionMap = parseReport(data.reports[0]);
+  const conversionMap = parseReport(data.reports[1]);
+  const allBuckets = /* @__PURE__ */ new Set([...impressionMap.keys(), ...conversionMap.keys()]);
+  const totalImpressions = [...impressionMap.values()].reduce((acc, n) => acc + n, 0);
+  const totalConversions = [...conversionMap.values()].reduce((acc, n) => acc + n, 0);
+  const variants = [...allBuckets].map((bucket) => {
+    const impressions = impressionMap.get(bucket) ?? 0;
+    const conversions = conversionMap.get(bucket) ?? 0;
+    return {
+      bucket,
+      impressions,
+      impressionShare: totalImpressions > 0 ? impressions / totalImpressions : 0,
+      conversions,
+      conversionRate: impressions > 0 ? conversions / impressions : 0
+    };
+  });
+  return {
+    experimentId,
+    dateRange,
+    variants,
+    totals: {
+      impressions: totalImpressions,
+      conversions: totalConversions
+    }
+  };
+}
+
+// src/analytics/adapters/googleAnalytics/index.ts
+function googleAnalyticsAdapter(config) {
+  return {
+    trackImpression: (args) => trackImpressionClient(config, args),
+    trackConversion: (args) => trackConversionClient(config, args),
+    ...config.apiSecret != null && {
+      trackImpressionServer: (args) => trackImpressionServer(config, args)
+    },
+    ...config.propertyId != null && config.getAccessToken != null && {
+      getStats: (experimentId, dateRange) => getExperimentStats(config, experimentId, dateRange)
+    }
+  };
+}
+export {
+  googleAnalyticsAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/analytics/adapters/googleAnalytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/analytics/adapters/googleAnalytics/constants.ts","../../../../src/analytics/adapters/googleAnalytics/utils/canUseGtag.ts","../../../../src/analytics/adapters/googleAnalytics/utils/waitForGtag.ts","../../../../src/analytics/adapters/googleAnalytics/client.ts","../../../../src/analytics/adapters/googleAnalytics/server.ts","../../../../src/analytics/adapters/googleAnalytics/stats.ts","../../../../src/analytics/adapters/googleAnalytics/index.ts"],"sourcesContent":["export const DEFAULT_IMPRESSION_EVENT_NAME = \"ab_impression\";\r\n\r\nexport const DEFAULT_CONVERSION_EVENT_NAME = \"ab_conversion\";\r\n\r\nexport const MEASUREMENT_PROTOCOL_URL = \"https://www.google-analytics.com/mp/collect\";\r\n\r\nexport const DATA_API_BASE = \"https://analyticsdata.googleapis.com/v1beta\";\r\n","export type WindowWithGtag = Window & { gtag: NonNullable<Window[\"gtag\"]> };\r\n\r\nexport const canUseGtag = (window: Window): window is WindowWithGtag => {\r\n  return typeof window !== \"undefined\" && typeof window.gtag === \"function\";\r\n};\r\n","import { canUseGtag, type WindowWithGtag } from \"./canUseGtag\";\r\n\r\ntype GtagFn = WindowWithGtag[\"gtag\"];\r\n\r\ninterface WaitForGtagOptions {\r\n  interval?: number;\r\n  timeout?: number;\r\n}\r\n\r\nexport function waitForGtag(callback: (gtag: GtagFn) => void, options: WaitForGtagOptions = {}) {\r\n  const { interval = 50, timeout = 5000 } = options;\r\n\r\n  if (canUseGtag(window)) {\r\n    callback(window.gtag);\r\n\r\n    return;\r\n  }\r\n\r\n  const start = Date.now();\r\n  const id = setInterval(() => {\r\n    if (canUseGtag(window)) {\r\n      clearInterval(id);\r\n\r\n      callback(window.gtag);\r\n    } else if (Date.now() - start >= timeout) {\r\n      clearInterval(id);\r\n    }\r\n  }, interval);\r\n}\r\n","import type { TrackConversionArgs, TrackImpressionArgs } from \"../../types\";\r\nimport type { GoogleAnalyticsAdapterConfig } from \"./types\";\r\nimport { DEFAULT_CONVERSION_EVENT_NAME, DEFAULT_IMPRESSION_EVENT_NAME } from \"./constants\";\r\nimport { canUseGtag } from \"./utils/canUseGtag\";\r\nimport { waitForGtag } from \"./utils/waitForGtag\";\r\n\r\ndeclare global {\r\n  interface Window {\r\n    gtag?: (command: \"event\", eventName: string, params: Record<string, unknown>) => void;\r\n  }\r\n}\r\n\r\nexport function trackImpressionClient(\r\n  config: GoogleAnalyticsAdapterConfig,\r\n  { experimentId, variantBucket, visitorId, locale, metadata }: TrackImpressionArgs,\r\n) {\r\n  waitForGtag((gtag) => {\r\n    gtag(\"event\", config.impressionEventName ?? DEFAULT_IMPRESSION_EVENT_NAME, {\r\n      experiment_id: experimentId,\r\n      variant_bucket: variantBucket,\r\n      visitor_id: visitorId,\r\n      ...(locale !== undefined && { locale }),\r\n      ...metadata,\r\n    });\r\n  });\r\n}\r\n\r\nexport function trackConversionClient(\r\n  config: GoogleAnalyticsAdapterConfig,\r\n  { experimentId, goalId, variantBucket, visitorId, goalValue, locale, metadata }: TrackConversionArgs,\r\n) {\r\n  if (!canUseGtag(window)) {\r\n    return;\r\n  }\r\n\r\n  window.gtag(\"event\", config.conversionEventName ?? DEFAULT_CONVERSION_EVENT_NAME, {\r\n    experiment_id: experimentId,\r\n    variant_bucket: variantBucket,\r\n    visitor_id: visitorId,\r\n    goal_id: goalId,\r\n    ...(goalValue !== undefined && { value: goalValue }),\r\n    ...(locale !== undefined && { locale }),\r\n    ...metadata,\r\n  });\r\n}\r\n","import type { TrackImpressionArgs } from \"../../types\";\r\nimport { DEFAULT_IMPRESSION_EVENT_NAME, MEASUREMENT_PROTOCOL_URL } from \"./constants\";\r\nimport type { GoogleAnalyticsAdapterConfig } from \"./types\";\r\n\r\nexport async function trackImpressionServer(\r\n  config: GoogleAnalyticsAdapterConfig,\r\n  { experimentId, variantBucket, visitorId, locale, metadata }: TrackImpressionArgs,\r\n) {\r\n  if (!config.apiSecret) return;\r\n\r\n  const url = `${MEASUREMENT_PROTOCOL_URL}?measurement_id=${config.measurementId}&api_secret=${config.apiSecret}`;\r\n\r\n  await fetch(url, {\r\n    method: \"POST\",\r\n    headers: { \"Content-Type\": \"application/json\" },\r\n    body: JSON.stringify({\r\n      client_id: visitorId,\r\n      events: [\r\n        {\r\n          name: config.impressionEventName ?? DEFAULT_IMPRESSION_EVENT_NAME,\r\n          params: {\r\n            experiment_id: experimentId,\r\n            variant_bucket: variantBucket,\r\n            visitor_id: visitorId,\r\n            engagement_time_msec: 1,\r\n            ...(locale !== undefined && { locale }),\r\n            ...metadata,\r\n          },\r\n        },\r\n      ],\r\n    }),\r\n  });\r\n}\r\n","import type { DateRange, ExperimentStats, VariantStats } from \"../../types\";\r\nimport { DATA_API_BASE, DEFAULT_CONVERSION_EVENT_NAME, DEFAULT_IMPRESSION_EVENT_NAME } from \"./constants\";\r\nimport type { GoogleAnalyticsAdapterConfig } from \"./types\";\r\n\r\ninterface GA4ReportRow {\r\n  dimensionValues: Array<{ value: string }>;\r\n  metricValues: Array<{ value: string }>;\r\n}\r\n\r\ninterface GA4Report {\r\n  rows?: GA4ReportRow[];\r\n}\r\n\r\ninterface GA4BatchResponse {\r\n  reports: GA4Report[];\r\n}\r\n\r\nfunction parseReport(report: GA4Report | undefined): Map<string, number> {\r\n  const result = new Map<string, number>();\r\n\r\n  if (!report) return result;\r\n\r\n  for (const row of report.rows ?? []) {\r\n    const bucket = row.dimensionValues[0]?.value;\r\n    const raw = row.metricValues[0]?.value;\r\n\r\n    if (bucket != null && raw != null) {\r\n      result.set(bucket, parseInt(raw, 10));\r\n    }\r\n  }\r\n\r\n  return result;\r\n}\r\n\r\nexport async function getExperimentStats(\r\n  config: GoogleAnalyticsAdapterConfig,\r\n  experimentId: string,\r\n  dateRange: DateRange = { startDate: \"30daysAgo\", endDate: \"today\" },\r\n): Promise<ExperimentStats> {\r\n  if (!config.propertyId || !config.getAccessToken) {\r\n    throw new Error(\r\n      \"payload-plugin-ab: getStats() requires propertyId and getAccessToken \"\r\n        + \"to be set in GoogleAnalyticsAdapterConfig.\",\r\n    );\r\n  }\r\n\r\n  const accessToken = await config.getAccessToken();\r\n  const url = `${DATA_API_BASE}/${config.propertyId}:batchRunReports`;\r\n\r\n  const makeReport = (eventName: string) => ({\r\n    dimensions: [{ name: \"customEvent:variant_bucket\" }],\r\n    metrics: [{ name: \"eventCount\" }],\r\n    dimensionFilter: {\r\n      andGroup: {\r\n        expressions: [\r\n          {\r\n            filter: {\r\n              fieldName: \"eventName\",\r\n              stringFilter: { matchType: \"EXACT\", value: eventName },\r\n            },\r\n          },\r\n          {\r\n            filter: {\r\n              fieldName: \"customEvent:experiment_id\",\r\n              stringFilter: { matchType: \"EXACT\", value: experimentId },\r\n            },\r\n          },\r\n        ],\r\n      },\r\n    },\r\n    dateRanges: [dateRange],\r\n  });\r\n\r\n  const res = await fetch(url, {\r\n    method: \"POST\",\r\n    headers: {\r\n      Authorization: `Bearer ${accessToken}`,\r\n      \"Content-Type\": \"application/json\",\r\n    },\r\n    body: JSON.stringify({\r\n      requests: [\r\n        makeReport(config.impressionEventName ?? DEFAULT_IMPRESSION_EVENT_NAME),\r\n        makeReport(config.conversionEventName ?? DEFAULT_CONVERSION_EVENT_NAME),\r\n      ],\r\n    }),\r\n  });\r\n\r\n  if (!res.ok) {\r\n    const body = await res.text();\r\n    throw new Error(`payload-plugin-ab: GA4 Data API responded with ${res.status}: ${body}`);\r\n  }\r\n\r\n  const data: GA4BatchResponse = await res.json();\r\n\r\n  const impressionMap = parseReport(data.reports[0]);\r\n  const conversionMap = parseReport(data.reports[1]);\r\n\r\n  const allBuckets = new Set([...impressionMap.keys(), ...conversionMap.keys()]);\r\n\r\n  const totalImpressions = [...impressionMap.values()].reduce((acc, n) => acc + n, 0);\r\n  const totalConversions = [...conversionMap.values()].reduce((acc, n) => acc + n, 0);\r\n\r\n  const variants: VariantStats[] = [...allBuckets].map((bucket) => {\r\n    const impressions = impressionMap.get(bucket) ?? 0;\r\n    const conversions = conversionMap.get(bucket) ?? 0;\r\n    return {\r\n      bucket,\r\n      impressions,\r\n      impressionShare: totalImpressions > 0 ? impressions / totalImpressions : 0,\r\n      conversions,\r\n      conversionRate: impressions > 0 ? conversions / impressions : 0,\r\n    };\r\n  });\r\n\r\n  return {\r\n    experimentId,\r\n    dateRange,\r\n    variants,\r\n    totals: {\r\n      impressions: totalImpressions,\r\n      conversions: totalConversions,\r\n    },\r\n  };\r\n}\r\n","import type { AnalyticsAdapter } from \"../../types\";\r\nimport { trackConversionClient, trackImpressionClient } from \"./client\";\r\nimport { trackImpressionServer } from \"./server\";\r\nimport { getExperimentStats } from \"./stats\";\r\nimport type { GoogleAnalyticsAdapterConfig } from \"./types\";\r\n\r\nexport type { GoogleAnalyticsAdapterConfig };\r\n\r\nexport function googleAnalyticsAdapter(config: GoogleAnalyticsAdapterConfig): AnalyticsAdapter {\r\n  return {\r\n    trackImpression: (args) => trackImpressionClient(config, args),\r\n    trackConversion: (args) => trackConversionClient(config, args),\r\n    ...(config.apiSecret != null && {\r\n      trackImpressionServer: (args) => trackImpressionServer(config, args),\r\n    }),\r\n    ...(config.propertyId != null\r\n      && config.getAccessToken != null && {\r\n        getStats: (experimentId, dateRange) => getExperimentStats(config, experimentId, dateRange),\r\n      }),\r\n  };\r\n}\r\n"],"mappings":"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","names":["window"]}

package/dist/analytics/client.d.ts

@@ -0,0 +1,32 @@
+import { AnalyticsAdapter } from './index.js';
+
+interface ExperimentTrackerProps {
+    experimentId: string;
+    /**
+     * Name of the cookie that holds the assigned variant bucket.
+     * Default: `exp_${experimentId}`
+     */
+    variantCookieName?: string;
+    /** Default: 'ab_visitor_id' */
+    visitorCookieName?: string;
+}
+declare function ExperimentTracker({ experimentId, variantCookieName, visitorCookieName, }: ExperimentTrackerProps): null;
+
+interface UseABConversionOptions {
+    experimentId: string;
+    variantCookieName?: string;
+    visitorCookieName?: string;
+}
+type TrackConversionFn = (args: {
+    goalId: string;
+    goalValue?: number;
+}) => void;
+declare function useABConversion({ experimentId, variantCookieName, visitorCookieName, }: UseABConversionOptions): TrackConversionFn;
+
+declare function useABAnalytics(): AnalyticsAdapter | null;
+declare function ABAnalyticsProvider({ adapter, children, }: {
+    adapter: AnalyticsAdapter;
+    children: React.ReactNode;
+}): React.ReactNode;
+
+export { ABAnalyticsProvider, ExperimentTracker, type ExperimentTrackerProps, type TrackConversionFn, type UseABConversionOptions, useABAnalytics, useABConversion };

package/dist/analytics/client.js

@@ -0,0 +1,88 @@
+"use client";
+
+// src/analytics/components/ABAnalyticsProvider.tsx
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var ABAnalyticsContext = createContext(null);
+function useABAnalytics() {
+  return useContext(ABAnalyticsContext);
+}
+function ABAnalyticsProvider({
+  adapter,
+  children
+}) {
+  return /* @__PURE__ */ jsx(ABAnalyticsContext.Provider, { value: adapter, children });
+}
+
+// src/analytics/components/ExperimentTracker.tsx
+import { useEffect } from "react";
+
+// src/analytics/utils/getCookie.ts
+function getCookie(name) {
+  if (typeof document === "undefined") return null;
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = document.cookie.match(new RegExp(`(?:^|; )${escaped}=([^;]*)`));
+  if (!match) return null;
+  const value = match[1];
+  return value != null ? decodeURIComponent(value) : null;
+}
+
+// src/analytics/constants.ts
+var DEFAULT_A_B_VISITOR_ID = "ab_visitor_id";
+
+// src/analytics/components/ExperimentTracker.tsx
+function ExperimentTracker({
+  experimentId,
+  variantCookieName,
+  visitorCookieName = DEFAULT_A_B_VISITOR_ID
+}) {
+  const adapter = useABAnalytics();
+  useEffect(() => {
+    if (!adapter) return;
+    const sessionKey = `ab_tracked_${experimentId}`;
+    if (typeof sessionStorage !== "undefined" && sessionStorage.getItem(sessionKey)) {
+      return;
+    }
+    const resolvedVariantCookie = variantCookieName ?? `exp_${experimentId}`;
+    const variantBucket = getCookie(resolvedVariantCookie);
+    const visitorId = getCookie(visitorCookieName);
+    if (!variantBucket || !visitorId) return;
+    adapter.trackImpression({ experimentId, variantBucket, visitorId });
+    sessionStorage.setItem(sessionKey, "1");
+  }, [adapter, experimentId, variantCookieName, visitorCookieName]);
+  return null;
+}
+
+// src/analytics/hooks/useABConversion.ts
+import { useCallback } from "react";
+function useABConversion({
+  experimentId,
+  variantCookieName,
+  visitorCookieName = DEFAULT_A_B_VISITOR_ID
+}) {
+  const adapter = useABAnalytics();
+  return useCallback(
+    ({ goalId, goalValue }) => {
+      if (!adapter) return;
+      const cookieName = variantCookieName ?? `exp_${experimentId}`;
+      const variantBucket = getCookie(cookieName);
+      const visitorId = getCookie(visitorCookieName);
+      if (!variantBucket || !visitorId) return;
+      adapter.trackConversion({
+        experimentId,
+        variantBucket,
+        visitorId,
+        goalId,
+        goalValue
+      });
+    },
+    [adapter, experimentId, variantCookieName, visitorCookieName]
+  );
+}
+export {
+  ABAnalyticsProvider,
+  ExperimentTracker,
+  useABAnalytics,
+  useABConversion
+};
+//# sourceMappingURL=client.js.map

package/dist/analytics/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/analytics/components/ABAnalyticsProvider.tsx","../../src/analytics/components/ExperimentTracker.tsx","../../src/analytics/utils/getCookie.ts","../../src/analytics/constants.ts","../../src/analytics/hooks/useABConversion.ts"],"sourcesContent":["\"use client\";\r\n\r\nimport { createContext, useContext } from \"react\";\r\nimport type { AnalyticsAdapter } from \"../types\";\r\n\r\nexport const ABAnalyticsContext = createContext<AnalyticsAdapter | null>(null);\r\n\r\nexport function useABAnalytics() {\r\n  return useContext(ABAnalyticsContext);\r\n}\r\n\r\nexport function ABAnalyticsProvider({\r\n  adapter,\r\n  children,\r\n}: {\r\n  adapter: AnalyticsAdapter;\r\n  children: React.ReactNode;\r\n}): React.ReactNode {\r\n  return <ABAnalyticsContext.Provider value={adapter}>{children}</ABAnalyticsContext.Provider>;\r\n}\r\n","\"use client\";\r\n\r\nimport { useEffect } from \"react\";\r\nimport { getCookie } from \"../utils/getCookie\";\r\nimport { useABAnalytics } from \"./ABAnalyticsProvider\";\r\nimport { DEFAULT_A_B_VISITOR_ID } from \"../constants\";\r\n\r\nexport interface ExperimentTrackerProps {\r\n  experimentId: string;\r\n  /**\r\n   * Name of the cookie that holds the assigned variant bucket.\r\n   * Default: `exp_${experimentId}`\r\n   */\r\n  variantCookieName?: string;\r\n  /** Default: 'ab_visitor_id' */\r\n  visitorCookieName?: string;\r\n}\r\n\r\nexport function ExperimentTracker({\r\n  experimentId,\r\n  variantCookieName,\r\n  visitorCookieName = DEFAULT_A_B_VISITOR_ID,\r\n}: ExperimentTrackerProps) {\r\n  const adapter = useABAnalytics();\r\n\r\n  useEffect(() => {\r\n    if (!adapter) return;\r\n\r\n    const sessionKey = `ab_tracked_${experimentId}`;\r\n    if (typeof sessionStorage !== \"undefined\" && sessionStorage.getItem(sessionKey)) {\r\n      return;\r\n    }\r\n\r\n    const resolvedVariantCookie = variantCookieName ?? `exp_${experimentId}`;\r\n    const variantBucket = getCookie(resolvedVariantCookie);\r\n    const visitorId = getCookie(visitorCookieName);\r\n\r\n    if (!variantBucket || !visitorId) return;\r\n\r\n    adapter.trackImpression({ experimentId, variantBucket, visitorId });\r\n\r\n    sessionStorage.setItem(sessionKey, \"1\");\r\n  }, [adapter, experimentId, variantCookieName, visitorCookieName]);\r\n\r\n  return null;\r\n}\r\n","export function getCookie(name: string) {\r\n  if (typeof document === \"undefined\") return null;\r\n\r\n  const escaped = name.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\r\n  const match = document.cookie.match(new RegExp(`(?:^|; )${escaped}=([^;]*)`));\r\n\r\n  if (!match) return null;\r\n\r\n  const value = match[1];\r\n\r\n  return value != null ? decodeURIComponent(value) : null;\r\n}\r\n","export const DEFAULT_A_B_VISITOR_ID = \"ab_visitor_id\";\r\n","\"use client\";\r\n\r\nimport { useCallback } from \"react\";\r\nimport { useABAnalytics } from \"../components/ABAnalyticsProvider\";\r\nimport { getCookie } from \"../utils/getCookie\";\r\nimport { DEFAULT_A_B_VISITOR_ID } from \"../constants\";\r\n\r\nexport interface UseABConversionOptions {\r\n  experimentId: string;\r\n  variantCookieName?: string;\r\n  visitorCookieName?: string;\r\n}\r\n\r\nexport type TrackConversionFn = (args: { goalId: string; goalValue?: number }) => void;\r\n\r\nexport function useABConversion({\r\n  experimentId,\r\n  variantCookieName,\r\n  visitorCookieName = DEFAULT_A_B_VISITOR_ID,\r\n}: UseABConversionOptions): TrackConversionFn {\r\n  const adapter = useABAnalytics();\r\n\r\n  return useCallback(\r\n    ({ goalId, goalValue }: { goalId: string; goalValue?: number }) => {\r\n      if (!adapter) return;\r\n\r\n      const cookieName = variantCookieName ?? `exp_${experimentId}`;\r\n      const variantBucket = getCookie(cookieName);\r\n      const visitorId = getCookie(visitorCookieName);\r\n\r\n      if (!variantBucket || !visitorId) return;\r\n\r\n      adapter.trackConversion({\r\n        experimentId,\r\n        variantBucket,\r\n        visitorId,\r\n        goalId,\r\n        goalValue,\r\n      });\r\n    },\r\n    [adapter, experimentId, variantCookieName, visitorCookieName],\r\n  );\r\n}\r\n"],"mappings":";;;AAEA,SAAS,eAAe,kBAAkB;AAgBjC;AAbF,IAAM,qBAAqB,cAAuC,IAAI;AAEtE,SAAS,iBAAiB;AAC/B,SAAO,WAAW,kBAAkB;AACtC;AAEO,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA;AACF,GAGoB;AAClB,SAAO,oBAAC,mBAAmB,UAAnB,EAA4B,OAAO,SAAU,UAAS;AAChE;;;ACjBA,SAAS,iBAAiB;;;ACFnB,SAAS,UAAU,MAAc;AACtC,MAAI,OAAO,aAAa,YAAa,QAAO;AAE5C,QAAM,UAAU,KAAK,QAAQ,uBAAuB,MAAM;AAC1D,QAAM,QAAQ,SAAS,OAAO,MAAM,IAAI,OAAO,WAAW,OAAO,UAAU,CAAC;AAE5E,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,QAAQ,MAAM,CAAC;AAErB,SAAO,SAAS,OAAO,mBAAmB,KAAK,IAAI;AACrD;;;ACXO,IAAM,yBAAyB;;;AFkB/B,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AAAA,EACA,oBAAoB;AACtB,GAA2B;AACzB,QAAM,UAAU,eAAe;AAE/B,YAAU,MAAM;AACd,QAAI,CAAC,QAAS;AAEd,UAAM,aAAa,cAAc,YAAY;AAC7C,QAAI,OAAO,mBAAmB,eAAe,eAAe,QAAQ,UAAU,GAAG;AAC/E;AAAA,IACF;AAEA,UAAM,wBAAwB,qBAAqB,OAAO,YAAY;AACtE,UAAM,gBAAgB,UAAU,qBAAqB;AACrD,UAAM,YAAY,UAAU,iBAAiB;AAE7C,QAAI,CAAC,iBAAiB,CAAC,UAAW;AAElC,YAAQ,gBAAgB,EAAE,cAAc,eAAe,UAAU,CAAC;AAElE,mBAAe,QAAQ,YAAY,GAAG;AAAA,EACxC,GAAG,CAAC,SAAS,cAAc,mBAAmB,iBAAiB,CAAC;AAEhE,SAAO;AACT;;;AG3CA,SAAS,mBAAmB;AAarB,SAAS,gBAAgB;AAAA,EAC9B;AAAA,EACA;AAAA,EACA,oBAAoB;AACtB,GAA8C;AAC5C,QAAM,UAAU,eAAe;AAE/B,SAAO;AAAA,IACL,CAAC,EAAE,QAAQ,UAAU,MAA8C;AACjE,UAAI,CAAC,QAAS;AAEd,YAAM,aAAa,qBAAqB,OAAO,YAAY;AAC3D,YAAM,gBAAgB,UAAU,UAAU;AAC1C,YAAM,YAAY,UAAU,iBAAiB;AAE7C,UAAI,CAAC,iBAAiB,CAAC,UAAW;AAElC,cAAQ,gBAAgB;AAAA,QACtB;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,CAAC,SAAS,cAAc,mBAAmB,iBAAiB;AAAA,EAC9D;AACF;","names":[]}

package/dist/analytics/index.d.ts

@@ -0,0 +1,72 @@
+type TrackMetadata = Record<string, string | number | boolean>;
+interface TrackImpressionArgs {
+    /** The experiment identifier — typically the URL path, e.g. "/en/about" */
+    experimentId: string;
+    /** The assigned variant bucket, e.g. "a", "b" */
+    variantBucket: string;
+    visitorId: string;
+    locale?: string;
+    metadata?: TrackMetadata;
+}
+interface TrackConversionArgs {
+    /** The experiment identifier — typically the URL path, e.g. "/en/about" */
+    experimentId: string;
+    /** The assigned variant bucket, e.g. "a", "b" */
+    variantBucket: string;
+    visitorId: string;
+    /** Identifies what conversion goal was achieved, e.g. "cta_click", "purchase" */
+    goalId: string;
+    /** Optional numeric value for statistics */
+    goalValue?: number;
+    locale?: string;
+    metadata?: TrackMetadata;
+}
+interface DateRange {
+    /** 'NdaysAgo' or 'YYYY-MM-DD' */
+    startDate: string;
+    /** 'NdaysAgo', 'today', or 'YYYY-MM-DD' */
+    endDate: string;
+}
+interface VariantStats {
+    bucket: string;
+    impressions: number;
+    /** Fraction of total impressions (0–1) */
+    impressionShare: number;
+    conversions: number;
+    /** conversions / impressions (0–1), 0 when impressions = 0 */
+    conversionRate: number;
+}
+interface ExperimentStats {
+    experimentId: string;
+    dateRange: DateRange;
+    variants: VariantStats[];
+    totals: {
+        impressions: number;
+        conversions: number;
+    };
+}
+interface AnalyticsAdapter {
+    /**
+     * Fire when a user is assigned to and shown a variant.
+     * Called client-side from ExperimentTracker.
+     */
+    trackImpression(args: TrackImpressionArgs): void;
+    /**
+     * Fire when a user completes a conversion goal.
+     * Called client-side from useABConversion.
+     */
+    trackConversion(args: TrackConversionArgs): void;
+    /**
+     * Optional: fire an impression server-side (RSC / Server Action / middleware).
+     * Implemented via GA4 Measurement Protocol when apiSecret is provided.
+     */
+    trackImpressionServer?(args: TrackImpressionArgs): Promise<void>;
+    /**
+     * Optional: fetch aggregated stats for an experiment.
+     * Powers the ExperimentStatsWidget admin component.
+     * Requires propertyId and getAccessToken in the adapter config.
+     */
+    getStats?(experimentId: string, dateRange?: DateRange): Promise<ExperimentStats>;
+}
+
+export type { AnalyticsAdapter, DateRange, ExperimentStats, TrackConversionArgs, TrackImpressionArgs, VariantStats };

package/dist/analytics/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/analytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiryl.pekarski/payload-plugin-ab",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "A/B testing plugin for Payload CMS",
   "keywords": [
     "payload-cms",
@@ -36,6 +36,15 @@
       ],
       "adapters/vercel-edge": [
         "./dist/adapters/vercelEdge/index.d.ts"
+      ],
+      "analytics": [
+        "./dist/analytics/index.d.ts"
+      ],
+      "analytics/client": [
+        "./dist/analytics/client.d.ts"
+      ],
+      "analytics/adapters/google-analytics": [
+        "./dist/analytics/adapters/googleAnalytics/index.d.ts"
       ]
     }
   },
@@ -51,16 +60,35 @@
     "./adapters/vercel-edge": {
       "import": "./dist/adapters/vercelEdge/index.js",
       "types": "./dist/adapters/vercelEdge/index.d.ts"
+    },
+    "./analytics": {
+      "import": "./dist/analytics/index.js",
+      "types": "./dist/analytics/index.d.ts"
+    },
+    "./analytics/client": {
+      "import": "./dist/analytics/client.js",
+      "types": "./dist/analytics/client.d.ts"
+    },
+    "./analytics/adapters/google-analytics": {
+      "import": "./dist/analytics/adapters/googleAnalytics/index.js",
+      "types": "./dist/analytics/adapters/googleAnalytics/index.d.ts"
     }
   },
   "peerDependencies": {
-    "payload": "^3.0.0"
+    "payload": "^3.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "optionalDependencies": {
     "@vercel/edge-config": "^1.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
     "eslint": "^9.0.0",
     "eslint-config-prettier": "^9.0.0",
     "payload": "^3.73.0",