@docx-editor.dev/telemetry 0.0.1 → 2.30.0

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunk6BTB6Y3H_cjs=require('./chunk-6BTB6Y3H.cjs'),chunkAL2YERWY_cjs=require('./chunk-AL2YERWY.cjs'),chunkE2HR5DHZ_cjs=require('./chunk-E2HR5DHZ.cjs'),chunk7SYLCJFQ_cjs=require('./chunk-7SYLCJFQ.cjs');require('./chunk-WGWKNKUT.cjs');var core=require('@docx-editor.dev/core');var X={documentOpen:true,documentSave:true,sessions:true,editing:true,trackedChanges:true,fonts:true,history:true,customNodes:true,collaborationClient:true,performance:true},Y=new Set(["edit.tracking-required","edit.suggesting-needs-author","edit.tracking-mode-unsupported","edit.tracking-author-required","edit.tracking-unsupported-host"]);function Z(e){switch(e.kind){case "document.open":return "documentOpen";case "document.save":return "documentSave";case "session":return "sessions";case "edit.rejected":return e.tracked||Y.has(e.code)?"trackedChanges":"editing";case "review.skipped":return "trackedChanges";case "font.failed":return "fonts";case "history":return "history";case "custom-node":return "customNodes";case "collab.status":case "collab.participants":return "collaborationClient";case "performance":return "performance";default:return null}}function J(e){return e.kind==="collab.participants"?`${e.editorSessionId}|participants`:e.kind==="edit.rejected"?[e.editorSessionId,e.code,e.cause,e.errorName,e.stage,e.origin,e.tracked,e.command].join("|"):e.kind==="font.failed"?`${e.editorSessionId}|font|${e.code}`:e.kind==="history"||e.kind==="custom-node"?`${e.editorSessionId}|${e.kind}|${e.code}`:e.kind==="collab.status"?`${e.editorSessionId}|status|${e.status}|${e.code??""}|${e.recovering}`:null}function Q(e){let t=chunk6BTB6Y3H_cjs.c(e),m=e.metricLabels??[];function n(o){let r={};try{let a=typeof e.attributes=="function"?e.attributes():e.attributes;r=chunk7SYLCJFQ_cjs.c(a??{},"attributes");}catch{}return Object.freeze({...r,...o})}function c(o){let r={};for(let a of m)o[a]!==void 0&&(r[a]=o[a]);return r}let f=e.include??X,l=e.dedupeWindowMs??1e4,g=o=>{try{if(e.filter&&!e.filter(o))return}catch{return}t.event(o);},E=e.documentShape==="detailed",y=new Map,S=false,k=()=>{},T=false;function D(o){let r=f[o];return r?r===true?1:Math.min(1,Math.max(0,r.sampleRate??1)):null}let h=new Map;function w(o,r,a){if(a>=1)return  true;if(r!=="performance"&&r!=="sessions")return Math.random()<a;let p=`${r}|${o.editorSessionId}`,b=h.get(p);return b===void 0&&(h.size>=1e3&&h.clear(),b=Math.random()<a,h.set(p,b)),b}function M(){if(S)return;S=true;let o=globalThis;if(typeof o.addEventListener!="function")return;let r=()=>{t.setPageClosing(true),u();},a=()=>{let p=globalThis.document?.visibilityState==="hidden";t.setPageClosing(p),p&&u();};o.addEventListener("pagehide",r),o.addEventListener("visibilitychange",a),k=()=>{o.removeEventListener?.("pagehide",r),o.removeEventListener?.("visibilitychange",a);};}function v(o){let r=y.get(o);if(r){if(y.delete(o),clearTimeout(r.timer),r.latest){let a=r.event;r.latest.count!==a.count&&g(I(F(r.latest,E),t,r.event.attributes));}else if(r.repeated>0){let{connectMs:a,...p}=r.event;g({...p,repeated:Math.min(r.repeated,chunk7SYLCJFQ_cjs.a)});}}}function i(o,r={}){if(T||!t.consented())return;let a=n(r),p=chunk7SYLCJFQ_cjs.b(I(o,t,a));if("dropped"in p){t.metric(chunkAL2YERWY_cjs.a.droppedEvents,1,{...c(a),reason:p.dropped,"docx_editor.version":chunk6BTB6Y3H_cjs.b});return}let b=Z(o),A=b?D(b):null;if(A===null||b==="performance"&&A===0)return;M(),ee(t,p.event,c(a));let x=l>0?J(o):null,O=x?y.get(x):void 0;if(O){o.kind==="collab.participants"?O.latest=o:O.repeated+=1;return}let _=o.kind==="session"&&o.phase==="end";if(!w(o,b,A)){_&&u();return}let L=I(F(o,E),t,a);if(g(L),_&&u(),x){let R=setTimeout(()=>v(x),l);R.unref?.(),y.set(x,{event:L,repeated:0,timer:R});}}function d(o){return Object.freeze({id:"telemetry",onDiagnostic:r=>i(r,o),wantsDiagnostic:r=>!T&&(r==="session"?D("sessions")!==null:r!=="performance"||(D("performance")??0)>0&&t.consented())})}async function u(){for(let o of [...y.keys()])v(o);await t.flush();}return {module:d({}),moduleFor(o){return d(chunk7SYLCJFQ_cjs.c(o,"moduleFor"))},record:i,flush:u,async shutdown(){for(let o of [...y.keys()])v(o);T=true,k(),await t.shutdown();}}}function F(e,t){if(t||e.kind!=="document.open"||e.outcome!=="opened"||!("shape"in e))return e;let{shape:m,...n}=e;return n}function I(e,t,m){let n="code"in e?e.code:void 0;return {...e,...n?core.explainDiagnostic(n):{},engineVersion:chunk6BTB6Y3H_cjs.b,resource:t.resource,attributes:m}}function ee(e,t,m){let n={metric:(c,f,l={})=>e.metric(c,f,{...l,...m,"docx_editor.version":chunk6BTB6Y3H_cjs.b})};switch(t.kind){case "document.open":t.outcome==="opened"?(n.metric(chunkAL2YERWY_cjs.a.documentOpens,1,{outcome:"opened",code:"none",cause:"none",part:"none"}),n.metric(chunkAL2YERWY_cjs.a.documentOpenDuration,t.durationMs/1e3)):n.metric(chunkAL2YERWY_cjs.a.documentOpens,1,{outcome:"rejected",code:t.code,cause:t.cause??"none",part:t.part??"none"});return;case "edit.rejected":n.metric(chunkAL2YERWY_cjs.a.editRejections,1,{code:t.code,cause:t.cause??"none",origin:t.origin,tracked:t.tracked});return;case "review.skipped":n.metric(chunkAL2YERWY_cjs.a.reviewSkipped,t.count,{code:t.code,cause:t.cause??"none",operation:t.operation??"none",change_kind:t.changeKind??"none"});return;case "font.failed":n.metric(chunkAL2YERWY_cjs.a.fontFailures,1,{code:t.code});return;case "history":n.metric(chunkAL2YERWY_cjs.a.historyDiagnostics,1,{code:t.code});return;case "custom-node":n.metric(chunkAL2YERWY_cjs.a.customNodeDiagnostics,1,{code:t.code});return;case "collab.status":n.metric(chunkAL2YERWY_cjs.a.collabClientStatusTransitions,1,{status:t.status,code:t.code??"none"}),t.connectMs!==void 0&&n.metric(chunkAL2YERWY_cjs.a.collabClientConnectDuration,t.connectMs/1e3);return;case "collab.participants":n.metric(chunkAL2YERWY_cjs.a.collabClientParticipants,t.count);return;case "performance":{let c=t.pagesBucket??"unknown";N(n,chunkAL2YERWY_cjs.a.editorInteractionDuration,c,t.interaction),N(n,chunkAL2YERWY_cjs.a.editorLayoutDuration,c,t.layout),N(n,chunkAL2YERWY_cjs.a.editorPaintDuration,c,t.paint);return}case "document.save":n.metric(chunkAL2YERWY_cjs.a.documentSaves,1,{outcome:t.outcome,code:t.outcome==="rejected"?t.code:"none"}),t.outcome==="saved"&&n.metric(chunkAL2YERWY_cjs.a.documentSaveDuration,t.durationMs/1e3);return;case "session":te(n,t);}}function te(e,t){if(t.phase==="start"){e.metric(chunkAL2YERWY_cjs.a.editorSessions,1,{phase:"start"});return}if(t.phase==="end"){e.metric(chunkAL2YERWY_cjs.a.editorSessions,1,{phase:"end"}),e.metric(chunkAL2YERWY_cjs.a.editorSessionDuration,t.durationMs/1e3);return}t.activeMs>0&&e.metric(chunkAL2YERWY_cjs.a.editorActiveTime,t.activeMs/1e3);for(let[m,n]of [["input",t.inputEdits],["command",t.commandEdits],["automation",t.automationEdits]])n>0&&e.metric(chunkAL2YERWY_cjs.a.edits,n,{origin:m});}function N(e,t,m,n){if(!n)return;let c=t.buckets??[];n.bands.forEach((f,l)=>{let g=c[l],E=l===0?0:c[l-1],y=g===void 0?Math.max(n.maxMs/1e3,E+1e-6):(E+g)/2;for(let S=0;S<f;S+=1)e.metric(t,y,{pages:m});});}var oe=new TextEncoder,ne=e=>oe.encode(e).byteLength;function re(e){let t=Math.min(50,Math.max(1,Math.floor(e.batchSize??20))),m=e.flushIntervalMs??1e4,n=[],c,f,l=new Set,g=i=>{try{e.onError?.(i);}catch{}},E=(i,d)=>{if(typeof fetch!="function")return;let u=fetch(e.url,{method:"POST",headers:{"Content-Type":"application/json",...e.headers},body:i,keepalive:d}).then(o=>{if(!o.ok)throw new Error(`telemetry endpoint answered ${o.status}`)}).catch(g).finally(()=>l.delete(u));l.add(u);},y=i=>{let d=globalThis.navigator;if(!e.headers&&typeof d?.sendBeacon=="function")try{if(d.sendBeacon(e.url,new Blob([i],{type:"application/json"})))return}catch{}E(i,true);},S=i=>{let d=Math.min(t,n.length);for(;d>0;){let u=JSON.stringify(n.slice(0,d)),o=ne(u);if(o<=i)return {body:u,bytes:o,count:d};if(d===1)return null;d=Math.ceil(d/2);}return null},k=0,T=false,D=i=>{if(c!==void 0&&clearTimeout(c),c=void 0,f&&!f.consented()){n=[];return}(!i||!T)&&(k=0),T=i;let d=0;for(;n.length;){let u=S(61440-(i?k:0));if(!u){d+=i?n.length:1,n=i?[]:n.slice(1);continue}n=n.slice(u.count),i?(k+=u.bytes,y(u.body)):E(u.body,false);}d&&g(new Error(`telemetry dropped ${d} events that did not fit`));},h=()=>{let i=f?.pageClosing()??false;return i||(T=false),i},w=globalThis.document,M=()=>{w?.visibilityState==="visible"&&(T=false);},v=()=>w?.removeEventListener?.("visibilitychange",M);return {name:"http",attach(i){f=i,w?.addEventListener?.("visibilitychange",M);},event(i){n.push(i),n.length>=t?D(h()):c===void 0&&(c=setTimeout(()=>D(h()),m),c.unref?.());},async flush(){D(h()),await Promise.all(l);},async shutdown(){v(),D(h()),await Promise.all(l);}}}function ie(e={}){return ()=>{let t=globalThis;if(!t.window||!t.document||!t.navigator||t.navigator.globalPrivacyControl===true||t.navigator.doNotTrack==="1")return  false;if(!e.optOutKey)return  true;try{return globalThis.localStorage?.getItem(e.optOutKey)!=="off"}catch{return  true}}}Object.defineProperty(exports,"ENGINE_VERSION",{enumerable:true,get:function(){return chunk6BTB6Y3H_cjs.b}});Object.defineProperty(exports,"MAX_METRIC_LABEL_VALUES",{enumerable:true,get:function(){return chunk6BTB6Y3H_cjs.a}});Object.defineProperty(exports,"METRICS",{enumerable:true,get:function(){return chunkAL2YERWY_cjs.a}});Object.defineProperty(exports,"prometheusName",{enumerable:true,get:function(){return chunkAL2YERWY_cjs.b}});Object.defineProperty(exports,"callbackExporter",{enumerable:true,get:function(){return chunkE2HR5DHZ_cjs.a}});Object.defineProperty(exports,"consoleExporter",{enumerable:true,get:function(){return chunkE2HR5DHZ_cjs.e}});Object.defineProperty(exports,"failureCount",{enumerable:true,get:function(){return chunkE2HR5DHZ_cjs.d}});Object.defineProperty(exports,"isFailure",{enumerable:true,get:function(){return chunkE2HR5DHZ_cjs.c}});Object.defineProperty(exports,"memoryExporter",{enumerable:true,get:function(){return chunkE2HR5DHZ_cjs.f}});Object.defineProperty(exports,"explainDiagnostic",{enumerable:true,get:function(){return core.explainDiagnostic}});exports.browserPrivacySignals=ie;exports.createTelemetry=Q;exports.httpExporter=re;

