@statoss/sdk 0.2.0 → 0.3.0

package/README.md

@@ -269,20 +269,88 @@ 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
+## Your own levels, categories and fields
 
 Sentry has five levels: `fatal`, `error`, `warning`, `info` and `debug`.
-StatOSS lets you use your own words as well, and adds a category. Both are
-sent as tags next to the nearest Sentry level, so Sentry and any Sentry-based
-tool still read the event normally.
+StatOSS adds levels of your own, categories and fields. They travel as tags
+next to the nearest Sentry level, so Sentry and any Sentry-based tool still
+read the event normally.
+
+Declare them with `defineSchema` and give the schema to `init`. The capture
+functions `init` returns take only the schema's names, so a wrong one fails
+to compile.
 
 ```ts
-StatOSS.init({
-  dsn: "...",
+import * as StatOSS from "@statoss/sdk";
+
+export const schema = StatOSS.defineSchema({
   levels: {
-    "payment-failed": "error",
+    "payment-failed": { like: "error", label: "Payment failed" },
     "slow-query": "warning",
   },
+  categories: {
+    billing: { label: "Billing", color: "plum" },
+    auth: {},
+  },
+  fields: {
+    route: { label: "Route", filterable: true },
+    duration_ms: { type: "number", unit: "ms", label: "Duration" },
+  },
+});
+
+const statoss = StatOSS.init({ dsn: process.env.STATOSS_DSN, schema });
+
+statoss.captureException(error, {
+  level: "payment-failed",
+  category: "billing",
+  fields: { route: "/pay" },
+});
+// level "error", tags { "statoss.level": "payment-failed",
+//   "statoss.category": "billing", route: "/pay" }
+
+statoss.captureMessage("Search took 2.4 s", {
+  level: "slow-query",
+  fields: { duration_ms: 2400 },
+});
+
+// @ts-expect-error: not a level of this schema
+statoss.captureException(error, { level: "payment-faild" });
+```
+
+- A level ranks like `fatal`, `error`, `warning`, `info`, `debug` or
+  `trace`: give that alone, or `like` with an optional `severity` (1 to 24,
+  inside its range), `label` and `color`. It is sent as the nearest Sentry
+  level (`trace` as `debug`; `error` when none is given).
+- A category takes an optional `label`, `color`, `owner` (a team member's
+  email) and `hidden`.
+- A field is a tag key, with an optional `label`, `type` (`text` or
+  `number`), `unit` and `filterable`. Field values are strings, numbers or
+  booleans.
+- Categories and fields can also be lists of names.
+- `rules` set a level or a category for events that match, such as
+  `{ subject: "logger", value: "payments", category: "billing" }`. They name
+  the schema's own levels and categories.
+- Colours: `crimson`, `red`, `orange`, `amber`, `yellow`, `green`, `aqua`,
+  `teal`, `blue`, `violet`, `indigo`, `magenta`, `plum` and `grey`.
+- Names: a level is 1 to 32 characters and a category 1 to 64, of lowercase
+  letters, digits, dots, dashes and underscores. A field is any tag key not
+  starting `statoss.`.
+
+`defineSchema` refuses a wrong name, range, severity, colour or setting at
+compile time (TypeScript 5.0 or later). It returns the schema as given:
+plain data in the shape StatOSS's schema API takes. A function of yours
+that hands a schema to `init` types it as
+`<const S extends SchemaSpec & CheckSchema<S>>(schema: S)`.
+
+### Without a schema
+
+The module-level functions take any level or category name, and `levels` in
+`init` maps your names to Sentry levels:
+
+```ts
+StatOSS.init({
+  dsn: "...",
+  levels: { "payment-failed": "error", "slow-query": "warning" },
 });
 
 StatOSS.captureMessage("Card declined", "payment-failed");
@@ -295,11 +363,10 @@ StatOSS.captureException(error, {
 // level "warning", tags { "statoss.level": "slow-query", "statoss.category": "db.postgres" }
 ```
 
-- `level` takes a Sentry level or any name of your own. A name that is not in
-  `levels` is sent as `error`.
-- `category` sets the `statoss.category` tag.
-- Names are 1 to 64 characters of lowercase letters, digits, dots, dashes and
-  underscores. Others are ignored; with `debug: true` the SDK logs each one.
+- A name in neither `levels` nor the schema is sent as `error`. Given both,
+  `levels` wins.
+- Names the SDK cannot send are ignored; with `debug: true` it logs each
+  one.
 - StatOSS filters and groups on these tags like any other.
 
 ## What is captured
