@borisch/snitch 1.1.0 → 1.2.0

package/README.md

@@ -8,7 +8,7 @@ Modular analytics tracking library. Compose your tracker from small, focused plu
 npm install @borisch/snitch
 ```
 
-## Quick Start
+## Quick Start (Browser)
 
 ```ts
 import {
@@ -38,6 +38,47 @@ const captureEvent = snitch(
 captureEvent('button_click', { buttonId: 'signup' })
 ```
 
+## Server-Side Usage
+
+Many plugins use browser APIs (`window`, `document`, `localStorage`). Importing `@borisch/snitch` on the server will fail because some plugins reference `window` at the module level.
+
+Use the server entry point instead:
+
+```ts
+import {
+  snitch,
+  userPlugin,
+  devicePlugin,
+  screenPlugin,
+  debugLoggerPlugin,
+  s2sTransportPlugin,
+} from '@borisch/snitch/server'
+```
+
+The server entry point exports only the plugins and transports that work without browser APIs:
+
+| Export               | Description                                                |
+| -------------------- | ---------------------------------------------------------- |
+| `snitch`             | Core factory function                                      |
+| `userPlugin`         | In-memory user ID tracking                                 |
+| `devicePlugin`       | Device ID (falls back to random ID without `localStorage`) |
+| `screenPlugin`       | Screen tracking (pure state management)                    |
+| `debugLoggerPlugin`  | Console logger (silently disabled without `localStorage`)  |
+| `s2sTransportPlugin` | HTTP transport via `fetch()` (available in Node 18+)       |
+
+All types are also re-exported from `@borisch/snitch/server`.
+
+**Example — server-side event tracking:**
+
+```ts
+import { snitch, userPlugin, s2sTransportPlugin } from '@borisch/snitch/server'
+
+const track = snitch(userPlugin(), s2sTransportPlugin({ hostname: 'analytics.example.com' })) as any
+
+// One-shot event with a specific user ID
+track.withUserId(req.userId, 'checkout_completed', { orderId: '12345' })
+```
+
 The `snitch()` function accepts any number of plugins and returns a `captureEvent` function. Plugins can:
 
 - **Provide event parameters** — automatically attached to every event

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+export { default as snitch } from './packages/snitch/index';
+export { default } from './packages/snitch/index';
+export type { Plugin, EventPayloadParamsProvider, InitializationHandler, EventSource, BeforeCaptureEventHandler, EventTransport, MixinProvider, } from './packages/common/plugin-interfaces';
+export type { TrackerEventPayload, EventHandler, TrackerInitializationOptions, } from './packages/common/tracker-interfaces';
+export { default as screenPlugin } from './packages/snitch-plugin-screens/index';
+export { default as debugLoggerPlugin } from './packages/snitch-plugin-debug-logger/index';
+export { default as devicePlugin } from './packages/snitch-plugin-device/index';
+export { default as userPlugin } from './packages/snitch-plugin-user/index';
+export { default as s2sTransportPlugin } from './packages/snitch-plugin-s2s-transport/index';

package/dist/server.js

@@ -0,0 +1,26 @@
+"use strict";
+// Server-safe entry point — no browser APIs required.
+// Usage: import { snitch, userPlugin, ... } from '@borisch/snitch/server'
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.s2sTransportPlugin = exports.userPlugin = exports.devicePlugin = exports.debugLoggerPlugin = exports.screenPlugin = 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; } });
+var index_2 = require("./packages/snitch/index");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(index_2).default; } });
+// Server-safe plugins
+var index_3 = require("./packages/snitch-plugin-screens/index");
+Object.defineProperty(exports, "screenPlugin", { enumerable: true, get: function () { return __importDefault(index_3).default; } });
+var index_4 = require("./packages/snitch-plugin-debug-logger/index");
+Object.defineProperty(exports, "debugLoggerPlugin", { enumerable: true, get: function () { return __importDefault(index_4).default; } });
+var index_5 = require("./packages/snitch-plugin-device/index");
+Object.defineProperty(exports, "devicePlugin", { enumerable: true, get: function () { return __importDefault(index_5).default; } });
+var index_6 = require("./packages/snitch-plugin-user/index");
+Object.defineProperty(exports, "userPlugin", { enumerable: true, get: function () { return __importDefault(index_6).default; } });
+// Server-safe transports
+var index_7 = require("./packages/snitch-plugin-s2s-transport/index");
+Object.defineProperty(exports, "s2sTransportPlugin", { enumerable: true, get: function () { return __importDefault(index_7).default; } });
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":";AAAA,sDAAsD;AACtD,0EAA0E;;;;;;AAE1E,OAAO;AACP,iDAA2D;AAAlD,gHAAA,OAAO,OAAU;AAC1B,iDAAiD;AAAxC,iHAAA,OAAO,OAAA;AAmBhB,sBAAsB;AACtB,gEAAgF;AAAvE,sHAAA,OAAO,OAAgB;AAChC,qEAA0F;AAAjF,2HAAA,OAAO,OAAqB;AACrC,+DAA+E;AAAtE,sHAAA,OAAO,OAAgB;AAChC,6DAA2E;AAAlE,oHAAA,OAAO,OAAc;AAE9B,yBAAyB;AACzB,sEAA4F;AAAnF,4HAAA,OAAO,OAAsB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borisch/snitch",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Modular analytics tracking library with pluggable transports",
   "keywords": [
     "analytics",
@@ -11,6 +11,16 @@
   ],
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
   "files": [
     "dist"
   ],