@funnelsgrove/analytics 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @funnelsgrove/analytics
+
+Shared public analytics SDK helpers for funnels.
+
+## Build And Publish
+
+- Build distributable output with `npm run build --workspace @funnelsgrove/analytics`.
+- Publish from the repo root with `npm publish --workspace @funnelsgrove/analytics --access public`.
+- Local repo installs still resolve this package through npm workspaces when another workspace depends on version `0.1.0`.
+
+## Use This Package For
+
+- browser user-id persistence
+- public analytics event batching and transport
+- identify/track helpers for the public SDK
+- identify bootstrap helper for funnel identity
+- local-only fallback when only the seed publishable key is present
+
+## Responsibilities
+
+- keep client identity stable across funnels
+- own the browser storage contract for the external user id
+- send analytics events through the shared API contract
+- avoid noisy network calls when a real publishable key is not configured
+
+## What Belongs Here
+
+- cookie/localStorage identity helpers
+- public SDK wrappers
+- event normalization and transport
+
+## What Does Not Belong Here
+
+- step routing
+- manifest logic
+- Stripe checkout UI
+- funnel-specific step components

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './services/runtime-api.config';
+export * from './services/sdk-user-id.storage';
+export * from './services/bootstrap-public-analytics-user';
+export * from './services/public-analytics-sdk.service';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './services/runtime-api.config';
+export * from './services/sdk-user-id.storage';
+export * from './services/bootstrap-public-analytics-user';
+export * from './services/public-analytics-sdk.service';

package/dist/services/bootstrap-public-analytics-user.d.ts

@@ -0,0 +1,5 @@
+import type { PublicSdkIdentifyInput } from './public-analytics-sdk.service';
+export type BootstrapPublicAnalyticsUserClient = {
+    identify(input?: PublicSdkIdentifyInput): Promise<string>;
+};
+export declare const bootstrapPublicAnalyticsUser: (input?: PublicSdkIdentifyInput, client?: BootstrapPublicAnalyticsUserClient) => Promise<string>;

package/dist/services/bootstrap-public-analytics-user.js

@@ -0,0 +1,4 @@
+import { publicAnalyticsSdk } from './public-analytics-sdk.service';
+export const bootstrapPublicAnalyticsUser = async (input = {}, client = publicAnalyticsSdk) => {
+    return client.identify(input);
+};

package/dist/services/public-analytics-sdk.service.d.ts

