mytart 0.6.4 → 0.6.6

package/README.md

@@ -271,7 +271,7 @@ When enabled:
 
 - The official `https://www.clarity.ms/tag/{projectId}` script is loaded once on the first `track()`, `identify()`, or `page()` call
 - `track()` fires `clarity('event', eventName)` and sets each property as a custom tag via `clarity('set', key, value)`
-- `identify()` calls `clarity('identify', userId)` with an optional friendly name from `traits.name`, and sets remaining traits as custom tags
+- `identify()` calls `clarity('identify', userId, sessionId, undefined, friendlyName)` with session ID as the native `custom-session-id` parameter, and sets remaining traits as custom tags
 - `page()` fires a `PageView` event and sets `pageUrl`, `pageName`, and `referrer` as custom tags
 - SSR-safe: silently succeeds when `window` is undefined
 
@@ -372,6 +372,63 @@ Returns `null` when `crossProviderLinking` is disabled.
 - **User properties take precedence.** If you pass a property with the same `xpl_*` key, your value wins.
 - **Consent.** This feature reads existing URL parameters and cookies — it does not set new cookies or tracking identifiers. Each provider's own consent mechanism remains authoritative.
 
+## State Management
+
+Mytart maintains a central state (`userId`, `anonymousId`, `sessionId`) that all providers can access. This enables consistent user identification across all analytics calls without manually passing IDs to every method.
+
+### How it works
+
+1. **Initial state** is set from `defaultUserId`, `defaultAnonymousId`, and `defaultSessionId` in the config
+2. **`identify()` updates state** — when you call `identify({ userId: 'abc' })`, the state is updated BEFORE dispatching to providers, ensuring all providers receive the updated userId
+3. **All methods use state** — `track()`, `page()`, and `identify()` all receive the current state values (user-provided values override state defaults)
+
+### State methods
+
+```typescript
+const analytics = new Mytart({
+  defaultUserId: 'default-user',
+  defaultAnonymousId: 'anon-123',
+  defaultSessionId: 'session-abc',
+  providers: [{ provider: 'segment', writeKey: 'YOUR_KEY', enabled: true }],
+});
+
+// Get current state
+const state = analytics.getState();
+// { userId: 'default-user', anonymousId: 'anon-123', sessionId: 'session-abc' }
+
+// Set individual IDs
+analytics.setUserId('user-456');
+analytics.setAnonymousId('anon-789');
+analytics.setSessionId('session-xyz');
+
+// Clear userId (e.g., on logout)
+analytics.clearUserId();
+
+// Clear session only (e.g., when session expires)
+analytics.clearSessionId();
+
+// Clear all state
+analytics.clearState();
+
+// identify() also updates state
+await analytics.identify({ userId: 'user-789', traits: { email: 'alice@example.com' } });
+// State is now: { userId: 'user-789', ... }
+```
+
+### How state flows to providers
+
+All providers receive the current state in their `track()`, `identify()`, and `page()` calls. Each provider maps state to its API correctly:
+
+- **GA4** — `user_id` and `session_id` in Measurement Protocol and gtag.js event params
+- **Segment** — `userId`, `anonymousId`, `sessionId` in track/identify/page
+- **Amplitude** — `user_id`, `device_id`, `session_id` in events
+- **PostHog** — `distinct_id` and `$session_id` in properties
+- **Mixpanel** — `distinct_id` and `$session_id` in events
+- **Meta Pixel (server)** — `external_id` in user_data, `xpl_anonymous_id` and `xpl_session_id` in custom_data
+- **Meta Pixel (browser)** — `xpl_session_id` in event properties
+- **Clarity** — `userId` passed to `clarity('identify', userId, sessionId, undefined, friendlyName)`, `sessionId` also set as custom tag
+- **Plausible** — does not support user identification (privacy-first, by design)
+
 ## API Reference
 
 ### `new Mytart(config: MytartConfig)`
@@ -494,12 +551,14 @@ All types are exported:
 
 ```typescript
 import type {
-  MytartConfig, BaseProviderConfig, ProviderConfig, TrackOptions, IdentifyOptions, PageOptions,
+  MytartConfig, MytartState, BaseProviderConfig, ProviderConfig, TrackOptions, IdentifyOptions, PageOptions,
   TrackResult, MytartError, EventContext, ProviderName, GoogleAnalyticsAppType,
   GoogleAnalyticsConfig, ConsentSettings, ConsentState, MixpanelConfig, SegmentConfig,
   AmplitudeConfig, PlausibleConfig, PostHogConfig, MetaPixelConfig, MetaPixelAppType,
   MetaPixelAdvancedMatching, ClarityConfig,
 } from 'mytart';
+
+import type { MytartLike } from 'mytart'; // interface for custom providers
 ```
 
 ## Custom Providers
@@ -507,12 +566,19 @@ import type {
 Extend `BaseProvider` to create your own:
 
 ```typescript
-import { BaseProvider, TrackOptions, IdentifyOptions, PageOptions, TrackResult } from 'mytart';
+import { BaseProvider, MytartLike, TrackOptions, IdentifyOptions, PageOptions, TrackResult } from 'mytart';
 
 export class MyProvider extends BaseProvider {
   readonly name = 'my-provider';
 
+  constructor(config: MyProviderConfig, mytart: MytartLike) {
+    super(mytart);
+    // Store config, set up HTTP client, etc.
+  }
+
   async track(options: TrackOptions): Promise<TrackResult> {
+    // Access central state via this.mytart.getState()
+    const state = this.mytart.getState();
     // your HTTP call here
     return this.buildSuccess(200);
   }

package/dist/index.d.mts

@@ -542,6 +542,16 @@ interface MytartConfig {
      */
     crossProviderLinking?: boolean;
 }
+/**
+ * Central state managed by Mytart that can be accessed by all providers.
+ * This enables providers to share state (userId, anonymousId, sessionId)
+ * without coupling to each other.
+ */
+interface MytartState {
+    userId: string | undefined;
+    anonymousId: string | undefined;
+    sessionId: string | undefined;
+}
 interface EventContext {
     ip?: string;
     userAgent?: string;
@@ -626,6 +636,7 @@ declare class Mytart {
     private readonly config;
     private readonly capturedIds;
     private readonly linkingProperties;
+    private state;
     constructor(config: MytartConfig);
     /**
      * Returns `true` when `ignoreBots` is enabled and the given (or detected)
@@ -653,10 +664,50 @@ declare class Mytart {
      * time, or `null` when `crossProviderLinking` is disabled.
      */
     getCapturedIds(): CapturedIds | null;
+    /**
+     * Get the current state.
+     */
+    getState(): MytartState;
+    /**
+     * Set userId in state. Use this when a user logs in.
+     */
+    setUserId(userId: string): void;
+    /**
+     * Set anonymousId in state. Use this to identify anonymous users.
+     */
+    setAnonymousId(anonymousId: string): void;
+    /**
+     * Set sessionId in state. Use this when a new session starts.
+     */
+    setSessionId(sessionId: string): void;
+    /**
+     * Clear userId (e.g., on logout).
+     */
+    clearUserId(): void;
+    /**
+     * Clear all state (userId, anonymousId, sessionId).
+     * Use this to reset state entirely.
+     */
+    clearState(): void;
+    /**
+     * Clear sessionId only (e.g., when session expires).
+     */
+    clearSessionId(): void;
 }
 
+interface MytartLike {
+    getState(): MytartState;
+    setUserId(userId: string): void;
+    setAnonymousId(anonymousId: string): void;
+    setSessionId(sessionId: string): void;
+    clearUserId(): void;
+    clearSessionId(): void;
+    clearState(): void;
+}
 declare abstract class BaseProvider {
     abstract readonly name: string;
+    protected readonly mytart: MytartLike;
+    constructor(mytart: MytartLike);
     abstract track(options: TrackOptions): Promise<TrackResult>;
     abstract identify(options: IdentifyOptions): Promise<TrackResult>;
     abstract page(options: PageOptions): Promise<TrackResult>;
@@ -683,7 +734,7 @@ declare class GoogleAnalyticsProvider extends BaseProvider {
     private readonly endpoint;
     private readonly isBrowser;
     private gtagReady;
-    constructor(config: GoogleAnalyticsConfig);
+    constructor(config: GoogleAnalyticsConfig, mytart: MytartLike);
     /**
      * Initializes the gtag.js snippet exactly as Google's official documentation
      * specifies. This mirrors the standard snippet:
@@ -738,11 +789,11 @@ declare class MixpanelProvider extends BaseProvider {
     readonly name = "mixpanel";
     private readonly config;
     private readonly http;
-    constructor(config: MixpanelConfig);
+    constructor(config: MixpanelConfig, mytart: MytartLike);
     private encodeData;
-    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, sessionId }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, sessionId, properties }: PageOptions): Promise<TrackResult>;
 }
 
 declare class SegmentProvider extends BaseProvider {
@@ -750,7 +801,7 @@ declare class SegmentProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly baseUrl;
-    constructor(config: SegmentConfig);
+    constructor(config: SegmentConfig, mytart: MytartLike);
     private getAuth;
     track({ event, properties, userId, anonymousId, sessionId, timestamp, context }: TrackOptions): Promise<TrackResult>;
     identify({ userId, traits, anonymousId, sessionId, timestamp }: IdentifyOptions): Promise<TrackResult>;
@@ -762,7 +813,7 @@ declare class AmplitudeProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly endpoint;
-    constructor(config: AmplitudeConfig);
+    constructor(config: AmplitudeConfig, mytart: MytartLike);
     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>;
@@ -773,11 +824,11 @@ declare class PlausibleProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly endpoint;
-    constructor(config: PlausibleConfig);
+    constructor(config: PlausibleConfig, mytart: MytartLike);
     private buildHeaders;
     track({ event, properties, context }: TrackOptions): Promise<TrackResult>;
     identify(_options: IdentifyOptions): Promise<TrackResult>;
-    page({ name, url, properties }: PageOptions): Promise<TrackResult>;
+    page({ name, url, referrer, properties }: PageOptions): Promise<TrackResult>;
 }
 
 declare class PostHogProvider extends BaseProvider {
@@ -785,7 +836,7 @@ declare class PostHogProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly endpoint;
-    constructor(config: PostHogConfig);
+    constructor(config: PostHogConfig, mytart: MytartLike);
     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>;
@@ -811,12 +862,8 @@ declare class MetaPixelProvider extends BaseProvider {
     private readonly isBrowser;
     private readonly apiVersion;
     private fbqReady;
-    /**
-     * Cached user data for the Conversions API. Updated by `identify()` so
-     * that subsequent `track()` and `page()` calls include user information.
-     */
     private cachedUserData;
-    constructor(config: MetaPixelConfig);
+    constructor(config: MetaPixelConfig, mytart: MytartLike);
     /**
      * Initialises the Meta Pixel snippet. This mirrors the official snippet from
      * https://developers.facebook.com/docs/meta-pixel/get-started:
@@ -881,7 +928,7 @@ declare class ClarityProvider extends BaseProvider {
     readonly name = "clarity";
     private readonly config;
     private clarityReady;
-    constructor(config: ClarityConfig);
+    constructor(config: ClarityConfig, mytart: MytartLike);
     /**
      * Injects the official Clarity tracking snippet. Mirrors:
      *
@@ -898,4 +945,4 @@ declare class ClarityProvider extends BaseProvider {
     page(options: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type CapturedIds, type ClarityConfig, ClarityProvider, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MetaPixelAdvancedMatching, type MetaPixelAppType, type MetaPixelConfig, MetaPixelProvider, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type CapturedIds, type ClarityConfig, ClarityProvider, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MetaPixelAdvancedMatching, type MetaPixelAppType, type MetaPixelConfig, MetaPixelProvider, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type MytartLike, type MytartState, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };

package/dist/index.d.ts

@@ -542,6 +542,16 @@ interface MytartConfig {
      */
     crossProviderLinking?: boolean;
 }
+/**
+ * Central state managed by Mytart that can be accessed by all providers.
+ * This enables providers to share state (userId, anonymousId, sessionId)
+ * without coupling to each other.
+ */
+interface MytartState {
+    userId: string | undefined;
+    anonymousId: string | undefined;
+    sessionId: string | undefined;
+}
 interface EventContext {
     ip?: string;
     userAgent?: string;
@@ -626,6 +636,7 @@ declare class Mytart {
     private readonly config;
     private readonly capturedIds;
     private readonly linkingProperties;
+    private state;
     constructor(config: MytartConfig);
     /**
      * Returns `true` when `ignoreBots` is enabled and the given (or detected)
@@ -653,10 +664,50 @@ declare class Mytart {
      * time, or `null` when `crossProviderLinking` is disabled.
      */
     getCapturedIds(): CapturedIds | null;
+    /**
+     * Get the current state.
+     */
+    getState(): MytartState;
+    /**
+     * Set userId in state. Use this when a user logs in.
+     */
+    setUserId(userId: string): void;
+    /**
+     * Set anonymousId in state. Use this to identify anonymous users.
+     */
+    setAnonymousId(anonymousId: string): void;
+    /**
+     * Set sessionId in state. Use this when a new session starts.
+     */
+    setSessionId(sessionId: string): void;
+    /**
+     * Clear userId (e.g., on logout).
+     */
+    clearUserId(): void;
+    /**
+     * Clear all state (userId, anonymousId, sessionId).
+     * Use this to reset state entirely.
+     */
+    clearState(): void;
+    /**
+     * Clear sessionId only (e.g., when session expires).
+     */
+    clearSessionId(): void;
 }
 
+interface MytartLike {
+    getState(): MytartState;
+    setUserId(userId: string): void;
+    setAnonymousId(anonymousId: string): void;
+    setSessionId(sessionId: string): void;
+    clearUserId(): void;
+    clearSessionId(): void;
+    clearState(): void;
+}
 declare abstract class BaseProvider {
     abstract readonly name: string;
+    protected readonly mytart: MytartLike;
+    constructor(mytart: MytartLike);
     abstract track(options: TrackOptions): Promise<TrackResult>;
     abstract identify(options: IdentifyOptions): Promise<TrackResult>;
     abstract page(options: PageOptions): Promise<TrackResult>;
@@ -683,7 +734,7 @@ declare class GoogleAnalyticsProvider extends BaseProvider {
     private readonly endpoint;
     private readonly isBrowser;
     private gtagReady;
-    constructor(config: GoogleAnalyticsConfig);
+    constructor(config: GoogleAnalyticsConfig, mytart: MytartLike);
     /**
      * Initializes the gtag.js snippet exactly as Google's official documentation
      * specifies. This mirrors the standard snippet:
@@ -738,11 +789,11 @@ declare class MixpanelProvider extends BaseProvider {
     readonly name = "mixpanel";
     private readonly config;
     private readonly http;
-    constructor(config: MixpanelConfig);
+    constructor(config: MixpanelConfig, mytart: MytartLike);
     private encodeData;
-    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, sessionId }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, sessionId, properties }: PageOptions): Promise<TrackResult>;
 }
 
 declare class SegmentProvider extends BaseProvider {
@@ -750,7 +801,7 @@ declare class SegmentProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly baseUrl;
-    constructor(config: SegmentConfig);
+    constructor(config: SegmentConfig, mytart: MytartLike);
     private getAuth;
     track({ event, properties, userId, anonymousId, sessionId, timestamp, context }: TrackOptions): Promise<TrackResult>;
     identify({ userId, traits, anonymousId, sessionId, timestamp }: IdentifyOptions): Promise<TrackResult>;
@@ -762,7 +813,7 @@ declare class AmplitudeProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly endpoint;
-    constructor(config: AmplitudeConfig);
+    constructor(config: AmplitudeConfig, mytart: MytartLike);
     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>;
@@ -773,11 +824,11 @@ declare class PlausibleProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly endpoint;
-    constructor(config: PlausibleConfig);
+    constructor(config: PlausibleConfig, mytart: MytartLike);
     private buildHeaders;
     track({ event, properties, context }: TrackOptions): Promise<TrackResult>;
     identify(_options: IdentifyOptions): Promise<TrackResult>;
-    page({ name, url, properties }: PageOptions): Promise<TrackResult>;
+    page({ name, url, referrer, properties }: PageOptions): Promise<TrackResult>;
 }
 
 declare class PostHogProvider extends BaseProvider {
@@ -785,7 +836,7 @@ declare class PostHogProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly endpoint;
-    constructor(config: PostHogConfig);
+    constructor(config: PostHogConfig, mytart: MytartLike);
     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>;
@@ -811,12 +862,8 @@ declare class MetaPixelProvider extends BaseProvider {
     private readonly isBrowser;
     private readonly apiVersion;
     private fbqReady;
-    /**
-     * Cached user data for the Conversions API. Updated by `identify()` so
-     * that subsequent `track()` and `page()` calls include user information.
-     */
     private cachedUserData;
-    constructor(config: MetaPixelConfig);
+    constructor(config: MetaPixelConfig, mytart: MytartLike);
     /**
      * Initialises the Meta Pixel snippet. This mirrors the official snippet from
      * https://developers.facebook.com/docs/meta-pixel/get-started:
@@ -881,7 +928,7 @@ declare class ClarityProvider extends BaseProvider {
     readonly name = "clarity";
     private readonly config;
     private clarityReady;
-    constructor(config: ClarityConfig);
+    constructor(config: ClarityConfig, mytart: MytartLike);
     /**
      * Injects the official Clarity tracking snippet. Mirrors:
      *
@@ -898,4 +945,4 @@ declare class ClarityProvider extends BaseProvider {
     page(options: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type CapturedIds, type ClarityConfig, ClarityProvider, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MetaPixelAdvancedMatching, type MetaPixelAppType, type MetaPixelConfig, MetaPixelProvider, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type CapturedIds, type ClarityConfig, ClarityProvider, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MetaPixelAdvancedMatching, type MetaPixelAppType, type MetaPixelConfig, MetaPixelProvider, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type MytartLike, type MytartState, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };