@docx-editor.dev/telemetry 0.0.1 → 2.29.0

package/dist/pipeline-DbVW7S-K.d.ts

@@ -0,0 +1,223 @@
+import { EditorDiagnostic } from '@docx-editor.dev/core';
+
+/**
+ * The metric catalog: one definition per metric, in OpenTelemetry terms. Prometheus names are
+ * derived from it mechanically by {@link prometheusName}, so the two outputs cannot drift.
+ *
+ * Every label is a bounded enum. No metric carries a room name, a user, or a document.
+ */
+/** How a metric aggregates. @public */
+type MetricKind = 'counter' | 'gauge' | 'histogram';
+/** One metric in the catalog. @public */
+interface MetricDefinition {
+    /** OpenTelemetry name, such as `docx_editor.collab.room.load.duration`. */
+    readonly name: string;
+    readonly kind: MetricKind;
+    /** UCUM unit as OpenTelemetry writes it: `s`, `By`, `1`, or a `{annotation}`. */
+    readonly unit: string;
+    readonly description: string;
+    /** The label keys this metric may carry. Each value is a bounded enum. */
+    readonly labels: readonly string[];
+    /** Histogram bucket upper bounds, in the metric's unit. */
+    readonly buckets?: readonly number[];
+}
+/**
+ * Every metric the package records.
+ *
+ * @example
+ * ```ts
+ * import { METRICS, prometheusName } from '@docx-editor.dev/telemetry';
+ * prometheusName(METRICS.roomLoadDuration); // 'docx_editor_collab_room_load_duration_seconds'
+ * ```
+ *
+ * @public
+ */
+declare const METRICS: Readonly<{
+    documentOpens: MetricDefinition;
+    documentOpenDuration: MetricDefinition;
+    editRejections: MetricDefinition;
+    reviewSkipped: MetricDefinition;
+    fontFailures: MetricDefinition;
+    historyDiagnostics: MetricDefinition;
+    customNodeDiagnostics: MetricDefinition;
+    collabClientStatusTransitions: MetricDefinition;
+    collabClientConnectDuration: MetricDefinition;
+    collabClientParticipants: MetricDefinition;
+    editorInteractionDuration: MetricDefinition;
+    editorLayoutDuration: MetricDefinition;
+    editorPaintDuration: MetricDefinition;
+    droppedEvents: MetricDefinition;
+    roomsActive: MetricDefinition;
+    connectionsActive: MetricDefinition;
+    participantsActive: MetricDefinition;
+    roomParticipants: MetricDefinition;
+    roomParticipantsMax: MetricDefinition;
+    roomMemory: MetricDefinition;
+    roomsMemory: MetricDefinition;
+    roomNodes: MetricDefinition;
+    roomResourceUsage: MetricDefinition;
+    roomAge: MetricDefinition;
+    roomIdle: MetricDefinition;
+    roomLoadDuration: MetricDefinition;
+    roomStoreDuration: MetricDefinition;
+    admissionRejections: MetricDefinition;
+    messageRefusals: MetricDefinition;
+    updates: MetricDefinition;
+    updateBytes: MetricDefinition;
+    roomParticipantsByRoom: MetricDefinition;
+    roomMemoryByRoom: MetricDefinition;
+    migrations: MetricDefinition;
+}>;
+/** A key of {@link METRICS}. @public */
+type MetricId = keyof typeof METRICS;
+/**
+ * The Prometheus name of a metric: dots become underscores, the unit becomes a suffix, and a
+ * counter ends in `_total`, as the OpenTelemetry Prometheus exporter writes it.
+ *
+ * @example
+ * ```ts
+ * prometheusName(METRICS.editRejections); // 'docx_editor_edit_rejections_total'
+ * prometheusName(METRICS.editorInteractionDuration); // 'docx_editor_editor_interaction_duration_seconds'
+ * ```
+ *
+ * @public
+ */
+declare function prometheusName(definition: MetricDefinition): string;
+
+/**
+ * The shared delivery path: consent, the anonymity guard, and exporters that can never throw
+ * into the code they observe. The editor client and the room server both send through it.
+ */
+
+/** A metric attribute or a resource value. @public */
+type AttributeValue = string | number | boolean;
+/** Attributes or resource values, keyed by name. @public */
+type Attributes = Readonly<Record<string, AttributeValue>>;
+/** Context the package adds to every diagnostic before it reaches an exporter. @public */
+interface TelemetryEventContext {
+    /** The fixed hint for the event's code. A constant, never document content. */
+    readonly hint?: string;
+    /** The documentation section for the event's code. */
+    readonly docs?: string;
+    /** The version of the editor packages. Core and this package release together. */
+    readonly engineVersion: string;
+    /**
+     * Present only on a summary: the event that closes a deduplication window repeats the first
+     * one, with the number of identical events folded into it beyond the first. Count it, do not
+     * treat it as a new failure. Its `time` is the first event's. The Sentry exporter records
+     * summaries as breadcrumbs.
+     */
+    readonly repeated?: number;
+    /**
+     * The host's own values from `createTelemetry({ resource })`, such as `service.name`. The
+     * host decides what goes here, and every event carries it.
+     */
+    readonly resource: Attributes;
+    /**
+     * Your identifiers for this event: the client's `attributes`, then the values of the
+     * `moduleFor` module of the editor that sent it, such as a room, a document, or a user.
+     * Empty when you set none. The engine never adds a value here.
+     */
+    readonly attributes: Attributes;
+}
+/** A diagnostic as an exporter receives it. Switch on `kind` to narrow it. @public */
+type TelemetryEvent = EditorDiagnostic & TelemetryEventContext;
+/** One metric measurement. @public */
+interface MetricRecord {
+    readonly definition: MetricDefinition;
+    /** A counter increment, a gauge value, or a histogram sample, in the metric's unit. */
+    readonly value: number;
+    readonly attributes: Attributes;
+}
+/**
+ * Where telemetry goes. Implement `event`, `metric`, or both.
+ *
+ * An exporter never throws into the editor or the server: a failure is caught and reported
+ * once through `onExporterError`.
+ *
+ * @example
+ * ```ts
+ * const toMyLogger: TelemetryExporter = {
+ *   name: 'my-logger',
+ *   event: (event) => myLogger.warn(event.kind, { code: 'code' in event ? event.code : undefined }),
+ * };
+ * ```
+ *
+ * @public
+ */
+interface TelemetryExporter {
+    /** Shown in `onExporterError` reports. */
+    readonly name: string;
+    event?(event: TelemetryEvent): void;
+    metric?(record: MetricRecord): void;
+    /**
+     * Drop a series that no longer exists, such as a closed room's per-room gauge. Optional:
+     * an exporter without it keeps the series until it expires on its own.
+     */
+    forget?(definition: MetricDefinition, attributes: Attributes): void;
+    /**
+     * Start a series at zero before its first measurement. A scraper that sees a counter first
+     * at 1 cannot count that first increase, so the room server declares its known series when
+     * it starts. Optional: an exporter without it creates each series at its first measurement.
+     */
+    declare?(definition: MetricDefinition, attributes: Attributes): void;
+    /** Send anything buffered. Called by `flush()` and when a page is hidden. */
+    flush?(): void | Promise<void>;
+    /** Flush and release resources. Called by `shutdown()`. */
+    shutdown?(): void | Promise<void>;
+    /**
+     * Called once when a telemetry client or room server takes the exporter. An exporter that
+     * holds events, such as a batching one, reads `consented()` before it sends, so events queued
+     * before consent was withdrawn are discarded, not sent.
+     */
+    attach?(context: TelemetryExporterContext): void;
+}
+/** What a telemetry client tells an exporter it takes. @public */
+interface TelemetryExporterContext {
+    /** Whether the host's consent is given, read now. */
+    consented(): boolean;
+    /**
+     * Whether the page is hidden or closing, read now. While it is, a browser exporter sends with
+     * `sendBeacon` or `keepalive`, which still deliver after the page goes away.
+     */
+    pageClosing(): boolean;
+}
+/** Options shared by the editor client and the room server. @public */
+interface TelemetryPipelineOptions {
+    /** Where telemetry goes. Nothing is recorded or sent without at least one exporter. */
+    readonly exporters: readonly TelemetryExporter[];
+    /**
+     * Whether the viewer agreed to telemetry. Read before each event and metric, so a consent
+     * banner can change it at any time. Events before consent are dropped, not buffered.
+     * Defaults to `true`: without this option, events are sent. Pass it whenever your app asks
+     * for consent.
+     *
+     * @example
+     * ```ts
+     * consent: () => window.cookieConsent?.analytics === true
+     * ```
+     */
+    readonly consent?: boolean | (() => boolean);
+    /**
+     * Values added to every event, such as `{ 'service.name': 'contracts-app' }`. Metrics do not
+     * carry them: set resource attributes on your OpenTelemetry SDK or Prometheus target instead.
+     * You own these values: do not put a user, a document, or a room name here.
+     */
+    readonly resource?: Attributes;
+    /** Told once per exporter when it throws. Defaults to one `console.warn`. */
+    readonly onExporterError?: (error: unknown, exporter: string) => void;
+    /**
+     * Keys of your own attributes that may also label metrics, such as `tenant.tier` or
+     * `app.region`. Only for values with few distinct values: each value makes a new series.
+     * After {@link MAX_METRIC_LABEL_VALUES} distinct values of one key, later values become
+     * `other`. Never list a user, document, or room id here; put those on events instead.
+     */
+    readonly metricLabels?: readonly string[];
+}
+/** Distinct values one of your metric labels may take before later values become `other`. @public */
+declare const MAX_METRIC_LABEL_VALUES = 50;
+/** The version of the editor packages, or `'development'` when running from source. @public */
+declare const ENGINE_VERSION: string;
+
+export { ENGINE_VERSION as E, MAX_METRIC_LABEL_VALUES as d, METRICS as e, prometheusName as p };
+export type { Attributes as A, MetricRecord as M, TelemetryPipelineOptions as T, TelemetryEvent as a, TelemetryExporter as b, AttributeValue as c, MetricDefinition as f, MetricId as g, MetricKind as h, TelemetryEventContext as i, TelemetryExporterContext as j };

package/dist/prometheus/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunkMJX3ECH3_cjs=require('../chunk-MJX3ECH3.cjs');require('../chunk-LGNT4I5W.cjs');Object.defineProperty(exports,"PROMETHEUS_CONTENT_TYPE",{enumerable:true,get:function(){return chunkMJX3ECH3_cjs.a}});Object.defineProperty(exports,"fetchMetricsHandler",{enumerable:true,get:function(){return chunkMJX3ECH3_cjs.d}});Object.defineProperty(exports,"metricsHandler",{enumerable:true,get:function(){return chunkMJX3ECH3_cjs.c}});Object.defineProperty(exports,"prometheusRegistry",{enumerable:true,get:function(){return chunkMJX3ECH3_cjs.b}});

package/dist/prometheus/index.d.cts

@@ -0,0 +1,88 @@
+/**
+ * Prometheus: an in-process registry in the text exposition format, and `/metrics` handlers for
+ * Node-style servers ({@link metricsHandler}) and Fetch-style servers
+ * ({@link fetchMetricsHandler}). No dependency on `prom-client`; a `prom-client` registry
+ * merges into the same endpoint.
+ *
+ * @packageDocumentation
+ */
+import { b as TelemetryExporter } from '../pipeline-DbVW7S-K.cjs';
+import '@docx-editor.dev/core';
+
+/** The Prometheus text exposition content type. @public */
+declare const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/** Anything that renders Prometheus text, such as a `prom-client` `Registry`. @public */
+interface PrometheusTextSource {
+    metrics(): string | Promise<string>;
+}
+/** The exporter returned by {@link prometheusRegistry}. @public */
+interface PrometheusRegistry extends TelemetryExporter, PrometheusTextSource {
+    /** Every recorded metric in the Prometheus text format. */
+    metrics(): string;
+    /** Forget every recorded value. */
+    reset(): void;
+}
+/**
+ * Collect metrics in memory and render them for Prometheus to scrape.
+ *
+ * @example
+ * ```ts
+ * import { prometheusRegistry, metricsHandler } from '@docx-editor.dev/telemetry/prometheus';
+ *
+ * const metrics = prometheusRegistry();
+ * // Pass `metrics` as an exporter, then serve it:
+ * app.get('/metrics', metricsHandler(metrics));
+ * ```
+ *
+ * @public
+ */
+declare function prometheusRegistry(): PrometheusRegistry;
+/** The part of a Node `ServerResponse` the handler writes to. @public */
+interface NodeResponseLike {
+    setHeader(name: string, value: string): unknown;
+    end(body: string): unknown;
+    statusCode?: number;
+}
+/** Options for {@link metricsHandler} and {@link fetchMetricsHandler}. @public */
+interface MetricsHandlerOptions {
+    /**
+     * More sources rendered into the same response, such as your `prom-client` registry:
+     * `merge: [register]`.
+     */
+    readonly merge?: readonly PrometheusTextSource[];
+}
+/**
+ * A Node-style handler, `(request, response)`, for Node `http`, Express, and Koa
+ * (`ctx.res`). For Fastify, hijack the reply and pass `reply.raw`. For Fetch-style servers,
+ * use {@link fetchMetricsHandler}. Protect the route as you protect other operational
+ * endpoints.
+ *
+ * @example
+ * ```ts
+ * app.get('/metrics', metricsHandler(metrics, { merge: [promClient.register] })); // Express
+ *
+ * fastify.get('/metrics', (request, reply) => {
+ *   reply.hijack();
+ *   return metricsHandler(metrics)(request.raw, reply.raw);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function metricsHandler(registry: PrometheusTextSource, options?: MetricsHandlerOptions): (request: unknown, response: NodeResponseLike) => Promise<void>;
+/**
+ * A Fetch-style handler that returns a `Response`, for Next.js route handlers, Hono, Bun,
+ * Deno, and workers. It ignores its argument, so a Hono context works as well as a `Request`.
+ *
+ * @example
+ * ```ts
+ * // app/metrics/route.ts
+ * export const GET = fetchMetricsHandler(metrics);
+ * ```
+ *
+ * @public
+ */
+declare function fetchMetricsHandler(registry: PrometheusTextSource, options?: MetricsHandlerOptions): (request?: unknown) => Promise<Response>;
+
+export { PROMETHEUS_CONTENT_TYPE, TelemetryExporter, fetchMetricsHandler, metricsHandler, prometheusRegistry };
+export type { MetricsHandlerOptions, NodeResponseLike, PrometheusRegistry, PrometheusTextSource };

package/dist/prometheus/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Prometheus: an in-process registry in the text exposition format, and `/metrics` handlers for
+ * Node-style servers ({@link metricsHandler}) and Fetch-style servers
+ * ({@link fetchMetricsHandler}). No dependency on `prom-client`; a `prom-client` registry
+ * merges into the same endpoint.
+ *
+ * @packageDocumentation
+ */
+import { b as TelemetryExporter } from '../pipeline-DbVW7S-K.js';
+import '@docx-editor.dev/core';
+
+/** The Prometheus text exposition content type. @public */
+declare const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/** Anything that renders Prometheus text, such as a `prom-client` `Registry`. @public */
+interface PrometheusTextSource {
+    metrics(): string | Promise<string>;
+}
+/** The exporter returned by {@link prometheusRegistry}. @public */
+interface PrometheusRegistry extends TelemetryExporter, PrometheusTextSource {
+    /** Every recorded metric in the Prometheus text format. */
+    metrics(): string;
+    /** Forget every recorded value. */
+    reset(): void;
+}
+/**
+ * Collect metrics in memory and render them for Prometheus to scrape.
+ *
+ * @example
+ * ```ts
+ * import { prometheusRegistry, metricsHandler } from '@docx-editor.dev/telemetry/prometheus';
+ *
+ * const metrics = prometheusRegistry();
+ * // Pass `metrics` as an exporter, then serve it:
+ * app.get('/metrics', metricsHandler(metrics));
+ * ```
+ *
+ * @public
+ */
+declare function prometheusRegistry(): PrometheusRegistry;
+/** The part of a Node `ServerResponse` the handler writes to. @public */
+interface NodeResponseLike {
+    setHeader(name: string, value: string): unknown;
+    end(body: string): unknown;
+    statusCode?: number;
+}
+/** Options for {@link metricsHandler} and {@link fetchMetricsHandler}. @public */
+interface MetricsHandlerOptions {
+    /**
+     * More sources rendered into the same response, such as your `prom-client` registry:
+     * `merge: [register]`.
+     */
+    readonly merge?: readonly PrometheusTextSource[];
+}
+/**
+ * A Node-style handler, `(request, response)`, for Node `http`, Express, and Koa
+ * (`ctx.res`). For Fastify, hijack the reply and pass `reply.raw`. For Fetch-style servers,
+ * use {@link fetchMetricsHandler}. Protect the route as you protect other operational
+ * endpoints.
+ *
+ * @example
+ * ```ts
+ * app.get('/metrics', metricsHandler(metrics, { merge: [promClient.register] })); // Express
+ *
+ * fastify.get('/metrics', (request, reply) => {
+ *   reply.hijack();
+ *   return metricsHandler(metrics)(request.raw, reply.raw);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function metricsHandler(registry: PrometheusTextSource, options?: MetricsHandlerOptions): (request: unknown, response: NodeResponseLike) => Promise<void>;
+/**
+ * A Fetch-style handler that returns a `Response`, for Next.js route handlers, Hono, Bun,
+ * Deno, and workers. It ignores its argument, so a Hono context works as well as a `Request`.
+ *
+ * @example
+ * ```ts
+ * // app/metrics/route.ts
+ * export const GET = fetchMetricsHandler(metrics);
+ * ```
+ *
+ * @public
+ */
+declare function fetchMetricsHandler(registry: PrometheusTextSource, options?: MetricsHandlerOptions): (request?: unknown) => Promise<Response>;
+
+export { PROMETHEUS_CONTENT_TYPE, TelemetryExporter, fetchMetricsHandler, metricsHandler, prometheusRegistry };
+export type { MetricsHandlerOptions, NodeResponseLike, PrometheusRegistry, PrometheusTextSource };

