@docx-editor.dev/telemetry 0.0.1 → 2.29.0

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

package/dist/otel/index.d.ts

@@ -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.js';
+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 };

package/dist/otel/index.js

@@ -0,0 +1 @@
+import {c}from'../chunk-NUN46EXH.js';import {a}from'../chunk-DT2KMPUJ.js';import {SpanStatusCode,trace,metrics}from'@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=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??metrics.getMeterProvider(),t=()=>o.tracerProvider??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:SpanStatusCode.ERROR,message:e.code}),u.end(e.time);return}let r=trace.getActiveSpan();if(r){r.addEvent(`docx_editor.${e.kind}`,m(e));return}if(!c(e))return;let c$1=t().getTracer(n).startSpan(`docx_editor.${e.kind}`,{startTime:e.time,attributes:m(e)},o.parentContext?.());c$1.setStatus({code:SpanStatusCode.ERROR,message:"code"in e?e.code:e.kind}),c$1.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())]);}}}export{j as otelExporter};

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

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