@nebulr-group/bridge-svelte 0.3.0-beta.6 → 0.3.0

package/dist/client/tracking/pii-hashing.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Client-side PII hashing for ad-platform advanced matching.
+ *
+ * Normalization MUST match the server-side util at
+ * `bridge-api/microservices/account/nebulr-api/utils/pii-hashing.util.ts`:
+ *   trim → lowercase → SHA-256 → hex.
+ *
+ * Any divergence between client and server hashing silently hurts match rates.
+ * Tests must assert byte-identical output across both sides for the same input.
+ */
+export declare function sha256Email(email: string | null | undefined): Promise<string | undefined>;

package/dist/client/tracking/pii-hashing.js

@@ -0,0 +1,29 @@
+/**
+ * Client-side PII hashing for ad-platform advanced matching.
+ *
+ * Normalization MUST match the server-side util at
+ * `bridge-api/microservices/account/nebulr-api/utils/pii-hashing.util.ts`:
+ *   trim → lowercase → SHA-256 → hex.
+ *
+ * Any divergence between client and server hashing silently hurts match rates.
+ * Tests must assert byte-identical output across both sides for the same input.
+ */
+export async function sha256Email(email) {
+    if (!email)
+        return undefined;
+    const normalized = email.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    return sha256Hex(normalized);
+}
+async function sha256Hex(input) {
+    if (typeof globalThis.crypto?.subtle?.digest !== 'function') {
+        // SSR / non-browser context without WebCrypto — skip hashing.
+        // Callers treat undefined as "advanced matching unavailable" and fall back to plain pixel.
+        return undefined;
+    }
+    const encoder = new TextEncoder();
+    const data = encoder.encode(input);
+    const buf = await globalThis.crypto.subtle.digest('SHA-256', data);
+    return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}

package/dist/client/tracking/pii-hashing.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client/tracking/pii-hashing.spec.js

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { webcrypto } from 'node:crypto';
+import { sha256Email } from './pii-hashing.js';
+/**
+ * Client-side PII hashing fixtures.
+ *
+ * The expected SHA-256 hex outputs below are shared BYTE-FOR-BYTE with
+ * the server-side test at
+ *   bridge-api/microservices/account/nebulr-api/utils/pii-hashing.util.spec.ts.
+ *
+ * Reddit advanced-matching match rate depends on client and server producing
+ * identical hashes for the same raw email. If either side changes
+ * normalization (trim/lowercase) or algorithm, the hashes diverge and
+ * match rates silently fall — these tests catch that drift.
+ */
+// SHA-256 hex of "user@example.com"
+const USER_AT_EXAMPLE_COM_HASH = 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514';
+// SHA-256 hex of "admin@gmail.com"
+const ADMIN_AT_GMAIL_COM_HASH = '7932b2e116b076a54f452848eaabd5857f61bd957fe8a218faf216f24c9885bb';
+/**
+ * Vitest's `environment: 'node'` exposes Node's `webcrypto` at `globalThis.crypto`
+ * from v19+, but the `digest()` API is the same as the browser `crypto.subtle`
+ * that `sha256Email` expects. We defensively wire it up here so the test is
+ * robust across Node versions.
+ */
+beforeAll(() => {
+    if (!globalThis.crypto || typeof globalThis.crypto.subtle?.digest !== 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        globalThis.crypto = webcrypto;
+    }
+});
+describe('sha256Email (client)', () => {
+    it('hashes a plain, already-normalized email to the known SHA-256 hex (matches server fixture)', async () => {
+        await expect(sha256Email('user@example.com')).resolves.toBe(USER_AT_EXAMPLE_COM_HASH);
+    });
+    it('trims whitespace and lowercases before hashing — output matches the plain form byte-for-byte', async () => {
+        const messy = await sha256Email('  User@Example.COM  ');
+        const clean = await sha256Email('user@example.com');
+        expect(messy).toBe(clean);
+        expect(messy).toBe(USER_AT_EXAMPLE_COM_HASH);
+    });
+    it('hashes a second fixture email consistently (matches server fixture)', async () => {
+        await expect(sha256Email('admin@gmail.com')).resolves.toBe(ADMIN_AT_GMAIL_COM_HASH);
+    });
+    it('returns undefined for empty string', async () => {
+        await expect(sha256Email('')).resolves.toBeUndefined();
+    });
+    it('returns undefined for null', async () => {
+        await expect(sha256Email(null)).resolves.toBeUndefined();
+    });
+    it('returns undefined for undefined', async () => {
+        await expect(sha256Email(undefined)).resolves.toBeUndefined();
+    });
+    it('returns undefined for whitespace-only input (normalization collapses to empty)', async () => {
+        await expect(sha256Email('   ')).resolves.toBeUndefined();
+    });
+});

package/dist/client/tracking/reddit-tracking.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Reddit / GA4 conversion tracking via GTM dataLayer.
+ *
+ * Emits standard events (SignUp, Lead, PageVisit, Purchase) with optional
+ * advanced-matching (hashed email) and a shared `conversion_id` that pairs
+ * with server-side CAPI events for Reddit's deduplication.
+ *
+ * This util lives in bridge-svelte so it can be consumed uniformly by
+ * bridge-cloud-views, bridge-admin-ui, and the marketing site — the hashing
+ * rules and dataLayer contract must stay consistent across all three.
+ *
+ * GTM-side: tags MUST read the `conversion_id` dataLayer variable and forward
+ * it to the Reddit Pixel tag as the event dedup key. Same for
+ * `user_data.email_address` (advanced matching).
+ */
+export type RedditConversionEvent = 'SignUp' | 'Lead' | 'PageVisit' | 'Purchase';
+export interface RedditUserData {
+    /** Pre-hashed (SHA-256 hex of trim+lowercase). Use `sha256Email()` before passing. */
+    email_address?: string;
+    phone_number?: string;
+}
+export interface RedditEcommerceItem {
+    item_id: string;
+    item_name: string;
+    item_category?: string;
+    price: number;
+    quantity: number;
+}
+export interface RedditEcommerce {
+    value: number;
+    currency: string;
+    items: RedditEcommerceItem[];
+}
+export interface PushConversionEventOptions {
+    user_data?: RedditUserData;
+    ecommerce?: RedditEcommerce;
+    /**
+     * How the user signed up or logged in. Surfaces as a GA4 custom dimension.
+     * e.g. 'email' | 'passkey' | 'google' | 'linkedin'
+     */
+    signup_method?: string;
+    /**
+     * UUID shared between this pixel event and the server-side CAPI call.
+     * Reddit dedupes on this value — without it, pixel + CAPI would double-count.
+     */
+    conversion_id?: string;
+}
+declare global {
+    interface Window {
+        dataLayer?: Record<string, unknown>[];
+    }
+}
+export interface RedditTrackingGate {
+    /**
+     * Return true to allow the event, false to suppress. Lets consuming apps
+     * gate on things like "is this the right app?" or "is tracking enabled in env?".
+     * When undefined, all events are pushed (assumes caller handles gating).
+     */
+    (): boolean;
+}
+/**
+ * Install an app-level gate. Called once at app bootstrap (e.g. from
+ * BridgeBootstrap or the app's layout). When the gate returns false, all
+ * pushConversionEvent calls no-op.
+ */
+export declare function configureRedditTracking(gate: RedditTrackingGate | undefined): void;
+/**
+ * Push a conversion event to dataLayer for GTM (Reddit Pixel + GA4).
+ *
+ * No-ops when not in a browser, dataLayer is missing, or the gate returns false.
+ */
+export declare function pushConversionEvent(event: RedditConversionEvent, options?: PushConversionEventOptions): void;
+/** @deprecated Use pushConversionEvent. Kept for backward compatibility. */
+export declare const pushRedditEvent: typeof pushConversionEvent;

