@statoss/sdk 0.0.0-stage → 0.1.1

package/dist/esm/event.js

@@ -0,0 +1,124 @@
+import { parseStack } from "./stack.js";
+import { summarize, isErrorLike, isObject, normalize, safeString, safely, toStringTag, truncate, } from "./utils.js";
+const MAX_CAUSES = 5;
+function exceptionFromError(error, mechanism) {
+    const name = safely(() => error.name);
+    const message = safely(() => error.message);
+    const exception = {
+        type: typeof name === "string" && name ? name : "Error",
+        value: typeof message === "string" ? truncate(message) : "",
+        mechanism,
+    };
+    const frames = parseStack(safely(() => error.stack));
+    if (frames.length)
+        exception.stacktrace = { frames };
+    return exception;
+}
+/** The error and its causes, as Sentry orders them: the thrown one last. */
+function exceptionChain(error, mechanism) {
+    const chain = [];
+    let current = error;
+    while (isErrorLike(current) &&
+        chain.length < MAX_CAUSES &&
+        !chain.includes(current)) {
+        chain.push(current);
+        current = safely(() => current.cause);
+    }
+    const values = chain.map((e, i) => exceptionFromError(e, i === 0
+        ? chain.length > 1
+            ? { ...mechanism, exception_id: 0 }
+            : mechanism
+        : {
+            type: "chained",
+            handled: mechanism.handled,
+            source: "cause",
+            exception_id: i,
+            parent_id: i - 1,
+        }));
+    return values.reverse();
+}
+function keysForMessage(value) {
+    // Only the first keys: the message holds 40 characters of them.
+    const keys = [];
+    for (const key in value) {
+        if (keys.length >= 100)
+            break;
+        if (Object.prototype.hasOwnProperty.call(value, key))
+            keys.push(key);
+    }
+    keys.sort();
+    let out = "";
+    for (const key of keys) {
+        const next = out ? `${out}, ${key}` : key;
+        if (next.length > 40)
+            return out || truncate(key, 40);
+        out = next;
+    }
+    return out || "[none]";
+}
+/**
+ * Builds an event from anything thrown or rejected, as Sentry's SDKs do:
+ * errors with their stacks and causes, other objects and plain values as
+ * synthetic exceptions.
+ */
+export function eventFromUnknown(input, mechanism, rejection = false) {
+    let value = input;
+    const tag = toStringTag(value);
+    if (tag === "[object ErrorEvent]" &&
+        isObject(value) &&
+        isErrorLike(value.error)) {
+        value = value.error;
+    }
+    else if (tag === "[object PromiseRejectionEvent]" &&
+        isObject(value) &&
+        "reason" in value) {
+        value = value.reason;
+    }
+    if (isErrorLike(value)) {
+        return { exception: { values: exceptionChain(value, mechanism) } };
+    }
+    const synthetic = { ...mechanism, synthetic: true };
+    if (isObject(value)) {
+        const name = safely(() => value.name);
+        const message = safely(() => value.message);
+        return {
+            exception: {
+                values: [
+                    {
+                        type: typeof name === "string" && name
+                            ? name
+                            : rejection
+                                ? "UnhandledRejection"
+                                : "Error",
+                        value: typeof message === "string"
+                            ? truncate(message)
+                            : `Object captured as ${rejection ? "promise rejection" : "exception"} ${summarize(value) ?? `with keys: ${keysForMessage(value)}`}`,
+                        mechanism: synthetic,
+                    },
+                ],
+            },
+            extra: { __serialized__: normalize(value, 3) },
+        };
+    }
+    const text = safeString(value);
+    return {
+        exception: {
+            values: [
+                {
+                    type: rejection ? "UnhandledRejection" : "Error",
+                    value: truncate(rejection
+                        ? `Non-Error promise rejection captured with value: ${text}`
+                        : text),
+                    mechanism: synthetic,
+                },
+            ],
+        },
+    };
+}
+/** For a browser error event that carried no Error: the file and line it names. */
+export function addInitialFrame(event, frame) {
+    const first = event.exception?.values[0];
+    if (first && !first.stacktrace)
+        first.stacktrace = { frames: [frame] };
+    return event;
+}

package/dist/esm/hub.d.ts

