@thred-apps/thred-track 1.1.5 → 1.2.1

package/README.md

@@ -4,14 +4,14 @@ A modern TypeScript SDK for browser tracking and lead enrichment from ChatGPT re
 
 ## Features
 
-- 🎯 **ChatGPT Detection** - Automatic detection of visitors from ChatGPT
-- 🔒 **Browser Fingerprinting** - Privacy-friendly visitor identification
-- 📊 **Page View Tracking** - Anonymous 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
+- **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
 
 ## Installation
 
@@ -30,183 +30,155 @@ yarn add thred-track
 ### CDN (Script Tag)
 
 ```html
-<script src="https://unpkg.com/thred-track/dist/thred-track.umd.js?browserKey=YOUR_KEY"></script>
+<script src="https://cdn.thred.dev/thred-track.js?browserKey=YOUR_KEY"></script>
 ```
 
 ## Quick Start
 
-### Auto-Initialize (Script Tag)
+### Script Tag
 
-Add the script with your browser key, and it will auto-initialize:
+Drop the script onto your page with your browser key. That's it — everything is automatic:
 
 ```html
-<script src="./dist/thred-track.umd.js?browserKey=751fe47a-d4f5-496a-ba9c-fb298c281e8a"></script>
+<script src="https://cdn.thred.dev/thred-track.js?browserKey=YOUR_KEY"></script>
 ```
 
-The SDK will automatically:
-- Detect ChatGPT referrals
-- Generate browser fingerprint
-- Track page views
-- Monitor form submissions
-
-### Manual Initialization (Module)
+### Module Import
 
 ```typescript
 import { ThredSDK } from 'thred-track';
 
-const thred = new ThredSDK({
-  browserKey: 'your-browser-key',
-  debug: true,
-  autoInit: false, // Control initialization
-});
-
-// Initialize manually
-await thred.init();
+new ThredSDK({ browserKey: 'YOUR_KEY' });
 ```
 
-## API Reference
+No additional setup required. The SDK automatically:
 
-### Constructor Options
+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
-  baseUrl?: string;        // Optional: API base URL (default: https://api.thred.dev/v1)
   debug?: boolean;         // Optional: Enable debug logging (default: false)
   autoInit?: boolean;      // Optional: Auto-initialize on construction (default: true)
 }
 ```
 
-### Methods
+## Usage Examples
 
-#### `init(): Promise<void>`
+### Basic HTML Page
 
-Initialize the SDK manually (only needed if `autoInit: false`).
+```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>
 
-```typescript
-await thred.init();
+<script src="https://unpkg.com/thred-track/dist/thred-track.umd.js?browserKey=YOUR_KEY"></script>
 ```
 
-#### `trackPageView(): Promise<void>`
+The SDK automatically picks up the form and tracks submissions — no extra JavaScript needed.
 
-Manually track a page view event.
+### React
 
 ```typescript
-await thred.trackPageView();
-```
+import { useEffect, useRef } from 'react';
+import { ThredSDK } from 'thred-track';
 
-#### `identify(leadData: LeadData): Promise<void>`
+function App() {
+  const thredRef = useRef<ThredSDK | null>(null);
 
-Identify a user and enrich lead data.
+  useEffect(() => {
+    thredRef.current = new ThredSDK({
+      browserKey: process.env.REACT_APP_THRED_KEY!,
+      debug: process.env.NODE_ENV === 'development',
+    });
 
-```typescript
-await thred.identify({
-  name: 'John Doe',
-  email: 'john@example.com',
-  company: 'Acme Inc',
-});
-```
+    return () => thredRef.current?.destroy();
+  }, []);
 
-#### `trackFormSubmit(formData: FormData): Promise<void>`
+  return <YourApp />;
+}
+```
 
-Manually track a form submission.
+### Next.js
 
 ```typescript
-const form = document.getElementById('myForm');
-const formData = new FormData(form);
-await thred.trackFormSubmit(formData);
-```
-
-#### `getFingerprint(): string | null`
+'use client';
 
-Get the current browser fingerprint (synchronous).
+import { useEffect, useRef } from 'react';
+import { ThredSDK } from 'thred-track';
 
-```typescript
-const fingerprint = thred.getFingerprint();
-```
+export function ThredProvider({ children }: { children: React.ReactNode }) {
+  const thredRef = useRef<ThredSDK | null>(null);
 
-#### `isFromChatGPT(): boolean`
+  useEffect(() => {
+    thredRef.current = new ThredSDK({
+      browserKey: process.env.NEXT_PUBLIC_THRED_KEY!,
+    });
 
-Check if the visitor came from ChatGPT.
+    return () => thredRef.current?.destroy();
+  }, []);
 
-```typescript
-if (thred.isFromChatGPT()) {
-  console.log('Visitor from ChatGPT!');
+  return <>{children}</>;
 }
 ```
 
-#### `destroy(): void`
+### Delayed Initialization
 
-Clean up the SDK instance and remove event listeners.
+If you need to control when tracking starts (e.g., after user consent):
 
 ```typescript
