mytart 0.6.0 → 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

@@ -197,6 +197,17 @@ interface MytartConfig {
     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;
@@ -249,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[]>;

package/dist/index.d.ts

@@ -197,6 +197,17 @@ interface MytartConfig {
     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;
@@ -249,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[]>;

package/dist/index.js

@@ -43,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 {
   /**
@@ -1224,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,
@@ -1233,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,

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 {
   /**
@@ -1179,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,
@@ -1188,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mytart",
-  "version": "0.6.0",
+  "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",