@statoss/sdk 0.1.0 → 0.2.0

package/README.md

@@ -252,6 +252,23 @@ The Edge runtime has no global error hook either: capture where you handle
 errors and `await StatOSS.flush(2000)` (or pass it to `waitUntil`) before
 returning. In Next.js, the `instrumentation.ts` above covers it.
 
+## Source maps
+
+After the build, give the bundles and their maps debug ids, then upload the
+maps with Sentry's CLI:
+
+```sh
+npx @sentry/cli sourcemaps inject ./dist
+
+SENTRY_URL=https://statoss.com \
+SENTRY_AUTH_TOKEN=<a StatOSS API key with write access> \
+npx @sentry/cli sourcemaps upload --org statoss --project <app slug> ./dist
+```
+
+Adding `--release <release>` to the upload is optional. Deploy the bundles as
+`inject` left them: the SDK reads their debug ids and sends them with each
+event. Frames are then shown as source and grouped by their source names.
+
 ## Custom levels and categories
 
 Sentry has five levels: `fatal`, `error`, `warning`, `info` and `debug`.

package/dist/cjs/client.d.ts

@@ -44,7 +44,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/cjs/client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Client = void 0;
+const debug_ids_js_1 = require("./debug-ids.js");
 const dsn_js_1 = require("./dsn.js");
 const envelope_js_1 = require("./envelope.js");
 const event_js_1 = require("./event.js");
@@ -434,7 +435,10 @@ 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 (!(0, levels_js_1.isSentryLevel)(event.level)) {
             const choice = (0, levels_js_1.chooseLevel)([event.level], this.levels, "error", this.logger);
@@ -444,6 +448,7 @@ class Client {
         }
         if ((0, utils_js_1.isObject)(event.tags))
             event.tags = cleanTags(event.tags);
+        (0, debug_ids_js_1.addDebugImages)(event);
         const size = () => (0, utils_js_1.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/cjs/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/cjs/debug-ids.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugIdsByFile = debugIdsByFile;
+exports.addDebugImages = addDebugImages;
+const stack_js_1 = require("./stack.js");
+const utils_js_1 = require("./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).
+ */
+function debugIdsByFile() {
+    const ids = globalThis._sentryDebugIds;
+    if (!(0, utils_js_1.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 = (0, stack_js_1.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 ((0, utils_js_1.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 (!(0, utils_js_1.isObject)(holder) || !(0, utils_js_1.isObject)(holder.stacktrace))
+            continue;
+        const frames = holder.stacktrace.frames;
+        if (!Array.isArray(frames))
+            continue;
+        for (const frame of frames) {
+            if ((0, utils_js_1.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.
+ */
+function addDebugImages(event) {
+    try {
+        const ids = debugIdsByFile();
+        if (!ids.size)
+            return;
+        const meta = (0, utils_js_1.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 ((0, utils_js_1.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/cjs/index.d.ts

@@ -2,7 +2,7 @@ import type { Breadcrumb, CaptureContext, Event, InitOptions, Level, Primitive,
 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";
+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

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.0";
+export declare const SDK_VERSION = "0.2.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.0";
+exports.SDK_VERSION = "0.2.0";
 exports.SDK_PACKAGE = "npm:@statoss/sdk";

package/dist/esm/client.d.ts

@@ -44,7 +44,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";
@@ -431,7 +432,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 +445,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

@@ -2,7 +2,7 @@ import type { Breadcrumb, CaptureContext, Event, InitOptions, Level, Primitive,
 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";
+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

package/dist/esm/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/esm/version.d.ts

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

package/dist/esm/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statoss/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Error tracking for StatOSS: browsers, Node, Bun, Deno, Cloudflare Workers and Vercel Edge. Speaks Sentry's protocol.",
   "license": "MIT",
   "author": "StatOSS",