@statoss/sdk 0.2.0 → 0.4.0

package/dist/esm/schema.js

@@ -0,0 +1,153 @@
+import { CATEGORY_RULE, isCategoryName, isLevelName, isSentryLevel, LEVEL_RULE, } from "./levels.js";
+import { LOG_SEVERITY, logLevelOf, rangeOfSeverity, } from "./logs.js";
+import { isObject, safeString } from "./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. */
+export const LIKES = [
+    "fatal",
+    "error",
+    "warning",
+    "info",
+    "debug",
+    "trace",
+];
+/** The colours a level or a category takes, by name. */
+export const 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. */
+export const RULE_SUBJECTS = [
+    "tag",
+    "logger",
+    "exception",
+    "culprit",
+    "title",
+    "message",
+];
+export const RULE_MATCHES = ["is", "starts", "contains"];
+export const 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.
+ */
+export 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 = isObject(value) ? value : {};
+    const like = typeof value === "string" ? value : settings.like;
+    if (isSentryLevel(like))
+        return like;
+    if (like === "trace")
+        return "debug";
+    if (like !== undefined || (typeof value !== "string" && !isObject(value))) {
+        logger.warn(`Level "${name}" in the schema: like should be ${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";
+}
+/**
+ * How a line at each level of init's `schema` is logged: at its range's
+ * level (trace stays trace), with its severity when it gives one inside
+ * that range. Names readSchema refuses are left out.
+ */
+export function schemaLogLevels(schema) {
+    const out = {};
+    if (!isObject(schema) || Array.isArray(schema))
+        return out;
+    const { levels } = schema;
+    if (!isObject(levels) || Array.isArray(levels))
+        return out;
+    for (const [name, value] of Object.entries(levels)) {
+        if (isSentryLevel(name) || !isLevelName(name))
+            continue;
+        const settings = isObject(value) ? value : {};
+        const like = typeof value === "string" ? value : settings.like;
+        const given = settings.severity;
+        const severity = typeof given === "number" &&
+            Number.isInteger(given) &&
+            given >= 1 &&
+            given <= 24
+            ? given
+            : undefined;
+        let level = "error";
+        if (typeof like === "string" && LIKES.includes(like))
+            level = logLevelOf(like) ?? "error";
+        else if (like === undefined && severity !== undefined)
+            level = rangeOfSeverity(severity);
+        out[name] = {
+            level,
+            severity: severity !== undefined && rangeOfSeverity(severity) === level
+                ? severity
+                : LOG_SEVERITY[level],
+        };
+    }
+    return out;
+}
+/**
+ * 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 function readSchema(schema, logger) {
+    const out = {};
+    if (schema === undefined || schema === null)
+        return out;
+    if (!isObject(schema) || Array.isArray(schema)) {
+        logger.warn("Ignored `schema`: pass what defineSchema returns.");
+        return out;
+    }
+    const { levels, categories } = schema;
+    if (isObject(levels) && !Array.isArray(levels)) {
+        for (const [name, value] of Object.entries(levels)) {
+            // A built-in level, given a label or a colour.
+            if (isSentryLevel(name))
+                continue;
+            if (isLevelName(name))
+                out[name] = sentAs(name, value, logger);
+            else
+                logger.warn(`Ignored level "${name}" in the schema: ${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
+        : isObject(categories)
+            ? Object.keys(categories)
+            : [];
+    for (const name of names) {
+        if (!isCategoryName(name))
+            logger.warn(`Category "${safeString(name)}" in the schema cannot be sent: ${CATEGORY_RULE}.`);
+    }
+    return out;
+}

package/dist/esm/transport.d.ts

@@ -2,6 +2,8 @@ import { type Envelope } from "./envelope.js";
 import type { Logger } from "./logger.js";
 import type { Transport } from "./types.js";
 export declare const QUEUE_LIMIT = 30;
+/** Of the queue, what log envelopes may take, so a flood of lines never pushes out an error. */
+export declare const LOG_QUEUE_LIMIT = 10;
 export declare const CONCURRENCY = 5;
 /** The default transport: fetch, called on globalThis (Workers refuse any other this). */
 export declare function fetchTransport(browserLike: boolean): Transport;
@@ -16,12 +18,15 @@ export interface SenderOptions {
 }
 /**
  * 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.
+ * waiting or in flight, of them at most 10 of log lines. Whatever cannot
+ * be sent is counted for client reports.
  */
 export declare class Sender {
     private readonly options;
     private readonly queue;
     private active;
+    /** Log envelopes waiting or in flight. */
+    private logs;
     private limits;
     private waiters;
     private keepaliveBytes;

package/dist/esm/transport.js

@@ -1,7 +1,9 @@
-import { itemCategory, serializeEnvelope } from "./envelope.js";
+import { isLogEnvelope, itemCategory, itemQuantity, serializeEnvelope, } from "./envelope.js";
 import { isRateLimited, updateRateLimits, } from "./ratelimit.js";
 import { safely, unref } from "./utils.js";
 export const QUEUE_LIMIT = 30;
+/** Of the queue, what log envelopes may take, so a flood of lines never pushes out an error. */
+export const LOG_QUEUE_LIMIT = 10;
 export const CONCURRENCY = 5;
 const REQUEST_TIMEOUT_MS = 30000;
 // Browsers refuse keepalive requests past 64 KiB in flight in total.
@@ -57,13 +59,16 @@ function header(response, name) {
 }
 /**
  * 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.
+ * waiting or in flight, of them at most 10 of log lines. Whatever cannot
+ * be sent is counted for client reports.
  */
 export class Sender {
     constructor(options) {
         this.options = options;
         this.queue = [];
         this.active = 0;
+        /** Log envelopes waiting or in flight. */
+        this.logs = 0;
         this.limits = {};
         this.waiters = [];
         this.keepaliveBytes = 0;
@@ -73,11 +78,15 @@ export class Sender {
         const allowed = this.withoutLimited(envelope);
         if (!allowed)
             return;
-        if (this.queue.length + this.active >= QUEUE_LIMIT) {
+        const log = isLogEnvelope(allowed);
+        if (this.queue.length + this.active >= QUEUE_LIMIT ||
+            (log && this.logs >= LOG_QUEUE_LIMIT)) {
             this.options.logger.warn("Dropped an envelope: the send queue is full.");
             this.lose(allowed, "queue_overflow");
             return;
         }
+        if (log)
+            this.logs++;
         this.queue.push(allowed);
         this.pump();
     }
@@ -126,7 +135,7 @@ export class Sender {
             if (!isRateLimited(this.limits, category, now))
                 return true;
             if (category !== "internal")
-                this.options.recordLoss("ratelimit_backoff", category);
+                this.options.recordLoss("ratelimit_backoff", category, itemQuantity(item));
             return false;
         });
         if (items.length < envelope[1].length) {
@@ -136,13 +145,20 @@ export class Sender {
     }
     pump() {
         while (this.active < CONCURRENCY && this.queue.length > 0) {
+            const waited = this.queue.shift();
+            const log = isLogEnvelope(waited);
             // A 429 may have come in while it waited.
-            const next = this.withoutLimited(this.queue.shift());
-            if (!next)
+            const next = this.withoutLimited(waited);
+            if (!next) {
+                if (log)
+                    this.logs--;
                 continue;
+            }
             this.active++;
             const done = () => {
                 this.active--;
+                if (log)
+                    this.logs--;
                 this.pump();
             };
             void this.deliver(next).then(done, done);
@@ -207,7 +223,7 @@ export class Sender {
             const category = itemCategory(item);
             // A lost client report is not reported again.
             if (category !== "internal")
-                this.options.recordLoss(reason, category);
+                this.options.recordLoss(reason, category, itemQuantity(item));
         }
     }
 }

package/dist/esm/types.d.ts

@@ -1,3 +1,4 @@
+import type { Log } from "./logs.js";
 /** The five levels Sentry knows. */
 export type SentryLevel = "fatal" | "error" | "warning" | "info" | "debug";
 /**
@@ -174,7 +175,10 @@ export interface InitOptions {
     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. */
+    /**
+     * When true, browsers ask the server to record the sender's IP address,
+     * and log lines carry the scope's user. Defaults to false.
+     */
     sendDefaultPii?: boolean;
     /** Tags on every event. */
     tags?: Record<string, Primitive>;
@@ -187,4 +191,8 @@ export interface InitOptions {
     integrations?: IntegrationToggles;
     /** Your own level names and the Sentry level each is sent as, such as { "payment-failed": "error" }. */
     levels?: Record<string, SentryLevel>;
+    /** Sends the lines of `logger`, as Sentry's enableLogs does. Defaults to false. */
+    logs?: boolean;
+    /** Change or drop (return null) a log line before it is sent. */
+    beforeSendLog?: (log: Log) => Log | null;
 }

package/dist/esm/version.d.ts

@@ -1,3 +1,3 @@
 export declare const SDK_NAME = "statoss.javascript";
-export declare const SDK_VERSION = "0.2.0";
+export declare const SDK_VERSION = "0.4.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.2.0";
+export const SDK_VERSION = "0.4.0";
 export const SDK_PACKAGE = "npm:@statoss/sdk";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statoss/sdk",
-  "version": "0.2.0",
-  "description": "Error tracking for StatOSS: browsers, Node, Bun, Deno, Cloudflare Workers and Vercel Edge. Speaks Sentry's protocol.",
+  "version": "0.4.0",
+  "description": "Error tracking and logs for StatOSS: browsers, Node, Bun, Deno, Cloudflare Workers and Vercel Edge. Speaks Sentry's protocol.",
   "license": "MIT",
   "author": "StatOSS",
   "homepage": "https://statoss.com",
@@ -14,6 +14,7 @@
     "statoss",
     "errors",
     "error-tracking",
+    "logs",
     "sentry",
     "monitoring"
   ],
@@ -38,6 +39,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {