mytart 0.5.2 → 0.6.1

package/README.md

@@ -6,11 +6,12 @@
 
 ## Features
 
-- 🔌 **7 providers out of the box**: Google Analytics 4, Mixpanel, Segment, Amplitude, Plausible, PostHog, Meta Pixel
+- 🔌 **8 providers out of the box**: Google Analytics 4, Mixpanel, Segment, Amplitude, Plausible, PostHog, Meta Pixel, Microsoft Clarity
 - 🌐 **Universal**: works in Node.js, browsers, and any JS framework (Next.js, Remix, Astro, SvelteKit, etc.)
 - 🔷 **TypeScript-first**: precise typings, object-parameter style for great DX
 - 📦 **Dual ESM/CJS output**: works with `import` and `require`
 - 🪶 **Lightweight**: direct HTTP via axios, no SDK overhead
+- 🤖 **Bot filtering**: optionally ignore bots and crawlers via [ua-parser-js](https://github.com/nicolevanderhoeven/ua-parser-js)
 - ✅ **Node.js ≥ 18**
 
 ## Installation
@@ -253,6 +254,64 @@ await provider.updatePixelConsent(true);   // fbq('consent', 'grant')
 await provider.updatePixelConsent(false);  // fbq('consent', 'revoke')
 ```
 
+### Microsoft Clarity
+
+[Microsoft Clarity](https://clarity.microsoft.com/) is a free behavioral analytics tool that provides session recordings, heatmaps, and insights. Clarity is **browser-only** — there is no server mode.
+
+```typescript
+{
+  provider: 'clarity',
+  projectId: 'YOUR_PROJECT_ID',
+  enabled: true,
+}
+```
+
+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
+- `page()` fires a `PageView` event and sets `pageUrl`, `pageName`, and `referrer` as custom tags
+- SSR-safe: silently succeeds when `window` is undefined
+
+#### Cookie consent
+
+By default Clarity operates in cookieless mode. To enable cookie-based tracking, set `cookie: true`:
+
+```typescript
+{
+  provider: 'clarity',
+  projectId: 'YOUR_PROJECT_ID',
+  cookie: true,
+  enabled: true,
+}
+```
+
+This calls `clarity('consent')` during initialisation so Clarity can set cookies for more accurate session tracking.
+
+## Bot Filtering
+
+Set `ignoreBots: true` at the top level to silently drop all `track()`, `identify()`, and `page()` calls when the visitor is a known bot or crawler. Detection is powered by [`ua-parser-js`](https://github.com/nicolevanderhoeven/ua-parser-js)'s `isBot()` function.
+
+```typescript
+const analytics = new Mytart({
+  ignoreBots: true,
+  providers: [
+    { provider: 'google-analytics', measurementId: 'G-XXXXXXXXXX', enabled: true },
+    { provider: 'segment', writeKey: 'YOUR_KEY', enabled: true },
+  ],
+});
+```
+
+When a bot is detected, all methods return an empty `TrackResult[]` array — no events are dispatched to any provider.
+
+The User-Agent is read from:
+
+1. `context.userAgent` if supplied in the `track()` call
+2. `navigator.userAgent` in browser environments
+
+If no User-Agent is available (e.g. server-side without `context.userAgent`), the call proceeds normally.
+
 ## API Reference
 
 ### `new Mytart(config: MytartConfig)`
@@ -263,6 +322,7 @@ interface MytartConfig {
   defaultUserId?: string;      // applied to every track/page call if no userId given
   defaultAnonymousId?: string; // applied to every track/page call if no anonymousId given
   debug?: boolean;
+  ignoreBots?: boolean;        // when true, silently drops all tracking calls from known bots/crawlers
 }
 ```
 
@@ -373,7 +433,7 @@ import type {
   TrackResult, MytartError, EventContext, ProviderName, GoogleAnalyticsAppType,
   GoogleAnalyticsConfig, ConsentSettings, ConsentState, MixpanelConfig, SegmentConfig,
   AmplitudeConfig, PlausibleConfig, PostHogConfig, MetaPixelConfig, MetaPixelAppType,
-  MetaPixelAdvancedMatching,
+  MetaPixelAdvancedMatching, ClarityConfig,
 } from 'mytart';
 ```
 

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,12 +180,34 @@ 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;
     defaultAnonymousId?: string;
     debug?: boolean;
+    /**
+     * When `true`, silently drops all `track`, `identify`, and `page` calls
+     * if the visitor's User-Agent belongs to a known bot or crawler.
+     *
+     * Detection uses `isBot()` from `ua-parser-js`. The User-Agent is read
+     * from `context.userAgent` (if supplied) or `navigator.userAgent` in
+     * browser environments.
+     *
+     * Defaults to `false` (bots are tracked like any other visitor).
+     */
+    ignoreBots?: boolean;
 }
 interface EventContext {
     ip?: string;
@@ -238,6 +260,11 @@ declare class Mytart {
     private readonly providers;
     private readonly config;
     constructor(config: MytartConfig);
+    /**
+     * Returns `true` when `ignoreBots` is enabled and the given (or detected)
+     * User-Agent belongs to a known bot or crawler.
+     */
+    private isBotRequest;
     track(options: TrackOptions): Promise<TrackResult[]>;
     identify(options: IdentifyOptions): Promise<TrackResult[]>;
     page(options: PageOptions): Promise<TrackResult[]>;
@@ -470,4 +497,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,12 +180,34 @@ 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;
     defaultAnonymousId?: string;
     debug?: boolean;
+    /**
+     * When `true`, silently drops all `track`, `identify`, and `page` calls
+     * if the visitor's User-Agent belongs to a known bot or crawler.
+     *
+     * Detection uses `isBot()` from `ua-parser-js`. The User-Agent is read
+     * from `context.userAgent` (if supplied) or `navigator.userAgent` in
+     * browser environments.
+     *
+     * Defaults to `false` (bots are tracked like any other visitor).
+     */
+    ignoreBots?: boolean;
 }
 interface EventContext {
     ip?: string;
@@ -238,6 +260,11 @@ declare class Mytart {
     private readonly providers;
     private readonly config;
     constructor(config: MytartConfig);
+    /**
+     * Returns `true` when `ignoreBots` is enabled and the given (or detected)
+     * User-Agent belongs to a known bot or crawler.
+     */
+    private isBotRequest;
     track(options: TrackOptions): Promise<TrackResult[]>;
     identify(options: IdentifyOptions): Promise<TrackResult[]>;
     page(options: PageOptions): Promise<TrackResult[]>;
@@ -470,4 +497,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,
@@ -42,6 +43,9 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/mytart.ts
+var import_bot_detection = require("ua-parser-js/bot-detection");
+
 // src/providers/base.ts
 var BaseProvider = class {
   /**
@@ -1092,6 +1096,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 +1214,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}`);
@@ -1120,7 +1227,17 @@ var Mytart = class {
     this.config = config;
     this.providers = config.providers.filter((c) => c.enabled === true).map(createProvider);
   }
