@statoss/sdk 0.0.0-stage → 0.1.1

package/dist/esm/integrations/fetch.js

@@ -0,0 +1,66 @@
+import { isObject, isThenable, safely, scrubUrl } from "../utils.js";
+function describe(args) {
+    const [input, init] = args;
+    let method = "GET";
+    let url = "";
+    if (typeof input === "string") {
+        url = input;
+    }
+    else if (isObject(input)) {
+        if (typeof input.url === "string")
+            url = input.url;
+        else if (typeof input.href === "string")
+            url = input.href;
+        if (typeof input.method === "string")
+            method = input.method;
+    }
+    else if (input !== undefined) {
+        url = String(input);
+    }
+    if (isObject(init) && typeof init.method === "string")
+        method = init.method;
+    return { method: method.toUpperCase(), url };
+}
+function levelFor(status) {
+    if (status >= 500)
+        return "error";
+    if (status >= 400)
+        return "warning";
+    return "info";
+}
+/** Breadcrumbs for fetch calls: method, URL without secrets, status. */
+export function installFetch(client) {
+    const g = globalThis;
+    const original = g.fetch;
+    if (typeof original !== "function")
+        return undefined;
+    const wrapper = function (...args) {
+        const request = safely(() => describe(args));
+        const result = original.apply(globalThis, args);
+        if (!request || !isThenable(result) || client.isOwnUrl(request.url))
+            return result;
+        const data = { method: request.method, url: scrubUrl(request.url) };
+        return result.then((response) => {
+            safely(() => {
+                const status = isObject(response) && typeof response.status === "number"
+                    ? response.status
+                    : 0;
+                client.addBreadcrumb({
+                    type: "http",
+                    category: "fetch",
+                    level: levelFor(status),
+                    data: { ...data, status_code: status },
+                }, { input: args, response });
+            });
+            return response;
+        }, (error) => {
+            safely(() => client.addBreadcrumb({ type: "http", category: "fetch", level: "error", data }, { input: args, error }));
+            throw error;
+        });
+    };
+    g.fetch = wrapper;
+    return () => {
+        if (g.fetch === wrapper)
+            g.fetch = original;
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { Client } from "../client.js";
+import { type ProcessLike } from "../runtime.js";
+/**
+ * Uncaught errors and unhandled rejections, per runtime. Edge runtimes have
+ * no global hook, so there the app captures in its handlers.
+ */
+export declare function installGlobalHandlers(client: Client): (() => void) | undefined;
+/** Node's --unhandled-rejections mode from NODE_OPTIONS and the command line (which wins); "throw" by default. */
+export declare function rejectionMode(proc: ProcessLike): string;

package/dist/esm/integrations/handlers.js

@@ -0,0 +1,188 @@
+import { printError } from "../logger.js";
+import { getProcess } from "../runtime.js";
+import { frameAt } from "../stack.js";
+import { isErrorLike, isObject, safely, safeString, truncate, } from "../utils.js";
+const SHUTDOWN_TIMEOUT_MS = 2000;
+/**
+ * Uncaught errors and unhandled rejections, per runtime. Edge runtimes have
+ * no global hook, so there the app captures in its handlers.
+ */
+export function installGlobalHandlers(client) {
+    switch (client.runtime.name) {
+        case "node":
+        case "bun":
+            return processHandlers(client);
+        case "deno":
+            return eventHandlers(client, true);
+        case "browser":
+        case "worker":
+            return eventHandlers(client, false);
+        default:
+            return undefined;
+    }
+}
+/** Node's --unhandled-rejections mode from NODE_OPTIONS and the command line (which wins); "throw" by default. */
+export function rejectionMode(proc) {
+    const flags = [
+        ...String(safely(() => proc.env?.NODE_OPTIONS) ?? "").split(/\s+/),
+        ...(safely(() => proc.execArgv) ?? []),
+    ];
+    let mode = "throw";
+    for (let i = 0; i < flags.length; i++) {
+        const flag = flags[i];
+        if (flag.startsWith("--unhandled-rejections=")) {
+            mode = flag.slice("--unhandled-rejections=".length);
+        }
+        else if (flag === "--unhandled-rejections" && i + 1 < flags.length) {
+            mode = flags[++i];
+        }
+    }
+    return ["strict", "warn", "none", "warn-with-error-code"].includes(mode)
+        ? mode
+        : "throw";
+}
+/** The error Node raises for a rejection with a value that is not an Error. */
+function rejectionError(reason) {
+    const error = new Error(`This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "${truncate(safeString(reason), 200)}".`);
+    error.name = "UnhandledPromiseRejection";
+    error.code = "ERR_UNHANDLED_REJECTION";
+    return error;
+}
+/**
+ * Node and Bun. A listener on uncaughtException or unhandledRejection
+ * switches off the runtime's own handling, so the SDK does what the runtime
+ * would have done, after sending:
+ * - uncaught exception: print it and exit with 1, unless the app has its own
+ *   listener;
+ * - unhandled rejection, by Node's --unhandled-rejections mode: "throw" (the
+ *   default) raises it as an uncaught exception, so the app's listener gets
+ *   it or the process exits with 1; "warn-with-error-code" prints it and sets
+ *   the exit code to 1; "warn" and "none" keep running; "strict" is raised by
+ *   Node itself. An app with its own unhandledRejection listener decides.
+ */
+function processHandlers(client) {
+    const proc = getProcess();
+    if (!proc ||
+        typeof proc.on !== "function" ||
+        typeof proc.listeners !== "function") {
+        return undefined;
+    }
+    const mode = rejectionMode(proc);
+    let shuttingDown = false;
+    let reraised = undefined;
+    const others = (event, own) => (proc.listeners?.(event) ?? []).filter((l) => l !== own && l.name !== "domainUncaughtExceptionClear").length;
+    const shutdown = (error) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        // First: if nothing keeps the process alive while sending, it still ends with 1.
+        safely(() => {
+            proc.exitCode = 1;
+        });
+        printError(error);
+        const exit = () => {
+            safely(() => proc.exit?.(1));
+        };
+        client.flush(SHUTDOWN_TIMEOUT_MS).then(exit, exit);
+    };
+    const onUncaught = (error, origin) => {
+        // A rejection passed on by onRejection below was captured there.
+        if (reraised === undefined || error !== reraised) {
+            const fromRejection = origin === "unhandledRejection";
+            client.captureUnhandled(error, {
+                type: fromRejection ? "onunhandledrejection" : "onuncaughtexception",
+                handled: false,
+            }, "fatal", { rejection: fromRejection });
+        }
+        if (others("uncaughtException", onUncaught) > 0)
+            return;
+        shutdown(error);
+    };
+    const onRejection = (reason) => {
+        // In strict mode Node has already raised it as an uncaught exception.
+        if (mode === "strict")
+            return;
+        const ownListener = others("unhandledRejection", onRejection) > 0;
+        const crashes = mode === "throw" &&
+            !ownListener &&
+            others("uncaughtException", onUncaught) === 0;
+        client.captureUnhandled(reason, { type: "onunhandledrejection", handled: false }, crashes ? "fatal" : "error", { rejection: true });
+        if (ownListener)
+            return;
+        if (mode === "throw") {
+            const error = isErrorLike(reason) ? reason : rejectionError(reason);
+            reraised = error;
+            safely(() => proc.emit?.("uncaughtException", error, "unhandledRejection"));
+            reraised = undefined;
+        }
+        else if (mode === "warn-with-error-code") {
+            printError("Unhandled promise rejection:", reason);
+            safely(() => {
+                proc.exitCode = 1;
+            });
+        }
+    };
+    proc.on("uncaughtException", onUncaught);
+    proc.on("unhandledRejection", onRejection);
+    return () => {
+        const off = proc.off ?? proc.removeListener;
+        safely(() => off?.call(proc, "uncaughtException", onUncaught));
+        safely(() => off?.call(proc, "unhandledRejection", onRejection));
+    };
+}
+/**
+ * Browsers, web workers and Deno: the error and unhandledrejection events.
+ * Deno exits on them, so there the SDK prevents that, sends, and then throws
+ * the error again for Deno to print and exit as it would have, as Sentry's
+ * Deno SDK does. A listener of the app's that already called preventDefault
+ * keeps the process running.
+ */
+function eventHandlers(client, deno) {
+    const target = globalThis;
+    if (typeof target.addEventListener !== "function")
+        return undefined;
+    let exiting = false;
+    const crash = (event, error) => {
+        if (!deno || event.defaultPrevented)
+            return;
+        safely(() => event.preventDefault?.());
+        exiting = true;
+        const rethrow = () => {
+            throw error;
+        };
+        void client.flush(SHUTDOWN_TIMEOUT_MS).then(rethrow, rethrow);
+    };
+    const onError = (event) => {
+        if (exiting || !isObject(event))
+            return;
+        const error = event.error;
+        const message = typeof event.message === "string" && event.message
+            ? event.message
+            : undefined;
+        const filename = typeof event.filename === "string" ? event.filename : undefined;
+        // Cross-origin scripts give only "Script error." with a null error.
+        client.captureUnhandled(error !== undefined && error !== null
+            ? error
+            : (message ?? "Unknown error"), { type: "onerror", handled: false }, deno ? "fatal" : "error", {
+            frame: filename && !isErrorLike(error)
+                ? frameAt(filename, typeof event.lineno === "number" ? event.lineno : undefined, typeof event.colno === "number" ? event.colno : undefined)
+                : undefined,
+        });
+        crash(event, error);
+    };
+    const onRejection = (event) => {
+        if (exiting || !isObject(event))
+            return;
+        const reason = "reason" in event
+            ? event.reason
+            : event.detail?.reason;
+        client.captureUnhandled(reason, { type: "onunhandledrejection", handled: false }, deno ? "fatal" : "error", { rejection: true });
+        crash(event, reason);
+    };
+    target.addEventListener("error", onError);
+    target.addEventListener("unhandledrejection", onRejection);
+    return () => {
+        safely(() => target.removeEventListener?.("error", onError));
+        safely(() => target.removeEventListener?.("unhandledrejection", onRejection));
+    };
+}

package/dist/esm/levels.d.ts

@@ -0,0 +1,20 @@
+import type { Logger } from "./logger.js";
+import type { SentryLevel } from "./types.js";
+export declare const SENTRY_LEVELS: readonly SentryLevel[];
+export declare const LEVEL_TAG = "statoss.level";
+export declare const CATEGORY_TAG = "statoss.category";
+export declare function isSentryLevel(value: unknown): value is SentryLevel;
+export declare function isValidName(value: unknown): value is string;
+/** Keeps the entries of init's `levels` that are usable, logging the rest in debug mode. */
+export declare function readLevels(input: unknown, logger: Logger): Record<string, SentryLevel>;
+export interface LevelChoice {
+    level: SentryLevel;
+    /** The custom name, when the level was one. */
+    custom?: string;
+}
+/**
+ * Picks the first usable level from candidates in order of precedence. A
+ * custom name is sent as its mapped Sentry level (error when unmapped).
+ */
+export declare function chooseLevel(candidates: unknown[], levels: Record<string, SentryLevel>, fallback: SentryLevel, logger: Logger): LevelChoice;
+export declare function readCategory(value: unknown, logger: Logger): string | undefined;

package/dist/esm/levels.js

@@ -0,0 +1,69 @@
+import { safeString } from "./utils.js";
+export const SENTRY_LEVELS = [
+    "fatal",
+    "error",
+    "warning",
+    "info",
+    "debug",
+];
+/** Custom level and category names: what the server accepts as tag values to filter on. */
+const NAME_RE = /^[a-z0-9._-]{1,64}$/;
+export const LEVEL_TAG = "statoss.level";
+export const CATEGORY_TAG = "statoss.category";
+export function isSentryLevel(value) {
+    return (typeof value === "string" &&
+        SENTRY_LEVELS.includes(value));
+}
+export function isValidName(value) {
+    return typeof value === "string" && NAME_RE.test(value);
+}
+/** Keeps the entries of init's `levels` that are usable, logging the rest in debug mode. */
+export function readLevels(input, logger) {
+    const out = {};
+    if (input === undefined || input === null)
+        return out;
+    if (typeof input !== "object") {
+        logger.warn('Ignored `levels`: it should be an object such as { "payment-failed": "error" }.');
+        return out;
+    }
+    for (const [name, level] of Object.entries(input)) {
+        if (isSentryLevel(name)) {
+            logger.warn(`Ignored level "${name}" in \`levels\`: it is already a Sentry level.`);
+        }
+        else if (!isValidName(name)) {
+            logger.warn(`Ignored level "${name}" in \`levels\`: use 1 to 64 lowercase letters, digits, dots, dashes or underscores.`);
+        }
+        else if (!isSentryLevel(level)) {
+            logger.warn(`Ignored level "${name}" in \`levels\`: map it to fatal, error, warning, info or debug.`);
+        }
+        else {
+            out[name] = level;
+        }
+    }
+    return out;
+}
+/**
+ * Picks the first usable level from candidates in order of precedence. A
+ * custom name is sent as its mapped Sentry level (error when unmapped).
+ */
+export function chooseLevel(candidates, levels, fallback, logger) {
+    for (const candidate of candidates) {
+        if (candidate === undefined || candidate === null)
+            continue;
+        if (isSentryLevel(candidate))
+            return { level: candidate };
+        if (isValidName(candidate)) {
+            return { level: levels[candidate] ?? "error", custom: candidate };
+        }
+        logger.warn(`Ignored level "${safeString(candidate)}": use a Sentry level or 1 to 64 lowercase letters, digits, dots, dashes or underscores.`);
+    }
+    return { level: fallback };
+}
+export function readCategory(value, logger) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (isValidName(value))
+        return value;
+    logger.warn(`Ignored category "${safeString(value)}": use 1 to 64 lowercase letters, digits, dots, dashes or underscores.`);
+    return undefined;
+}