package/dist/prometheus/index.js

@@ -0,0 +1 @@
+export{a as PROMETHEUS_CONTENT_TYPE,d as fetchMetricsHandler,c as metricsHandler,b as prometheusRegistry}from'../chunk-LFX65QJG.js';import'../chunk-73YEPWY5.js';

package/dist/sentry/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunkUK2MNJCG_cjs=require('../chunk-UK2MNJCG.cjs');var i=class extends Error{name="DocxEditorDiagnosticError";code;constructor(r,t){super(t?`${r}: ${t}`:r),this.code=r;}},u=new Set(["collab.authentication-failed","collab.room-generation-changed"]),l=new Set(["open.failed","open.unsupported-source","open.invalid-limits"]),f=Object.freeze([".docx-editor",".docx-pages"]);function x(e,r){return e.category?.startsWith("ui.")&&g(r?.event?.target)?null:e}function g(e){try{let r=e;return r&&typeof r.closest!="function"&&(r=r.parentElement),!r||typeof r.closest!="function"?!0:r.closest(f.join(", "))!=null}catch{return  true}}function p(e){switch(e.kind){case "document.open":return e.outcome==="rejected"&&l.has(e.code);case "edit.rejected":return e.code==="edit.internal-invariant";case "review.skipped":return e.code==="review.revision-unsupported"||e.code==="review.retained-structure";case "font.failed":return e.code==="font.shaper-unavailable";case "collab.status":return e.status==="error"&&!e.recovering&&!u.has(e.code??"");default:return  false}}function m(e){return e.kind==="document.open"?e.outcome==="opened":e.kind==="performance"&&e.code===void 0}function c(e){return "code"in e&&e.code?e.code:e.kind}function y(e){let r=e,t={"docx_editor.kind":e.kind,"docx_editor.code":c(e),"docx_editor.version":e.engineVersion,"docx_editor.editor_session":e.editorSessionId};for(let[o,n]of [["origin","origin"],["tracked","tracked"],["status","status"],["outcome","outcome"],["command","command"],["cause","cause"],["part","part"],["errorName","error_name"],["stage","stage"],["operation","operation"],["changeKind","change_kind"],["formattingKind","formatting_kind"]])r[o]!==void 0&&(t[`docx_editor.${n}`]=String(r[o]));for(let[o,n]of Object.entries(e.attributes??{}))t[o]=String(n);return t}function k(e,r){let t=e,o=["cause","errorName","stage","changeKind","formattingKind"].map(n=>t[n]).filter(n=>typeof n=="string");return ["docx-editor",e.kind,r,...o]}function d(e){let{resource:r,...t}=e;return {...t,...Object.keys(r).length?{resource:r}:{}}}function b(e,r={}){let t=r.issue??p,o=r.breadcrumbs??true;return {name:"sentry",event(n){let s=c(n);if(n.repeated===void 0&&t(n)){e.captureException(new i(s,n.hint),{fingerprint:k(n,s),level:n.kind==="font.failed"||n.kind==="review.skipped"?"warning":"error",tags:y(n),contexts:{docx_editor:d(n)}});return}o&&e.addBreadcrumb({category:"docx-editor",message:chunkUK2MNJCG_cjs.b(n),level:m(n)?"info":"warning",data:d(n)});},async flush(){await e.flush?.(2e3);}}}exports.DocxEditorDiagnosticError=i;exports.EDITOR_SELECTORS=f;exports.dropEditorBreadcrumbs=x;exports.isSentryIssue=p;exports.sentryExporter=b;

