feat: add anonymous PostHog telemetry (#342)

* feat: add anonymous PostHog telemetry

Anonymous, opt-out telemetry via PostHog (separate project from Framelink
SaaS). Captures tool_called events for get_figma_data, download_figma_images,
and the fetch CLI command, with payload size, node count, transport mode, and
sanitized error details.

- Random per-session UUID as distinct_id; PostHog GeoIP for rough unique-user
  dedup. No persistent state, no credential touching.
- Disabled by --no-telemetry, FRAMELINK_TELEMETRY=off, or DO_NOT_TRACK=1.
- One-line stderr notice on every startup.
- Figma API key/OAuth token redacted from error messages before capture.
- Graceful flush on SIGINT + SIGTERM in both stdio and HTTP modes.
- Fetch CLI uses immediate flushing (flushAt:1, flushInterval:0) for the
  short-lived process.

Bumps engines.node to >=20.0.0 (posthog-node requirement).

* refactor(telemetry): address review findings

- Discriminated union for ToolCallProperties (compile-time enforcement
  of per-tool fields; output_format now only on get_figma_data events).
- Wrap PostHog capture/shutdown in try/catch — telemetry must never break
  the tool handler's return value via a finally that throws.
- Tighten redaction min length to 8 chars to avoid garbling unrelated text
  from accidental short secrets.
- Reset initialized=false in shutdown() so tests can re-init in the same
  process.
- Extract shared get-figma-data pipeline (fetch → simplify → serialize →
  measure) into src/services/get-figma-data.ts so the MCP tool and the
  fetch CLI command don't drift. Tool uses progress hooks; CLI passes none.
- Wrap onShutdown() in try/finally inside registerShutdownHandlers so
  process.exit(0) always runs.

* chore: tighten Node engines to >=20.20.0

posthog-node 5.x requires ^20.20.0 || >=22.22.0. Match the lower bound
honestly so install doesn't fail on stale Node 20 patches that the
previous >=20.0.0 incorrectly claimed to support.

* refactor(telemetry): move telemetry to edges via onComplete hooks

Domain functions (getFigmaData, downloadFigmaImages) no longer know about
telemetry. They fire a single onComplete lifecycle callback with timing +
metrics + error; the shell wires it to telemetry (or anything else).

- src/services/get-figma-data.ts: add GetFigmaDataOutcome type and
  onComplete hook fired from a finally. Observer errors swallowed.
- src/services/download-figma-images.ts: NEW, extracts the download-plan
  dedup logic + downloadImages call from the tool handler. Same
  onComplete shape. Tool keeps param parsing, path validation, and
  result formatting (edge concerns).
- src/services/telemetry.ts: unexport captureToolCall (now internal),
  export captureGetFigmaDataCall / captureDownloadImagesCall that take
  the outcome + a small { transport, authMode } context. The tool_called
  event construction lives here in internal translator functions.
- src/mcp/tools/get-figma-data-tool.ts, download-figma-images-tool.ts,
  src/commands/fetch.ts: strip all telemetry bookkeeping (let-bindings,
  manual try/catch/finally). Shells are now thin — ~130 lines removed.

* refactor(telemetry): generic redactFromErrors, simpler init surface

- initTelemetry now takes { optOut, immediateFlush, redactFromErrors }.
  The credential-named fields (figmaApiKey, figmaOAuthToken) are gone —
  the shell just hands over any strings it wants scrubbed from error
  messages, and telemetry filters out empties internally.
- initTelemetry returns boolean (resolved enabled state), letting
  server.ts gate its disclosure notice without a separate getter.
- Move resolveTelemetryEnabled from config.ts into telemetry.ts where
  it belongs. config.ts imports it for the printout.
- Drop ServerConfig.telemetryEnabled in favor of passing the raw
  noTelemetry flag through config. Telemetry owns resolution.
- Drop the >= 8 length heuristic — the shell is the right place to
  decide what counts as a real secret, not telemetry.

* feat(telemetry): richer design-shape metrics on get_figma_data

Adds style_count, component_count, instance_count, text_node_count,
image_node_count, component_property_count, and has_variables to the
tool_called event. All computed in one extra walk of the simplified
tree plus an early-exiting walk of the raw response for variable
detection. Also splits the old node_count into raw/simplified/max_depth
and renames node_major -> nodejs_major for clarity.

* feat(telemetry): replace style_count with named_style_count

The old style_count was counting entries in globalVars.styles — our
internal dedup cache, not Figma's named/published styles. That's
redundant with the size metrics for "how visually varied is this file."

What we actually want is a signal for design-system maturity: how
many reusable named styles (from the Figma Styles panel) does this
file reference. Read directly from the raw API response's top-level
styles dict (or merged across per-node entries for GetFileNodesResponse).

* refactor: update imports for telemetry/error-meta file reorganization

Point all consumers at new locations after file moves:
- ~/services/telemetry.js -> ~/telemetry/index.js
- ~/services/error-meta.js -> ~/utils/error-meta.js
- Metric helpers extracted from get-figma-data.ts to get-figma-data-metrics.ts
- Validation capture extracted from mcp/index.ts to mcp/validation-capture.ts
- Add 429 rate-limit user-facing error in figma.ts
- Delete old src/services/telemetry.ts

* feat(telemetry): error taxonomy, phase timings, client identity, validation capture

Structured error analytics:
- tagError/getErrorMeta in utils/error-meta.ts — attaches phase, http_status,
  network_code, is_retryable to thrown errors via a Symbol key; walks the cause
  chain so wrappers preserve inner metadata
- fetch_ms/simplify_ms/serialize_ms phase timings on get_figma_data events
- client_name/client_version from MCP initialize handshake (stdio reliable,
  stateless HTTP best-effort)
- Validation reject capture via McpServer.validateToolInput monkey patch with
  structured validation_field/validation_rule; also captures path-traversal
  rejects from the download tool
- 2000-char error_message truncation
- Figma 429 rate limit message with plan-specific guidance

Bug fixes:
- Race-prone nodesProcessed module-global replaced with per-call NodeCounter
  on TraversalContext — concurrent HTTP requests no longer corrupt each other
- Opt-out init no longer poisons subsequent re-init attempts
- "Anonymous telemetry" banner updated to "Usage telemetry" (GeoIP is on)

File reorganization:
- src/telemetry/{client,capture,types,index}.ts split from services/telemetry.ts
- src/services/get-figma-data-metrics.ts extracted from get-figma-data.ts
- src/mcp/validation-capture.ts extracted from mcp/index.ts
- src/utils/error-meta.ts moved from services/

* fix(telemetry): redact before truncate, dynamic 429 guidance, pin MCP SDK

- P3 fix: move error_message truncation to client.ts so it runs AFTER secret
  redaction — a token straddling the 2000-char cutoff can no longer survive
  as a partial match.

- 429 message now reads Figma's rate-limit response headers (Retry-After,
  X-Figma-Plan-Tier, X-Figma-Rate-Limit-Type, X-Figma-Upgrade-Link) and
  gives targeted guidance based on actual seat type and plan tier, instead
  of generic "free plan → upgrade" advice.

