@borisch/snitch 1.0.1 → 1.1.0

package/README.md

@@ -11,12 +11,27 @@ npm install @borisch/snitch
 ## Quick Start
 
 ```ts
-import { snitch, sessionPlugin, scrollPlugin, beaconTransportPlugin } from '@borisch/snitch'
+import {
+  snitch,
+  devicePlugin,
+  userPlugin,
+  sessionPlugin,
+  launchPlugin,
+  scrollPlugin,
+  locationPlugin,
+  beaconTransportPlugin,
+  debugLoggerPlugin,
+} from '@borisch/snitch'
 
 const captureEvent = snitch(
+  devicePlugin(),
+  userPlugin(),
   sessionPlugin(),
-  scrollPlugin({ threshold: 25 }),
-  beaconTransportPlugin({ url: 'https://analytics.example.com/collect' })
+  launchPlugin(),
+  scrollPlugin(),
+  locationPlugin({ captureLocationChange: true }),
+  beaconTransportPlugin({ hostname: 'analytics.example.com' }),
+  debugLoggerPlugin(),
 )
 
 // Manually capture events
@@ -25,43 +40,374 @@ captureEvent('button_click', { buttonId: 'signup' })
 
 The `snitch()` function accepts any number of plugins and returns a `captureEvent` function. Plugins can:
 
-- **Provide event parameters** (automatically attached to every event)
+- **Provide event parameters** — automatically attached to every event
 - **Emit events** on their own (e.g. scroll milestones, page views)
-- **Transport events** to a backend (Beacon API, fetch, VK Bridge, etc.)
+- **Transport events** to a backend
 - **Intercept events** before they are sent
+- **Expose mixins** — additional methods attached to the `captureEvent` function
 
 ## Plugins
 
-| Plugin             | Factory                  | Description                                                |
-| ------------------ | ------------------------ | ---------------------------------------------------------- |
-| Session            | `sessionPlugin()`        | Generates a unique session ID, attaches it to every event  |
-| Launch             | `launchPlugin()`         | Captures a `launch` event on initialization                |
-| Scroll             | `scrollPlugin(opts)`     | Tracks scroll depth milestones (default: 25/50/75/100%)    |
-| Location           | `locationPlugin()`       | Attaches page URL and referrer to every event              |
-| Engagement         | `engagementPlugin(opts)` | Tracks time spent on page, emits engagement events         |
-| Screens            | `screenPlugin()`         | Tracks screen/page view events                             |
-| Exceptions         | `exceptionsPlugin()`     | Captures unhandled errors and unhandled promise rejections |
-| Web Vitals         | `webVitalsPlugin()`      | Reports Core Web Vitals (LCP, FID, CLS, etc.)              |
-| Flag               | `flagPlugin(opts)`       | Attaches a static key-value flag to every event            |
-| User Agent         | `useragentPlugin()`      | Attaches `navigator.userAgent` to every event              |
-| Debug Logger       | `debugLoggerPlugin()`    | Logs all events to the console (for development)           |
-| VK Mini App Launch | `vkmaLaunchPlugin()`     | Parses VK Mini App launch parameters                       |
+### `sessionPlugin()`
+
+Manages user sessions using `localStorage`. A new session starts when:
+
+- No previous session exists
+- The previous session has been inactive for 30+ minutes
+- UTM parameters are present in the URL
+
+If a session expires between events, a new session is started automatically before the next event is sent.
+
+Emits: `sessionStart`
+
+Attaches to every event:
+| Param | Description |
+|-------|-------------|
+| `sid` | Unique session ID |
+| `scnt` | Total session count for this device |
+| `set` | Milliseconds since session started |
+| `sutm` | Compact UTM parameters from the URL that started the session |
+
+---
+
+### `launchPlugin()`
+
+Captures a `launch` event when the tracker initializes. Records whether the page runs inside an iframe.
+
+Emits: `launch` with `{ ifr: "true" | "false" }`
+
+Attaches to every event:
+| Param | Description |
+|-------|-------------|
+| `lid` | Unique launch ID (generated per `snitch()` call) |
+| `ref` | `document.referrer` at initialization time |
+
+---
+
+### `scrollPlugin()`
+
+Tracks scroll depth. Emits events when the user scrolls past depth milestones (25%, 50%, 75%, 100%). The scroll depth cache resets whenever a `locationChange` or `screenChange` event occurs, so milestones are tracked per-page.
+
+Emits: `scroll` with `{ depthPercent: number }`
+
+---
+
+### `locationPlugin(options)`
+
+Tracks the current page URL and optionally emits events on URL changes (SPA navigation, `pushState`, etc.).
+
+**Options:**
+| Option | Type | Description |
+|--------|------|-------------|
+| `captureLocationChange` | `boolean` | Whether to listen for URL changes and emit events |
+| `getLocation` | `() => string` | Custom location getter (defaults to `window.location.href`) |
+
+Emits (when `captureLocationChange` is `true`): `locationChange` with `{ phref: string }` (previous URL)
+
+Attaches to every event:
+| Param | Description |
+|-------|-------------|
+| `href` | Current page URL (truncated to 500 characters) |
+
+---
+
+### `engagementPlugin(options?)`
+
+Periodically emits engagement events while the page is visible. Events are suppressed when the tab is hidden (`document.hidden === true`).
+
+**Options:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `engagementTrackingIntervalMsec` | `number` | `10000` | Interval in milliseconds between engagement pings |
+
+Emits: `engage` (at configured interval, only when tab is visible)
+
+---
+
+### `screenPlugin(initialScreen)`
+
+Tracks screen/page views within an app. Maintains current and previous screen state.
+
+**Options:**
+| Option | Type | Description |
+|--------|------|-------------|
+| `screenType` | `string` | Type/category of the initial screen |
+| `screenId` | `string?` | Optional screen identifier |
+
+To change screens, call `captureEvent('screenChange', { screenType: 'catalog', screenId: 'page2' })`. The plugin automatically injects previous screen params and removes the raw `screenType`/`screenId` from the event payload.
+
+Attaches to every event:
+| Param | Description |
+|-------|-------------|
+| `sct` | Current screen type |
+| `scid` | Current screen ID (or `""`) |
+
+Attaches to `screenChange` events:
+| Param | Description |
+|-------|-------------|
+| `psct` | Previous screen type |
+| `pscid` | Previous screen ID (or `""`) |
+
+---
+
+### `exceptionsPlugin()`
+
+Captures unhandled errors and promise rejections globally.
+
+Emits:
+
+- `uncaughtError` with `{ message, filename, lineno, colno, error }`
+- `unhandledRejection` with `{ reason }`
+
+---
+
+### `webVitalsPlugin()`
+
+Reports [Core Web Vitals](https://web.dev/vitals/) using the `web-vitals` library. Tracks CLS, FID, LCP, TTFB, and FCP.
+
+Emits: `webVital` with `{ name, value, delta, metricId }`
+
+---
+
+### `flagPlugin(options)`
+
+Feature flag evaluation plugin. Adds `getFlag()` and `getFlags()` methods to the `captureEvent` function via mixins.
+
+**Options:**
+| Option | Type | Description |
+|--------|------|-------------|
+| `flagApiEndpoint` | `string` | URL of the flag evaluation API |
+| `userIdResolver` | `() => string \| null \| undefined` | Optional custom user ID resolver |
+
+User ID is resolved in order: custom resolver → VK user ID from URL → Top Mail.ru counter cookie → auto-generated anonymous ID (persisted in `localStorage`).
+
+**Usage:**
+
+```ts
+const captureEvent = snitch(flagPlugin({ flagApiEndpoint: 'https://flags.example.com/api' })) as any
+
+const flag = await captureEvent.getFlag('new-feature')
+// { flagKey: 'new-feature', match: true, variant: 'control', attachment: '...' }
+
+const flags = await captureEvent.getFlags(['feature-a', 'feature-b'])
+```
+
+Emits:
+
+- `flagEvaluationComplete` with full evaluation response
+- `flagEvaluationFailed` with `{ flagKey, errorMessage }`
+
+---
+
+### `useragentPlugin()`
+
+Attaches the browser user agent string to every event.
+
+Attaches to every event:
+| Param | Description |
+|-------|-------------|
+| `ua` | `navigator.userAgent` |
+
+---
+
+### `devicePlugin()`
+
+Generates a persistent device (browser) identifier stored in `localStorage` under the key `snitch:did`. The ID is created once and reused forever across all sessions — it survives page reloads, tab closes, and new sessions. It only resets if the user clears their browser storage.
+
+If `localStorage` is unavailable, a new ID is generated per `snitch()` call (in-memory only).
+
+Attaches to every event:
+| Param | Description |
+|-------|-------------|
+| `did` | Persistent device ID |
+
+---
+
+### `userPlugin(userId?)`
+
+Tracks the current user. Exposes `.setUserId(id)` and `.clearUserId()` methods on the `captureEvent` function via mixins. The user ID is stored in-memory only — no `localStorage`, no emitted events. This makes it safe to use in both browser and server-side environments.
+
+When no user ID is set, `uid` is omitted from events entirely.
+
+If the user ID is known at initialization time, it can be passed directly:
+
+```ts
+const captureEvent = snitch(
+  userPlugin('user-123'),
+  // ...
+) as any
+```
+
+Otherwise, set it later:
+
+```ts
+captureEvent.setUserId('user-123')
+```
+
+**Methods (mixins):**
+| Method | Description |
+|--------|-------------|
+| `setUserId(id: string)` | Set the user ID. All subsequent events will include `uid`. |
+| `clearUserId()` | Clear the user ID. `uid` is no longer attached to events. |
+| `withUserId(id: string, eventName: string, eventPayload?)` | Temporarily set the user ID, send a single event, then restore the previous user ID. Designed for server-side use where a single snitch instance handles multiple users. |
+
+Attaches to every event (while user ID is set):
+| Param | Description |
+|-------|-------------|
+| `uid` | Current user ID |
+
+**Usage:**
+
+```ts
+const captureEvent = snitch(
+  devicePlugin(),
+  userPlugin(),
+  sessionPlugin(),
+  beaconTransportPlugin({ hostname: '...' }),
+) as any
+
+// User logs in
+captureEvent.setUserId('user-123')
+
+captureEvent('add_to_cart', { productId: 'abc' })
+// => { event: 'add_to_cart', productId: 'abc', uid: 'user-123', did: '...', sid: '...' }
+
+// User logs out
+captureEvent.clearUserId()
+// uid is no longer attached to events
+
+// Server-side (s2s-transport) — pass uid at init, no localStorage needed
+const track = snitch(
+  userPlugin(req.userId),
+  s2sTransportPlugin({ hostname: 'analytics.example.com' }),
+)
+track('subscriptionRenewalPaymentFailed')
+// => { event: 'subscriptionRenewalPaymentFailed', uid: 'user-123' }
+```
+
+**Server-side with `.withUserId()`:**
+
+When a single snitch instance handles requests from multiple users (e.g., in an Express handler), use `.withUserId()` to atomically send an event with a specific user ID without affecting other requests. The captureEvent pipeline is synchronous, so the temporary uid swap is safe — no interleaving is possible.
+
+```ts
+const track = snitch(userPlugin(), s2sTransportPlugin({ hostname: 'analytics.example.com' })) as any
+
+app.post('/api/checkout', (req, res) => {
+  // Sends this one event with uid='user-42', then restores previous state
+  track.withUserId(req.userId, 'checkout_completed', { orderId: req.body.orderId })
+  res.json({ ok: true })
+})
+```
+
+---
+
+### `debugLoggerPlugin()`
+
+Development helper. Logs every event to the browser console with timestamps and time deltas between events. When the event has a non-empty payload, it is also rendered via `console.table()`.
+
+**Silent by default.** To enable, set a `localStorage` flag:
+
+```js
+localStorage.setItem('snitch:debug', 'true')
+```
+
+The flag is read once when `debugLoggerPlugin()` is called. To disable, remove the flag and reload:
+
+```js
+localStorage.removeItem('snitch:debug')
+```
+
+---
 
 ## Transports
 
-| Transport   | Factory                          | Description                                                                     |
-| ----------- | -------------------------------- | ------------------------------------------------------------------------------- |
-| Beacon      | `beaconTransportPlugin(opts)`    | Sends events as URL query params via `navigator.sendBeacon()`                   |
-| S2S         | `s2sTransportPlugin(opts)`       | Sends events as URL query params via `fetch()` GET (for server-side / Node 18+) |
-| Top Mail.ru | `topmailruTransportPlugin(opts)` | Sends events to Top Mail.ru counter                                             |
-| VK Bridge   | `vkBridgeTransportPlugin(opts)`  | Sends events via VK Bridge                                                      |
+### `beaconTransportPlugin(options?)`
+
+Sends events via [`navigator.sendBeacon()`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon). All event data is encoded as URL query parameters — designed for CDN log-based analytics where request URLs are parsed from access logs.
+
+**Options:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `hostname` | `string` | `window.location.hostname` | Target hostname |
+| `path` | `string` | `/_snitch` | URL path |
+
+Requests are sent to: `{protocol}//{hostname}{path}?event={name}&...params`
+
+---
+
+### `s2sTransportPlugin(options)`
+
+Sends events via `fetch()` GET requests over HTTPS. Fire-and-forget (errors are silently caught). Designed for server-side environments (Node 18+, Cloudflare Workers) or any environment with `fetch`.
+
+**Options:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `hostname` | `string` | _required_ | Target hostname |
+| `path` | `string` | `/_snitch` | URL path |
+| `s2sToken` | `string` | — | Optional auth token (sent as a query parameter) |
+
+Requests are sent to: `https://{hostname}{path}?event={name}&...params[&s2sToken=...]`
+
+---
+
+### `topmailruTransportPlugin(counterId, userIdResolver?)`
+
+Sends events to [Top Mail.ru](https://top.mail.ru/) analytics counter by pushing to the `window._tmr` queue.
+
+**Parameters:**
+| Param | Type | Description |
+|-------|------|-------------|
+| `counterId` | `string` | Top Mail.ru counter ID (required) |
+| `userIdResolver` | `() => string \| null \| undefined` | Optional custom user ID resolver |
+
+User ID resolution order: custom resolver → TMR counter cookie → auto-generated anonymous ID.
+
+---
+
+### `vkBridgeTransportPlugin()`
+
+Sends events via [VK Bridge](https://dev.vk.com/mini-apps/bridge) for VK Mini Apps. Extracts `vk_user_id` from the URL. Each event triggers two VK Bridge calls: `VKWebAppTrackEvent` and `VKWebAppSendCustomEvent`. All param values are coerced to strings to work around iOS VK Bridge limitations.
+
+---
+
+## Platform-Specific Plugins
+
+### `vkmaLaunchPlugin()`
+
+A VK Mini Apps variant of `launchPlugin`. Parses VK Mini App launch parameters from the URL (`vk_user_id`, `vk_app_id`, `vk_platform`, `vk_ref`, etc.).
+
+Emits: `launch` (with iframe flag + VKMA params), `mt_internal_launch`
+
+Attaches to every event:
+| Param | Description |
+|-------|-------------|
+| `lid` | Unique launch ID |
+| `ref` | `document.referrer` |
+| `mauid` | VK user ID |
+| `maaid` | VK app ID |
+| `malang` | VK language |
+| `mac` | VK access token settings |
+| `map` | VK platform |
+| `maref` | VK ref |
+
+---
 
 ## Types
 
 All public types are exported for TypeScript consumers:
 
 ```ts
-import type { Plugin, EventTransport, TrackerEventPayload } from '@borisch/snitch'
+import type {
+  Plugin,
+  EventTransport,
+  EventSource,
+  EventPayloadParamsProvider,
+  InitializationHandler,
+  BeforeCaptureEventHandler,
+  MixinProvider,
+  TrackerEventPayload,
+  EventHandler,
+} from '@borisch/snitch'
 ```
 
 ## Writing a Custom Plugin
@@ -73,12 +419,21 @@ import type { Plugin } from '@borisch/snitch'
 
 function myPlugin(): Plugin {
   return {
+    // Attach params to every event
     getEventPayloadParams() {
       return { customParam: 'value' }
     },
+    // React to events before transport
+    beforeCaptureEvent(eventName, eventParams) {
+      // filter, modify, log, etc.
+    },
+    // Transport events
     sendEvent(eventName, eventParams) {
-      // custom transport logic
-    }
+      fetch('/analytics', {
+        method: 'POST',
+        body: JSON.stringify({ eventName, ...eventParams }),
+      })
+    },
   }
 }
 ```

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { default as webVitalsPlugin } from './packages/snitch-plugin-web-vitals/
 export { default as flagPlugin } from './packages/snitch-plugin-flag/index';
 export { default as debugLoggerPlugin } from './packages/snitch-plugin-debug-logger/index';
 export { default as useragentPlugin } from './packages/snitch-plugin-useragent/index';
+export { default as devicePlugin } from './packages/snitch-plugin-device/index';
+export { default as userPlugin } from './packages/snitch-plugin-user/index';
 export { default as beaconTransportPlugin } from './packages/snitch-plugin-beacon-transport/index';
 export { default as s2sTransportPlugin } from './packages/snitch-plugin-s2s-transport/index';
 export { default as topmailruTransportPlugin } from './packages/snitch-plugin-topmailru-transport/index';

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.vkmaLaunchPlugin = exports.vkBridgeTransportPlugin = exports.topmailruTransportPlugin = exports.s2sTransportPlugin = exports.beaconTransportPlugin = exports.useragentPlugin = exports.debugLoggerPlugin = exports.flagPlugin = exports.webVitalsPlugin = exports.exceptionsPlugin = exports.screenPlugin = exports.engagementPlugin = exports.launchPlugin = exports.sessionPlugin = exports.locationPlugin = exports.scrollPlugin = exports.default = exports.snitch = void 0;
+exports.vkmaLaunchPlugin = exports.vkBridgeTransportPlugin = exports.topmailruTransportPlugin = exports.s2sTransportPlugin = exports.beaconTransportPlugin = exports.userPlugin = exports.devicePlugin = exports.useragentPlugin = exports.debugLoggerPlugin = exports.flagPlugin = exports.webVitalsPlugin = exports.exceptionsPlugin = exports.screenPlugin = exports.engagementPlugin = exports.launchPlugin = exports.sessionPlugin = exports.locationPlugin = exports.scrollPlugin = exports.default = exports.snitch = void 0;
 // Core
 var index_1 = require("./packages/snitch/index");
 Object.defineProperty(exports, "snitch", { enumerable: true, get: function () { return __importDefault(index_1).default; } });
@@ -32,16 +32,20 @@ var index_12 = require("./packages/snitch-plugin-debug-logger/index");
 Object.defineProperty(exports, "debugLoggerPlugin", { enumerable: true, get: function () { return __importDefault(index_12).default; } });
 var index_13 = require("./packages/snitch-plugin-useragent/index");
 Object.defineProperty(exports, "useragentPlugin", { enumerable: true, get: function () { return __importDefault(index_13).default; } });
+var index_14 = require("./packages/snitch-plugin-device/index");
+Object.defineProperty(exports, "devicePlugin", { enumerable: true, get: function () { return __importDefault(index_14).default; } });
+var index_15 = require("./packages/snitch-plugin-user/index");
+Object.defineProperty(exports, "userPlugin", { enumerable: true, get: function () { return __importDefault(index_15).default; } });
 // Transports
-var index_14 = require("./packages/snitch-plugin-beacon-transport/index");
-Object.defineProperty(exports, "beaconTransportPlugin", { enumerable: true, get: function () { return __importDefault(index_14).default; } });
-var index_15 = require("./packages/snitch-plugin-s2s-transport/index");
-Object.defineProperty(exports, "s2sTransportPlugin", { enumerable: true, get: function () { return __importDefault(index_15).default; } });
-var index_16 = require("./packages/snitch-plugin-topmailru-transport/index");
-Object.defineProperty(exports, "topmailruTransportPlugin", { enumerable: true, get: function () { return __importDefault(index_16).default; } });
-var index_17 = require("./packages/snitch-plugin-vkbridge-transport/index");
-Object.defineProperty(exports, "vkBridgeTransportPlugin", { enumerable: true, get: function () { return __importDefault(index_17).default; } });
+var index_16 = require("./packages/snitch-plugin-beacon-transport/index");
+Object.defineProperty(exports, "beaconTransportPlugin", { enumerable: true, get: function () { return __importDefault(index_16).default; } });
+var index_17 = require("./packages/snitch-plugin-s2s-transport/index");
+Object.defineProperty(exports, "s2sTransportPlugin", { enumerable: true, get: function () { return __importDefault(index_17).default; } });
+var index_18 = require("./packages/snitch-plugin-topmailru-transport/index");
+Object.defineProperty(exports, "topmailruTransportPlugin", { enumerable: true, get: function () { return __importDefault(index_18).default; } });
+var index_19 = require("./packages/snitch-plugin-vkbridge-transport/index");
+Object.defineProperty(exports, "vkBridgeTransportPlugin", { enumerable: true, get: function () { return __importDefault(index_19).default; } });
 // Platform-specific
-var index_18 = require("./packages/snitch-plugin-vkma-launch/index");
-Object.defineProperty(exports, "vkmaLaunchPlugin", { enumerable: true, get: function () { return __importDefault(index_18).default; } });
+var index_20 = require("./packages/snitch-plugin-vkma-launch/index");
+Object.defineProperty(exports, "vkmaLaunchPlugin", { enumerable: true, get: function () { return __importDefault(index_20).default; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO;AACP,iDAA2D;AAAlD,gHAAA,OAAO,OAAU;AAC1B,iDAAiD;AAAxC,iHAAA,OAAO,OAAA;AAmBhB,UAAU;AACV,+DAA+E;AAAtE,sHAAA,OAAO,OAAgB;AAChC,iEAAmF;AAA1E,wHAAA,OAAO,OAAkB;AAClC,gEAAiF;AAAxE,uHAAA,OAAO,OAAiB;AACjC,+DAA+E;AAAtE,sHAAA,OAAO,OAAgB;AAChC,mEAAuF;AAA9E,0HAAA,OAAO,OAAoB;AACpC,gEAAgF;AAAvE,sHAAA,OAAO,OAAgB;AAChC,mEAAuF;AAA9E,0HAAA,OAAO,OAAoB;AACpC,oEAAsF;AAA7E,0HAAA,OAAO,OAAmB;AACnC,8DAA2E;AAAlE,qHAAA,OAAO,OAAc;AAC9B,sEAA0F;AAAjF,4HAAA,OAAO,OAAqB;AACrC,mEAAqF;AAA5E,0HAAA,OAAO,OAAmB;AAEnC,aAAa;AACb,0EAAkG;AAAzF,gIAAA,OAAO,OAAyB;AACzC,uEAA4F;AAAnF,6HAAA,OAAO,OAAsB;AACtC,6EAAwG;AAA/F,mIAAA,OAAO,OAA4B;AAC5C,4EAAsG;AAA7F,kIAAA,OAAO,OAA2B;AAE3C,oBAAoB;AACpB,qEAAwF;AAA/E,2HAAA,OAAO,OAAoB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO;AACP,iDAA2D;AAAlD,gHAAA,OAAO,OAAU;AAC1B,iDAAiD;AAAxC,iHAAA,OAAO,OAAA;AAmBhB,UAAU;AACV,+DAA+E;AAAtE,sHAAA,OAAO,OAAgB;AAChC,iEAAmF;AAA1E,wHAAA,OAAO,OAAkB;AAClC,gEAAiF;AAAxE,uHAAA,OAAO,OAAiB;AACjC,+DAA+E;AAAtE,sHAAA,OAAO,OAAgB;AAChC,mEAAuF;AAA9E,0HAAA,OAAO,OAAoB;AACpC,gEAAgF;AAAvE,sHAAA,OAAO,OAAgB;AAChC,mEAAuF;AAA9E,0HAAA,OAAO,OAAoB;AACpC,oEAAsF;AAA7E,0HAAA,OAAO,OAAmB;AACnC,8DAA2E;AAAlE,qHAAA,OAAO,OAAc;AAC9B,sEAA0F;AAAjF,4HAAA,OAAO,OAAqB;AACrC,mEAAqF;AAA5E,0HAAA,OAAO,OAAmB;AACnC,gEAA+E;AAAtE,uHAAA,OAAO,OAAgB;AAChC,8DAA2E;AAAlE,qHAAA,OAAO,OAAc;AAE9B,aAAa;AACb,0EAAkG;AAAzF,gIAAA,OAAO,OAAyB;AACzC,uEAA4F;AAAnF,6HAAA,OAAO,OAAsB;AACtC,6EAAwG;AAA/F,mIAAA,OAAO,OAA4B;AAC5C,4EAAsG;AAA7F,kIAAA,OAAO,OAA2B;AAE3C,oBAAoB;AACpB,qEAAwF;AAA/E,2HAAA,OAAO,OAAoB"}

package/dist/packages/snitch-plugin-debug-logger/debug-logger.d.ts

@@ -1,2 +1,2 @@
 import { BeforeCaptureEventHandler, InitializationHandler } from '../common/plugin-interfaces';
-export default function engagementPlugin(): InitializationHandler & BeforeCaptureEventHandler;
+export default function debugLoggerPlugin(): InitializationHandler & BeforeCaptureEventHandler;

package/dist/packages/snitch-plugin-debug-logger/debug-logger.js

@@ -1,9 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = engagementPlugin;
-function engagementPlugin() {
+exports.default = debugLoggerPlugin;
+const STORAGE_KEY = 'snitch:debug';
+function debugLoggerPlugin() {
+    let enabled = false;
+    try {
+        enabled = localStorage.getItem(STORAGE_KEY) === 'true';
+    }
+    catch (_a) { }
     let lastLogTS = null;
     function logLine(message) {
+        if (!enabled)
+            return;
         const now = new Date();
         console.log(`%c[${now.getHours()}:${now.getMinutes()}:${now.getSeconds()}]${lastLogTS ? ` (+${Math.floor((now.getTime() - lastLogTS) / 1e3)}s)` : ''} %cSnitch: %c${message}`, 'color: gray', 'color: black', 'font-weight: bold');
         lastLogTS = now.getTime();
@@ -14,9 +22,9 @@ function engagementPlugin() {
         },
         beforeCaptureEvent(eventName, eventPayload) {
             logLine(`captured event '${eventName}'`);
-            if (eventPayload && Object.keys(eventPayload).length !== 0)
+            if (enabled && eventPayload && Object.keys(eventPayload).length !== 0)
                 console.table(eventPayload);
-        }
+        },
     };
 }
 //# sourceMappingURL=debug-logger.js.map

package/dist/packages/snitch-plugin-debug-logger/debug-logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"debug-logger.js","sourceRoot":"","sources":["../../../packages/snitch-plugin-debug-logger/debug-logger.ts"],"names":[],"mappings":";;AAEA,mCAwBC;AAxBD,SAAwB,gBAAgB;IACtC,IAAI,SAAS,GAAkB,IAAI,CAAA;IACnC,SAAS,OAAO,CAAC,OAAe;QAC9B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;QACtB,OAAO,CAAC,GAAG,CACT,MAAM,GAAG,CAAC,QAAQ,EAAE,IAAI,GAAG,CAAC,UAAU,EAAE,IAAI,GAAG,CAAC,UAAU,EAAE,IAC1D,SAAS,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,GAAI,SAAoB,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EACpF,gBAAgB,OAAO,EAAE,EACzB,aAAa,EACb,cAAc,EACd,mBAAmB,CACpB,CAAA;QACD,SAAS,GAAG,GAAG,CAAC,OAAO,EAAE,CAAA;IAC3B,CAAC;IACD,OAAO;QACL,MAAM;YACJ,OAAO,CAAC,yBAAyB,CAAC,CAAA;QACpC,CAAC;QAED,kBAAkB,CAAC,SAAiB,EAAE,YAAiC;YACrE,OAAO,CAAC,mBAAmB,SAAS,GAAG,CAAC,CAAA;YACxC,IAAI,YAAY,IAAI,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;QACzF,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"debug-logger.js","sourceRoot":"","sources":["../../../packages/snitch-plugin-debug-logger/debug-logger.ts"],"names":[],"mappings":";;AAKA,oCA+BC;AAjCD,MAAM,WAAW,GAAG,cAAc,CAAA;AAElC,SAAwB,iBAAiB;IACvC,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,IAAI,CAAC;QACH,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,MAAM,CAAA;IACxD,CAAC;IAAC,WAAM,CAAC,CAAA,CAAC;IAEV,IAAI,SAAS,GAAkB,IAAI,CAAA;IACnC,SAAS,OAAO,CAAC,OAAe;QAC9B,IAAI,CAAC,OAAO;YAAE,OAAM;QACpB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;QACtB,OAAO,CAAC,GAAG,CACT,MAAM,GAAG,CAAC,QAAQ,EAAE,IAAI,GAAG,CAAC,UAAU,EAAE,IAAI,GAAG,CAAC,UAAU,EAAE,IAC1D,SAAS,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,GAAI,SAAoB,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EACpF,gBAAgB,OAAO,EAAE,EACzB,aAAa,EACb,cAAc,EACd,mBAAmB,CACpB,CAAA;QACD,SAAS,GAAG,GAAG,CAAC,OAAO,EAAE,CAAA;IAC3B,CAAC;IACD,OAAO;QACL,MAAM;YACJ,OAAO,CAAC,yBAAyB,CAAC,CAAA;QACpC,CAAC;QAED,kBAAkB,CAAC,SAAiB,EAAE,YAAiC;YACrE,OAAO,CAAC,mBAAmB,SAAS,GAAG,CAAC,CAAA;YACxC,IAAI,OAAO,IAAI,YAAY,IAAI,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,KAAK,CAAC;gBACnE,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;QAC/B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/packages/snitch-plugin-device/device.d.ts

@@ -0,0 +1,2 @@
+import { EventPayloadParamsProvider } from '../common/plugin-interfaces';
+export default function devicePlugin(): EventPayloadParamsProvider;

package/dist/packages/snitch-plugin-device/device.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = devicePlugin;
+const create_unique_id_1 = __importDefault(require("../common/create-unique-id"));
+const STORAGE_KEY = 'snitch:did';
+function devicePlugin() {
+    let deviceId;
+    try {
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (stored) {
+            deviceId = stored;
+        }
+        else {
+            deviceId = (0, create_unique_id_1.default)();
+            localStorage.setItem(STORAGE_KEY, deviceId);
+        }
+    }
+    catch (_a) {
+        deviceId = (0, create_unique_id_1.default)();
+    }
+    return {
+        getEventPayloadParams() {
+            return { did: deviceId };
+        },
+    };
+}
+//# sourceMappingURL=device.js.map

package/dist/packages/snitch-plugin-device/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../../../packages/snitch-plugin-device/device.ts"],"names":[],"mappings":";;;;;AAKA,+BAoBC;AAzBD,kFAAuD;AAGvD,MAAM,WAAW,GAAG,YAAY,CAAA;AAEhC,SAAwB,YAAY;IAClC,IAAI,QAAgB,CAAA;IAEpB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;QAChD,IAAI,MAAM,EAAE,CAAC;YACX,QAAQ,GAAG,MAAM,CAAA;QACnB,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,IAAA,0BAAc,GAAE,CAAA;YAC3B,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAA;QAC7C,CAAC;IACH,CAAC;IAAC,WAAM,CAAC;QACP,QAAQ,GAAG,IAAA,0BAAc,GAAE,CAAA;IAC7B,CAAC;IAED,OAAO;QACL,qBAAqB;YACnB,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAA;QAC1B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/packages/snitch-plugin-device/index.d.ts

@@ -0,0 +1,2 @@
+import devicePlugin from './device';
+export default devicePlugin;

package/dist/packages/snitch-plugin-device/index.js

@@ -0,0 +1,8 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const device_1 = __importDefault(require("./device"));
+exports.default = device_1.default;
+//# sourceMappingURL=index.js.map

package/dist/packages/snitch-plugin-device/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../packages/snitch-plugin-device/index.ts"],"names":[],"mappings":";;;;;AAAA,sDAAmC;AACnC,kBAAe,gBAAY,CAAA"}

package/dist/packages/snitch-plugin-user/index.d.ts

@@ -0,0 +1,2 @@
+import userPlugin from './user';
+export default userPlugin;

package/dist/packages/snitch-plugin-user/index.js

@@ -0,0 +1,8 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const user_1 = __importDefault(require("./user"));
+exports.default = user_1.default;
+//# sourceMappingURL=index.js.map

package/dist/packages/snitch-plugin-user/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../packages/snitch-plugin-user/index.ts"],"names":[],"mappings":";;;;;AAAA,kDAA+B;AAC/B,kBAAe,cAAU,CAAA"}

package/dist/packages/snitch-plugin-user/user.d.ts

@@ -0,0 +1,2 @@
+import { EventPayloadParamsProvider, EventSource, MixinProvider } from '../common/plugin-interfaces';
+export default function userPlugin(userId?: string): EventPayloadParamsProvider & MixinProvider & EventSource;

package/dist/packages/snitch-plugin-user/user.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = userPlugin;
+function userPlugin(userId) {
+    let uid = userId !== null && userId !== void 0 ? userId : null;
+    let captureEvent;
+    return {
+        setEventHandler(eventHandler) {
+            captureEvent = eventHandler;
+        },
+        getEventPayloadParams() {
+            if (uid) {
+                return { uid };
+            }
+            return {};
+        },
+        getMixins() {
+            return {
+                setUserId(id) {
+                    uid = id;
+                },
+                clearUserId() {
+                    uid = null;
+                },
+                withUserId(id, eventName, eventPayload) {
+                    const prevUid = uid;
+                    uid = id;
+                    captureEvent(eventName, eventPayload);
+                    uid = prevUid;
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=user.js.map

package/dist/packages/snitch-plugin-user/user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.js","sourceRoot":"","sources":["../../../packages/snitch-plugin-user/user.ts"],"names":[],"mappings":";;AAGA,6BAmCC;AAnCD,SAAwB,UAAU,CAChC,MAAe;IAEf,IAAI,GAAG,GAAkB,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,IAAI,CAAA;IACvC,IAAI,YAA0B,CAAA;IAE9B,OAAO;QACL,eAAe,CAAC,YAA0B;YACxC,YAAY,GAAG,YAAY,CAAA;QAC7B,CAAC;QAED,qBAAqB;YACnB,IAAI,GAAG,EAAE,CAAC;gBACR,OAAO,EAAE,GAAG,EAAE,CAAA;YAChB,CAAC;YACD,OAAO,EAAE,CAAA;QACX,CAAC;QAED,SAAS;YACP,OAAO;gBACL,SAAS,CAAC,EAAU;oBAClB,GAAG,GAAG,EAAE,CAAA;gBACV,CAAC;gBACD,WAAW;oBACT,GAAG,GAAG,IAAI,CAAA;gBACZ,CAAC;gBACD,UAAU,CAAC,EAAU,EAAE,SAAiB,EAAE,YAAkC;oBAC1E,MAAM,OAAO,GAAG,GAAG,CAAA;oBACnB,GAAG,GAAG,EAAE,CAAA;oBACR,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAA;oBACrC,GAAG,GAAG,OAAO,CAAA;gBACf,CAAC;aACF,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borisch/snitch",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Modular analytics tracking library with pluggable transports",
   "keywords": [
     "analytics",