@hexclave/shared 1.0.14 → 1.0.15

package/src/hexclave-config-file.ts

@@ -100,11 +100,100 @@ function evaluateStaticConfigExpression(expression: t.Expression): unknown {
   throw new Error(`Unsupported config expression: ${unwrapped.type}`);
 }
 
+/**
+ * Like {@link parseHexclaveConfigFileContent}, but returns `null` instead of
+ * throwing when the file is not a plain static config (e.g. it wraps the config
+ * in a helper call, references imported values, or has a syntax error). Useful
+ * for deciding whether a config file can be safely regenerated deterministically
+ * or whether it has custom structure that must be preserved.
+ */
+export function tryParseHexclaveConfigFileContent(content: string, filePath: string): ParsedStackConfig | null {
+  try {
+    return parseHexclaveConfigFileContent(content, filePath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Returns whether `content` parses as a module that exports a `config` binding.
+ * Used as a lightweight structural sanity check after editing config files whose
+ * values can't be evaluated by our loader (e.g. they import external text
+ * files), where a full semantic comparison isn't possible.
+ */
+export function hexclaveConfigFileExportsConfig(content: string, filePath: string): boolean {
+  let ast: parser.ParseResult<t.File>;
+  try {
+    ast = parser.parse(content, {
+      sourceType: "module",
+      sourceFilename: filePath,
+      plugins: ["typescript", "importAttributes"],
+    });
+  } catch {
+    return false;
+  }
+  for (const statement of ast.program.body) {
+    if (!t.isExportNamedDeclaration(statement)) {
+      continue;
+    }
+    // Ignore type-only exports (`export type { config }`): they don't produce a
+    // runtime `config` value, so they must not satisfy the structural check.
+    if (statement.exportKind === "type") {
+      continue;
+    }
+    if (t.isVariableDeclaration(statement.declaration)) {
+      for (const declaration of statement.declaration.declarations) {
+        if (t.isIdentifier(declaration.id) && declaration.id.name === "config" && declaration.init != null) {
+          return true;
+        }
+      }
+    }
+    for (const specifier of statement.specifiers) {
+      if (t.isExportSpecifier(specifier) && specifier.exportKind !== "type") {
+        const exportedName = t.isIdentifier(specifier.exported) ? specifier.exported.name : specifier.exported.value;
+        if (exportedName === "config") {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Returns the relative import sources (those starting with `./` or `../`)
+ * declared in `content`. Used to discover the external files a config update may
+ * touch — e.g. `import x from "./welcome-email.tsx" with { type: "text" }` — so
+ * they can be snapshotted and rolled back if an in-place update fails. Returns
+ * an empty array if the file can't be parsed.
+ */
+export function getRelativeImportSpecifiers(content: string): string[] {
+  let ast: parser.ParseResult<t.File>;
+  try {
+    ast = parser.parse(content, {
+      sourceType: "module",
+      plugins: ["typescript", "importAttributes"],
+    });
+  } catch {
+    return [];
+  }
+  const sources: string[] = [];
+  for (const statement of ast.program.body) {
+    if (t.isImportDeclaration(statement)) {
+      const source = statement.source.value;
+      if (source.startsWith("./") || source.startsWith("../")) {
+        sources.push(source);
+      }
+    }
+  }
+  return sources;
+}
+
 export function parseHexclaveConfigFileContent(content: string, filePath: string): ParsedStackConfig {
   if (content.trim() === "") return {};
   const ast = parser.parse(content, {
     sourceType: "module",
-    plugins: ["typescript"],
+    plugins: ["typescript", "importAttributes"],
   });
 
   for (const statement of ast.program.body) {

package/src/interface/admin-interface.ts

@@ -6,7 +6,7 @@ import type { MoneyAmount } from "../utils/currency-constants";
 import type { Json } from "../utils/json";
 import { Result } from "../utils/results";
 import { urlString } from "../utils/urls";
-import type { MetricsResponse, MetricsUserCounts, UserActivityResponse } from "./admin-metrics";
+import type { AnalyticsClickmapDevice, AnalyticsClickmapKind, AnalyticsClickmapResponse, AnalyticsClickmapTokenResponse, MetricsResponse, MetricsUserCounts, UserActivityResponse } from "./admin-metrics";
 import type { AnalyticsQueryOptions, AnalyticsQueryResponse } from "./crud/analytics";
 import { EmailOutboxCrud } from "./crud/email-outbox";
 import { InternalEmailsCrud } from "./crud/emails";
@@ -435,6 +435,48 @@ export class HexclaveAdminInterface extends HexclaveServerInterface {
     return (await response.json()) as UserActivityResponse;
   }
 
+  async getAnalyticsClickmap(options: {
+    kind: AnalyticsClickmapKind,
+    member_user_ids?: string[],
+    route_path?: string,
+    route_regex?: string,
+    url_pattern?: string,
+    user_id?: string,
+    replay_id?: string,
+    device?: AnalyticsClickmapDevice,
+    viewport_width_min?: number,
+    viewport_width_max?: number,
+    sampling?: number,
+    since: string,
+    until: string,
+  }): Promise<AnalyticsClickmapResponse> {
+    const response = await this.sendAdminRequest(
+      "/internal/analytics/clickmap",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(options),
+      },
+      null,
+    );
+    return (await response.json()) as AnalyticsClickmapResponse;
+  }
+
+  async createAnalyticsClickmapToken(options: {
+    origin: string,
+  }): Promise<AnalyticsClickmapTokenResponse> {
+    const response = await this.sendAdminRequest(
+      "/internal/analytics/clickmap-token",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(options),
+      },
+      null,
+    );
+    return (await response.json()) as AnalyticsClickmapTokenResponse;
+  }
+
   async getMetricsUserCounts(): Promise<MetricsUserCounts> {
     const response = await this.sendAdminRequest(
       "/internal/metrics/user-counts",

package/src/interface/admin-metrics.ts

@@ -140,9 +140,9 @@ export const MetricsAnalyticsOverviewSchema = yupObject({
   daily_bounce_rate: yupArray(MetricsDataPointSchema).optional().default([]),
   daily_avg_session_seconds: yupArray(MetricsDataPointSchema).optional().default([]),
   // User-Agent-derived breakdowns for the analytics overview. Computed from the
-  // `data.user_agent` blob on `$page-view` events (captured client-side only,
-  // no server-side fallback). Optional + default-[] for one release cycle
-  // so older clients / servers without UA capture don't fail validation.
+  // `data.user_agent` blob on `$page-view` events, captured client-side.
+  // Optional + default-[] for one release cycle so older clients / servers
+  // without UA capture don't fail validation.
   top_browsers: yupArray(MetricsNamedCountSchema).optional().default([]),
   top_operating_systems: yupArray(MetricsNamedCountSchema).optional().default([]),
   top_devices: yupArray(MetricsNamedCountSchema).optional().default([]),
@@ -172,13 +172,77 @@ export const MetricsRecentUserSchema = yupObject({
   last_active_at_millis: yupNumber().nullable().defined(),
 }).noUnknown(false).defined();
 
-// Per-user activity heatmap — a simple list of daily event counts for a single
+// Per-user activity clickmap — a simple list of daily event counts for a single
 // user. Backed by ClickHouse `analytics_internal.events` filtered by user_id,
 // project_id, and branch_id. See `/internal/user-activity` on the backend.
 export const UserActivityResponseBodySchema = yupObject({
   data_points: MetricsDataPointsSchema,
 }).defined();
 
+export const AnalyticsClickmapKindSchema = yupString().oneOf(["team_user_hour_of_week", "session_replay_clicks"]).defined();
+export const AnalyticsClickmapDeviceSchema = yupString().oneOf(["tv", "widescreen", "desktop", "laptop", "tablet", "mobile"]).defined();
+
+export const AnalyticsClickmapTokenResponseBodySchema = yupObject({
+  token: yupString().defined(),
+  origin: yupString().defined(),
+  expires_at_millis: yupNumber().integer().defined(),
+}).defined();
+
+export const AnalyticsClickmapCellSchema = yupObject({
+  weekday: yupNumber().integer().min(1).max(7).defined(),
+  hour: yupNumber().integer().min(0).max(23).defined(),
+  value: yupNumber().integer().defined(),
+}).defined();
+
+export const AnalyticsClickmapResponseBodySchema = yupObject({
+  kind: AnalyticsClickmapKindSchema,
+  cells: yupArray(AnalyticsClickmapCellSchema).defined(),
+  // Fraction of source rows the result was computed from (1 = full scan).
+  // Returned counts are pre-scaled by 1/sampling.
+  sampling: yupNumber().min(0).max(1).optional().default(1),
+  routes: yupArray(yupObject({
+    path: yupString().defined(),
+    clicks: yupNumber().integer().defined(),
+    users: yupNumber().integer().defined(),
+    replays: yupNumber().integer().defined(),
+  }).defined()).optional().default([]),
+  users: yupArray(yupObject({
+    id: yupString().defined(),
+    display_name: yupString().nullable().defined(),
+    primary_email: yupString().nullable().defined(),
+    profile_image_url: yupString().nullable().defined(),
+    clicks: yupNumber().integer().defined(),
+    replays: yupNumber().integer().defined(),
+    last_event_at_millis: yupNumber().defined(),
+  }).defined()).optional().default([]),
+  replays: yupArray(yupObject({
+    id: yupString().defined(),
+    user_id: yupString().nullable().defined(),
+    route_path: yupString().nullable().defined(),
+    viewport_width: yupNumber().integer().nullable().defined(),
+    viewport_height: yupNumber().integer().nullable().defined(),
+    clicks: yupNumber().integer().defined(),
+    last_event_at_millis: yupNumber().defined(),
+  }).defined()).optional().default([]),
+  selectors: yupArray(yupObject({
+    selector: yupString().defined(),
+    clicks: yupNumber().integer().defined(),
+  }).defined()).optional().default([]),
+  // PostHog-style aggregated element identities. Resilient to DOM drift
+  // because the chain encodes ancestor tags/classes/attrs/text rather than
+  // a positional CSS selector.
+  elements: yupArray(yupObject({
+    elements_chain: yupString().defined(),
+    elements_text: yupString().defined(),
+    tag_name: yupString().defined(),
+    href: yupString().nullable().defined(),
+    clicks: yupNumber().integer().defined(),
+    // Optional for one release cycle so new overlay clients can validate
+    // responses from older servers that only returned aggregate click counts.
+    dead_clicks: yupNumber().integer().optional().default(0),
+  }).defined()).optional().default([]),
+}).defined();
+
 // Recent "currently live" users keyed by ISO country code. Populated by
 // joining a bounded ClickHouse selection from the live `$token-refresh` window
 // with the corresponding Prisma profile rows, so the overview globe can render
@@ -243,3 +307,27 @@ export type MetricsRecentUser = yup.InferType<typeof MetricsRecentUserSchema>;
 export type MetricsResponse = yup.InferType<typeof MetricsResponseBodySchema>;
 export type MetricsUserCounts = yup.InferType<typeof MetricsUserCountsSchema>;
 export type UserActivityResponse = yup.InferType<typeof UserActivityResponseBodySchema>;
+export type AnalyticsClickmapKind = yup.InferType<typeof AnalyticsClickmapKindSchema>;
+export type AnalyticsClickmapDevice = yup.InferType<typeof AnalyticsClickmapDeviceSchema>;
+export type AnalyticsClickmapCell = yup.InferType<typeof AnalyticsClickmapCellSchema>;
+export type AnalyticsClickmapResponse = yup.InferType<typeof AnalyticsClickmapResponseBodySchema>;
+export type AnalyticsClickmapTokenResponse = yup.InferType<typeof AnalyticsClickmapTokenResponseBodySchema>;
+
+// Single (camelCase) options shape for the clickmap SDK surface — shared by the
+// StackAdminApp interface and its implementation so the two can't drift. The
+// HexclaveAdminInterface transport layer maps these to the snake_case request body.
+export type AnalyticsClickmapOptions = {
+  kind: AnalyticsClickmapKind,
+  memberUserIds?: string[],
+  routePath?: string,
+  routeRegex?: string,
+  urlPattern?: string,
+  userId?: string,
+  replayId?: string,
+  device?: AnalyticsClickmapDevice,
+  viewportWidthMin?: number,
+  viewportWidthMax?: number,
+  sampling?: number,
+  since: string,
+  until: string,
+};

package/src/utils/analytics-clickmap-overlay.tsx

@@ -0,0 +1,15 @@
+/**
+ * Wire protocol for handing a clickmap overlay token from the dashboard to the
+ * in-page dev tool via `sessionStorage` + a window event.
+ *
+ * The token is a self-describing JWT: its payload already carries the
+ * `project_id` and `origin` it was minted for, so the reader derives both from
+ * the token itself and the writer only has to hand over a single value. The
+ * dashboard (writer) and the dev tool (reader) live in different packages but
+ * must agree on these exact names — this module is the single source of truth so
+ * they can never silently desync.
+ */
+
+export const CLICKMAP_OVERLAY_TOKEN_STORAGE_KEY = "hexclave-clickmap-token";
+export const CLICKMAP_OVERLAY_RESUME_STORAGE_KEY = "hexclave-clickmap-resume";
+export const CLICKMAP_OVERLAY_TOKEN_UPDATED_EVENT = "hexclave:clickmap-token-updated";

package/src/utils/dev-tool.tsx

@@ -0,0 +1,30 @@
+/**
+ * Shared identity of the Hexclave in-page dev tool / clickmap overlay.
+ *
+ * These constants are the single source of truth for "is this DOM / event /
+ * stored click part of the dev tool itself?". They are consumed across package
+ * boundaries:
+ *  - the dev tool mounts its root element with {@link DEV_TOOL_ROOT_ID} and
+ *    prefixes every generated class with {@link DEV_TOOL_CLASS_PREFIX};
+ *  - the event tracker uses them to skip self-clicks at ingest;
+ *  - the backend clickmap query uses them to filter dev-tool clicks out of
+ *    aggregate clickmaps server-side.
+ *
+ * Keep them here so a rename can never silently desync the SQL filter from the
+ * actual DOM identity.
+ */
+export const DEV_TOOL_ROOT_ID = "__hexclave-dev-tool-root";
+
+/**
+ * Root element id of the standalone clickmap overlay. The clickmap is an
+ * independent feature with its own mount (it must survive the dev tool being
+ * removed), so it gets its own root — but its self-clicks need the exact same
+ * ingest/query exclusions as the dev tool's.
+ */
+export const CLICKMAP_ROOT_ID = "__hexclave-clickmap-root";
+
+/** Prefix applied to every class/generated id the dev tool renders. */
+export const DEV_TOOL_CLASS_PREFIX = "sdt-";
+
+/** Legacy class marker still present on older dev-tool builds. */
+export const DEV_TOOL_LEGACY_CLASS = "stack-devtool";

package/src/utils/dom.tsx

@@ -5,3 +5,45 @@ export function hasClickableParent(element: HTMLElement): boolean {
 
   return hasClickableParent(element.parentElement);
 }
+
+/**
+ * Escape a string so it is safe to use as a CSS identifier (id/class) inside a selector.
+ * Prefers the native `CSS.escape` when available, falling back to a conservative
+ * backslash-escape for non-DOM environments (SSR, tests, older runtimes).
+ */
+export function cssEscapeIdent(value: string): string {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+
+  let escaped = "";
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value.charAt(i);
+    const codeUnit = value.charCodeAt(i);
+
+    if (codeUnit === 0x0000) {
+      escaped += "\uFFFD";
+    } else if (
+      (codeUnit >= 0x0001 && codeUnit <= 0x001f) ||
+      codeUnit === 0x007f ||
+      (i === 0 && codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
+      (i === 1 && codeUnit >= 0x0030 && codeUnit <= 0x0039 && value.charCodeAt(0) === 0x002d)
+    ) {
+      escaped += `\\${codeUnit.toString(16)} `;
+    } else if (i === 0 && codeUnit === 0x002d && value.length === 1) {
+      escaped += "\\-";
+    } else if (
+      codeUnit >= 0x0080 ||
+      codeUnit === 0x002d ||
+      codeUnit === 0x005f ||
+      (codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
+      (codeUnit >= 0x0041 && codeUnit <= 0x005a) ||
+      (codeUnit >= 0x0061 && codeUnit <= 0x007a)
+    ) {
+      escaped += char;
+    } else {
+      escaped += `\\${char}`;
+    }
+  }
+  return escaped;
+}