feat(posthog): per-actor distinctId via clientDeviceId / twitterHandle ladder (#218)

Author: saulmc

prisma/migrations/20260516000000_add_generation_client_device_id/migration.sql

@@ -0,0 +1,5 @@
+-- AlterTable
+-- VARCHAR(128) mirrors the zod cap on the API body so the DB enforces
+-- the same contract for any non-handler write path (admin, seed, etc.).
+ALTER TABLE "AgentTemplateGeneration"
+  ADD COLUMN "clientDeviceId" VARCHAR(128);

prisma/schema.prisma

@@ -163,6 +163,7 @@ model AgentTemplateGeneration {
   idempotencyKey  String
   inputs          Json
   twitterContext  Json?
+  clientDeviceId  String?          @db.VarChar(128)
   templateId      String?          @db.Uuid
   publishStatus   PublishStatus    @default(draft)
   reply           String?          @db.Text

src/api/v2/agent-templates/handlers/generations-post.ts

@@ -162,6 +162,14 @@ const bodySchema = z
     source: z.string().min(1, "source is required"),
     inputs: inputsSchema,
     twitterContext: twitterContextSchema.optional(),
+    /** Stable per-client identifier used as the PostHog distinctId fallback
+     *  when the request isn't authenticated (anonymous web/iOS, or the
+     *  twitter-bot path before we wire Twitter user IDs). Web should pass
+     *  posthog-js's `$device_id`. Capped at 128 chars to bound storage and
+     *  prevent abuse — posthog-js generates a UUIDv7 (~36 chars). Excluded
+     *  from the idempotency dedupe body comparison (`dedupeBodiesMatch`)
+     *  so a retry with a rotated device ID still matches the original row. */
+    clientDeviceId: z.string().trim().min(1).max(128).optional(),
     publishStatus: z
       .enum(["draft", "unlisted", "published"])
       .optional()
@@ -714,6 +722,7 @@ export async function generationsPostHandler(req: Request, res: Response) {
         twitterContext: body.twitterContext
           ? (body.twitterContext as Prisma.InputJsonValue)
           : Prisma.JsonNull,
+        clientDeviceId: body.clientDeviceId ?? null,
         publishStatus: body.publishStatus,
         status: "pending",
       },

src/api/v2/agent-templates/services/generation-executor.ts

@@ -28,13 +28,17 @@ import {
   buildDeterministicFallback,
   composeReply,
 } from "@/api/v2/agent-templates/services/compose-reply";
-import { capturePostHog } from "@/api/v2/agent-templates/services/posthog";
+import {
+  capturePostHog,
+  type PostHogCaptureProperties,
+} from "@/api/v2/agent-templates/services/posthog";
 import {
   callGenerateTemplate,
   getModel,
   type GenerateTemplateInput,
 } from "@/api/v2/agent-templates/services/templateGen";
 import { GENERATION_EXECUTOR_TIMEOUT_MS, GENERATION_TTL_HOURS } from "@/config";
+import { ADMIN_ACCOUNT_ID } from "@/utils/constants";
 import logger from "@/utils/logger";
 import { prisma } from "@/utils/prisma";
 import { validateSlug } from "@/utils/reserved-slugs";
@@ -109,6 +113,65 @@ interface TwitterContext {
   idea?: string;
 }
 
+// ---------------------------------------------------------------------------
+// PostHog actor-attribution fields — shared across every capture site
+// ---------------------------------------------------------------------------
+
+/** Generation row shape consumed by `postHogBase` — the actor-attribution
+ *  inputs only. Declared as a structural subset of the Prisma row so this
+ *  helper is decoupled from the full schema. */
+interface PostHogActorSource {
+  ownerAccountId: string;
+  source: string;
+  twitterContext: unknown;
+  clientDeviceId: string | null;
+}
+
+/**
+ * Build the actor-attribution + always-on fields shared across every
+ * PostHog capture site in this pipeline. Centralised so the four sites
+ * (generate-fail, persist-fail, timeout-race-fail, success) stay in sync —
+ * adding a new actor signal only needs one edit here.
+ *
+ * `isAnonymous` is derived from the admin-account sentinel: anonymous
+ * submissions are owned by `ADMIN_ACCOUNT_ID` so the row has a valid
+ * owner FK, but the value is a system identity, not a real user.
+ * `resolveActor` in posthog.ts skips ownerAccountId when this is set.
+ */
+function postHogBase(args: {
+  generation: PostHogActorSource;
+  requestId: string;
+  inputType: "text" | "pdfBase64" | "imageBase64";
+}): Pick<
+  PostHogCaptureProperties,
+  | "requestId"
+  | "inputType"
+  | "source"
+  | "ownerAccountId"
+  | "isAnonymous"
+  | "clientDeviceId"
+  | "twitterUserId"
+> {
+  const { generation, requestId, inputType } = args;
+  const twitterCtx = generation.twitterContext as TwitterContext | null;
+  return {
+    requestId,
+    inputType,
+    source: generation.source,
+    ownerAccountId: generation.ownerAccountId,
+    isAnonymous: generation.ownerAccountId === ADMIN_ACCOUNT_ID,
+    clientDeviceId: generation.clientDeviceId ?? undefined,
+    // Lowercase + strip optional leading `@` so handle casing/format drift
+    // on the Twitter side doesn't fragment a single user across multiple
+    // PostHog persons. We don't currently have a stable numeric user ID
+    // from the twitter bot — once it's threaded through, replace this with
+    // `twitter:<numericUserId>` for true rename-resilient attribution.
+    twitterUserId: twitterCtx?.twitterHandle
+      ? twitterCtx.twitterHandle.toLowerCase().replace(/^@/, "")
+      : undefined,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Input coalescing — same priority as today's generate-template handler
 // ---------------------------------------------------------------------------
@@ -395,10 +458,7 @@ async function _runPipeline(
       promptTokens: 0,
       completionTokens: 0,
       latencyMs: Math.round(performance.now() - startTime),
-      requestId: generationId,
-      source: generation.source,
-      ownerAccountId: generation.ownerAccountId,
-      inputType,
+      ...postHogBase({ generation, requestId: generationId, inputType }),
       outcome: "failed",
     });
     throw new Error(
@@ -428,10 +488,7 @@ async function _runPipeline(
   } catch (err) {
     capturePostHog({
       ...templateResult.metrics,
-      requestId: generationId,
-      source: generation.source,
-      ownerAccountId: generation.ownerAccountId,
-      inputType,
+      ...postHogBase({ generation, requestId: generationId, inputType }),
       outcome: "failed",
     });
     throw new Error(
@@ -501,21 +558,15 @@ async function _runPipeline(
     }
     capturePostHog({
       ...templateResult.metrics,
-      requestId: generationId,
-      source: generation.source,
-      ownerAccountId: generation.ownerAccountId,
-      inputType,
+      ...postHogBase({ generation, requestId: generationId, inputType }),
       outcome: "failed",
     });
     return;
   }
 
   capturePostHog({
     ...templateResult.metrics,
-    requestId: generationId,
-    source: generation.source,
-    ownerAccountId: generation.ownerAccountId,
-    inputType,
+    ...postHogBase({ generation, requestId: generationId, inputType }),
     outcome: "done",
   });
   logger.info(

src/api/v2/agent-templates/services/posthog.ts

@@ -41,8 +41,21 @@ export interface PostHogCaptureProperties extends GenerationMetrics {
   /** Source field from the AgentTemplateGeneration row — free-form
    *  client telemetry tag (e.g. "ios-app", "web", "twitter-bot"). */
   source?: string;
-  /** Account ID of the generation owner. */
+  /** Account ID of the generation owner. Present whether or not the row
+   *  was anonymous — anonymous rows are owned by the admin sentinel. Use
+   *  `isAnonymous` to disambiguate. */
   ownerAccountId?: string;
+  /** True when the row is owned by the admin sentinel (no real account).
+   *  When true, `ownerAccountId` is NOT used for actor attribution. */
+  isAnonymous?: boolean;
+  /** Twitter user identifier (handle, lowercased, '@' stripped) when the
+   *  generation was triggered via the twitter bot. Used as a fallback
+   *  actor identifier when there's no `ownerAccountId`. */
+  twitterUserId?: string;
+  /** Stable device identifier supplied by the client (e.g. posthog-js's
+   *  `$device_id` cookie). Used as a fallback actor identifier when the
+   *  user hasn't authenticated. */
+  clientDeviceId?: string;
   /** Input type used for generation: "text", "pdfBase64", or "imageBase64". */
   inputType?: string;
   /** Terminal outcome: "done" or "failed". */
@@ -51,6 +64,63 @@ export interface PostHogCaptureProperties extends GenerationMetrics {
   authMode?: "jwt" | "agentKey";
 }
 
+// ---------------------------------------------------------------------------
+// Actor attribution — the distinctId precedence ladder
+// ---------------------------------------------------------------------------
+
+/**
+ * Kind of identifier used as `distinctId` on the event. Sent as a top-level
+ * `actorKind` property so downstream queries can segment by attribution type
+ * without parsing the distinctId string. Survives prefix-convention changes;
+ * makes post-merge analytics on aliased persons trivial.
+ */
+export type ActorKind = "account" | "device" | "twitter" | "unattributed";
+
+export interface ResolvedActor {
+  distinctId: string;
+  kind: ActorKind;
+}
+
+/**
+ * Resolve the distinctId + kind to send with the event from the available
+ * signals. Precedence:
+ *
+ *   1. `<ownerAccountId>` (real account)      — kind: `account`        — most stable.
+ *   2. `device:<clientDeviceId>`              — kind: `device`         — anonymous web/iOS.
+ *   3. `twitter:<twitterUserId>`              — kind: `twitter`        — anonymous twitter-bot.
+ *   4. `request:<requestId>`                  — kind: `unattributed`   — one-off fallback.
+ *
+ * Each non-account rung is namespaced (`device:`, `twitter:`, `request:`) so an
+ * anonymous identifier never collides with a real account UUID — which is the
+ * load-bearing property for safe `posthog.alias()` merges later: when an
+ * anonymous user authenticates, the frontend can alias `device:<X>` into the
+ * account UUID without risking a cross-person merge.
+ *
+ * Reasoning: anonymous web/twitter submissions still populate `ownerAccountId`
+ * — the route uses `ADMIN_ACCOUNT_ID` as the system-identity fallback so the
+ * row has a valid owner FK. Using that sentinel directly as distinctId would
+ * collapse every anonymous submission onto a single PostHog person and defeat
+ * the point of analytics. The executor sets `isAnonymous: true` when the
+ * owner is the sentinel so this function skips to the next rung.
+ *
+ * `kind: "unattributed"` is the honest name for rung 4 — every event in this
+ * file is a generation, so calling rung 4 "generation" would conflate event
+ * type with actor identity. `unattributed` says what's actually true: we
+ * have no stable actor signal and each event gets a one-off person.
+ */
+export function resolveActor(p: PostHogCaptureProperties): ResolvedActor {
+  if (p.ownerAccountId && !p.isAnonymous) {
+    return { distinctId: p.ownerAccountId, kind: "account" };
+  }
+  if (p.clientDeviceId) {
+    return { distinctId: `device:${p.clientDeviceId}`, kind: "device" };
+  }
+  if (p.twitterUserId) {
+    return { distinctId: `twitter:${p.twitterUserId}`, kind: "twitter" };
+  }
+  return { distinctId: `request:${p.requestId}`, kind: "unattributed" };
+}
+
 // ---------------------------------------------------------------------------
 // Lazy PostHog client singleton
 // ---------------------------------------------------------------------------
@@ -134,10 +204,13 @@ export function capturePostHog(properties: PostHogCaptureProperties): void {
     const client = getPostHogClient();
     if (!client) return; // silent no-op when env not set
 
+    const actor = resolveActor(properties);
     client.capture({
-      distinctId: "builder",
+      distinctId: actor.distinctId,
       event: BUILDER_GENERATION_COMPLETED_EVENT,
-      properties,
+      // Carry the rung as a property so dashboards can segment by
+      // attribution type without parsing prefixes off `distinct_id`.
+      properties: { ...properties, actorKind: actor.kind },
     });
   } catch (err) {
     logger.error(

tests/agent-templates.executor.test.ts

@@ -390,6 +390,10 @@ describe("generation-executor", () => {
       expect(event.requestId).toBe(gen.id);
       expect(event.source).toBe(TEST_SOURCE);
       expect(event.ownerAccountId).toBe(ADMIN_ACCOUNT_ID);
+      // Rows owned by ADMIN_ACCOUNT_ID are flagged anonymous so
+      // resolveActor in posthog.ts skips the sentinel and falls
+      // through to the next rung of the actor-attribution ladder.
+      expect(event.isAnonymous).toBe(true);
       expect(event.inputType).toBe("text");
       expect(event.outcome).toBe("done");
       expect(event.model).toBe(DEFAULT_TEST_METRICS.model);