@thred-apps/thred-track 1.2.1 → 1.2.3

package/README.md

@@ -1,106 +1,43 @@
 # Thred SDK
 
-A modern TypeScript SDK for browser tracking and lead enrichment from ChatGPT referrals.
-
-## Features
-
-- **ChatGPT Detection** - Automatic detection of visitors from ChatGPT
-- **Browser Fingerprinting** - Privacy-friendly visitor identification
-- **Page View Tracking** - Automatic page view analytics
-- **Form Tracking** - Automatic form submission tracking
-- **Lead Enrichment** - Capture and enrich lead data
-- **Zero Dependencies** - Lightweight with no external dependencies
-- **Multiple Formats** - UMD, CommonJS, and ES modules
-- **TypeScript Support** - Full TypeScript definitions included
+Automatic browser tracking and lead enrichment for ChatGPT referrals.
 
 ## Installation
 
-### NPM
-
-```bash
-npm install thred-track
-```
-
-### Yarn
-
-```bash
-yarn add thred-track
-```
-
-### CDN (Script Tag)
+### Script Tag
 
 ```html
 <script src="https://cdn.thred.dev/thred-track.js?browserKey=YOUR_KEY"></script>
 ```
 
-## Quick Start
-
-### Script Tag
-
-Drop the script onto your page with your browser key. That's it — everything is automatic:
+### NPM
 
-```html
-<script src="https://cdn.thred.dev/thred-track.js?browserKey=YOUR_KEY"></script>
+```bash
+npm install @thred-apps/thred-track
 ```
 
-### Module Import
-
 ```typescript
-import { ThredSDK } from 'thred-track';
+import { ThredSDK } from '@thred-apps/thred-track';
 
 new ThredSDK({ browserKey: 'YOUR_KEY' });
 ```
 
-No additional setup required. The SDK automatically:
-
-1. Detects ChatGPT referrals via UTM parameters
-2. Generates a browser fingerprint
-3. Tracks page views for ChatGPT visitors
-4. Monitors and captures form submissions based on your API config
-
-## What Happens on Initialization
-
-When the SDK initializes, it follows the same flow as the original script:
-
-1. **Fetches config** from the Thred API using your `browserKey`
-2. **Checks eligibility** — tracking only runs if the config says `enabled: true` and the visitor has a ChatGPT session or arrived via ChatGPT UTM
-3. **Tracks the page view** automatically for ChatGPT visitors
-4. **Sets up form tracking** — either injecting fingerprints into hosted form links, or attaching submit listeners to your form (based on config `type`)
-
-All of this happens without any manual method calls.
-
-## Constructor Options
-
-```typescript
-interface ThredOptions {
-  browserKey: string;      // Required: Your Thred browser key
-  debug?: boolean;         // Optional: Enable debug logging (default: false)
-  autoInit?: boolean;      // Optional: Auto-initialize on construction (default: true)
-}
-```
-
-## Usage Examples
-
-### Basic HTML Page
+That's it. The SDK automatically:
 
-```html
-<form id="form">
-  <input type="text" name="name" required>
-  <input type="email" name="email" required>
-  <input type="text" name="company">
-  <button type="submit">Submit</button>
-</form>
+- Detects ChatGPT referrals
+- Fingerprints the visitor
+- Tracks page views
+- Captures form submissions
 
-<script src="https://unpkg.com/thred-track/dist/thred-track.umd.js?browserKey=YOUR_KEY"></script>
-```
+No manual method calls needed.
 
-The SDK automatically picks up the form and tracks submissions — no extra JavaScript needed.
+## Framework Examples
 
 ### React
 
 ```typescript
 import { useEffect, useRef } from 'react';
