@uniformdev/insights 20.35.1-alpha.87

package/LICENSE.txt

@@ -0,0 +1,2 @@
+© 2025 Uniform Systems, Inc. All Rights Reserved.
+See details of Uniform Systems, Inc. Master Subscription Agreement here: https://uniform.dev/eula

package/README.md

@@ -0,0 +1,78 @@
+# @uniformdev/insights
+
+This package provides insights tracking capabilities for Uniform Context, including a proxy handler for forwarding analytics requests.
+
+## Client-side tracking
+
+Create Uniform Insights Context plugin with endpoint type `api`.
+
+```
+import {
+  Context,
+  ContextPlugin,
+  enableContextDevTools,
+  enableDebugConsoleLogDrain,
+  ManifestV2,
+} from '@uniformdev/context';
+import { enableUniformInsights } from '@uniformdev/insights';
+
+const plugins: ContextPlugin[] = [];
+
+if (typeof window !== 'undefined' && window.document) {
+  plugins.push(
+    enableUniformInsights({
+      endpoint: {
+        type: 'api',
+        projectId: process.env.NEXT_PUBLIC_PROJECT_ID!,
+        apiKey: process.env.NEXT_PUBLIC_UNIFORM_INSIGHTS_KEY!,
+        host: process.env.NEXT_PUBLIC_INSIGHTS_API_URL!,
+      },
+    })
+  );
+}
+
+const context = new Context({
+  ...
+  plugins: plugins,
+});
+```
+
+## Proxy Handler
+
+The proxy handler is optimized for Node.js environments and provides a simple interface for forwarding analytics data to the Uniform Insights API. It automatically:
+
+- Routes requests to `/v0/events` endpoint
+- Sets proper authentication headers
+- Configures NDJSON content type
+- Uses Node.js fetch API types
+- Only requires the request body (URL and headers are built from config)
+
+### Basic Usage with Next.JS
+
+```typescript
+import { NextApiRequest, NextApiResponse } from 'next';
+import { BackendInsightsProxyHandler } from '@uniformdev/insights/proxy';
+
+// Create a proxy handler
+const proxyHandler = new BackendInsightsProxyHandler({
+  apiHost: process.env.INSIGHTS_API_URL,
+  apiKey: process.env.INSIGHTS_API_KEY,
+});
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  const proxyResponse = await proxyHandler.handleRequest(req.body);
+
+  res.status(proxyResponse.status).json(proxyResponse.body);
+}
+```
+To use proxy mode you have to change you Context plugin settings a bit:
+
+```
+enableUniformInsights({
+  endpoint: {
+    type: 'proxy',
+    projectId: process.env.UNIFORM_PROJECT_ID!,
+    path: '/api/{YOUR_ENDPOINT},
+  },
+})
+```

package/dist/chunk-FFLO523H.mjs