@@ -0,0 +1,37 @@
+import type { Client } from "./client.js";
+import { Scope } from "./scope.js";
+import type { CaptureContext, Level } from "./types.js";
+interface ScopeStorage {
+    getStore(): Scope | undefined;
+    run<T>(store: Scope, callback: () => T): T;
+}
+export interface Carrier {
+    client?: Client;
+    root: Scope;
+    /** Without AsyncLocalStorage: the scopes of withScope callbacks still running synchronously. */
+    stack: Scope[];
+    /** Undefined until first needed, null when the runtime has none. */
+    storage?: ScopeStorage | null;
+    warnedNoStorage?: boolean;
+    lastEventId?: string;
+}
+export declare function getCarrier(): Carrier;
+export declare function getClient(): Client | undefined;
+export declare function getCurrentScope(): Scope;
+/**
+ * Runs callback with a copy of the current scope, so what it sets applies only
+ * to events captured inside it.
+ *
+ * With AsyncLocalStorage (Node 20.16+ and 22.3+, Bun, Deno, Vercel Edge,
+ * Workers with nodejs_compat) the copy follows the callback's async work.
+ * Without it (browsers, Workers without nodejs_compat) the copy is current
+ * only until the callback first awaits: it is never left current for other
+ * work to pick up, which would send one request's user with another's error.
+ * After an await, capture through the scope argument (scope.captureException).
+ */
+export declare function withScope<T>(callback: (scope: Scope) => T): T;
+/** Runs a capture against the client with the given scope, or the current one. */
+export declare function captureWith(scope: Scope | undefined, run: (client: Client, scope: Scope) => string): string;
+/** captureMessage's second argument: a level or a context. */
+export declare function messageContext(levelOrContext: Level | CaptureContext | undefined): CaptureContext | undefined;
+export {};

package/dist/esm/hub.js

