@witchpot/gmc 0.1.7 → 0.1.9

package/src/telemetry.js

@@ -0,0 +1,341 @@
+import { CLI_VERSION } from "./constants.js";
+import { buildRequestHeaders } from "./requests.js";
+
+const TELEMETRY_TIMEOUT_MS = 800;
+const TELEMETRY_ENDPOINT = "/api/v1/product-events";
+const FORMAT_OPTION_KEYS = new Set(["json", "fields", "preset", "help", "version", "format"]);
+const RAW_TEXT_KEYS = new Set(["q", "query", "title", "topic", "message", "prompt"]);
+const SENSITIVE_OPTION_KEYS = new Set([
+  "api-key",
+  "authorization",
+  "bearer",
+  "credential",
+  "key",
+  "secret",
+  "token"
+]);
+const SAFE_QUERY_VALUE_KEYS = new Set([
+  "bucket",
+  "compareBy",
+  "coverage",
+  "detail",
+  "format",
+  "focus",
+  "groupBy",
+  "includeTotal",
+  "limit",
+  "locale",
+  "maxTopicsPerGame",
+  "metric",
+  "minGames",
+  "offset",
+  "priceMax",
+  "priceMin",
+  "ratingMin",
+  "releaseFrom",
+  "releaseTo",
+  "reviewsGt",
+  "reviewsLt",
+  "reviewsMax",
+  "reviewsMin",
+  "samplePages",
+  "sampleSize",
+  "sections",
+  "sentiment",
+  "sort",
+  "source",
+  "status",
+  "tagMode",
+  "tags"
+]);
+
+export async function trackCliCommandExecuted({
+  baseUrl,
+  apiKey,
+  command,
+  options,
+  positional,
+  request,
+  response,
+  startedAt
+}) {
+  if (!apiKey || isCliTelemetryDisabled()) return;
+
+  const event = buildCliCommandTelemetryEvent({
+    command,
+    options,
+    positional,
+    request,
+    response,
+    startedAt
+  });
+
+  await sendCliTelemetryEvent(baseUrl, apiKey, event);
+}
+
+export function buildCliCommandTelemetryEvent({
+  command,
+  options = {},
+  positional = [],
+  request,
+  response,
+  startedAt,
+  now = Date.now()
+}) {
+  const appid = extractSingleAppid(request);
+  const queryInputs = collectRequestQueries(request);
+  const safeQueryValues = mergeSafeQueryValues(queryInputs);
+  const properties = compactObject({
+    source: "gmc-cli",
+    cliVersion: CLI_VERSION,
+    command: command.join(" "),
+    commandGroup: command[0],
+    commandAction: command.slice(1).join(" ") || undefined,
+    workflow: request.workflow ?? request.kind ?? "direct",
+    endpointTemplate: getPrimaryEndpointTemplate(request),
+    success: true,
+    durationMs: boundedInteger(now - startedAt),
+    outputMode: options.json ? "json" : "default",
+    optionKeys: safeOptionKeys(options),
+    filterKeys: safeFilterKeys(queryInputs),
+    hasSearchText: hasRawTextInput(options, request, positional),
+    externalIdCount: countExternalIds(request),
+    tags: normalizeTokenList(safeQueryValues.tags),
+    sections: normalizeTokenList(safeQueryValues.sections),
+    coverage: normalizeTokenList(safeQueryValues.coverage),
+    focus: safeToken(request.focus ?? safeQueryValues.focus),
+    compareBy: safeToken(request.compareBy ?? safeQueryValues.compareBy),
+    evidenceType: safeToken(request.evidenceType),
+    metric: safeToken(safeQueryValues.metric),
+    groupBy: safeToken(safeQueryValues.groupBy),
+    bucket: safeToken(safeQueryValues.bucket),
+    sort: safeToken(safeQueryValues.sort),
+    status: safeToken(safeQueryValues.status),
+    format: safeToken(safeQueryValues.format),
+    tagMode: safeToken(safeQueryValues.tagMode),
+    limit: safeNumber(safeQueryValues.limit ?? request.limit),
+    offset: safeNumber(safeQueryValues.offset),
+    minGames: safeNumber(request.minGames),
+    maxTopicsPerGame: safeNumber(request.maxTopicsPerGame),
+    sampleMode: safeToken(request.sampling?.mode),
+    sampleRequestedSize: safeNumber(request.sampling?.requestedSize),
+    sampleRequestedPages: safeNumber(request.sampling?.requestedPages),
+    samplePageLimit: safeNumber(request.sampling?.pageLimit),
+    includeTotal: Boolean(safeQueryValues.includeTotal || request.countRequest),
+    releaseFrom: safeDate(safeQueryValues.releaseFrom),
+    releaseTo: safeDate(safeQueryValues.releaseTo),
+    reviewsMin: safeNumber(safeQueryValues.reviewsMin),
+    reviewsMax: safeNumber(safeQueryValues.reviewsMax),
+    reviewsGt: safeNumber(safeQueryValues.reviewsGt),
+    reviewsLt: safeNumber(safeQueryValues.reviewsLt),
+    ratingMin: safeNumber(safeQueryValues.ratingMin),
+    priceMin: safeNumber(safeQueryValues.priceMin),
+    priceMax: safeNumber(safeQueryValues.priceMax),
+    rowCount: topLevelRowCount(response),
+    warningCount: safeWarnings(response).length,
+    lockedCount: safeLockedSections(response).length,
+    resultKind: safeToken(response?.data?.kind),
+    apiRequestId: safeShortString(response?.meta?.requestId)
+  });
+
+  return compactObject({
+    eventType: "cli_command_executed",
+    appid,
+    properties
+  });
+}
+
+export async function sendCliTelemetryEvent(baseUrl, apiKey, event, {
+  fetchImpl = globalThis.fetch,
+  timeoutMs = TELEMETRY_TIMEOUT_MS
+} = {}) {
+  if (typeof fetchImpl !== "function") return;
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const url = new URL(TELEMETRY_ENDPOINT, baseUrl);
+    await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        ...buildRequestHeaders(apiKey),
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(event),
+      signal: controller.signal
+    });
+  } catch (error) {
+    // CLI telemetry is best-effort and must never change command behavior.
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function isCliTelemetryDisabled(env = process.env) {
+  if (env.GMC_CLI_TELEMETRY != null) {
+    return /^(0|false|off|no|disabled)$/i.test(String(env.GMC_CLI_TELEMETRY));
+  }
+  if (env.GMC_DISABLE_TELEMETRY != null) {
+    return /^(1|true|on|yes|enabled)$/i.test(String(env.GMC_DISABLE_TELEMETRY));
+  }
+  return false;
+}
+
+function safeOptionKeys(options) {
+  return Object.keys(options)
+    .filter((key) => !FORMAT_OPTION_KEYS.has(key) && !SENSITIVE_OPTION_KEYS.has(key))
+    .sort()
+    .slice(0, 40);
+}
+
+function collectRequestQueries(request) {
+  return [
+    request.query,
+    request.searchRequest?.query,
+    request.countRequest?.query,
+    request.topicQuery,
+    request.detailQuery,
+    request.analysisQuery,
+    request.showcaseQuery
+  ].filter((query) => query && typeof query === "object");
+}
+
+function mergeSafeQueryValues(queries) {
+  const values = {};
+  for (const query of queries) {
+    for (const [key, value] of Object.entries(query)) {
+      if (SAFE_QUERY_VALUE_KEYS.has(key) && value != null && value !== "") values[key] = value;
+    }
+  }
+  return values;
+}
+
+function safeFilterKeys(queries) {
+  const keys = new Set();
+  for (const query of queries) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value == null || value === "" || RAW_TEXT_KEYS.has(key)) continue;
+      keys.add(key);
+    }
+  }
+  return [...keys].sort().slice(0, 40);
+}
+
+function hasRawTextInput(options, request, positional) {
+  if (Object.keys(options).some((key) => RAW_TEXT_KEYS.has(key) && options[key] != null && options[key] !== "")) {
+    return true;
+  }
+  if (typeof request.query === "string" && request.query.trim()) return true;
+  if (typeof request.topic === "string" && request.topic.trim()) return true;
+  if (request.query && typeof request.query === "object" && typeof request.query.q === "string" && request.query.q.trim()) {
+    return true;
+  }
+  if ((request.kind === "resolve" || request.workflow) && positional.some((value) => String(value).trim())) {
+    return true;
+  }
+  return false;
+}
+
+function getPrimaryEndpointTemplate(request) {
+  const path = request.path ?? request.searchRequest?.path ?? request.countRequest?.path;
+  if (!path) return undefined;
+  return templateEndpoint(path);
+}
+
+function templateEndpoint(path) {
+  return String(path)
+    .replace(/\/api\/v1\/steam\/games\/[^/]+/g, "/api/v1/steam/games/{externalId}")
+    .replace(/\/\d+(?=\/|$)/g, "/{id}");
+}
+
+function extractSingleAppid(request) {
+  const candidates = [
+    request.externalId,
+    ...(Array.isArray(request.externalIds) ? request.externalIds : []),
+    extractAppidFromPath(request.path)
+  ].filter(Boolean);
+  const unique = [...new Set(candidates.map((value) => String(value)))];
+  if (unique.length !== 1 || !/^\d+$/.test(unique[0])) return undefined;
+  const appid = Number(unique[0]);
+  return Number.isSafeInteger(appid) && appid > 0 ? appid : undefined;
+}
+
+function extractAppidFromPath(path) {
+  if (!path) return undefined;
+  const match = String(path).match(/\/api\/v1\/steam\/games\/([^/]+)/);
+  if (!match) return undefined;
+  return decodeURIComponent(match[1]);
+}
+
+function countExternalIds(request) {
+  if (Array.isArray(request.externalIds)) return request.externalIds.length;
+  if (request.externalId) return 1;
+  return extractAppidFromPath(request.path) ? 1 : 0;
+}
+
+function normalizeTokenList(value) {
+  const values = Array.isArray(value) ? value : String(value ?? "").split(",");
+  const normalized = values
+    .map((item) => safeToken(item))
+    .filter(Boolean);
+  return normalized.length ? [...new Set(normalized)].slice(0, 20) : undefined;
+}
+
+function safeToken(value) {
+  if (value == null || value === "") return undefined;
+  const normalized = String(value)
+    .trim()
+    .replace(/[^a-zA-Z0-9_.:-]/g, "_")
+    .replace(/_+/g, "_")
+    .slice(0, 80);
+  return normalized || undefined;
+}
+
+function safeShortString(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed.slice(0, 120) : undefined;
+}
+
+function safeDate(value) {
+  if (typeof value !== "string") return undefined;
+  return /^\d{4}-\d{2}-\d{2}$/.test(value) ? value : undefined;
+}
+
+function safeNumber(value) {
+  if (value == null || value === "") return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function boundedInteger(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return undefined;
+  return Math.max(0, Math.round(number));
+}
+
+function topLevelRowCount(response) {
+  if (Array.isArray(response?.data)) return response.data.length;
+  if (Array.isArray(response?.data?.games)) return response.data.games.length;
+  if (Array.isArray(response?.data?.cohort?.included)) return response.data.cohort.included.length;
+  return undefined;
+}
+
+function safeWarnings(response) {
+  if (Array.isArray(response?.warnings)) return response.warnings;
+  if (Array.isArray(response?.data?.warnings)) return response.data.warnings;
+  if (Array.isArray(response?.meta?.warnings)) return response.meta.warnings;
+  return [];
+}
+
+function safeLockedSections(response) {
+  const locked = response?.meta?.entitlements?.locked;
+  return Array.isArray(locked) ? locked : [];
+}
+
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined)
+  );
+}

