@statoss/sdk 0.0.0-stage → 0.1.1

package/dist/esm/transport.js

@@ -0,0 +1,213 @@
+import { itemCategory, serializeEnvelope } from "./envelope.js";
+import { isRateLimited, updateRateLimits, } from "./ratelimit.js";
+import { safely, unref } from "./utils.js";
+export const QUEUE_LIMIT = 30;
+export const CONCURRENCY = 5;
+const REQUEST_TIMEOUT_MS = 30000;
+// Browsers refuse keepalive requests past 64 KiB in flight in total.
+const KEEPALIVE_BYTES = 60000;
+const KEEPALIVE_REQUESTS = 15;
+/** The default transport: fetch, called on globalThis (Workers refuse any other this). */
+export function fetchTransport(browserLike) {
+    return async (request) => {
+        const fetchFn = globalThis.fetch;
+        if (typeof fetchFn !== "function")
+            throw new Error("fetch is not available");
+        const controller = typeof AbortController === "function" ? new AbortController() : undefined;
+        const timer = controller
+            ? setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS)
+            : undefined;
+        unref(timer);
+        // Workers reject RequestInit fields they do not implement, so only browsers get the extra ones.
+        const init = {
+            method: "POST",
+            headers: request.headers,
+            body: request.body,
+        };
+        if (controller)
+            init.signal = controller.signal;
+        if (browserLike) {
+            init.keepalive = request.keepalive;
+            init.referrerPolicy = "strict-origin";
+        }
+        try {
+            const response = await fetchFn.call(globalThis, request.url, init);
+            // Free the connection: nobody reads the answer.
+            safely(() => void response.body?.cancel?.().catch(() => undefined));
+            return { status: response.status, headers: response.headers };
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    };
+}
+function header(response, name) {
+    const headers = response.headers;
+    if (!headers)
+        return null;
+    if (typeof headers.get === "function") {
+        return headers.get(name);
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name)
+            return value ?? null;
+    }
+    return null;
+}
+/**
+ * Sends envelopes in order of arrival, a few at a time, keeping at most 30
+ * waiting or in flight. Whatever cannot be sent is counted for client reports.
+ */
+export class Sender {
+    constructor(options) {
+        this.options = options;
+        this.queue = [];
+        this.active = 0;
+        this.limits = {};
+        this.waiters = [];
+        this.keepaliveBytes = 0;
+        this.keepaliveCount = 0;
+    }
+    send(envelope) {
+        const allowed = this.withoutLimited(envelope);
+        if (!allowed)
+            return;
+        if (this.queue.length + this.active >= QUEUE_LIMIT) {
+            this.options.logger.warn("Dropped an envelope: the send queue is full.");
+            this.lose(allowed, "queue_overflow");
+            return;
+        }
+        this.queue.push(allowed);
+        this.pump();
+    }
+    /** Resolves true once nothing waits or is in flight, false if timeoutMs passes first. */
+    flush(timeoutMs) {
+        if (this.idle())
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    resolve(false);
+                }
+            }, timeoutMs);
+            unref(timer);
+            this.waiters.push(() => {
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve(true);
+                }
+            });
+        });
+    }
+    /** @internal for tests */
+    get rateLimits() {
+        return this.limits;
+    }
+    idle() {
+        return this.active === 0 && this.queue.length === 0;
+    }
+    notify() {
+        if (!this.idle())
+            return;
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const waiter of waiters)
+            waiter();
+    }
+    /** Drops the items whose category is rate limited; undefined when none is left. */
+    withoutLimited(envelope) {
+        const now = Date.now();
+        const items = envelope[1].filter((item) => {
+            const category = itemCategory(item);
+            if (!isRateLimited(this.limits, category, now))
+                return true;
+            if (category !== "internal")
+                this.options.recordLoss("ratelimit_backoff", category);
+            return false;
+        });
+        if (items.length < envelope[1].length) {
+            this.options.logger.warn("Held back by a rate limit from the server.");
+        }
+        return items.length ? [envelope[0], items] : undefined;
+    }
+    pump() {
+        while (this.active < CONCURRENCY && this.queue.length > 0) {
+            // A 429 may have come in while it waited.
+            const next = this.withoutLimited(this.queue.shift());
+            if (!next)
+                continue;
+            this.active++;
+            const done = () => {
+                this.active--;
+                this.pump();
+            };
+            void this.deliver(next).then(done, done);
+        }
+        this.notify();
+    }
+    async deliver(envelope) {
+        const { logger } = this.options;
+        let body;
+        try {
+            body = serializeEnvelope(envelope);
+        }
+        catch (error) {
+            logger.error("Could not serialise an envelope:", error);
+            this.lose(envelope, "internal_sdk_error");
+            return;
+        }
+        const keepalive = this.options.browserLike &&
+            this.keepaliveBytes + body.length <= KEEPALIVE_BYTES &&
+            this.keepaliveCount < KEEPALIVE_REQUESTS;
+        if (keepalive) {
+            this.keepaliveBytes += body.length;
+            this.keepaliveCount++;
+        }
+        try {
+            const response = await this.options.transport({
+                url: this.options.url,
+                headers: this.options.headers,
+                body,
+                keepalive,
+            });
+            const status = typeof response?.status === "number" ? response.status : 200;
+            this.limits = updateRateLimits(this.limits, status, header(response, "x-sentry-rate-limits"), header(response, "retry-after"), Date.now());
+            if (status === 413 || status >= 500) {
+                // The server did not keep it.
+                logger.warn(`The server answered ${status}; the envelope was not stored.`);
+                this.lose(envelope, "send_error");
+            }
+            else if (status === 429) {
+                logger.warn("The server is rate limiting this app; waiting before sending again.");
+            }
+            else if (status < 200 || status >= 300) {
+                logger.warn(`The server answered ${status}.`);
+            }
+            else {
+                logger.log(`Sent an envelope (${envelope[1].map((i) => i[0].type).join(", ")}).`);
+            }
+        }
+        catch (error) {
+            logger.warn("Could not reach the server:", error);
+            this.lose(envelope, "network_error");
+        }
+        finally {
+            if (keepalive) {
+                this.keepaliveBytes -= body.length;
+                this.keepaliveCount--;
+            }
+        }
+    }
+    lose(envelope, reason) {
+        for (const item of envelope[1]) {
+            const category = itemCategory(item);
+            // A lost client report is not reported again.
+            if (category !== "internal")
+                this.options.recordLoss(reason, category);
+        }
+    }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,180 @@
+/** The five levels Sentry knows. */
+export type SentryLevel = "fatal" | "error" | "warning" | "info" | "debug";
+/**
+ * A Sentry level, or a name of your own such as "payment-failed". Custom
+ * names are sent as the Sentry level they map to in `levels`, with the name
+ * in the `statoss.level` tag.
+ */
+export type Level = SentryLevel | (string & {});
+export type Primitive = string | number | boolean | bigint | null | undefined;
+export interface User {
+    id?: string | number;
+    email?: string;
+    username?: string;
+    ip_address?: string;
+    [key: string]: unknown;
+}
+export interface Breadcrumb {
+    type?: string;
+    category?: string;
+    message?: string;
+    level?: SentryLevel;
+    data?: Record<string, unknown>;
+    /** Seconds since the epoch; set for you when left out. */
+    timestamp?: number;
+}
+export type BreadcrumbHint = Record<string, unknown>;
+export interface StackFrame {
+    filename?: string;
+    abs_path?: string;
+    function?: string;
+    lineno?: number;
+    colno?: number;
+    in_app?: boolean;
+}
+export interface Mechanism {
+    type: string;
+    handled: boolean;
+    synthetic?: boolean;
+    source?: string;
+    exception_id?: number;
+    parent_id?: number;
+}
+export interface Exception {
+    type: string;
+    value: string;
+    mechanism?: Mechanism;
+    stacktrace?: {
+        frames: StackFrame[];
+    };
+}
+export interface RequestInfo {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    query_string?: string;
+    data?: unknown;
+}
+export interface SdkInfo {
+    name: string;
+    version: string;
+    integrations?: string[];
+    packages?: {
+        name: string;
+        version: string;
+    }[];
+}
+/** An event in Sentry's schema, as the SDK sends it. */
+export interface Event {
+    event_id?: string;
+    /** Seconds since the epoch, with fractions. */
+    timestamp?: number;
+    platform?: string;
+    level?: Level;
+    logger?: string;
+    transaction?: string;
+    server_name?: string;
+    environment?: string;
+    release?: string;
+    dist?: string;
+    message?: string;
+    exception?: {
+        values: Exception[];
+    };
+    breadcrumbs?: {
+        values: Breadcrumb[];
+    };
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    contexts?: Record<string, Record<string, unknown>>;
+    user?: User;
+    request?: RequestInfo;
+    fingerprint?: string[];
+    sdk?: SdkInfo;
+    [key: string]: unknown;
+}
+/** What `captureException`, `captureMessage` and `captureEvent` take as context. */
+export interface CaptureContext {
+    /** A Sentry level or one of your own names (see `levels` in init). */
+    level?: Level;
+    tags?: Record<string, Primitive>;
+    extra?: Record<string, unknown>;
+    contexts?: Record<string, Record<string, unknown>>;
+    user?: User;
+    fingerprint?: string[];
+    /** Sent as the `statoss.category` tag. */
+    category?: string;
+}
+export interface EventHint {
+    event_id: string;
+    originalException?: unknown;
+}
+export interface ScopeData {
+    tags?: Record<string, Primitive>;
+    extra?: Record<string, unknown>;
+    contexts?: Record<string, Record<string, unknown>>;
+    user?: User;
+    level?: Level;
+    fingerprint?: string[];
+}
+/** Each defaults to true; integrations that do not apply to a runtime are skipped. */
+export interface IntegrationToggles {
+    /** Uncaught errors and unhandled rejections. */
+    globalHandlers?: boolean;
+    /** Breadcrumbs for console calls. */
+    console?: boolean;
+    /** Breadcrumbs for fetch requests. */
+    fetch?: boolean;
+    /** Breadcrumbs for history changes, in browsers. */
+    navigation?: boolean;
+    /** Breadcrumbs for clicks, in browsers. */
+    clicks?: boolean;
+    /** Drops an event identical to the one before it. */
+    dedupe?: boolean;
+}
+export interface TransportRequest {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+    /** True in browsers for small envelopes, so they survive a page unload. */
+    keepalive: boolean;
+}
+export interface TransportResponse {
+    status: number;
+    headers?: {
+        get(name: string): string | null;
+    } | Record<string, string | null | undefined>;
+}
+/** Sends one envelope. The default uses fetch; tests can pass their own. */
+export type Transport = (request: TransportRequest) => Promise<TransportResponse>;
+export interface InitOptions {
+    /** https://<key>@ingest.statoss.com/<app number>. Without one the SDK stays off. */
+    dsn?: string;
+    /** Defaults to "production". */
+    environment?: string;
+    release?: string;
+    dist?: string;
+    /** Sent as server_name; defaults to the host name in Node and Bun. */
+    serverName?: string;
+    /** Share of events to send, 0 to 1. Defaults to 1. */
+    sampleRate?: number;
+    /** Change or drop (return null) an event before it is sent. May be async. */
+    beforeSend?: (event: Event, hint: EventHint) => Event | null | PromiseLike<Event | null>;
+    /** Change or drop (return null) a breadcrumb before it is kept. */
+    beforeBreadcrumb?: (breadcrumb: Breadcrumb, hint?: BreadcrumbHint) => Breadcrumb | null;
+    /** Defaults to 100, which is also the most kept. */
+    maxBreadcrumbs?: number;
+    /** When true, browsers ask the server to record the sender's IP address. Defaults to false. */
+    sendDefaultPii?: boolean;
+    /** Tags on every event. */
+    tags?: Record<string, Primitive>;
+    initialScope?: ScopeData;
+    /** Defaults to true. */
+    enabled?: boolean;
+    /** Logs what the SDK does to the console. Defaults to false. */
+    debug?: boolean;
+    transport?: Transport;
+    integrations?: IntegrationToggles;
+    /** Your own level names and the Sentry level each is sent as, such as { "payment-failed": "error" }. */
+    levels?: Record<string, SentryLevel>;
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/utils.d.ts

@@ -0,0 +1,27 @@
+export declare const MAX_STRING = 8192;
+export declare function now(): number;
+export declare function uuid4(): string;
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function toStringTag(value: unknown): string;
+export declare function isErrorLike(value: unknown): value is Error;
+export declare function safeString(value: unknown): string;
+export declare function truncate(value: string, max?: number): string;
+/** Runs fn and swallows anything it throws: the SDK must not break the app. */
+export declare function safely<T>(fn: () => T, fallback?: T): T | undefined;
+/** Lets Node exit while a timer is pending. */
+export declare function unref(timer: unknown): void;
+/**
+ * Buffers, typed arrays, DataViews, ArrayBuffers, Maps and Sets as their type
+ * and size, such as [Uint8Array(30000000)], without reading their contents.
+ */
+export declare function summarize(obj: object): string | undefined;
+/**
+ * Makes any value safe to put in JSON: cycles, functions, bigints, errors and
+ * deep or wide structures become short strings, and long strings are cut.
+ * Arrays and objects are read only up to `breadth` entries, and binary data,
+ * Maps and Sets are summarised, so a huge value costs no more than what is kept.
+ */
+export declare function normalize(input: unknown, depth?: number, maxString?: number, breadth?: number): unknown;
+/** Removes credentials, the fragment and secret-looking query values from a URL. */
+export declare function scrubUrl(url: string): string;

package/dist/esm/utils.js

@@ -0,0 +1,211 @@
+export const MAX_STRING = 8192;
+export function now() {
+    return Date.now() / 1000;
+}
+export function uuid4() {
+    const c = globalThis.crypto;
+    try {
+        if (c && typeof c.randomUUID === "function") {
+            return c.randomUUID().replace(/-/g, "");
+        }
+    }
+    catch {
+        // randomUUID needs a secure context in browsers
+    }
+    const bytes = new Uint8Array(16);
+    try {
+        if (c && typeof c.getRandomValues === "function")
+            c.getRandomValues(bytes);
+        else
+            throw new Error("no crypto");
+    }
+    catch {
+        for (let i = 0; i < 16; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    let out = "";
+    for (const b of bytes)
+        out += (b < 16 ? "0" : "") + b.toString(16);
+    return out;
+}
+export function isThenable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+export function isObject(value) {
+    return value !== null && typeof value === "object";
+}
+export function toStringTag(value) {
+    try {
+        return Object.prototype.toString.call(value);
+    }
+    catch {
+        return "";
+    }
+}
+export function isErrorLike(value) {
+    if (!isObject(value))
+        return false;
+    switch (toStringTag(value)) {
+        case "[object Error]":
+        case "[object Exception]":
+        case "[object DOMException]":
+        case "[object DOMError]":
+            return true;
+    }
+    return value instanceof Error;
+}
+export function safeString(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return "[unprintable]";
+    }
+}
+export function truncate(value, max = MAX_STRING) {
+    return value.length > max ? `${value.slice(0, max)}...` : value;
+}
+/** Runs fn and swallows anything it throws: the SDK must not break the app. */
+export function safely(fn, fallback) {
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Lets Node exit while a timer is pending. */
+export function unref(timer) {
+    const t = timer;
+    if (t && typeof t.unref === "function")
+        safely(() => t.unref());
+}
+/**
+ * Buffers, typed arrays, DataViews, ArrayBuffers, Maps and Sets as their type
+ * and size, such as [Uint8Array(30000000)], without reading their contents.
+ */
+export function summarize(obj) {
+    const name = safely(() => obj.constructor?.name);
+    const tag = toStringTag(obj);
+    const label = (fallback) => typeof name === "string" && name ? name : fallback;
+    if (typeof ArrayBuffer === "function" && ArrayBuffer.isView(obj)) {
+        const view = obj;
+        const size = typeof view.length === "number" ? view.length : view.byteLength;
+        return `[${label("TypedArray")}(${size})]`;
+    }
+    if (tag === "[object ArrayBuffer]" || tag === "[object SharedArrayBuffer]") {
+        return `[${label("ArrayBuffer")}(${obj.byteLength})]`;
+    }
+    if (tag === "[object Map]" || tag === "[object Set]") {
+        const size = safely(() => obj.size);
+        return `[${label(tag.slice(8, -1))}(${typeof size === "number" ? size : "?"})]`;
+    }
+    return undefined;
+}
+/**
+ * Makes any value safe to put in JSON: cycles, functions, bigints, errors and
+ * deep or wide structures become short strings, and long strings are cut.
+ * Arrays and objects are read only up to `breadth` entries, and binary data,
+ * Maps and Sets are summarised, so a huge value costs no more than what is kept.
+ */
+export function normalize(input, depth = 5, maxString = MAX_STRING, breadth = 1000) {
+    const ancestors = [];
+    function walk(value, remaining) {
+        if (value === null || value === undefined || typeof value === "boolean")
+            return value;
+        if (typeof value === "number")
+            return Number.isFinite(value) ? value : `[${value}]`;
+        if (typeof value === "string")
+            return truncate(value, maxString);
+        if (typeof value === "bigint")
+            return `[BigInt: ${value.toString()}]`;
+        if (typeof value === "symbol")
+            return `[${safeString(value)}]`;
+        if (typeof value === "function")
+            return `[Function: ${value.name || "<anonymous>"}]`;
+        const obj = value;
+        if (ancestors.includes(obj))
+            return "[Circular ~]";
+        if (isErrorLike(obj)) {
+            return walk({ name: obj.name, message: obj.message, stack: obj.stack }, remaining);
+        }
+        if (typeof obj.nodeType === "number" && typeof obj.nodeName === "string") {
+            return `[Node: ${obj.nodeName.toLowerCase()}]`;
+        }
+        // Before toJSON: Buffer.toJSON would copy every byte into an array.
+        const summary = summarize(obj);
+        if (summary)
+            return summary;
+        if (typeof obj.toJSON === "function") {
+            const json = safely(() => obj.toJSON());
+            if (json !== obj)
+                return walk(json, remaining);
+        }
+        if (remaining <= 0)
+            return Array.isArray(obj) ? "[Array]" : "[Object]";
+        ancestors.push(obj);
+        let out;
+        // Nothing past `breadth` entries is ever read or copied.
+        if (Array.isArray(obj)) {
+            const list = [];
+            const n = Math.min(obj.length, breadth);
+            for (let i = 0; i < n; i++)
+                list.push(walk(obj[i], remaining - 1));
+            if (obj.length > breadth)
+                list.push("[MaxProperties ~]");
+            out = list;
+        }
+        else {
+            const map = {};
+            let count = 0;
+            for (const key in obj) {
+                if (!Object.prototype.hasOwnProperty.call(obj, key))
+                    continue;
+                if (count++ >= breadth) {
+                    map[key] = "[MaxProperties ~]";
+                    break;
+                }
+                map[key] = walk(safely(() => obj[key], "[Unreadable]"), remaining - 1);
+            }
+            out = map;
+        }
+        ancestors.pop();
+        return out;
+    }
+    try {
+        return walk(input, depth);
+    }
+    catch {
+        return "[Unserializable]";
+    }
+}
+const SECRET_KEY = /pass|secret|token|auth|cookie|session|csrf|xsrf|key|sig|jwt|credential|code|otp/i;
+/** Removes credentials, the fragment and secret-looking query values from a URL. */
+export function scrubUrl(url) {
+    try {
+        let out = url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^@/?#]*@/i, "$1");
+        const hash = out.indexOf("#");
+        if (hash >= 0)
+            out = out.slice(0, hash);
+        const q = out.indexOf("?");
+        if (q < 0)
+            return out;
+        const query = out
+            .slice(q + 1)
+            .split("&")
+            .map((pair) => {
+            const eq = pair.indexOf("=");
+            const key = eq >= 0 ? pair.slice(0, eq) : pair;
+            return eq >= 0 && SECRET_KEY.test(key) ? `${key}=[Filtered]` : pair;
+        })
+            .join("&");
+        return `${out.slice(0, q + 1)}${query}`;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/esm/version.d.ts

@@ -0,0 +1,3 @@
+export declare const SDK_NAME = "statoss.javascript";
+export declare const SDK_VERSION = "0.1.1";
+export declare const SDK_PACKAGE = "npm:@statoss/sdk";

package/dist/esm/version.js

@@ -0,0 +1,4 @@
+export const SDK_NAME = "statoss.javascript";
+// Kept equal to package.json by a test.
+export const SDK_VERSION = "0.1.1";
+export const SDK_PACKAGE = "npm:@statoss/sdk";