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

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

package/dist/index.js

@@ -0,0 +1 @@
+export{a as callbackExporter,d as consoleExporter,c as isFailure,e as memoryExporter}from'./chunk-NUN46EXH.js';import {c,b as b$1}from'./chunk-S7KBMROA.js';export{b as ENGINE_VERSION,a as MAX_METRIC_LABEL_VALUES}from'./chunk-S7KBMROA.js';import {a as a$1}from'./chunk-73YEPWY5.js';export{a as METRICS,b as prometheusName}from'./chunk-73YEPWY5.js';import {b,a}from'./chunk-DTEVX2XS.js';import'./chunk-DT2KMPUJ.js';import {explainDiagnostic}from'@docx-editor.dev/core';export{explainDiagnostic}from'@docx-editor.dev/core';var W={documentOpen:true,editing:true,trackedChanges:true,fonts:true,history:true,customNodes:true,collaborationClient:true,performance:true},q=new Set(["edit.tracking-required","edit.suggesting-needs-author","edit.tracking-mode-unsupported","edit.tracking-author-required","edit.tracking-unsupported-host"]);function U(e){switch(e.kind){case "document.open":return "documentOpen";case "edit.rejected":return e.tracked||q.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 X(e){return 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.participants"?`${e.editorSessionId}|participants`:e.kind==="collab.status"?`${e.editorSessionId}|status|${e.status}|${e.code??""}|${e.recovering}`:null}function Y(e){let t=c(e),m=e.metricLabels??[];function n(r){let o={};try{let a=typeof e.attributes=="function"?e.attributes():e.attributes;o=b(a??{},"attributes");}catch{}return Object.freeze({...o,...r})}function s(r){let o={};for(let a of m)r[a]!==void 0&&(o[a]=r[a]);return o}let f=e.include??W,l=e.dedupeWindowMs??1e4,g=r=>{try{if(e.filter&&!e.filter(r))return}catch{return}t.event(r);},h=e.documentShape==="detailed",y=new Map,T=false,w=()=>{},E=false;function D(r){let o=f[r];return o?o===true?1:Math.min(1,Math.max(0,o.sampleRate??1)):null}let b$2=new Map;function k(r,o,a){if(a>=1)return  true;if(o!=="performance")return Math.random()<a;let p=b$2.get(r.editorSessionId);return p===void 0&&(b$2.size>=1e3&&b$2.clear(),p=Math.random()<a,b$2.set(r.editorSessionId,p)),p}function v(){if(T)return;T=true;let r=globalThis;if(typeof r.addEventListener!="function")return;let o=()=>{t.setPageClosing(true),u();},a=()=>{let p=globalThis.document?.visibilityState==="hidden";t.setPageClosing(p),p&&u();};r.addEventListener("pagehide",o),r.addEventListener("visibilitychange",a),w=()=>{r.removeEventListener?.("pagehide",o),r.removeEventListener?.("visibilitychange",a);};}function x(r){let o=y.get(r);if(o)if(y.delete(r),clearTimeout(o.timer),o.latest){let a=o.event;o.latest.count!==a.count&&g(I(F(o.latest,h),t,o.event.attributes));}else o.repeated>0&&g({...o.event,repeated:o.repeated});}function i(r,o={}){if(E||!t.consented())return;let a$2=n(o),p=a(I(r,t,a$2));if("dropped"in p){t.metric(a$1.droppedEvents,1,{...s(a$2),reason:p.dropped,"docx_editor.version":b$1});return}let A=U(r),M=A?D(A):null;if(M===null||A==="performance"&&M===0)return;v(),Z(t,p.event,s(a$2));let S=l>0?X(r):null,O=S?y.get(S):void 0;if(O){r.kind==="collab.participants"?O.latest=r:O.repeated+=1;return}if(!k(r,A,M))return;let N=I(F(r,h),t,a$2);if(g(N),S){let R=setTimeout(()=>x(S),l);R.unref?.(),y.set(S,{event:N,repeated:0,timer:R});}}function c$1(r){return Object.freeze({id:"telemetry",onDiagnostic:o=>i(o,r),wantsDiagnostic:o=>!E&&(o!=="performance"||(D("performance")??0)>0&&t.consented())})}async function u(){for(let r of [...y.keys()])x(r);await t.flush();}return {module:c$1({}),moduleFor(r){return c$1(b(r,"moduleFor"))},record:i,flush:u,async shutdown(){for(let r of [...y.keys()])x(r);E=true,w(),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?explainDiagnostic(n):{},engineVersion:b$1,resource:t.resource,attributes:m}}function Z(e,t,m){let n={metric:(s,f,l={})=>e.metric(s,f,{...l,...m,"docx_editor.version":b$1})};switch(t.kind){case "document.open":t.outcome==="opened"?(n.metric(a$1.documentOpens,1,{outcome:"opened",code:"none",cause:"none",part:"none"}),n.metric(a$1.documentOpenDuration,t.durationMs/1e3)):n.metric(a$1.documentOpens,1,{outcome:"rejected",code:t.code,cause:t.cause??"none",part:t.part??"none"});return;case "edit.rejected":n.metric(a$1.editRejections,1,{code:t.code,cause:t.cause??"none",origin:t.origin,tracked:t.tracked});return;case "review.skipped":n.metric(a$1.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(a$1.fontFailures,1,{code:t.code});return;case "history":n.metric(a$1.historyDiagnostics,1,{code:t.code});return;case "custom-node":n.metric(a$1.customNodeDiagnostics,1,{code:t.code});return;case "collab.status":n.metric(a$1.collabClientStatusTransitions,1,{status:t.status,code:t.code??"none"}),t.connectMs!==void 0&&n.metric(a$1.collabClientConnectDuration,t.connectMs/1e3);return;case "collab.participants":n.metric(a$1.collabClientParticipants,t.count);return;case "performance":{let s=t.pagesBucket??"unknown";L(n,a$1.editorInteractionDuration,s,t.interaction),L(n,a$1.editorLayoutDuration,s,t.layout),L(n,a$1.editorPaintDuration,s,t.paint);}}}function L(e,t,m,n){if(!n)return;let s=t.buckets??[];n.bands.forEach((f,l)=>{let g=s[l],h=l===0?0:s[l-1],y=g===void 0?Math.max(n.maxMs/1e3,h+1e-6):(h+g)/2;for(let T=0;T<f;T+=1)e.metric(t,y,{pages:m});});}var J=new TextEncoder,Q=e=>J.encode(e).byteLength;function ee(e){let t=Math.min(50,Math.max(1,Math.floor(e.batchSize??20))),m=e.flushIntervalMs??1e4,n=[],s,f,l=new Set,g=i=>{try{e.onError?.(i);}catch{}},h=(i,c)=>{if(typeof fetch!="function")return;let u=fetch(e.url,{method:"POST",headers:{"Content-Type":"application/json",...e.headers},body:i,keepalive:c}).then(r=>{if(!r.ok)throw new Error(`telemetry endpoint answered ${r.status}`)}).catch(g).finally(()=>l.delete(u));l.add(u);},y=i=>{let c=globalThis.navigator;if(!e.headers&&typeof c?.sendBeacon=="function")try{if(c.sendBeacon(e.url,new Blob([i],{type:"application/json"})))return}catch{}h(i,true);},T=i=>{let c=Math.min(t,n.length);for(;c>0;){let u=JSON.stringify(n.slice(0,c)),r=Q(u);if(r<=i)return {body:u,bytes:r,count:c};if(c===1)return null;c=Math.ceil(c/2);}return null},w=0,E=false,D=i=>{if(s!==void 0&&clearTimeout(s),s=void 0,f&&!f.consented()){n=[];return}(!i||!E)&&(w=0),E=i;let c=0;for(;n.length;){let u=T(61440-(i?w:0));if(!u){c+=i?n.length:1,n=i?[]:n.slice(1);continue}n=n.slice(u.count),i?(w+=u.bytes,y(u.body)):h(u.body,false);}c&&g(new Error(`telemetry dropped ${c} events that did not fit`));},b=()=>{let i=f?.pageClosing()??false;return i||(E=false),i},k=globalThis.document,v=()=>{k?.visibilityState==="visible"&&(E=false);},x=()=>k?.removeEventListener?.("visibilitychange",v);return {name:"http",attach(i){f=i,k?.addEventListener?.("visibilitychange",v);},event(i){n.push(i),n.length>=t?D(b()):s===void 0&&(s=setTimeout(()=>D(b()),m),s.unref?.());},async flush(){D(b()),await Promise.all(l);},async shutdown(){x(),D(b()),await Promise.all(l);}}}function te(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}}}export{te as browserPrivacySignals,Y as createTelemetry,ee as httpExporter};

package/dist/ingest/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunkLFQSY2TD_cjs=require('../chunk-LFQSY2TD.cjs');require('../chunk-WGWKNKUT.cjs');var b=50,i=e=>typeof e=="string",l=e=>typeof e=="number"&&Number.isFinite(e),m=e=>typeof e=="boolean",k={"edit.rejected":[["code",i],["origin",i],["tracked",m]],"review.skipped":[["code",i],["count",l]],"font.failed":[["code",i]],history:[["code",i]],"custom-node":[["code",i]],"collab.status":[["status",i],["previous",i],["recovering",m]],"collab.participants":[["count",l]],performance:[["windowMs",l]]};function h(e){if(!l(e.schemaVersion)||!l(e.time)||!i(e.editorSessionId)||!i(e.engineVersion))return  false;if(e.kind==="document.open")return e.outcome==="opened"?i(e.sizeBucket)&&l(e.durationMs):e.outcome==="rejected"&&i(e.code);let r=k[e.kind];return !!r&&r.every(([t,o])=>o(e[t]))}function w(e,r){if(r.size===0)return {};let t=chunkLFQSY2TD_cjs.c(e)??{};return Object.fromEntries(Object.entries(t).filter(([o])=>r.has(o)))}function E(e,r={}){let t=r.maxEvents??b,o=new Set(r.attributeKeys??[]);return !Array.isArray(e)||e.length>t?[]:e.flatMap(n=>{if(!n||typeof n!="object"||Array.isArray(n))return [];let c=n,{resource:d,attributes:u,...s}=c,a=chunkLFQSY2TD_cjs.a(s);if("dropped"in a||!h(a.event))return [];let g=w(c.attributes,o),{attributes:x,...p}=a.event;return [Object.freeze({...p,resource:w(c.resource,o),attributes:g})]})}function O(e){let{hint:r,docs:t,...o}=e,n="code"in e&&e.code?` ${e.code}`:"";return {...o,dt:e.time,message:`${e.kind}${n}`}}var T=64*1024;async function R(e,r){if(Number(e.headers.get("content-length")??0)>r)return null;let t=e.body;if(!t)return "";let o=t.getReader(),n=[],c=0;for(;;){let{done:s,value:a}=await o.read();if(s)break;if(c+=a.byteLength,c>r)return await o.cancel().catch(()=>{}),null;n.push(a);}let d=new Uint8Array(c),u=0;for(let s of n)d.set(s,u),u+=s.byteLength;return new TextDecoder().decode(d)}function v(e){let r=e.maxBodyBytes??T,t=()=>new Response(null,{status:204}),o=n=>{try{e.onError?.(n);}catch{}};return async n=>{if(n.method!=="POST")return t();if(e.allowedOrigins){let s=n.headers.get("origin");if(!s||!e.allowedOrigins.includes(s))return t()}let c;try{c=await R(n,r);}catch{return t()}if(c===null)return t();let d;try{d=JSON.parse(c);}catch{return t()}let u=E(d,e);if(!u.length)return t();try{let a=await e.forward(u);if(a&&a.ok===!1)throw new Error(`the log service answered ${String(a.status)}`)}catch(s){o(s);}return t()}}exports.telemetryRoute=v;exports.toLogRecord=O;exports.validateTelemetryEvents=E;

package/dist/ingest/index.d.cts

@@ -0,0 +1,107 @@
+/**
+ * Receive editor telemetry on your server and forward it to a log service, such as Better Stack,
+ * Axiom, or Datadog Logs. Pair it with `httpExporter` in the browser: the browser posts to your
+ * route, and only your server holds the log service's token.
+ *
+ * Anyone can POST to a public route, so every event is checked again with the same closed lists
+ * the browser used, and fields the client chose itself are dropped unless you allow them. No
+ * dependency: Fetch API `Request` and `Response` only, so it runs in Next.js route handlers,
+ * Hono, Bun, Deno, and Cloudflare Workers.
+ *
+ * @packageDocumentation
+ */
+import { a as TelemetryEvent } from '../pipeline-DbVW7S-K.cjs';
+import '@docx-editor.dev/core';
+
+/** Options for {@link validateTelemetryEvents}. @public */
+interface ValidateTelemetryEventsOptions {
+    /** The most events one request may carry. Defaults to 50; a longer list is refused whole. */
+    readonly maxEvents?: number;
+    /**
+     * Keys of the browser's `resource` and `attributes` to keep, such as `['app.version']`. Each
+     * kept value must be a number, a boolean, or an identifier string. Defaults to none: a value
+     * the client chose cannot be checked for meaning, so add your fixed fields on the server.
+     */
+    readonly attributeKeys?: readonly string[];
+}
+/**
+ * The telemetry events in an untrusted request body, checked again with the package's own
+ * closed lists. An event with an unknown kind or code, or without the fields its kind needs, is
+ * dropped. A field outside its list is removed. The client's `resource` and `attributes` keep
+ * only the keys in `attributeKeys`. Returns an empty list for a body that is not an array or is
+ * longer than `maxEvents`.
+ *
+ * The check proves that every value comes from the package's lists or is a number. It cannot
+ * prove that a client told the truth: a script can send a well-formed event that never
+ * happened. It can never send text.
+ *
+ * @example
+ * ```ts
+ * const events = validateTelemetryEvents(await request.json(), { attributeKeys: ['app.version'] });
+ * ```
+ *
+ * @public
+ */
+declare function validateTelemetryEvents(body: unknown, options?: ValidateTelemetryEventsOptions): TelemetryEvent[];
+/** A log record with the fields log services read for time and summary. @public */
+type TelemetryLogRecord = Record<string, unknown> & {
+    /** The event time in milliseconds since the epoch, which Better Stack and others read. */
+    readonly dt: number;
+    /** A one-line summary, such as `edit.rejected edit.picture-selected`. */
+    readonly message: string;
+};
+/**
+ * An event as a log record: `dt` for the time, `message` for the live tail, and every field of
+ * the event except the fixed `hint` and `docs` text, which the code already identifies. Add
+ * your own fixed fields, such as a service name, to the result.
+ *
+ * @example
+ * ```ts
+ * body: JSON.stringify(events.map((event) => ({ ...toLogRecord(event), service: 'my-app' })))
+ * ```
+ *
+ * @public
+ */
+declare function toLogRecord(event: TelemetryEvent): TelemetryLogRecord;
+/** Options for {@link telemetryRoute}. @public */
+interface TelemetryRouteOptions extends ValidateTelemetryEventsOptions {
+    /** Send the checked events on, such as to your log service. Errors are caught and reported. */
+    forward(events: readonly TelemetryEvent[]): unknown;
+    /** Origins allowed to post, such as `['https://app.example.com']`. Omit to allow any. */
+    readonly allowedOrigins?: readonly string[];
+    /** The largest body accepted, in bytes. Defaults to 64 KiB. */
+    readonly maxBodyBytes?: number;
+    /** Called when `forward` throws or rejects, or the log service refuses. Defaults to nothing. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * A Fetch-style handler for telemetry from `httpExporter`: it accepts POST only, checks the
+ * origin, reads at most `maxBodyBytes`, validates every event, and calls `forward` with what
+ * passes. It answers 204 to every request, so a telemetry problem never surfaces in the
+ * editor; use `onError` to see failures. It does not rate-limit; put it behind your platform's
+ * limits.
+ *
+ * @example
+ * ```ts
+ * // Next.js: app/api/telemetry/route.ts
+ * import { telemetryRoute, toLogRecord } from '@docx-editor.dev/telemetry/ingest';
+ *
+ * export const POST = telemetryRoute({
+ *   forward: (events) =>
+ *     fetch(`https://${process.env.BETTERSTACK_INGESTING_HOST}`, {
+ *       method: 'POST',
+ *       headers: {
+ *         'Content-Type': 'application/json',
+ *         Authorization: `Bearer ${process.env.BETTERSTACK_SOURCE_TOKEN}`,
+ *       },
+ *       body: JSON.stringify(events.map(toLogRecord)),
+ *     }),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function telemetryRoute(options: TelemetryRouteOptions): (request: Request) => Promise<Response>;
+
+export { TelemetryEvent, telemetryRoute, toLogRecord, validateTelemetryEvents };
+export type { TelemetryLogRecord, TelemetryRouteOptions, ValidateTelemetryEventsOptions };

package/dist/ingest/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Receive editor telemetry on your server and forward it to a log service, such as Better Stack,
+ * Axiom, or Datadog Logs. Pair it with `httpExporter` in the browser: the browser posts to your
+ * route, and only your server holds the log service's token.
+ *
+ * Anyone can POST to a public route, so every event is checked again with the same closed lists
+ * the browser used, and fields the client chose itself are dropped unless you allow them. No
+ * dependency: Fetch API `Request` and `Response` only, so it runs in Next.js route handlers,
+ * Hono, Bun, Deno, and Cloudflare Workers.
+ *
+ * @packageDocumentation
+ */
+import { a as TelemetryEvent } from '../pipeline-DbVW7S-K.js';
+import '@docx-editor.dev/core';
+
+/** Options for {@link validateTelemetryEvents}. @public */
+interface ValidateTelemetryEventsOptions {
+    /** The most events one request may carry. Defaults to 50; a longer list is refused whole. */
+    readonly maxEvents?: number;
+    /**
+     * Keys of the browser's `resource` and `attributes` to keep, such as `['app.version']`. Each
+     * kept value must be a number, a boolean, or an identifier string. Defaults to none: a value
+     * the client chose cannot be checked for meaning, so add your fixed fields on the server.
+     */
+    readonly attributeKeys?: readonly string[];
+}
+/**
+ * The telemetry events in an untrusted request body, checked again with the package's own
+ * closed lists. An event with an unknown kind or code, or without the fields its kind needs, is
+ * dropped. A field outside its list is removed. The client's `resource` and `attributes` keep
+ * only the keys in `attributeKeys`. Returns an empty list for a body that is not an array or is
+ * longer than `maxEvents`.
+ *
+ * The check proves that every value comes from the package's lists or is a number. It cannot
+ * prove that a client told the truth: a script can send a well-formed event that never
+ * happened. It can never send text.
+ *
+ * @example
+ * ```ts
+ * const events = validateTelemetryEvents(await request.json(), { attributeKeys: ['app.version'] });
+ * ```
+ *
+ * @public
+ */
+declare function validateTelemetryEvents(body: unknown, options?: ValidateTelemetryEventsOptions): TelemetryEvent[];
+/** A log record with the fields log services read for time and summary. @public */
+type TelemetryLogRecord = Record<string, unknown> & {
+    /** The event time in milliseconds since the epoch, which Better Stack and others read. */
+    readonly dt: number;
+    /** A one-line summary, such as `edit.rejected edit.picture-selected`. */
+    readonly message: string;
+};
+/**
+ * An event as a log record: `dt` for the time, `message` for the live tail, and every field of
+ * the event except the fixed `hint` and `docs` text, which the code already identifies. Add
+ * your own fixed fields, such as a service name, to the result.
+ *
+ * @example
+ * ```ts
+ * body: JSON.stringify(events.map((event) => ({ ...toLogRecord(event), service: 'my-app' })))
+ * ```
+ *
+ * @public
+ */
+declare function toLogRecord(event: TelemetryEvent): TelemetryLogRecord;
+/** Options for {@link telemetryRoute}. @public */
+interface TelemetryRouteOptions extends ValidateTelemetryEventsOptions {
+    /** Send the checked events on, such as to your log service. Errors are caught and reported. */
+    forward(events: readonly TelemetryEvent[]): unknown;
+    /** Origins allowed to post, such as `['https://app.example.com']`. Omit to allow any. */
+    readonly allowedOrigins?: readonly string[];
+    /** The largest body accepted, in bytes. Defaults to 64 KiB. */
+    readonly maxBodyBytes?: number;
+    /** Called when `forward` throws or rejects, or the log service refuses. Defaults to nothing. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * A Fetch-style handler for telemetry from `httpExporter`: it accepts POST only, checks the
+ * origin, reads at most `maxBodyBytes`, validates every event, and calls `forward` with what
+ * passes. It answers 204 to every request, so a telemetry problem never surfaces in the
+ * editor; use `onError` to see failures. It does not rate-limit; put it behind your platform's
+ * limits.
+ *
+ * @example
+ * ```ts
+ * // Next.js: app/api/telemetry/route.ts
+ * import { telemetryRoute, toLogRecord } from '@docx-editor.dev/telemetry/ingest';
+ *
+ * export const POST = telemetryRoute({
+ *   forward: (events) =>
+ *     fetch(`https://${process.env.BETTERSTACK_INGESTING_HOST}`, {
+ *       method: 'POST',
+ *       headers: {
+ *         'Content-Type': 'application/json',
+ *         Authorization: `Bearer ${process.env.BETTERSTACK_SOURCE_TOKEN}`,
+ *       },
+ *       body: JSON.stringify(events.map(toLogRecord)),
+ *     }),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function telemetryRoute(options: TelemetryRouteOptions): (request: Request) => Promise<Response>;
+
+export { TelemetryEvent, telemetryRoute, toLogRecord, validateTelemetryEvents };
+export type { TelemetryLogRecord, TelemetryRouteOptions, ValidateTelemetryEventsOptions };

package/dist/ingest/index.js

@@ -0,0 +1 @@
+import {a,c}from'../chunk-DTEVX2XS.js';import'../chunk-DT2KMPUJ.js';var b=50,i=e=>typeof e=="string",l=e=>typeof e=="number"&&Number.isFinite(e),m=e=>typeof e=="boolean",k={"edit.rejected":[["code",i],["origin",i],["tracked",m]],"review.skipped":[["code",i],["count",l]],"font.failed":[["code",i]],history:[["code",i]],"custom-node":[["code",i]],"collab.status":[["status",i],["previous",i],["recovering",m]],"collab.participants":[["count",l]],performance:[["windowMs",l]]};function h(e){if(!l(e.schemaVersion)||!l(e.time)||!i(e.editorSessionId)||!i(e.engineVersion))return  false;if(e.kind==="document.open")return e.outcome==="opened"?i(e.sizeBucket)&&l(e.durationMs):e.outcome==="rejected"&&i(e.code);let r=k[e.kind];return !!r&&r.every(([t,o])=>o(e[t]))}function w(e,r){if(r.size===0)return {};let t=c(e)??{};return Object.fromEntries(Object.entries(t).filter(([o])=>r.has(o)))}function E(e,r={}){let t=r.maxEvents??b,o=new Set(r.attributeKeys??[]);return !Array.isArray(e)||e.length>t?[]:e.flatMap(n=>{if(!n||typeof n!="object"||Array.isArray(n))return [];let c=n,{resource:d,attributes:u,...s}=c,a$1=a(s);if("dropped"in a$1||!h(a$1.event))return [];let g=w(c.attributes,o),{attributes:x,...p}=a$1.event;return [Object.freeze({...p,resource:w(c.resource,o),attributes:g})]})}function O(e){let{hint:r,docs:t,...o}=e,n="code"in e&&e.code?` ${e.code}`:"";return {...o,dt:e.time,message:`${e.kind}${n}`}}var T=64*1024;async function R(e,r){if(Number(e.headers.get("content-length")??0)>r)return null;let t=e.body;if(!t)return "";let o=t.getReader(),n=[],c=0;for(;;){let{done:s,value:a}=await o.read();if(s)break;if(c+=a.byteLength,c>r)return await o.cancel().catch(()=>{}),null;n.push(a);}let d=new Uint8Array(c),u=0;for(let s of n)d.set(s,u),u+=s.byteLength;return new TextDecoder().decode(d)}function v(e){let r=e.maxBodyBytes??T,t=()=>new Response(null,{status:204}),o=n=>{try{e.onError?.(n);}catch{}};return async n=>{if(n.method!=="POST")return t();if(e.allowedOrigins){let s=n.headers.get("origin");if(!s||!e.allowedOrigins.includes(s))return t()}let c;try{c=await R(n,r);}catch{return t()}if(c===null)return t();let d;try{d=JSON.parse(c);}catch{return t()}let u=E(d,e);if(!u.length)return t();try{let a=await e.forward(u);if(a&&a.ok===!1)throw new Error(`the log service answered ${String(a.status)}`)}catch(s){o(s);}return t()}}export{v as telemetryRoute,O as toLogRecord,E as validateTelemetryEvents};

package/dist/otel/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunkUK2MNJCG_cjs=require('../chunk-UK2MNJCG.cjs'),chunkWGWKNKUT_cjs=require('../chunk-WGWKNKUT.cjs'),api=require('@opentelemetry/api');var w="@docx-editor.dev/telemetry";function O(o){let n=o.getDelegate?.()??o;return /^Noop/.test(n?.constructor?.name??"")}var M=false;function E(o,n){let s=chunkWGWKNKUT_cjs.a();M||s==="production"||!O(o)||!O(n)||(M=true,console.warn("[docx-editor telemetry] otelExporter found no OpenTelemetry SDK. Register a MeterProvider and a TracerProvider before creating the exporter, or pass them as options. Until then every measurement is dropped."));}function h(o,n,s){return o.createObservableGauge(n.name,{unit:n.unit,description:n.description}).addCallback(t=>{for(let{value:i,attributes:a}of s.values())t.observe(i,a);}),{record(t,i={}){s.set(f(i),{value:t,attributes:i});},forget(t){s.delete(f(t));}}}function f(o){return JSON.stringify(Object.keys(o).sort().map(n=>[n,o[n]]))}function m(o){let n={...o.resource,...o.attributes};for(let[s,t]of Object.entries(o))if(!(s==="resource"||s==="attributes"||s==="hint"||s==="docs")){if(typeof t=="string"||typeof t=="number"||typeof t=="boolean")n[`docx_editor.${s}`]=t;else if(s==="shape"&&t&&typeof t=="object")for(let[i,a]of Object.entries(t))typeof a=="string"&&(n[`docx_editor.shape.${i}`]=a);else if(t&&typeof t=="object"&&!Array.isArray(t))for(let[i,a]of Object.entries(t))typeof a=="number"&&(n[`docx_editor.${s}.${i}`]=a);}return n}function j(o={}){let n=o.scope??w,s=()=>o.meterProvider??api.metrics.getMeterProvider(),t=()=>o.tracerProvider??api.trace.getTracerProvider(),i,a,l=new Map,p=new Map,g=false;function P(e){let r=p.get(e);return r||(r=new Map,p.set(e,r)),r}function k(){let e=s();return (e!==i||!a)&&(i=e,a=e.getMeter(n),l.clear()),a}function T(e){let r=k();g||(g=true,setTimeout(()=>E(s(),t()),5e3).unref?.());let c=l.get(e.name);if(c)return c;let d={unit:e.unit,description:e.description},u=e.kind==="counter"?r.createCounter(e.name,d):e.kind==="histogram"?r.createHistogram(e.name,{...d,...e.buckets?{advice:{explicitBucketBoundaries:[...e.buckets]}}:{}}):h(r,e,P(e.name));return l.set(e.name,u),u}return {name:"otel",metric(e){let r=T(e.definition),c=e.attributes;"add"in r?r.add(e.value,c):r.record(e.value,c);},event(e){if(e.kind==="document.open"){let d=e.time-(e.outcome==="opened"?e.durationMs:0),u=t().getTracer(n).startSpan("docx_editor.document.open",{startTime:d,attributes:m(e)},o.parentContext?.());e.outcome==="rejected"&&u.setStatus({code:api.SpanStatusCode.ERROR,message:e.code}),u.end(e.time);return}let r=api.trace.getActiveSpan();if(r){r.addEvent(`docx_editor.${e.kind}`,m(e));return}if(!chunkUK2MNJCG_cjs.c(e))return;let c=t().getTracer(n).startSpan(`docx_editor.${e.kind}`,{startTime:e.time,attributes:m(e)},o.parentContext?.());c.setStatus({code:api.SpanStatusCode.ERROR,message:"code"in e?e.code:e.kind}),c.end(e.time);},forget(e,r){p.get(e.name)?.delete(f(r));},async flush(){let e=r=>(r.getDelegate?.()??r).forceFlush?.();await Promise.all([e(s()),e(t())]);}}}exports.otelExporter=j;

package/dist/otel/index.d.cts

@@ -0,0 +1,57 @@
+/**
+ * OpenTelemetry: metrics and traces through the OpenTelemetry SDK you already run. This entry
+ * depends only on `@opentelemetry/api`; your SDK decides where data goes (OTLP to a
+ * collector, Datadog, Grafana, Honeycomb, New Relic, and others).
+ *
+ * @packageDocumentation
+ */
+import { MeterProvider, TracerProvider, Context } from '@opentelemetry/api';
+import { b as TelemetryExporter } from '../pipeline-DbVW7S-K.cjs';
+import '@docx-editor.dev/core';
+
+/**
+ * OpenTelemetry: metrics and traces through the OpenTelemetry SDK you already run. This entry
+ * depends only on `@opentelemetry/api`; your SDK decides where data goes (OTLP to a
+ * collector, Datadog, Grafana, Honeycomb, New Relic, and others).
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link otelExporter}. @public */
+interface OtelExporterOptions {
+    /** Defaults to the global provider your SDK registered. */
+    readonly meterProvider?: MeterProvider;
+    /** Defaults to the global provider your SDK registered. */
+    readonly tracerProvider?: TracerProvider;
+    /**
+     * The parent of each `docx_editor.document.open` span. Browsers have no async context, so
+     * without this the span is a root span. Return your page-load or route span's context.
+     */
+    readonly parentContext?: () => Context | undefined;
+    /** Instrumentation scope name. Defaults to `@docx-editor.dev/telemetry`. */
+    readonly scope?: string;
+}
+/**
+ * Record metrics and traces with OpenTelemetry. The exporter reads the global providers at
+ * each use, so it can be created before your SDK starts.
+ *
+ * Metrics use the names in `METRICS`. Each document open becomes a
+ * `docx_editor.document.open` span, with an error status when it is refused. Other events
+ * become events on the active span; without one, a failure gets a short span of its own.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry } from '@docx-editor.dev/telemetry';
+ * import { otelExporter } from '@docx-editor.dev/telemetry/otel';
+ *
+ * // Before or after your OpenTelemetry SDK starts: the exporter reads the global providers at
+ * // each use.
+ * export const telemetry = createTelemetry({ exporters: [otelExporter()] });
+ * ```
+ *
+ * @public
+ */
+declare function otelExporter(options?: OtelExporterOptions): TelemetryExporter;
+
+export { TelemetryExporter, otelExporter };
+export type { OtelExporterOptions };