@tellann/frontend-sdk 0.1.0 → 0.3.0

package/dist/auto-track.js

@@ -2,7 +2,7 @@
 function shouldIgnore(element) {
     let curr = element;
     while (curr) {
-        if (curr.hasAttribute && curr.hasAttribute('data-tellann-ignore')) {
+        if (curr.hasAttribute && (curr.hasAttribute('data-tellann-ignore') || curr.hasAttribute('data-tellann-sensitive'))) {
             return true;
         }
         // Ignore password inputs completely
@@ -39,28 +39,51 @@ export function sanitizeMetadata(metadata) {
         'secret',
         'private_key',
         'access_token',
-        'authorization'
+        'authorization',
+        'cookie',
+        'session_id',
+        'sessionid',
+        'card_number',
+        'file_content'
     ];
-    const sanitize = (val) => {
+    const identifierKeys = ['email', 'phone', 'mobile', 'user_id', 'userid', 'account_id', 'accountid'];
+    const sanitizeUrl = (value) => {
+        try {
+            const parsed = new URL(value, typeof window === 'undefined' ? 'http://localhost' : window.location.origin);
+            const names = [...new Set([...parsed.searchParams.keys()])];
+            parsed.search = names.length ? `?${names.map((name) => `${encodeURIComponent(name)}=`).join('&')}` : '';
+            parsed.hash = '';
+            return parsed.toString();
+        }
+        catch {
+            return value.slice(0, 2_000);
+        }
+    };
+    const sanitize = (val, keyPath = '') => {
         if (val === null || val === undefined)
             return val;
         if (Array.isArray(val)) {
-            return val.map(sanitize);
+            return val.map((item, index) => sanitize(item, `${keyPath}.${index}`));
         }
         if (typeof val === 'object') {
             const result = {};
             for (const key of Object.keys(val)) {
                 const lowerKey = key.toLowerCase();
                 if (sensitiveKeys.some(sk => lowerKey.includes(sk))) {
-                    result[key] = '[REDACTED]';
+                    result[key] = '[NOT CAPTURED]';
+                }
+                else if (identifierKeys.some(identifier => lowerKey === identifier || lowerKey.endsWith(`_${identifier}`))) {
+                    result[key] = '[PSEUDONYMIZED BY QA INGESTION]';
                 }
                 else {
-                    result[key] = sanitize(val[key]);
+                    result[key] = sanitize(val[key], keyPath ? `${keyPath}.${key}` : key);
                 }
             }
             return result;
         }
-        return val;
+        if (typeof val === 'string' && /(^|\.)(url|href|from|to|referrer)$/i.test(keyPath))
+            return sanitizeUrl(val);
+        return typeof val === 'string' ? val.slice(0, 2_000) : val;
     };
     return sanitize(metadata);
 }

package/dist/index.d.ts

@@ -38,6 +38,51 @@ declare class TellannFrontendSDK {
     }): void;
     trackState(stateName: string, category?: string): void;
     trackTransition(fromState: string, toState: string, action?: string): void;
+    trackFlowInitialState(flowVersionId: string, stateKey: string): void;
+    trackFlowStateReached(flowVersionId: string, stateKey: string): void;
+    trackFlowTransition(flowVersionId: string, fromStateKey: string, toStateKey: string, action: string): void;
+    trackFlowTerminalState(flowVersionId: string, stateKey: string): void;
+    /**
+     * Explicit adapter for Zustand, MobX, custom Context, and other stores.
+     *
+     * Shape metadata (type, length, populated) always travels. Actual values are
+     * only attached while a QA run credential is present on the page and the run
+     * is not observation-only, and even then they are carried as *candidate*
+     * protected values: the browser observer and the ingestion API both classify
+     * and encrypt them before anything is persisted. Nothing raw is ever written
+     * to the generic telemetry wire.
+     */
+    trackClientState(store: string, key: string, previous: unknown, next: unknown): void;
+    /**
+     * Redux middleware. Records the action type, which top-level slice paths
+     * actually changed, and protected before/after values for those slices.
+     *
+     *   const store = configureStore({
+     *     reducer,
+     *     middleware: (get) => get().concat(TELLANN.createReduxMiddleware()),
+     *   });
+     */
+    createReduxMiddleware(): (store: {
+        getState(): unknown;
+    }) => (next: (action: unknown) => unknown) => (action: unknown) => unknown;
+    /**
+     * React Context adapter. Only providers explicitly identified and approved in
+     * the validated Flow instrumentation manifest should call this — there is no
+     * blanket interception of React internals, because that cannot be done
+     * reliably and would misreport what was actually captured.
+     *
+     *   useEffect(() => TELLANN.trackContextValue('AuthContext', 'user', value), [value]);
+     */
+    trackContextValue(providerName: string, key: string, value: unknown): void;
+    /**
+     * Wraps an approved `useState` setter so Flow-relevant state changes are
+     * recorded. Intended to be applied to the specific setters identified during
+     * static analysis, not to every setter in the application.
+     *
+     *   const [email, setEmail] = useState('');
+     *   const setTracked = TELLANN.trackStateSetter('CheckoutForm', 'email', setEmail, email);
+     */
+    trackStateSetter<T>(componentName: string, key: string, setter: (value: T) => void, current?: T): (value: T) => void;
     startWorkflow(workflowName: string): string;
     completeWorkflow(workflowId: string): void;
     failWorkflow(workflowId: string, reason?: string): void;

package/dist/index.js

@@ -1,6 +1,90 @@
 import { v4 as uuidv4 } from 'uuid';
 import { WorkflowTracker } from './workflow-tracker.js';
 import { setupAutoTrack, sanitizeMetadata } from './auto-track.js';
+const CLIENT_STATE_SECRET_KEY = /password|passwd|passcode|secret|token|authorization|cookie|session|auth|private.?key|cvv|cvc|card/i;
+/** Shape-only description; always safe to send regardless of environment. */
+function describeClientStateValue(value) {
+    return {
+        type: value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value,
+        length: typeof value === 'string' || Array.isArray(value) ? value.length : null,
+        populated: value !== null && value !== undefined && value !== '',
+    };
+}
+/**
+ * True only while a desktop QA run credential is present on the page. Outside a
+ * run — and in any observation-only run — client state values never leave the
+ * page at all.
+ */
+function qaRunActive() {
+    const run = globalThis.__TELLANN_RUN__;
+    return Boolean(run && run.runId && run.relayToken);
+}
+/**
+ * The local relay the desktop observer injected for this run, if any.
+ *
+ * While a guided run is active every event has to travel through the relay:
+ * only the relay attaches the run-ingestion credential, and the collector
+ * advances the Flow boundary solely for credentialed events. A
+ * `FLOW_INITIAL_STATE` flushed straight to the configured gateway is ingested
+ * as ordinary telemetry, so the run would sit at "Waiting for
+ * FLOW_INITIAL_STATE" no matter how many times the page emits it.
+ */
+function activeRunRelay() {
+    const run = globalThis.__TELLANN_RUN__;
+    if (!run || typeof run.runId !== 'string' || typeof run.relayToken !== 'string')
+        return null;
+    const endpoint = typeof run.relayEndpoint === 'string' ? run.relayEndpoint.replace(/\/$/, '') : '';
+    return endpoint ? { endpoint, token: run.relayToken } : null;
+}
+function serializeCandidate(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string')
+        return value.slice(0, 16_384);
+    try {
+        return JSON.stringify(value)?.slice(0, 16_384);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Attaches candidate protected values for the QA pipeline. These are proposals,
+ * not decisions: the browser observer re-derives a classification and the
+ * ingestion API applies the authoritative server-side floor before persisting.
+ * Anything whose key looks like a secret is dropped here as well, so a secret
+ * never leaves the page even as a candidate.
+ */
+function qaCandidateValues(key, previous, next) {
+    if (!qaRunActive() || CLIENT_STATE_SECRET_KEY.test(String(key)))
+        return {};
+    const previousValue = serializeCandidate(previous);
+    const nextValue = serializeCandidate(next);
+    if (previousValue === undefined && nextValue === undefined)
+        return {};
+    return {
+        qaProtectedCandidates: [
+            ...(previousValue === undefined ? [] : [{ keyPath: `clientState.${key}.previousValue`, value: previousValue }]),
+            ...(nextValue === undefined ? [] : [{ keyPath: `clientState.${key}.newValue`, value: nextValue }]),
+        ],
+    };
+}
+function safeState(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** Top-level slice keys whose reference actually changed. */
+function changedSlicePaths(before, after) {
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    return [...keys].filter((key) => before[key] !== after[key]);
+}
+function pickPaths(source, paths) {
+    const result = {};
+    for (const path of paths.slice(0, 50))
+        result[path] = source[path];
+    return result;
+}
 const MAX_EVENT_SIZE_BYTES = 32 * 1024; // 32 KB limit for standard events
 const MAX_REPLAY_SIZE_BYTES = 128 * 1024; // 128 KB limit for replay events (e.g. if eventType is a replay event)
 class TellannFrontendSDK {
@@ -64,6 +148,22 @@ class TellannFrontendSDK {
             }
             return;
         }
+        // Enforce the contract against the caller's payload before redaction. A
+        // multi-kilobyte value must not become an apparently valid tiny event just
+        // because the privacy layer replaced it with a marker.
+        try {
+            const rawPayload = JSON.stringify({ eventType, metadata });
+            const rawSize = typeof Blob !== 'undefined' ? new Blob([rawPayload]).size : rawPayload.length;
+            const rawLimit = eventType.includes('REPLAY') ? MAX_REPLAY_SIZE_BYTES : MAX_EVENT_SIZE_BYTES;
+            if (rawSize > rawLimit) {
+                console.error(`[Tellann] Event of type "${eventType}" discarded. Size (${rawSize} bytes) exceeds limit of ${rawLimit} bytes.`);
+                return;
+            }
+        }
+        catch (err) {
+            console.error('[Tellann] Failed to compute size of event, discarding', err);
+            return;
+        }
         // Apply privacy-by-default metadata sanitization
         const sanitizedMetadata = sanitizeMetadata(metadata);
         const event = {
@@ -134,6 +234,100 @@ class TellannFrontendSDK {
             action: action || 'NAVIGATE',
         });
     }
+    trackFlowInitialState(flowVersionId, stateKey) {
+        this.trackEvent('FLOW_INITIAL_STATE', { flowVersionId, stateKey });
+    }
+    trackFlowStateReached(flowVersionId, stateKey) {
+        this.trackEvent('FLOW_STATE_REACHED', { flowVersionId, stateKey });
+    }
+    trackFlowTransition(flowVersionId, fromStateKey, toStateKey, action) {
+        this.trackEvent('FLOW_TRANSITION', { flowVersionId, stateKey: toStateKey, fromStateKey, toStateKey, action });
+    }
+    trackFlowTerminalState(flowVersionId, stateKey) {
+        this.trackEvent('FLOW_TERMINAL_STATE', { flowVersionId, stateKey });
+    }
+    /**
+     * Explicit adapter for Zustand, MobX, custom Context, and other stores.
+     *
+     * Shape metadata (type, length, populated) always travels. Actual values are
+     * only attached while a QA run credential is present on the page and the run
+     * is not observation-only, and even then they are carried as *candidate*
+     * protected values: the browser observer and the ingestion API both classify
+     * and encrypt them before anything is persisted. Nothing raw is ever written
+     * to the generic telemetry wire.
+     */
+    trackClientState(store, key, previous, next) {
+        this.trackEvent('BUSINESS_EVENT', {
+            businessEventType: 'QA_CLIENT_STATE_MUTATION',
+            store: String(store).slice(0, 100),
+            key: String(key).slice(0, 200),
+            previous: describeClientStateValue(previous),
+            next: describeClientStateValue(next),
+            ...qaCandidateValues(key, previous, next),
+        });
+    }
+    /**
+     * Redux middleware. Records the action type, which top-level slice paths
+     * actually changed, and protected before/after values for those slices.
+     *
+     *   const store = configureStore({
+     *     reducer,
+     *     middleware: (get) => get().concat(TELLANN.createReduxMiddleware()),
+     *   });
+     */
+    createReduxMiddleware() {
+        const sdk = this;
+        return (store) => (next) => (action) => {
+            const before = safeState(store.getState());
+            const result = next(action);
+            const after = safeState(store.getState());
+            const type = String(action?.type ?? 'UNKNOWN_ACTION');
+            const changed = changedSlicePaths(before, after);
+            if (changed.length) {
+                sdk.trackEvent('BUSINESS_EVENT', {
+                    businessEventType: 'QA_CLIENT_STATE_MUTATION',
+                    store: 'redux',
+                    key: type.slice(0, 200),
+                    actionType: type.slice(0, 200),
+                    changedSlicePaths: changed.slice(0, 50),
+                    previous: describeClientStateValue(before),
+                    next: describeClientStateValue(after),
+                    ...qaCandidateValues(type, pickPaths(before, changed), pickPaths(after, changed)),
+                });
+            }
+            return result;
+        };
+    }
+    /**
+     * React Context adapter. Only providers explicitly identified and approved in
+     * the validated Flow instrumentation manifest should call this — there is no
+     * blanket interception of React internals, because that cannot be done
+     * reliably and would misreport what was actually captured.
+     *
+     *   useEffect(() => TELLANN.trackContextValue('AuthContext', 'user', value), [value]);
+     */
+    trackContextValue(providerName, key, value) {
+        this.trackClientState(`context:${providerName}`, key, undefined, value);
+    }
+    /**
+     * Wraps an approved `useState` setter so Flow-relevant state changes are
+     * recorded. Intended to be applied to the specific setters identified during
+     * static analysis, not to every setter in the application.
+     *
+     *   const [email, setEmail] = useState('');
+     *   const setTracked = TELLANN.trackStateSetter('CheckoutForm', 'email', setEmail, email);
+     */
+    trackStateSetter(componentName, key, setter, current) {
+        let previous = current;
+        return (value) => {
+            const resolved = typeof value === 'function'
+                ? value(previous)
+                : value;
+            this.trackClientState(`useState:${componentName}`, key, previous, resolved);
+            previous = resolved;
+            setter(resolved);
+        };
+    }
     startWorkflow(workflowName) {
         const id = this.workflowTracker.start(workflowName);
         this.trackEvent('WORKFLOW_STARTED', {
@@ -220,13 +414,21 @@ class TellannFrontendSDK {
                 console.error(`[Tellann] Batch payload size of ${payloadSize} bytes exceeds the 5 MB limit. Dropping batch.`);
                 return;
             }
+            const relay = activeRunRelay();
+            const target = relay ? relay.endpoint : this.config.endpoint;
             const headers = {
                 'Content-Type': 'application/json',
             };
-            if (this.config.apiKey) {
+            if (relay) {
+                headers.Authorization = `Bearer ${relay.token}`;
+            }
+            else if (this.config.apiKey) {
                 headers.Authorization = `Bearer ${this.config.apiKey}`;
             }
-            if (this.config.environmentId) {
+            // The relay re-derives the environment from the run correlation, and its
+            // CORS allow-list does not carry this header — sending it would fail the
+            // preflight and lose the batch.
+            if (!relay && this.config.environmentId) {
                 headers['x-tellann-environment-id'] = this.config.environmentId;
             }
             if (this.config.runId)
@@ -236,16 +438,16 @@ class TellannFrontendSDK {
             if (this.config.traceId)
                 headers['x-tellann-trace-id'] = this.config.traceId;
             // sendBeacon cannot set auth headers, so only use it for unauthenticated direct collector targets.
-            if (!this.config.apiKey && !this.config.environmentId && navigator.sendBeacon && typeof Blob !== 'undefined') {
+            if (!relay && !this.config.apiKey && !this.config.environmentId && navigator.sendBeacon && typeof Blob !== 'undefined') {
                 const blob = new Blob([payload], { type: 'application/json' });
-                const success = navigator.sendBeacon(`${this.config.endpoint}/v1/events/batch`, blob);
+                const success = navigator.sendBeacon(`${target}/v1/events/batch`, blob);
                 if (!success) {
                     throw new Error('sendBeacon returned false');
                 }
             }
             else {
                 // Fallback to fetch
-                await fetch(`${this.config.endpoint}/v1/events/batch`, {
+                await fetch(`${target}/v1/events/batch`, {
                     method: 'POST',
                     headers,
                     body: payload,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellann/frontend-sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Tellann browser telemetry and QA-run correlation SDK",
   "license": "UNLICENSED",
@@ -24,7 +24,8 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -45,6 +46,6 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc -w",
-    "test": "node --test dist/index.test.js"
+    "test": "tsc && node --test dist/index.test.js"
   }
 }