package/dist/sentry/index.d.cts

@@ -0,0 +1,134 @@
+/**
+ * Sentry: actionable failures become issues grouped by code; everything else becomes a
+ * breadcrumb, so it appears beside your own errors without using your event quota.
+ *
+ * @packageDocumentation
+ */
+import { a as TelemetryEvent, b as TelemetryExporter } from '../pipeline-DbVW7S-K.cjs';
+import '@docx-editor.dev/core';
+
+/** Sentry severity, as the Sentry SDKs spell it. @public */
+type SentrySeverity = 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+/**
+ * The part of a Sentry SDK the exporter uses. `@sentry/browser`, `@sentry/react`,
+ * `@sentry/vue`, `@sentry/nextjs`, and `@sentry/node` all fit: pass the module itself.
+ *
+ * @public
+ */
+interface SentryLike {
+    captureException(exception: unknown, context?: {
+        readonly fingerprint?: string[];
+        readonly level?: SentrySeverity;
+        readonly tags?: Record<string, string>;
+        readonly contexts?: Record<string, Record<string, unknown>>;
+    }): unknown;
+    addBreadcrumb(breadcrumb: {
+        readonly category?: string;
+        readonly message?: string;
+        readonly level?: SentrySeverity;
+        readonly data?: Record<string, unknown>;
+    }): void;
+    /** Send queued events. Called when the page is hidden. */
+    flush?(timeout?: number): PromiseLike<boolean>;
+}
+/** Options for {@link sentryExporter}. @public */
+interface SentryExporterOptions {
+    /**
+     * Which events become Sentry issues. The rest become breadcrumbs. The default sends an issue
+     * when the app can act: an open refused because the app passed something wrong or for an
+     * unknown reason, a collaboration error that will not heal, a text shaper that did not load,
+     * and an engine invariant. A corrupt or oversized file and a refused keystroke are
+     * breadcrumbs.
+     */
+    readonly issue?: (event: TelemetryEvent) => boolean;
+    /** Record breadcrumbs for the other events. Defaults to `true`. */
+    readonly breadcrumbs?: boolean;
+}
+/**
+ * The error a Sentry issue is made from. The message is the code, so issues group by cause,
+ * and the stack trace contains no document data.
+ *
+ * @public
+ */
+declare class DocxEditorDiagnosticError extends Error {
+    readonly name = "DocxEditorDiagnosticError";
+    readonly code: string;
+    constructor(code: string, hint?: string);
+}
+/**
+ * CSS selectors for everything that shows the document: the editor shell and the painted pages.
+ * Pass them to Session Replay's `block` option, which replaces the editor with a placeholder, so
+ * `mask` is not needed as well.
+ *
+ * @public
+ */
+declare const EDITOR_SELECTORS: readonly string[];
+/** A Sentry breadcrumb, as `beforeBreadcrumb` receives it. @public */
+interface SentryBreadcrumbLike {
+    readonly category?: string;
+}
+/** The hint Sentry passes with a breadcrumb. For a click or key press, `event` is the DOM event. @public */
+interface SentryBreadcrumbHintLike {
+    readonly event?: unknown;
+}
+/**
+ * A `beforeBreadcrumb` filter that drops Sentry's click and key press breadcrumbs from inside the
+ * editor. Sentry describes the element a person clicked with its `alt`, `title`, and
+ * `aria-label` values. Inside the editor, those values come from the document: picture
+ * descriptions, link tooltips, and content control names. A `ui` breadcrumb whose element is
+ * unknown is dropped too. Other breadcrumbs pass unchanged.
+ *
+ * @example
+ * ```ts
+ * Sentry.init({ dsn, beforeBreadcrumb: dropEditorBreadcrumbs });
+ * // With a filter of your own:
+ * Sentry.init({
+ *   dsn,
+ *   beforeBreadcrumb: (crumb, hint) => {
+ *     const kept = dropEditorBreadcrumbs(crumb, hint);
+ *     return kept && myFilter(kept, hint); // dropped breadcrumbs never reach your filter
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function dropEditorBreadcrumbs<B extends SentryBreadcrumbLike>(breadcrumb: B, hint?: SentryBreadcrumbHintLike): B | null;
+/**
+ * The default issue rule: an open the app caused, an internal error, a shaper that never
+ * loaded, and a collaboration error that will not heal become issues. Wrap it to add your own.
+ *
+ * @example
+ * ```ts
+ * sentryExporter(Sentry, {
+ *   issue: (event) =>
+ *     isSentryIssue(event) || ('code' in event && event.code === 'font.load-failed'),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function isSentryIssue(event: TelemetryEvent): boolean;
+/**
+ * Send diagnostics to Sentry.
+ *
+ * Sentry Session Replay records the page, and the page shows the document. Block the editor in
+ * Replay, so neither its text nor its pictures are recorded, and drop the click breadcrumbs that
+ * describe its elements: `Sentry.replayIntegration({ block: [...EDITOR_SELECTORS] })` and
+ * `beforeBreadcrumb: dropEditorBreadcrumbs`.
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from '@sentry/react';
+ * import { createTelemetry } from '@docx-editor.dev/telemetry';
+ * import { sentryExporter } from '@docx-editor.dev/telemetry/sentry';
+ *
+ * export const telemetry = createTelemetry({ exporters: [sentryExporter(Sentry)] });
+ * ```
+ *
+ * @public
+ */
+declare function sentryExporter(sentry: SentryLike, options?: SentryExporterOptions): TelemetryExporter;
+
+export { DocxEditorDiagnosticError, EDITOR_SELECTORS, TelemetryEvent, TelemetryExporter, dropEditorBreadcrumbs, isSentryIssue, sentryExporter };
+export type { SentryBreadcrumbHintLike, SentryBreadcrumbLike, SentryExporterOptions, SentryLike, SentrySeverity };

