@statoss/sdk 0.1.1 → 0.3.0

package/dist/cjs/schema.d.ts

@@ -0,0 +1,199 @@
+import type { Logger } from "./logger.js";
+import type { CaptureContext, Event, Level, SentryLevel } from "./types.js";
+/** The ranges a level ranks in: Sentry's five and OpenTelemetry's trace. */
+export declare const LIKES: readonly ["fatal", "error", "warning", "info", "debug", "trace"];
+export type Like = (typeof LIKES)[number];
+/** The colours a level or a category takes, by name. */
+export declare const SCHEMA_COLORS: readonly ["crimson", "red", "orange", "amber", "yellow", "green", "aqua", "teal", "blue", "violet", "indigo", "magenta", "plum", "grey"];
+export type SchemaColor = (typeof SCHEMA_COLORS)[number];
+/** What a rule tests: a tag by key, the logger, or one of the event's own fields. */
+export declare const RULE_SUBJECTS: readonly ["tag", "logger", "exception", "culprit", "title", "message"];
+export type RuleSubject = (typeof RULE_SUBJECTS)[number];
+export declare const RULE_MATCHES: readonly ["is", "starts", "contains"];
+export type RuleMatch = (typeof RULE_MATCHES)[number];
+export declare const FIELD_TYPES: readonly ["text", "number"];
+export type FieldType = (typeof FIELD_TYPES)[number];
+/** Each range's severities, as OpenTelemetry numbers them. */
+interface Severities {
+    fatal: 21 | 22 | 23 | 24;
+    error: 17 | 18 | 19 | 20;
+    warning: 13 | 14 | 15 | 16;
+    info: 9 | 10 | 11 | 12;
+    debug: 5 | 6 | 7 | 8;
+    trace: 1 | 2 | 3 | 4;
+}
+export type Severity = Severities[Like];
+/** A level of your own. Null clears a setting. */
+export interface LevelSettings {
+    /** The range it ranks in. Without it (and without severity) it ranks as error. */
+    like?: Like;
+    /** 1 to 24, inside the range of `like`. */
+    severity?: Severity;
+    label?: string | null;
+    color?: SchemaColor | null;
+}
+/** A category. Null clears a setting. */
+export interface CategorySettings {
+    label?: string | null;
+    color?: SchemaColor | null;
+    /** Left out of filters and lists; its events still carry it. */
+    hidden?: boolean;
+    /** A team member's email. */
+    owner?: string | null;
+}
+/** A field: a tag key. Null clears a setting. */
+export interface FieldSettings {
+    label?: string | null;
+    type?: FieldType;
+    unit?: string | null;
+    /** Gets a picker in Explore's filters. */
+    filterable?: boolean;
+}
+type RuleTests = {
+    subject: "tag";
+    tagKey: string;
+} | {
+    subject: Exclude<RuleSubject, "tag">;
+    tagKey?: undefined;
+};
+type RuleSets<L extends string, C extends string> = {
+    level: L;
+    category?: C;
+} | {
+    level?: L;
+    category: C;
+};
+/**
+ * Sets a level, a category or both for events that match: the first rule
+ * that matches wins. `match` defaults to "is".
+ */
+export type SchemaRule<L extends string = string, C extends string = string> = RuleTests & {
+    match?: RuleMatch;
+    value: string;
+} & RuleSets<L, C>;
+/** An app's levels, categories, fields and rules, as the server takes them. */
+export interface SchemaSpec {
+    /** Each name with the range it ranks in, or with its settings. */
+    levels?: {
+        readonly [name: string]: Like | LevelSettings;
+    };
+    categories?: readonly string[] | {
+        readonly [name: string]: CategorySettings;
+    };
+    fields?: readonly string[] | {
+        readonly [name: string]: FieldSettings;
+    };
+    rules?: readonly SchemaRule[];
+}
+type NamesIn<T> = T extends readonly (infer N)[] ? N & string : T extends object ? keyof T & string : never;
+type LevelNames<S> = S extends {
+    levels?: infer L;
+} ? NamesIn<NonNullable<L>> : never;
+type CategoryNames<S> = S extends {
+    categories?: infer C;
+} ? NamesIn<NonNullable<C>> : never;
+type FieldNames<S> = S extends {
+    fields?: infer F;
+} ? NamesIn<NonNullable<F>> : never;
+/** A Sentry level or a level of the schema. */
+export type LevelOf<S> = string extends LevelNames<S> ? Level : SentryLevel | LevelNames<S>;
+/** A category of the schema. */
+export type CategoryOf<S> = CategoryNames<S>;
+/** A field of the schema. */
+export type FieldOf<S> = FieldNames<S>;
+type NameChar = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "." | "-" | "_";
+/** True for 1 to Max of NameChar. A name only known as string passes. */
+type IsName<S extends string, Max extends number, Seen extends 0[] = []> = string extends S ? true : S extends `${infer C}${infer Rest}` ? C extends NameChar ? Seen["length"] extends Max ? false : IsName<Rest, Max, [...Seen, 0]> : false : Seen extends [] ? false : true;
+type LevelRule = "Level names are 1 to 32 lowercase letters, digits, dots, dashes or underscores";
+type CategoryRule = "Category names are 1 to 64 lowercase letters, digits, dots, dashes or underscores";
+type FieldRule = "Field names are not empty and do not start statoss.";
+type Only<V, Keys extends PropertyKey, Message extends string> = {
+    [P in Exclude<keyof V, Keys>]: {
+        [M in Message]: true;
+    };
+};
+type LevelCheck<V> = V extends string ? Like : {
+    like?: Like;
+    severity?: V extends {
+        like: infer K extends Like;
+    } ? Severities[K] : Severity;
+    label?: string | null;
+    color?: SchemaColor | null;
+} & Only<V, keyof LevelSettings, "A level takes like, severity, label and color">;
+/** Sentry's own levels rank as themselves: a label and a colour only. */
+type BuiltinLevelCheck<K extends SentryLevel, V> = V extends string ? K : {
+    like?: K;
+    label?: string | null;
+    color?: SchemaColor | null;
+} & Only<V, "like" | "label" | "color", "A built-in level takes label and color, and ranks as itself">;
+type CheckLevels<T> = {
+    [K in keyof T]: K extends SentryLevel ? BuiltinLevelCheck<K, T[K]> : K extends string ? IsName<K, 32> extends true ? LevelCheck<T[K]> : {
+        [M in LevelRule]: true;
+    } : never;
+};
+type CheckCategories<T> = T extends readonly unknown[] ? {
+    [I in keyof T]: T[I] extends string ? IsName<T[I], 64> extends true ? T[I] : {
+        [M in CategoryRule]: true;
+    } : string;
+} : {
+    [K in keyof T]: K extends string ? IsName<K, 64> extends true ? CategorySettings & Only<T[K], keyof CategorySettings, "A category takes label, color, hidden and owner"> : {
+        [M in CategoryRule]: true;
+    } : never;
+};
+type IsField<K extends string> = K extends "" | `statoss.${string}` ? false : true;
+type CheckFields<T> = T extends readonly unknown[] ? {
+    [I in keyof T]: T[I] extends string ? IsField<T[I]> extends true ? T[I] : {
+        [M in FieldRule]: true;
+    } : string;
+} : {
+    [K in keyof T]: K extends string ? IsField<K> extends true ? FieldSettings & Only<T[K], keyof FieldSettings, "A field takes label, type, unit and filterable"> : {
+        [M in FieldRule]: true;
+    } : never;
+};
+type CheckRules<T, L extends string, C extends string> = {
+    [I in keyof T]: SchemaRule<L, C> & Only<T[I], "subject" | "tagKey" | "match" | "value" | "level" | "category", "A rule takes subject, tagKey, match, value, level and category">;
+};
+/** What defineSchema holds a schema to, read from the schema itself. */
+export type CheckSchema<S> = {
+    [K in keyof S]: K extends "levels" ? CheckLevels<S[K]> : K extends "categories" ? CheckCategories<S[K]> : K extends "fields" ? CheckFields<S[K]> : K extends "rules" ? CheckRules<S[K], SentryLevel | LevelNames<S>, CategoryNames<S>> : {
+        "A schema takes levels, categories, fields and rules": true;
+    };
+};
+/**
+ * Declares an app's levels, categories, fields and rules. Returns the schema
+ * as given: plain data in the shape the server takes, so it can be sent as
+ * it is. Its names become types: pass it to init as `schema` and the capture
+ * functions init returns take only these names.
+ */
+export declare function defineSchema<const S extends SchemaSpec & CheckSchema<S>>(schema: S): S;
+/** A field's value; sent as a tag. */
+export type FieldValue = string | number | boolean;
+/** What the capture functions of init's handle take, typed by the schema. */
+export interface SchemaContext<S = SchemaSpec> extends Omit<CaptureContext, "level" | "category"> {
+    /** A Sentry level or a level of the schema. */
+    level?: LevelOf<S>;
+    /** A category of the schema, sent as the `statoss.category` tag. */
+    category?: CategoryOf<S>;
+    /**
+     * Fields of the schema, sent as tags; a schema that declares none takes
+     * none here.
+     */
+    fields?: [FieldOf<S>] extends [never] ? never : {
+        [K in FieldOf<S>]?: FieldValue;
+    };
+}
+/** The capture functions, typed by the schema given to init. */
+export interface Handle<S = SchemaSpec> {
+    /** Sends an error (or anything thrown). Returns the event id. */
+    captureException(error: unknown, context?: SchemaContext<S>): string;
+    /** Sends a message, with a level or a context. Returns the event id. */
+    captureMessage(message: string, levelOrContext?: LevelOf<S> | SchemaContext<S>): string;
+    /** Sends an event you built in Sentry's schema. Returns the event id. */
+    captureEvent(event: Event, context?: SchemaContext<S>): string;
+}
+/**
+ * The Sentry level each level of init's `schema` is sent as. Built-in
+ * levels are left out; names the SDK cannot send are logged in debug mode.
+ */
+export declare function readSchema(schema: unknown, logger: Logger): Record<string, SentryLevel>;
+export {};

