mytart 0.6.2 → 0.6.4

package/README.md

@@ -379,8 +379,9 @@ Returns `null` when `crossProviderLinking` is disabled.
 ```typescript
 interface MytartConfig {
   providers: ProviderConfig[];
-  defaultUserId?: string;      // applied to every track/page call if no userId given
-  defaultAnonymousId?: string; // applied to every track/page call if no anonymousId given
+  defaultUserId?: string;       // applied to every track/page call if no userId given
+  defaultAnonymousId?: string;  // applied to every track/page call if no anonymousId given
+  defaultSessionId?: string;    // applied to every track/page call if no sessionId given
   debug?: boolean;
   ignoreBots?: boolean;          // when true, silently drops all tracking calls from known bots/crawlers
   crossProviderLinking?: boolean; // when true, auto-captures click IDs & cookies and injects them into every call
@@ -406,6 +407,7 @@ interface TrackOptions {
   properties?: Record<string, unknown>;
   userId?: string;
   anonymousId?: string;
+  sessionId?: string;
   timestamp?: Date;
   context?: EventContext;
 }
@@ -418,6 +420,7 @@ interface IdentifyOptions {
   userId: string;
   traits?: Record<string, unknown>;
   anonymousId?: string;
+  sessionId?: string;
   timestamp?: Date;
 }
 ```
