@guidelytech/node 0.16.0 → 0.17.0

package/dist/index.js

@@ -46,6 +46,11 @@ function id(name, value, required) {
   if (length(s) > LIMITS.maxIdLength) throw new InvalidMessageError(`${name} is longer than ${LIMITS.maxIdLength} characters`);
   return s;
 }
+function version(value) {
+  if (typeof value !== "string" && typeof value !== "number") return void 0;
+  const s = String(value).trim();
+  return s ? s.slice(0, 200) : void 0;
+}
 function isPlainObject(v) {
   if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
   const proto = Object.getPrototypeOf(v);
@@ -56,11 +61,11 @@ function object(name, value) {
   if (!isPlainObject(value)) throw new InvalidMessageError(`${name} must be an object`);
   return value;
 }
-function buildMessage(type, args, now = () => /* @__PURE__ */ new Date()) {
-  if (!isPlainObject(args)) throw new InvalidMessageError(`${type}() needs an object argument`);
+function buildMessage(type2, args, now = () => /* @__PURE__ */ new Date()) {
+  if (!isPlainObject(args)) throw new InvalidMessageError(`${type2}() needs an object argument`);
   const timestamp = args.timestamp === void 0 || args.timestamp === null ? now().toISOString() : formatTimestamp(args.timestamp);
-  const base = { type, messageId: newMessageId(), timestamp };
-  switch (type) {
+  const base = { type: type2, messageId: newMessageId(), timestamp };
+  switch (type2) {
     case "identify": {
       const userId = id("userId", args.userId, true);
       const traits = object("traits", args.traits);
@@ -76,13 +81,15 @@ function buildMessage(type, args, now = () => /* @__PURE__ */ new Date()) {
       if (length(event) > LIMITS.maxEventLength) throw new InvalidMessageError(`event is longer than ${LIMITS.maxEventLength} characters`);
       const properties = object("properties", args.properties);
       const accountId = id("accountId", args.accountId, false);
+      const appVersion = version(args.appVersion);
       return {
         ...base,
         ...userId ? { userId } : {},
         ...anonymousId ? { anonymousId } : {},
         event,
         ...properties ? { properties } : {},
-        ...accountId ? { accountId } : {}
+        ...accountId ? { accountId } : {},
+        ...appVersion ? { appVersion } : {}
       };
     }
     case "group": {
@@ -115,12 +122,1249 @@ function jitter(delayMs, random) {
   return Math.round(delayMs * (0.8 + 0.4 * random));
 }
 
+// src/errors/event.ts
+import { randomUUID } from "crypto";
+import { readFileSync } from "fs";
+import * as os from "os";
+
+// src/errors/normalize.ts
+var SENSITIVE_KEY = /(password|passwd|secret|token|credit|card|cvv|ssn|iban|authorization|cookie|api[-_]?key|private[-_]?key)/i;
+var SENSITIVE_HEADER = /^(authorization|proxy-authorization|cookie|set-cookie|x-api-key|x-auth-token|x-csrf-token|x-xsrf-token|x-guidely-key|x-guidely-conversation)$|secret|token|password|passwd|api[-_]?key|signature|session/i;
+var SENSITIVE_PARAM = /(token|key|secret|password|passwd|pwd|auth|session|code|sig|signature|credential|ssn|card|cvv|iban)/i;
+var IP_HEADER = /^(x-forwarded-for|x-real-ip|forwarded|cf-connecting-ip|true-client-ip|x-client-ip)$/i;
+var FILTERED = "[Filtered]";
+var MAX_STRING = 2e3;
+var MAX_KEYS = 100;
+var MAX_ITEMS = 100;
+function normalize(value, depth = 4, seen = /* @__PURE__ */ new WeakSet()) {
+  switch (typeof value) {
+    case "string":
+      return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}\u2026` : value;
+    case "number":
+      return Number.isFinite(value) ? value : String(value);
+    case "boolean":
+      return value;
+    case "bigint":
+      return `${value}n`;
+    case "symbol":
+      return value.toString();
+    case "function":
+      return `[Function${value.name ? `: ${value.name}` : ""}]`;
+    case "undefined":
+      return void 0;
+  }
+  if (value === null) return null;
+  const obj = value;
+  if (obj instanceof Date) return Number.isNaN(obj.getTime()) ? "Invalid Date" : obj.toISOString();
+  if (obj instanceof Error) return `${obj.name}: ${obj.message}`.slice(0, MAX_STRING);
+  if (obj instanceof RegExp) return obj.toString();
+  if (ArrayBuffer.isView(obj)) return `[${obj.constructor?.name ?? "Buffer"} ${obj.byteLength} bytes]`;
+  if (seen.has(obj)) return "[Circular]";
+  if (depth <= 0) return Array.isArray(obj) ? "[Array]" : "[Object]";
+  seen.add(obj);
+  try {
+    if (Array.isArray(obj) || obj instanceof Set) {
+      const items = Array.isArray(obj) ? obj : [...obj];
+      const out2 = items.slice(0, MAX_ITEMS).map((v) => normalize(v, depth - 1, seen) ?? null);
+      if (items.length > MAX_ITEMS) out2.push(`[${items.length - MAX_ITEMS} more]`);
+      return out2;
+    }
+    const entries = obj instanceof Map ? [...obj].map(([k, v]) => [String(k), v]) : Object.keys(obj).map((k) => [k, void 0]);
+    const out = {};
+    let n = 0;
+    for (const [key, mapped] of entries) {
+      if (n >= MAX_KEYS) {
+        out["\u2026"] = `${entries.length - MAX_KEYS} more keys`;
+        break;
+      }
+      if (SENSITIVE_KEY.test(key)) continue;
+      let v;
+      try {
+        v = obj instanceof Map ? mapped : obj[key];
+      } catch {
+        v = "[Getter threw]";
+      }
+      const nv = normalize(v, depth - 1, seen);
+      if (nv === void 0) continue;
+      out[key] = nv;
+      n++;
+    }
+    return out;
+  } finally {
+    seen.delete(obj);
+  }
+}
+function normalizeObject(value, depth = 4) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const out = normalize(value, depth);
+  return out && typeof out === "object" && !Array.isArray(out) ? out : void 0;
+}
+function scrubQuery(query) {
+  return query.replace(/^\?/, "").split("&").filter(Boolean).slice(0, 100).map((pair) => {
+    const i = pair.indexOf("=");
+    const key = i < 0 ? pair : pair.slice(0, i);
+    let name = key;
+    try {
+      name = decodeURIComponent(key.replace(/\+/g, " "));
+    } catch {
+    }
+    return i >= 0 && SENSITIVE_PARAM.test(name) ? `${key}=${FILTERED}` : pair;
+  }).join("&").slice(0, 2e3);
+}
+function stripQuery(url) {
+  const i = url.search(/[?#]/);
+  return (i < 0 ? url : url.slice(0, i)).slice(0, 2e3);
+}
+
+// src/errors/stack.ts
+import { posix } from "path";
+import { fileURLToPath } from "url";
+var MAX_DETAIL_FRAMES = 250;
+var MAX_PROPERTY_FRAMES = 30;
+var LINE = /^\s*at (?:async )?(?:(.+?) \((.*)\)|(.+))$/;
+var LOCATION = /^(.*?):(\d+)(?::(\d+))?$/;
+var EVAL_ORIGIN = /\(([^()]*?:\d+:\d+)\)/;
+function parseStack(stack, o = {}) {
+  if (typeof stack !== "string" || !stack) return [];
+  const frames = [];
+  for (const raw of stack.split("\n")) {
+    if (frames.length >= MAX_DETAIL_FRAMES * 2) break;
+    const m = LINE.exec(raw.length > 2e3 ? raw.slice(0, 2e3) : raw);
+    if (!m) continue;
+    const fn = m[1]?.trim();
+    let location = (m[2] ?? m[3] ?? "").trim();
+    if (location.startsWith("eval at ")) location = EVAL_ORIGIN.exec(location)?.[1] ?? location;
+    const at = LOCATION.exec(location);
+    const frame = {};
+    if (fn) frame.function = fn.slice(0, 200);
+    if (at) {
+      const file = filePath(at[1]);
+      frame.filename = file.slice(0, 1e3);
+      frame.abs_path = file.slice(0, 1e3);
+      frame.lineno = Number(at[2]);
+      if (at[3]) frame.colno = Number(at[3]);
+      const mod = moduleOf(file, o.root);
+      if (mod) frame.module = mod;
+      frame.in_app = isInApp(file, o.inAppExclude);
+    } else {
+      if (!fn && !location) continue;
+      if (location && !/^index \d+$/.test(location)) frame.filename = location.slice(0, 200);
+      frame.in_app = false;
+    }
+    frames.push(frame);
+  }
+  frames.reverse();
+  return frames.length > MAX_DETAIL_FRAMES ? frames.slice(-MAX_DETAIL_FRAMES) : frames;
+}
+function filePath(location) {
+  if (!location.startsWith("file://")) return location;
+  try {
+    return fileURLToPath(location);
+  } catch {
+    return location;
+  }
+}
+function isInApp(file, exclude) {
+  if (!file || file.startsWith("node:") || file.startsWith("internal/")) return false;
+  if (!file.startsWith("/") && !/^[a-z]:[\\/]/i.test(file) && !file.startsWith("\\\\")) return false;
+  if (/[\\/]node_modules[\\/]/.test(file)) return false;
+  for (const p of exclude ?? []) {
+    if (typeof p === "string") {
+      if (p && file.includes(p)) return false;
+    } else if (p instanceof RegExp) {
+      p.lastIndex = 0;
+      if (p.test(file)) return false;
+    }
+  }
+  return true;
+}
+function moduleOf(file, root) {
+  if (!file || file.startsWith("node:") || file.startsWith("internal/")) return void 0;
+  const normalized = file.replace(/^[a-z]:/i, "").replace(/\\/g, "/");
+  if (!normalized.startsWith("/")) return void 0;
+  const parsed = posix.parse(normalized);
+  let name = /^\.[cm]?[jt]sx?$/.test(parsed.ext) ? parsed.name : parsed.base;
+  try {
+    name = decodeURIComponent(name);
+  } catch {
+  }
+  const dir = parsed.dir || ".";
+  const n = dir.lastIndexOf("/node_modules");
+  if (n > -1) return `${dir.slice(n + 14).replace(/\//g, ".")}:${name}`;
+  const base = root?.replace(/^[a-z]:/i, "").replace(/\\/g, "/").replace(/\/+$/, "");
+  if (base && (dir === base || dir.startsWith(`${base}/`))) {
+    const mod = dir.slice(base.length + 1).replace(/\//g, ".");
+    return mod ? `${mod}:${name}` : name;
+  }
+  return name;
+}
+function toGuidelyFrames(frames) {
+  const out = [];
+  if (!frames) return out;
+  for (let i = frames.length - 1; i >= 0 && out.length < MAX_PROPERTY_FRAMES; i--) {
+    const f = frames[i];
+    const file = f.abs_path || f.filename;
+    out.push({
+      ...f.function ? { fn: f.function.slice(0, 200) } : {},
+      ...file ? { file: file.slice(0, 500) } : {},
+      ...typeof f.lineno === "number" ? { line: f.lineno } : {},
+      ...typeof f.colno === "number" ? { col: f.colno } : {},
+      ...typeof f.in_app === "boolean" ? { inApp: f.in_app } : {}
+    });
+  }
+  return out;
+}
+
+// src/errors/event.ts
+var ERROR_LIMITS = {
+  /** `detail` (the Sentry-shaped event) after trimming. */
+  maxDetailBytes: 65536,
+  /** `properties`, inside the event's property budget. */
+  maxPropertyBytes: 8192,
+  /** A whole `exception` message: properties + detail + envelope. Larger ones lose their `detail`. */
+  maxMessageBytes: 81920,
+  /** Exceptions in a cause / AggregateError chain. */
+  maxChain: 20
+};
+var newEventId = () => randomUUID().replace(/-/g, "");
+var errorLike = (v) => v instanceof Error || !!v && typeof v === "object" && typeof v.message === "string" && (typeof v.stack === "string" || typeof v.name === "string");
+function typeOf(e) {
+  const name = typeof e.name === "string" && e.name ? e.name : void 0;
+  const ctor = e.constructor?.name;
+  return (name === "Error" && typeof ctor === "string" && ctor && ctor !== "Error" ? ctor : name) ?? (typeof ctor === "string" && ctor ? ctor : "Error");
+}
+function describe(value) {
+  if (typeof value === "string") return value;
+  if (value === void 0 || value === null || typeof value !== "object") return String(value);
+  const keys = Object.keys(value).slice(0, 10);
+  return keys.length ? `Non-Error exception captured with keys: ${keys.join(", ")}` : `Non-Error exception captured: ${Object.prototype.toString.call(value)}`;
+}
+function exceptionChain(error, mechanism, o, fallbackType = "Error") {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (value, mech) => {
+    if (out.length >= ERROR_LIMITS.maxChain) return;
+    seen.add(value);
+    const id2 = out.length;
+    const isError = errorLike(value);
+    const frames = isError ? parseStack(value.stack, o) : [];
+    const aggregate = isError && Array.isArray(value.errors);
+    const ex = {
+      type: (isError ? typeOf(value) : fallbackType).slice(0, 200),
+      value: (isError ? String(value.message ?? "") : describe(value)).slice(0, 8e3),
+      mechanism: { ...mech, exception_id: id2, ...aggregate ? { is_exception_group: true } : {} },
+      ...frames.length ? { stacktrace: { frames } } : {}
+    };
+    out.push(ex);
+    if (!isError) return;
+    const link = (child, source) => {
+      if (!errorLike(child) || seen.has(child)) return;
+      visit(child, { type: "chained", handled: mechanism.handled, source, parent_id: id2 });
+    };
+    if (aggregate) value.errors.slice(0, ERROR_LIMITS.maxChain).forEach((child, i) => link(child, `errors[${i}]`));
+    link(value.cause, "cause");
+  };
+  visit(error, { type: mechanism.type, handled: mechanism.handled });
+  return out.reverse();
+}
+function linuxRelease() {
+  try {
+    const text = readFileSync("/etc/os-release", "utf8").slice(0, 1e4);
+    const field = (k) => new RegExp(`^${k}="?([^"\\n]*)"?$`, "m").exec(text)?.[1];
+    return { name: field("NAME"), version: field("VERSION_ID") };
+  } catch {
+    return {};
+  }
+}
+function macosVersion(release2) {
+  const major = Number(release2.split(".")[0]);
+  if (!Number.isFinite(major)) return void 0;
+  if (major >= 25) return String(major + 1);
+  if (major >= 20) return String(major - 9);
+  return major >= 5 ? `10.${major - 4}` : void 0;
+}
+var staticContexts = null;
+function processContexts() {
+  if (!staticContexts) {
+    const release2 = safe(() => os.release(), "");
+    const platform = process.platform;
+    const linux = platform === "linux" ? linuxRelease() : {};
+    const osName = platform === "darwin" ? "macOS" : platform === "win32" ? "Windows" : platform === "linux" ? linux.name ?? "Linux" : safe(() => os.type(), platform);
+    const osVersion = platform === "darwin" ? macosVersion(release2) : platform === "linux" ? linux.version : release2;
+    const cpus2 = safe(() => os.cpus(), []);
+    const intl = safe(() => Intl.DateTimeFormat().resolvedOptions(), void 0);
+    staticContexts = {
+      runtime: { name: "node", version: process.version },
+      os: { name: osName, ...osVersion ? { version: osVersion } : {}, ...release2 ? { kernel_version: release2 } : {} },
+      device: {
+        arch: process.arch,
+        memory_size: safe(() => os.totalmem(), void 0),
+        processor_count: cpus2.length || void 0,
+        cpu_description: cpus2[0]?.model,
+        processor_frequency: cpus2[0]?.speed || void 0,
+        boot_time: safe(() => new Date(Date.now() - os.uptime() * 1e3).toISOString(), void 0)
+      },
+      app: { app_start_time: new Date(Date.now() - process.uptime() * 1e3).toISOString() },
+      culture: intl ? { locale: intl.locale, timezone: intl.timeZone } : {}
+    };
+  }
+  const s = staticContexts;
+  return {
+    runtime: { ...s.runtime },
+    os: { ...s.os },
+    device: { ...s.device, free_memory: safe(() => os.freemem(), void 0) },
+    app: { ...s.app, app_memory: safe(() => process.memoryUsage().rss, void 0) },
+    culture: { ...s.culture }
+  };
+}
+function safe(fn, fallback) {
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+}
+var bytes = (v) => Buffer.byteLength(JSON.stringify(v) ?? "", "utf8");
+function trimDetail(event, max = ERROR_LIMITS.maxDetailBytes) {
+  let size = bytes(event);
+  if (size <= max) return event;
+  const e = { ...event };
+  const frames = () => (e.exception?.values ?? []).flatMap((x) => x.stacktrace?.frames ?? []);
+  let crumbs = e.breadcrumbs?.values ?? [];
+  while (crumbs.length > 0 && size > max) {
+    crumbs = crumbs.slice(Math.ceil(crumbs.length / 2));
+    e.breadcrumbs = { values: crumbs };
+    size = bytes(e);
+  }
+  if (size <= max) return e;
+  delete e.breadcrumbs;
+  e.exception = e.exception ? { values: e.exception.values.map((x) => ({ ...x, ...x.stacktrace ? { stacktrace: { frames: x.stacktrace.frames.map((f) => ({ ...f })) } } : {} })) } : void 0;
+  if (!e.exception) delete e.exception;
+  for (const f of frames()) {
+    delete f.pre_context;
+    delete f.post_context;
+    delete f.context_line;
+    delete f.vars;
+  }
+  size = bytes(e);
+  if (size <= max) return e;
+  e.extra = { _trimmed: true };
+  if (e.request) e.request = { ...e.request, headers: {} };
+  size = bytes(e);
+  if (size <= max) return e;
+  for (const x of e.exception?.values ?? []) if (x.stacktrace && x.stacktrace.frames.length > 50) x.stacktrace.frames = x.stacktrace.frames.slice(-50);
+  while (e.exception && e.exception.values.length > 1 && bytes(e) > max) e.exception.values.shift();
+  if (bytes(e) <= max) return e;
+  e.contexts = { runtime: e.contexts?.runtime ?? {} };
+  delete e.extra;
+  return bytes(e) <= max ? e : void 0;
+}
+function propertiesOf(event, source, release2, extra) {
+  const main = event.exception?.values?.[event.exception.values.length - 1];
+  const os3 = event.contexts?.os;
+  const props = {
+    type: (main?.type ?? "Message").slice(0, 200),
+    message: (main?.value ?? event.logentry?.formatted ?? "").slice(0, 1e3),
+    frames: toGuidelyFrames(main?.stacktrace?.frames),
+    source,
+    handled: main?.mechanism ? main.mechanism.handled !== false : event.level !== "fatal",
+    level: event.level,
+    platform: "node",
+    ...main?.mechanism?.type ? { mechanism: main.mechanism.type.slice(0, 60) } : {},
+    ...release2 ? { release: release2.slice(0, 200) } : {},
+    ...Array.isArray(event.fingerprint) && event.fingerprint.length ? { fingerprintParts: event.fingerprint.slice(0, 20).map((p) => String(p).slice(0, 200)) } : {},
+    ...event.transaction ? { transaction: String(event.transaction).slice(0, 200) } : {},
+    ...os3?.name ? { os: [os3.name, os3.version].filter(Boolean).join(" ").slice(0, 60) } : {}
+  };
+  const user = normalize(extra, 3);
+  for (const [k, v] of Object.entries(user ?? {})) if (!(k in props) && !k.startsWith("$")) props[k] = v;
+  return fitProperties(props);
+}
+function fitProperties(props) {
+  if (bytes(props) <= ERROR_LIMITS.maxPropertyBytes) return props;
+  const core = /* @__PURE__ */ new Set(["type", "message", "frames", "source", "handled", "level", "platform", "mechanism", "release", "fingerprintParts", "transaction", "os"]);
+  const out = {};
+  for (const [k, v] of Object.entries(props)) if (core.has(k)) out[k] = v;
+  const frames = out.frames.slice();
+  while (frames.length > 1 && bytes(out) > ERROR_LIMITS.maxPropertyBytes) {
+    frames.pop();
+    out.frames = frames;
+  }
+  if (bytes(out) > ERROR_LIMITS.maxPropertyBytes) out.message = String(out.message).slice(0, 200);
+  return out;
+}
+
+// src/errors/monitor.ts
+import { AsyncLocalStorage, AsyncResource } from "async_hooks";
+import * as os2 from "os";
+import { dirname } from "path";
+
+// src/errors/breadcrumbs.ts
+import * as dc from "diagnostics_channel";
+import { format } from "util";
+var CONSOLE_LEVEL = { debug: "debug", info: "info", log: "log", warn: "warning", error: "error" };
+var wrapped = /* @__PURE__ */ new Map();
+var inConsole = false;
+function instrumentConsole(levels, record) {
+  const target = console;
+  const mine = [];
+  for (const level of new Set(levels)) {
+    if (typeof target[level] !== "function") continue;
+    let w = wrapped.get(level);
+    if (w && w.listeners.size === 0 && target[level] !== w.wrapper) {
+      wrapped.delete(level);
+      w = void 0;
+    }
+    if (!w) {
+      const original = target[level];
+      const listeners = /* @__PURE__ */ new Set();
+      const wrapper = function(...args) {
+        if (!inConsole && listeners.size > 0) {
+          inConsole = true;
+          try {
+            const message = format(...args);
+            if (!message.startsWith("[guidely-node]")) {
+              const crumb = { category: "console", level: CONSOLE_LEVEL[level], message: message.slice(0, 1e3), data: { arguments: normalize(args, 3), logger: "console" } };
+              for (const l of listeners) l({ ...crumb }, { input: args, level });
+            }
+          } catch {
+          } finally {
+            inConsole = false;
+          }
+        }
+        return original.apply(this, args);
+      };
+      w = { original, wrapper, listeners };
+      wrapped.set(level, w);
+      target[level] = wrapper;
+    }
+    w.listeners.add(record);
+    mine.push(level);
+  }
+  return () => {
+    for (const level of mine) {
+      const w = wrapped.get(level);
+      if (!w) continue;
+      w.listeners.delete(record);
+      if (w.listeners.size === 0 && target[level] === w.wrapper) {
+        target[level] = w.original;
+        wrapped.delete(level);
+      }
+    }
+  };
+}
+function subscribe2(name, handler) {
+  try {
+    if (typeof dc.subscribe === "function") {
+      dc.subscribe(name, handler);
+      return () => dc.unsubscribe(name, handler);
+    }
+    const ch = dc.channel(name);
+    ch.subscribe(handler);
+    return () => ch.unsubscribe(handler);
+  } catch {
+    return () => {
+    };
+  }
+}
+var levelOf = (status) => status === void 0 || status >= 500 ? "error" : status >= 400 ? "warning" : "info";
+function instrumentHttp(record, current, ignore) {
+  const started = /* @__PURE__ */ new WeakMap();
+  const begin = (request, method, url) => {
+    if (ignore(url)) return;
+    started.set(request, { method: typeof method === "string" ? method.toUpperCase() : "GET", url: stripQuery(url), start: Date.now(), target: current() });
+  };
+  const end = (request, response, status, error) => {
+    const s = started.get(request);
+    if (!s) return;
+    started.delete(request);
+    const data = { method: s.method, url: s.url, ...status !== void 0 ? { status_code: status } : {}, duration_ms: Date.now() - s.start };
+    if (error) data.error = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
+    try {
+      record({ type: "http", category: "http", level: levelOf(status), data }, { request, response }, s.target);
+    } catch {
+    }
+  };
+  const statusOf2 = (response) => {
+    const code = response?.statusCode;
+    return typeof code === "number" ? code : void 0;
+  };
+  const offs = [
+    // http / https
+    subscribe2("http.client.request.start", (m) => {
+      const req = m.request;
+      if (!req || typeof req !== "object") return;
+      const host = typeof req.getHeader === "function" ? req.getHeader("host") : void 0;
+      begin(req, req.method, `${req.protocol ?? "http:"}//${typeof host === "string" ? host : req.host ?? ""}${req.path ?? "/"}`);
+    }),
+    subscribe2("http.client.response.finish", (m) => {
+      const { request, response } = m;
+      if (request) end(request, response, statusOf2(response));
+    }),
+    subscribe2("http.client.request.error", (m) => {
+      const { request, error } = m;
+      if (request) end(request, void 0, void 0, error);
+    }),
+    // fetch / undici
+    subscribe2("undici:request:create", (m) => {
+      const req = m.request;
+      if (!req || typeof req !== "object") return;
+      const origin = String(req.origin ?? "").replace(/\/+$/, "");
+      begin(req, req.method, `${origin}${req.path ?? "/"}`);
+    }),
+    subscribe2("undici:request:headers", (m) => {
+      const { request, response } = m;
+      if (request) end(request, response, statusOf2(response));
+    }),
+    subscribe2("undici:request:error", (m) => {
+      const { request, error } = m;
+      if (request) end(request, void 0, void 0, error);
+    })
+  ];
+  return () => offs.forEach((off) => off());
+}
+
+// src/errors/context-lines.ts
+import { readFile, stat } from "fs/promises";
+import { isAbsolute } from "path";
+var MAX_FILE_BYTES = 1e6;
+var MAX_CACHED_FILES = 20;
+var MAX_FRAMES = 50;
+var MAX_LINE = 200;
+var MAX_CONTEXT_LINES = 10;
+var cache = /* @__PURE__ */ new Map();
+var loading = /* @__PURE__ */ new Map();
+function remember(file, lines) {
+  cache.delete(file);
+  cache.set(file, lines);
+  while (cache.size > MAX_CACHED_FILES) cache.delete(cache.keys().next().value);
+}
+function linesOf(file) {
+  if (cache.has(file)) {
+    const lines = cache.get(file);
+    remember(file, lines);
+    return Promise.resolve(lines);
+  }
+  let p = loading.get(file);
+  if (!p) {
+    p = (async () => {
+      try {
+        const s = await stat(file);
+        if (!s.isFile() || s.size > MAX_FILE_BYTES) return null;
+        return (await readFile(file, "utf8")).split(/\r?\n/);
+      } catch {
+        return null;
+      }
+    })().then((lines) => {
+      loading.delete(file);
+      remember(file, lines);
+      return lines;
+    });
+    loading.set(file, p);
+  }
+  return p;
+}
+function snip(line, colno) {
+  if (line.length <= MAX_LINE) return line;
+  const at = colno ? Math.max(0, colno - 1) : 0;
+  const start = Math.max(0, Math.min(at - 60, line.length - MAX_LINE));
+  const end = Math.min(line.length, start + MAX_LINE);
+  return `${start > 0 ? "{snip} " : ""}${line.slice(start, end)}${end < line.length ? " {snip}" : ""}`;
+}
+function wantsContext(frames) {
+  return frames.some((f) => f.in_app && f.lineno && f.abs_path && isAbsolute(f.abs_path));
+}
+async function addContextLines(frames, n) {
+  const count = Math.min(Math.max(0, Math.floor(n)), MAX_CONTEXT_LINES);
+  if (count === 0) return;
+  const targets = frames.filter((f) => f.in_app && f.lineno && f.abs_path && isAbsolute(f.abs_path)).slice(-MAX_FRAMES);
+  await Promise.all(
+    targets.map(async (f) => {
+      const lines = await linesOf(f.abs_path);
+      const i = f.lineno - 1;
+      if (!lines || i < 0 || i >= lines.length) return;
+      f.pre_context = lines.slice(Math.max(0, i - count), i).map((l) => snip(l));
+      f.context_line = snip(lines[i], f.colno);
+      f.post_context = lines.slice(i + 1, i + 1 + count).map((l) => snip(l));
+    })
+  );
+}
+
+// src/errors/process-handlers.ts
+import { inspect } from "util";
+var OURS = /* @__PURE__ */ Symbol.for("guidely.processHandler");
+var isOurs = (l) => typeof l === "function" && l[OURS] === true;
+function nodeMode(proc) {
+  const args = [...proc.execArgv ?? [], ...(proc.env?.NODE_OPTIONS ?? "").split(/\s+/)];
+  for (const a of args) {
+    const m = /^--unhandled-rejections=([\w-]+)$/.exec(a);
+    if (m && ["throw", "strict", "warn", "warn-with-error-code", "none"].includes(m[1])) return m[1];
+  }
+  return "throw";
+}
+function installProcessHandlers(host, o = {}) {
+  const proc = o.process ?? process;
+  const exitOnUncaught = o.exitOnUncaught !== false;
+  const mode = o.unhandledRejection ?? nodeMode(proc);
+  const flushTimeoutMs = typeof o.flushTimeoutMs === "number" && o.flushTimeoutMs >= 0 ? o.flushTimeoutMs : 2e3;
+  let exiting = false;
+  const others = (event) => proc.listeners(event).filter((l) => !isOurs(l)).length;
+  const exit = (error, prefix) => {
+    if (exiting) return;
+    exiting = true;
+    try {
+      console.error(`${prefix}${inspect(error)}`);
+    } catch {
+    }
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(resolve, flushTimeoutMs);
+    });
+    void Promise.race([host.flush().catch(() => {
+    }), timeout]).then(() => {
+      clearTimeout(timer);
+      proc.exitCode = 1;
+      proc.exit(1);
+    });
+  };
+  const onUncaught = (error) => {
+    const crash = exitOnUncaught && others("uncaughtException") === 0;
+    host.capture(error, { mechanism: "uncaughtException", level: "fatal" });
+    if (crash) exit(error, "Uncaught ");
+  };
+  const onRejection = (reason) => {
+    const raised = mode === "strict" || mode === "throw" && others("unhandledRejection") === 0;
+    const crash = exitOnUncaught && raised && others("uncaughtException") === 0;
+    host.capture(reason, { mechanism: "unhandledRejection", level: crash ? "fatal" : "error", fallbackType: "UnhandledRejection" });
+    if (crash) return exit(reason, "Unhandled promise rejection: ");
+    if (mode === "none" || others("unhandledRejection") > 0) return;
+    if (mode === "warn-with-error-code") proc.exitCode = 1;
+    try {
+      console.warn(`Unhandled promise rejection: ${inspect(reason)}`);
+    } catch {
+    }
+  };
+  for (const l of [onUncaught, onRejection]) l[OURS] = true;
+  proc.on("uncaughtException", onUncaught);
+  proc.on("unhandledRejection", onRejection);
+  let installed = true;
+  return () => {
+    if (!installed) return;
+    installed = false;
+    proc.removeListener("uncaughtException", onUncaught);
+    proc.removeListener("unhandledRejection", onRejection);
+  };
+}
+
+// src/errors/request.ts
+var str = (v, max = 2e3) => typeof v === "string" && v ? v.slice(0, max) : void 0;
+function nodeRequestOf(r) {
+  const req = r.req;
+  return req && typeof req === "object" ? req : r;
+}
+function header(headers, name) {
+  const v = headers?.[name];
+  return Array.isArray(v) ? v[0] : typeof v === "string" ? v : typeof v === "number" ? String(v) : void 0;
+}
+function transactionOf(input) {
+  if (!input || typeof input !== "object") return void 0;
+  const r = input;
+  const method = str(r.method, 16)?.toUpperCase();
+  const routePath = typeof r.route?.path === "string" ? r.route.path : void 0;
+  const route = str(r.routeOptions?.url) ?? str(r.routerPath) ?? str(r._matchedRoute) ?? (routePath !== void 0 ? `${r.baseUrl ?? ""}${routePath}` || "/" : void 0);
+  return method && route ? `${method} ${route}`.slice(0, 200) : void 0;
+}
+function requestDataOf(input, sendDefaultPii) {
+  if (!input || typeof input !== "object") return void 0;
+  const r = input;
+  const node = nodeRequestOf(r);
+  const rawHeaders = (r.headers && typeof r.headers === "object" ? r.headers : node.headers) ?? {};
+  const headers = {};
+  let n = 0;
+  for (const [name, value] of Object.entries(rawHeaders)) {
+    if (n >= 50) break;
+    if (value === void 0 || SENSITIVE_HEADER.test(name) || !sendDefaultPii && IP_HEADER.test(name)) continue;
+    headers[name.toLowerCase()] = (Array.isArray(value) ? value.join(", ") : String(value)).slice(0, 1e3);
+    n++;
+  }
+  const raw = str(r.originalUrl) ?? str(node.originalUrl) ?? str(r.url) ?? str(node.url) ?? "";
+  let url = raw;
+  let query = typeof r.query_string === "string" ? r.query_string : void 0;
+  const q = raw.indexOf("?");
+  if (q >= 0) {
+    query = raw.slice(q + 1).replace(/#.*$/, "");
+    url = raw.slice(0, q);
+  }
+  url = url.replace(/#.*$/, "");
+  if (url && !/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
+    const host = header(rawHeaders, "host") ?? str(r.host) ?? str(r.hostname);
+    const protocol = (str(r.protocol) ?? (node.socket?.encrypted ? "https" : "http")).replace(/:$/, "");
+    if (host) url = `${protocol}://${host}${url.startsWith("/") ? "" : "/"}${url}`;
+  }
+  const request = {
+    ...str(r.method, 16) ? { method: str(r.method, 16).toUpperCase() } : {},
+    ...url ? { url: url.slice(0, 2e3) } : {},
+    ...query ? { query_string: scrubQuery(query) } : {},
+    headers
+  };
+  if (!sendDefaultPii) return { request };
+  const forwarded = header(rawHeaders, "x-forwarded-for")?.split(",")[0]?.trim();
+  const ip = str(r.ip, 64) ?? str(forwarded, 64) ?? str(node.socket?.remoteAddress, 64);
+  if (ip) request.env = { REMOTE_ADDR: ip };
+  return { request, ...ip ? { ip } : {} };
+}
+function scrubRequest(request, sendDefaultPii) {
+  if (!request || typeof request !== "object") return void 0;
+  const headers = {};
+  for (const [k, v] of Object.entries(request.headers ?? {})) if (!SENSITIVE_HEADER.test(k) && (sendDefaultPii || !IP_HEADER.test(k))) headers[k] = String(v).slice(0, 1e3);
+  return {
+    ...request,
+    ...typeof request.query_string === "string" ? { query_string: scrubQuery(request.query_string) } : {},
+    ...typeof request.url === "string" && request.url.includes("?") ? { url: `${request.url.split("?")[0]}?${scrubQuery(request.url.split("?").slice(1).join("?"))}` } : {},
+    headers
+  };
+}
+
+// src/errors/scope.ts
+var MAX_BREADCRUMBS = 100;
+var MAX_TAGS = 50;
+var Scope = class _Scope {
+  /** @internal `max`: breadcrumbs kept; `hook`: the client's breadcrumb pipeline (`beforeBreadcrumb`). */
+  constructor(max = MAX_BREADCRUMBS, hook) {
+    this.max = max;
+    this.hook = hook;
+  }
+  max;
+  hook;
+  tags = {};
+  extra = {};
+  contexts = {};
+  user = null;
+  level;
+  fingerprint;
+  transaction;
+  crumbs = [];
+  /** @internal The framework request this scope was opened for (read when an error is captured). */
+  request;
+  /** A tag (searchable, ≤ 50 per event; keys ≤ 32 and values ≤ 200 characters). `null` removes it. */
+  setTag(key, value) {
+    if (typeof key !== "string" || !key) return this;
+    const k = key.slice(0, 32);
+    if (value === null || value === void 0) delete this.tags[k];
+    else if (k in this.tags || Object.keys(this.tags).length < MAX_TAGS) this.tags[k] = String(value).slice(0, 200);
+    return this;
+  }
+  setTags(tags) {
+    if (tags && typeof tags === "object") for (const [k, v] of Object.entries(tags)) this.setTag(k, v);
+    return this;
+  }
+  /** Arbitrary data shown with the event. `undefined` removes it. */
+  setExtra(key, value) {
+    if (typeof key !== "string" || !key) return this;
+    if (value === void 0) delete this.extra[key];
+    else this.extra[key] = value;
+    return this;
+  }
+  setExtras(extras) {
+    if (extras && typeof extras === "object") for (const [k, v] of Object.entries(extras)) this.setExtra(k, v);
+    return this;
+  }
+  /** A named context (`{ name: "checkout", cartSize: 3 }`); `null` removes it. */
+  setContext(name, context) {
+    if (typeof name !== "string" || !name) return this;
+    if (context === null || context === void 0 || typeof context !== "object") delete this.contexts[name];
+    else this.contexts[name] = { ...context };
+    return this;
+  }
+  /** The user errors are attributed to; `user.id` becomes the event's `userId`. `null` clears it. */
+  setUser(user) {
+    this.user = user && typeof user === "object" ? { ...user } : null;
+    return this;
+  }
+  /** Overrides the level of events captured in this scope. */
+  setLevel(level) {
+    this.level = level;
+    return this;
+  }
+  setFingerprint(fingerprint) {
+    this.fingerprint = Array.isArray(fingerprint) ? fingerprint.map(String) : void 0;
+    return this;
+  }
+  /** The transaction name (`GET /users/:id`); the request middlewares set it from the matched route. */
+  setTransactionName(name) {
+    this.transaction = typeof name === "string" && name ? name.slice(0, 200) : void 0;
+    return this;
+  }
+  /** Records a breadcrumb through the client's `beforeBreadcrumb`. */
+  addBreadcrumb(crumb) {
+    if (this.hook) this.hook(crumb, this);
+    else this.pushBreadcrumb(crumb);
+    return this;
+  }
+  /** @internal Adds an already-filtered breadcrumb, dropping the oldest beyond the limit. */
+  pushBreadcrumb(crumb) {
+    this.crumbs.push(crumb);
+    if (this.crumbs.length > this.max) this.crumbs.splice(0, this.crumbs.length - this.max);
+  }
+  clearBreadcrumbs() {
+    this.crumbs = [];
+    return this;
+  }
+  /** Removes everything (tags, extras, contexts, user, breadcrumbs…). */
+  clear() {
+    this.tags = {};
+    this.extra = {};
+    this.contexts = {};
+    this.user = null;
+    this.level = void 0;
+    this.fingerprint = void 0;
+    this.transaction = void 0;
+    this.crumbs = [];
+    this.request = void 0;
+    return this;
+  }
+  /** A copy whose changes do not affect this scope. */
+  clone() {
+    const s = new _Scope(this.max, this.hook);
+    s.tags = { ...this.tags };
+    s.extra = { ...this.extra };
+    s.contexts = { ...this.contexts };
+    s.user = this.user ? { ...this.user } : null;
+    s.level = this.level;
+    s.fingerprint = this.fingerprint;
+    s.transaction = this.transaction;
+    s.crumbs = this.crumbs.slice();
+    s.request = this.request;
+    return s;
+  }
+  /** @internal The scope's data at capture time. */
+  data() {
+    return {
+      tags: { ...this.tags },
+      extra: { ...this.extra },
+      contexts: { ...this.contexts },
+      user: this.user ? { ...this.user } : null,
+      level: this.level,
+      fingerprint: this.fingerprint,
+      transaction: this.transaction,
+      breadcrumbs: this.crumbs.slice(),
+      request: this.request
+    };
+  }
+};
+
+// src/errors/monitor.ts
+var LEVELS = ["fatal", "error", "warning", "log", "info", "debug"];
+var levelOf2 = (v) => typeof v === "string" && LEVELS.includes(v) ? v : v === "warn" ? "warning" : void 0;
+var KNOWN_CONTEXT_KEYS = /* @__PURE__ */ new Set(["userId", "anonymousId", "accountId", "tags", "extra", "level", "fingerprint", "contexts", "request", "user", "mechanism", "transaction"]);
+var idString = (v) => typeof v === "string" && v.trim() ? v.slice(0, 256) : typeof v === "number" && Number.isSafeInteger(v) ? String(v) : void 0;
+function statusOf(error) {
+  if (!error || typeof error !== "object") return void 0;
+  const e = error;
+  for (const v of [e.status, e.statusCode, e.status_code, e.output?.statusCode]) {
+    const n = typeof v === "string" ? Number(v) : v;
+    if (typeof n === "number" && Number.isInteger(n) && n >= 100 && n < 600) return n;
+  }
+  return void 0;
+}
+var defaultShouldHandle = (error) => {
+  const status = statusOf(error);
+  return status === void 0 || status >= 500;
+};
+var ErrorMonitor = class {
+  constructor(host, options) {
+    this.host = host;
+    const o = options && typeof options === "object" ? options : {};
+    this.options = o;
+    const max = typeof o.maxBreadcrumbs === "number" && o.maxBreadcrumbs >= 0 ? Math.min(MAX_BREADCRUMBS, Math.floor(o.maxBreadcrumbs)) : MAX_BREADCRUMBS;
+    this.global = new Scope(max, (crumb, scope) => this.record(crumb, void 0, scope));
+    const entry = typeof process !== "undefined" ? process.argv?.[1] : void 0;
+    this.frameOptions = { root: entry ? dirname(entry) : safeCwd(), inAppExclude: Array.isArray(o.inAppExclude) ? o.inAppExclude : void 0 };
+    this.sampleRate = typeof o.sampleRate === "number" && Number.isFinite(o.sampleRate) ? Math.min(1, Math.max(0, o.sampleRate)) : 1;
+    this.contextLines = typeof o.contextLines === "number" && Number.isFinite(o.contextLines) ? Math.max(0, Math.floor(o.contextLines)) : 5;
+    this.pii = o.sendDefaultPii === true;
+    this.release = (typeof o.release === "string" && o.release.trim() ? o.release.trim() : host.appVersion)?.slice(0, 200);
+    let serverName;
+    try {
+      serverName = typeof o.serverName === "string" && o.serverName ? o.serverName : os2.hostname();
+    } catch {
+      serverName = void 0;
+    }
+    this.serverName = serverName?.slice(0, 200);
+    if (options === false) return;
+    const levels = o.captureConsole === false ? [] : Array.isArray(o.captureConsole) ? o.captureConsole : ["warn", "error"];
+    if (levels.length) this.cleanups.push(instrumentConsole(levels, (crumb, hint) => this.record(crumb, hint, this.current())));
+    if (o.captureHttp !== false) {
+      const own = originOf(host.apiUrl);
+      this.cleanups.push(
+        instrumentHttp(
+          (crumb, hint, target) => this.record(crumb, hint, target instanceof Scope ? target : this.global),
+          () => this.current(),
+          (url) => !!own && originOf(url) === own
+        )
+      );
+    }
+  }
+  host;
+  global;
+  als = new AsyncLocalStorage();
+  requestScopes = /* @__PURE__ */ new WeakMap();
+  /** Errors already reported by an automatic hook (an error passing through two middlewares, or a middleware and the process handler). */
+  captured = /* @__PURE__ */ new WeakSet();
+  bound = /* @__PURE__ */ new WeakSet();
+  pending = /* @__PURE__ */ new Set();
+  cleanups = [];
+  options;
+  frameOptions;
+  sampleRate;
+  contextLines;
+  pii;
+  release;
+  serverName;
+  // --- scopes --------------------------------------------------------------------------------
+  /** The scope of the running request / `withScope()` callback, else the process-wide one. */
+  current() {
+    return this.als.getStore() ?? this.global;
+  }
+  withScope(fn) {
+    const scope = this.current().clone();
+    return this.als.run(scope, () => fn(scope));
+  }
+  addBreadcrumb(crumb, hint) {
+    this.record(crumb, hint, this.current());
+  }
+  /** Validates a breadcrumb, runs `beforeBreadcrumb` and adds it to `scope`. */
+  record(crumb, hint, scope) {
+    try {
+      if (!crumb || typeof crumb !== "object") return;
+      let c = {
+        timestamp: typeof crumb.timestamp === "number" && Number.isFinite(crumb.timestamp) ? crumb.timestamp : Date.now() / 1e3,
+        ...typeof crumb.type === "string" && crumb.type ? { type: crumb.type.slice(0, 40) } : {},
+        ...typeof crumb.category === "string" && crumb.category ? { category: crumb.category.slice(0, 100) } : {},
+        ...levelOf2(crumb.level) ? { level: levelOf2(crumb.level) } : {},
+        ...typeof crumb.message === "string" ? { message: crumb.message.slice(0, 1e3) } : crumb.message !== void 0 ? { message: String(crumb.message).slice(0, 1e3) } : {}
+      };
+      const data = normalizeObject(crumb.data, 3);
+      if (data) c.data = data;
+      const hook = this.options.beforeBreadcrumb;
+      if (typeof hook === "function") {
+        let out = c;
+        try {
+          out = hook(c, hint);
+        } catch {
+          out = c;
+        }
+        if (out === null) return;
+        if (out && typeof out === "object" && out !== c) c = { ...out, ...out.data ? { data: normalizeObject(out.data, 3) } : {} };
+      }
+      scope.pushBreadcrumb(c);
+    } catch {
+    }
+  }
+  // --- capture -------------------------------------------------------------------------------
+  captureException(error, context) {
+    const m = context?.mechanism;
+    return this.capture({ error }, context, { type: m?.type ? String(m.type).slice(0, 60) : "generic", handled: m?.handled ?? true, level: "error", source: "manual" });
+  }
+  captureMessage(message, level, context) {
+    const ctx = level && typeof level === "object" ? level : context;
+    const lvl = typeof level === "string" ? levelOf2(level) : void 0;
+    return this.capture({ message: typeof message === "string" ? message : String(message) }, ctx, { type: "generic", handled: true, level: lvl ?? "info", source: "manual" });
+  }
+  /** An error caught by an automatic hook (process handler, middleware); skipped when already reported. */
+  captureAuto(error, kind) {
+    if (error && typeof error === "object") {
+      if (this.captured.has(error)) return void 0;
+    }
+    return this.capture({ error }, kind.request ? { request: kind.request } : void 0, {
+      type: kind.mechanism,
+      handled: false,
+      level: kind.level ?? "error",
+      source: kind.mechanism,
+      fallbackType: kind.fallbackType
+    });
+  }
+  capture(input, context, mech) {
+    const eventId = newEventId();
+    try {
+      if (!this.host.accepting()) {
+        this.host.report(`${"error" in input ? "captureException" : "captureMessage"}() was called after shutdown(); the event was dropped`, void 0, "closed");
+        return eventId;
+      }
+      const ctx = context && typeof context === "object" && !Array.isArray(context) ? context : {};
+      const scope = (ctx.request && typeof ctx.request === "object" ? this.requestScopes.get(ctx.request) : void 0) ?? this.current();
+      const data = scope.data();
+      const values = "error" in input ? exceptionChain(input.error, { type: mech.type, handled: mech.handled }, this.frameOptions, mech.fallbackType) : void 0;
+      const main = values?.[values.length - 1];
+      if (this.ignored(main?.type, main ? main.value : input.message)) return eventId;
+      if (this.sampleRate < 1 && Math.random() >= this.sampleRate) return eventId;
+      if ("error" in input && input.error && typeof input.error === "object") this.captured.add(input.error);
+      const requestSource = ctx.request ?? data.request;
+      const req = requestSource ? requestDataOf(requestSource, this.pii) : void 0;
+      const user = { ...data.user ?? {}, ...ctx.user && typeof ctx.user === "object" ? ctx.user : {} };
+      if (idString(ctx.userId)) user.id = idString(ctx.userId);
+      if (req?.ip && !user.ip_address) user.ip_address = req.ip;
+      const tags = new Scope().setTags(data.tags).setTags(ctx.tags ?? {}).data().tags;
+      const extra = { ...data.extra, ...ctx.extra && typeof ctx.extra === "object" ? ctx.extra : {} };
+      const contexts = { ...processContexts(), ...data.contexts };
+      for (const [k, v] of Object.entries(ctx.contexts ?? {})) {
+        if (v && typeof v === "object") contexts[k] = v;
+        else delete contexts[k];
+      }
+      const fingerprint = Array.isArray(ctx.fingerprint) ? ctx.fingerprint.map(String) : data.fingerprint;
+      const transaction = (typeof ctx.transaction === "string" && ctx.transaction ? ctx.transaction.slice(0, 200) : void 0) ?? data.transaction ?? transactionOf(requestSource);
+      const level = levelOf2(ctx.level) ?? data.level ?? mech.level;
+      const event = {
+        event_id: eventId,
+        timestamp: Date.now() / 1e3,
+        platform: "node",
+        level,
+        ...this.release ? { release: this.release } : {},
+        environment: this.host.environment,
+        ...this.serverName ? { server_name: this.serverName } : {},
+        ...transaction ? { transaction } : {},
+        ..."message" in input ? { logentry: { formatted: input.message.slice(0, 8e3) } } : {},
+        ...values ? { exception: { values } } : {},
+        ...data.breadcrumbs.length ? { breadcrumbs: { values: data.breadcrumbs } } : {},
+        contexts,
+        ...Object.keys(tags).length ? { tags } : {},
+        extra,
+        user,
+        ...fingerprint?.length ? { fingerprint } : {},
+        ...req ? { request: req.request } : {},
+        sdk: { ...this.host.sdk }
+      };
+      this.scrub(event);
+      const properties = {};
+      for (const [k, v] of Object.entries(ctx)) if (!KNOWN_CONTEXT_KEYS.has(k)) properties[k] = v;
+      const ids = { anonymousId: idString(ctx.anonymousId), accountId: idString(ctx.accountId) };
+      const hint = { originalException: "error" in input ? input.error : input.message, event_id: eventId };
+      const finish = () => this.finish(event, hint, mech.source, properties, ids);
+      const frames = values?.flatMap((v) => v.stacktrace?.frames ?? []) ?? [];
+      if (this.contextLines > 0 && wantsContext(frames)) this.track(addContextLines(frames, this.contextLines).then(finish, finish));
+      else {
+        const done = finish();
+        if (done) this.track(done);
+      }
+    } catch (e) {
+      this.host.report(`${"error" in input ? "captureException" : "captureMessage"}() failed: ${e instanceof Error ? e.message : String(e)}`, e);
+    }
+    return eventId;
+  }
+  ignored(type2, message) {
+    const patterns = this.options.ignoreErrors;
+    if (!Array.isArray(patterns) || patterns.length === 0) return false;
+    const candidates = [type2 && message !== void 0 ? `${type2}: ${message}` : void 0, message].filter((s) => typeof s === "string");
+    return patterns.some(
+      (p) => candidates.some((s) => {
+        if (typeof p === "string") return !!p && s.includes(p);
+        if (!(p instanceof RegExp)) return false;
+        p.lastIndex = 0;
+        return p.test(s);
+      })
+    );
+  }
+  /** Makes user-supplied parts of an event JSON-safe and credential-free (again after `beforeSend`). */
+  scrub(event) {
+    event.extra = normalizeObject(event.extra, 4) ?? {};
+    const contexts = {};
+    for (const [k, v] of Object.entries(event.contexts ?? {}).slice(0, 50)) {
+      const c = normalizeObject(v, 4);
+      if (c) contexts[k] = c;
+    }
+    event.contexts = contexts;
+    const user = normalizeObject(event.user, 3);
+    if (user && !this.pii && user.ip_address === "{{auto}}") delete user.ip_address;
+    if (user && Object.keys(user).length) event.user = user;
+    else delete event.user;
+    if (!Object.keys(event.extra).length) delete event.extra;
+    if (event.tags) {
+      const tags = {};
+      for (const [k, v] of Object.entries(event.tags).slice(0, MAX_TAGS)) if (v !== null && v !== void 0) tags[String(k).slice(0, 32)] = String(v).slice(0, 200);
+      event.tags = tags;
+    }
+    if (event.request) event.request = scrubRequest(event.request, this.pii);
+    if (event.breadcrumbs?.values) event.breadcrumbs = { values: event.breadcrumbs.values.slice(-MAX_BREADCRUMBS).map((b) => b.data ? { ...b, data: normalizeObject(b.data, 3) } : b) };
+  }
+  /** `beforeSend`, then the message: properties ≤ 8 KB, detail ≤ 64 KB. May return a promise (async `beforeSend`). */
+  finish(event, hint, source, properties, ids) {
+    const send = (result2) => {
+      if (result2 === null) return;
+      const final = result2 && typeof result2 === "object" ? result2 : event;
+      this.scrub(final);
+      this.send(final, source, properties, ids);
+    };
+    const hook = this.options.beforeSend;
+    if (typeof hook !== "function") return this.send(event, source, properties, ids);
+    let result;
+    try {
+      result = hook(event, hint);
+    } catch {
+      return send(event);
+    }
+    if (result && typeof result.then === "function") return result.then(send, () => send(event));
+    return send(result);
+  }
+  send(event, source, extraProperties, ids) {
+    try {
+      const properties = propertiesOf(event, source, this.release, extraProperties);
+      const userId = idString(event.user?.id);
+      const timestamp = new Date(typeof event.timestamp === "number" && Number.isFinite(event.timestamp) ? event.timestamp * 1e3 : Date.now()).toISOString();
+      let safe2;
+      try {
+        safe2 = JSON.parse(JSON.stringify(event));
+      } catch {
+        safe2 = normalize(event, 12);
+      }
+      const detail = trimDetail(safe2);
+      const message = {
+        type: "exception",
+        messageId: event.event_id,
+        timestamp,
+        ...userId ? { userId } : {},
+        ...ids.anonymousId ? { anonymousId: ids.anonymousId } : {},
+        ...ids.accountId ? { accountId: ids.accountId } : {},
+        ...this.release ? { appVersion: this.release } : {},
+        properties,
+        ...detail ? { detail } : {}
+      };
+      this.host.push(message);
+    } catch (e) {
+      this.host.report(`Could not build the exception event: ${e instanceof Error ? e.message : String(e)}`, e);
+    }
+  }
+  track(p) {
+    const tracked = p.catch((e) => this.host.report(`Could not build the exception event: ${e instanceof Error ? e.message : String(e)}`, e)).finally(() => {
+      this.pending.delete(tracked);
+    });
+    this.pending.add(tracked);
+  }
+  /** Resolves once every event being prepared (source lines, async `beforeSend`) is queued; `null` when none is. */
+  idle() {
+    if (this.pending.size === 0) return null;
+    return Promise.all([...this.pending]).then(() => this.idle() ?? void 0);
+  }
+  // --- process and framework hooks ----------------------------------------------------------
+  installProcessHandlers(options) {
+    try {
+      const off = installProcessHandlers(
+        {
+          capture: (error, kind) => void this.captureAuto(error, { mechanism: kind.mechanism, level: kind.level, fallbackType: kind.fallbackType }),
+          flush: () => this.host.flush()
+        },
+        options
+      );
+      this.cleanups.push(off);
+      return off;
+    } catch (e) {
+      this.host.report(`installProcessHandlers() failed: ${e instanceof Error ? e.message : String(e)}`, e);
+      return () => {
+      };
+    }
+  }
+  /** Runs `fn` in a new scope for `request`, with the request's events bound to it (body parsing, `finish`). */
+  runRequest(request, emitters, fn) {
+    if (!request || typeof request !== "object") return fn();
+    const scope = this.current().clone();
+    scope.request = request;
+    scope.clearBreadcrumbs();
+    this.requestScopes.set(request, scope);
+    return this.als.run(scope, () => {
+      for (const e of emitters) this.bindEmitter(e);
+      return fn();
+    });
+  }
+  /**
+   * Listeners of a request's / response's events (`data`, `end`, `finish`) run in the async context
+   * of the server's socket, not of the middleware: bind `emit` to the request scope, as domains did.
+   */
+  bindEmitter(emitter) {
+    if (!emitter || typeof emitter !== "object" || this.bound.has(emitter)) return;
+    const e = emitter;
+    if (typeof e.emit !== "function") return;
+    try {
+      e.emit = AsyncResource.bind(e.emit, "GuidelyRequest", emitter);
+      this.bound.add(emitter);
+    } catch {
+    }
+  }
+  captureRequestError(error, request, mechanism, options) {
+    try {
+      const should = typeof options?.shouldHandleError === "function" ? options.shouldHandleError : defaultShouldHandle;
+      if (should(error)) this.captureAuto(error, { mechanism, request });
+    } catch {
+    }
+  }
+  expressRequestHandler() {
+    return (req, res, next) => this.runRequest(req, [req, res], () => next());
+  }
+  expressErrorHandler(options) {
+    return (error, req, _res, next) => {
+      this.captureRequestError(error, req, "express", options);
+      next(error);
+    };
+  }
+  fastifyErrorHook(options) {
+    return (request, _reply, error, done) => {
+      this.captureRequestError(error, request, "fastify", options);
+      done?.();
+    };
+  }
+  fastifyPlugin(options) {
+    const plugin = (fastify, _opts, done) => {
+      fastify.addHook("onRequest", (request, reply, next) => this.runRequest(request, [request?.raw, reply?.raw], () => next()));
+      fastify.addHook("preHandler", (request, _reply, next) => {
+        const scope = request && typeof request === "object" ? this.requestScopes.get(request) : void 0;
+        if (scope) this.als.run(scope, () => next());
+        else next();
+      });
+      fastify.addHook("onError", this.fastifyErrorHook(options));
+      done?.();
+    };
+    Object.assign(plugin, { [/* @__PURE__ */ Symbol.for("skip-override")]: true, [/* @__PURE__ */ Symbol.for("fastify.display-name")]: "@guidelytech/node" });
+    return plugin;
+  }
+  koaMiddleware(options) {
+    return (ctx, next) => this.runRequest(ctx, [ctx?.req, ctx?.res], async () => {
+      try {
+        return await next();
+      } catch (error) {
+        this.captureRequestError(error, ctx, "koa", options);
+        throw error;
+      }
+    });
+  }
+  /** Stops the automatic breadcrumbs and process handlers. */
+  close() {
+    for (const off of this.cleanups.splice(0)) {
+      try {
+        off();
+      } catch {
+      }
+    }
+  }
+};
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return void 0;
+  }
+}
+function safeCwd() {
+  try {
+    return process.cwd();
+  } catch {
+    return void 0;
+  }
+}
+
 // src/client.ts
 var SDK_NAME = "guidely-node";
-var SDK_VERSION = "0.16.0";
+var SDK_VERSION = "0.17.0";
 var DEFAULT_API_URL = "https://guidelytech.com";
 var BATCH_PATH = "/api/v1/sdk/server/batch";
-var ENVIRONMENTS = ["development", "staging", "production"];
+var ENV_KEY = /^[a-z][a-z0-9-]{0,29}$/;
 var GuidelyError = class extends Error {
   constructor(code, message, count = 1, status, options) {
     super(message, options);
@@ -145,6 +1389,7 @@ var Guidely = class {
   timeoutMs;
   onError;
   fetch;
+  appVersion;
   sdkJson = JSON.stringify({ name: SDK_NAME, version: SDK_VERSION });
   queue = [];
   droppedSinceReport = 0;
@@ -159,14 +1404,17 @@ var Guidely = class {
   shutdownPromise = null;
   exitDrain = null;
   exitListener = null;
+  /** Set once `shutdown()` has finished: events still being prepared then are dropped, not sent. */
+  finished = false;
+  monitor;
   constructor(options) {
     const o = options ?? {};
     const key = typeof o.secretKey === "string" ? o.secretKey.trim() : "";
     if (!key.startsWith("gly_sk_")) {
       throw new TypeError("Guidely: secretKey must be a secret API key (gly_sk_\u2026) with the events:write scope");
     }
-    if (!ENVIRONMENTS.includes(o.environment)) {
-      throw new TypeError('Guidely: environment must be "development", "staging" or "production"');
+    if (typeof o.environment !== "string" || !ENV_KEY.test(o.environment)) {
+      throw new TypeError('Guidely: environment must be an environment key: "development", "staging", "production" or one you added (e.g. "qa"), as shown in Settings \u2192 Environments');
     }
     const fetchImpl = o.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
     if (!fetchImpl) throw new TypeError("Guidely: no global fetch (Node 18+ is required), pass the fetch option");
@@ -186,6 +1434,20 @@ var Guidely = class {
     this.shutdownTimeoutMs = int(o.shutdownTimeoutMs, 1e4, 0);
     this.timeoutMs = int(o.timeoutMs, 1e4, 1);
     this.onError = o.onError ?? ((e) => console.warn(`[${SDK_NAME}] ${e.message}`));
+    this.appVersion = typeof o.appVersion === "string" && o.appVersion.trim() ? o.appVersion.trim() : void 0;
+    this.monitor = new ErrorMonitor(
+      {
+        environment: o.environment,
+        appVersion: this.appVersion,
+        apiUrl,
+        sdk: { name: SDK_NAME, version: SDK_VERSION },
+        push: (message) => this.enqueueException(message),
+        accepting: () => !this.closed,
+        report: (message, cause, code = "invalid_message") => this.report(new GuidelyError(code, message, 1, void 0, { cause })),
+        flush: () => this.flush()
+      },
+      o.errors
+    );
     if (o.handleExit !== false && typeof process !== "undefined" && typeof process.on === "function") {
       this.exitListener = () => this.onBeforeExit();
       process.on("beforeExit", this.exitListener);
@@ -197,58 +1459,166 @@ var Guidely = class {
   }
   /** What a user (or anonymous visitor) did. */
   track(message) {
-    this.enqueue("track", message);
+    const withVersion = this.appVersion && message && typeof message === "object" && (message.appVersion === void 0 || message.appVersion === null);
+    this.enqueue("track", withVersion ? { ...message, appVersion: this.appVersion } : message);
   }
   /** Account traits, and optionally adds `userId` to the account. */
   group(message) {
     this.enqueue("group", message);
   }
+  // --- errors ----------------------------------------------------------------------------------
+  /**
+   * Reports an error as an `exception` event (grouped into an issue), with the current scope's tags,
+   * extras, contexts, user and breadcrumbs. Returns the event id. Never throws.
+   *
+   * ```ts
+   * guidely.captureException(err, { userId: "u_42", tags: { area: "billing" }, extra: { invoiceId } });
+   * ```
+   */
+  captureException(error, context) {
+    return this.monitor.captureException(error, context);
+  }
+  /** Reports a message (level `info` unless given), grouped by its text. Returns the event id. */
+  captureMessage(message, level, context) {
+    return this.monitor.captureMessage(message, level, context);
+  }
+  /** A tag on every later error of the current scope (`null` removes it). */
+  setTag(key, value) {
+    this.monitor.current().setTag(key, value);
+  }
+  setTags(tags) {
+    this.monitor.current().setTags(tags);
+  }
+  setExtra(key, value) {
+    this.monitor.current().setExtra(key, value);
+  }
+  setExtras(extras) {
+    this.monitor.current().setExtras(extras);
+  }
+  /** A named context on every later error of the current scope (`null` removes it). */
+  setContext(name, context) {
+    this.monitor.current().setContext(name, context);
+  }
+  /** The user later errors of the current scope belong to (`user.id` becomes `userId`); `null` clears it. */
+  setUser(user) {
+    this.monitor.current().setUser(user);
+  }
+  /** Adds a breadcrumb to the current scope (the last 100 ride along with each error). */
+  addBreadcrumb(breadcrumb, hint) {
+    this.monitor.addBreadcrumb(breadcrumb, hint);
+  }
+  /**
+   * Runs `fn` with a copy of the current scope: tags, user and breadcrumbs set inside (and in
+   * everything it starts, through AsyncLocalStorage) stay there. Returns what `fn` returns.
+   */
+  withScope(fn) {
+    return this.monitor.withScope(fn);
+  }
+  /**
+   * Reports `uncaughtException` (fatal) and `unhandledRejection`, keeping Node's behaviour: the error
+   * is printed, queued events are sent (at most `flushTimeoutMs`) and the process exits with code 1.
+   * Returns a function that removes the handlers (`shutdown()` removes them too).
+   */
+  installProcessHandlers(options) {
+    return this.monitor.installProcessHandlers(options);
+  }
+  /** Express: `app.use(guidely.expressRequestHandler())` first, so each request gets its own scope. */
+  expressRequestHandler() {
+    return this.monitor.expressRequestHandler();
+  }
+  /** Express: `app.use(guidely.expressErrorHandler())` after your routes, before other error handlers. */
+  expressErrorHandler(options) {
+    return this.monitor.expressErrorHandler(options);
+  }
+  /** Fastify: `await app.register(guidely.fastifyPlugin())` (request scopes + the `onError` hook). */
+  fastifyPlugin(options) {
+    return this.monitor.fastifyPlugin(options);
+  }
+  /** Fastify: `app.addHook("onError", guidely.fastifyErrorHook())`, when you do not use the plugin. */
+  fastifyErrorHook(options) {
+    return this.monitor.fastifyErrorHook(options);
+  }
+  /** Koa: `app.use(guidely.koaMiddleware())` first: a scope per request; errors are reported and rethrown. */
+  koaMiddleware(options) {
+    return this.monitor.koaMiddleware(options);
+  }
+  // --- delivery ------------------------------------------------------------------------------
   /** Sends everything queued; resolves once it has been delivered or dropped. Never rejects. */
   flush() {
-    return this.startPump(true);
+    const preparing = this.monitor.idle();
+    return preparing ? preparing.then(() => this.startPump(true)) : this.startPump(true);
   }
   /**
-   * Stops the timer and the exit hook, then flushes, waiting at most `shutdownTimeoutMs`. Later calls
-   * are dropped (and reported). Call it before your process exits. Never rejects.
+   * Stops the timer, the exit hook and the error hooks, then flushes, waiting at most
+   * `shutdownTimeoutMs`. Later calls are dropped (and reported). Call it before your process exits.
+   * Never rejects.
    */
   shutdown() {
     if (this.shutdownPromise) return this.shutdownPromise;
     this.closed = true;
     this.clearTimer();
+    this.monitor.close();
     if (this.exitListener) process.removeListener("beforeExit", this.exitListener);
-    this.shutdownPromise = this.drain(this.shutdownTimeoutMs);
+    this.shutdownPromise = this.drain(this.shutdownTimeoutMs).finally(() => {
+      this.finished = true;
+    });
     return this.shutdownPromise;
   }
   // --- queueing ------------------------------------------------------------------------------
-  enqueue(type, args) {
+  enqueue(type2, args) {
     try {
       if (this.closed) {
-        this.report(new GuidelyError("closed", `${type}() was called after shutdown(); the message was dropped`));
+        this.report(new GuidelyError("closed", `${type2}() was called after shutdown(); the message was dropped`));
         return;
       }
-      const message = buildMessage(type, args);
+      const message = buildMessage(type2, args);
       let json;
       try {
         json = JSON.stringify(message);
       } catch (e) {
         throw new InvalidMessageError(`could not be serialized to JSON (${e instanceof Error ? e.message : String(e)})`);
       }
-      const bytes = Buffer.byteLength(json, "utf8");
-      if (bytes > LIMITS.maxMessageBytes) {
-        this.report(new GuidelyError("message_too_large", `${type}() message is ${bytes} bytes, more than the ${LIMITS.maxMessageBytes}-byte limit; it was dropped`));
+      const bytes2 = Buffer.byteLength(json, "utf8");
+      if (bytes2 > LIMITS.maxMessageBytes) {
+        this.report(new GuidelyError("message_too_large", `${type2}() message is ${bytes2} bytes, more than the ${LIMITS.maxMessageBytes}-byte limit; it was dropped`));
         return;
       }
-      if (this.queue.length >= this.maxQueueSize) {
-        this.queue.shift();
-        this.droppedSinceReport++;
-      }
-      this.queue.push({ json, bytes });
-      if (this.queue.length >= this.flushAt) void this.startPump(false);
-      else this.scheduleTimer();
+      this.push(json, bytes2, false);
     } catch (e) {
-      if (e instanceof InvalidMessageError) this.report(new GuidelyError("invalid_message", `Invalid ${type}() call dropped: ${e.message}`));
-      else this.report(new GuidelyError("invalid_message", `${type}() failed: ${e instanceof Error ? e.message : String(e)}`, 1, void 0, { cause: e }));
+      if (e instanceof InvalidMessageError) this.report(new GuidelyError("invalid_message", `Invalid ${type2}() call dropped: ${e.message}`));
+      else this.report(new GuidelyError("invalid_message", `${type2}() failed: ${e instanceof Error ? e.message : String(e)}`, 1, void 0, { cause: e }));
+    }
+  }
+  /**
+   * Queues a built `exception` message (it may finish preparing after `shutdown()` began, which
+   * still sends it) and starts sending right away: errors should not wait for the flush interval.
+   */
+  enqueueException(message) {
+    if (this.finished) {
+      this.report(new GuidelyError("closed", "an exception finished preparing after shutdown(); it was dropped"));
+      return;
+    }
+    let json = JSON.stringify(message);
+    let bytes2 = Buffer.byteLength(json, "utf8");
+    if (bytes2 > ERROR_LIMITS.maxMessageBytes && "detail" in message) {
+      json = JSON.stringify({ ...message, detail: void 0 });
+      bytes2 = Buffer.byteLength(json, "utf8");
+    }
+    if (bytes2 > ERROR_LIMITS.maxMessageBytes) {
+      this.report(new GuidelyError("message_too_large", `exception message is ${bytes2} bytes, more than the ${ERROR_LIMITS.maxMessageBytes}-byte limit; it was dropped`));
+      return;
+    }
+    this.push(json, bytes2, true);
+  }
+  push(json, bytes2, prompt) {
+    if (this.queue.length >= this.maxQueueSize) {
+      this.queue.shift();
+      this.droppedSinceReport++;
     }
+    this.queue.push({ json, bytes: bytes2 });
+    if (prompt) void this.startPump(true);
+    else if (this.queue.length >= this.flushAt) void this.startPump(false);
+    else this.scheduleTimer();
   }
   scheduleTimer() {
     if (this.timer !== void 0 || this.closed) return;
@@ -358,7 +1728,7 @@ var Guidely = class {
   async drain(timeoutMs) {
     let timer;
     const timedOut = await Promise.race([
-      this.startPump(true).then(() => false),
+      this.flush().then(() => false),
       new Promise((resolve) => {
         timer = setTimeout(() => resolve(true), timeoutMs);
       })
@@ -377,7 +1747,7 @@ var Guidely = class {
     if (left > 0) this.report(new GuidelyError("delivery_failed", `${left} queued messages were not sent within ${timeoutMs} ms`, left, 0));
   }
   onBeforeExit() {
-    if (this.closed || this.exitDrain || this.queue.length === 0 && !this.pumping) return;
+    if (this.closed || this.exitDrain || this.queue.length === 0 && !this.pumping && !this.monitor.idle()) return;
     this.exitDrain = this.drain(this.shutdownTimeoutMs).finally(() => {
       this.exitDrain = null;
     });
@@ -408,6 +1778,8 @@ export {
   Guidely,
   GuidelyError,
   SDK_NAME,
-  SDK_VERSION
+  SDK_VERSION,
+  Scope,
+  parseStack
 };
 //# sourceMappingURL=index.js.map