package/dist/client/tracking/reddit-tracking.js

@@ -0,0 +1,59 @@
+/**
+ * Reddit / GA4 conversion tracking via GTM dataLayer.
+ *
+ * Emits standard events (SignUp, Lead, PageVisit, Purchase) with optional
+ * advanced-matching (hashed email) and a shared `conversion_id` that pairs
+ * with server-side CAPI events for Reddit's deduplication.
+ *
+ * This util lives in bridge-svelte so it can be consumed uniformly by
+ * bridge-cloud-views, bridge-admin-ui, and the marketing site — the hashing
+ * rules and dataLayer contract must stay consistent across all three.
+ *
+ * GTM-side: tags MUST read the `conversion_id` dataLayer variable and forward
+ * it to the Reddit Pixel tag as the event dedup key. Same for
+ * `user_data.email_address` (advanced matching).
+ */
+let _gate;
+/**
+ * Install an app-level gate. Called once at app bootstrap (e.g. from
+ * BridgeBootstrap or the app's layout). When the gate returns false, all
+ * pushConversionEvent calls no-op.
+ */
+export function configureRedditTracking(gate) {
+    _gate = gate;
+}
+function getDataLayer() {
+    if (typeof window === 'undefined')
+        return undefined;
+    return window.dataLayer;
+}
+/**
+ * Push a conversion event to dataLayer for GTM (Reddit Pixel + GA4).
+ *
+ * No-ops when not in a browser, dataLayer is missing, or the gate returns false.
+ */
+export function pushConversionEvent(event, options) {
+    if (_gate && !_gate())
+        return;
+    const dataLayer = getDataLayer();
+    if (!dataLayer || !Array.isArray(dataLayer))
+        return;
+    const payload = { event };
+    if (options?.user_data && Object.keys(options.user_data).length > 0) {
+        payload.user_data = options.user_data;
+    }
+    if (options?.ecommerce) {
+        // Reddit/GA4 best practice: clear ecommerce before pushing a new one
+        dataLayer.push({ ecommerce: null });
+        payload.ecommerce = options.ecommerce;
+    }
+    if (options?.signup_method != null && options.signup_method !== '') {
+        payload.signup_method = options.signup_method;
+    }
+    if (options?.conversion_id != null && options.conversion_id !== '') {
+        payload.conversion_id = options.conversion_id;
+    }
+    dataLayer.push(payload);
+}
+/** @deprecated Use pushConversionEvent. Kept for backward compatibility. */
+export const pushRedditEvent = pushConversionEvent;

package/dist/client/tracking/reddit-tracking.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client/tracking/reddit-tracking.spec.js