package/src/telemetry.test.js

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildCliCommandTelemetryEvent,
+  isCliTelemetryDisabled,
+  sendCliTelemetryEvent
+} from "./telemetry.js";
+
+test("buildCliCommandTelemetryEvent captures safe CLI filters without raw search text", () => {
+  const event = buildCliCommandTelemetryEvent({
+    command: ["games", "search"],
+    options: {
+      source: "steam",
+      query: "cozy fishing games like Dredge",
+      tags: "cozy,fishing",
+      "reviews-min": "100",
+      "api-key": "gmc_should_not_appear",
+      json: true
+    },
+    positional: [],
+    request: {
+      path: "/api/v1/steam/games",
+      query: {
+        q: "cozy fishing games like Dredge",
+        tags: "cozy,fishing",
+        reviewsMin: "100",
+        source: "steam",
+        limit: "20"
+      }
+    },
+    response: {
+      data: [{ appid: 1 }, { appid: 2 }],
+      meta: {
+        requestId: "req_123"
+      }
+    },
+    startedAt: 1_000,
+    now: 1_250
+  });
+
+  const serialized = JSON.stringify(event);
+  assert.equal(event.eventType, "cli_command_executed");
+  assert.equal(event.properties.command, "games search");
+  assert.deepEqual(event.properties.tags, ["cozy", "fishing"]);
+  assert.equal(event.properties.reviewsMin, 100);
+  assert.equal(event.properties.hasSearchText, true);
+  assert.equal(event.properties.rowCount, 2);
+  assert.equal(event.properties.durationMs, 250);
+  assert.equal(event.properties.optionKeys.includes("api-key"), false);
+  assert.equal(serialized.includes("Dredge"), false);
+  assert.equal(serialized.includes("cozy fishing games"), false);
+  assert.equal(serialized.includes("gmc_should_not_appear"), false);
+});
+
+test("buildCliCommandTelemetryEvent templates app endpoints and attaches single appid", () => {
+  const event = buildCliCommandTelemetryEvent({
+    command: ["games", "analysis"],
+    options: {
+      source: "steam",
+      sections: "reviews,marketing",
+      json: true
+    },
+    positional: ["1384160"],
+    request: {
+      path: "/api/v1/steam/games/1384160/analysis",
+      query: {
+        sections: "reviews,marketing"
+      }
+    },
+    response: {
+      data: {
+        kind: "game_analysis"
+      },
+      meta: {
+        entitlements: {
+          locked: ["marketing.full"]
+        }
+      }
+    },
+    startedAt: 2_000,
+    now: 2_040
+  });
+
+  assert.equal(event.appid, 1384160);
+  assert.equal(event.properties.endpointTemplate, "/api/v1/steam/games/{externalId}/analysis");
+  assert.deepEqual(event.properties.sections, ["reviews", "marketing"]);
+  assert.equal(event.properties.lockedCount, 1);
+  assert.equal(event.properties.resultKind, "game_analysis");
+});
+
+test("sendCliTelemetryEvent posts product events with bearer auth and swallows failures", async () => {
+  const calls = [];
+  const fetchImpl = async (url, init) => {
+    calls.push({ url, init });
+    throw new Error("network unavailable");
+  };
+
+  await sendCliTelemetryEvent("https://example.test", "gmcc_secret", {
+    eventType: "cli_command_executed",
+    properties: {
+      source: "gmc-cli"
+    }
+  }, {
+    fetchImpl,
+    timeoutMs: 20
+  });
+
+  assert.equal(calls.length, 1);
+  assert.equal(String(calls[0].url), "https://example.test/api/v1/product-events");
+  assert.equal(calls[0].init.method, "POST");
+  assert.equal(calls[0].init.headers.authorization, "Bearer gmcc_secret");
+});
+
+test("isCliTelemetryDisabled supports opt-out environment values", () => {
+  assert.equal(isCliTelemetryDisabled({}), false);
+  assert.equal(isCliTelemetryDisabled({ GMC_CLI_TELEMETRY: "0" }), true);
+  assert.equal(isCliTelemetryDisabled({ GMC_CLI_TELEMETRY: "1" }), false);
+  assert.equal(isCliTelemetryDisabled({ GMC_DISABLE_TELEMETRY: "1" }), true);
+  assert.equal(isCliTelemetryDisabled({ GMC_CLI_TELEMETRY: "true" }), false);
+});