@@ -0,0 +1,56 @@
+export type PublicSdkTrackEventInput = {
+    eventType: string;
+    eventId?: string;
+    occurredAt?: string;
+    stepId?: string;
+    stepName?: string;
+    startedAt?: string;
+    endedAt?: string;
+    selected?: Record<string, unknown>;
+    payload?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+export type PublicSdkStepStartInput = {
+    stepId: string;
+    stepName: string;
+    startedAt: string;
+};
+export type PublicSdkStepEndInput = {
+    stepId: string;
+    stepName: string;
+    startedAt: string;
+    endedAt: string;
+    selected?: Record<string, unknown>;
+};
+export type PublicSdkIdentifyInput = {
+    externalUserId?: string;
+    email?: string;
+    fullName?: string;
+    metadata?: Record<string, unknown>;
+};
+export type PublicAnalyticsSdkOptions = {
+    batchSize: number;
+    flushIntervalMs: number;
+};
+export declare class PublicAnalyticsSdkService {
+    private readonly options;
+    private readonly endpoint;
+    private readonly eventQueue;
+    private flushTimerId;
+    private inFlightFlush;
+    private externalUserId;
+    constructor(options?: Partial<PublicAnalyticsSdkOptions>);
+    getCurrentExternalUserId(): string;
+    identify(input?: PublicSdkIdentifyInput): Promise<string>;
+    track(event: PublicSdkTrackEventInput): string | null;
+    trackStepStarted(input: PublicSdkStepStartInput): string | null;
+    trackStepCompleted(input: PublicSdkStepEndInput): string | null;
+    flush(): Promise<number>;
+    private ensureExternalUserId;
+    private scheduleFlush;
+    private clearFlushTimer;
+    private flushQueue;
+    private sendBatch;
+}
+export declare const publicAnalyticsSdk: PublicAnalyticsSdkService;

package/dist/services/public-analytics-sdk.service.js

@@ -0,0 +1,219 @@
+import { buildMainApiUrl, buildSdkHeaders, FUNNEL_ID, getFunnelSdkPublishableKey, } from './runtime-api.config';
+import { canUseDom, getOrCreateUserId, persistUserId, } from './sdk-user-id.storage';
+const DEFAULT_OPTIONS = {
+    batchSize: 20,
+    flushIntervalMs: 1500,
+};
+const asRecord = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+};
+const asString = (value) => {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed || null;
+};
+const toIsoOrNow = (value) => {
+    if (value) {
+        const parsed = new Date(value);
+        if (!Number.isNaN(parsed.getTime())) {
+            return parsed.toISOString();
+        }
+    }
+    return new Date().toISOString();
+};
+const buildEventId = () => {
+    var _a;
+    if (canUseDom() && typeof ((_a = window.crypto) === null || _a === void 0 ? void 0 : _a.randomUUID) === "function") {
+        return `sdk_evt_${window.crypto.randomUUID().replace(/-/g, "")}`;
+    }
+    return `sdk_evt_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`;
+};
+export class PublicAnalyticsSdkService {
+    constructor(options = {}) {
+        this.options = Object.assign(Object.assign({}, DEFAULT_OPTIONS), options);
+        this.endpoint = buildMainApiUrl("/sdk/public/events");
+        this.eventQueue = [];
+        this.flushTimerId = null;
+        this.inFlightFlush = null;
+        this.externalUserId = null;
+    }
+    getCurrentExternalUserId() {
+        return this.ensureExternalUserId();
+    }
+    async identify(input = {}) {
+        var _a;
+        const externalUserId = persistUserId(input.externalUserId || this.ensureExternalUserId());
+        const publishableKey = getFunnelSdkPublishableKey();
+        if (!publishableKey) {
+            this.externalUserId = externalUserId;
+            return externalUserId;
+        }
+        try {
+            const response = await fetch(buildMainApiUrl("/sdk/public/users/bootstrap"), {
+                method: "POST",
+                headers: buildSdkHeaders({
+                    "Content-Type": "application/json",
+                }),
+                body: JSON.stringify({
+                    publishableKey,
+                    funnelId: FUNNEL_ID || undefined,
+                    externalUserId,
+                    email: asString(input.email) || undefined,
+                    fullName: asString(input.fullName) || undefined,
+                    metadata: asRecord(input.metadata),
+                }),
+            });
+            if (!response.ok) {
+                this.externalUserId = externalUserId;
+                return externalUserId;
+            }
+            const payload = (await response.json());
+            const persistedUserId = persistUserId(asString((_a = payload.user) === null || _a === void 0 ? void 0 : _a.externalUserId) ||
+                asString(payload.externalUserId) ||
+                externalUserId) || externalUserId;
+            this.externalUserId = persistedUserId;
+            return persistedUserId;
+        }
+        catch (_b) {
+            this.externalUserId = externalUserId;
+            return externalUserId;
+        }
+    }
+    track(event) {
+        const eventType = asString(event.eventType);
+        if (!eventType) {
+            return null;
+        }
+        if (!getFunnelSdkPublishableKey()) {
+            return asString(event.eventId) || buildEventId();
+        }
+        const envelope = {
+            eventType,
+            eventId: asString(event.eventId) || buildEventId(),
+            occurredAt: toIsoOrNow(event.occurredAt),
+            stepId: asString(event.stepId),
+            stepName: asString(event.stepName),
+            startedAt: asString(event.startedAt),
+            endedAt: asString(event.endedAt),
+            selected: asRecord(event.selected),
+            payload: asRecord(event.payload),
+            context: asRecord(event.context),
+            metadata: asRecord(event.metadata),
+        };
+        this.eventQueue.push(envelope);
+        if (this.eventQueue.length >= this.options.batchSize) {
+            void this.flush();
+            return envelope.eventId;
+        }
+        this.scheduleFlush();
+        return envelope.eventId;
+    }
+    trackStepStarted(input) {
+        return this.track({
+            eventType: "step_start",
+            stepId: input.stepId,
+            stepName: input.stepName,
+            startedAt: input.startedAt,
+            occurredAt: input.startedAt,
+        });
+    }
+    trackStepCompleted(input) {
+        return this.track({
+            eventType: "step_end",
+            stepId: input.stepId,
+            stepName: input.stepName,
+            startedAt: input.startedAt,
+            endedAt: input.endedAt,
+            occurredAt: input.endedAt,
+            selected: asRecord(input.selected),
+        });
+    }
+    async flush() {
+        if (this.inFlightFlush) {
+            return this.inFlightFlush;
+        }
+        this.clearFlushTimer();
+        this.inFlightFlush = this.flushQueue().finally(() => {
+            this.inFlightFlush = null;
+        });
+        return this.inFlightFlush;
+    }
+    ensureExternalUserId() {
+        if (this.externalUserId) {
+            return this.externalUserId;
+        }
+        this.externalUserId = persistUserId(getOrCreateUserId());
+        return this.externalUserId;
+    }
+    scheduleFlush() {
+        if (!canUseDom() || this.flushTimerId !== null || this.eventQueue.length === 0) {
+            return;
+        }
+        this.flushTimerId = window.setTimeout(() => {
+            this.flushTimerId = null;
+            void this.flush();
+        }, this.options.flushIntervalMs);
+    }
+    clearFlushTimer() {
+        if (!canUseDom() || this.flushTimerId === null) {
+            return;
+        }
+        window.clearTimeout(this.flushTimerId);
+        this.flushTimerId = null;
+    }
+    async flushQueue() {
+        let sentEvents = 0;
+        while (this.eventQueue.length > 0) {
+            const batch = this.eventQueue.splice(0, this.options.batchSize);
+            const delivered = await this.sendBatch(batch);
+            if (!delivered) {
+                this.eventQueue.unshift(...batch);
+                break;
+            }
+            sentEvents += batch.length;
+        }
+        if (this.eventQueue.length > 0) {
+            this.scheduleFlush();
+        }
+        return sentEvents;
+    }
+    async sendBatch(events) {
+        if (events.length === 0) {
+            return true;
+        }
+        const publishableKey = getFunnelSdkPublishableKey();
+        if (!publishableKey) {
+            return true;
+        }
+        const payload = JSON.stringify({
+            publishableKey,
+            funnelId: FUNNEL_ID || undefined,
+            externalUserId: this.ensureExternalUserId(),
+            events,
+        });
+        if (canUseDom() && typeof navigator.sendBeacon === "function") {
+            const accepted = navigator.sendBeacon(this.endpoint, new Blob([payload], { type: "application/json" }));
+            if (accepted) {
+                return true;
+            }
+        }
+        try {
+            const response = await fetch(this.endpoint, {
+                method: "POST",
+                headers: buildSdkHeaders({ "Content-Type": "application/json" }),
+                body: payload,
+                keepalive: true,
+            });
+            return response.ok;
+        }
+        catch (_a) {
+            return false;
+        }
+    }
+}
+export const publicAnalyticsSdk = new PublicAnalyticsSdkService();