+  /**
+   * Returns `true` when `ignoreBots` is enabled and the given (or detected)
+   * User-Agent belongs to a known bot or crawler.
+   */
+  isBotRequest(userAgent) {
+    if (!this.config.ignoreBots) return false;
+    const ua = userAgent ?? (typeof navigator !== "undefined" ? navigator.userAgent : void 0);
+    return ua ? (0, import_bot_detection.isBot)(ua) : false;
+  }
   async track(options) {
+    if (this.isBotRequest(options.context?.userAgent)) return [];
     const enriched = {
       userId: this.config.defaultUserId,
       anonymousId: this.config.defaultAnonymousId,
@@ -1129,9 +1246,11 @@ var Mytart = class {
     return Promise.all(this.providers.map((p) => p.track(enriched)));
   }
   async identify(options) {
+    if (this.isBotRequest()) return [];
     return Promise.all(this.providers.map((p) => p.identify(options)));
   }
   async page(options) {
+    if (this.isBotRequest()) return [];
     const enriched = {
       userId: this.config.defaultUserId,
       anonymousId: this.config.defaultAnonymousId,
@@ -1169,6 +1288,7 @@ var Mytart = class {
 0 && (module.exports = {
   AmplitudeProvider,
   BaseProvider,
+  ClarityProvider,
   GoogleAnalyticsProvider,
   MetaPixelProvider,
   MixpanelProvider,

package/dist/index.mjs

@@ -1,3 +1,6 @@
+// src/mytart.ts
+import { isBot } from "ua-parser-js/bot-detection";
+
 // src/providers/base.ts
 var BaseProvider = class {
   /**
@@ -1048,6 +1051,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 +1169,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}`);
@@ -1076,7 +1182,17 @@ var Mytart = class {
     this.config = config;
     this.providers = config.providers.filter((c) => c.enabled === true).map(createProvider);
   }
+  /**
+   * Returns `true` when `ignoreBots` is enabled and the given (or detected)
+   * User-Agent belongs to a known bot or crawler.
+   */
+  isBotRequest(userAgent) {
+    if (!this.config.ignoreBots) return false;
+    const ua = userAgent ?? (typeof navigator !== "undefined" ? navigator.userAgent : void 0);
+    return ua ? isBot(ua) : false;
+  }
   async track(options) {
+    if (this.isBotRequest(options.context?.userAgent)) return [];
     const enriched = {
       userId: this.config.defaultUserId,
       anonymousId: this.config.defaultAnonymousId,
@@ -1085,9 +1201,11 @@ var Mytart = class {
     return Promise.all(this.providers.map((p) => p.track(enriched)));
   }
   async identify(options) {
+    if (this.isBotRequest()) return [];
     return Promise.all(this.providers.map((p) => p.identify(options)));
   }
   async page(options) {
+    if (this.isBotRequest()) return [];
     const enriched = {
       userId: this.config.defaultUserId,
       anonymousId: this.config.defaultAnonymousId,
@@ -1124,6 +1242,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.1",
   "description": "Multi-Yield Tracking & Analytics Relay Tool — framework-agnostic analytics for any project",
   "keywords": [
     "analytics",
@@ -35,7 +35,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "axios": "^1.7.0"
+    "axios": "^1.7.0",
+    "ua-parser-js": "^2.0.9"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",