@@ -432,6 +435,7 @@ interface PageOptions {
   properties?: Record<string, unknown>;
   userId?: string;
   anonymousId?: string;
+  sessionId?: string;
   timestamp?: Date;
 }
 ```

package/dist/index.d.mts

@@ -37,12 +37,64 @@ interface ConsentSettings {
 }
 type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog' | 'meta-pixel' | 'clarity';
 type GoogleAnalyticsAppType = 'browser' | 'server';
+/**
+ * Configuration for the Google Analytics (GA4) provider.
+ *
+ * @example
+ * ```ts
+ * {
+ *   provider: 'google-analytics',
+ *   enabled: true,
+ *   measurementId: 'G-XXXXXXXXXX',
+ *   appType: 'browser',
+ *   debug: true,
+ *   signals: true,
+ * }
+ * ```
+ */
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
     provider: 'google-analytics';
+    /**
+     * The GA4 Measurement ID for your data stream.
+     * Found in GA4 under Admin › Data Streams › your stream.
+     *
+     * @example 'G-XXXXXXXXXX'
+     */
     measurementId: string;
+    /**
+     * API secret for the GA4 Measurement Protocol (server-side).
+     * Generate one in GA4 under Admin › Data Streams › Measurement Protocol API secrets.
+     * Required when `appType` is `'server'`.
+     *
+     * @example 'xYzAbCdEfGhIjKlM'
+     */
     apiSecret?: string;
+    /**
+     * A unique identifier for the client (device/browser instance).
+     * In server mode this is required to associate hits with a user session.
+     * In browser mode it is managed automatically by gtag.js and can be omitted.
+     *
+     * @example 'client-123456.7890123456'
+     */
     clientId?: string;
+    /**
+     * When `true`, enables GA4 debug mode.
+     * In browser mode this sends events to the DebugView in the GA4 dashboard.
+     * In server mode this sets `debug_mode: true` on Measurement Protocol payloads.
+     *
+     * @default false
+     */
     debug?: boolean;
+    /**
+     * Determines how events are sent to Google Analytics.
+     *
+     * - `'browser'` — injects the gtag.js snippet and uses `window.gtag()` calls.
+     *   Suitable for client-side web apps.
+     * - `'server'` — sends events via the GA4 Measurement Protocol HTTP API.
+     *   Requires `apiSecret` and `clientId`. Suitable for Node.js / edge / SSR.
+     *
+     * @default 'browser'
+     */
     appType?: GoogleAnalyticsAppType;
     /**
      * Default consent state set before gtag('config'). In browser mode this
@@ -83,31 +135,198 @@ interface GoogleAnalyticsConfig extends BaseProviderConfig {
      */
     signals?: boolean;
 }
+/**
+ * Configuration for the Mixpanel provider.
+ *
+ * @example
+ * ```ts
+ * {
+ *   provider: 'mixpanel',
+ *   enabled: true,
+ *   token: 'abc123def456',
+ * }
+ * ```
+ */
 interface MixpanelConfig extends BaseProviderConfig {
     provider: 'mixpanel';
+    /**
+     * Your Mixpanel project token.
+     * Found in Mixpanel under Settings › Project Settings › Project Token.
+     *
+     * @example 'abc123def456'
+     */
     token: string;
+    /**
+     * Custom Mixpanel API endpoint. Use this if you are routing events through
+     * a proxy or using Mixpanel's EU residency endpoint.
+     *
+     * @default 'https://api.mixpanel.com'
+     * @example 'https://api-eu.mixpanel.com'
+     */
     apiUrl?: string;
 }
+/**
+ * Configuration for the Segment provider.
+ *
+ * @example
+ * ```ts
+ * {
+ *   provider: 'segment',
+ *   enabled: true,
+ *   writeKey: 'wk_abc123...',
+ * }
+ * ```
+ */
 interface SegmentConfig extends BaseProviderConfig {
     provider: 'segment';
+    /**
+     * The Segment source Write Key.
+     * Found in Segment under Sources › your source › Settings › API Keys.
+     *
+     * @example 'wk_abc123def456ghi789'
+     */
     writeKey: string;
+    /**
+     * Custom Segment API endpoint. Use this if you are routing events through
+     * a proxy or a custom Segment data plane.
+     *
+     * @default 'https://api.segment.io/v1'
+     * @example 'https://events.yourdomain.com/v1'
+     */
     apiUrl?: string;
 }
+/**
+ * Configuration for the Amplitude provider.
+ *
+ * @example
+ * ```ts
+ * {
+ *   provider: 'amplitude',
+ *   enabled: true,
+ *   apiKey: 'your-amplitude-api-key',
+ * }
+ * ```
+ */
 interface AmplitudeConfig extends BaseProviderConfig {
     provider: 'amplitude';
+    /**
+     * Your Amplitude project API key.
+     * Found in Amplitude under Settings › Projects › your project › General.
+     *
+     * @example 'a1b2c3d4e5f6a1b2c3d4e5f6'
+     */
     apiKey: string;
+    /**
+     * Custom Amplitude API endpoint. Use this if you are routing events through
+     * a proxy or using Amplitude's EU data centre.
+     *
+     * @default 'https://api2.amplitude.com/2/httpapi'
+     * @example 'https://api.eu.amplitude.com/2/httpapi'
+     */
     apiUrl?: string;
 }
+/**
+ * Configuration for the Plausible Analytics provider.
+ *
+ * Plausible is a privacy-focused analytics platform. Server-side usage
+ * requires `userAgent` and `xForwardedFor` so Plausible can attribute
+ * visits without cookies.
+ *
+ * @example
+ * ```ts
+ * // Browser usage
+ * {
+ *   provider: 'plausible',
+ *   enabled: true,
+ *   domain: 'example.com',
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Server-side usage
+ * {
+ *   provider: 'plausible',
+ *   enabled: true,
+ *   domain: 'example.com',
+ *   apiUrl: 'https://plausible.example.com',
+ *   userAgent: req.headers['user-agent'],
+ *   xForwardedFor: req.headers['x-forwarded-for'],
+ * }
+ * ```
+ */
 interface PlausibleConfig extends BaseProviderConfig {
     provider: 'plausible';
+    /**
+     * The domain name of the site as configured in your Plausible dashboard.
+     * Must match exactly (no protocol, no trailing slash).
+     *
+     * @example 'example.com'
+     */
     domain: string;
+    /**
+     * Custom Plausible API endpoint. Use this if you self-host Plausible
+     * or route events through a proxy to avoid ad-blockers.
+     *
+     * @default 'https://plausible.io'
+     * @example 'https://plausible.example.com'
+     */
     apiUrl?: string;
+    /**
+     * The visitor's User-Agent string. Required for server-side usage so
+     * Plausible can perform unique-visitor counting without cookies.
+     *
+     * @example 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...'
+     */
     userAgent?: string;
+    /**
+     * The visitor's IP address, used by Plausible for geolocation and
+     * unique-visitor hashing. Required for server-side usage.
+     * Pass the `X-Forwarded-For` header value from the incoming request.
+     *
+     * @example '203.0.113.42'
+     */
     xForwardedFor?: string;
 }
+/**
+ * Configuration for the PostHog provider.
+ *
+ * @example
+ * ```ts
+ * {
+ *   provider: 'posthog',
+ *   enabled: true,
+ *   apiKey: 'phc_abc123def456',
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Self-hosted PostHog
+ * {
+ *   provider: 'posthog',
+ *   enabled: true,
+ *   apiKey: 'phc_abc123def456',
+ *   apiUrl: 'https://posthog.example.com',
+ * }
+ * ```
+ */
 interface PostHogConfig extends BaseProviderConfig {
     provider: 'posthog';
+    /**
+     * Your PostHog project API key (starts with `phc_`).
+     * Found in PostHog under Project Settings › Project API Key.
+     *
+     * @example 'phc_abc123def456ghi789'
+     */
     apiKey: string;
+    /**
+     * Custom PostHog API endpoint. Use this if you self-host PostHog
+     * or use PostHog's EU cloud instance.
+     *
+     * @default 'https://us.i.posthog.com' (PostHog US Cloud)
+     * @example 'https://eu.i.posthog.com'
+     */
     apiUrl?: string;
 }
 /**
@@ -116,35 +335,113 @@ interface PostHogConfig extends BaseProviderConfig {
  * In server mode they are included in the `user_data` object sent to the
  * Conversions API — plain-text values are automatically SHA-256 hashed before
  * sending.
+ *
+ * @example
+ * ```ts
+ * {
+ *   em: 'user@example.com',
+ *   fn: 'jane',
+ *   ln: 'doe',
+ *   country: 'us',
+ * }
+ * ```
  */
 interface MetaPixelAdvancedMatching {
-    /** Email address */
+    /**
+     * Email address. Lowercased before hashing.
+     * @example 'user@example.com'
+     */
     em?: string;
-    /** Phone number */
+    /**
+     * Phone number including country code, digits only (no dashes or spaces).
+     * @example '15551234567'
+     */
     ph?: string;
-    /** First name */
+    /**
+     * First name. Lowercased before hashing.
+     * @example 'jane'
+     */
     fn?: string;
-    /** Last name */
+    /**
+     * Last name. Lowercased before hashing.
+     * @example 'doe'
+     */
     ln?: string;
-    /** Gender (m or f) */
+    /**
+     * Gender. Single lowercase letter: `'m'` for male, `'f'` for female.
+     * @example 'm'
+     */
     ge?: string;
-    /** Date of birth (YYYYMMDD) */
+    /**
+     * Date of birth in `YYYYMMDD` format.
+     * @example '19900115'
+     */
     db?: string;
-    /** City */
+    /**
+     * City name. Lowercased, no spaces or punctuation.
+     * @example 'newyork'
+     */
     ct?: string;
-    /** State / province (2-letter code) */
+    /**
+     * State or province as a 2-letter code. Lowercased.
+     * @example 'ny'
+     */
     st?: string;
-    /** Zip / postal code */
+    /**
+     * Zip or postal code. For US, use 5-digit format.
+     * @example '10001'
+     */
     zp?: string;
-    /** Country (2-letter ISO code) */
+    /**
+     * Country as a 2-letter ISO 3166-1 alpha-2 code. Lowercased.
+     * @example 'us'
+     */
     country?: string;
-    /** External ID */
+    /**
+     * External ID — your own unique identifier for the user.
+     * Useful for deduplicating browser and server events.
+     * @example 'user_abc123'
+     */
     external_id?: string;
 }
 type MetaPixelAppType = 'browser' | 'server';
+/**
+ * Configuration for the Meta Pixel (Facebook Pixel) provider.
+ * Supports both browser-side pixel tracking and server-side Conversions API.
+ *
+ * @example
+ * ```ts
+ * // Browser mode
+ * {
+ *   provider: 'meta-pixel',
+ *   enabled: true,
+ *   pixelId: '1234567890',
+ *   appType: 'browser',
+ *   debug: true,
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Server mode (Conversions API)
+ * {
+ *   provider: 'meta-pixel',
+ *   enabled: true,
+ *   pixelId: '1234567890',
+ *   appType: 'server',
+ *   accessToken: 'EAABsb...',
+ *   testEventCode: 'TEST12345',
+ * }
+ * ```
+ */
 interface MetaPixelConfig extends BaseProviderConfig {
     provider: 'meta-pixel';
-    /** The Meta Pixel ID (numeric string). */
+    /**
+     * The Meta Pixel ID (numeric string).
+     * Found in Meta Events Manager under your pixel's settings.
+     *
+     * @example '1234567890'
+     */
     pixelId: string;
     /**
      * Access token for the Conversions API. Required when `appType` is
@@ -180,9 +477,29 @@ interface MetaPixelConfig extends BaseProviderConfig {
     /** Enable Meta Pixel debug mode (`fbq('set', 'debug', true)`). */
     debug?: boolean;
 }
+/**
+ * Configuration for the Microsoft Clarity provider.
+ * Clarity provides session recordings, heatmaps, and behavioral analytics.
+ * Browser-only — this provider is a no-op in server environments.
+ *
+ * @example
+ * ```ts
+ * {
+ *   provider: 'clarity',
+ *   enabled: true,
+ *   projectId: 'abc123def4',
+ *   cookie: true,
+ * }
+ * ```
+ */
 interface ClarityConfig extends BaseProviderConfig {
     provider: 'clarity';
-    /** The Clarity project ID (from the Clarity dashboard). */
+    /**
+     * The Clarity project ID found in your Clarity dashboard under
+     * Settings › Overview › Project ID.
+     *
+     * @example 'abc123def4'
+     */
     projectId: string;
     /**
      * Enable Clarity cookie consent mode. When `true`, calls
@@ -196,6 +513,7 @@ interface MytartConfig {
     providers: ProviderConfig[];
     defaultUserId?: string;
     defaultAnonymousId?: string;
+    defaultSessionId?: string;
     debug?: boolean;
     /**
      * When `true`, silently drops all `track`, `identify`, and `page` calls
@@ -240,6 +558,7 @@ interface TrackOptions {
     properties?: Record<string, unknown>;
     userId?: string;
     anonymousId?: string;
+    sessionId?: string;
     timestamp?: Date;
     context?: EventContext;
 }
@@ -247,6 +566,7 @@ interface IdentifyOptions {
     userId: string;
     traits?: Record<string, unknown>;
     anonymousId?: string;
+    sessionId?: string;
     timestamp?: Date;
 }
 interface PageOptions {
@@ -256,6 +576,7 @@ interface PageOptions {
     properties?: Record<string, unknown>;
     userId?: string;
     anonymousId?: string;
+    sessionId?: string;
     timestamp?: Date;
 }
 interface TrackResult {
@@ -408,9 +729,9 @@ declare class GoogleAnalyticsProvider extends BaseProvider {
      * support Consent Mode.
      */
     updateConsent(consent: ConsentSettings): Promise<void>;
-    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
-    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
-    page({ name, url, referrer, userId, anonymousId }: PageOptions): Promise<TrackResult>;
+    track({ event, properties, userId, anonymousId, sessionId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits, sessionId }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, referrer, userId, anonymousId, sessionId }: PageOptions): Promise<TrackResult>;
 }
 
 declare class MixpanelProvider extends BaseProvider {
@@ -431,9 +752,9 @@ declare class SegmentProvider extends BaseProvider {
     private readonly baseUrl;
     constructor(config: SegmentConfig);
     private getAuth;
-    track({ event, properties, userId, anonymousId, timestamp, context }: TrackOptions): Promise<TrackResult>;
-    identify({ userId, traits, anonymousId, timestamp }: IdentifyOptions): Promise<TrackResult>;
-    page({ name, url, referrer, properties, userId, anonymousId, timestamp }: PageOptions): Promise<TrackResult>;
+    track({ event, properties, userId, anonymousId, sessionId, timestamp, context }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits, anonymousId, sessionId, timestamp }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, referrer, properties, userId, anonymousId, sessionId, timestamp }: PageOptions): Promise<TrackResult>;
 }
 
 declare class AmplitudeProvider extends BaseProvider {
@@ -442,9 +763,9 @@ declare class AmplitudeProvider extends BaseProvider {
     private readonly http;
     private readonly endpoint;
     constructor(config: AmplitudeConfig);
-    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
-    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
-    page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
+    track({ event, properties, userId, anonymousId, sessionId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits, anonymousId, sessionId }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, sessionId, properties }: PageOptions): Promise<TrackResult>;
 }
 
 declare class PlausibleProvider extends BaseProvider {
@@ -465,9 +786,9 @@ declare class PostHogProvider extends BaseProvider {
     private readonly http;
     private readonly endpoint;
     constructor(config: PostHogConfig);
-    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
-    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
-    page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
+    track({ event, properties, userId, anonymousId, sessionId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits, anonymousId, sessionId }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, sessionId, properties }: PageOptions): Promise<TrackResult>;
 }
 
 declare global {