-import { ThredSDK } from 'thred-track';
+import { ThredSDK } from '@thred-apps/thred-track';
 
 function App() {
   const thredRef = useRef<ThredSDK | null>(null);
@@ -108,9 +45,7 @@ function App() {
   useEffect(() => {
     thredRef.current = new ThredSDK({
       browserKey: process.env.REACT_APP_THRED_KEY!,
-      debug: process.env.NODE_ENV === 'development',
     });
-
     return () => thredRef.current?.destroy();
   }, []);
 
@@ -124,7 +59,7 @@ function App() {
 'use client';
 
 import { useEffect, useRef } from 'react';
-import { ThredSDK } from 'thred-track';
+import { ThredSDK } from '@thred-apps/thred-track';
 
 export function ThredProvider({ children }: { children: React.ReactNode }) {
   const thredRef = useRef<ThredSDK | null>(null);
@@ -133,7 +68,6 @@ export function ThredProvider({ children }: { children: React.ReactNode }) {
     thredRef.current = new ThredSDK({
       browserKey: process.env.NEXT_PUBLIC_THRED_KEY!,
     });
-
     return () => thredRef.current?.destroy();
   }, []);
 
@@ -141,162 +75,17 @@ export function ThredProvider({ children }: { children: React.ReactNode }) {
 }
 ```
 
-### Delayed Initialization
-
-If you need to control when tracking starts (e.g., after user consent):
-
-```typescript
-import { ThredSDK } from 'thred-track';
-
-const thred = new ThredSDK({
-  browserKey: 'YOUR_KEY',
-  autoInit: false,
-});
-
-// Later, when ready:
-await thred.init();
-```
-
-## Advanced API
-
-These methods are available for advanced use cases but are **not required** for typical usage — the SDK handles everything automatically.
-
-#### `identify(leadData: LeadData): Promise<void>`
-
-Manually identify a user outside of automatic form tracking (e.g., after OAuth or a custom flow):
-
-```typescript
-await thred.identify({
-  name: 'John Doe',
-  email: 'john@example.com',
-  company: 'Acme Inc',
-});
-```
-
-#### `destroy(): void`
-
-Clean up the SDK instance and remove event listeners. Use this when unmounting in SPAs:
-
-```typescript
-thred.destroy();
-```
-
-## Development
-
-### Setup
-
-```bash
-npm install
-npm run build
-npm run dev       # Watch mode
-npm test
-npm run lint
-npm run format
-```
-
-### Project Structure
-
-```
-thred-track/
-├── src/
-│   ├── core/              # Core SDK functionality
-│   │   ├── api.ts         # API client
-│   │   ├── fingerprint.ts # Fingerprint management
-│   │   └── tracker.ts     # Event tracking
-│   ├── utils/             # Utility functions
-│   │   ├── detector.ts    # ChatGPT detection
-│   │   └── logger.ts      # Logging utility
-│   ├── types/             # TypeScript definitions
-│   │   └── index.ts
-│   ├── __tests__/         # Test files
-│   └── index.ts           # Main entry point
-├── dist/                  # Build output
-└── package.json
-```
-
-### Building
-
-The SDK builds to multiple formats:
-
-- **UMD** (`dist/thred-track.umd.js`) — For script tags
-- **CommonJS** (`dist/index.js`) — For Node.js / bundlers
-- **ES Module** (`dist/index.esm.js`) — For modern bundlers
-- **TypeScript** (`dist/index.d.ts`) — Type definitions
-
-### Testing
-
-```bash
-npm test
-npm run test:watch
-```
-
-### Local Testing
-
-```bash
-npm run serve
-```
-
-Then open http://localhost:8080/basic.html?utm_source=chatgpt
-
-## Configuration
-
-The SDK fetches configuration from your Thred API automatically on init:
-
-```json
-{
-  "enabled": true,
-  "type": "custom",
-  "formId": "form",
-  "emailId": "email",
-  "nameId": "name",
-  "companyId": "company",
-  "hasChatSession": true
-}
-```
-
-This config controls which form to track, which fields to extract, and whether the visitor has an existing ChatGPT session.
-
 ## Privacy & Security
 
-- Only tracks visitors from ChatGPT (opt-in by source)
-- Uses browser fingerprinting (no cookies required)
-- All tracking controlled by API configuration
+- Only tracks visitors arriving from ChatGPT
+- Browser fingerprinting — no cookies required
 - No PII collected without explicit user submission
-- Compliant with privacy regulations (GDPR, CCPA)
+- GDPR and CCPA compliant
 
 ## Browser Support
 
-- Chrome/Edge (latest)
-- Firefox (latest)
-- Safari (latest)
-- Opera (latest)
-
-Requires ES2015+ support.
-
-## API Endpoints
-
-- **Config**: `GET /v1/config?browserKey={key}`
-- **Page View**: `POST /v1/events/page-view?browserKey={key}`
-- **Enrich**: `POST /v1/customers/enrich?browserKey={key}`
-
-## TypeScript
-
-Full TypeScript support with exported types:
-
-```typescript
-import type {
-  ThredOptions,
-  ThredConfig,
-  LeadData,
-  PageViewPayload,
-  EnrichPayload,
-} from 'thred-track';
-```
+Chrome, Firefox, Safari, Edge (latest versions). Requires ES2015+.
 
 ## License
 
 MIT
-
-## Support
-
-For questions or issues, please open a GitHub issue or contact support@thred.dev.

package/dist/core/tracker.d.ts

@@ -8,7 +8,16 @@ export declare class Tracker {
     private logger;
     private config;
     private formObserver;
+    private lastTrackedUrl;
+    private popstateHandler;
+    private originalPushState;
+    private originalReplaceState;
     constructor(api: ThredAPI, fingerprint: FingerprintManager, logger: Logger);
+    /**
+     * Resolves when the DOM is interactive (document.body exists).
+     * Safe to call whether the script is in <head> or <body>.
+     */
+    private domReady;
     /**
      * Initialize tracker with config
      */
@@ -25,6 +34,11 @@ export declare class Tracker {
      * Identify user and enrich lead data
      */
     identify(leadData: LeadData): Promise<void>;
+    /**
+     * Track page views on SPA route changes by patching pushState/replaceState
+     * and listening for popstate.
+     */
+    private setupRouteTracking;
     /**
      * Setup automatic form tracking
      */

package/dist/core/tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/core/tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,QAAQ,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,qBAAa,OAAO;IAClB,OAAO,CAAC,GAAG,CAAW;IACtB,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,YAAY,CAAiC;gBAGnD,GAAG,EAAE,QAAQ,EACb,WAAW,EAAE,kBAAkB,EAC/B,MAAM,EAAE,MAAM;IAOhB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B3B;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBpC;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BxD;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsGzB;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAOlC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAuBjC;;OAEG;IACH,OAAO,IAAI,IAAI;CAMhB"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/core/tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,QAAQ,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,qBAAa,OAAO;IAClB,OAAO,CAAC,GAAG,CAAW;IACtB,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,oBAAoB,CAA4C;gBAGtE,GAAG,EAAE,QAAQ,EACb,WAAW,EAAE,kBAAkB,EAC/B,MAAM,EAAE,MAAM;IAOhB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAUhB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC3B;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBpC;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BxD;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjD;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsGzB;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAOlC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAuBjC;;OAEG;IACH,OAAO,IAAI,IAAI;CAqBhB"}

package/dist/index.esm.js

@@ -258,10 +258,28 @@ class Tracker {
     constructor(api, fingerprint, logger) {
         this.config = null;
         this.formObserver = null;
+        this.lastTrackedUrl = null;
+        this.popstateHandler = null;
+        this.originalPushState = null;
+        this.originalReplaceState = null;
         this.api = api;
         this.fingerprint = fingerprint;
         this.logger = logger;
     }
+    /**
+     * Resolves when the DOM is interactive (document.body exists).
+     * Safe to call whether the script is in <head> or <body>.
+     */
+    domReady() {
+        return new Promise((resolve) => {
+            if (document.readyState === 'loading') {
+                document.addEventListener('DOMContentLoaded', () => resolve(), { once: true });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
     /**
      * Initialize tracker with config
      */
@@ -283,13 +301,17 @@ class Tracker {
                 this.logger.log('No chat session for this fingerprint - exiting');
                 return;
             }
-            // Only track page view if UTM is from ChatGPT
+            // Track initial page view
             if (isFromChatGPT()) {
                 yield this.trackPageView();
             }
             else {
                 this.logger.log('UTM not from ChatGPT - skipping page view');
             }
+            // Track SPA route changes (only needs window/history — safe before DOM ready)
+            this.setupRouteTracking();
+            // Wait for document.body to exist before touching the DOM
+            yield this.domReady();
             // Setup form tracking
             this.setupFormTracking();
         });
@@ -358,6 +380,35 @@ class Tracker {
             });
         });
     }
+    /**
+     * Track page views on SPA route changes by patching pushState/replaceState
+     * and listening for popstate.
+     */
+    setupRouteTracking() {
+        if (typeof window === 'undefined')
+            return;
+        this.lastTrackedUrl = window.location.href;
+        const onRouteChange = () => {
+            const currentUrl = window.location.href;
+            if (currentUrl === this.lastTrackedUrl)
+                return;
+            this.lastTrackedUrl = currentUrl;
+            this.logger.log('Route change detected:', currentUrl);
+            this.trackPageView();
+        };
+        this.popstateHandler = onRouteChange;
+        window.addEventListener('popstate', this.popstateHandler);
+        this.originalPushState = history.pushState.bind(history);
+        this.originalReplaceState = history.replaceState.bind(history);
+        history.pushState = (...args) => {
+            this.originalPushState(...args);
+            onRouteChange();
+        };
+        history.replaceState = (...args) => {
+            this.originalReplaceState(...args);
+            onRouteChange();
+        };
+    }
     /**
      * Setup automatic form tracking
      */
@@ -485,6 +536,18 @@ class Tracker {
             this.formObserver.disconnect();
             this.formObserver = null;
         }
+        if (this.popstateHandler) {
+            window.removeEventListener('popstate', this.popstateHandler);
+            this.popstateHandler = null;
+        }
+        if (this.originalPushState) {
+            history.pushState = this.originalPushState;
+            this.originalPushState = null;
+        }
+        if (this.originalReplaceState) {
+            history.replaceState = this.originalReplaceState;
+            this.originalReplaceState = null;
+        }
     }
 }