@@ -0,0 +1,126 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { configureRedditTracking, pushConversionEvent } from './reddit-tracking.js';
+function installWindow(dataLayer) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    globalThis.window = { dataLayer };
+}
+function uninstallWindow() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    delete globalThis.window;
+}
+describe('pushConversionEvent', () => {
+    beforeEach(() => {
+        // Reset the module-level gate between tests.
+        configureRedditTracking(undefined);
+    });
+    afterEach(() => {
+        uninstallWindow();
+        configureRedditTracking(undefined);
+    });
+    it('no-ops when the configured gate returns false', () => {
+        const dl = [];
+        installWindow(dl);
+        configureRedditTracking(() => false);
+        pushConversionEvent('SignUp', {
+            user_data: { email_address: 'hash-abc' },
+            conversion_id: 'cid-1'
+        });
+        expect(dl).toHaveLength(0);
+    });
+    it('no-ops when window is missing (SSR / non-browser context)', () => {
+        // No installWindow — globalThis.window is undefined.
+        configureRedditTracking(() => true);
+        // Must not throw.
+        expect(() => pushConversionEvent('SignUp', { conversion_id: 'cid-ssr' })).not.toThrow();
+    });
+    it('no-ops when window.dataLayer is missing', () => {
+        installWindow(undefined);
+        configureRedditTracking(() => true);
+        // Must not throw.
+        expect(() => pushConversionEvent('SignUp', { conversion_id: 'cid-no-dl' })).not.toThrow();
+    });
+    it('pushes a full conversion payload when gate returns true — event, user_data, ecommerce (with cleanup push), signup_method, conversion_id', () => {
+        const dl = [];
+        installWindow(dl);
+        configureRedditTracking(() => true);
+        pushConversionEvent('Purchase', {
+            user_data: { email_address: 'hash-abc' },
+            ecommerce: {
+                value: 29,
+                currency: 'USD',
+                items: [
+                    { item_id: 'premium', item_name: 'Premium Monthly', price: 29, quantity: 1 }
+                ]
+            },
+            signup_method: 'email',
+            conversion_id: 'cid-purchase-1'
+        });
+        // ecommerce cleanup push MUST come first, then the real event payload
+        expect(dl).toHaveLength(2);
+        expect(dl[0]).toEqual({ ecommerce: null });
+        const payload = dl[1];
+        expect(payload.event).toBe('Purchase');
+        expect(payload.user_data).toEqual({ email_address: 'hash-abc' });
+        expect(payload.ecommerce).toMatchObject({
+            value: 29,
+            currency: 'USD'
+        });
+        expect(payload.signup_method).toBe('email');
+        expect(payload.conversion_id).toBe('cid-purchase-1');
+    });
+    it('propagates conversion_id through to the pushed payload', () => {
+        const dl = [];
+        installWindow(dl);
+        configureRedditTracking(() => true);
+        pushConversionEvent('SignUp', { conversion_id: 'my-shared-uuid' });
+        expect(dl).toHaveLength(1);
+        expect(dl[0].conversion_id).toBe('my-shared-uuid');
+    });
+    it('omits user_data from payload when provided as an empty object', () => {
+        const dl = [];
+        installWindow(dl);
+        configureRedditTracking(() => true);
+        pushConversionEvent('Lead', { user_data: {}, conversion_id: 'cid-lead' });
+        expect(dl).toHaveLength(1);
+        const payload = dl[0];
+        expect(payload.event).toBe('Lead');
+        expect('user_data' in payload).toBe(false);
+        expect(payload.conversion_id).toBe('cid-lead');
+    });
+    it('omits signup_method when the option is undefined or empty string', () => {
+        const dl = [];
+        installWindow(dl);
+        configureRedditTracking(() => true);
+        pushConversionEvent('SignUp', { conversion_id: 'cid-sm-undefined' });
+        pushConversionEvent('SignUp', { signup_method: '', conversion_id: 'cid-sm-empty' });
+        expect(dl).toHaveLength(2);
+        expect('signup_method' in dl[0]).toBe(false);
+        expect('signup_method' in dl[1]).toBe(false);
+    });
+    it('omits conversion_id from payload when the option is undefined or empty string', () => {
+        const dl = [];
+        installWindow(dl);
+        configureRedditTracking(() => true);
+        pushConversionEvent('SignUp');
+        pushConversionEvent('SignUp', { conversion_id: '' });
+        expect(dl).toHaveLength(2);
+        expect('conversion_id' in dl[0]).toBe(false);
+        expect('conversion_id' in dl[1]).toBe(false);
+    });
+    it('pushes without gate-check when no gate is configured', () => {
+        const dl = [];
+        installWindow(dl);
+        // No configureRedditTracking call — default is "allow all".
+        pushConversionEvent('PageVisit', { conversion_id: 'cid-pv' });
+        expect(dl).toHaveLength(1);
+        expect(dl[0].event).toBe('PageVisit');
+    });
+    it('emits the ecommerce cleanup push only when ecommerce option is provided', () => {
+        const dl = [];
+        installWindow(dl);
+        configureRedditTracking(() => true);
+        pushConversionEvent('SignUp', { conversion_id: 'cid-no-ecom' });
+        expect(dl).toHaveLength(1);
+        expect(dl[0]).not.toEqual({ ecommerce: null });
+    });
+});

