@rudderjs/pulse 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleiman Shahbari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @rudderjs/pulse
+
+Application performance monitoring for RudderJS — aggregates request throughput, queue metrics, cache hit rates, exceptions, active users, slow queries, and server resource usage.
+
+## Installation
+
+```bash
+pnpm add @rudderjs/pulse
+```
+
+## Setup
+
+```ts
+// bootstrap/providers.ts
+import { pulse } from '@rudderjs/pulse'
+import configs from '../config/index.js'
+export default [..., pulse(configs.pulse), ...]
+```
+
+## Pulse Facade
+
+```ts
+import { Pulse } from '@rudderjs/pulse'
+
+// Record a metric
+Pulse.record('request_duration', 142)
+Pulse.record('cache_hits', 1, 'user-cache')
+
+// Query aggregates
+const since = new Date(Date.now() - 3600_000) // last hour
+const requestMetrics = await Pulse.aggregates('request_count', since)
+const cacheMetrics   = await Pulse.aggregates('cache_hits', since, 'user-cache')
+
+// Get entries (slow requests, exceptions, etc.)
+const slowRequests = await Pulse.entries('slow_request', { perPage: 25 })
+
+// Overview of all metrics
+const overview = await Pulse.overview(since)
+```
+
+## `Pulse` Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `record(type, value, key?)` | `void` | Increment an aggregate bucket |
+| `aggregates(type, since, key?)` | `PulseAggregate[]` | Aggregates for a metric type within a period |
+| `entries(type, options?)` | `PulseEntry[]` | Individual entries (slow requests, exceptions) |
+| `overview(since)` | `PulseAggregate[]` | All aggregates since a given date |
+
+## Metric Types
+
+| Type | Source |
+|------|--------|
+| `request_count` | Request middleware |
+| `request_duration` | Request middleware |
+| `queue_throughput` | Queue aggregator |
+| `queue_wait_time` | Queue aggregator |
+| `cache_hits` / `cache_misses` | Cache aggregator |
+| `exceptions` | Exception aggregator |
+| `active_users` | User aggregator middleware |
+| `server_cpu` / `server_memory` | Server aggregator (periodic) |
+
+## Storage Drivers
+
+- **`memory`** (default) — In-process, capped at `maxEntries`. Good for development.
+- **`sqlite`** — Persistent storage via `better-sqlite3`. Run `pnpm add better-sqlite3` to enable.
+
+## Configuration
+
+```ts
+// config/pulse.ts
+export default {
+  enabled: true,
+  path: 'pulse',
+  storage: 'memory',
+  sqlitePath: '.pulse.db',
+  pruneAfterHours: 168,            // 7 days
+  slowRequestThreshold: 1000,      // ms
+  slowQueryThreshold: 100,         // ms
+  recordRequests: true,
+  recordQueues: true,
+  recordCache: true,
+  recordExceptions: true,
+  recordUsers: true,
+  recordServers: true,
+  serverStatsIntervalMs: 15_000,
+  auth: null,
+} satisfies PulseConfig
+```
+
+## Aggregators
+
+Pulse auto-registers aggregators based on config:
+
+- **RequestAggregator** — Tracks request throughput and duration via middleware
+- **QueueAggregator** — Tracks queue throughput and wait times
+- **CacheAggregator** — Tracks cache hit/miss rates
+- **ExceptionAggregator** — Counts unhandled exceptions
+- **QueryAggregator** — Records slow database queries
+- **UserAggregator** — Tracks unique active users via middleware
+- **ServerAggregator** — Periodically records CPU and memory usage
+
+## Notes
+
+- Auto-prune runs on a background interval.
+- Optional peers: `@rudderjs/log`, `@rudderjs/orm`, `@rudderjs/cache`, `@rudderjs/queue`.
+- Dashboard served at `/{path}` with auto-refreshing metric cards.

package/boost/guidelines.md

@@ -0,0 +1,33 @@
+# @rudderjs/pulse — AI Coding Guidelines
+
+## What This Package Does
+
+Pulse is an application metrics dashboard for RudderJS applications. It aggregates time-series data (request throughput, cache hit rates, queue metrics, server stats) into 1-minute buckets and exposes a JSON API for visualization.
+
+## Architecture
+
+Two data models:
+1. **Aggregates** — Time-bucketed metrics (1-minute resolution). Used for throughput, duration, hit rates.
+2. **Entries** — Individual notable events (slow requests, slow queries, exceptions, failed jobs).
+
+Seven aggregators collect data:
+- `RequestAggregator` — middleware: request count + duration
+- `QueueAggregator` — wraps adapter: throughput + wait time + failures
+- `CacheAggregator` — wraps adapter: hit/miss counting
+- `ExceptionAggregator` — exception reporter hook
+- `UserAggregator` — middleware: unique users per minute
+- `QueryAggregator` — ORM hook: slow query detection
+- `ServerAggregator` — periodic: CPU + memory
+
+## Key Patterns
+
+- Aggregators implement the `Aggregator` interface with `register()` method
+- `storage.record(type, value, key?)` increments a 1-minute bucket aggregate
+- `storage.storeEntry(type, content)` records individual notable events
+- API endpoints support `?period=1h|6h|24h|7d` for time range selection
+
+## Do NOT
+
+- Import peer dependencies statically — always use dynamic `import()` with try/catch
+- Record Pulse's own API requests (request aggregator skips `/pulse*`)
+- Store high-cardinality keys in aggregates — keep `key` to queue names, route patterns, not full URLs

package/dist/aggregators/cache.d.ts

