@docx-editor.dev/telemetry 0.0.0-stage → 2.29.0

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 };

package/dist/sentry/index.js

@@ -0,0 +1 @@
+import {b as b$1}from'../chunk-NUN46EXH.js';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:b$1(n),level:m(n)?"info":"warning",data:d(n)});},async flush(){await e.flush?.(2e3);}}}export{i as DocxEditorDiagnosticError,f as EDITOR_SELECTORS,x as dropEditorBreadcrumbs,p as isSentryIssue,b as sentryExporter};

package/dist/server/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunk7ZXJ6HP2_cjs=require('../chunk-7ZXJ6HP2.cjs');require('../chunk-U6ERFNUM.cjs'),require('../chunk-LGNT4I5W.cjs'),require('../chunk-LFQSY2TD.cjs'),require('../chunk-WGWKNKUT.cjs');Object.defineProperty(exports,"hmacRoomLabel",{enumerable:true,get:function(){return chunk7ZXJ6HP2_cjs.a}});Object.defineProperty(exports,"roomTelemetry",{enumerable:true,get:function(){return chunk7ZXJ6HP2_cjs.b}});

package/dist/server/index.d.cts

@@ -0,0 +1,156 @@
+/**
+ * Room telemetry for any Yjs collaboration server: rooms, connections, the people in each
+ * room, the memory each room holds, and why connections and messages were refused.
+ *
+ * No metric carries a room name. Per-room detail is in {@link RoomTelemetry.list}, for an
+ * admin endpoint you protect.
+ *
+ * @packageDocumentation
+ */
+import * as Y from 'yjs';
+import { T as TelemetryPipelineOptions } from '../pipeline-DbVW7S-K.cjs';
+export { b as TelemetryExporter } from '../pipeline-DbVW7S-K.cjs';
+import '@docx-editor.dev/core';
+
+/** The part of a `y-protocols` `Awareness` the telemetry reads. @public */
+interface AwarenessLike {
+    getStates(): Map<number, unknown>;
+    on(event: 'change', listener: (...args: unknown[]) => void): void;
+    off(event: 'change', listener: (...args: unknown[]) => void): void;
+}
+/** Options for {@link roomTelemetry}. @public */
+interface RoomTelemetryOptions extends TelemetryPipelineOptions {
+    /**
+     * How often to sample people, memory, and room size, in milliseconds. Defaults to 60 000.
+     * `false` turns the timer off; call `sample()` yourself, for example before each scrape.
+     */
+    readonly sampleInterval?: number | false;
+    /**
+     * Measure each room's encoded Yjs state. This encodes the room once per sample, and only when
+     * it changed since the last one. Defaults to `true`.
+     */
+    readonly measureState?: boolean;
+    /**
+     * How a room appears in {@link RoomTelemetry.list}. Defaults to an index that is valid only
+     * inside this process, such as `room-3`. Use `(name) => name` to see real names, or
+     * {@link hmacRoomLabel} for a stable label that does not reveal the name.
+     */
+    readonly roomLabel?: (name: string) => string;
+    /**
+     * Also record each room's people and memory as gauges labeled `room`. Off by default: a label
+     * per room makes one series per room, and a large server has many rooms. A closed room's
+     * series is dropped. Only the default label or `hmacRoomLabel` is accepted, so no room name
+     * can become a label; any other `roomLabel` throws.
+     */
+    readonly perRoomSeries?: boolean;
+    /**
+     * Your own reading of a refusal, for errors whose `reason` or `code` is free text. Return a
+     * common reason such as `unauthorized`, a collaboration failure code, or one of `reasons`;
+     * anything else is counted as `other`. Return undefined to use the default reading.
+     */
+    readonly reasonOf?: (error: unknown) => string | undefined;
+    /**
+     * Refusal reasons to keep as metric labels. Compared without case and recorded in lowercase. Collaboration failure codes are always kept.
+     * Any other reason is counted as `other`, so a free-text error never becomes a time series.
+     */
+    readonly reasons?: readonly string[];
+}
+/** One room in {@link RoomTelemetry.list}. @public */
+interface RoomStats {
+    readonly room: string;
+    /** People present, from awareness states. A person with two tabs counts twice. */
+    readonly participants: number;
+    readonly connections: number;
+    /** Encoded Yjs state at the last sample, or `null` before the first one. */
+    readonly stateBytes: number | null;
+    readonly blobBytes: number | null;
+    /** Bytes of updates applied since the room was last stored. */
+    readonly pendingBytes: number;
+    readonly nodes: number | null;
+    /** The largest share of any room limit in use, from 0 to 1. */
+    readonly limitRatio: number | null;
+    readonly ageSeconds: number;
+    readonly idleSeconds: number;
+}
+/** What a timed room operation is. @public */
+type RoomOperation = 'load' | 'store';
+/** Records a started operation's duration with its outcome. Later calls do nothing. @public */
+type SettleOperation = (outcome: 'success' | 'failure') => void;
+/** One open room. Returned by {@link RoomTelemetry.open}. @public */
+interface RoomHandle {
+    /** The room's label, as {@link RoomTelemetryOptions.roomLabel} made it. */
+    readonly label: string;
+    /** Run `operation` and record its duration and outcome. Rethrows its error. */
+    time<T>(operation: RoomOperation, run: () => T | Promise<T>): Promise<T>;
+    /** Start timing `operation` where `time` cannot wrap it; call the result once it settles. */
+    begin(operation: RoomOperation): SettleOperation;
+    connected(): void;
+    disconnected(): void;
+    /** Stop tracking the room, for example when the server unloads it. */
+    close(): void;
+}
+/** Room telemetry for one server process. @public */
+interface RoomTelemetry {
+    /**
+     * Start tracking a loaded room. Pass the room's awareness to count people; without it the
+     * number of connections stands in.
+     */
+    open(doc: Y.Doc, options?: {
+        readonly name?: string;
+        readonly awareness?: AwarenessLike;
+    }): RoomHandle;
+    /** A connection refused at admission. `reason` can be a string or an error with `reason`. */
+    rejected(reason: unknown): void;
+    /** A message refused before it applied, such as `room-generation-changed`. */
+    refused(reason: unknown): void;
+    /** A room migration finished. */
+    migrated(outcome: 'migrated' | 'unchanged' | 'failed'): void;
+    /** Time an operation that happens before the room is open, such as a load that fails. */
+    time<T>(operation: RoomOperation, run: () => T | Promise<T>): Promise<T>;
+    /** Start timing an operation that has no room yet; call the result once it settles. */
+    begin(operation: RoomOperation): SettleOperation;
+    /** Every open room, for an admin endpoint you protect. */
+    list(): readonly RoomStats[];
+    /** Sample people, memory, and size now. */
+    sample(): void;
+    flush(): Promise<void>;
+    /** Stop the timer, close every room, and shut the exporters down. */
+    shutdown(): Promise<void>;
+}
+/**
+ * A stable room label that does not reveal the name: an HMAC of the name with your secret.
+ * The same name gives the same label across processes and restarts.
+ *
+ * @example
+ * ```ts
+ * const rooms = roomTelemetry({
+ *   exporters: [metrics],
+ *   roomLabel: hmacRoomLabel(process.env.ROOM_LABEL_SECRET),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function hmacRoomLabel(secret: string | undefined): (name: string) => string;
+/**
+ * Track rooms on a Yjs server.
+ *
+ * @example
+ * ```ts
+ * import { roomTelemetry } from '@docx-editor.dev/telemetry/server';
+ * import { prometheusRegistry, metricsHandler } from '@docx-editor.dev/telemetry/prometheus';
+ *
+ * const metrics = prometheusRegistry();
+ * const rooms = roomTelemetry({ exporters: [metrics] });
+ *
+ * const room = rooms.open(ydoc, { name, awareness });
+ * await room.time('load', () => loadRoom(ydoc)); // the loaded state is not counted as edits
+ * room.connected();
+ * ```
+ *
+ * @public
+ */
+declare function roomTelemetry(options: RoomTelemetryOptions): RoomTelemetry;
+
+export { TelemetryPipelineOptions, hmacRoomLabel, roomTelemetry };
+export type { AwarenessLike, RoomHandle, RoomOperation, RoomStats, RoomTelemetry, RoomTelemetryOptions, SettleOperation };