package/dist/services/runtime-api.config.d.ts

@@ -0,0 +1,7 @@
+export declare const APP_DEALS_API_BASE_URL: string;
+export declare const FUNNEL_SDK_PUBLISHABLE_KEY: string;
+export declare const FUNNEL_ID: string;
+export declare const hasRealFunnelSdkPublishableKey: (value?: string) => boolean;
+export declare const getFunnelSdkPublishableKey: () => string | null;
+export declare const buildMainApiUrl: (path: string) => string;
+export declare const buildSdkHeaders: (headers?: Record<string, string>) => Record<string, string>;

package/dist/services/runtime-api.config.js

@@ -0,0 +1,40 @@
+var _a, _b, _c, _d;
+const DEFAULT_API_BASE_URL = 'https://sdk-api.funnelsgrove.com';
+const DEFAULT_FUNNEL_SDK_PUBLISHABLE_KEY = 'pk_test_app_deals_seed_public';
+const trimTrailingSlash = (value) => {
+    return value.replace(/\/+$/, '');
+};
+const toNormalizedPath = (path) => {
+    return path.startsWith('/') ? path : `/${path}`;
+};
+const isPreviewFrameRuntime = () => {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    try {
+        return new URLSearchParams(window.location.search).get('previewFrame') === '1';
+    }
+    catch (_a) {
+        return false;
+    }
+};
+export const APP_DEALS_API_BASE_URL = trimTrailingSlash((_a = process.env.NEXT_PUBLIC_APP_DEALS_API_BASE_URL) !== null && _a !== void 0 ? _a : DEFAULT_API_BASE_URL);
+export const FUNNEL_SDK_PUBLISHABLE_KEY = ((_c = (_b = process.env.NEXT_PUBLIC_FUNNEL_SDK_PUBLISHABLE_KEY) !== null && _b !== void 0 ? _b : process.env.NEXT_PUBLIC_FUNNEL_PUBLISHABLE_KEY) !== null && _c !== void 0 ? _c : DEFAULT_FUNNEL_SDK_PUBLISHABLE_KEY).trim();
+export const FUNNEL_ID = ((_d = process.env.NEXT_PUBLIC_FUNNEL_ID) !== null && _d !== void 0 ? _d : '').trim();
+export const hasRealFunnelSdkPublishableKey = (value = FUNNEL_SDK_PUBLISHABLE_KEY) => {
+    const normalized = value.trim();
+    return Boolean(normalized) && normalized !== DEFAULT_FUNNEL_SDK_PUBLISHABLE_KEY;
+};
+export const getFunnelSdkPublishableKey = () => {
+    if (isPreviewFrameRuntime()) {
+        return null;
+    }
+    return hasRealFunnelSdkPublishableKey() ? FUNNEL_SDK_PUBLISHABLE_KEY : null;
+};
+export const buildMainApiUrl = (path) => {
+    return `${APP_DEALS_API_BASE_URL}${toNormalizedPath(path)}`;
+};
+export const buildSdkHeaders = (headers) => {
+    const publishableKey = getFunnelSdkPublishableKey();
+    return Object.assign(Object.assign({}, (publishableKey ? { 'x-sdk-publishable-key': publishableKey } : {})), (headers !== null && headers !== void 0 ? headers : {}));
+};