-thred.destroy();
-```
-
-## Usage Examples
-
-### Basic Form Tracking
+import { ThredSDK } from 'thred-track';
 
-```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>
+const thred = new ThredSDK({
+  browserKey: 'YOUR_KEY',
+  autoInit: false,
+});
 
-<script src="./dist/thred-track.umd.js?browserKey=YOUR_KEY"></script>
+// Later, when ready:
+await thred.init();
 ```
 
-### Programmatic Tracking
+## Advanced API
 
-```typescript
-import { ThredSDK } from 'thred-track';
+These methods are available for advanced use cases but are **not required** for typical usage — the SDK handles everything automatically.
 
-const thred = new ThredSDK({
-  browserKey: 'your-key',
-  debug: true,
-});
+#### `identify(leadData: LeadData): Promise<void>`
 
-// Track custom events
-await thred.trackPageView();
+Manually identify a user outside of automatic form tracking (e.g., after OAuth or a custom flow):
 
-// Identify users manually
-document.querySelector('#signup-btn').addEventListener('click', async () => {
-  await thred.identify({
-    name: userName,
-    email: userEmail,
-    company: userCompany,
-  });
+```typescript
+await thred.identify({
+  name: 'John Doe',
+  email: 'john@example.com',
+  company: 'Acme Inc',
 });
 ```
 
-### React Integration
-
-```typescript
-import { useEffect, useState } from 'react';
-import { ThredSDK } from 'thred-track';
-
-function App() {
-  const [thred] = useState(() => new ThredSDK({
-    browserKey: process.env.REACT_APP_THRED_KEY,
-    debug: process.env.NODE_ENV === 'development',
-  }));
+#### `destroy(): void`
 
-  useEffect(() => {
-    return () => thred.destroy();
-  }, [thred]);
-
-  const handleSubmit = async (formData) => {
-    await thred.identify({
-      name: formData.name,
-      email: formData.email,
-      company: formData.company,
-    });
-  };
+Clean up the SDK instance and remove event listeners. Use this when unmounting in SPAs:
 
-  return <YourApp onSubmit={handleSubmit} />;
-}
+```typescript
+thred.destroy();
 ```
 
 ## Development
@@ -214,22 +186,11 @@ function App() {
 ### Setup
 
 ```bash
-# Install dependencies
 npm install
-
-# Build the SDK
 npm run build
-
-# Run in watch mode
-npm run dev
-
-# Run tests
+npm run dev       # Watch mode
 npm test
-
-# Lint code
 npm run lint
-
-# Format code
 npm run format
 ```
 
@@ -238,20 +199,18 @@ npm run format
 ```
 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
+│   ├── 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
-├── examples/           # Usage examples
-├── dist/               # Build output
-├── thred-track.js           # Original implementation (reference)
+│   ├── __tests__/         # Test files
+│   └── index.ts           # Main entry point
+├── dist/                  # Build output
 └── package.json
 ```
 
@@ -259,26 +218,20 @@ thred-track/
 
 The SDK builds to multiple formats:
 
-- **UMD** (`dist/thred-track.umd.js`) - For script tags
-- **CommonJS** (`dist/index.js`) - For Node.js
-- **ES Module** (`dist/index.esm.js`) - For bundlers
-- **TypeScript** (`dist/index.d.ts`) - Type definitions
+- **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
 
-Run the test suite:
-
 ```bash
 npm test
-
-# Watch mode
 npm run test:watch
 ```
 
 ### Local Testing
 
-Serve examples locally:
-
 ```bash
 npm run serve
 ```
@@ -287,11 +240,12 @@ Then open http://localhost:8080/basic.html?utm_source=chatgpt
 
 ## Configuration
 
-The SDK fetches configuration from your Thred API:
+The SDK fetches configuration from your Thred API automatically on init:
 
 ```json
 {
   "enabled": true,
+  "type": "custom",
   "formId": "form",
   "emailId": "email",
   "nameId": "name",
@@ -300,6 +254,8 @@ The SDK fetches configuration from your Thred API:
 }
 ```
 
+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)
@@ -341,10 +297,6 @@ import type {
 
 MIT
 
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.
-
 ## Support
 
 For questions or issues, please open a GitHub issue or contact support@thred.dev.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thred-apps/thred-track",
-  "version": "1.1.5",
+  "version": "1.2.1",
   "description": "Browser SDK for lead tracking and enrichment from ChatGPT referrals",
   "type": "module",
   "main": "dist/index.js",