@behindthescenes/analytics 0.0.9 → 0.0.11

package/docs/api-reference.md

@@ -0,0 +1,498 @@
+# API Reference
+
+Complete reference for the BTS Analytics SDK.
+
+## Core Functions
+
+### `createBTSAnalytics(init)`
+
+Creates and initializes a new BTS Analytics instance.
+
+```typescript
+import { createBTSAnalytics } from "@behindthescenes/analytics";
+
+const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  autoPageviews: true,
+  debug: false,
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `siteKey` | `string` | Yes | Your public site key from BTS |
+| `endpoint` | `string` | No | Override the default endpoint |
+| `autoPageviews` | `boolean` | No | Enable automatic page view tracking (default: `true`) |
+| `autoTrack` | `boolean \| object` | No | Fine-grained auto-tracking control |
+| `debug` | `boolean` | No | Enable debug logging (default: `false`) |
+| `flushIntervalMs` | `number` | No | Event flush interval in ms (default: `300`) |
+| `googleAnalytics` | `boolean \| object` | No | GA4 integration settings |
+| `requestHeaders` | `HeadersInit \| function` | No | Custom request headers |
+
+**AutoTrack Configuration:**
+
+```typescript
+autoTrack: {
+  pageviews: true,        // Initial page_view + SPA navigation
+  history: true,          // pushState/replaceState hooks
+  outboundLinks: true,    // External link clicks
+  buttonClicks: true,     // Button interactions
+  formSubmissions: true,  // Form submit events
+  search: true,           // GET search forms
+  viewContent: true       // IntersectionObserver content views
+}
+```
+
+---
+
+## Methods
+
+### `track(eventName, properties?)`
+
+Track a custom event.
+
+```typescript
+analytics.track("video_played", {
+  videoId: "intro-01",
+  duration: 120,
+  autoplay: false,
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `eventName` | `string` | Yes | Name of the event |
+| `properties` | `object` | No | Additional event properties |
+
+---
+
+### `trackStandard(eventName, properties?)`
+
+Track a predefined standard event.
+
+```typescript
+analytics.trackStandard("purchase", {
+  orderId: "order_123",
+  monetaryValue: 149,
+  currency: "USD",
+});
+```
+
+**Standard Events:**
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `page_view` | Page | Page viewed |
+| `view_content` | Engagement | Content viewed |
+| `search` | Engagement | Search performed |
+| `lead` | Conversion | Lead captured |
+| `sign_up` | Conversion | User registered |
+| `begin_checkout` | Conversion | Checkout started |
+| `add_payment_info` | Conversion | Payment info added |
+| `purchase` | Conversion | Purchase completed |
+| `outbound_click` | Engagement | External link clicked |
+| `button_click` | Engagement | Button clicked |
+| `form_submit` | Engagement | Form submitted |
+
+**Legacy Aliases:**
+
+| Legacy Name | Maps To |
+|-------------|---------|
+| `$pageview` | `page_view` |
+| `checkout_started` | `begin_checkout` |
+| `lead_capture` | `lead` |
+| `purchase_completed` | `purchase` |
+| `registration_complete` | `sign_up` |
+
+---
+
+### `identify(userId, traits?)`
+
+Associate events with a known user.
+
+```typescript
+analytics.identify("user_123", {
+  email: "fan@example.com",
+  name: "John Doe",
+  plan: "pro",
+  createdAt: "2024-01-15",
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `userId` | `string` | Yes | Unique user identifier |
+| `traits` | `object` | No | User attributes |
+
+---
+
+### `page(path?)`
+
+Manually trigger a page view event.
+
+```typescript
+// Use current URL
+analytics.page();
+
+// Specify path
+analytics.page("/pricing");
+
+// Include query params
+analytics.page("/pricing?plan=pro");
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | `string` | No | Page path (defaults to current path) |
+
+---
+
+### `startFunnel(entryPath?)`
+
+Start a cross-site attribution journey.
+
+```typescript
+const { journeyId, journeyToken, expiresAt } = await analytics.startFunnel("/landing");
+
+// Use journeyToken to decorate URLs
+const checkoutUrl = analytics.decorateUrl(
+  "https://behindthescenes.com/checkout",
+  journeyToken,
+);
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `entryPath` | `string` | No | Entry point path |
+
+**Returns:** `Promise<{ journeyId: string; journeyToken: string; expiresAt: number }>`
+
+---
+
+### `decorateUrl(url, journeyToken?)`
+
+Append site key and journey token to a BTS URL.
+
+```typescript
+const checkoutUrl = analytics.decorateUrl(
+  "https://behindthescenes.com/checkout",
+  journeyToken,
+);
+// Result: https://behindthescenes.com/checkout?bts_site=xxx&bts_jt=yyy
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | `string` | Yes | Base URL to decorate |
+| `journeyToken` | `string` | No | Journey token (uses persisted if omitted) |
+
+**Returns:** `string` - Decorated URL
+
+---
+
+### `getPersistedJourneyToken()`
+
+Get the currently stored journey token.
+
+```typescript
+const token = analytics.getPersistedJourneyToken();
+if (token) {
+  const url = analytics.decorateUrl("https://behindthescenes.com/join", token);
+}
+```
+
+**Returns:** `string | null` - Journey token or null if none exists
+
+---
+
+### `notifyHandoff(journeyToken, context?)`
+
+Notify BTS of a journey handoff event.
+
+```typescript
+await analytics.notifyHandoff(journeyToken, {
+  source: "external_landing_page",
+  campaign: "summer_2024",
+  customValue: 100,
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `journeyToken` | `string` | Yes | Journey token |
+| `context` | `object` | No | Additional handoff context |
+
+---
+
+### `submitContactForm(input)`
+
+Submit a contact form to GoHighLevel.
+
+```typescript
+await analytics.submitContactForm({
+  locationId: "your-ghl-location-id",
+  email: "fan@example.com",
+  subject: "Partnership enquiry",
+  body: "Tell us more about working together.",
+  name: "Jane Smith",
+  phone: "+1234567890",
+  source: "website_contact",
+  tags: ["partnership", "high-value"],
+  customFields: {
+    company: "Acme Inc",
+    industry: "Technology",
+  },
+  metadata: {
+    page: window.location.pathname,
+    referrer: document.referrer,
+  },
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `locationId` | `string` | Yes | GoHighLevel location ID |
+| `email` | `string` | No* | Contact email (required if no phone) |
+| `phone` | `string` | No* | Contact phone (required if no email) |
+| `subject` | `string` | No | Subject line |
+| `body` | `string` | No | Message body |
+| `name` | `string` | No | Full name |
+| `firstName` | `string` | No | First name |
+| `lastName` | `string` | No | Last name |
+| `source` | `string` | No | Lead source (default: `behind_the_scenes`) |
+| `tags` | `string[]` | No | GHL tags |
+| `customFields` | `object` | No | GHL custom fields |
+| `metadata` | `object` | No | BTS metadata (stored as `bts_meta_<key>`) |
+
+**Returns:** `Promise<{ ok: boolean; data?: unknown }>`
+
+---
+
+### `flushNow()`
+
+Immediately flush the event queue.
+
+```typescript
+// Track event and ensure it's sent before navigation
+analytics.track("checkout_cta_clicked", { placement: "hero" });
+await analytics.flushNow();
+window.location.href = "/checkout";
+```
+
+**Returns:** `Promise<void>`
+
+---
+
+### `listStandardEvents()`
+
+Get the list of supported standard event names.
+
+```typescript
+const events = analytics.listStandardEvents();
+// ["page_view", "view_content", "search", "lead", "sign_up", ...]
+```
+
+**Returns:** `string[]` - Array of standard event names
+
+---
+
+### `destroy()`
+
+Clean up the analytics instance.
+
+```typescript
+// When unmounting a component or navigating away
+analytics.destroy();
+```
+
+This method:
+- Removes all event listeners
+- Disconnects observers
+- Flushes any pending events
+- Prevents further tracking
+
+---
+
+## Types
+
+### `BTSAnalyticsInit`
+
+Initialization options type.
+
+```typescript
+type BTSAnalyticsInit = {
+  siteKey: string;
+  endpoint?: string;
+  autoPageviews?: boolean;
+  autoTrack?: boolean | Partial<AutoTrackConfig>;
+  debug?: boolean;
+  flushIntervalMs?: number;
+  googleAnalytics?: boolean | {
+    loadTag?: boolean;
+    measurementId?: string;
+  };
+  requestHeaders?: BTSAnalyticsRequestHeaders;
+};
+```
+
+### `BTSAnalyticsStandardEventName`
+
+Standard event name union type.
+
+```typescript
+type BTSAnalyticsStandardEventName =
+  | "page_view"
+  | "view_content"
+  | "search"
+  | "lead"
+  | "sign_up"
+  | "begin_checkout"
+  | "add_payment_info"
+  | "purchase"
+  | "outbound_click"
+  | "button_click"
+  | "form_submit";
+```
+
+### `BTSAnalyticsEventType`
+
+Event type classification.
+
+```typescript
+type BTSAnalyticsEventType = "page_view" | "custom" | "identify" | "conversion";
+```
+
+### `BTSAnalyticsContactFormInput`
+
+Contact form input type.
+
+```typescript
+type BTSAnalyticsContactFormInput = {
+  locationId: string;
+  email?: string;
+  phone?: string;
+  subject?: string;
+  body?: string;
+  name?: string;
+  firstName?: string;
+  lastName?: string;
+  source?: string;
+  tags?: string[];
+  customFields?: Record<string, string | number | boolean>;
+  metadata?: Record<string, unknown>;
+};
+```
+
+### `BTSAnalyticsRequestContext`
+
+Context passed to request headers callback.
+
+```typescript
+type BTSAnalyticsRequestContext = {
+  body: unknown;
+  bodyText: string;
+  endpoint: string;
+  headers: Record<string, string>;
+  path: string;
+  siteKey: string;
+  url: string;
+};
+```
+
+---
+
+## HTML Data Attributes
+
+Use these data attributes for automatic tracking:
+
+### Content View Tracking
+
+```html
+<article
+  data-bts-view-content="offer_123"
+  data-bts-content-type="offer"
+  data-bts-content-title="Creator Accelerator"
+>
+  Content here
+</article>
+```
+
+**Attributes:**
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-bts-view-content` | Content identifier (required) |
+| `data-bts-content-type` | Type of content (e.g., "offer", "video", "post") |
+| `data-bts-content-title` | Human-readable title |
+| `data-bts-content-id` | Alternative content ID |
+
+### Click Tracking
+
+```html
+<button data-bts-track-click>Track this button</button>
+```
+
+**Attributes:**
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-bts-track-click` | Mark element for click tracking |
+
+---
+
+## Auto-Tracked Events
+
+Events captured automatically when `autoTrack` is enabled:
+
+### Page View
+
+- **Trigger**: Initial page load, SPA navigation (pushState/replaceState/popstate)
+- **Event**: `page_view`
+- **Properties**: `autoCaptured: true`
+
+### Outbound Click
+
+- **Trigger**: Click on `<a>` tag with different origin
+- **Event**: `outbound_click`
+- **Properties**: `elementHref`, `elementId`, `elementText`, `linkHost`
+
+### Button Click
+
+- **Trigger**: Click on `<button>`, `[role="button"]`, or `[data-bts-track-click]`
+- **Event**: `button_click`
+- **Properties**: `elementId`, `elementName`, `elementRole`, `elementText`
+
+### Form Submit
+
+- **Trigger**: Form submission
+- **Event**: `form_submit`
+- **Properties**: `formAction`, `formId`, `formMethod`, `formName`
+
+### Search
+
+- **Trigger**: GET form submission with query params
+- **Query Keys**: `q`, `query`, `search`
+- **Event**: `search`
+- **Properties**: `autoCaptured: true`, `queryKey`, `searchQuery`
+
+### View Content
+
+- **Trigger**: Element with `[data-bts-view-content]` enters viewport
+- **Event**: `view_content`
+- **Properties**: `autoCaptured: true`, `contentId`, `contentType`, `contentTitle`