@thred-apps/thred-track 1.0.3

package/LICENSE

@@ -0,0 +1,18 @@
+Proprietary License
+
+Copyright (c) 2026 Thred. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the 
+proprietary property of Thred.
+
+NOTICE: All information contained herein is, and remains the property of 
+Thred and its suppliers, if any. The intellectual and technical concepts 
+contained herein are proprietary to Thred and its suppliers and may be 
+covered by U.S. and Foreign Patents, patents in process, and are protected 
+by trade secret or copyright law.
+
+Dissemination of this information or reproduction of this material is 
+strictly forbidden unless prior written permission is obtained from Thred.
+
+Unauthorized copying, modification, distribution, or use of this software, 
+via any medium, is strictly prohibited.

package/README.md

@@ -0,0 +1,349 @@
+# 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** - 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
+
+## Installation
+
+### NPM
+
+```bash
+npm install thred-track
+```
+
+### Yarn
+
+```bash
+yarn add thred-track
+```
+
+### CDN (Script Tag)
+
+```html
+<script src="https://unpkg.com/thred-track/dist/thred-track.umd.js?browserKey=YOUR_KEY"></script>
+```
+
+## Quick Start
+
+### Auto-Initialize (Script Tag)
+
+Add the script with your browser key, and it will auto-initialize:
+
+```html
+<script src="./dist/thred-track.umd.js?browserKey=751fe47a-d4f5-496a-ba9c-fb298c281e8a"></script>
+```
+
+The SDK will automatically:
+- Detect ChatGPT referrals
+- Generate browser fingerprint
+- Track page views
+- Monitor form submissions
+
+### Manual Initialization (Module)
+
+```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();
+```
+
+## API Reference
+
+### 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
+
+#### `init(): Promise<void>`
+
+Initialize the SDK manually (only needed if `autoInit: false`).
+
+```typescript
+await thred.init();
+```
+
+#### `trackPageView(): Promise<void>`
+
+Manually track a page view event.
+
+```typescript
+await thred.trackPageView();
+```
+
+#### `identify(leadData: LeadData): Promise<void>`
+
+Identify a user and enrich lead data.
+
+```typescript
+await thred.identify({
+  name: 'John Doe',
+  email: 'john@example.com',
+  company: 'Acme Inc',
+});
+```
+
+#### `trackFormSubmit(formData: FormData): Promise<void>`
+
+Manually track a form submission.
+
+```typescript
+const form = document.getElementById('myForm');
+const formData = new FormData(form);
+await thred.trackFormSubmit(formData);
+```
+
+#### `getFingerprint(): string | null`
+
+Get the current browser fingerprint (synchronous).
+
+```typescript
+const fingerprint = thred.getFingerprint();
+```
+
+#### `isFromChatGPT(): boolean`
+
+Check if the visitor came from ChatGPT.
+
+```typescript
+if (thred.isFromChatGPT()) {
+  console.log('Visitor from ChatGPT!');
+}
+```
+
+#### `destroy(): void`
+
+Clean up the SDK instance and remove event listeners.
+
+```typescript
+thred.destroy();
+```
+
+## Usage Examples
+
+### Basic Form Tracking
+
+```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>
+
+<script src="./dist/thred-track.umd.js?browserKey=YOUR_KEY"></script>
+```
+
+### Programmatic Tracking
+
+```typescript
+import { ThredSDK } from 'thred-track';
+
+const thred = new ThredSDK({
+  browserKey: 'your-key',
+  debug: true,
+});
+
+// Track custom events
+await thred.trackPageView();
+
+// Identify users manually
+document.querySelector('#signup-btn').addEventListener('click', async () => {
+  await thred.identify({
+    name: userName,
+    email: userEmail,
+    company: userCompany,
+  });
+});
+```
+
+### 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',
+  }));
+
+  useEffect(() => {
+    return () => thred.destroy();
+  }, [thred]);
+
+  const handleSubmit = async (formData) => {
+    await thred.identify({
+      name: formData.name,
+      email: formData.email,
+      company: formData.company,
+    });
+  };
+
+  return <YourApp onSubmit={handleSubmit} />;
+}
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK
+npm run build
+
+# Run in watch mode
+npm run dev
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+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
+├── examples/           # Usage examples
+├── dist/               # Build output
+├── thred-track.js           # Original implementation (reference)
+└── 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
+- **ES Module** (`dist/index.esm.js`) - For 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
+```
+
+Then open http://localhost:8080/basic.html?utm_source=chatgpt
+
+## Configuration
+
+The SDK fetches configuration from your Thred API:
+
+```json
+{
+  "enabled": true,
+  "formId": "form",
+  "emailId": "email",
+  "nameId": "name",
+  "companyId": "company"
+}
+```
+
+## Privacy & Security
+
+- Only tracks visitors from ChatGPT (opt-in by source)
+- Uses browser fingerprinting (no cookies required)
+- All tracking controlled by API configuration
+- No PII collected without explicit user submission
+- Compliant with privacy regulations (GDPR, CCPA)
+
+## 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';
+```
+
+## License
+
+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/dist/core/api.d.ts