- Pin @modelcontextprotocol/sdk to exact 1.27.1 (was ^1.27.1). The
  validation-capture monkey patch targets a private SDK method that won't
  surface as a type error if renamed — tests are the only safety net, so
  SDK upgrades should be deliberate.

* chore: upgrade @modelcontextprotocol/sdk to 1.29.0

Upgraded from 1.27.1. The validateToolInput monkey patch still works —
validation-reject integration tests pass, confirming the private method
signature hasn't changed in this release.

Author: GLips

package.json

@@ -28,7 +28,7 @@
     "prepack": "pnpm build"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.20.0"
   },
   "packageManager": "pnpm@10.10.0",
   "pnpm": {
@@ -56,12 +56,13 @@
     "@jimp/js-jpeg": "^1.6.0",
     "@jimp/js-png": "^1.6.0",
     "@jimp/plugin-crop": "^1.6.0",
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "cleye": "^2.2.1",
     "cross-env": "^7.0.3",
     "dotenv": "^16.4.7",
     "express": "^5.2.1",
     "js-yaml": "^4.1.1",
+    "posthog-node": "^5.29.2",
     "remeda": "^2.20.1",
     "undici": "^6.24.1",
     "zod": "^3.25.76"

pnpm-lock.yaml

@@ -50,6 +50,10 @@ const argv = cli({
       type: Boolean,
       description: "Run in stdio transport mode for MCP clients",
     },
+    noTelemetry: {
+      type: Boolean,
+      description: "Disable usage telemetry (telemetry is on by default)",
+    },
   },
   commands: [fetchCommand],
 });

src/bin.ts

@@ -1,13 +1,14 @@
 import { type Command, command } from "cleye";
 import { loadEnvFile, resolveAuth } from "~/config.js";
 import { FigmaService } from "~/services/figma.js";
-import {
-  simplifyRawFigmaObject,
-  allExtractors,
-  collapseSvgContainers,
-} from "~/extractors/index.js";
-import { serializeResult } from "~/utils/serialize.js";
 import { parseFigmaUrl } from "~/utils/figma-url.js";
+import {
+  initTelemetry,
+  captureGetFigmaDataCall,
+  shutdown,
+  type AuthMode,
+} from "~/telemetry/index.js";
+import { getFigmaData } from "~/services/get-figma-data.js";
 
 export const fetchCommand: Command = command(
   {
@@ -43,13 +44,19 @@ export const fetchCommand: Command = command(
         type: String,
         description: "Path to .env file",
       },
+      noTelemetry: {
+        type: Boolean,
+        description: "Disable usage telemetry",
+      },
     },
   },
   (argv) => {
-    run(argv.flags, argv._).catch((error) => {
-      console.error(error instanceof Error ? error.message : String(error));
-      process.exit(1);
-    });
+    run(argv.flags, argv._)
+      .catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+      })
+      .finally(() => shutdown());
   },
 );
 
@@ -62,6 +69,7 @@ async function run(
     figmaApiKey?: string;
     figmaOauthToken?: string;
     env?: string;
+    noTelemetry?: boolean;
   },
   positionals: string[],
 ) {
@@ -87,21 +95,25 @@ async function run(
 
   loadEnvFile(flags.env);
   const auth = resolveAuth(flags);
-  const figmaService = new FigmaService(auth);
 
-  const depth = flags.depth;
-  const rawApiResponse = nodeId
-    ? await figmaService.getRawNode(fileKey, nodeId, depth)
-    : await figmaService.getRawFile(fileKey, depth);
-
-  const simplifiedDesign = await simplifyRawFigmaObject(rawApiResponse, allExtractors, {
-    maxDepth: depth,
-    afterChildren: collapseSvgContainers,
+  // Initialize telemetry only after input validation succeeds, so every
+  // captured event corresponds to an actual fetch attempt (not a usage error).
+  initTelemetry({
+    optOut: flags.noTelemetry,
+    immediateFlush: true,
+    redactFromErrors: [auth.figmaApiKey, auth.figmaOAuthToken],
   });
 
-  const { nodes, globalVars, ...metadata } = simplifiedDesign;
-  const result = { metadata, nodes, globalVars };
-
+  const authMode: AuthMode = auth.useOAuth ? "oauth" : "api_key";
   const outputFormat = flags.json ? "json" : "yaml";
-  console.log(serializeResult(result, outputFormat));
+
+  const result = await getFigmaData(
+    new FigmaService(auth),
+    { fileKey, nodeId, depth: flags.depth },
+    outputFormat,
+    {
+      onComplete: (outcome) => captureGetFigmaDataCall(outcome, { transport: "cli", authMode }),
+    },
+  );
+  console.log(result.formatted);
 }

src/commands/fetch.ts

@@ -1,6 +1,7 @@
 import { config as loadEnv } from "dotenv";
 import { resolve as resolvePath } from "path";
 import type { FigmaAuthOptions } from "./services/figma.js";
+import { resolveTelemetryEnabled } from "./telemetry/index.js";
 
 export type Source = "cli" | "env" | "default";
 
@@ -20,6 +21,7 @@ export interface ServerFlags {
   imageDir?: string;
   proxy?: string;
   stdio?: boolean;
+  noTelemetry?: boolean;
 }
 
 export interface ServerConfig {
@@ -31,6 +33,7 @@ export interface ServerConfig {
   skipImageDownloads: boolean;
   imageDir: string;
   isStdioMode: boolean;
+  noTelemetry: boolean;
   configSources: Record<string, Source>;
 }
 
@@ -134,6 +137,14 @@ export function getServerConfig(flags: ServerFlags): ServerConfig {
 
   const isStdioMode = flags.stdio === true;
 
+  const noTelemetry = flags.noTelemetry ?? false;
+  const telemetrySource: Source =
+    flags.noTelemetry === true
+      ? "cli"
+      : process.env.FRAMELINK_TELEMETRY !== undefined || process.env.DO_NOT_TRACK !== undefined
+        ? "env"
+        : "default";
+
   const configSources: Record<string, Source> = {
     envFile: envFileSource,
     figmaApiKey: figmaApiKey.source,
@@ -144,6 +155,7 @@ export function getServerConfig(flags: ServerFlags): ServerConfig {
     outputFormat: outputFormat.source,
     skipImageDownloads: skipImageDownloads.source,
     imageDir: imageDir.source,
+    telemetry: telemetrySource,
   };
 
   if (!isStdioMode) {
@@ -168,6 +180,10 @@ export function getServerConfig(flags: ServerFlags): ServerConfig {
       `- SKIP_IMAGE_DOWNLOADS: ${skipImageDownloads.value} (source: ${configSources.skipImageDownloads})`,
     );
     console.log(`- IMAGE_DIR: ${imageDir.value} (source: ${configSources.imageDir})`);
+    const telemetryEnabled = resolveTelemetryEnabled(noTelemetry);
+    console.log(
+      `- TELEMETRY: ${telemetryEnabled ? "enabled" : "disabled"} (source: ${configSources.telemetry})`,
+    );
     console.log();
   }
 
@@ -180,6 +196,7 @@ export function getServerConfig(flags: ServerFlags): ServerConfig {
     skipImageDownloads: skipImageDownloads.value,
     imageDir: imageDir.value,
     isStdioMode,
+    noTelemetry,
     configSources,
   };
 }

src/config.ts

@@ -1,6 +1,7 @@
 // Types
 export type {
   ExtractorFn,
+  NodeCounter,
   SimplifiedNode,
   TraversalContext,
   TraversalOptions,
@@ -10,7 +11,7 @@ export type {
 } from "./types.js";
 
 // Core traversal function
-export { extractFromDesign, getNodesProcessed } from "./node-walker.js";
+export { extractFromDesign } from "./node-walker.js";
 
 // Design-level extraction (unified nodes + components)
 export { simplifyRawFigmaObject } from "./design-extractor.js";