securenow 8.0.3 → 8.2.0

package/events.d.ts

@@ -0,0 +1,29 @@
+export interface TrackProps {
+  /** End-user / account identifier (durable identity for correlation). */
+  userId?: string | number;
+  /** Session identifier (finer-grained than userId). */
+  sessionId?: string | number;
+  /** End-user client IP as seen by your app (enriched to geo/ASN server-side). */
+  ip?: string;
+  /** End-user agent string. */
+  userAgent?: string;
+  /** Severity hint. Defaults to "info". */
+  severity?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+  /** Event time in epoch ms. Defaults to now. */
+  ts?: number;
+  /** Arbitrary structured attributes (string/number/boolean values). */
+  attributes?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Emit a custom security event to SecureNow. Fire-and-forget: returns
+ * immediately, batches in the background, and never throws into your app.
+ *
+ * @example
+ * import { track } from "securenow/events";
+ * track("auth.login.success", { userId, sessionId, ip, attributes: { method: "magic_link" } });
+ */
+export function track(type: string, props?: TrackProps): void;
+
+/** Force a flush of any buffered events. Best-effort; never throws. */
+export function flush(): Promise<unknown>;

package/events.js

@@ -0,0 +1,160 @@
+'use strict';
+
+// SecureNow custom events — a tiny, batched, fire-and-forget emitter.
+//
+//   const { track } = require('securenow/events');
+//   track('auth.login.success', { userId, sessionId, ip, attributes: { method: 'magic_link' } });
+//
+// Design goals:
+//   - Never throw into the caller. A SecureNow/network outage must not affect
+//     the app's request path. Events are advisory.
+//   - Non-blocking: events are buffered and flushed asynchronously in batches.
+//   - Bounded memory: the buffer is capped; oldest events drop on overflow.
+//   - Reuses the SDK's resolved runtime config (app key + auth headers +
+//     endpoint), so there is nothing extra to configure.
+
+const appConfig = require('./app-config');
+
+const MAX_BUFFER = 1000; // hard cap on queued events
+const MAX_BATCH = 100; // events sent per flush
+const FLUSH_INTERVAL_MS = 2000;
+const POST_TIMEOUT_MS = 5000;
+
+let buffer = [];
+let timer = null;
+let target = null;
+let targetResolved = false;
+
+function resolveTarget() {
+  if (targetResolved) return target;
+  targetResolved = true;
+  try {
+    const endpoints = appConfig.resolveEndpoints();
+    const base = String((endpoints && endpoints.endpointBase) || '').replace(/\/$/, '');
+    if (!base) {
+      target = null;
+      return null;
+    }
+    const headers = Object.assign({ 'Content-Type': 'application/json' }, (endpoints && endpoints.headers) || {});
+    // Without an app key + auth we can't attribute events; stay silent.
+    const hasAppKey = headers['x-securenow-app-key'] || headers['X-SecureNow-App-Key'];
+    if (!hasAppKey) {
+      target = null;
+      return null;
+    }
+    target = { url: `${base}/v1/events`, headers };
+  } catch {
+    target = null;
+  }
+  return target;
+}
+
+function post(t, payload) {
+  return new Promise((resolve) => {
+    let parsed;
+    let lib;
+    try {
+      parsed = new (require('url').URL)(t.url);
+      lib = parsed.protocol === 'https:' ? require('https') : require('http');
+    } catch {
+      return resolve(false);
+    }
+    let body;
+    try {
+      body = Buffer.from(JSON.stringify(payload));
+    } catch {
+      return resolve(false);
+    }
+    const req = lib.request(
+      {
+        method: 'POST',
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        headers: Object.assign({ 'Content-Length': body.length }, t.headers),
+        timeout: POST_TIMEOUT_MS,
+      },
+      (res) => {
+        res.on('data', () => {});
+        res.on('end', () => resolve(res.statusCode >= 200 && res.statusCode < 300));
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => {
+      try { req.destroy(); } catch {}
+      resolve(false);
+    });
+    try {
+      req.write(body);
+      req.end();
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+function scheduleFlush() {
+  if (timer) return;
+  timer = setTimeout(flush, FLUSH_INTERVAL_MS);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+}
+
+function flush() {
+  if (timer) {
+    clearTimeout(timer);
+    timer = null;
+  }
+  if (!buffer.length) return Promise.resolve();
+  const t = resolveTarget();
+  if (!t) {
+    buffer = []; // not configured to emit — drop silently
+    return Promise.resolve();
+  }
+  const batch = buffer.splice(0, MAX_BATCH);
+  const p = post(t, { events: batch }).catch(() => false);
+  if (buffer.length) scheduleFlush();
+  return p;
+}
+
+function normalizeEvent(type, props) {
+  if (!type || typeof type !== 'string') return null;
+  const ev = { type, ts: (props && Number(props.ts)) || Date.now() };
+  if (props) {
+    if (props.userId != null) ev.user_id = String(props.userId);
+    if (props.sessionId != null) ev.session_id = String(props.sessionId);
+    if (props.ip != null) ev.ip = String(props.ip);
+    if (props.userAgent != null) ev.user_agent = String(props.userAgent);
+    if (props.severity) ev.severity = String(props.severity);
+    if (props.attributes && typeof props.attributes === 'object' && !Array.isArray(props.attributes)) {
+      ev.attributes = props.attributes;
+    }
+  }
+  return ev;
+}
+
+/**
+ * Emit a custom event. Fire-and-forget — returns immediately, never throws.
+ * @param {string} type        Event type, e.g. "auth.login.success".
+ * @param {object} [props]      { userId, sessionId, ip, userAgent, severity, ts, attributes }
+ */
+function track(type, props = {}) {
+  try {
+    const ev = normalizeEvent(type, props);
+    if (!ev) return;
+    buffer.push(ev);
+    if (buffer.length > MAX_BUFFER) buffer.splice(0, buffer.length - MAX_BUFFER); // drop oldest
+    if (buffer.length >= MAX_BATCH) flush();
+    else scheduleFlush();
+  } catch {
+    /* never throw into the app */
+  }
+}
+
+// Best-effort flush so buffered events aren't lost on a clean shutdown.
+try {
+  process.once('beforeExit', () => {
+    try { flush(); } catch {}
+  });
+} catch {}
+
+module.exports = { track, flush };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "8.0.3",
+  "version": "8.2.0",
   "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",
   "main": "register.js",
@@ -50,6 +50,10 @@
       "types": "./tracing.d.ts",
       "default": "./tracing.js"
     },
+    "./events": {
+      "types": "./events.d.ts",
+      "default": "./events.js"
+    },
     "./console-instrumentation": {
       "default": "./console-instrumentation.js"
     },
@@ -112,6 +116,8 @@
     "register.d.ts",
     "tracing.js",
     "tracing.d.ts",
+    "events.js",
+    "events.d.ts",
     "console-instrumentation.js",
     "nextjs.js",
     "nextjs.d.ts",