package/dist/esm/logger.d.ts

@@ -0,0 +1,18 @@
+export type ConsoleMethod = "debug" | "info" | "warn" | "error" | "log" | "assert";
+type ConsoleFn = (...args: unknown[]) => void;
+/** The console methods as they were before the console integration wrapped them. */
+export declare const originalConsole: Partial<Record<ConsoleMethod, ConsoleFn>>;
+export interface Logger {
+    readonly enabled: boolean;
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/** Writes only when debug is on, and never through the wrapped console. */
+export declare function makeLogger(enabled: boolean): Logger;
+/**
+ * Prints an error the way the runtime would have if the SDK had not taken
+ * over its crash handling. Not a debug message, so it ignores `debug`.
+ */
+export declare function printError(...args: unknown[]): void;
+export {};

package/dist/esm/logger.js

@@ -0,0 +1,33 @@
+/** The console methods as they were before the console integration wrapped them. */
+export const originalConsole = {};
+function call(method, args) {
+    try {
+        const c = globalThis
+            .console;
+        const fn = originalConsole[method] ?? c?.[method];
+        if (typeof fn === "function")
+            fn.apply(c, args);
+    }
+    catch {
+        // nowhere left to report to
+    }
+}
+/** Writes only when debug is on, and never through the wrapped console. */
+export function makeLogger(enabled) {
+    const write = (method) => enabled
+        ? (...args) => call(method, ["[StatOSS]", ...args])
+        : () => undefined;
+    return {
+        enabled,
+        log: write("log"),
+        warn: write("warn"),
+        error: write("error"),
+    };
+}
+/**
+ * Prints an error the way the runtime would have if the SDK had not taken
+ * over its crash handling. Not a debug message, so it ignores `debug`.
+ */
+export function printError(...args) {
+    call("error", args);
+}

package/dist/esm/ratelimit.d.ts

@@ -0,0 +1,11 @@
+/** Per category (or "all"), the time in ms until which nothing is sent. */
+export type RateLimits = Record<string, number>;
+export declare function parseRetryAfter(header: string, now: number): number;
+/**
+ * Applies a response's limits as Sentry's SDKs do. X-Sentry-Rate-Limits
+ * entries are "seconds:categories:scope:reason", categories split by ";" and
+ * empty for all. Its scope (key, project, organization) and reason (such as
+ * usage_exceeded) do not change what the client does: wait, then try again.
+ */
+export declare function updateRateLimits(limits: RateLimits, status: number, rateLimitHeader: string | null | undefined, retryAfterHeader: string | null | undefined, now: number): RateLimits;
+export declare function isRateLimited(limits: RateLimits, category: string, now: number): boolean;

package/dist/esm/ratelimit.js

@@ -0,0 +1,45 @@
+const DEFAULT_RETRY_MS = 60000;
+export function parseRetryAfter(header, now) {
+    const seconds = parseInt(header, 10);
+    if (!Number.isNaN(seconds))
+        return seconds * 1000;
+    const date = Date.parse(header);
+    if (!Number.isNaN(date))
+        return date - now;
+    return DEFAULT_RETRY_MS;
+}
+/**
+ * Applies a response's limits as Sentry's SDKs do. X-Sentry-Rate-Limits
+ * entries are "seconds:categories:scope:reason", categories split by ";" and
+ * empty for all. Its scope (key, project, organization) and reason (such as
+ * usage_exceeded) do not change what the client does: wait, then try again.
+ */
+export function updateRateLimits(limits, status, rateLimitHeader, retryAfterHeader, now) {
+    const next = { ...limits };
+    if (rateLimitHeader) {
+        for (const entry of rateLimitHeader.trim().split(",")) {
+            const [retryAfter, categories] = entry.trim().split(":", 2);
+            const seconds = parseInt(retryAfter, 10);
+            const until = now + (Number.isNaN(seconds) ? 60 : seconds) * 1000;
+            if (!categories) {
+                next.all = until;
+            }
+            else {
+                for (const category of categories.split(";")) {
+                    if (category)
+                        next[category] = until;
+                }
+            }
+        }
+    }
+    else if (retryAfterHeader) {
+        next.all = now + parseRetryAfter(retryAfterHeader, now);
+    }
+    else if (status === 429) {
+        next.all = now + DEFAULT_RETRY_MS;
+    }
+    return next;
+}
+export function isRateLimited(limits, category, now) {
+    return (limits[category] || limits.all || 0) > now;
+}

package/dist/esm/runtime.d.ts

@@ -0,0 +1,42 @@
+export type RuntimeName = "browser" | "worker" | "node" | "bun" | "deno" | "cloudflare" | "vercel-edge" | "unknown";
+export interface RuntimeInfo {
+    name: RuntimeName;
+    platform: "javascript" | "node";
+    /** Browsers and web workers: key in the query, keepalive, page context. */
+    browserLike: boolean;
+    serverName?: string;
+    contexts: Record<string, Record<string, unknown>>;
+}
+/** The parts of Node's process the SDK reads, all optional. */
+export interface ProcessLike {
+    version?: string;
+    versions?: Record<string, string | undefined>;
+    platform?: string;
+    arch?: string;
+    getBuiltinModule?: (id: string) => unknown;
+    on?: (event: string, listener: (...args: never[]) => void) => unknown;
+    off?: (event: string, listener: (...args: never[]) => void) => unknown;
+    removeListener?: (event: string, listener: (...args: never[]) => void) => unknown;
+    listeners?: (event: string) => ((...args: never[]) => void)[];
+    emit?: (event: string, ...args: unknown[]) => boolean;
+    exit?: (code?: number) => never;
+    exitCode?: number | string;
+    execArgv?: string[];
+    env?: Record<string, string | undefined>;
+}
+export declare function getProcess(): ProcessLike | undefined;
+/** A Node built-in without a static import, so bundlers for the browser never see one. */
+export declare function getBuiltin<T>(id: string): T | undefined;
+export declare function detectRuntime(): RuntimeName;
+/** Browser and OS from a user agent, for the common browsers only. */
+export declare function parseUserAgent(ua: string): {
+    browser?: {
+        name: string;
+        version: string;
+    };
+    os?: {
+        name: string;
+        version?: string;
+    };
+};
+export declare function describeRuntime(name?: RuntimeName): RuntimeInfo;