package/dist/services/sdk-user-id.storage.d.ts

@@ -0,0 +1,7 @@
+declare const canUseDom: () => boolean;
+declare const normalizeUserId: (value: string | null | undefined) => string | null;
+declare const generateUserId: () => string;
+declare const readStoredUserId: () => string | null;
+declare const persistUserId: (value: string) => string;
+declare const getOrCreateUserId: () => string;
+export { canUseDom, generateUserId, getOrCreateUserId, normalizeUserId, persistUserId, readStoredUserId, };

package/dist/services/sdk-user-id.storage.js

@@ -0,0 +1,39 @@
+const USER_ID_STORAGE_KEY = "funnel:external-user-id";
+const canUseDom = () => {
+    return typeof window !== "undefined";
+};
+const normalizeUserId = (value) => {
+    if (!value || typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed || null;
+};
+const generateUserId = () => {
+    var _a;
+    if (canUseDom() && typeof ((_a = window.crypto) === null || _a === void 0 ? void 0 : _a.randomUUID) === "function") {
+        return `sdk_user_${window.crypto.randomUUID().replace(/-/g, "")}`;
+    }
+    return `sdk_user_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`;
+};
+const readStoredUserId = () => {
+    if (!canUseDom()) {
+        return null;
+    }
+    return normalizeUserId(window.localStorage.getItem(USER_ID_STORAGE_KEY));
+};
+const persistUserId = (value) => {
+    const normalized = normalizeUserId(value) || generateUserId();
+    if (canUseDom()) {
+        window.localStorage.setItem(USER_ID_STORAGE_KEY, normalized);
+    }
+    return normalized;
+};
+const getOrCreateUserId = () => {
+    const existing = readStoredUserId();
+    if (existing) {
+        return existing;
+    }
+    return persistUserId(generateUserId());
+};
+export { canUseDom, generateUserId, getOrCreateUserId, normalizeUserId, persistUserId, readStoredUserId, };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@funnelsgrove/analytics",
+  "version": "0.1.0",
+  "type": "module",
+  "private": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "prepublishOnly": "npm run build",
+    "test:run": "vitest run --passWithNoTests"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  }
+}