@docx-editor.dev/telemetry 0.0.1 → 2.29.0

package/dist/index.d.cts

@@ -0,0 +1,332 @@
+/**
+ * Anonymous diagnostics, metrics, and error reporting for editors and collaboration servers.
+ *
+ * - `@docx-editor.dev/telemetry`: {@link createTelemetry} for editors, the console, callback,
+ *   memory, and HTTP exporters, and {@link browserPrivacySignals}.
+ * - `@docx-editor.dev/telemetry/ingest`: a route that receives telemetry from `httpExporter`
+ *   and forwards it to a log service.
+ * - `@docx-editor.dev/telemetry/otel`: OpenTelemetry metrics and traces through your SDK.
+ * - `@docx-editor.dev/telemetry/sentry`: Sentry issues and breadcrumbs.
+ * - `@docx-editor.dev/telemetry/prometheus`: a `/metrics` endpoint.
+ * - `@docx-editor.dev/telemetry/server`: room telemetry for any Yjs server.
+ * - `@docx-editor.dev/telemetry/hocuspocus`: room telemetry for Hocuspocus in one call.
+ *
+ * @packageDocumentation
+ */
+import { EditorModule, EditorDiagnostic } from '@docx-editor.dev/core';
+export { ByteSizeBucket, CollaborationDiagnosticCode, CollaborationParticipantsDiagnostic, CollaborationStatusDiagnostic, CountBucket, CustomNodeDiagnosticCode, CustomNodeDiagnosticEvent, DiagnosticBase, DiagnosticCode, DiagnosticErrorName, DiagnosticExplanation, DiagnosticFailureDetail, DocumentOpenDiagnostic, DocumentOpenDiagnosticCode, DocumentPartKind, DocumentShape, EditDiagnosticCode, EditRejectedDiagnostic, EditRejectionOrigin, EditorDiagnostic, EditorDiagnosticKind, FailureStage, FontDiagnosticCode, FontFailedDiagnostic, FormattingChangeKind, HistoryDiagnosticCode, HistoryDiagnosticEvent, PerformanceDiagnostic, PerformanceDiagnosticCode, ReviewChangeKind, ReviewDiagnosticCode, ReviewOperation, ReviewSkippedDiagnostic, TimingSummary, explainDiagnostic } from '@docx-editor.dev/core';
+import { A as Attributes, T as TelemetryPipelineOptions, a as TelemetryEvent, b as TelemetryExporter, M as MetricRecord } from './pipeline-DbVW7S-K.cjs';
+export { c as AttributeValue, E as ENGINE_VERSION, d as MAX_METRIC_LABEL_VALUES, e as METRICS, f as MetricDefinition, g as MetricId, h as MetricKind, i as TelemetryEventContext, j as TelemetryExporterContext, p as prometheusName } from './pipeline-DbVW7S-K.cjs';
+
+/**
+ * The areas you can switch on. Each one selects diagnostic kinds:
+ *
+ * - `documentOpen`: documents opened and refused (`document.open`).
+ * - `editing`: edits and commands refused while changes are not tracked (`edit.rejected`).
+ * - `trackedChanges`: refusals while suggesting, refusals about tracking itself, and skipped
+ *   tracked changes
+ *   (`edit.rejected` with `tracked: true`, `review.skipped`).
+ * - `fonts`: fonts that failed and were substituted (`font.failed`).
+ * - `history`: undo steps that did not group as the gesture intended (`history`).
+ * - `customNodes`: custom node payloads that could not be read (`custom-node`).
+ * - `collaborationClient`: collaboration status changes and room size (`collab.*`).
+ * - `performance`: how fast the editor responds: key presses and clicks to the next frame,
+ *   and engine layout and paint times, as one summary per minute of use (`performance`).
+ *
+ * @public
+ */
+type TelemetryArea = 'documentOpen' | 'editing' | 'trackedChanges' | 'fonts' | 'history' | 'customNodes' | 'collaborationClient' | 'performance';
+/** Options for one area. @public */
+interface TelemetryAreaOptions {
+    /**
+     * Share of events to send, from 0 to 1. Metrics count every event, except that a
+     * `performance` rate of 0 turns performance off, metrics included. Defaults to 1.
+     * Each event is sampled on its own, except in `performance`: there the choice is made once
+     * for each editor, which sends all of its summaries or none.
+     */
+    readonly sampleRate?: number;
+}
+/** Which areas to record. An area that is absent or `false` records nothing. @public */
+type TelemetryInclude = {
+    readonly [A in TelemetryArea]?: boolean | TelemetryAreaOptions;
+};
+/** Options for {@link createTelemetry}. @public */
+interface TelemetryOptions extends TelemetryPipelineOptions {
+    /**
+     * The areas to record. Omitted, every area is on.
+     *
+     * @example
+     * ```ts
+     * include: { documentOpen: true, trackedChanges: true, editing: { sampleRate: 0.2 } }
+     * ```
+     */
+    readonly include?: TelemetryInclude;
+    /**
+     * Identical refusals inside this window are sent once, then summarized with `repeated`.
+     * Holding Backspace on a locked drawing is one event, not hundreds. Defaults to 10 000 ms.
+     * Set 0 to send every event.
+     */
+    readonly dedupeWindowMs?: number;
+    /**
+     * How much of an opened document's shape to send. `'basic'`, the default, sends the size and
+     * page buckets. `'detailed'` also sends part, paragraph, review item, and embedded font
+     * buckets: useful to group open times, but several counts together describe a document more
+     * closely, so ask for it only when you need it.
+     */
+    readonly documentShape?: 'basic' | 'detailed';
+    /**
+     * Your identifiers on every event, such as a tenant or a pseudonymous user id. A function is
+     * read at each event, so it can follow sign-in and tenant switches. Events only: to label
+     * metrics with a key, list it in `metricLabels`. For values that belong to one editor, such as
+     * its room or document, use {@link Telemetry.moduleFor}.
+     *
+     * These values are yours and go only to your exporters. Keys follow attribute rules: letters,
+     * digits, `_`, `.`, and `-`, up to 64 characters. Values are strings, numbers, or booleans;
+     * strings are cut at 256 characters.
+     *
+     * @example
+     * ```ts
+     * attributes: () => ({ 'tenant.id': session.tenantId, 'user.id': session.pseudonymousId })
+     * ```
+     */
+    readonly attributes?: Attributes | (() => Attributes);
+    /**
+     * Which events go to your exporters, after the privacy check and sampling. Metrics still count
+     * every event. A filter that throws drops the event.
+     *
+     * @example
+     * ```ts
+     * // Failures and performance summaries only: no event for an open that succeeded.
+     * filter: (event) => isFailure(event) || event.kind === 'performance'
+     * ```
+     */
+    readonly filter?: (event: TelemetryEvent) => boolean;
+}
+/** A configured telemetry client. Create it once, outside any component. @public */
+interface Telemetry {
+    /**
+     * Register this in the editor's `modules`. It observes every editor created with it, from
+     * the first open on.
+     *
+     * @example
+     * ```tsx
+     * const MODULES = [reviewModule(), telemetry.module];
+     * <DocxEditor document={bytes} modules={MODULES} />;
+     * ```
+     */
+    readonly module: EditorModule;
+    /**
+     * A module for one editor, whose events also carry `attributes`, such as its collaboration
+     * room, document, or workspace. Create one for each editor, and keep it stable across renders.
+     * Use it in place of `module`, not next to it.
+     *
+     * @example
+     * ```tsx
+     * const modules = useMemo(
+     *   () => [reviewModule(), telemetry.moduleFor({ 'room.id': roomId, 'document.id': documentId })],
+     *   [roomId, documentId]
+     * );
+     * ```
+     */
+    moduleFor(attributes: Attributes): EditorModule;
+    /**
+     * Record one diagnostic yourself, for example from a runtime you created without `module`.
+     * Use `module` or `record`, not both, or every event is recorded twice. `attributes` are added
+     * to this event, as `moduleFor` adds them.
+     */
+    record(event: EditorDiagnostic, attributes?: Attributes): void;
+    /** Send summaries of open deduplication windows, then flush every exporter. */
+    flush(): Promise<void>;
+    /** Flush, then stop. Later events are dropped. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a telemetry client for editors.
+ *
+ * Nothing is sent unless you pass an exporter. With `consent`, nothing is sent while it is
+ * false; without it, events are sent. Every event is anonymous: codes, enums, and bucketed
+ * numbers only.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, consoleExporter } from '@docx-editor.dev/telemetry';
+ *
+ * export const telemetry = createTelemetry({
+ *   exporters: [consoleExporter()],
+ *   include: { documentOpen: true, trackedChanges: true },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createTelemetry(options: TelemetryOptions): Telemetry;
+
+/**
+ * Sending telemetry to your own HTTP endpoint from a browser, and reading the browser's privacy
+ * signals. No dependency: `fetch`, `sendBeacon`, and `localStorage` only.
+ */
+
+/** Options for {@link httpExporter}. @public */
+interface HttpExporterOptions {
+    /**
+     * Where to POST. Use a route on your own origin, which then forwards to your log service, so
+     * the service's token never reaches the browser. See `@docx-editor.dev/telemetry/ingest`.
+     */
+    readonly url: string;
+    /**
+     * Events per request, from 1 to 50. Defaults to 20. A full batch is sent at once. The limit
+     * matches the default `maxEvents` of `telemetryRoute`, which refuses a longer list.
+     */
+    readonly batchSize?: number;
+    /** How long an event waits for its batch to fill, in milliseconds. Defaults to 10 000. */
+    readonly flushIntervalMs?: number;
+    /**
+     * Extra request headers. A browser cannot set headers on `sendBeacon`, so with headers, the
+     * batches sent while the page closes use `fetch` with `keepalive` instead.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Called when a request fails, or when batches are dropped because the page closed with more
+     * than the browser lets it send. Telemetry never throws into your app.
+     */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Batch events and POST them as a JSON array to your own endpoint.
+ *
+ * While the page is open, events wait up to `flushIntervalMs` for a batch of `batchSize`, and
+ * each batch goes out with an ordinary `fetch`; so does a `telemetry.flush()` you call. When the
+ * page is hidden or closes, everything waiting goes out with `sendBeacon`. A closing page may
+ * send only about 64 KiB in all, so delivery while closing is best effort: batches beyond that
+ * are dropped and reported to `onError`. If consent is withdrawn, events still waiting are
+ * discarded.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, httpExporter } from '@docx-editor.dev/telemetry';
+ *
+ * export const telemetry = createTelemetry({
+ *   exporters: [httpExporter({ url: '/api/telemetry' })],
+ *   include: { documentOpen: true, editing: true, trackedChanges: true, performance: true },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function httpExporter(options: HttpExporterOptions): TelemetryExporter;
+/** Options for {@link browserPrivacySignals}. @public */
+interface BrowserPrivacySignalsOptions {
+    /**
+     * A `localStorage` key that opts the visitor out when its value is `off`, such as one your
+     * privacy settings page writes. Omit it to read only the browser signals.
+     */
+    readonly optOutKey?: string;
+}
+/**
+ * A `consent` function that follows the browser's privacy signals: it returns `false` when the
+ * visitor sends Global Privacy Control or Do Not Track, or when `optOutKey` is set to `off`.
+ * Outside a browser page, such as during server rendering, it returns `false`. Combine it with
+ * your consent manager when you have one.
+ *
+ * @example
+ * ```ts
+ * import { browserPrivacySignals, createTelemetry } from '@docx-editor.dev/telemetry';
+ *
+ * const privacy = browserPrivacySignals({ optOutKey: 'my-app:telemetry' });
+ * export const telemetry = createTelemetry({
+ *   exporters: [],
+ *   consent: () => privacy() && consentManager.analytics,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function browserPrivacySignals(options?: BrowserPrivacySignalsOptions): () => boolean;
+
+/**
+ * Send each event to your own function: Datadog RUM, PostHog, a logger, or an API route.
+ *
+ * `onMetric` receives every measurement. A performance summary arrives as one histogram sample
+ * for each timing in it, at the middle of the timing's band, so the bucket counts are exact.
+ * To chart percentiles, read `p50Ms` and `p95Ms` from the `performance` event instead.
+ *
+ * @example
+ * ```ts
+ * callbackExporter((event) =>
+ *   isFailure(event)
+ *     ? datadogRum.addError(new Error(event.kind), event)
+ *     : datadogRum.addAction(event.kind, event)
+ * );
+ * ```
+ *
+ * @public
+ */
+declare function callbackExporter(onEvent: (event: TelemetryEvent) => void, onMetric?: (record: MetricRecord) => void): TelemetryExporter;
+/** Options for {@link consoleExporter}. @public */
+interface ConsoleExporterOptions {
+    /** Also print every metric measurement. Defaults to `false`. */
+    readonly metrics?: boolean;
+    /** Where to print. Defaults to the global `console`. */
+    readonly console?: Pick<Console, 'info' | 'warn'>;
+}
+/**
+ * Whether an event is a failure: a refused open, a refused edit other than an expected one
+ * (a stale range, a read-only document, protected content, a session or refresh not ready
+ * yet), an unreadable payload, a font that did not load, or a collaboration error. A missing
+ * font that was substituted and a tracked change someone else already reviewed are not. Use it
+ * in a callback to send failures as errors and the rest as actions or logs.
+ *
+ * @example
+ * ```ts
+ * callbackExporter((event) => {
+ *   const code = 'code' in event ? event.code : undefined;
+ *   if (isFailure(event)) myLogger.error(event.kind, { code, hint: event.hint });
+ *   else myLogger.info(event.kind);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function isFailure(event: TelemetryEvent): boolean;
+/**
+ * Print each event with its hint and docs link. Use it during development to see why a
+ * document did not open or why a tracked change was refused.
+ *
+ * @example
+ * ```ts
+ * createTelemetry({ exporters: [consoleExporter()] });
+ * // An agent deletes a picture while changes are tracked:
+ * // [docx-editor] edit refused: edit.tracked-operation-unsupported (automation, tracked)
+ * //   This editing API operation cannot be recorded as a tracked change, so nothing was ...
+ * //   https://docx-editor.dev/docs/2.x/guides/diagnostics#edit-tracked-operation-unsupported
+ * ```
+ *
+ * @public
+ */
+declare function consoleExporter(options?: ConsoleExporterOptions): TelemetryExporter;
+/** An exporter that keeps what it receives. Returned by {@link memoryExporter}. @public */
+interface MemoryExporter extends TelemetryExporter {
+    readonly events: readonly TelemetryEvent[];
+    readonly metrics: readonly MetricRecord[];
+    /** Forget everything received so far. */
+    clear(): void;
+}
+/**
+ * Keep events and metrics in memory, for tests in your own suite.
+ *
+ * @example
+ * ```ts
+ * const memory = memoryExporter();
+ * const telemetry = createTelemetry({ exporters: [memory] });
+ * // ...open a file that fails...
+ * expect(memory.events).toContainEqual(
+ *   expect.objectContaining({ code: 'open.missing-main-document' })
+ * );
+ * ```
+ *
+ * @public
+ */
+declare function memoryExporter(): MemoryExporter;
+
+export { Attributes, MetricRecord, TelemetryEvent, TelemetryExporter, TelemetryPipelineOptions, browserPrivacySignals, callbackExporter, consoleExporter, createTelemetry, httpExporter, isFailure, memoryExporter };
+export type { BrowserPrivacySignalsOptions, ConsoleExporterOptions, HttpExporterOptions, MemoryExporter, Telemetry, TelemetryArea, TelemetryAreaOptions, TelemetryInclude, TelemetryOptions };

package/dist/index.d.ts

@@ -0,0 +1,332 @@
+/**
+ * Anonymous diagnostics, metrics, and error reporting for editors and collaboration servers.
+ *
+ * - `@docx-editor.dev/telemetry`: {@link createTelemetry} for editors, the console, callback,
+ *   memory, and HTTP exporters, and {@link browserPrivacySignals}.
+ * - `@docx-editor.dev/telemetry/ingest`: a route that receives telemetry from `httpExporter`
+ *   and forwards it to a log service.
+ * - `@docx-editor.dev/telemetry/otel`: OpenTelemetry metrics and traces through your SDK.
+ * - `@docx-editor.dev/telemetry/sentry`: Sentry issues and breadcrumbs.
+ * - `@docx-editor.dev/telemetry/prometheus`: a `/metrics` endpoint.
+ * - `@docx-editor.dev/telemetry/server`: room telemetry for any Yjs server.
+ * - `@docx-editor.dev/telemetry/hocuspocus`: room telemetry for Hocuspocus in one call.
+ *
+ * @packageDocumentation
+ */
+import { EditorModule, EditorDiagnostic } from '@docx-editor.dev/core';
+export { ByteSizeBucket, CollaborationDiagnosticCode, CollaborationParticipantsDiagnostic, CollaborationStatusDiagnostic, CountBucket, CustomNodeDiagnosticCode, CustomNodeDiagnosticEvent, DiagnosticBase, DiagnosticCode, DiagnosticErrorName, DiagnosticExplanation, DiagnosticFailureDetail, DocumentOpenDiagnostic, DocumentOpenDiagnosticCode, DocumentPartKind, DocumentShape, EditDiagnosticCode, EditRejectedDiagnostic, EditRejectionOrigin, EditorDiagnostic, EditorDiagnosticKind, FailureStage, FontDiagnosticCode, FontFailedDiagnostic, FormattingChangeKind, HistoryDiagnosticCode, HistoryDiagnosticEvent, PerformanceDiagnostic, PerformanceDiagnosticCode, ReviewChangeKind, ReviewDiagnosticCode, ReviewOperation, ReviewSkippedDiagnostic, TimingSummary, explainDiagnostic } from '@docx-editor.dev/core';
+import { A as Attributes, T as TelemetryPipelineOptions, a as TelemetryEvent, b as TelemetryExporter, M as MetricRecord } from './pipeline-DbVW7S-K.js';
+export { c as AttributeValue, E as ENGINE_VERSION, d as MAX_METRIC_LABEL_VALUES, e as METRICS, f as MetricDefinition, g as MetricId, h as MetricKind, i as TelemetryEventContext, j as TelemetryExporterContext, p as prometheusName } from './pipeline-DbVW7S-K.js';
+
+/**
+ * The areas you can switch on. Each one selects diagnostic kinds:
+ *
+ * - `documentOpen`: documents opened and refused (`document.open`).
+ * - `editing`: edits and commands refused while changes are not tracked (`edit.rejected`).
+ * - `trackedChanges`: refusals while suggesting, refusals about tracking itself, and skipped
+ *   tracked changes
+ *   (`edit.rejected` with `tracked: true`, `review.skipped`).
+ * - `fonts`: fonts that failed and were substituted (`font.failed`).
+ * - `history`: undo steps that did not group as the gesture intended (`history`).
+ * - `customNodes`: custom node payloads that could not be read (`custom-node`).
+ * - `collaborationClient`: collaboration status changes and room size (`collab.*`).
+ * - `performance`: how fast the editor responds: key presses and clicks to the next frame,
+ *   and engine layout and paint times, as one summary per minute of use (`performance`).
+ *
+ * @public
+ */
+type TelemetryArea = 'documentOpen' | 'editing' | 'trackedChanges' | 'fonts' | 'history' | 'customNodes' | 'collaborationClient' | 'performance';
+/** Options for one area. @public */
+interface TelemetryAreaOptions {
+    /**
+     * Share of events to send, from 0 to 1. Metrics count every event, except that a
+     * `performance` rate of 0 turns performance off, metrics included. Defaults to 1.
+     * Each event is sampled on its own, except in `performance`: there the choice is made once
+     * for each editor, which sends all of its summaries or none.
+     */
+    readonly sampleRate?: number;
+}
+/** Which areas to record. An area that is absent or `false` records nothing. @public */
+type TelemetryInclude = {
+    readonly [A in TelemetryArea]?: boolean | TelemetryAreaOptions;
+};
+/** Options for {@link createTelemetry}. @public */
+interface TelemetryOptions extends TelemetryPipelineOptions {
+    /**
+     * The areas to record. Omitted, every area is on.
+     *
+     * @example
+     * ```ts
+     * include: { documentOpen: true, trackedChanges: true, editing: { sampleRate: 0.2 } }
+     * ```
+     */
+    readonly include?: TelemetryInclude;
+    /**
+     * Identical refusals inside this window are sent once, then summarized with `repeated`.
+     * Holding Backspace on a locked drawing is one event, not hundreds. Defaults to 10 000 ms.
+     * Set 0 to send every event.
+     */
+    readonly dedupeWindowMs?: number;
+    /**
+     * How much of an opened document's shape to send. `'basic'`, the default, sends the size and
+     * page buckets. `'detailed'` also sends part, paragraph, review item, and embedded font
+     * buckets: useful to group open times, but several counts together describe a document more
+     * closely, so ask for it only when you need it.
+     */
+    readonly documentShape?: 'basic' | 'detailed';
+    /**
+     * Your identifiers on every event, such as a tenant or a pseudonymous user id. A function is
+     * read at each event, so it can follow sign-in and tenant switches. Events only: to label
+     * metrics with a key, list it in `metricLabels`. For values that belong to one editor, such as
+     * its room or document, use {@link Telemetry.moduleFor}.
+     *
+     * These values are yours and go only to your exporters. Keys follow attribute rules: letters,
+     * digits, `_`, `.`, and `-`, up to 64 characters. Values are strings, numbers, or booleans;
+     * strings are cut at 256 characters.
+     *
+     * @example
+     * ```ts
+     * attributes: () => ({ 'tenant.id': session.tenantId, 'user.id': session.pseudonymousId })
+     * ```
+     */
+    readonly attributes?: Attributes | (() => Attributes);
+    /**
+     * Which events go to your exporters, after the privacy check and sampling. Metrics still count
+     * every event. A filter that throws drops the event.
+     *
+     * @example
+     * ```ts
+     * // Failures and performance summaries only: no event for an open that succeeded.
+     * filter: (event) => isFailure(event) || event.kind === 'performance'
+     * ```
+     */
+    readonly filter?: (event: TelemetryEvent) => boolean;
+}
+/** A configured telemetry client. Create it once, outside any component. @public */
+interface Telemetry {
+    /**
+     * Register this in the editor's `modules`. It observes every editor created with it, from
+     * the first open on.
+     *
+     * @example
+     * ```tsx
+     * const MODULES = [reviewModule(), telemetry.module];
+     * <DocxEditor document={bytes} modules={MODULES} />;
+     * ```
+     */
+    readonly module: EditorModule;
+    /**
+     * A module for one editor, whose events also carry `attributes`, such as its collaboration
+     * room, document, or workspace. Create one for each editor, and keep it stable across renders.
+     * Use it in place of `module`, not next to it.
+     *
+     * @example
+     * ```tsx
+     * const modules = useMemo(
+     *   () => [reviewModule(), telemetry.moduleFor({ 'room.id': roomId, 'document.id': documentId })],
+     *   [roomId, documentId]
+     * );
+     * ```
+     */
+    moduleFor(attributes: Attributes): EditorModule;
+    /**
+     * Record one diagnostic yourself, for example from a runtime you created without `module`.
+     * Use `module` or `record`, not both, or every event is recorded twice. `attributes` are added
+     * to this event, as `moduleFor` adds them.
+     */
+    record(event: EditorDiagnostic, attributes?: Attributes): void;
+    /** Send summaries of open deduplication windows, then flush every exporter. */
+    flush(): Promise<void>;
+    /** Flush, then stop. Later events are dropped. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a telemetry client for editors.
+ *
+ * Nothing is sent unless you pass an exporter. With `consent`, nothing is sent while it is
+ * false; without it, events are sent. Every event is anonymous: codes, enums, and bucketed
+ * numbers only.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, consoleExporter } from '@docx-editor.dev/telemetry';
+ *
+ * export const telemetry = createTelemetry({
+ *   exporters: [consoleExporter()],
+ *   include: { documentOpen: true, trackedChanges: true },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createTelemetry(options: TelemetryOptions): Telemetry;
+
+/**
+ * Sending telemetry to your own HTTP endpoint from a browser, and reading the browser's privacy
+ * signals. No dependency: `fetch`, `sendBeacon`, and `localStorage` only.
+ */
+
+/** Options for {@link httpExporter}. @public */
+interface HttpExporterOptions {
+    /**
+     * Where to POST. Use a route on your own origin, which then forwards to your log service, so
+     * the service's token never reaches the browser. See `@docx-editor.dev/telemetry/ingest`.
+     */
+    readonly url: string;
+    /**
+     * Events per request, from 1 to 50. Defaults to 20. A full batch is sent at once. The limit
+     * matches the default `maxEvents` of `telemetryRoute`, which refuses a longer list.
+     */
+    readonly batchSize?: number;
+    /** How long an event waits for its batch to fill, in milliseconds. Defaults to 10 000. */
+    readonly flushIntervalMs?: number;
+    /**
+     * Extra request headers. A browser cannot set headers on `sendBeacon`, so with headers, the
+     * batches sent while the page closes use `fetch` with `keepalive` instead.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Called when a request fails, or when batches are dropped because the page closed with more
+     * than the browser lets it send. Telemetry never throws into your app.
+     */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Batch events and POST them as a JSON array to your own endpoint.
+ *
+ * While the page is open, events wait up to `flushIntervalMs` for a batch of `batchSize`, and
+ * each batch goes out with an ordinary `fetch`; so does a `telemetry.flush()` you call. When the
+ * page is hidden or closes, everything waiting goes out with `sendBeacon`. A closing page may
+ * send only about 64 KiB in all, so delivery while closing is best effort: batches beyond that
+ * are dropped and reported to `onError`. If consent is withdrawn, events still waiting are
+ * discarded.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, httpExporter } from '@docx-editor.dev/telemetry';
+ *
+ * export const telemetry = createTelemetry({
+ *   exporters: [httpExporter({ url: '/api/telemetry' })],
+ *   include: { documentOpen: true, editing: true, trackedChanges: true, performance: true },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function httpExporter(options: HttpExporterOptions): TelemetryExporter;
+/** Options for {@link browserPrivacySignals}. @public */
+interface BrowserPrivacySignalsOptions {
+    /**
+     * A `localStorage` key that opts the visitor out when its value is `off`, such as one your
+     * privacy settings page writes. Omit it to read only the browser signals.
+     */
+    readonly optOutKey?: string;
+}
+/**
+ * A `consent` function that follows the browser's privacy signals: it returns `false` when the
+ * visitor sends Global Privacy Control or Do Not Track, or when `optOutKey` is set to `off`.
+ * Outside a browser page, such as during server rendering, it returns `false`. Combine it with
+ * your consent manager when you have one.
+ *
+ * @example
+ * ```ts
+ * import { browserPrivacySignals, createTelemetry } from '@docx-editor.dev/telemetry';
+ *
+ * const privacy = browserPrivacySignals({ optOutKey: 'my-app:telemetry' });
+ * export const telemetry = createTelemetry({
+ *   exporters: [],
+ *   consent: () => privacy() && consentManager.analytics,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function browserPrivacySignals(options?: BrowserPrivacySignalsOptions): () => boolean;
+
+/**
+ * Send each event to your own function: Datadog RUM, PostHog, a logger, or an API route.
+ *
+ * `onMetric` receives every measurement. A performance summary arrives as one histogram sample
+ * for each timing in it, at the middle of the timing's band, so the bucket counts are exact.
+ * To chart percentiles, read `p50Ms` and `p95Ms` from the `performance` event instead.
+ *
+ * @example
+ * ```ts
+ * callbackExporter((event) =>
+ *   isFailure(event)
+ *     ? datadogRum.addError(new Error(event.kind), event)
+ *     : datadogRum.addAction(event.kind, event)
+ * );
+ * ```
+ *
+ * @public
+ */
+declare function callbackExporter(onEvent: (event: TelemetryEvent) => void, onMetric?: (record: MetricRecord) => void): TelemetryExporter;
+/** Options for {@link consoleExporter}. @public */
+interface ConsoleExporterOptions {
+    /** Also print every metric measurement. Defaults to `false`. */
+    readonly metrics?: boolean;
+    /** Where to print. Defaults to the global `console`. */
+    readonly console?: Pick<Console, 'info' | 'warn'>;
+}
+/**
+ * Whether an event is a failure: a refused open, a refused edit other than an expected one
+ * (a stale range, a read-only document, protected content, a session or refresh not ready
+ * yet), an unreadable payload, a font that did not load, or a collaboration error. A missing
+ * font that was substituted and a tracked change someone else already reviewed are not. Use it
+ * in a callback to send failures as errors and the rest as actions or logs.
+ *
+ * @example
+ * ```ts
+ * callbackExporter((event) => {
+ *   const code = 'code' in event ? event.code : undefined;
+ *   if (isFailure(event)) myLogger.error(event.kind, { code, hint: event.hint });
+ *   else myLogger.info(event.kind);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function isFailure(event: TelemetryEvent): boolean;
+/**
+ * Print each event with its hint and docs link. Use it during development to see why a
+ * document did not open or why a tracked change was refused.
+ *
+ * @example
+ * ```ts
+ * createTelemetry({ exporters: [consoleExporter()] });
+ * // An agent deletes a picture while changes are tracked:
+ * // [docx-editor] edit refused: edit.tracked-operation-unsupported (automation, tracked)
+ * //   This editing API operation cannot be recorded as a tracked change, so nothing was ...
+ * //   https://docx-editor.dev/docs/2.x/guides/diagnostics#edit-tracked-operation-unsupported
+ * ```
+ *
+ * @public
+ */
+declare function consoleExporter(options?: ConsoleExporterOptions): TelemetryExporter;
+/** An exporter that keeps what it receives. Returned by {@link memoryExporter}. @public */
+interface MemoryExporter extends TelemetryExporter {
+    readonly events: readonly TelemetryEvent[];
+    readonly metrics: readonly MetricRecord[];
+    /** Forget everything received so far. */
+    clear(): void;
+}
+/**
+ * Keep events and metrics in memory, for tests in your own suite.
+ *
+ * @example
+ * ```ts
+ * const memory = memoryExporter();
+ * const telemetry = createTelemetry({ exporters: [memory] });
+ * // ...open a file that fails...
+ * expect(memory.events).toContainEqual(
+ *   expect.objectContaining({ code: 'open.missing-main-document' })
+ * );
+ * ```
+ *
+ * @public
+ */
+declare function memoryExporter(): MemoryExporter;
+
+export { Attributes, MetricRecord, TelemetryEvent, TelemetryExporter, TelemetryPipelineOptions, browserPrivacySignals, callbackExporter, consoleExporter, createTelemetry, httpExporter, isFailure, memoryExporter };
+export type { BrowserPrivacySignalsOptions, ConsoleExporterOptions, HttpExporterOptions, MemoryExporter, Telemetry, TelemetryArea, TelemetryAreaOptions, TelemetryInclude, TelemetryOptions };