@@ -356,7 +423,8 @@ await StatOSS.withScope(async (scope) => {
 ## API
 
 ```ts
-init(options): void
+init(options): handle                                // handle.captureException, captureMessage, captureEvent
+defineSchema(schema): schema                         // the schema as given, its names as types
 captureException(error, context?): string            // returns the event id
 captureMessage(message, levelOrContext?): string
 captureEvent(event, context?): string
@@ -374,8 +442,9 @@ scope.setUser, setTag, setTags, setExtra, setExtras, setContext, setLevel,
 scope.captureException, captureMessage, captureEvent // with this scope
 ```
 
-`context` is `{ level, tags, extra, contexts, user, fingerprint, category }`.
-It wins over the scope for that one event.
+`context` is `{ level, tags, extra, contexts, user, fingerprint, category }`,
+and on the handle `init` returns also `fields`. It wins over the scope for
+that one event.
 
 ### Options
 
@@ -392,6 +461,7 @@ It wins over the scope for that one event.
 | `sendDefaultPii`   | `false`        | Record the sender's IP address                         |
 | `tags`             |                | Tags on every event                                    |
 | `initialScope`     |                | `{ tags, extra, contexts, user, level, fingerprint }`  |
+| `schema`           |                | From `defineSchema`: your levels, categories, fields   |
 | `levels`           |                | Your level names and the Sentry level each is sent as  |
 | `integrations`     | all on         | See above                                              |
 | `enabled`          | `true`         |                                                        |

package/dist/cjs/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;

package/dist/cjs/client.js

@@ -14,6 +14,7 @@ const handlers_js_1 = require("./integrations/handlers.js");
 const levels_js_1 = require("./levels.js");
 const logger_js_1 = require("./logger.js");
 const runtime_js_1 = require("./runtime.js");
+const schema_js_1 = require("./schema.js");
 const scope_js_1 = require("./scope.js");
 const transport_js_1 = require("./transport.js");
 const utils_js_1 = require("./utils.js");
@@ -54,6 +55,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 (!(0, utils_js_1.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)) {
@@ -103,7 +130,11 @@ class Client {
         this.options = options;
         this.logger = (0, logger_js_1.makeLogger)(options.debug === true);
         this.runtime = (0, runtime_js_1.describeRuntime)();
-        this.levels = (0, levels_js_1.readLevels)(options.levels, this.logger);
+        // What `levels` says wins over the schema.
+        this.levels = {
+            ...(0, schema_js_1.readSchema)(options.schema, this.logger),
+            ...(0, levels_js_1.readLevels)(options.levels, this.logger),
+        };
         const rate = options.sampleRate;
         if (rate !== undefined &&
             !(typeof rate === "number" && rate >= 0 && rate <= 1)) {
@@ -329,6 +360,7 @@ class Client {
         const tags = {
             ...scope._tags,
             ...ctx.tags,
+            ...fieldTags(ctx.fields, this.logger),
             ...base.tags,
         };
         if (choice.custom)

package/dist/cjs/index.d.ts

@@ -1,5 +1,8 @@
+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, DebugImage, Event, EventHint, Exception, InitOptions, IntegrationToggles, Level, Mechanism, Primitive, RequestInfo, ScopeData, SdkInfo, SentryLevel, StackFrame, Transport, TransportRequest, TransportResponse, User, } from "./types.js";
@@ -7,8 +10,14 @@ export type { Breadcrumb, BreadcrumbHint, CaptureContext, DebugImage, Event, Eve
  * 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/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SDK_VERSION = exports.SDK_NAME = exports.withScope = void 0;
+exports.SDK_VERSION = exports.SDK_NAME = exports.defineSchema = exports.withScope = void 0;
 exports.init = init;
 exports.captureException = captureException;
 exports.captureMessage = captureMessage;
@@ -19,14 +19,11 @@ const hub_js_1 = require("./hub.js");
 const utils_js_1 = require("./utils.js");
 var hub_js_2 = require("./hub.js");
 Object.defineProperty(exports, "withScope", { enumerable: true, get: function () { return hub_js_2.withScope; } });
+var schema_js_1 = require("./schema.js");
+Object.defineProperty(exports, "defineSchema", { enumerable: true, get: function () { return schema_js_1.defineSchema; } });
 var version_js_1 = require("./version.js");
 Object.defineProperty(exports, "SDK_NAME", { enumerable: true, get: function () { return version_js_1.SDK_NAME; } });
 Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return version_js_1.SDK_VERSION; } });
-/**
- * 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.
- */
 function init(options = {}) {
     try {
         const carrier = (0, hub_js_1.getCarrier)();
@@ -45,6 +42,7 @@ function init(options = {}) {
             (0, utils_js_1.safely)(() => console.error("[StatOSS] init failed:", error));
         }
     }
+    return HANDLE;
 }
 /** Sends an error (or anything thrown). Returns the event id. */
 function captureException(error, context) {
@@ -61,6 +59,13 @@ function captureMessage(message, levelOrContext) {
 function captureEvent(event, context) {
     return (0, hub_js_1.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. */
 function setUser(user) {
     (0, utils_js_1.safely)(() => (0, hub_js_1.getCurrentScope)().setUser(user));

package/dist/cjs/levels.d.ts

@@ -1,10 +1,13 @@
 import type { Logger } from "./logger.js";
 import type { SentryLevel } from "./types.js";
 export declare const SENTRY_LEVELS: readonly SentryLevel[];
+export declare const LEVEL_RULE = "use 1 to 32 lowercase letters, digits, dots, dashes or underscores";
+export declare const CATEGORY_RULE = "use 1 to 64 lowercase letters, digits, dots, dashes or underscores";
 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;
+export declare function isLevelName(value: unknown): value is string;
+export declare function isCategoryName(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 {

package/dist/cjs/levels.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATEGORY_TAG = exports.LEVEL_TAG = exports.SENTRY_LEVELS = void 0;
+exports.CATEGORY_TAG = exports.LEVEL_TAG = exports.CATEGORY_RULE = exports.LEVEL_RULE = exports.SENTRY_LEVELS = void 0;
 exports.isSentryLevel = isSentryLevel;
-exports.isValidName = isValidName;
+exports.isLevelName = isLevelName;
+exports.isCategoryName = isCategoryName;
 exports.readLevels = readLevels;
 exports.chooseLevel = chooseLevel;
 exports.readCategory = readCategory;
@@ -14,16 +15,26 @@ exports.SENTRY_LEVELS = [
     "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}$/;
+/**
+ * Names of your own: lowercase letters, digits, dots, dashes and
+ * underscores. A level is at most 32 characters, as the server keeps it; a
+ * category at most 64.
+ */
+const LEVEL_RE = /^[a-z0-9._-]{1,32}$/;
+const CATEGORY_RE = /^[a-z0-9._-]{1,64}$/;
+exports.LEVEL_RULE = "use 1 to 32 lowercase letters, digits, dots, dashes or underscores";
+exports.CATEGORY_RULE = "use 1 to 64 lowercase letters, digits, dots, dashes or underscores";
 exports.LEVEL_TAG = "statoss.level";
 exports.CATEGORY_TAG = "statoss.category";
 function isSentryLevel(value) {
     return (typeof value === "string" &&
         exports.SENTRY_LEVELS.includes(value));
 }
-function isValidName(value) {
-    return typeof value === "string" && NAME_RE.test(value);
+function isLevelName(value) {
+    return typeof value === "string" && LEVEL_RE.test(value);
+}
+function isCategoryName(value) {
+    return typeof value === "string" && CATEGORY_RE.test(value);
 }
 /** Keeps the entries of init's `levels` that are usable, logging the rest in debug mode. */
 function readLevels(input, logger) {
@@ -38,8 +49,8 @@ function readLevels(input, logger) {
         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 (!isLevelName(name)) {
+            logger.warn(`Ignored level "${name}" in \`levels\`: ${exports.LEVEL_RULE}.`);
         }
         else if (!isSentryLevel(level)) {
             logger.warn(`Ignored level "${name}" in \`levels\`: map it to fatal, error, warning, info or debug.`);
@@ -60,18 +71,18 @@ function chooseLevel(candidates, levels, fallback, logger) {
             continue;
         if (isSentryLevel(candidate))
             return { level: candidate };
-        if (isValidName(candidate)) {
+        if (isLevelName(candidate)) {
             return { level: levels[candidate] ?? "error", custom: candidate };
         }
-        logger.warn(`Ignored level "${(0, utils_js_1.safeString)(candidate)}": use a Sentry level or 1 to 64 lowercase letters, digits, dots, dashes or underscores.`);
+        logger.warn(`Ignored level "${(0, utils_js_1.safeString)(candidate)}": use a Sentry level or 1 to 32 lowercase letters, digits, dots, dashes or underscores.`);
     }
     return { level: fallback };
 }
 function readCategory(value, logger) {
     if (value === undefined || value === null)
         return undefined;
-    if (isValidName(value))
+    if (isCategoryName(value))
         return value;
-    logger.warn(`Ignored category "${(0, utils_js_1.safeString)(value)}": use 1 to 64 lowercase letters, digits, dots, dashes or underscores.`);
+    logger.warn(`Ignored category "${(0, utils_js_1.safeString)(value)}": ${exports.CATEGORY_RULE}.`);
     return undefined;
 }

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/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.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.2.0";
+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;

package/dist/esm/client.js

@@ -11,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";
@@ -51,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)) {
@@ -100,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)) {
@@ -326,6 +357,7 @@ export class Client {
         const tags = {
             ...scope._tags,
             ...ctx.tags,
+            ...fieldTags(ctx.fields, this.logger),
             ...base.tags,
         };
         if (choice.custom)

package/dist/esm/index.d.ts

@@ -1,5 +1,8 @@
+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, DebugImage, Event, EventHint, Exception, InitOptions, IntegrationToggles, Level, Mechanism, Primitive, RequestInfo, ScopeData, SdkInfo, SentryLevel, StackFrame, Transport, TransportRequest, TransportResponse, User, } from "./types.js";
@@ -7,8 +10,14 @@ export type { Breadcrumb, BreadcrumbHint, CaptureContext, DebugImage, Event, Eve
  * 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));

package/dist/esm/levels.d.ts

@@ -1,10 +1,13 @@
 import type { Logger } from "./logger.js";
 import type { SentryLevel } from "./types.js";
 export declare const SENTRY_LEVELS: readonly SentryLevel[];
+export declare const LEVEL_RULE = "use 1 to 32 lowercase letters, digits, dots, dashes or underscores";
+export declare const CATEGORY_RULE = "use 1 to 64 lowercase letters, digits, dots, dashes or underscores";
 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;
+export declare function isLevelName(value: unknown): value is string;
+export declare function isCategoryName(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 {

package/dist/esm/levels.js

@@ -6,16 +6,26 @@ export const SENTRY_LEVELS = [
     "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}$/;
+/**
+ * Names of your own: lowercase letters, digits, dots, dashes and
+ * underscores. A level is at most 32 characters, as the server keeps it; a
+ * category at most 64.
+ */
+const LEVEL_RE = /^[a-z0-9._-]{1,32}$/;
+const CATEGORY_RE = /^[a-z0-9._-]{1,64}$/;
+export const LEVEL_RULE = "use 1 to 32 lowercase letters, digits, dots, dashes or underscores";
+export const CATEGORY_RULE = "use 1 to 64 lowercase letters, digits, dots, dashes or underscores";
 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);
+export function isLevelName(value) {
+    return typeof value === "string" && LEVEL_RE.test(value);
+}
+export function isCategoryName(value) {
+    return typeof value === "string" && CATEGORY_RE.test(value);
 }
 /** Keeps the entries of init's `levels` that are usable, logging the rest in debug mode. */
 export function readLevels(input, logger) {
@@ -30,8 +40,8 @@ export function readLevels(input, logger) {
         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 (!isLevelName(name)) {
+            logger.warn(`Ignored level "${name}" in \`levels\`: ${LEVEL_RULE}.`);
         }
         else if (!isSentryLevel(level)) {
             logger.warn(`Ignored level "${name}" in \`levels\`: map it to fatal, error, warning, info or debug.`);
@@ -52,18 +62,18 @@ export function chooseLevel(candidates, levels, fallback, logger) {
             continue;
         if (isSentryLevel(candidate))
             return { level: candidate };
-        if (isValidName(candidate)) {
+        if (isLevelName(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.`);
+        logger.warn(`Ignored level "${safeString(candidate)}": use a Sentry level or 1 to 32 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))
+    if (isCategoryName(value))
         return value;
-    logger.warn(`Ignored category "${safeString(value)}": use 1 to 64 lowercase letters, digits, dots, dashes or underscores.`);
+    logger.warn(`Ignored category "${safeString(value)}": ${CATEGORY_RULE}.`);
     return undefined;
 }

package/dist/esm/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/esm/schema.js

@@ -0,0 +1,114 @@
+import { CATEGORY_RULE, isCategoryName, isLevelName, isSentryLevel, LEVEL_RULE, } from "./levels.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";
+}
+/**
+ * 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/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.3.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.3.0";
 export const SDK_PACKAGE = "npm:@statoss/sdk";

package/package.json

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