package/dist/cjs/schema.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIELD_TYPES = exports.RULE_MATCHES = exports.RULE_SUBJECTS = exports.SCHEMA_COLORS = exports.LIKES = void 0;
+exports.defineSchema = defineSchema;
+exports.readSchema = readSchema;
+const levels_js_1 = require("./levels.js");
+const utils_js_1 = require("./utils.js");
+// The server's own lists (src/lib/app-schema.ts, src/lib/schema-colors.ts,
+// src/db/schema.ts), kept equal by a test.
+/** The ranges a level ranks in: Sentry's five and OpenTelemetry's trace. */
+exports.LIKES = [
+    "fatal",
+    "error",
+    "warning",
+    "info",
+    "debug",
+    "trace",
+];
+/** The colours a level or a category takes, by name. */
+exports.SCHEMA_COLORS = [
+    "crimson",
+    "red",
+    "orange",
+    "amber",
+    "yellow",
+    "green",
+    "aqua",
+    "teal",
+    "blue",
+    "violet",
+    "indigo",
+    "magenta",
+    "plum",
+    "grey",
+];
+/** What a rule tests: a tag by key, the logger, or one of the event's own fields. */
+exports.RULE_SUBJECTS = [
+    "tag",
+    "logger",
+    "exception",
+    "culprit",
+    "title",
+    "message",
+];
+exports.RULE_MATCHES = ["is", "starts", "contains"];
+exports.FIELD_TYPES = ["text", "number"];
+/**
+ * Declares an app's levels, categories, fields and rules. Returns the schema
+ * as given: plain data in the shape the server takes, so it can be sent as
+ * it is. Its names become types: pass it to init as `schema` and the capture
+ * functions init returns take only these names.
+ */
+function defineSchema(schema) {
+    return schema;
+}
+// At runtime
+/** The Sentry level a level of the schema is sent as. */
+function sentAs(name, value, logger) {
+    const settings = (0, utils_js_1.isObject)(value) ? value : {};
+    const like = typeof value === "string" ? value : settings.like;
+    if ((0, levels_js_1.isSentryLevel)(like))
+        return like;
+    if (like === "trace")
+        return "debug";
+    if (like !== undefined || (typeof value !== "string" && !(0, utils_js_1.isObject)(value))) {
+        logger.warn(`Level "${name}" in the schema: like should be ${exports.LIKES.join(", ")}; sent as error.`);
+        return "error";
+    }
+    const severity = settings.severity;
+    if (typeof severity !== "number" || severity < 1 || severity > 24)
+        return "error";
+    if (severity >= 21)
+        return "fatal";
+    if (severity >= 17)
+        return "error";
+    if (severity >= 13)
+        return "warning";
+    if (severity >= 9)
+        return "info";
+    return "debug";
+}
+/**
+ * The Sentry level each level of init's `schema` is sent as. Built-in
+ * levels are left out; names the SDK cannot send are logged in debug mode.
+ */
+function readSchema(schema, logger) {
+    const out = {};
+    if (schema === undefined || schema === null)
+        return out;
+    if (!(0, utils_js_1.isObject)(schema) || Array.isArray(schema)) {
+        logger.warn("Ignored `schema`: pass what defineSchema returns.");
+        return out;
+    }
+    const { levels, categories } = schema;
+    if ((0, utils_js_1.isObject)(levels) && !Array.isArray(levels)) {
+        for (const [name, value] of Object.entries(levels)) {
+            // A built-in level, given a label or a colour.
+            if ((0, levels_js_1.isSentryLevel)(name))
+                continue;
+            if ((0, levels_js_1.isLevelName)(name))
+                out[name] = sentAs(name, value, logger);
+            else
+                logger.warn(`Ignored level "${name}" in the schema: ${levels_js_1.LEVEL_RULE}.`);
+        }
+    }
+    else if (levels !== undefined && levels !== null) {
+        logger.warn('Ignored the schema\'s levels: they should be an object such as { "payment-failed": "error" }.');
+    }
+    const names = Array.isArray(categories)
+        ? categories
+        : (0, utils_js_1.isObject)(categories)
+            ? Object.keys(categories)
+            : [];
+    for (const name of names) {
+        if (!(0, levels_js_1.isCategoryName)(name))
+            logger.warn(`Category "${(0, utils_js_1.safeString)(name)}" in the schema cannot be sent: ${levels_js_1.CATEGORY_RULE}.`);
+    }
+    return out;
+}

package/dist/cjs/types.d.ts

@@ -64,6 +64,13 @@ export interface SdkInfo {
         version: string;
     }[];
 }
+/** A file the event's frames ran in; type "sourcemap" names its debug id. */
+export interface DebugImage {
+    type: string;
+    code_file?: string;
+    debug_id?: string;
+    [key: string]: unknown;
+}
 /** An event in Sentry's schema, as the SDK sends it. */
 export interface Event {
     event_id?: string;
@@ -91,6 +98,9 @@ export interface Event {
     request?: RequestInfo;
     fingerprint?: string[];
     sdk?: SdkInfo;
+    debug_meta?: {
+        images?: DebugImage[];
+    };
     [key: string]: unknown;
 }
 /** What `captureException`, `captureMessage` and `captureEvent` take as context. */

package/dist/cjs/version.d.ts

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

package/dist/cjs/version.js

@@ -3,5 +3,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_PACKAGE = exports.SDK_VERSION = exports.SDK_NAME = void 0;
 exports.SDK_NAME = "statoss.javascript";
 // Kept equal to package.json by a test.
-exports.SDK_VERSION = "0.1.1";
+exports.SDK_VERSION = "0.3.0";
 exports.SDK_PACKAGE = "npm:@statoss/sdk";

package/dist/esm/client.d.ts

@@ -2,6 +2,10 @@ import { type Logger } from "./logger.js";
 import { type RuntimeInfo } from "./runtime.js";
 import { type Scope } from "./scope.js";
 import type { Breadcrumb, BreadcrumbHint, CaptureContext, Event, InitOptions } from "./types.js";
+/** init's options as the client reads them: init may pass a schema. */
+export type ClientOptions = InitOptions & {
+    schema?: unknown;
+};
 export declare class Client {
     readonly logger: Logger;
     readonly runtime: RuntimeInfo;
@@ -20,7 +24,7 @@ export declare class Client {
     private reportTimer?;
     private previousSignature?;
     private closed;
-    constructor(options: InitOptions);
+    constructor(options: ClientOptions);
     /** Installs the integrations that apply to this runtime. */
     setup(): void;
     captureException(error: unknown, context: CaptureContext | undefined, scope: Scope): string;
@@ -44,7 +48,10 @@ export declare class Client {
     /** Merges scope, context and options into the event, in Sentry's field order. */
     private prepare;
     private process;
-    /** Makes what beforeSend handed back valid again: a Sentry level, string tags, a sane size. */
+    /**
+     * Makes what beforeSend handed back valid again (a Sentry level, string
+     * tags, a sane size) and names the debug ids of the files its frames ran in.
+     */
     private finish;
     private send;
 }

package/dist/esm/client.js

@@ -1,3 +1,4 @@
+import { addDebugImages } from "./debug-ids.js";
 import { authHeader, envelopeEndpoint, envelopeUrlWithQueryAuth, parseDsn, } from "./dsn.js";
 import { clientReportEnvelope, eventEnvelope, } from "./envelope.js";
 import { addInitialFrame, eventFromUnknown } from "./event.js";
@@ -10,6 +11,7 @@ import { installGlobalHandlers } from "./integrations/handlers.js";
 import { CATEGORY_TAG, chooseLevel, isSentryLevel, LEVEL_TAG, readCategory, readLevels, } from "./levels.js";
 import { makeLogger } from "./logger.js";
 import { describeRuntime } from "./runtime.js";
+import { readSchema } from "./schema.js";
 import { MAX_BREADCRUMBS } from "./scope.js";
 import { fetchTransport, Sender } from "./transport.js";
 import { isObject, isThenable, normalize, now, safely, safeString, scrubUrl, truncate, unref, uuid4, } from "./utils.js";
@@ -50,6 +52,32 @@ function cleanTags(tags) {
     }
     return out;
 }
+/** A capture's fields, as tags. Keys starting statoss. are not fields. */
+function fieldTags(fields, logger) {
+    const out = {};
+    if (fields === undefined || fields === null)
+        return out;
+    if (!isObject(fields) || Array.isArray(fields)) {
+        logger.warn('Ignored `fields`: it should be an object such as { route: "/pay" }.');
+        return out;
+    }
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined || value === null)
+            continue;
+        if (key === "" || key.startsWith("statoss.")) {
+            logger.warn(`Ignored field "${key}": fields are not empty and do not start statoss.`);
+        }
+        else if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean") {
+            out[key] = value;
+        }
+        else {
+            logger.warn(`Ignored field "${key}": its value should be a string, number or boolean.`);
+        }
+    }
+    return out;
+}
 function cleanContexts(contexts) {
     const out = {};
     for (const [name, value] of Object.entries(contexts)) {
@@ -99,7 +127,11 @@ export class Client {
         this.options = options;
         this.logger = makeLogger(options.debug === true);
         this.runtime = describeRuntime();
-        this.levels = readLevels(options.levels, this.logger);
+        // What `levels` says wins over the schema.
+        this.levels = {
+            ...readSchema(options.schema, this.logger),
+            ...readLevels(options.levels, this.logger),
+        };
         const rate = options.sampleRate;
         if (rate !== undefined &&
             !(typeof rate === "number" && rate >= 0 && rate <= 1)) {
@@ -325,6 +357,7 @@ export class Client {
         const tags = {
             ...scope._tags,
             ...ctx.tags,
+            ...fieldTags(ctx.fields, this.logger),
             ...base.tags,
         };
         if (choice.custom)
@@ -431,7 +464,10 @@ export class Client {
         }
         this.send(this.finish(final));
     }
-    /** Makes what beforeSend handed back valid again: a Sentry level, string tags, a sane size. */
+    /**
+     * Makes what beforeSend handed back valid again (a Sentry level, string
+     * tags, a sane size) and names the debug ids of the files its frames ran in.
+     */
     finish(event) {
         if (!isSentryLevel(event.level)) {
             const choice = chooseLevel([event.level], this.levels, "error", this.logger);
@@ -441,6 +477,7 @@ export class Client {
         }
         if (isObject(event.tags))
             event.tags = cleanTags(event.tags);
+        addDebugImages(event);
         const size = () => safely(() => JSON.stringify(event).length, 0) ?? 0;
         if (size() > MAX_EVENT_CHARS) {
             this.logger.warn("The event is over 1 MB; sending it without breadcrumbs and extra.");

package/dist/esm/debug-ids.d.ts

@@ -0,0 +1,16 @@
+import type { Event } from "./types.js";
+/**
+ * Debug ids by the abs_path of the bundle they belong to, as Sentry's
+ * getFilenameToDebugIdMap reads them. `sentry-cli sourcemaps inject` and
+ * Sentry's bundler plugins put a snippet in each bundle that sets
+ * `globalThis._sentryDebugIds[new Error().stack] = "<debug id>"`, so the
+ * newest frame of each key ran in that bundle. Read again only when the
+ * number of entries changes (or the object is replaced).
+ */
+export declare function debugIdsByFile(): ReadonlyMap<string, string>;
+/**
+ * Adds `{ type: "sourcemap", code_file, debug_id }` to event.debug_meta.images
+ * for each file in the event's frames that has a debug id, after the images
+ * already there, so the server can map those frames to source. Never throws.
+ */
+export declare function addDebugImages(event: Event): void;

package/dist/esm/debug-ids.js

@@ -0,0 +1,108 @@
+import { parseStack } from "./stack.js";
+import { isObject } from "./utils.js";
+const NONE = new Map();
+// The file each stack string names, so each is parsed once.
+const fileOfStack = new Map();
+let lastIds;
+let lastCount = -1;
+let lastMap = NONE;
+/**
+ * Debug ids by the abs_path of the bundle they belong to, as Sentry's
+ * getFilenameToDebugIdMap reads them. `sentry-cli sourcemaps inject` and
+ * Sentry's bundler plugins put a snippet in each bundle that sets
+ * `globalThis._sentryDebugIds[new Error().stack] = "<debug id>"`, so the
+ * newest frame of each key ran in that bundle. Read again only when the
+ * number of entries changes (or the object is replaced).
+ */
+export function debugIdsByFile() {
+    const ids = globalThis._sentryDebugIds;
+    if (!isObject(ids) || Array.isArray(ids))
+        return NONE;
+    const keys = Object.keys(ids);
+    if (ids === lastIds && keys.length === lastCount)
+        return lastMap;
+    const map = new Map();
+    for (const key of keys) {
+        const id = ids[key];
+        if (typeof id !== "string" || id === "")
+            continue;
+        if (!fileOfStack.has(key))
+            fileOfStack.set(key, newestFile(key));
+        const file = fileOfStack.get(key);
+        if (file)
+            map.set(file, id);
+    }
+    lastIds = ids;
+    lastCount = keys.length;
+    lastMap = map;
+    return map;
+}
+// As Sentry does: walking from the newest frame, the first that names a file.
+function newestFile(stack) {
+    const frames = parseStack(stack);
+    for (let i = frames.length - 1; i >= 0; i--) {
+        const file = frames[i].abs_path;
+        if (file)
+            return file;
+    }
+    return undefined;
+}
+// Sentry's schema allows { values: [...] } or a bare list.
+function valuesOf(value) {
+    if (Array.isArray(value))
+        return value;
+    if (isObject(value) && Array.isArray(value.values))
+        return value.values;
+    return [];
+}
+/** The abs_path of every frame in the event's exceptions and threads. */
+function framePaths(event) {
+    const paths = new Set();
+    const holders = [...valuesOf(event.exception), ...valuesOf(event.threads)];
+    for (const holder of holders) {
+        if (!isObject(holder) || !isObject(holder.stacktrace))
+            continue;
+        const frames = holder.stacktrace.frames;
+        if (!Array.isArray(frames))
+            continue;
+        for (const frame of frames) {
+            if (isObject(frame) && typeof frame.abs_path === "string")
+                paths.add(frame.abs_path);
+        }
+    }
+    return paths;
+}
+/**
+ * Adds `{ type: "sourcemap", code_file, debug_id }` to event.debug_meta.images
+ * for each file in the event's frames that has a debug id, after the images
+ * already there, so the server can map those frames to source. Never throws.
+ */
+export function addDebugImages(event) {
+    try {
+        const ids = debugIdsByFile();
+        if (!ids.size)
+            return;
+        const meta = isObject(event.debug_meta)
+            ? event.debug_meta
+            : {};
+        const images = Array.isArray(meta.images)
+            ? [...meta.images]
+            : [];
+        const named = new Set();
+        for (const image of images) {
+            if (isObject(image) && image.type === "sourcemap")
+                named.add(image.code_file);
+        }
+        const before = images.length;
+        for (const path of framePaths(event)) {
+            const id = ids.get(path);
+            if (id !== undefined && !named.has(path))
+                images.push({ type: "sourcemap", code_file: path, debug_id: id });
+        }
+        if (images.length > before)
+            event.debug_meta = { ...meta, images: images };
+    }
+    catch {
+        // A malformed _sentryDebugIds or event costs the images, nothing more.
+    }
+}

package/dist/esm/index.d.ts

@@ -1,14 +1,23 @@
+import type { CheckSchema, Handle, SchemaSpec } from "./schema.js";
 import type { Breadcrumb, CaptureContext, Event, InitOptions, Level, Primitive, User } from "./types.js";
 export { withScope } from "./hub.js";
+export { defineSchema } from "./schema.js";
+export type { CategoryOf, CategorySettings, CheckSchema, FieldOf, FieldSettings, FieldType, FieldValue, Handle, LevelOf, LevelSettings, Like, RuleMatch, RuleSubject, SchemaColor, SchemaContext, SchemaRule, SchemaSpec, Severity, } from "./schema.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";
+export type { Breadcrumb, BreadcrumbHint, CaptureContext, DebugImage, 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.
+ *
+ * With a `schema` from defineSchema, its levels are sent as the Sentry level
+ * each ranks like, and the capture functions it returns take only the
+ * schema's levels, categories and fields.
  */
-export declare function init(options?: InitOptions): void;
+export declare function init<const S extends SchemaSpec & CheckSchema<S> = SchemaSpec>(options?: InitOptions & {
+    schema?: S;
+}): Handle<S>;
 /** Sends an error (or anything thrown). Returns the event id. */
 export declare function captureException(error: unknown, context?: CaptureContext): string;
 /**

package/dist/esm/index.js

@@ -2,12 +2,8 @@ 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 { defineSchema } from "./schema.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();
@@ -26,6 +22,7 @@ export function init(options = {}) {
             safely(() => console.error("[StatOSS] init failed:", error));
         }
     }
+    return HANDLE;
 }
 /** Sends an error (or anything thrown). Returns the event id. */
 export function captureException(error, context) {
@@ -42,6 +39,13 @@ export function captureMessage(message, levelOrContext) {
 export function captureEvent(event, context) {
     return captureWith(undefined, (client, scope) => client.captureEvent(event, context, scope));
 }
+// What init returns: the same functions, typed by the schema. The client
+// reads a context's fields whichever function it came through.
+const HANDLE = Object.freeze({
+    captureException,
+    captureMessage,
+    captureEvent,
+});
 /** Pass null to forget the user. */
 export function setUser(user) {
     safely(() => getCurrentScope().setUser(user));