package/dist/index.d.cts

@@ -0,0 +1,355 @@
+/**
+ * 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, DocumentSaveDiagnostic, DocumentSaveDiagnosticCode, DocumentShape, EditDiagnosticCode, EditRejectedDiagnostic, EditRejectionOrigin, EditorDiagnostic, EditorDiagnosticKind, FailureStage, FontDiagnosticCode, FontFailedDiagnostic, FormattingChangeKind, HistoryDiagnosticCode, HistoryDiagnosticEvent, PerformanceDiagnostic, PerformanceDiagnosticCode, ReviewChangeKind, ReviewDiagnosticCode, ReviewOperation, ReviewSkippedDiagnostic, SessionActivity, SessionDiagnostic, 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-CCq2Ng0B.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-CCq2Ng0B.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`).
+ * - `documentSave`: calls to `save()` that returned the document or failed (`document.save`).
+ * - `sessions`: when each editor starts and ends, how long it is used, and how many edits it
+ *   commits, as one summary per minute of use (`session`).
+ *
+ * @public
+ */
+type TelemetryArea = 'documentOpen' | 'documentSave' | 'sessions' | '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` and `sessions`: 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);
+ * });
+ * ```
+ *
+ * A deduplication summary returns `false`: it repeats an event already reported. To total
+ * failures with summaries included, use {@link failureCount}.
+ *
+ * @public
+ */
+declare function isFailure(event: TelemetryEvent): boolean;
+/**
+ * How many failures an event adds to a failure total: `0` when it is not a failure, `1` for a
+ * failure, and `repeated` for a deduplication summary of one. The sum over every event a
+ * client sends equals the number of failures the editor reported, which {@link isFailure}
+ * alone undercounts. Sampling still applies: a sampled area sends a share of its events.
+ *
+ * @example
+ * ```ts
+ * let failures = 0;
+ * callbackExporter((event) => {
+ *   failures += failureCount(event);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function failureCount(event: TelemetryEvent): number;
+/**
+ * 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, failureCount, httpExporter, isFailure, memoryExporter };
+export type { BrowserPrivacySignalsOptions, ConsoleExporterOptions, HttpExporterOptions, MemoryExporter, Telemetry, TelemetryArea, TelemetryAreaOptions, TelemetryInclude, TelemetryOptions };