@@ -0,0 +1,38 @@
+// src/proxy.ts
+var BackendInsightsProxyHandler = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Handle a proxy request with only the body payload
+   * @param body - The request body to forward
+   * @returns Promise resolving to the API response
+   */
+  async handleRequest(originalBody) {
+    try {
+      const targetUrl = new URL("/v0/events", this.config.apiHost);
+      targetUrl.searchParams.set("name", "events");
+      return fetch(targetUrl.toString(), {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "Content-Type": "application/x-ndjson",
+          Accept: "application/json"
+        },
+        body: originalBody
+      });
+    } catch (error) {
+      throw new Error(
+        `Backend proxy request failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+};
+function createBackendInsightsProxyHandler(config) {
+  return new BackendInsightsProxyHandler(config);
+}
+
+export {
+  BackendInsightsProxyHandler,
+  createBackendInsightsProxyHandler
+};

package/dist/index.d.mts

@@ -0,0 +1,125 @@
+import { TestEvent, Context, PersonalizationEvent, ContextPlugin } from '@uniformdev/context';
+export { BackendInsightsProxyHandler, BackendProxyConfig, createBackendInsightsProxyHandler } from './proxy.mjs';
+
+type InsightsEndpoint = {
+    /** Sending events directly to Uniform Insights API from client-side */
+    type: 'api';
+    /** Region aware api endpoint. Can be one of two values:
+     * - https://analytics.uniform.global
+     * - https://analytics.eu.uniform.global
+     *
+     * Otherwise it will come as NEXT_PUBLIC_INSIGHTS_API_URL environment variable copied from Insights Settings page
+     */
+    host: string;
+    /** API key for the Uniform Insights API. Can be found in Insights Settings page */
+    apiKey: string;
+    /** Uniform project Id. */
+    projectId: string;
+} | {
+    /** Sending events through own proxy. Useful to avoid any traffic towards external analytics related endpoints to trigger AD blockers */
+    type: 'proxy';
+    /** Path to internal proxy endpoint. */
+    path: string;
+    /** Uniform project Id. */
+    projectId: string;
+};
+type InsightsStorage = {
+    get: () => InsightsStorageData | undefined;
+    set: (data: Omit<InsightsStorageData, 'updated'>) => void;
+    clear: () => void;
+};
+type InsightsStorageData = {
+    visitorId: string;
+    sessionId: string;
+    updated: number;
+};
+type UniformMetadata = {
+    composition_id?: string;
+    pm_node_path?: string;
+    dynamic_inputs?: Record<string, string>;
+};
+type WebMetadata = {
+    'user-agent': string;
+    locale: string;
+    location: string;
+    referrer: string;
+    pathname: string;
+    href: string;
+};
+type InsightsTrackingEvent<TAction extends string, TPayload = Record<string, never>> = {
+    timestamp: string;
+    action: TAction;
+    version: '2';
+    visitor_id: string;
+    session_id: string;
+    page_view_id: string;
+    project_id: string;
+    payload: TPayload;
+    web_metadata: WebMetadata;
+    uniform: UniformMetadata;
+};
+type PageHitPayload = Record<string, never>;
+type SessionStatePayload = {
+    previous_session_id: string | undefined;
+};
+type TestResultPayload = TestEvent;
+type PersonalizationResultPayload = {
+    name: string;
+    variantId: string;
+    control: boolean | undefined;
+    changed: boolean;
+};
+type GoalConvertPayload = {
+    goal_id: string;
+};
+type PageHitEvent = InsightsTrackingEvent<'page_hit', PageHitPayload>;
+type SessionStateEvent = InsightsTrackingEvent<'session_start', SessionStatePayload>;
+type TestResultEvent = InsightsTrackingEvent<'test_result', TestResultPayload>;
+type PersonalizationResultEvent = InsightsTrackingEvent<'personalization_result', PersonalizationResultPayload>;
+type GoalConvertEvent = InsightsTrackingEvent<'goal_convert', GoalConvertPayload>;
+type UniformInsights = {
+    init: (context: Context) => Promise<void>;
+    forget: () => void;
+    pageHit: (compositionData?: UniformMetadata) => void;
+    testResult: (result: TestEvent, compositionData?: UniformMetadata) => void;
+    personalizationResult: (result: PersonalizationEvent, compositionData?: UniformMetadata) => void;
+    goalConvert: (goalId: string, compositionData?: UniformMetadata) => void;
+    get sessionId(): string | undefined;
+};
+
+type BatchConfig = {
+    maxBatchSize: number;
+    maxBatchDelayMs: number;
+    maxPayloadSizeBytes: number;
+    maxRequestsPerSecond: number;
+};
+
+interface InsightsPluginOptions {
+    endpoint: InsightsEndpoint;
+    /** Custom storage implementation (optional, defaults to localStorage) */
+    storage?: InsightsStorage;
+    /** Batch configuration for event processing (optional, batching disabled by default) */
+    batchConfig?: Partial<BatchConfig>;
+    /** Session duration in seconds (default: 30 minutes) */
+    sessionDurationSeconds?: number;
+    /** Async functions for visitor and session ID generation */
+    getVisitorId?: ({ context, previousVisitorId, previousSessionId, }: {
+        context: Context;
+        previousVisitorId?: string;
+        previousSessionId?: string;
+    }) => Promise<string>;
+    getSessionId?: ({ context, visitorId, previousSessionId, }: {
+        context: Context;
+        visitorId: string;
+        previousSessionId?: string;
+    }) => Promise<string>;
+}
+declare const createInsightsPlugin: (options: InsightsPluginOptions) => ContextPlugin;
+
+declare const createInsightsStorage: (customStorage?: InsightsStorage) => InsightsStorage;
+/**
+ * Creates a memory-based storage implementation for server-side or testing environments
+ */
+declare const createMemoryStorage: () => InsightsStorage;
+
+export { type BatchConfig, type GoalConvertEvent, type GoalConvertPayload, type InsightsEndpoint, type InsightsPluginOptions, type InsightsStorage, type InsightsStorageData, type InsightsTrackingEvent, type PageHitEvent, type PageHitPayload, type PersonalizationResultEvent, type PersonalizationResultPayload, type SessionStateEvent, type SessionStatePayload, type TestResultEvent, type TestResultPayload, type UniformInsights, type UniformMetadata, type WebMetadata, createInsightsPlugin, createInsightsStorage, createMemoryStorage, createInsightsPlugin as enableUniformInsights };

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+import { TestEvent, Context, PersonalizationEvent, ContextPlugin } from '@uniformdev/context';
+export { BackendInsightsProxyHandler, BackendProxyConfig, createBackendInsightsProxyHandler } from './proxy.js';
+
+type InsightsEndpoint = {
+    /** Sending events directly to Uniform Insights API from client-side */
+    type: 'api';
+    /** Region aware api endpoint. Can be one of two values:
+     * - https://analytics.uniform.global
+     * - https://analytics.eu.uniform.global
+     *
+     * Otherwise it will come as NEXT_PUBLIC_INSIGHTS_API_URL environment variable copied from Insights Settings page
+     */
+    host: string;
+    /** API key for the Uniform Insights API. Can be found in Insights Settings page */
+    apiKey: string;
+    /** Uniform project Id. */
+    projectId: string;
+} | {
+    /** Sending events through own proxy. Useful to avoid any traffic towards external analytics related endpoints to trigger AD blockers */
+    type: 'proxy';
+    /** Path to internal proxy endpoint. */
+    path: string;
+    /** Uniform project Id. */
+    projectId: string;
+};
+type InsightsStorage = {
+    get: () => InsightsStorageData | undefined;
+    set: (data: Omit<InsightsStorageData, 'updated'>) => void;
+    clear: () => void;
+};
+type InsightsStorageData = {
+    visitorId: string;
+    sessionId: string;
+    updated: number;
+};
+type UniformMetadata = {
+    composition_id?: string;
+    pm_node_path?: string;
+    dynamic_inputs?: Record<string, string>;
+};
+type WebMetadata = {
+    'user-agent': string;
+    locale: string;
+    location: string;
+    referrer: string;
+    pathname: string;
+    href: string;
+};
+type InsightsTrackingEvent<TAction extends string, TPayload = Record<string, never>> = {
+    timestamp: string;
+    action: TAction;
+    version: '2';
+    visitor_id: string;
+    session_id: string;
+    page_view_id: string;
+    project_id: string;
+    payload: TPayload;
+    web_metadata: WebMetadata;
+    uniform: UniformMetadata;
+};
+type PageHitPayload = Record<string, never>;
+type SessionStatePayload = {
+    previous_session_id: string | undefined;
+};
+type TestResultPayload = TestEvent;
+type PersonalizationResultPayload = {
+    name: string;
+    variantId: string;
+    control: boolean | undefined;
+    changed: boolean;
+};
+type GoalConvertPayload = {
+    goal_id: string;
+};
+type PageHitEvent = InsightsTrackingEvent<'page_hit', PageHitPayload>;
+type SessionStateEvent = InsightsTrackingEvent<'session_start', SessionStatePayload>;
+type TestResultEvent = InsightsTrackingEvent<'test_result', TestResultPayload>;
+type PersonalizationResultEvent = InsightsTrackingEvent<'personalization_result', PersonalizationResultPayload>;
+type GoalConvertEvent = InsightsTrackingEvent<'goal_convert', GoalConvertPayload>;
+type UniformInsights = {
+    init: (context: Context) => Promise<void>;
+    forget: () => void;
+    pageHit: (compositionData?: UniformMetadata) => void;
+    testResult: (result: TestEvent, compositionData?: UniformMetadata) => void;
+    personalizationResult: (result: PersonalizationEvent, compositionData?: UniformMetadata) => void;
+    goalConvert: (goalId: string, compositionData?: UniformMetadata) => void;
+    get sessionId(): string | undefined;
+};
+
+type BatchConfig = {
+    maxBatchSize: number;
+    maxBatchDelayMs: number;
+    maxPayloadSizeBytes: number;
+    maxRequestsPerSecond: number;
+};
+
+interface InsightsPluginOptions {
+    endpoint: InsightsEndpoint;
+    /** Custom storage implementation (optional, defaults to localStorage) */
+    storage?: InsightsStorage;
+    /** Batch configuration for event processing (optional, batching disabled by default) */
+    batchConfig?: Partial<BatchConfig>;
+    /** Session duration in seconds (default: 30 minutes) */
+    sessionDurationSeconds?: number;
+    /** Async functions for visitor and session ID generation */
+    getVisitorId?: ({ context, previousVisitorId, previousSessionId, }: {
+        context: Context;
+        previousVisitorId?: string;
+        previousSessionId?: string;
+    }) => Promise<string>;
+    getSessionId?: ({ context, visitorId, previousSessionId, }: {
+        context: Context;
+        visitorId: string;
+        previousSessionId?: string;
+    }) => Promise<string>;
+}
+declare const createInsightsPlugin: (options: InsightsPluginOptions) => ContextPlugin;
+
+declare const createInsightsStorage: (customStorage?: InsightsStorage) => InsightsStorage;
+/**
+ * Creates a memory-based storage implementation for server-side or testing environments
+ */
+declare const createMemoryStorage: () => InsightsStorage;
+
+export { type BatchConfig, type GoalConvertEvent, type GoalConvertPayload, type InsightsEndpoint, type InsightsPluginOptions, type InsightsStorage, type InsightsStorageData, type InsightsTrackingEvent, type PageHitEvent, type PageHitPayload, type PersonalizationResultEvent, type PersonalizationResultPayload, type SessionStateEvent, type SessionStatePayload, type TestResultEvent, type TestResultPayload, type UniformInsights, type UniformMetadata, type WebMetadata, createInsightsPlugin, createInsightsStorage, createMemoryStorage, createInsightsPlugin as enableUniformInsights };