mytart 0.5.2 → 0.6.0

package/dist/index.d.mts

@@ -35,7 +35,7 @@ interface ConsentSettings {
     /** Controls storage for security purposes (e.g. authentication). */
     security_storage?: ConsentState;
 }
-type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog' | 'meta-pixel';
+type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog' | 'meta-pixel' | 'clarity';
 type GoogleAnalyticsAppType = 'browser' | 'server';
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
     provider: 'google-analytics';
@@ -180,7 +180,18 @@ interface MetaPixelConfig extends BaseProviderConfig {
     /** Enable Meta Pixel debug mode (`fbq('set', 'debug', true)`). */
     debug?: boolean;
 }
-type ProviderConfig = GoogleAnalyticsConfig | MixpanelConfig | SegmentConfig | AmplitudeConfig | PlausibleConfig | PostHogConfig | MetaPixelConfig;
+interface ClarityConfig extends BaseProviderConfig {
+    provider: 'clarity';
+    /** The Clarity project ID (from the Clarity dashboard). */
+    projectId: string;
+    /**
+     * Enable Clarity cookie consent mode. When `true`, calls
+     * `clarity('consent')` after initialisation so Clarity sets cookies.
+     * When omitted or `false`, Clarity operates in cookieless mode.
+     */
+    cookie?: boolean;
+}
+type ProviderConfig = GoogleAnalyticsConfig | MixpanelConfig | SegmentConfig | AmplitudeConfig | PlausibleConfig | PostHogConfig | MetaPixelConfig | ClarityConfig;
 interface MytartConfig {
     providers: ProviderConfig[];
     defaultUserId?: string;
@@ -470,4 +481,33 @@ declare class MetaPixelProvider extends BaseProvider {
     page(options: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, 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 };
+declare global {
+    interface Window {
+        clarity: ClarityFn & {
+            q?: unknown[][];
+        };
+    }
+}
+type ClarityFn = (...args: unknown[]) => void;
+declare class ClarityProvider extends BaseProvider {
+    readonly name = "clarity";
+    private readonly config;
+    private clarityReady;
+    constructor(config: ClarityConfig);
+    /**
+     * Injects the official Clarity tracking snippet. Mirrors:
+     *
+     *   (function(c,l,a,r,i,t,y){
+     *     c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
+     *     t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
+     *     y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
+     *   })(window, document, "clarity", "script", "PROJECT_ID");
+     */
+    private initClarity;
+    private ensureClarity;
+    track(options: TrackOptions): Promise<TrackResult>;
+    identify(options: IdentifyOptions): Promise<TrackResult>;
+    page(options: PageOptions): Promise<TrackResult>;
+}
+
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, 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 };

package/dist/index.d.ts

@@ -35,7 +35,7 @@ interface ConsentSettings {
     /** Controls storage for security purposes (e.g. authentication). */
     security_storage?: ConsentState;
 }
-type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog' | 'meta-pixel';
+type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog' | 'meta-pixel' | 'clarity';
 type GoogleAnalyticsAppType = 'browser' | 'server';
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
     provider: 'google-analytics';
@@ -180,7 +180,18 @@ interface MetaPixelConfig extends BaseProviderConfig {
     /** Enable Meta Pixel debug mode (`fbq('set', 'debug', true)`). */
     debug?: boolean;
 }
-type ProviderConfig = GoogleAnalyticsConfig | MixpanelConfig | SegmentConfig | AmplitudeConfig | PlausibleConfig | PostHogConfig | MetaPixelConfig;
+interface ClarityConfig extends BaseProviderConfig {
+    provider: 'clarity';
+    /** The Clarity project ID (from the Clarity dashboard). */
+    projectId: string;
+    /**
+     * Enable Clarity cookie consent mode. When `true`, calls
+     * `clarity('consent')` after initialisation so Clarity sets cookies.
+     * When omitted or `false`, Clarity operates in cookieless mode.
+     */
+    cookie?: boolean;
+}
+type ProviderConfig = GoogleAnalyticsConfig | MixpanelConfig | SegmentConfig | AmplitudeConfig | PlausibleConfig | PostHogConfig | MetaPixelConfig | ClarityConfig;
 interface MytartConfig {
     providers: ProviderConfig[];
     defaultUserId?: string;
@@ -470,4 +481,33 @@ declare class MetaPixelProvider extends BaseProvider {
     page(options: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, 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 };
+declare global {
+    interface Window {
+        clarity: ClarityFn & {
+            q?: unknown[][];
+        };
+    }
+}
+type ClarityFn = (...args: unknown[]) => void;
+declare class ClarityProvider extends BaseProvider {
+    readonly name = "clarity";
+    private readonly config;
+    private clarityReady;
+    constructor(config: ClarityConfig);
+    /**
+     * Injects the official Clarity tracking snippet. Mirrors:
+     *
+     *   (function(c,l,a,r,i,t,y){
+     *     c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
+     *     t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
+     *     y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
+     *   })(window, document, "clarity", "script", "PROJECT_ID");
+     */
+    private initClarity;
+    private ensureClarity;
+    track(options: TrackOptions): Promise<TrackResult>;
+    identify(options: IdentifyOptions): Promise<TrackResult>;
+    page(options: PageOptions): Promise<TrackResult>;
+}
+
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, 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 };

package/dist/index.js

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   AmplitudeProvider: () => AmplitudeProvider,
   BaseProvider: () => BaseProvider,
+  ClarityProvider: () => ClarityProvider,
   GoogleAnalyticsProvider: () => GoogleAnalyticsProvider,
   MetaPixelProvider: () => MetaPixelProvider,
   MixpanelProvider: () => MixpanelProvider,
@@ -1092,6 +1093,107 @@ var MetaPixelProvider = class extends BaseProvider {
   }
 };
 
+// src/providers/clarity.ts
+var CLARITY_SCRIPT_BASE = "https://www.clarity.ms/tag/";
+var ClarityProvider = class extends BaseProvider {
+  constructor(config) {
+    super();
+    this.name = "clarity";
+    this.clarityReady = null;
+    this.config = config;
+  }
+  /**
+   * Injects the official Clarity tracking snippet. Mirrors:
+   *
+   *   (function(c,l,a,r,i,t,y){
+   *     c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
+   *     t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
+   *     y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
+   *   })(window, document, "clarity", "script", "PROJECT_ID");
+   */
+  initClarity() {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return Promise.resolve();
+    }
+    if (!window.clarity) {
+      const q = [];
+      const fn = function clarity(...args) {
+        q.push(args);
+      };
+      fn.q = q;
+      window.clarity = fn;
+    }
+    if (this.config.cookie) {
+      window.clarity("consent");
+    }
+    return new Promise((resolve) => {
+      const script = document.createElement("script");
+      script.async = true;
+      script.src = CLARITY_SCRIPT_BASE + this.config.projectId;
+      script.onload = () => resolve();
+      script.onerror = () => resolve();
+      document.head.appendChild(script);
+    });
+  }
+  ensureClarity() {
+    if (!this.clarityReady) {
+      this.clarityReady = this.initClarity();
+    }
+    return this.clarityReady;
+  }
+  async track(options) {
+    if (typeof window === "undefined") {
+      return this.buildSuccess(200);
+    }
+    await this.ensureClarity();
+    window.clarity("event", options.event);
+    if (options.properties) {
+      for (const [key, value] of Object.entries(options.properties)) {
+        window.clarity("set", key, String(value));
+      }
+    }
+    return this.buildSuccess(200);
+  }
+  async identify(options) {
+    if (typeof window === "undefined") {
+      return this.buildSuccess(200);
+    }
+    await this.ensureClarity();
+    const friendlyName = options.traits?.name ?? void 0;
+    window.clarity("identify", options.userId, void 0, void 0, friendlyName);
+    if (options.traits) {
+      for (const [key, value] of Object.entries(options.traits)) {
+        if (key !== "name") {
+          window.clarity("set", key, String(value));
+        }
+      }
+    }
+    return this.buildSuccess(200);
+  }
+  async page(options) {
+    if (typeof window === "undefined") {
+      return this.buildSuccess(200);
+    }
+    await this.ensureClarity();
+    window.clarity("event", "PageView");
+    if (options.url) {
+      window.clarity("set", "pageUrl", options.url);
+    }
+    if (options.name) {
+      window.clarity("set", "pageName", options.name);
+    }
+    if (options.referrer) {
+      window.clarity("set", "referrer", options.referrer);
+    }
+    if (options.properties) {
+      for (const [key, value] of Object.entries(options.properties)) {
+        window.clarity("set", key, String(value));
+      }
+    }
+    return this.buildSuccess(200);
+  }
+};
+
 // src/mytart.ts
 function createProvider(config) {
   switch (config.provider) {
@@ -1109,6 +1211,8 @@ function createProvider(config) {
       return new PostHogProvider(config);
     case "meta-pixel":
       return new MetaPixelProvider(config);
+    case "clarity":
+      return new ClarityProvider(config);
     default: {
       const exhaustive = config;
       throw new Error(`Unknown provider: ${exhaustive.provider}`);
@@ -1169,6 +1273,7 @@ var Mytart = class {
 0 && (module.exports = {
   AmplitudeProvider,
   BaseProvider,
+  ClarityProvider,
   GoogleAnalyticsProvider,
   MetaPixelProvider,
   MixpanelProvider,

package/dist/index.mjs

@@ -1048,6 +1048,107 @@ var MetaPixelProvider = class extends BaseProvider {
   }
 };
 
+// src/providers/clarity.ts
+var CLARITY_SCRIPT_BASE = "https://www.clarity.ms/tag/";
+var ClarityProvider = class extends BaseProvider {
+  constructor(config) {
+    super();
+    this.name = "clarity";
+    this.clarityReady = null;
+    this.config = config;
+  }
+  /**
+   * Injects the official Clarity tracking snippet. Mirrors:
+   *
+   *   (function(c,l,a,r,i,t,y){
+   *     c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
+   *     t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
+   *     y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
+   *   })(window, document, "clarity", "script", "PROJECT_ID");
+   */
+  initClarity() {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return Promise.resolve();
+    }
+    if (!window.clarity) {
+      const q = [];
+      const fn = function clarity(...args) {
+        q.push(args);
+      };
+      fn.q = q;
+      window.clarity = fn;
+    }
+    if (this.config.cookie) {
+      window.clarity("consent");
+    }
+    return new Promise((resolve) => {
+      const script = document.createElement("script");
+      script.async = true;
+      script.src = CLARITY_SCRIPT_BASE + this.config.projectId;
+      script.onload = () => resolve();
+      script.onerror = () => resolve();
+      document.head.appendChild(script);
+    });
+  }
+  ensureClarity() {
+    if (!this.clarityReady) {
+      this.clarityReady = this.initClarity();
+    }
+    return this.clarityReady;
+  }
+  async track(options) {
+    if (typeof window === "undefined") {
+      return this.buildSuccess(200);
+    }
+    await this.ensureClarity();
+    window.clarity("event", options.event);
+    if (options.properties) {
+      for (const [key, value] of Object.entries(options.properties)) {
+        window.clarity("set", key, String(value));
+      }
+    }
+    return this.buildSuccess(200);
+  }
+  async identify(options) {
+    if (typeof window === "undefined") {
+      return this.buildSuccess(200);
+    }
+    await this.ensureClarity();
+    const friendlyName = options.traits?.name ?? void 0;
+    window.clarity("identify", options.userId, void 0, void 0, friendlyName);
+    if (options.traits) {
+      for (const [key, value] of Object.entries(options.traits)) {
+        if (key !== "name") {
+          window.clarity("set", key, String(value));
+        }
+      }
+    }
+    return this.buildSuccess(200);
+  }
+  async page(options) {
+    if (typeof window === "undefined") {
+      return this.buildSuccess(200);
+    }
+    await this.ensureClarity();
+    window.clarity("event", "PageView");
+    if (options.url) {
+      window.clarity("set", "pageUrl", options.url);
+    }
+    if (options.name) {
+      window.clarity("set", "pageName", options.name);
+    }
+    if (options.referrer) {
+      window.clarity("set", "referrer", options.referrer);
+    }
+    if (options.properties) {
+      for (const [key, value] of Object.entries(options.properties)) {
+        window.clarity("set", key, String(value));
+      }
+    }
+    return this.buildSuccess(200);
+  }
+};
+
 // src/mytart.ts
 function createProvider(config) {
   switch (config.provider) {
@@ -1065,6 +1166,8 @@ function createProvider(config) {
       return new PostHogProvider(config);
     case "meta-pixel":
       return new MetaPixelProvider(config);
+    case "clarity":
+      return new ClarityProvider(config);
     default: {
       const exhaustive = config;
       throw new Error(`Unknown provider: ${exhaustive.provider}`);
@@ -1124,6 +1227,7 @@ var Mytart = class {
 export {
   AmplitudeProvider,
   BaseProvider,
+  ClarityProvider,
   GoogleAnalyticsProvider,
   MetaPixelProvider,
   MixpanelProvider,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mytart",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Multi-Yield Tracking & Analytics Relay Tool — framework-agnostic analytics for any project",
   "keywords": [
     "analytics",