@graphysdk/telemetry 1.8.1-beta.1786024899180

package/LICENSE.md

@@ -0,0 +1,17 @@
+# License
+
+This software is available under any of the following licenses, at your option,
+depending on which one's conditions you meet:
+
+- **PolyForm Noncommercial 1.0.0** — for noncommercial use (personal,
+  charitable, educational, research, government).
+  See [licenses/PolyForm-NonCommercial-1.0.0.md](licenses/PolyForm-NonCommercial-1.0.0.md)
+
+- **PolyForm Small Business 1.0.0** — free commercial use for organizations
+  under the size thresholds defined in the license.
+  See [licenses/PolyForm-Small-Business-1.0.0.md](licenses/PolyForm-Small-Business-1.0.0.md)
+
+- **PolyForm Free Trial 1.0.0** — a 32-day evaluation for anyone else.
+  See [licenses/PolyForm-Free-Trial-1.0.0.md](licenses/PolyForm-Free-Trial-1.0.0.md)
+
+For commercial use beyond these terms, contact [hello@graphy.dev](mailto:hello@graphy.dev) or visit [https://graphy.dev](https://graphy.dev).

package/README.md

@@ -0,0 +1,47 @@
+# @graphysdk/telemetry
+
+A **pure, push-based** telemetry module for the Graphy chart engine. It derives anonymised usage events
+from viz-engine's public compiler output (`CompiledSpec` / `CompileResult`) — it does **not** modify or
+depend on viz-engine internals, and it never touches the network, storage, or timers.
+
+Identity, opt-out policy, sampling, and beaconing (if any) live in the wrapper/host that subscribes to
+these events — not in this package.
+
+## Docs
+
+- [Quickstart](https://docs.graphy.dev/sdk-next/quickstart)
+
+## Guarantees
+
+- **No network, no storage, no timers.** The module only _derives_ and _emits_. Anything with a side
+  effect is the subscriber's job.
+- **Anonymised by construction.** Every payload carries only counts, enums, and booleans derived from
+  `CompiledSpec`. Data values, column names/labels, annotation content, and formatted strings never
+  cross the boundary. An allowlist test asserts no dataset string leaks into a serialized event.
+- **Zero-overhead when unused.** Don't wire an emitter and nothing happens. `emit` is also a no-op when
+  disabled or when nobody is subscribed.
+- **Listener isolation.** A throwing subscriber can never break the caller — each listener call is
+  wrapped in `try/catch`.
+- **Leak-safe subscriptions.** `subscribe` returns a `VizTelemetrySubscription` (with `unsubscribe()`,
+  a `closed` flag, and `[Symbol.dispose]` for `using`).
+
+## Usage
+
+```ts
+import { createCompiler } from '@graphysdk/viz-engine';
+import { createTelemetryEmitter, emitCompileEvents } from '@graphysdk/telemetry';
+
+const telemetry = createTelemetryEmitter(); // { chartInstanceId?, engineVersion?, enabled? }
+const subscription = telemetry.subscribe((event) => {
+  // Defer any beaconing — subscribers must not block.
+});
+
+const compiler = createCompiler();
+const result = compiler.compile({ input, data });
+emitCompileEvents(telemetry, result, 'compile'); // 'compile' | 'recompile' | 'command'
+
+subscription.unsubscribe();
+```
+
+In a React host, subscribe to a `GraphHandle` (`handle.subscribe()` + `handle.getCompiled()`) and
+call `deriveChartShape` / `emitCompileEvents` from the listener.

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});var m="1.8.1-beta.1786024899180",u=0;function y(e={}){f();const{chartInstanceId:t=b(),engineVersion:s=m,enabled:i=!0}=e,r=new Set;return{chartInstanceId:t,engineVersion:s,emit:a=>{if(!i||r.size===0)return;const o=[...r];for(const n of o)try{n(a)}catch{}},subscribe:a=>{r.add(a);let o=!1;const n=()=>{o||(o=!0,r.delete(a))};return{get closed(){return o},unsubscribe:n,[Symbol.dispose]:n}}}}var b=()=>`${Math.random().toString(36).slice(2,6)}${(u+=1).toString(36)}`,f=()=>{Symbol.dispose??=Symbol.for("Symbol.dispose")};function p(e){const{layers:t,coordSystem:s,scales:i,guides:r,annotations:l,spec:d}=e,a=r.colorGroups.length>0?r.colorGroups.length:null,o=t.reduce((n,g)=>n+g.data.size(),0);return{layerCount:t.length,geoms:t.map(n=>n.geom),positions:v(t.map(n=>n.position)),coordSystem:s.type,...s.type==="cartesian"?{mainAxis:s.mainAxis}:{},scaleAesthetics:Object.keys(i),seriesCount:a,observationCount:o,hasSecondaryAxis:t.some(n=>n.yScaleType==="secondary"),features:{headline:r.headline!==null,legend:r.legends.length>0,visibleAxes:r.axes.filter(n=>n.isVisible).length,dataLabels:t.some(n=>n.dataLabels.showDataLabels),highlights:d.highlights.length,annotations:C(l)}}}function S(e,t,s){if(!e)return;const i=h(e);if(t.ok){e.emit({...i,type:"chart.compiled",trigger:s,chart:p(t.compiled),warningCodes:c(t.warnings)});return}e.emit({...i,type:"chart.compile_failed",trigger:s,errorCodes:c(t.errors),warningCodes:c(t.warnings)})}function A(e,t,s){e&&e.emit({...h(e),type:"command.applied",commandType:t.type,transient:s})}var c=e=>e.map(t=>t.code),v=e=>[...new Set(e)],C=e=>({differenceArrows:e.differenceArrows.length,shapes:e.shapes.length,freeformArrows:e.arrows.length,textAnnotations:e.textAnnotations.length,images:e.images.length,stickers:e.stickers.length,pinnedNumbers:e.pinnedNumbers.length,comments:e.comments.length}),h=e=>({timestamp:Date.now(),engineVersion:e.engineVersion,chartInstanceId:e.chartInstanceId});exports.PACKAGE_VERSION=m;exports.createTelemetryEmitter=y;exports.deriveChartShape=p;exports.emitCommandApplied=A;exports.emitCompileEvents=S;

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+import { Command } from '@graphysdk/viz-engine';
+import { CompiledSpec } from '@graphysdk/viz-engine';
+import { CompileResult } from '@graphysdk/viz-engine';
+import { VizErrorCode } from '@graphysdk/viz-engine';
+
+/**
+ * Per-kind annotation counts, mirroring `CompiledAnnotations`' groups. Counts only — annotation
+ * content (text, images, positions) never enters telemetry.
+ */
+export declare interface ChartAnnotationCounts {
+    differenceArrows: number;
+    shapes: number;
+    freeformArrows: number;
+    textAnnotations: number;
+    images: number;
+    stickers: number;
+    pinnedNumbers: number;
+    comments: number;
+}
+
+/** A chart compiled successfully. Carries the anonymised {@link ChartShape} and any warning codes. */
+export declare interface ChartCompiledEvent extends VizTelemetryEventBase {
+    type: 'chart.compiled';
+    trigger: CompileTrigger;
+    chart: ChartShape;
+    /** Warning codes only — never messages, context, or suggestions. */
+    warningCodes: VizErrorCode[];
+}
+
+/** A compile failed. Carries error and warning codes only; no shape, since there is no compiled spec. */
+export declare interface ChartCompileFailedEvent extends VizTelemetryEventBase {
+    type: 'chart.compile_failed';
+    trigger: CompileTrigger;
+    errorCodes: VizErrorCode[];
+    warningCodes: VizErrorCode[];
+}
+
+/** Optional-feature usage, all counts and booleans. */
+export declare interface ChartFeatureUsage {
+    headline: boolean;
+    legend: boolean;
+    /** Number of visible axis guides. */
+    visibleAxes: number;
+    dataLabels: boolean;
+    /** Number of highlight rules on the spec. */
+    highlights: number;
+    annotations: ChartAnnotationCounts;
+}
+
+/**
+ * Anonymised "shape" of a compiled chart — counts, enums, and booleans derived from `CompiledSpec`.
+ * Never carries data values, variable names/labels, or formatted output, so it is safe to beacon.
+ */
+export declare interface ChartShape {
+    layerCount: number;
+    /** Geom names in layer order (built-in or custom plugin names). */
+    geoms: string[];
+    /** Distinct position adjusters in use (e.g. `'stack'`, `'dodge'`, `'identity'`, `'fill'`). */
+    positions: string[];
+    coordSystem: 'cartesian' | 'polar';
+    /** The main (independent) axis for a cartesian coord; absent for polar. */
+    mainAxis?: 'x' | 'y';
+    /** Scale aesthetic keys in use (e.g. `['x', 'y', 'color']`) — keys only, no values. */
+    scaleAesthetics: string[];
+    /** Discrete color-group cardinality (a count), or `null` when color is not discrete. */
+    seriesCount: number | null;
+    /** Total observations across all layers (a count only). */
+    observationCount: number;
+    hasSecondaryAxis: boolean;
+    features: ChartFeatureUsage;
+}
+
+/** A command was applied to the live spec. */
+export declare interface CommandAppliedEvent extends VizTelemetryEventBase {
+    type: 'command.applied';
+    /** The command's type discriminator (e.g. `'set-layer-geom'`). Not data-derived. */
+    commandType: string;
+    /** Whether the dispatch was transient (a live gesture frame) rather than a committed edit. */
+    transient: boolean;
+}
+
+/**
+ * How a compile was triggered. `compile` is a fresh full compile (input/palette change or first
+ * mount), `recompile` a data-only re-run against an already-resolved spec, `command` a recompile
+ * driven by an applied command.
+ */
+export declare type CompileTrigger = 'compile' | 'recompile' | 'command';
+
+/**
+ * Create a {@link VizTelemetryEmitter}. Emission is synchronous fire-and-forget: each listener call is
+ * isolated in a try/catch so a throwing subscriber can never break the caller, and `emit` is a no-op
+ * when disabled or when nobody is listening (the zero-overhead-when-unused path).
+ */
+export declare function createTelemetryEmitter(options?: CreateTelemetryEmitterOptions): VizTelemetryEmitter;
+
+/** Options for {@link createTelemetryEmitter}. */
+export declare interface CreateTelemetryEmitterOptions {
+    /** Ephemeral per-chart id stamped into each event. Defaults to a generated {@link uniqueId}. */
+    chartInstanceId?: string;
+    /** Version string stamped into each event. Defaults to this package's version ({@link PACKAGE_VERSION}). */
+    engineVersion?: string;
+    /** When `false`, {@link VizTelemetryEmitter.emit} is a no-op — a cheap host opt-out. Defaults to `true`. */
+    enabled?: boolean;
+}
+
+/**
+ * Project a {@link CompiledSpec} down to its anonymised {@link ChartShape}. Reads only counts, enums,
+ * and booleans — no data values, variable names/labels, or formatted output ever cross into the shape.
+ */
+export declare function deriveChartShape(compiled: CompiledSpec): ChartShape;
+
+/** Emit `command.applied` for an applied {@link Command}. A no-op when no `emitter` is wired. */
+export declare function emitCommandApplied(emitter: VizTelemetryEmitter | undefined, command: Command, transient: boolean): void;
+
+/**
+ * Emit the compile-lifecycle event for a finished {@link CompileResult}: `chart.compiled` with the
+ * anonymised shape and warning codes on success, or `chart.compile_failed` with error and warning
+ * codes on failure. A no-op when no `emitter` is wired.
+ */
+export declare function emitCompileEvents(emitter: VizTelemetryEmitter | undefined, result: CompileResult, trigger: CompileTrigger): void;
+
+/**
+ * This package's version, substituted at build time by the `__GRAPHY_TELEMETRY_VERSION__` replace
+ * plugin. In dev / test (unbuilt source) it stays the literal token, which is fine — telemetry only
+ * needs a string. Pass `engineVersion` to {@link createTelemetryEmitter} to report the engine version
+ * instead.
+ */
+export declare const PACKAGE_VERSION = "__GRAPHY_TELEMETRY_VERSION__";
+
+/**
+ * The module's push-based telemetry surface. It only *emits*; a subscriber (the telemetry wrapper, or
+ * enterprise infra) decides what to do with events. Pure by construction — no network, no storage, no
+ * timers, no id persistence live here.
+ */
+export declare interface VizTelemetryEmitter {
+    /** Ephemeral per-emitter id stamped into every event. NOT persisted, NOT PII. */
+    readonly chartInstanceId: string;
+    /** Version string stamped into every event. Defaults to this package's version. */
+    readonly engineVersion: string;
+    /** Fan an event out to every current listener. */
+    emit: (event: VizTelemetryEvent) => void;
+    /** Attach a listener, receiving a leak-safe {@link VizTelemetrySubscription}. */
+    subscribe: (listener: VizTelemetryListener) => VizTelemetrySubscription;
+}
+
+/** Every telemetry event, discriminated by `type`. */
+export declare type VizTelemetryEvent = ChartCompiledEvent | ChartCompileFailedEvent | CommandAppliedEvent;
+
+/**
+ * Common envelope shared by every telemetry event. Carries only low-cardinality primitives — no data
+ * values, column names, labels, or formatted strings ever cross this boundary.
+ */
+export declare interface VizTelemetryEventBase {
+    type: VizTelemetryEventType;
+    /** ms epoch, stamped at emit. */
+    timestamp: number;
+    /** Version string for the code that produced the event (defaults to this package's version). */
+    engineVersion: string;
+    /**
+     * Ephemeral per-emitter id. NOT persisted, NOT PII — a stable anonymous install id is the
+     * wrapper's job, not this module's.
+     */
+    chartInstanceId: string;
+}
+
+/** The set of telemetry event names. Extended when renderer/interaction events land. */
+export declare type VizTelemetryEventType = 'chart.compiled' | 'chart.compile_failed' | 'command.applied';
+
+/** A telemetry subscriber. Must not block — defer any beaconing off the emit path. */
+export declare type VizTelemetryListener = (event: VizTelemetryEvent) => void;
+
+/**
+ * Handle returned from {@link VizTelemetryEmitter.subscribe}. Owns its own teardown so a listener
+ * can't leak: hold the subscription, call {@link VizTelemetrySubscription.unsubscribe} (or let a
+ * `using` block dispose it) to detach.
+ */
+export declare interface VizTelemetrySubscription {
+    /** True once unsubscribed. */
+    readonly closed: boolean;
+    /** Remove the listener. Idempotent — safe to call more than once. */
+    unsubscribe: () => void;
+    /** Enables `using sub = emitter.subscribe(...)` auto-teardown. */
+    [Symbol.dispose]: () => void;
+}
+
+export { }