package/dist/index.d.ts

@@ -27,6 +27,9 @@ export * from './auth/route-guard.js';
 export * from './shared/profile.js';
 export * from './shared/types/config.js';
 export { logger, setLoggerDebug } from './shared/logger.js';
+export { pushConversionEvent, pushRedditEvent, configureRedditTracking, } from './client/tracking/reddit-tracking.js';
+export type { RedditConversionEvent, RedditEcommerce, RedditEcommerceItem, RedditUserData, PushConversionEventOptions, RedditTrackingGate, } from './client/tracking/reddit-tracking.js';
+export { sha256Email } from './client/tracking/pii-hashing.js';
 export type { AuthConfigResponse, AuthResult, AuthState, BridgeAuthConfig, BridgeAuthEventName, BridgeAuthEvents, FederationConnection, MagicLinkResult, MfaResult, PasskeyAuthOptions, PasskeyRegistrationOptions, PasskeyVerificationResult, SignupResult, SsoOptions, SsoResult, TenantUser, } from '@nebulr-group/bridge-auth-core';
 export { BridgeAuth, BridgeAuthError, HttpError, TeamService, ApiTokenService } from '@nebulr-group/bridge-auth-core';
 export type { ApiToken, CreateApiTokenInput, CreateApiTokenResponse, } from '@nebulr-group/bridge-auth-core';

package/dist/index.js

@@ -36,4 +36,7 @@ export * from './shared/profile.js';
 export * from './shared/types/config.js';
 // Logger
 export { logger, setLoggerDebug } from './shared/logger.js';
+// Conversion tracking (Reddit / GA4 via GTM dataLayer)
+export { pushConversionEvent, pushRedditEvent, configureRedditTracking, } from './client/tracking/reddit-tracking.js';
+export { sha256Email } from './client/tracking/pii-hashing.js';
 export { BridgeAuth, BridgeAuthError, HttpError, TeamService, ApiTokenService } from '@nebulr-group/bridge-auth-core';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nebulr-group/bridge-svelte",
-	"version": "0.3.0-beta.6",
+	"version": "0.3.0",
 	"description": "Bridge Svelte library, This library helps you to add bridge authentication and feature flags, and payments to your svelte application.",
 	"author": "Iman Pouya",
 	"license": "MIT",
@@ -20,6 +20,7 @@
 		"prepack": "svelte-kit sync && svelte-package",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"test:unit": "vitest run",
 		"package": "bun run prepack && bun pm pack --destination ../",
 		"publish:local": "bun run prepack && node -e \"const fs=require('fs'),p=JSON.parse(fs.readFileSync('package.json','utf8')),v=p.version.match(/^(\\d+\\.\\d+\\.\\d+)-alpha\\.(\\d+)$/);if(v){p.version=v[1]+'-alpha.'+(+v[2]+1);}else{p.version=p.version+'-alpha.0';}fs.writeFileSync('package.json',JSON.stringify(p,null,'\t')+'\\n');console.log('Version bumped to '+p.version);\" && npm publish --registry http://host.docker.internal:4873 --no-git-checks --ignore-scripts && npm dist-tag add @nebulr-group/bridge-svelte@$(node -p \"require('./package.json').version\") alpha --registry http://host.docker.internal:4873"
 	},
@@ -60,7 +61,7 @@
 		}
 	},
 	"dependencies": {
-		"@nebulr-group/bridge-auth-core": "0.1.0-beta.4"
+		"@nebulr-group/bridge-auth-core": "0.1.0"
 	},
 	"devDependencies": {
 		"@sveltejs/kit": "^2.16.0",
@@ -71,7 +72,8 @@
 		"svelte": "^5.0.0",
 		"svelte-check": "^4.0.0",
 		"typescript": "^5.0.0",
-		"vite": "^6.2.6"
+		"vite": "^6.2.6",
+		"vitest": "^4.1.4"
 	},
 	"keywords": [
 		"svelte",