@prath/observability-sdk 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @prath/observability-sdk
+
+A minimal, dependency-light client for sending metrics and logs to a network-observer
+ingestion endpoint. Batches events in memory and flushes them off your app's hot path —
+this package is never the reason your service runs out of memory or slows down.
+
+## Install
+
+```bash
+npm install @prath/observability-sdk
+```
+
+## Quick start
+
+```ts
+import { ObservabilityClient } from "@prath/observability-sdk";
+
+const client = new ObservabilityClient({
+  apiKey: process.env.OBS_API_KEY!,
+  endpoint: "https://your-backend.com/ingest",
+  flushIntervalMs: 5000,
+  maxBatchSize: 100,
+});
+
+client.track("checkout.duration_ms", 245, { region: "us-east" });
+client.log("error", "Payment failed", { orderId: "123" });
+
+process.on("SIGTERM", () => client.flush());
+```
+
+## API reference
+
+### `new ObservabilityClient(options)`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | required | Per-service API key sent as a bearer token. |
+| `endpoint` | `string` | required | Ingestion endpoint URL, e.g. `https://host/ingest`. |
+| `flushIntervalMs` | `number` | `5000` | Flush the batch on this interval regardless of size. |
+| `maxBatchSize` | `number` | `100` | Flush immediately once this many events are buffered. |
+| `maxQueueSize` | `number` | `1000` | Upper bound on buffered events; oldest are dropped past this. |
+| `maxRetries` | `number` | `3` | Retry attempts per flush before dropping that batch. |
+| `retryBaseDelayMs` | `number` | `500` | Base backoff delay between retries (doubles each attempt). |
+| `onDrop` | `(dropped, reason) => void` | — | Called when events are dropped (`"queue-full"` or `"flush-failed"`). |
+| `onError` | `(error) => void` | — | Called on unexpected flush errors. |
+
+### `client.track(metricName, value, tags?)`
+
+Records a numeric metric point, e.g. `client.track("checkout.duration_ms", 245, { region: "us-east" })`.
+
+### `client.log(level, message, meta?)`
+
+Records a log line. `level` is one of `"debug" | "info" | "warn" | "error"`.
+
+### `client.flush(): Promise<void>`
+
+Forces an immediate flush of buffered events. Call this on shutdown (e.g. `SIGTERM`) to
+avoid losing the last partial batch.
+
+### `client.stop()`
+
+Stops the internal flush timer. Useful in tests.
+
+## Why this exists
+
+Instrumenting a service shouldn't require the instrumented service to take on network
+latency, unbounded memory growth, or crash risk. This SDK batches and bounds everything
+client-side so that if the ingestion endpoint is slow or down, the host app degrades not
+at all — it just stops getting new data reflected on the dashboard until the endpoint
+recovers.

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface MetricEvent {
+    type: "metric";
+    name: string;
+    value: number;
+    tags?: Record<string, string>;
+    timestamp: string;
+}
+interface LogEvent {
+    type: "log";
+    level: LogLevel;
+    message: string;
+    meta?: Record<string, unknown>;
+    timestamp: string;
+}
+type ObservabilityEvent = MetricEvent | LogEvent;
+interface ObservabilityClientOptions {
+    /** Per-service API key, sent as `Authorization: Bearer <apiKey>`. */
+    apiKey: string;
+    /** Base URL of the ingestion endpoint, e.g. https://your-backend.com/ingest */
+    endpoint: string;
+    /** Flush the batch on this interval, regardless of size. Default 5000ms. */
+    flushIntervalMs?: number;
+    /** Flush immediately once the batch reaches this many events. Default 100. */
+    maxBatchSize?: number;
+    /** Upper bound on events held in memory if the endpoint is unreachable. Oldest events are dropped past this. Default 1000. */
+    maxQueueSize?: number;
+    /** Max retry attempts per flush before giving up on that batch. Default 3. */
+    maxRetries?: number;
+    /** Base backoff delay in ms between retries (doubles each attempt). Default 500ms. */
+    retryBaseDelayMs?: number;
+    /** Called when events are dropped due to a full queue or exhausted retries. Never throws from inside the client. */
+    onDrop?: (dropped: ObservabilityEvent[], reason: "queue-full" | "flush-failed") => void;
+    /** Called on unexpected flush errors, for host-app diagnostics. */
+    onError?: (error: unknown) => void;
+    /** Injectable fetch implementation, mainly for testing. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+
+/**
+ * Client SDK for the network-observer ingestion endpoint.
+ *
+ * Every network call is fire-and-forget from the host app's perspective:
+ * flush() never throws and never blocks the caller. On sustained failure,
+ * the oldest buffered events are dropped rather than growing the queue
+ * without bound.
+ */
+declare class ObservabilityClient {
+    private readonly options;
+    private readonly batcher;
+    private readonly fetchImpl;
+    private inFlight;
+    constructor(options: ObservabilityClientOptions);
+    track(metricName: string, value: number, tags?: Record<string, string>): void;
+    log(level: LogLevel, message: string, meta?: Record<string, unknown>): void;
+    /** Force an immediate flush — call on process shutdown (SIGTERM/beforeExit). */
+    flush(): Promise<void>;
+    stop(): void;
+    private sendBatch;
+}
+
+export { type LogEvent, type LogLevel, type MetricEvent, ObservabilityClient, type ObservabilityClientOptions, type ObservabilityEvent };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface MetricEvent {
+    type: "metric";
+    name: string;
+    value: number;
+    tags?: Record<string, string>;
+    timestamp: string;
+}
+interface LogEvent {
+    type: "log";
+    level: LogLevel;
+    message: string;
+    meta?: Record<string, unknown>;
+    timestamp: string;
+}
+type ObservabilityEvent = MetricEvent | LogEvent;
+interface ObservabilityClientOptions {
+    /** Per-service API key, sent as `Authorization: Bearer <apiKey>`. */
+    apiKey: string;
+    /** Base URL of the ingestion endpoint, e.g. https://your-backend.com/ingest */
+    endpoint: string;
+    /** Flush the batch on this interval, regardless of size. Default 5000ms. */
+    flushIntervalMs?: number;
+    /** Flush immediately once the batch reaches this many events. Default 100. */
+    maxBatchSize?: number;
+    /** Upper bound on events held in memory if the endpoint is unreachable. Oldest events are dropped past this. Default 1000. */
+    maxQueueSize?: number;
+    /** Max retry attempts per flush before giving up on that batch. Default 3. */
+    maxRetries?: number;
+    /** Base backoff delay in ms between retries (doubles each attempt). Default 500ms. */
+    retryBaseDelayMs?: number;
+    /** Called when events are dropped due to a full queue or exhausted retries. Never throws from inside the client. */
+    onDrop?: (dropped: ObservabilityEvent[], reason: "queue-full" | "flush-failed") => void;
+    /** Called on unexpected flush errors, for host-app diagnostics. */
+    onError?: (error: unknown) => void;
+    /** Injectable fetch implementation, mainly for testing. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+
+/**
+ * Client SDK for the network-observer ingestion endpoint.
+ *
+ * Every network call is fire-and-forget from the host app's perspective:
+ * flush() never throws and never blocks the caller. On sustained failure,
+ * the oldest buffered events are dropped rather than growing the queue
+ * without bound.
+ */
+declare class ObservabilityClient {
+    private readonly options;
+    private readonly batcher;
+    private readonly fetchImpl;
+    private inFlight;
+    constructor(options: ObservabilityClientOptions);
+    track(metricName: string, value: number, tags?: Record<string, string>): void;
+    log(level: LogLevel, message: string, meta?: Record<string, unknown>): void;
+    /** Force an immediate flush — call on process shutdown (SIGTERM/beforeExit). */
+    flush(): Promise<void>;
+    stop(): void;
+    private sendBatch;
+}
+
+export { type LogEvent, type LogLevel, type MetricEvent, ObservabilityClient, type ObservabilityClientOptions, type ObservabilityEvent };

package/dist/index.js

@@ -0,0 +1,171 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ObservabilityClient: () => ObservabilityClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/batcher.ts
+var EventBatcher = class {
+  constructor(maxBatchSize, maxQueueSize, flushIntervalMs, onFlush, onDrop) {
+    this.maxBatchSize = maxBatchSize;
+    this.maxQueueSize = maxQueueSize;
+    this.flushIntervalMs = flushIntervalMs;
+    this.onFlush = onFlush;
+    this.onDrop = onDrop;
+    this.buffer = [];
+    this.timer = null;
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.flush(), this.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  push(event) {
+    this.buffer.push(event);
+    if (this.buffer.length > this.maxQueueSize) {
+      const overflow = this.buffer.length - this.maxQueueSize;
+      const dropped = this.buffer.splice(0, overflow);
+      this.onDrop(dropped);
+    }
+    if (this.buffer.length >= this.maxBatchSize) {
+      this.flush();
+    }
+  }
+  flush() {
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer;
+    this.buffer = [];
+    this.onFlush(batch);
+  }
+  /** Re-queue events after a failed flush, respecting the size bound. */
+  requeueFront(events) {
+    this.buffer = [...events, ...this.buffer];
+    if (this.buffer.length > this.maxQueueSize) {
+      const overflow = this.buffer.length - this.maxQueueSize;
+      const dropped = this.buffer.splice(0, overflow);
+      this.onDrop(dropped);
+    }
+  }
+  size() {
+    return this.buffer.length;
+  }
+};
+
+// src/client.ts
+var DEFAULTS = {
+  flushIntervalMs: 5e3,
+  maxBatchSize: 100,
+  maxQueueSize: 1e3,
+  maxRetries: 3,
+  retryBaseDelayMs: 500
+};
+var ObservabilityClient = class {
+  constructor(options) {
+    this.options = options;
+    this.inFlight = false;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.batcher = new EventBatcher(
+      options.maxBatchSize ?? DEFAULTS.maxBatchSize,
+      options.maxQueueSize ?? DEFAULTS.maxQueueSize,
+      options.flushIntervalMs ?? DEFAULTS.flushIntervalMs,
+      (events) => this.sendBatch(events),
+      (dropped) => this.options.onDrop?.(dropped, "queue-full")
+    );
+    this.batcher.start();
+  }
+  track(metricName, value, tags) {
+    const event = {
+      type: "metric",
+      name: metricName,
+      value,
+      tags,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.batcher.push(event);
+  }
+  log(level, message, meta) {
+    const event = {
+      type: "log",
+      level,
+      message,
+      meta,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.batcher.push(event);
+  }
+  /** Force an immediate flush — call on process shutdown (SIGTERM/beforeExit). */
+  async flush() {
+    this.batcher.flush();
+    for (let i = 0; i < 20 && this.inFlight; i++) {
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+  stop() {
+    this.batcher.stop();
+  }
+  async sendBatch(events) {
+    this.inFlight = true;
+    const maxRetries = this.options.maxRetries ?? DEFAULTS.maxRetries;
+    const baseDelay = this.options.retryBaseDelayMs ?? DEFAULTS.retryBaseDelayMs;
+    try {
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const res = await this.fetchImpl(this.options.endpoint, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${this.options.apiKey}`
+            },
+            body: JSON.stringify({ events })
+          });
+          if (res.ok) return;
+          if (res.status >= 400 && res.status < 500) {
+            this.options.onDrop?.(events, "flush-failed");
+            return;
+          }
+        } catch (err) {
+          if (attempt === maxRetries) {
+            this.options.onError?.(err);
+          }
+        }
+        if (attempt < maxRetries) {
+          await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
+        }
+      }
+      this.options.onDrop?.(events, "flush-failed");
+    } finally {
+      this.inFlight = false;
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ObservabilityClient
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/batcher.ts","../src/client.ts"],"sourcesContent":["export { ObservabilityClient } from \"./client.js\";\nexport type {\n  LogEvent,\n  LogLevel,\n  MetricEvent,\n  ObservabilityClientOptions,\n  ObservabilityEvent,\n} from \"./types.js\";\n","import type { ObservabilityEvent } from \"./types.js\";\n\n/**\n * Bounded in-memory buffer with timer/size-triggered flush.\n * Never grows past maxQueueSize — the oldest events are dropped first,\n * because the monitoring client must never be the reason the host app\n * runs out of memory.\n */\nexport class EventBatcher {\n  private buffer: ObservabilityEvent[] = [];\n  private timer: ReturnType<typeof setInterval> | null = null;\n\n  constructor(\n    private readonly maxBatchSize: number,\n    private readonly maxQueueSize: number,\n    private readonly flushIntervalMs: number,\n    private readonly onFlush: (events: ObservabilityEvent[]) => void,\n    private readonly onDrop: (dropped: ObservabilityEvent[]) => void,\n  ) {}\n\n  start(): void {\n    if (this.timer) return;\n    this.timer = setInterval(() => this.flush(), this.flushIntervalMs);\n    // Don't let this timer keep a Node process alive on its own.\n    this.timer.unref?.();\n  }\n\n  stop(): void {\n    if (this.timer) {\n      clearInterval(this.timer);\n      this.timer = null;\n    }\n  }\n\n  push(event: ObservabilityEvent): void {\n    this.buffer.push(event);\n\n    if (this.buffer.length > this.maxQueueSize) {\n      const overflow = this.buffer.length - this.maxQueueSize;\n      const dropped = this.buffer.splice(0, overflow);\n      this.onDrop(dropped);\n    }\n\n    if (this.buffer.length >= this.maxBatchSize) {\n      this.flush();\n    }\n  }\n\n  flush(): void {\n    if (this.buffer.length === 0) return;\n    const batch = this.buffer;\n    this.buffer = [];\n    this.onFlush(batch);\n  }\n\n  /** Re-queue events after a failed flush, respecting the size bound. */\n  requeueFront(events: ObservabilityEvent[]): void {\n    this.buffer = [...events, ...this.buffer];\n    if (this.buffer.length > this.maxQueueSize) {\n      const overflow = this.buffer.length - this.maxQueueSize;\n      const dropped = this.buffer.splice(0, overflow);\n      this.onDrop(dropped);\n    }\n  }\n\n  size(): number {\n    return this.buffer.length;\n  }\n}\n","import { EventBatcher } from \"./batcher.js\";\nimport type {\n  LogEvent,\n  LogLevel,\n  MetricEvent,\n  ObservabilityClientOptions,\n  ObservabilityEvent,\n} from \"./types.js\";\n\nconst DEFAULTS = {\n  flushIntervalMs: 5000,\n  maxBatchSize: 100,\n  maxQueueSize: 1000,\n  maxRetries: 3,\n  retryBaseDelayMs: 500,\n} as const;\n\n/**\n * Client SDK for the network-observer ingestion endpoint.\n *\n * Every network call is fire-and-forget from the host app's perspective:\n * flush() never throws and never blocks the caller. On sustained failure,\n * the oldest buffered events are dropped rather than growing the queue\n * without bound.\n */\nexport class ObservabilityClient {\n  private readonly batcher: EventBatcher;\n  private readonly fetchImpl: typeof fetch;\n  private inFlight = false;\n\n  constructor(private readonly options: ObservabilityClientOptions) {\n    this.fetchImpl = options.fetchImpl ?? fetch;\n    this.batcher = new EventBatcher(\n      options.maxBatchSize ?? DEFAULTS.maxBatchSize,\n      options.maxQueueSize ?? DEFAULTS.maxQueueSize,\n      options.flushIntervalMs ?? DEFAULTS.flushIntervalMs,\n      (events) => this.sendBatch(events),\n      (dropped) => this.options.onDrop?.(dropped, \"queue-full\"),\n    );\n    this.batcher.start();\n  }\n\n  track(metricName: string, value: number, tags?: Record<string, string>): void {\n    const event: MetricEvent = {\n      type: \"metric\",\n      name: metricName,\n      value,\n      tags,\n      timestamp: new Date().toISOString(),\n    };\n    this.batcher.push(event);\n  }\n\n  log(level: LogLevel, message: string, meta?: Record<string, unknown>): void {\n    const event: LogEvent = {\n      type: \"log\",\n      level,\n      message,\n      meta,\n      timestamp: new Date().toISOString(),\n    };\n    this.batcher.push(event);\n  }\n\n  /** Force an immediate flush — call on process shutdown (SIGTERM/beforeExit). */\n  async flush(): Promise<void> {\n    this.batcher.flush();\n    // Give the in-flight send a moment to land during shutdown.\n    for (let i = 0; i < 20 && this.inFlight; i++) {\n      await new Promise((r) => setTimeout(r, 50));\n    }\n  }\n\n  stop(): void {\n    this.batcher.stop();\n  }\n\n  private async sendBatch(events: ObservabilityEvent[]): Promise<void> {\n    this.inFlight = true;\n    const maxRetries = this.options.maxRetries ?? DEFAULTS.maxRetries;\n    const baseDelay = this.options.retryBaseDelayMs ?? DEFAULTS.retryBaseDelayMs;\n\n    try {\n      for (let attempt = 0; attempt <= maxRetries; attempt++) {\n        try {\n          const res = await this.fetchImpl(this.options.endpoint, {\n            method: \"POST\",\n            headers: {\n              \"Content-Type\": \"application/json\",\n              Authorization: `Bearer ${this.options.apiKey}`,\n            },\n            body: JSON.stringify({ events }),\n          });\n          if (res.ok) return;\n          if (res.status >= 400 && res.status < 500) {\n            // Not retryable — bad key or malformed payload.\n            this.options.onDrop?.(events, \"flush-failed\");\n            return;\n          }\n        } catch (err) {\n          if (attempt === maxRetries) {\n            this.options.onError?.(err);\n          }\n        }\n        if (attempt < maxRetries) {\n          await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));\n        }\n      }\n      // Exhausted retries: drop this batch rather than requeueing it forever.\n      this.options.onDrop?.(events, \"flush-failed\");\n    } finally {\n      this.inFlight = false;\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,144 @@
+// src/batcher.ts
+var EventBatcher = class {
+  constructor(maxBatchSize, maxQueueSize, flushIntervalMs, onFlush, onDrop) {
+    this.maxBatchSize = maxBatchSize;
+    this.maxQueueSize = maxQueueSize;
+    this.flushIntervalMs = flushIntervalMs;
+    this.onFlush = onFlush;
+    this.onDrop = onDrop;
+    this.buffer = [];
+    this.timer = null;
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.flush(), this.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  push(event) {
+    this.buffer.push(event);
+    if (this.buffer.length > this.maxQueueSize) {
+      const overflow = this.buffer.length - this.maxQueueSize;
+      const dropped = this.buffer.splice(0, overflow);
+      this.onDrop(dropped);
+    }
+    if (this.buffer.length >= this.maxBatchSize) {
+      this.flush();
+    }
+  }
+  flush() {
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer;
+    this.buffer = [];
+    this.onFlush(batch);
+  }
+  /** Re-queue events after a failed flush, respecting the size bound. */
+  requeueFront(events) {
+    this.buffer = [...events, ...this.buffer];
+    if (this.buffer.length > this.maxQueueSize) {
+      const overflow = this.buffer.length - this.maxQueueSize;
+      const dropped = this.buffer.splice(0, overflow);
+      this.onDrop(dropped);
+    }
+  }
+  size() {
+    return this.buffer.length;
+  }
+};
+
+// src/client.ts
+var DEFAULTS = {
+  flushIntervalMs: 5e3,
+  maxBatchSize: 100,
+  maxQueueSize: 1e3,
+  maxRetries: 3,
+  retryBaseDelayMs: 500
+};
+var ObservabilityClient = class {
+  constructor(options) {
+    this.options = options;
+    this.inFlight = false;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.batcher = new EventBatcher(
+      options.maxBatchSize ?? DEFAULTS.maxBatchSize,
+      options.maxQueueSize ?? DEFAULTS.maxQueueSize,
+      options.flushIntervalMs ?? DEFAULTS.flushIntervalMs,
+      (events) => this.sendBatch(events),
+      (dropped) => this.options.onDrop?.(dropped, "queue-full")
+    );
+    this.batcher.start();
+  }
+  track(metricName, value, tags) {
+    const event = {
+      type: "metric",
+      name: metricName,
+      value,
+      tags,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.batcher.push(event);
+  }
+  log(level, message, meta) {
+    const event = {
+      type: "log",
+      level,
+      message,
+      meta,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.batcher.push(event);
+  }
+  /** Force an immediate flush — call on process shutdown (SIGTERM/beforeExit). */
+  async flush() {
+    this.batcher.flush();
+    for (let i = 0; i < 20 && this.inFlight; i++) {
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+  stop() {
+    this.batcher.stop();
+  }
+  async sendBatch(events) {
+    this.inFlight = true;
+    const maxRetries = this.options.maxRetries ?? DEFAULTS.maxRetries;
+    const baseDelay = this.options.retryBaseDelayMs ?? DEFAULTS.retryBaseDelayMs;
+    try {
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const res = await this.fetchImpl(this.options.endpoint, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${this.options.apiKey}`
+            },
+            body: JSON.stringify({ events })
+          });
+          if (res.ok) return;
+          if (res.status >= 400 && res.status < 500) {
+            this.options.onDrop?.(events, "flush-failed");
+            return;
+          }
+        } catch (err) {
+          if (attempt === maxRetries) {
+            this.options.onError?.(err);
+          }
+        }
+        if (attempt < maxRetries) {
+          await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
+        }
+      }
+      this.options.onDrop?.(events, "flush-failed");
+    } finally {
+      this.inFlight = false;
+    }
+  }
+};
+export {
+  ObservabilityClient
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/batcher.ts","../src/client.ts"],"sourcesContent":["import type { ObservabilityEvent } from \"./types.js\";\n\n/**\n * Bounded in-memory buffer with timer/size-triggered flush.\n * Never grows past maxQueueSize — the oldest events are dropped first,\n * because the monitoring client must never be the reason the host app\n * runs out of memory.\n */\nexport class EventBatcher {\n  private buffer: ObservabilityEvent[] = [];\n  private timer: ReturnType<typeof setInterval> | null = null;\n\n  constructor(\n    private readonly maxBatchSize: number,\n    private readonly maxQueueSize: number,\n    private readonly flushIntervalMs: number,\n    private readonly onFlush: (events: ObservabilityEvent[]) => void,\n    private readonly onDrop: (dropped: ObservabilityEvent[]) => void,\n  ) {}\n\n  start(): void {\n    if (this.timer) return;\n    this.timer = setInterval(() => this.flush(), this.flushIntervalMs);\n    // Don't let this timer keep a Node process alive on its own.\n    this.timer.unref?.();\n  }\n\n  stop(): void {\n    if (this.timer) {\n      clearInterval(this.timer);\n      this.timer = null;\n    }\n  }\n\n  push(event: ObservabilityEvent): void {\n    this.buffer.push(event);\n\n    if (this.buffer.length > this.maxQueueSize) {\n      const overflow = this.buffer.length - this.maxQueueSize;\n      const dropped = this.buffer.splice(0, overflow);\n      this.onDrop(dropped);\n    }\n\n    if (this.buffer.length >= this.maxBatchSize) {\n      this.flush();\n    }\n  }\n\n  flush(): void {\n    if (this.buffer.length === 0) return;\n    const batch = this.buffer;\n    this.buffer = [];\n    this.onFlush(batch);\n  }\n\n  /** Re-queue events after a failed flush, respecting the size bound. */\n  requeueFront(events: ObservabilityEvent[]): void {\n    this.buffer = [...events, ...this.buffer];\n    if (this.buffer.length > this.maxQueueSize) {\n      const overflow = this.buffer.length - this.maxQueueSize;\n      const dropped = this.buffer.splice(0, overflow);\n      this.onDrop(dropped);\n    }\n  }\n\n  size(): number {\n    return this.buffer.length;\n  }\n}\n","import { EventBatcher } from \"./batcher.js\";\nimport type {\n  LogEvent,\n  LogLevel,\n  MetricEvent,\n  ObservabilityClientOptions,\n  ObservabilityEvent,\n} from \"./types.js\";\n\nconst DEFAULTS = {\n  flushIntervalMs: 5000,\n  maxBatchSize: 100,\n  maxQueueSize: 1000,\n  maxRetries: 3,\n  retryBaseDelayMs: 500,\n} as const;\n\n/**\n * Client SDK for the network-observer ingestion endpoint.\n *\n * Every network call is fire-and-forget from the host app's perspective:\n * flush() never throws and never blocks the caller. On sustained failure,\n * the oldest buffered events are dropped rather than growing the queue\n * without bound.\n */\nexport class ObservabilityClient {\n  private readonly batcher: EventBatcher;\n  private readonly fetchImpl: typeof fetch;\n  private inFlight = false;\n\n  constructor(private readonly options: ObservabilityClientOptions) {\n    this.fetchImpl = options.fetchImpl ?? fetch;\n    this.batcher = new EventBatcher(\n      options.maxBatchSize ?? DEFAULTS.maxBatchSize,\n      options.maxQueueSize ?? DEFAULTS.maxQueueSize,\n      options.flushIntervalMs ?? DEFAULTS.flushIntervalMs,\n      (events) => this.sendBatch(events),\n      (dropped) => this.options.onDrop?.(dropped, \"queue-full\"),\n    );\n    this.batcher.start();\n  }\n\n  track(metricName: string, value: number, tags?: Record<string, string>): void {\n    const event: MetricEvent = {\n      type: \"metric\",\n      name: metricName,\n      value,\n      tags,\n      timestamp: new Date().toISOString(),\n    };\n    this.batcher.push(event);\n  }\n\n  log(level: LogLevel, message: string, meta?: Record<string, unknown>): void {\n    const event: LogEvent = {\n      type: \"log\",\n      level,\n      message,\n      meta,\n      timestamp: new Date().toISOString(),\n    };\n    this.batcher.push(event);\n  }\n\n  /** Force an immediate flush — call on process shutdown (SIGTERM/beforeExit). */\n  async flush(): Promise<void> {\n    this.batcher.flush();\n    // Give the in-flight send a moment to land during shutdown.\n    for (let i = 0; i < 20 && this.inFlight; i++) {\n      await new Promise((r) => setTimeout(r, 50));\n    }\n  }\n\n  stop(): void {\n    this.batcher.stop();\n  }\n\n  private async sendBatch(events: ObservabilityEvent[]): Promise<void> {\n    this.inFlight = true;\n    const maxRetries = this.options.maxRetries ?? DEFAULTS.maxRetries;\n    const baseDelay = this.options.retryBaseDelayMs ?? DEFAULTS.retryBaseDelayMs;\n\n    try {\n      for (let attempt = 0; attempt <= maxRetries; attempt++) {\n        try {\n          const res = await this.fetchImpl(this.options.endpoint, {\n            method: \"POST\",\n            headers: {\n              \"Content-Type\": \"application/json\",\n              Authorization: `Bearer ${this.options.apiKey}`,\n            },\n            body: JSON.stringify({ events }),\n          });\n          if (res.ok) return;\n          if (res.status >= 400 && res.status < 500) {\n            // Not retryable — bad key or malformed payload.\n            this.options.onDrop?.(events, \"flush-failed\");\n            return;\n          }\n        } catch (err) {\n          if (attempt === maxRetries) {\n            this.options.onError?.(err);\n          }\n        }\n        if (attempt < maxRetries) {\n          await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));\n        }\n      }\n      // Exhausted retries: drop this batch rather than requeueing it forever.\n      this.options.onDrop?.(events, \"flush-failed\");\n    } finally {\n      this.inFlight = false;\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@prath/observability-sdk",
+  "version": "0.1.0",
+  "description": "Tiny client for the network-observer observability service: batches metrics and logs client-side and flushes them off the host app's hot path.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["observability", "metrics", "logging", "monitoring", "sdk"],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.2.4",
+    "typescript": "^5.5.4"
+  }
+}