package/dist/sentry/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Sentry: actionable failures become issues grouped by code; everything else becomes a
+ * breadcrumb, so it appears beside your own errors without using your event quota.
+ *
+ * @packageDocumentation
+ */
+import { a as TelemetryEvent, b as TelemetryExporter } from '../pipeline-DbVW7S-K.js';
+import '@docx-editor.dev/core';
+
+/** Sentry severity, as the Sentry SDKs spell it. @public */
+type SentrySeverity = 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+/**
+ * The part of a Sentry SDK the exporter uses. `@sentry/browser`, `@sentry/react`,
+ * `@sentry/vue`, `@sentry/nextjs`, and `@sentry/node` all fit: pass the module itself.
+ *
+ * @public
+ */
+interface SentryLike {
+    captureException(exception: unknown, context?: {
+        readonly fingerprint?: string[];
+        readonly level?: SentrySeverity;
+        readonly tags?: Record<string, string>;
+        readonly contexts?: Record<string, Record<string, unknown>>;
+    }): unknown;
+    addBreadcrumb(breadcrumb: {
+        readonly category?: string;
+        readonly message?: string;
+        readonly level?: SentrySeverity;
+        readonly data?: Record<string, unknown>;
+    }): void;
+    /** Send queued events. Called when the page is hidden. */
+    flush?(timeout?: number): PromiseLike<boolean>;
+}
+/** Options for {@link sentryExporter}. @public */
+interface SentryExporterOptions {
+    /**
+     * Which events become Sentry issues. The rest become breadcrumbs. The default sends an issue
+     * when the app can act: an open refused because the app passed something wrong or for an
+     * unknown reason, a collaboration error that will not heal, a text shaper that did not load,
+     * and an engine invariant. A corrupt or oversized file and a refused keystroke are
+     * breadcrumbs.
+     */
+    readonly issue?: (event: TelemetryEvent) => boolean;
+    /** Record breadcrumbs for the other events. Defaults to `true`. */
+    readonly breadcrumbs?: boolean;
+}
+/**
+ * The error a Sentry issue is made from. The message is the code, so issues group by cause,
+ * and the stack trace contains no document data.
+ *
+ * @public
+ */
+declare class DocxEditorDiagnosticError extends Error {
+    readonly name = "DocxEditorDiagnosticError";
+    readonly code: string;
+    constructor(code: string, hint?: string);
+}
+/**
+ * CSS selectors for everything that shows the document: the editor shell and the painted pages.
+ * Pass them to Session Replay's `block` option, which replaces the editor with a placeholder, so
+ * `mask` is not needed as well.
+ *
+ * @public
+ */
+declare const EDITOR_SELECTORS: readonly string[];
+/** A Sentry breadcrumb, as `beforeBreadcrumb` receives it. @public */
+interface SentryBreadcrumbLike {
+    readonly category?: string;
+}
+/** The hint Sentry passes with a breadcrumb. For a click or key press, `event` is the DOM event. @public */
+interface SentryBreadcrumbHintLike {
+    readonly event?: unknown;
+}
+/**
+ * A `beforeBreadcrumb` filter that drops Sentry's click and key press breadcrumbs from inside the
+ * editor. Sentry describes the element a person clicked with its `alt`, `title`, and
+ * `aria-label` values. Inside the editor, those values come from the document: picture
+ * descriptions, link tooltips, and content control names. A `ui` breadcrumb whose element is
+ * unknown is dropped too. Other breadcrumbs pass unchanged.
+ *
+ * @example
+ * ```ts
+ * Sentry.init({ dsn, beforeBreadcrumb: dropEditorBreadcrumbs });
+ * // With a filter of your own:
+ * Sentry.init({
+ *   dsn,
+ *   beforeBreadcrumb: (crumb, hint) => {
+ *     const kept = dropEditorBreadcrumbs(crumb, hint);
+ *     return kept && myFilter(kept, hint); // dropped breadcrumbs never reach your filter
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function dropEditorBreadcrumbs<B extends SentryBreadcrumbLike>(breadcrumb: B, hint?: SentryBreadcrumbHintLike): B | null;
+/**
+ * The default issue rule: an open the app caused, an internal error, a shaper that never
+ * loaded, and a collaboration error that will not heal become issues. Wrap it to add your own.
+ *
+ * @example
+ * ```ts
+ * sentryExporter(Sentry, {
+ *   issue: (event) =>
+ *     isSentryIssue(event) || ('code' in event && event.code === 'font.load-failed'),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function isSentryIssue(event: TelemetryEvent): boolean;
+/**
+ * Send diagnostics to Sentry.
+ *
+ * Sentry Session Replay records the page, and the page shows the document. Block the editor in
+ * Replay, so neither its text nor its pictures are recorded, and drop the click breadcrumbs that
+ * describe its elements: `Sentry.replayIntegration({ block: [...EDITOR_SELECTORS] })` and
+ * `beforeBreadcrumb: dropEditorBreadcrumbs`.
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from '@sentry/react';
+ * import { createTelemetry } from '@docx-editor.dev/telemetry';
+ * import { sentryExporter } from '@docx-editor.dev/telemetry/sentry';
+ *
+ * export const telemetry = createTelemetry({ exporters: [sentryExporter(Sentry)] });
+ * ```
+ *
+ * @public
+ */
+declare function sentryExporter(sentry: SentryLike, options?: SentryExporterOptions): TelemetryExporter;
+
+export { DocxEditorDiagnosticError, EDITOR_SELECTORS, TelemetryEvent, TelemetryExporter, dropEditorBreadcrumbs, isSentryIssue, sentryExporter };
+export type { SentryBreadcrumbHintLike, SentryBreadcrumbLike, SentryExporterOptions, SentryLike, SentrySeverity };