@@ -0,0 +1,111 @@
+import { getBuiltin } from "./runtime.js";
+import { Scope } from "./scope.js";
+import { uuid4 } from "./utils.js";
+// On globalThis so the ESM and CJS builds, if both get loaded, share one SDK.
+const KEY = "__statossSdk";
+let fallback;
+export function getCarrier() {
+    const g = globalThis;
+    const existing = g[KEY] ?? fallback;
+    if (existing)
+        return existing;
+    const carrier = { root: new Scope(), stack: [] };
+    try {
+        Object.defineProperty(g, KEY, {
+            value: carrier,
+            configurable: true,
+            enumerable: false,
+            writable: true,
+        });
+    }
+    catch {
+        fallback = carrier;
+    }
+    return carrier;
+}
+export function getClient() {
+    return getCarrier().client;
+}
+function getStorage(carrier) {
+    if (carrier.storage !== undefined)
+        return carrier.storage;
+    let storage = null;
+    try {
+        // Vercel Edge and Next.js edge expose it as a global; Node, Bun and Deno through node:async_hooks.
+        const global = globalThis
+            .AsyncLocalStorage;
+        const Ctor = typeof global === "function"
+            ? global
+            : getBuiltin("node:async_hooks")
+                ?.AsyncLocalStorage;
+        if (typeof Ctor === "function")
+            storage = new Ctor();
+    }
+    catch {
+        storage = null;
+    }
+    carrier.storage = storage;
+    return storage;
+}
+export function getCurrentScope() {
+    const carrier = getCarrier();
+    const fromStorage = carrier.storage ? carrier.storage.getStore() : undefined;
+    if (fromStorage)
+        return fromStorage;
+    return carrier.stack.length > 0
+        ? carrier.stack[carrier.stack.length - 1]
+        : carrier.root;
+}
+/**
+ * Runs callback with a copy of the current scope, so what it sets applies only
+ * to events captured inside it.
+ *
+ * With AsyncLocalStorage (Node 20.16+ and 22.3+, Bun, Deno, Vercel Edge,
+ * Workers with nodejs_compat) the copy follows the callback's async work.
+ * Without it (browsers, Workers without nodejs_compat) the copy is current
+ * only until the callback first awaits: it is never left current for other
+ * work to pick up, which would send one request's user with another's error.
+ * After an await, capture through the scope argument (scope.captureException).
+ */
+export function withScope(callback) {
+    const carrier = getCarrier();
+    const scope = getCurrentScope().clone();
+    const storage = getStorage(carrier);
+    if (storage)
+        return storage.run(scope, () => callback(scope));
+    const logger = carrier.client?.logger;
+    if (logger?.enabled && !carrier.warnedNoStorage) {
+        carrier.warnedNoStorage = true;
+        logger.warn("withScope cannot isolate across awaits here (no AsyncLocalStorage): its scope is current only until the callback first awaits. After that, capture with the scope it passes, such as scope.captureException(error).");
+    }
+    carrier.stack.push(scope);
+    try {
+        return callback(scope);
+    }
+    finally {
+        const i = carrier.stack.lastIndexOf(scope);
+        if (i >= 0)
+            carrier.stack.splice(i, 1);
+    }
+}
+/** Runs a capture against the client with the given scope, or the current one. */
+export function captureWith(scope, run) {
+    try {
+        const carrier = getCarrier();
+        if (carrier.client) {
+            const id = run(carrier.client, scope ?? getCurrentScope());
+            carrier.lastEventId = id;
+            return id;
+        }
+    }
+    catch {
+        // never throw into the app
+    }
+    return uuid4();
+}
+/** captureMessage's second argument: a level or a context. */
+export function messageContext(levelOrContext) {
+    return typeof levelOrContext === "string"
+        ? { level: levelOrContext }
+        : levelOrContext;
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,38 @@
+import type { Breadcrumb, CaptureContext, Event, InitOptions, Level, Primitive, User } from "./types.js";
+export { withScope } from "./hub.js";
+export type { Scope } from "./scope.js";
+export { SDK_NAME, SDK_VERSION } from "./version.js";
+export type { Breadcrumb, BreadcrumbHint, CaptureContext, Event, EventHint, Exception, InitOptions, IntegrationToggles, Level, Mechanism, Primitive, RequestInfo, ScopeData, SdkInfo, SentryLevel, StackFrame, Transport, TransportRequest, TransportResponse, User, } from "./types.js";
+/**
+ * Starts the SDK. Call it once, as early as you can. Calling it again replaces
+ * the earlier setup. Without a valid DSN, or with enabled: false, nothing is
+ * sent and nothing is patched.
+ */
+export declare function init(options?: InitOptions): void;
+/** Sends an error (or anything thrown). Returns the event id. */
+export declare function captureException(error: unknown, context?: CaptureContext): string;
+/**
+ * Sends a message. The second argument is a level (Sentry's or your own) or
+ * a context. Returns the event id.
+ */
+export declare function captureMessage(message: string, levelOrContext?: Level | CaptureContext): string;
+/** Sends an event you built in Sentry's schema. Returns the event id. */
+export declare function captureEvent(event: Event, context?: CaptureContext): string;
+/** Pass null to forget the user. */
+export declare function setUser(user: User | null): void;
+export declare function setTag(key: string, value: Primitive): void;
+export declare function setTags(tags: Record<string, Primitive>): void;
+/** Pass null to remove the context. */
+export declare function setContext(name: string, context: Record<string, unknown> | null): void;
+export declare function setExtra(key: string, value: unknown): void;
+/** Records a breadcrumb on the current scope, through beforeBreadcrumb. Ignored before init. */
+export declare function addBreadcrumb(breadcrumb: Breadcrumb): void;
+/**
+ * Waits up to timeoutMs (default 2000) for captured events to be sent.
+ * Resolves true once nothing is left to send, false on timeout or before init.
+ */
+export declare function flush(timeoutMs?: number): Promise<boolean>;
+/** Flushes, then stops the SDK and removes its integrations. */
+export declare function close(timeoutMs?: number): Promise<boolean>;
+/** The id of the last event captured, sent or not. */
+export declare function lastEventId(): string | undefined;

package/dist/esm/index.js

@@ -0,0 +1,88 @@
+import { Client } from "./client.js";
+import { captureWith, getCarrier, getCurrentScope, messageContext, } from "./hub.js";
+import { isObject, safely } from "./utils.js";
+export { withScope } from "./hub.js";
+export { SDK_NAME, SDK_VERSION } from "./version.js";
+/**
+ * Starts the SDK. Call it once, as early as you can. Calling it again replaces
+ * the earlier setup. Without a valid DSN, or with enabled: false, nothing is
+ * sent and nothing is patched.
+ */
+export function init(options = {}) {
+    try {
+        const carrier = getCarrier();
+        carrier.client?.teardown();
+        carrier.client = undefined;
+        const opts = isObject(options) ? options : {};
+        const client = new Client(opts);
+        carrier.root._apply(opts.initialScope);
+        if (opts.tags)
+            carrier.root.setTags(opts.tags);
+        carrier.client = client;
+        client.setup();
+    }
+    catch (error) {
+        if (isObject(options) && options.debug) {
+            safely(() => console.error("[StatOSS] init failed:", error));
+        }
+    }
+}
+/** Sends an error (or anything thrown). Returns the event id. */
+export function captureException(error, context) {
+    return captureWith(undefined, (client, scope) => client.captureException(error, context, scope));
+}
+/**
+ * Sends a message. The second argument is a level (Sentry's or your own) or
+ * a context. Returns the event id.
+ */
+export function captureMessage(message, levelOrContext) {
+    return captureWith(undefined, (client, scope) => client.captureMessage(message, messageContext(levelOrContext), scope));
+}
+/** Sends an event you built in Sentry's schema. Returns the event id. */
+export function captureEvent(event, context) {
+    return captureWith(undefined, (client, scope) => client.captureEvent(event, context, scope));
+}
+/** Pass null to forget the user. */
+export function setUser(user) {
+    safely(() => getCurrentScope().setUser(user));
+}
+export function setTag(key, value) {
+    safely(() => getCurrentScope().setTag(key, value));
+}
+export function setTags(tags) {
+    safely(() => getCurrentScope().setTags(tags));
+}
+/** Pass null to remove the context. */
+export function setContext(name, context) {
+    safely(() => getCurrentScope().setContext(name, context));
+}
+export function setExtra(key, value) {
+    safely(() => getCurrentScope().setExtra(key, value));
+}
+/** Records a breadcrumb on the current scope, through beforeBreadcrumb. Ignored before init. */
+export function addBreadcrumb(breadcrumb) {
+    safely(() => getCarrier().client?.addBreadcrumb(breadcrumb));
+}
+/**
+ * Waits up to timeoutMs (default 2000) for captured events to be sent.
+ * Resolves true once nothing is left to send, false on timeout or before init.
+ */
+export function flush(timeoutMs) {
+    const client = safely(() => getCarrier().client);
+    if (!client)
+        return Promise.resolve(false);
+    return client.flush(timeoutMs).catch(() => false);
+}
+/** Flushes, then stops the SDK and removes its integrations. */
+export function close(timeoutMs) {
+    const carrier = safely(() => getCarrier());
+    const client = carrier?.client;
+    if (!carrier || !client)
+        return Promise.resolve(false);
+    carrier.client = undefined;
+    return client.close(timeoutMs).catch(() => false);
+}
+/** The id of the last event captured, sent or not. */
+export function lastEventId() {
+    return safely(() => getCarrier().lastEventId);
+}

package/dist/esm/integrations/browser.d.ts

@@ -0,0 +1,7 @@
+import type { Client } from "../client.js";
+/** Breadcrumbs for pushState, replaceState and popstate. */
+export declare function installNavigation(client: Client): (() => void) | undefined;
+/** A short CSS-like path to an element, such as `div#app > button.buy[type="submit"]`. */
+export declare function selectorFor(target: unknown): string;
+/** A breadcrumb per click, once a second at most for the same element. */
+export declare function installClicks(client: Client): (() => void) | undefined;

package/dist/esm/integrations/browser.js

@@ -0,0 +1,119 @@
+import { isObject, safely, scrubUrl } from "../utils.js";
+function relative(url, origin) {
+    const clean = scrubUrl(url);
+    return origin && clean.startsWith(`${origin}/`)
+        ? clean.slice(origin.length)
+        : clean;
+}
+/** Breadcrumbs for pushState, replaceState and popstate. */
+export function installNavigation(client) {
+    const w = globalThis;
+    const history = w.history;
+    if (!history || !w.location)
+        return undefined;
+    let last = safely(() => w.location?.href) ?? "";
+    const record = () => {
+        const to = safely(() => w.location?.href);
+        if (typeof to !== "string" || to === last)
+            return;
+        const origin = safely(() => w.location?.origin);
+        const from = last;
+        last = to;
+        client.addBreadcrumb({
+            category: "navigation",
+            data: { from: relative(from, origin), to: relative(to, origin) },
+        }, { from, to });
+    };
+    const restore = [];
+    for (const name of ["pushState", "replaceState"]) {
+        const original = history[name];
+        if (typeof original !== "function")
+            continue;
+        const fn = original;
+        const wrapper = function (...args) {
+            const result = fn.apply(this, args);
+            safely(record);
+            return result;
+        };
+        history[name] = wrapper;
+        restore.push(() => {
+            if (history[name] === wrapper)
+                history[name] = original;
+        });
+    }
+    w.addEventListener?.("popstate", record);
+    return () => {
+        for (const undo of restore)
+            undo();
+        safely(() => w.removeEventListener?.("popstate", record));
+    };
+}
+const ATTRIBUTES = ["name", "type", "title", "alt", "aria-label"];
+const MAX_SELECTOR = 80;
+const MAX_DEPTH = 5;
+function describeElement(el) {
+    if (typeof el.tagName !== "string")
+        return "";
+    let out = el.tagName.toLowerCase();
+    if (typeof el.id === "string" && el.id)
+        out += `#${el.id}`;
+    if (typeof el.className === "string" && el.className.trim()) {
+        out += el.className
+            .trim()
+            .split(/\s+/)
+            .slice(0, 3)
+            .map((c) => `.${c}`)
+            .join("");
+    }
+    for (const attr of ATTRIBUTES) {
+        const value = safely(() => el.getAttribute?.(attr));
+        if (typeof value === "string" && value)
+            out += `[${attr}="${value.slice(0, 30)}"]`;
+    }
+    return out;
+}
+/** A short CSS-like path to an element, such as `div#app > button.buy[type="submit"]`. */
+export function selectorFor(target) {
+    const parts = [];
+    let el = target;
+    let length = 0;
+    for (let depth = 0; isObject(el) && depth < MAX_DEPTH; depth++) {
+        const part = describeElement(el);
+        if (!part || part === "html")
+            break;
+        if (parts.length > 0 && length + part.length + 3 > MAX_SELECTOR)
+            break;
+        parts.unshift(part);
+        length += part.length + 3;
+        el = el.parentElement;
+    }
+    return parts.join(" > ");
+}
+/** A breadcrumb per click, once a second at most for the same element. */
+export function installClicks(client) {
+    const doc = globalThis.document;
+    if (!doc || typeof doc.addEventListener !== "function")
+        return undefined;
+    let lastTarget;
+    let lastTime = 0;
+    const onClick = (event) => {
+        safely(() => {
+            const target = isObject(event) ? event.target : undefined;
+            if (!isObject(target))
+                return;
+            const time = Date.now();
+            if (target === lastTarget && time - lastTime < 1000)
+                return;
+            lastTarget = target;
+            lastTime = time;
+            const selector = selectorFor(target);
+            if (selector)
+                client.addBreadcrumb({ category: "ui.click", message: selector }, { event });
+        });
+    };
+    const options = { capture: true, passive: true };
+    doc.addEventListener("click", onClick, options);
+    return () => {
+        safely(() => doc.removeEventListener?.("click", onClick, options));
+    };
+}

package/dist/esm/integrations/console.d.ts

@@ -0,0 +1,3 @@
+import type { Client } from "../client.js";
+/** Breadcrumbs for console calls; the original methods still run, unchanged. */
+export declare function installConsole(client: Client): (() => void) | undefined;

package/dist/esm/integrations/console.js

@@ -0,0 +1,103 @@
+import { originalConsole } from "../logger.js";
+import { isErrorLike, normalize, safely, safeString, truncate, } from "../utils.js";
+const METHODS = [
+    "debug",
+    "info",
+    "warn",
+    "error",
+    "log",
+    "assert",
+];
+const LEVELS = {
+    debug: "debug",
+    info: "info",
+    warn: "warning",
+    error: "error",
+    log: "info",
+    assert: "error",
+};
+const MAX_MESSAGE = 1024;
+// Every part is cut before it is joined, so a huge argument is never copied whole.
+function format(arg) {
+    if (typeof arg === "string")
+        return truncate(arg, MAX_MESSAGE);
+    if (isErrorLike(arg)) {
+        return `${truncate(safeString(arg.name), 200)}: ${truncate(safeString(arg.message), MAX_MESSAGE)}`;
+    }
+    if (arg !== null && typeof arg === "object") {
+        const normalized = normalize(arg, 2, 200, 20);
+        if (typeof normalized === "string")
+            return normalized;
+        try {
+            return truncate(JSON.stringify(normalized), MAX_MESSAGE);
+        }
+        catch {
+            return "[Object]";
+        }
+    }
+    return truncate(safeString(arg), MAX_MESSAGE);
+}
+function join(args) {
+    let out = "";
+    for (let i = 0; i < args.length && out.length <= MAX_MESSAGE; i++) {
+        out += (i > 0 ? " " : "") + format(args[i]);
+    }
+    return out;
+}
+/** Breadcrumbs for console calls; the original methods still run, unchanged. */
+export function installConsole(client) {
+    const target = globalThis.console;
+    if (!target)
+        return undefined;
+    const wrapped = {};
+    let inside = false;
+    for (const method of METHODS) {
+        const original = target[method];
+        if (typeof original !== "function")
+            continue;
+        const fn = original;
+        originalConsole[method] = fn;
+        // One breadcrumb per call: console.assert, for one, calls console.warn itself.
+        const wrapper = function (...args) {
+            if (inside)
+                return fn.apply(this, args);
+            inside = true;
+            try {
+                safely(() => record(client, method, args));
+                return fn.apply(this, args);
+            }
+            finally {
+                inside = false;
+            }
+        };
+        wrapped[method] = wrapper;
+        target[method] = wrapper;
+    }
+    return () => {
+        for (const method of METHODS) {
+            // Leave it if something else has wrapped the console since.
+            if (wrapped[method] && target[method] === wrapped[method]) {
+                target[method] = originalConsole[method];
+            }
+            delete originalConsole[method];
+        }
+    };
+}
+function record(client, method, args) {
+    let message;
+    if (method === "assert") {
+        if (args[0])
+            return;
+        const rest = join(args.slice(1));
+        message = `Assertion failed: ${rest || "console.assert"}`;
+    }
+    else {
+        message = join(args);
+    }
+    client.addBreadcrumb({
+        category: "console",
+        level: LEVELS[method],
+        message: truncate(message, MAX_MESSAGE),
+        data: { logger: "console" },
+    }, { input: args, level: method });
+}

package/dist/esm/integrations/dedupe.d.ts

@@ -0,0 +1,7 @@
+import type { Event } from "../types.js";
+/**
+ * What makes two events the same for dedupe, as Sentry's Dedupe compares
+ * them: message, exception types and values, frames and fingerprint.
+ * Undefined for events with neither message nor exception.
+ */
+export declare function eventSignature(event: Event): string | undefined;

package/dist/esm/integrations/dedupe.js

@@ -0,0 +1,29 @@
+/**
+ * What makes two events the same for dedupe, as Sentry's Dedupe compares
+ * them: message, exception types and values, frames and fingerprint.
+ * Undefined for events with neither message nor exception.
+ */
+export function eventSignature(event) {
+    const exceptions = event.exception?.values?.map((e) => [
+        e.type,
+        e.value,
+        (e.stacktrace?.frames ?? []).map((f) => [
+            f.filename,
+            f.function,
+            f.lineno,
+            f.colno,
+        ]),
+    ]);
+    if (!exceptions && event.message === undefined)
+        return undefined;
+    try {
+        return JSON.stringify([
+            event.message ?? null,
+            exceptions ?? null,
+            event.fingerprint ?? null,
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/esm/integrations/fetch.d.ts

@@ -0,0 +1,3 @@
+import type { Client } from "../client.js";
+/** Breadcrumbs for fetch calls: method, URL without secrets, status. */
+export declare function installFetch(client: Client): (() => void) | undefined;