@@ -0,0 +1,21 @@
+import type { ThredConfig, PageViewPayload, EnrichPayload } from '../types';
+import { Logger } from '../utils/logger';
+export declare class ThredAPI {
+    private baseUrl;
+    private browserKey;
+    private logger;
+    constructor(baseUrl: string, browserKey: string, logger: Logger);
+    /**
+     * Fetch configuration from API
+     */
+    fetchConfig(): Promise<ThredConfig | null>;
+    /**
+     * Send page view event
+     */
+    trackPageView(payload: PageViewPayload): Promise<void>;
+    /**
+     * Send lead enrichment data
+     */
+    enrichLead(payload: EnrichPayload): Promise<void>;
+}
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/core/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,aAAa,EACd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAM/D;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IA0BhD;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB5D;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAuBxD"}

package/dist/core/fingerprint.d.ts

@@ -0,0 +1,21 @@
+import { Logger } from '../utils/logger';
+export declare class FingerprintManager {
+    private fingerprint;
+    private logger;
+    private promise;
+    constructor(logger: Logger);
+    /**
+     * Get or generate fingerprint
+     */
+    getFingerprint(): Promise<string | null>;
+    private generateFingerprint;
+    /**
+     * Get cached fingerprint (synchronous)
+     */
+    getCachedFingerprint(): string | null;
+    /**
+     * Clear fingerprint cache
+     */
+    clear(): void;
+}
+//# sourceMappingURL=fingerprint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/core/fingerprint.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAOzC,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAuC;gBAE1C,MAAM,EAAE,MAAM;IAI1B;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YA2BhC,mBAAmB;IAyBjC;;OAEG;IACH,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,KAAK;CAON"}

package/dist/core/tracker.d.ts

@@ -0,0 +1,37 @@
+import type { LeadData } from '../types';
+import { Logger } from '../utils/logger';
+import { ThredAPI } from './api';
+import { FingerprintManager } from './fingerprint';
+export declare class Tracker {
+    private api;
+    private fingerprint;
+    private logger;
+    private config;
+    private formObserver;
+    constructor(api: ThredAPI, fingerprint: FingerprintManager, logger: Logger);
+    /**
+     * Initialize tracker with config
+     */
+    init(): Promise<void>;
+    /**
+     * Track page view event
+     */
+    trackPageView(): Promise<void>;
+    /**
+     * Track form submission and enrich lead
+     */
+    trackFormSubmit(formData: FormData): Promise<void>;
+    /**
+     * Identify user and enrich lead data
+     */
+    identify(leadData: LeadData): Promise<void>;
+    /**
+     * Setup automatic form tracking
+     */
+    private setupFormTracking;
+    /**
+     * Cleanup tracker
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=tracker.d.ts.map

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

@@ -0,0 +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;AACzC,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;IAe3B;;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;IA4FzB;;OAEG;IACH,OAAO,IAAI,IAAI;CAMhB"}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Thred SDK - Browser tracking and lead enrichment
+ */
+import type { ThredOptions, ThredSDK as IThredSDK, LeadData } from './types';
+export * from './types';
+export declare class ThredSDK implements IThredSDK {
+    private options;
+    private logger;
+    private fingerprint;
+    private api;
+    private tracker;
+    private initialized;
+    constructor(options: ThredOptions);
+    /**
+     * Initialize the SDK
+     */
+    init(): Promise<void>;
+    /**
+     * Check if visitor is from ChatGPT
+     */
+    isFromChatGPT(): boolean;
+    /**
+     * Track page view
+     */
+    trackPageView(): Promise<void>;
+    /**
+     * Track form submission
+     */
+    trackFormSubmit(formData: FormData): Promise<void>;
+    /**
+     * Identify user with lead data
+     */
+    identify(leadData: LeadData): Promise<void>;
+    /**
+     * Get current fingerprint
+     */
+    getFingerprint(): string | null;
+    /**
+     * Destroy SDK instance and cleanup
+     */
+    destroy(): void;
+}
+export default ThredSDK;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,IAAI,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAO7E,cAAc,SAAS,CAAC;AAIxB,qBAAa,QAAS,YAAW,SAAS;IACxC,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,GAAG,CAAW;IACtB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,EAAE,YAAY;IAsBjC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB3B;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,OAAO,IAAI,IAAI;CAMhB;AAaD,eAAe,QAAQ,CAAC"}