package/dist/index.mjs

@@ -0,0 +1,106 @@
+var p = "1.8.1-beta.1786024899180", g = 0;
+function A(e = {}) {
+  b();
+  const { chartInstanceId: n = u(), engineVersion: t = p, enabled: i = !0 } = e, r = /* @__PURE__ */ new Set();
+  return {
+    chartInstanceId: n,
+    engineVersion: t,
+    emit: (a) => {
+      if (!i || r.size === 0) return;
+      const o = [...r];
+      for (const s of o) try {
+        s(a);
+      } catch {
+      }
+    },
+    subscribe: (a) => {
+      r.add(a);
+      let o = !1;
+      const s = () => {
+        o || (o = !0, r.delete(a));
+      };
+      return {
+        get closed() {
+          return o;
+        },
+        unsubscribe: s,
+        [Symbol.dispose]: s
+      };
+    }
+  };
+}
+var u = () => `${Math.random().toString(36).slice(2, 6)}${(g += 1).toString(36)}`, b = () => {
+  Symbol.dispose ??= /* @__PURE__ */ Symbol.for("Symbol.dispose");
+};
+function y(e) {
+  const { layers: n, coordSystem: t, scales: i, guides: r, annotations: l, spec: d } = e, a = r.colorGroups.length > 0 ? r.colorGroups.length : null, o = n.reduce((s, h) => s + h.data.size(), 0);
+  return {
+    layerCount: n.length,
+    geoms: n.map((s) => s.geom),
+    positions: f(n.map((s) => s.position)),
+    coordSystem: t.type,
+    ...t.type === "cartesian" ? { mainAxis: t.mainAxis } : {},
+    scaleAesthetics: Object.keys(i),
+    seriesCount: a,
+    observationCount: o,
+    hasSecondaryAxis: n.some((s) => s.yScaleType === "secondary"),
+    features: {
+      headline: r.headline !== null,
+      legend: r.legends.length > 0,
+      visibleAxes: r.axes.filter((s) => s.isVisible).length,
+      dataLabels: n.some((s) => s.dataLabels.showDataLabels),
+      highlights: d.highlights.length,
+      annotations: S(l)
+    }
+  };
+}
+function v(e, n, t) {
+  if (!e) return;
+  const i = m(e);
+  if (n.ok) {
+    e.emit({
+      ...i,
+      type: "chart.compiled",
+      trigger: t,
+      chart: y(n.compiled),
+      warningCodes: c(n.warnings)
+    });
+    return;
+  }
+  e.emit({
+    ...i,
+    type: "chart.compile_failed",
+    trigger: t,
+    errorCodes: c(n.errors),
+    warningCodes: c(n.warnings)
+  });
+}
+function w(e, n, t) {
+  e && e.emit({
+    ...m(e),
+    type: "command.applied",
+    commandType: n.type,
+    transient: t
+  });
+}
+var c = (e) => e.map((n) => n.code), f = (e) => [...new Set(e)], S = (e) => ({
+  differenceArrows: e.differenceArrows.length,
+  shapes: e.shapes.length,
+  freeformArrows: e.arrows.length,
+  textAnnotations: e.textAnnotations.length,
+  images: e.images.length,
+  stickers: e.stickers.length,
+  pinnedNumbers: e.pinnedNumbers.length,
+  comments: e.comments.length
+}), m = (e) => ({
+  timestamp: Date.now(),
+  engineVersion: e.engineVersion,
+  chartInstanceId: e.chartInstanceId
+});
+export {
+  p as PACKAGE_VERSION,
+  A as createTelemetryEmitter,
+  y as deriveChartShape,
+  w as emitCommandApplied,
+  v as emitCompileEvents
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@graphysdk/telemetry",
+  "author": "Graphy",
+  "description": "Local event emitter for Graphy chart usage (no network)",
+  "homepage": "https://docs.graphy.dev/sdk-next/quickstart",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "keywords": [
+    "graphy",
+    "telemetry",
+    "analytics",
+    "chart",
+    "events"
+  ],
+  "version": "1.8.1-beta.1786024899180",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "peerDependencies": {
+    "@graphysdk/viz-engine": "1.8.1-beta.1786024899180"
+  },
+  "devDependencies": {
+    "@rollup/plugin-replace": "^6.0.3",
+    "rollup-plugin-node-externals": "^8.1.1",
+    "tslib": "^2.8.1",
+    "vite": "^8.1.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.0",
+    "@graphysdk/viz-engine": "1.8.1-beta.1786024899180",
+    "@graphytools/eslint-config": "0.0.1",
+    "@graphytools/eslint-plugin-graphy": "1.0.0",
+    "@graphytools/typescript-config": "0.0.1",
+    "@graphytools/vitest-config": "1.0.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,json,css,md}": [
+      "prettier --write"
+    ],
+    "*.{ts,tsx}": [
+      "eslint --max-warnings=0 --fix"
+    ]
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "TZ=utc vitest",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit"
+  }
+}