@@ -0,0 +1,11 @@
+import type { Aggregator, PulseStorage } from '../types.js';
+/**
+ * Tracks cache hit/miss ratio by wrapping the CacheRegistry adapter.
+ */
+export declare class CacheAggregator implements Aggregator {
+    private readonly storage;
+    readonly name = "Cache Aggregator";
+    constructor(storage: PulseStorage);
+    register(): Promise<void>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/aggregators/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/aggregators/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE3D;;GAEG;AACH,qBAAa,eAAgB,YAAW,UAAU;IAGpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,IAAI,sBAAqB;gBAEL,OAAO,EAAE,YAAY;IAE5C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAsBhC"}

package/dist/aggregators/cache.js

@@ -0,0 +1,34 @@
+/**
+ * Tracks cache hit/miss ratio by wrapping the CacheRegistry adapter.
+ */
+export class CacheAggregator {
+    storage;
+    name = 'Cache Aggregator';
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async register() {
+        try {
+            const { CacheRegistry } = await import('@rudderjs/cache');
+            const adapter = CacheRegistry.get();
+            if (!adapter)
+                return;
+            const storage = this.storage;
+            const origGet = adapter.get.bind(adapter);
+            adapter['get'] = async (key) => {
+                const value = await origGet(key);
+                if (value !== null) {
+                    storage.record('cache_hits', 1);
+                }
+                else {
+                    storage.record('cache_misses', 1);
+                }
+                return value;
+            };
+        }
+        catch {
+            // @rudderjs/cache not installed — skip
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/aggregators/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/aggregators/cache.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,eAAe;IAGG;IAFpB,IAAI,GAAG,kBAAkB,CAAA;IAElC,YAA6B,OAAqB;QAArB,YAAO,GAAP,OAAO,CAAc;IAAG,CAAC;IAEtD,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC;YACH,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAA;YACzD,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,EAAE,CAAA;YACnC,IAAI,CAAC,OAAO;gBAAE,OAAM;YAEpB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;YAC5B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAExC;YAAC,OAA8C,CAAC,KAAK,CAAC,GAAG,KAAK,EAAe,GAAW,EAAqB,EAAE;gBAC9G,MAAM,KAAK,GAAG,MAAO,OAA8C,CAAC,GAAG,CAAC,CAAA;gBACxE,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;oBACnB,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAA;gBACjC,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAA;gBACnC,CAAC;gBACD,OAAO,KAAK,CAAA;YACd,CAAC,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uCAAuC;QACzC,CAAC;IACH,CAAC;CACF"}

package/dist/aggregators/exception.d.ts

@@ -0,0 +1,11 @@
+import type { Aggregator, PulseStorage } from '../types.js';
+/**
+ * Tracks exception count over time by hooking into the exception reporter.
+ */
+export declare class ExceptionAggregator implements Aggregator {
+    private readonly storage;
+    readonly name = "Exception Aggregator";
+    constructor(storage: PulseStorage);
+    register(): Promise<void>;
+}
+//# sourceMappingURL=exception.d.ts.map

package/dist/aggregators/exception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exception.d.ts","sourceRoot":"","sources":["../../src/aggregators/exception.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE3D;;GAEG;AACH,qBAAa,mBAAoB,YAAW,UAAU;IAGxC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,IAAI,0BAAyB;gBAET,OAAO,EAAE,YAAY;IAE5C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAuBhC"}

package/dist/aggregators/exception.js

@@ -0,0 +1,30 @@
+/**
+ * Tracks exception count over time by hooking into the exception reporter.
+ */
+export class ExceptionAggregator {
+    storage;
+    name = 'Exception Aggregator';
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async register() {
+        try {
+            const { setExceptionReporter, report } = await import('@rudderjs/core');
+            const storage = this.storage;
+            const previousReport = report;
+            setExceptionReporter((err) => {
+                storage.record('exceptions', 1);
+                const isError = err instanceof Error;
+                storage.storeEntry('exception', {
+                    class: isError ? err.constructor.name : 'Unknown',
+                    message: isError ? err.message : String(err),
+                });
+                previousReport(err);
+            });
+        }
+        catch {
+            // Should not fail
+        }
+    }
+}
+//# sourceMappingURL=exception.js.map

package/dist/aggregators/exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exception.js","sourceRoot":"","sources":["../../src/aggregators/exception.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,mBAAmB;IAGD;IAFpB,IAAI,GAAG,sBAAsB,CAAA;IAEtC,YAA6B,OAAqB;QAArB,YAAO,GAAP,OAAO,CAAc;IAAG,CAAC;IAEtD,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC;YACH,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAGrE,CAAA;YAED,MAAM,OAAO,GAAU,IAAI,CAAC,OAAO,CAAA;YACnC,MAAM,cAAc,GAAG,MAAM,CAAA;YAE7B,oBAAoB,CAAC,CAAC,GAAY,EAAE,EAAE;gBACpC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAA;gBAC/B,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAA;gBACpC,OAAO,CAAC,UAAU,CAAC,WAAW,EAAE;oBAC9B,KAAK,EAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;oBACnD,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBAC7C,CAAC,CAAA;gBACF,cAAc,CAAC,GAAG,CAAC,CAAA;YACrB,CAAC,CAAC,CAAA;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;CACF"}

package/dist/aggregators/query.d.ts

@@ -0,0 +1,12 @@
+import type { Aggregator, PulseStorage, PulseConfig } from '../types.js';
+/**
+ * Tracks slow database queries by hooking into the ORM adapter.
+ */
+export declare class QueryAggregator implements Aggregator {
+    private readonly storage;
+    private readonly config;
+    readonly name = "Query Aggregator";
+    constructor(storage: PulseStorage, config: PulseConfig);
+    register(): Promise<void>;
+}
+//# sourceMappingURL=query.d.ts.map

package/dist/aggregators/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/aggregators/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAExE;;GAEG;AACH,qBAAa,eAAgB,YAAW,UAAU;IAI9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,QAAQ,CAAC,IAAI,sBAAqB;gBAGf,OAAO,EAAE,YAAY,EACrB,MAAM,EAAG,WAAW;IAGjC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA4BhC"}

package/dist/aggregators/query.js

@@ -0,0 +1,39 @@
+/**
+ * Tracks slow database queries by hooking into the ORM adapter.
+ */
+export class QueryAggregator {
+    storage;
+    config;
+    name = 'Query Aggregator';
+    constructor(storage, config) {
+        this.storage = storage;
+        this.config = config;
+    }
+    async register() {
+        try {
+            const orm = await import('@rudderjs/orm');
+            const registry = orm.ModelRegistry;
+            if (!registry.getAdapter)
+                return;
+            const adapter = registry.getAdapter();
+            if (!adapter?.onQuery)
+                return;
+            const storage = this.storage;
+            const threshold = this.config.slowQueryThreshold ?? 100;
+            adapter.onQuery((info) => {
+                if (info.duration > threshold) {
+                    storage.storeEntry('slow_query', {
+                        sql: info.sql,
+                        bindings: info.bindings,
+                        duration: info.duration,
+                        model: info.model,
+                    });
+                }
+            });
+        }
+        catch {
+            // @rudderjs/orm not installed — skip
+        }
+    }
+}
+//# sourceMappingURL=query.js.map

package/dist/aggregators/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/aggregators/query.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,eAAe;IAIP;IACA;IAJV,IAAI,GAAG,kBAAkB,CAAA;IAElC,YACmB,OAAqB,EACrB,MAAoB;QADpB,YAAO,GAAP,OAAO,CAAc;QACrB,WAAM,GAAN,MAAM,CAAc;IACpC,CAAC;IAEJ,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAA;YACzC,MAAM,QAAQ,GAAG,GAAG,CAAC,aAEpB,CAAA;YACD,IAAI,CAAC,QAAQ,CAAC,UAAU;gBAAE,OAAM;YAEhC,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,EAAE,CAAA;YACrC,IAAI,CAAC,OAAO,EAAE,OAAO;gBAAE,OAAM;YAE7B,MAAM,OAAO,GAAK,IAAI,CAAC,OAAO,CAAA;YAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,kBAAkB,IAAI,GAAG,CAAA;YAEvD,OAAO,CAAC,OAAO,CAAC,CAAC,IAAe,EAAE,EAAE;gBAClC,IAAI,IAAI,CAAC,QAAQ,GAAG,SAAS,EAAE,CAAC;oBAC9B,OAAO,CAAC,UAAU,CAAC,YAAY,EAAE;wBAC/B,GAAG,EAAO,IAAI,CAAC,GAAG;wBAClB,QAAQ,EAAE,IAAI,CAAC,QAAQ;wBACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;wBACvB,KAAK,EAAK,IAAI,CAAC,KAAK;qBACrB,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,qCAAqC;QACvC,CAAC;IACH,CAAC;CACF"}

package/dist/aggregators/queue.d.ts

@@ -0,0 +1,12 @@
+import type { Aggregator, PulseStorage } from '../types.js';
+/**
+ * Tracks queue throughput, wait time, and failed jobs.
+ * Wraps the QueueRegistry adapter's dispatch method.
+ */
+export declare class QueueAggregator implements Aggregator {
+    private readonly storage;
+    readonly name = "Queue Aggregator";
+    constructor(storage: PulseStorage);
+    register(): Promise<void>;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/aggregators/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/aggregators/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE3D;;;GAGG;AACH,qBAAa,eAAgB,YAAW,UAAU;IAGpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,IAAI,sBAAqB;gBAEL,OAAO,EAAE,YAAY;IAE5C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAiChC"}

package/dist/aggregators/queue.js

@@ -0,0 +1,43 @@
+/**
+ * Tracks queue throughput, wait time, and failed jobs.
+ * Wraps the QueueRegistry adapter's dispatch method.
+ */
+export class QueueAggregator {
+    storage;
+    name = 'Queue Aggregator';
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async register() {
+        try {
+            const { QueueRegistry } = await import('@rudderjs/queue');
+            const adapter = QueueRegistry.get();
+            if (!adapter)
+                return;
+            const storage = this.storage;
+            const originalDispatch = adapter.dispatch.bind(adapter);
+            adapter['dispatch'] = async (job, options) => {
+                const dispatchedAt = Date.now();
+                try {
+                    await originalDispatch(job, options);
+                    const duration = Date.now() - dispatchedAt;
+                    storage.record('queue_throughput', 1);
+                    storage.record('queue_wait_time', duration);
+                }
+                catch (err) {
+                    storage.record('queue_throughput', 1);
+                    const j = job;
+                    storage.storeEntry('failed_job', {
+                        class: j.constructor.name,
+                        exception: err instanceof Error ? err.message : String(err),
+                    });
+                    throw err;
+                }
+            };
+        }
+        catch {
+            // @rudderjs/queue not installed — skip
+        }
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/aggregators/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/aggregators/queue.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,eAAe;IAGG;IAFpB,IAAI,GAAG,kBAAkB,CAAA;IAElC,YAA6B,OAAqB;QAArB,YAAO,GAAP,OAAO,CAAc;IAAG,CAAC;IAEtD,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC;YACH,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAA;YACzD,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,EAAE,CAAA;YACnC,IAAI,CAAC,OAAO;gBAAE,OAAM;YAEpB,MAAM,OAAO,GAAY,IAAI,CAAC,OAAO,CAAA;YACrC,MAAM,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAEtD;YAAC,OAA8C,CAAC,UAAU,CAAC,GAAG,KAAK,EAClE,GAAY,EACZ,OAAiB,EACF,EAAE;gBACjB,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;gBAC/B,IAAI,CAAC;oBACH,MAAO,gBAA0D,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;oBAC/E,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAA;oBAC1C,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAA;oBACrC,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAA;gBAC7C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAA;oBACrC,MAAM,CAAC,GAAG,GAAwC,CAAA;oBAClD,OAAO,CAAC,UAAU,CAAC,YAAY,EAAE;wBAC/B,KAAK,EAAM,CAAC,CAAC,WAAW,CAAC,IAAI;wBAC7B,SAAS,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;qBAC5D,CAAC,CAAA;oBACF,MAAM,GAAG,CAAA;gBACX,CAAC;YACH,CAAC,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uCAAuC;QACzC,CAAC;IACH,CAAC;CACF"}

package/dist/aggregators/request.d.ts

@@ -0,0 +1,15 @@
+import type { AppRequest, AppResponse } from '@rudderjs/contracts';
+import type { Aggregator, PulseStorage, PulseConfig } from '../types.js';
+/**
+ * Tracks request throughput, duration (p50/p95/p99), and slow requests.
+ * Installs as global middleware.
+ */
+export declare class RequestAggregator implements Aggregator {
+    private readonly storage;
+    private readonly config;
+    readonly name = "Request Aggregator";
+    constructor(storage: PulseStorage, config: PulseConfig);
+    register(): void;
+    middleware(): (req: AppRequest, res: AppResponse, next: () => Promise<void>) => Promise<void>;
+}
+//# sourceMappingURL=request.d.ts.map

package/dist/aggregators/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/aggregators/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGxE;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IAIhD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,QAAQ,CAAC,IAAI,wBAAuB;gBAGjB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAG,WAAW;IAGvC,QAAQ,IAAI,IAAI;IAIhB,UAAU,KAKM,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC;CAyB7E"}

package/dist/aggregators/request.js

@@ -0,0 +1,46 @@
+import { isAsset } from '../utils.js';
+/**
+ * Tracks request throughput, duration (p50/p95/p99), and slow requests.
+ * Installs as global middleware.
+ */
+export class RequestAggregator {
+    storage;
+    config;
+    name = 'Request Aggregator';
+    constructor(storage, config) {
+        this.storage = storage;
+        this.config = config;
+    }
+    register() {
+        // Middleware is registered by the service provider
+    }
+    middleware() {
+        const storage = this.storage;
+        const threshold = this.config.slowRequestThreshold ?? 1000;
+        const ignore = this.config.path ?? 'pulse';
+        return async (req, res, next) => {
+            // Skip pulse's own routes
+            if (req.path.startsWith(`/${ignore}`))
+                return next();
+            // Skip Vite internals, source files, and static assets
+            if (isAsset(req.path))
+                return next();
+            const start = Date.now();
+            await next();
+            const duration = Date.now() - start;
+            // Record aggregates
+            storage.record('request_count', 1);
+            storage.record('request_duration', duration);
+            // Slow request entry
+            if (duration > threshold) {
+                storage.storeEntry('slow_request', {
+                    method: req.method,
+                    url: req.url,
+                    path: req.path,
+                    duration,
+                });
+            }
+        };
+    }
+}
+//# sourceMappingURL=request.js.map

package/dist/aggregators/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/aggregators/request.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IAIT;IACA;IAJV,IAAI,GAAG,oBAAoB,CAAA;IAEpC,YACmB,OAAqB,EACrB,MAAoB;QADpB,YAAO,GAAP,OAAO,CAAc;QACrB,WAAM,GAAN,MAAM,CAAc;IACpC,CAAC;IAEJ,QAAQ;QACN,mDAAmD;IACrD,CAAC;IAED,UAAU;QACR,MAAM,OAAO,GAAK,IAAI,CAAC,OAAO,CAAA;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,oBAAoB,IAAI,IAAI,CAAA;QAC1D,MAAM,MAAM,GAAM,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,OAAO,CAAA;QAE7C,OAAO,KAAK,EAAE,GAAe,EAAE,GAAgB,EAAE,IAAyB,EAAE,EAAE;YAC5E,0BAA0B;YAC1B,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,MAAM,EAAE,CAAC;gBAAE,OAAO,IAAI,EAAE,CAAA;YACpD,uDAAuD;YACvD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,EAAE,CAAA;YAEpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YACxB,MAAM,IAAI,EAAE,CAAA;YACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAA;YAEnC,oBAAoB;YACpB,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC,CAAA;YAClC,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAA;YAE5C,qBAAqB;YACrB,IAAI,QAAQ,GAAG,SAAS,EAAE,CAAC;gBACzB,OAAO,CAAC,UAAU,CAAC,cAAc,EAAE;oBACjC,MAAM,EAAI,GAAG,CAAC,MAAM;oBACpB,GAAG,EAAO,GAAG,CAAC,GAAG;oBACjB,IAAI,EAAM,GAAG,CAAC,IAAI;oBAClB,QAAQ;iBACT,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAA;IACH,CAAC;CACF"}

package/dist/aggregators/server.d.ts

@@ -0,0 +1,13 @@
+import type { Aggregator, PulseStorage } from '../types.js';
+/**
+ * Periodically collects server resource metrics — CPU usage and memory.
+ */
+export declare class ServerAggregator implements Aggregator {
+    private readonly storage;
+    private readonly intervalMs;
+    readonly name = "Server Aggregator";
+    constructor(storage: PulseStorage, intervalMs?: number);
+    register(): void;
+    private collect;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/aggregators/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/aggregators/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE3D;;GAEG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IAI/C,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAJ7B,QAAQ,CAAC,IAAI,uBAAsB;gBAGhB,OAAO,EAAE,YAAY,EACrB,UAAU,GAAE,MAAe;IAG9C,QAAQ,IAAI,IAAI;IAOhB,OAAO,CAAC,OAAO;CAiBhB"}

package/dist/aggregators/server.js

@@ -0,0 +1,35 @@
+import { cpus, totalmem, freemem } from 'node:os';
+/**
+ * Periodically collects server resource metrics — CPU usage and memory.
+ */
+export class ServerAggregator {
+    storage;
+    intervalMs;
+    name = 'Server Aggregator';
+    constructor(storage, intervalMs = 15_000) {
+        this.storage = storage;
+        this.intervalMs = intervalMs;
+    }
+    register() {
+        const timer = setInterval(() => this.collect(), this.intervalMs);
+        timer.unref();
+        // Collect once immediately
+        this.collect();
+    }
+    collect() {
+        // CPU — average load across cores (0–100)
+        const cores = cpus();
+        const cpuPercent = cores.reduce((sum, core) => {
+            const total = Object.values(core.times).reduce((a, b) => a + b, 0);
+            const idle = core.times.idle;
+            return sum + ((total - idle) / total) * 100;
+        }, 0) / cores.length;
+        this.storage.record('server_cpu', Math.round(cpuPercent * 100) / 100);
+        // Memory — used percentage
+        const total = totalmem();
+        const free = freemem();
+        const usedPercent = ((total - free) / total) * 100;
+        this.storage.record('server_memory', Math.round(usedPercent * 100) / 100);
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/aggregators/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/aggregators/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAGjD;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAIR;IACA;IAJV,IAAI,GAAG,mBAAmB,CAAA;IAEnC,YACmB,OAAqB,EACrB,aAAqB,MAAM;QAD3B,YAAO,GAAP,OAAO,CAAc;QACrB,eAAU,GAAV,UAAU,CAAiB;IAC3C,CAAC;IAEJ,QAAQ;QACN,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;QAChE,KAAK,CAAC,KAAK,EAAE,CAAA;QACb,2BAA2B;QAC3B,IAAI,CAAC,OAAO,EAAE,CAAA;IAChB,CAAC;IAEO,OAAO;QACb,0CAA0C;QAC1C,MAAM,KAAK,GAAG,IAAI,EAAE,CAAA;QACpB,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;YAClE,MAAM,IAAI,GAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAA;YAC7B,OAAO,GAAG,GAAG,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,CAAA;QAC7C,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAA;QAEpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAA;QAErE,2BAA2B;QAC3B,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAA;QACxB,MAAM,IAAI,GAAI,OAAO,EAAE,CAAA;QACvB,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,CAAA;QAClD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAA;IAC3E,CAAC;CACF"}

package/dist/aggregators/user.d.ts

@@ -0,0 +1,17 @@
+import type { AppRequest, AppResponse } from '@rudderjs/contracts';
+import type { Aggregator, PulseStorage } from '../types.js';
+/**
+ * Tracks active (unique) users per minute bucket.
+ * Identifies users by session cookie, auth header, or IP.
+ */
+export declare class UserAggregator implements Aggregator {
+    private readonly storage;
+    readonly name = "User Aggregator";
+    private readonly seen;
+    private currentMinute;
+    constructor(storage: PulseStorage);
+    register(): void;
+    middleware(): (req: AppRequest, _res: AppResponse, next: () => Promise<void>) => Promise<void>;
+    private identifyUser;
+}
+//# sourceMappingURL=user.d.ts.map

package/dist/aggregators/user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/aggregators/user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG3D;;;GAGG;AACH,qBAAa,cAAe,YAAW,UAAU;IAKnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,QAAQ,CAAC,IAAI,qBAAoB;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,aAAa,CAAI;gBAEI,OAAO,EAAE,YAAY;IAElD,QAAQ,IAAI,IAAI;IAIhB,UAAU,KAGM,KAAK,UAAU,EAAE,MAAM,WAAW,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC;IAoB7E,OAAO,CAAC,YAAY;CAWrB"}

package/dist/aggregators/user.js

@@ -0,0 +1,48 @@
+import { isAsset } from '../utils.js';
+/**
+ * Tracks active (unique) users per minute bucket.
+ * Identifies users by session cookie, auth header, or IP.
+ */
+export class UserAggregator {
+    storage;
+    name = 'User Aggregator';
+    seen = new Set();
+    currentMinute = 0;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    register() {
+        // Middleware is registered by the service provider
+    }
+    middleware() {
+        const storage = this.storage;
+        return async (req, _res, next) => {
+            // Skip Vite internals, source files, and static assets
+            if (isAsset(req.path))
+                return next();
+            const minute = Math.floor(Date.now() / 60_000);
+            if (minute !== this.currentMinute) {
+                this.seen.clear();
+                this.currentMinute = minute;
+            }
+            const userId = this.identifyUser(req);
+            if (!this.seen.has(userId)) {
+                this.seen.add(userId);
+                storage.record('active_users', 1);
+            }
+            return next();
+        };
+    }
+    identifyUser(req) {
+        // Prefer auth user, then session, then IP
+        const auth = req.headers['authorization'];
+        if (auth)
+            return `auth:${auth.slice(0, 40)}`;
+        const cookie = req.headers['cookie'] ?? '';
+        const session = cookie.match(/(?:^|;\s*)session=([^;]+)/)?.[1];
+        if (session)
+            return `session:${session}`;
+        return `ip:${req.headers['x-forwarded-for']?.split(',')[0]?.trim() ?? req.headers['x-real-ip'] ?? 'unknown'}`;
+    }
+}
+//# sourceMappingURL=user.js.map

package/dist/aggregators/user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.js","sourceRoot":"","sources":["../../src/aggregators/user.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,MAAM,OAAO,cAAc;IAKI;IAJpB,IAAI,GAAG,iBAAiB,CAAA;IAChB,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IACjC,aAAa,GAAG,CAAC,CAAA;IAEzB,YAA6B,OAAqB;QAArB,YAAO,GAAP,OAAO,CAAc;IAAG,CAAC;IAEtD,QAAQ;QACN,mDAAmD;IACrD,CAAC;IAED,UAAU;QACR,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;QAE5B,OAAO,KAAK,EAAE,GAAe,EAAE,IAAiB,EAAE,IAAyB,EAAE,EAAE;YAC7E,uDAAuD;YACvD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,EAAE,CAAA;YAEpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,CAAA;YAC9C,IAAI,MAAM,KAAK,IAAI,CAAC,aAAa,EAAE,CAAC;gBAClC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAA;gBACjB,IAAI,CAAC,aAAa,GAAG,MAAM,CAAA;YAC7B,CAAC;YAED,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;YACrC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;gBACrB,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAA;YACnC,CAAC;YAED,OAAO,IAAI,EAAE,CAAA;QACf,CAAC,CAAA;IACH,CAAC;IAEO,YAAY,CAAC,GAAe;QAClC,0CAA0C;QAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAA;QACzC,IAAI,IAAI;YAAE,OAAO,QAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAA;QAE5C,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAA;QAC1C,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,2BAA2B,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAC9D,IAAI,OAAO;YAAE,OAAO,WAAW,OAAO,EAAE,CAAA;QAExC,OAAO,MAAM,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,SAAS,EAAE,CAAA;IAC/G,CAAC;CACF"}

package/dist/api/routes.d.ts

@@ -0,0 +1,6 @@
+import type { PulseStorage, PulseConfig } from '../types.js';
+/**
+ * Register all Pulse API routes on the router.
+ */
+export declare function registerRoutes(storage: PulseStorage, config: PulseConfig): Promise<void>;
+//# sourceMappingURL=routes.d.ts.map

package/dist/api/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/api/routes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAc,MAAM,aAAa,CAAA;AAexE;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAG,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAkJf"}