@hogsend/engine 0.36.0 → 0.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.36.0",
3
+ "version": "0.37.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -42,14 +42,14 @@
42
42
  "svix": "^1.95.1",
43
43
  "winston": "^3.19.0",
44
44
  "zod": "^4.4.3",
45
- "@hogsend/core": "^0.36.0",
46
- "@hogsend/db": "^0.36.0",
47
- "@hogsend/email": "^0.36.0",
48
- "@hogsend/plugin-posthog": "^0.36.0",
49
- "@hogsend/plugin-resend": "^0.36.0"
45
+ "@hogsend/core": "^0.37.0",
46
+ "@hogsend/db": "^0.37.0",
47
+ "@hogsend/email": "^0.37.0",
48
+ "@hogsend/plugin-posthog": "^0.37.0",
49
+ "@hogsend/plugin-resend": "^0.37.0"
50
50
  },
51
51
  "optionalDependencies": {
52
- "@hogsend/plugin-postmark": "^0.36.0"
52
+ "@hogsend/plugin-postmark": "^0.37.0"
53
53
  },
54
54
  "devDependencies": {
55
55
  "@types/node": "^22.15.3",
package/src/index.ts CHANGED
@@ -435,6 +435,8 @@ export {
435
435
  SEMANTIC_BURST_WINDOW_MS,
436
436
  } from "./lib/semantic-click.js";
437
437
  export { type MountStudioResult, mountStudio } from "./lib/studio.js";
438
+ // --- In-app survey/rating (sendSurvey — producer sugar over sendFeedItem) ---
439
+ export { type SendSurveyOptions, sendSurvey } from "./lib/survey.js";
438
440
  export {
439
441
  type ResolveTimezoneInput,
440
442
  type ResolveTimezoneResult,
@@ -34,6 +34,23 @@ export class PublishableAnonymousMergeError extends Error {
34
34
  }
35
35
  }
36
36
 
37
+ /**
38
+ * Thrown by {@link resolveOrCreateContact}'s engine-internal `contactId` pin when
39
+ * the pinned subject row no longer exists and no merge-alias chain leads to a live
40
+ * survivor (the subject was hard-deleted). The internal re-emit is then dropped
41
+ * (ingestEvent returns `{ stored: false }`, logs `identity.provenance.lost`) rather
42
+ * than value-resolving — a value fall-back could mint the very phantom twin the
43
+ * pin exists to prevent. Reachable ONLY for a hard-deleted/unfollowable subject.
44
+ */
45
+ export class ContactProvenanceLostError extends Error {
46
+ constructor(public readonly contactId: string) {
47
+ super(
48
+ `contact provenance lost: no live contact or survivor for ${contactId}`,
49
+ );
50
+ this.name = "ContactProvenanceLostError";
51
+ }
52
+ }
53
+
37
54
  /**
38
55
  * The transaction handle drizzle hands to a `db.transaction(cb)` callback. It
39
56
  * exposes the same `.select/.insert/.update/.execute/.query` surface as the
@@ -211,6 +228,93 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
211
228
  return null;
212
229
  }
213
230
 
231
+ /**
232
+ * ENGINE-INTERNAL provenance pin (see {@link resolveOrCreateContact}'s
233
+ * `contactId`). Resolve to the EXACT subject row by its unforgeable uuid PK and
234
+ * fold there — never value-probing, never minting. Serializes on the row PK via
235
+ * `FOR UPDATE`, so a concurrent collide-MERGE that soft-deletes this row as a
236
+ * loser blocks on / is observed by this pin (rather than racing the mismatched
237
+ * `external:value` vs `anonymous:value` advisory locks). If the row was merged
238
+ * away (soft-deleted), follow the server-authored merge-alias chain to the live
239
+ * SURVIVOR by row id — independent of alias kind/value, closing the post-merge
240
+ * anon-alias residual. A hard-deleted/unfollowable subject throws
241
+ * {@link ContactProvenanceLostError} (the caller drops the event, never mints).
242
+ */
243
+ async function resolveByContactId(
244
+ tx: Tx,
245
+ contactId: string,
246
+ ctx: { patch: Record<string, unknown>; hasPatch: boolean },
247
+ ): Promise<{
248
+ id: string;
249
+ resolvedKey: string;
250
+ created: boolean;
251
+ linked: boolean;
252
+ merged: boolean;
253
+ }> {
254
+ let row: ContactRow | null =
255
+ (
256
+ await tx
257
+ .select()
258
+ .from(contacts)
259
+ .where(eq(contacts.id, contactId))
260
+ .for("update")
261
+ .limit(1)
262
+ )[0] ?? null;
263
+ if (!row || row.deletedAt) {
264
+ row = await followToSurvivor(tx, contactId);
265
+ }
266
+ if (!row) throw new ContactProvenanceLostError(contactId);
267
+ const set: Record<string, unknown> = {
268
+ lastSeenAt: new Date(),
269
+ updatedAt: new Date(),
270
+ };
271
+ if (ctx.hasPatch) set.properties = mergePropertiesSql(ctx.patch);
272
+ await tx.update(contacts).set(set).where(eq(contacts.id, row.id));
273
+ return {
274
+ id: row.id,
275
+ resolvedKey: contactKey(row),
276
+ created: false,
277
+ linked: false,
278
+ merged: false,
279
+ };
280
+ }
281
+
282
+ /**
283
+ * Follow the server-authored merge-alias chain from a (soft-deleted loser)
284
+ * `contacts.id` to the live SURVIVOR row, re-locking each hop `FOR UPDATE`.
285
+ * Bounded (merge-of-a-merge) to a small cap. Keyed on `from_contact_id` — the
286
+ * unforgeable row id, never a value — so an attacker-plantable key can never
287
+ * steer it. Returns the live survivor or null (hard-deleted / chain broken).
288
+ */
289
+ async function followToSurvivor(
290
+ tx: Tx,
291
+ lostId: string,
292
+ ): Promise<ContactRow | null> {
293
+ let cursor = lostId;
294
+ for (let i = 0; i < 8; i++) {
295
+ const alias = (
296
+ await tx
297
+ .select({ contactId: contactAliases.contactId })
298
+ .from(contactAliases)
299
+ .where(eq(contactAliases.fromContactId, cursor))
300
+ .limit(1)
301
+ )[0];
302
+ if (!alias?.contactId) return null;
303
+ const survivor: ContactRow | undefined = (
304
+ await tx
305
+ .select()
306
+ .from(contacts)
307
+ .where(eq(contacts.id, alias.contactId))
308
+ .for("update")
309
+ .limit(1)
310
+ )[0];
311
+ if (!survivor) return null;
312
+ if (!survivor.deletedAt) return survivor;
313
+ cursor = alias.contactId;
314
+ }
315
+ return null;
316
+ }
317
+
214
318
  /**
215
319
  * Top-level property keys whose object value is DEEP-merged (one level) rather
216
320
  * than wholly replaced. The §2.1 shallow `||` contract clobbers a top-level key
@@ -374,6 +478,21 @@ export async function resolveOrCreateContact(opts: {
374
478
  * secret-key path NEVER sets this, so its behavior is byte-for-byte unchanged.
375
479
  */
376
480
  restrictToAnonymous?: boolean;
481
+ /**
482
+ * ENGINE-INTERNAL provenance — the subject contact's UNFORGEABLE row id
483
+ * (`contacts.id`, a server-minted uuid). Set ONLY by engine-internal re-emit
484
+ * sites that already resolved the subject (ingestEvent's downstream re-ingests,
485
+ * the feed mark/clear re-ingests, journey/bucket re-emits). When present (and
486
+ * uuid-shaped, and not a clamped publishable write), the resolver PINS to that
487
+ * exact row — never value-resolving, never minting — so an internal event whose
488
+ * `userId` is a contact's own canonical key (its anonymous_id/id round-tripping)
489
+ * folds back into that contact instead of minting a phantom `external_id` twin.
490
+ * NEVER settable from a request body: the public `/v1/events`/`/v1/contacts`/
491
+ * `/v1/feed` Zod schemas omit it and their handlers build the resolve call
492
+ * literally, so an attacker cannot forge provenance. Mutually exclusive with
493
+ * `restrictToAnonymous`.
494
+ */
495
+ contactId?: string;
377
496
  }): Promise<{
378
497
  id: string;
379
498
  /**
@@ -409,6 +528,7 @@ export async function resolveOrCreateContact(opts: {
409
528
  const email = opts.email ? normalizeEmail(opts.email) : undefined;
410
529
  const anonymousId = opts.anonymousId?.trim() || undefined;
411
530
  const discordId = opts.discordId?.trim() || undefined;
531
+ const contactId = opts.contactId?.trim() || undefined;
412
532
  // §Phase 1 GAP-1: the publishable clamp only bites an ANON-ONLY write (the
413
533
  // only shape a token-less pk_ key can produce — the gate 403s any
414
534
  // email/userId without a verified userToken before we get here). An identified
@@ -437,6 +557,18 @@ export async function resolveOrCreateContact(opts: {
437
557
  const hasPatch = Object.keys(patch).length > 0;
438
558
 
439
559
  return db.transaction(async (tx) => {
560
+ // (−1) ENGINE-INTERNAL PROVENANCE PIN. A uuid-shaped `contactId` from a
561
+ // trusted internal re-emit pins resolution to that exact row (no value-key
562
+ // probe, no mint), so a contact's own canonical key round-tripping back as a
563
+ // `userId` folds into it instead of minting a phantom `external_id` twin.
564
+ // Gated on `!restrictToAnonymous` (mutually exclusive with the publishable
565
+ // clamp — a clamped pk_ write can never carry provenance) so it is never an
566
+ // attacker-reachable path. Runs BEFORE the value-key advisory locks: the pin
567
+ // serializes on the concrete row PK via `FOR UPDATE`, not on value locks.
568
+ if (contactId && UUID_REGEX.test(contactId) && !restrictToAnonymous) {
569
+ return resolveByContactId(tx, contactId, { patch, hasPatch });
570
+ }
571
+
440
572
  // (0) Advisory locks per key — serialize concurrent resolves on the same
441
573
  // identity so the INSERT race can't mint duplicates. Sorted to keep a stable
442
574
  // acquisition order across callers (deadlock-safe).
@@ -16,7 +16,10 @@ import {
16
16
  getAnalytics,
17
17
  getAnalyticsEventMirror,
18
18
  } from "./analytics-singleton.js";
19
- import { resolveOrCreateContact } from "./contacts.js";
19
+ import {
20
+ ContactProvenanceLostError,
21
+ resolveOrCreateContact,
22
+ } from "./contacts.js";
20
23
  import type { Logger } from "./logger.js";
21
24
 
22
25
  export interface IngestEvent {
@@ -26,6 +29,16 @@ export interface IngestEvent {
26
29
  userEmail?: string;
27
30
  /** D1: future anonymous→identified path. Threaded into the resolver. */
28
31
  anonymousId?: string;
32
+ /**
33
+ * ENGINE-INTERNAL provenance — the subject contact's unforgeable row id
34
+ * (`contacts.id`). Set ONLY by engine-internal re-emit sites that already
35
+ * resolved the subject (this fn's own downstream re-ingests, the feed
36
+ * mark/clear re-ingests). Pins the resolver to that exact row so a contact's
37
+ * own canonical key round-tripping as `userId` folds back in instead of minting
38
+ * a phantom `external_id` twin. NEVER set from a request body (the public route
39
+ * schemas omit it); the public/publishable boundary cannot forge it.
40
+ */
41
+ contactId?: string;
29
42
  /**
30
43
  * Discord user id (snowflake). Resolves a `discord`-keyed contact (a later
31
44
  * per-member link merges it into the email contact).
@@ -185,21 +198,46 @@ export async function ingestEvent(opts: {
185
198
  // `contacts.properties` (D2 split) and returns BOTH the canonical contact id
186
199
  // AND its resolved string key (external_id ?? anonymous_id ?? contact.id —
187
200
  // risk 1/6), so no second read-back of the contact row is needed.
201
+ let resolved: Awaited<ReturnType<typeof resolveOrCreateContact>>;
202
+ try {
203
+ resolved = await resolveOrCreateContact({
204
+ db,
205
+ userId: event.userId,
206
+ email: event.userEmail || undefined,
207
+ anonymousId: event.anonymousId,
208
+ discordId: event.discordId,
209
+ // ENGINE-INTERNAL provenance pin (never from a request body — public route
210
+ // schemas omit it). Pins to the subject's own row so an internal re-emit
211
+ // whose userId is the contact's canonical key folds in, not a phantom twin.
212
+ contactId: event.contactId,
213
+ contactProperties: event.contactProperties,
214
+ restrictToAnonymous: opts.restrictToAnonymous,
215
+ });
216
+ } catch (err) {
217
+ // Provenance pin pointed at a hard-deleted/unfollowable subject: drop the
218
+ // internal re-emit (do NOT value-fall-back — that could mint the very twin
219
+ // the pin prevents). Reachable only for a hard-deleted subject.
220
+ if (err instanceof ContactProvenanceLostError) {
221
+ logger.warn("identity.provenance.lost — dropping internal re-emit", {
222
+ event: event.event,
223
+ contactId: err.contactId,
224
+ source: event.source ?? null,
225
+ });
226
+ return {
227
+ stored: false,
228
+ exits: [],
229
+ contactKey: event.userId ?? event.anonymousId ?? err.contactId,
230
+ };
231
+ }
232
+ throw err;
233
+ }
188
234
  const {
189
235
  id: contactId,
190
236
  resolvedKey,
191
237
  mergedKeys,
192
238
  mergedIdentifiedKeys,
193
239
  merged,
194
- } = await resolveOrCreateContact({
195
- db,
196
- userId: event.userId,
197
- email: event.userEmail || undefined,
198
- anonymousId: event.anonymousId,
199
- discordId: event.discordId,
200
- contactProperties: event.contactProperties,
201
- restrictToAnonymous: opts.restrictToAnonymous,
202
- });
240
+ } = resolved;
203
241
 
204
242
  // Caller-supplied event time (backfill/replay). Coerced to a Date; undefined
205
243
  // falls back to the `occurred_at` DB default (ingest instant).
@@ -327,6 +365,11 @@ export async function ingestEvent(opts: {
327
365
  userId: resolvedKey,
328
366
  userEmail: event.userEmail ?? "",
329
367
  properties: serializableProperties,
368
+ // ENGINE-INTERNAL provenance: the resolved subject row id, so a journey
369
+ // enrolling on this event can re-emit for the SAME subject by row id
370
+ // (folds, never mints a twin). Additive/optional — consumers ignoring it
371
+ // are unaffected.
372
+ contactId,
330
373
  }),
331
374
  checkExits(db, registry, hatchet, logger, {
332
375
  userId: resolvedKey,
@@ -0,0 +1,50 @@
1
+ import type { FeedBlock } from "@hogsend/db";
2
+ import { type SendFeedItemResult, sendFeedItem } from "./feed.js";
3
+
4
+ /** The survey block's own fields (event/mode/property/…), minus the discriminant. */
5
+ type SurveyBlockFields = Omit<Extract<FeedBlock, { type: "survey" }>, "type">;
6
+
7
+ /**
8
+ * Options for {@link sendSurvey} — the producer sugar that drops a `survey`
9
+ * feed block into a recipient's in-app feed. Thin over {@link sendFeedItem}, so
10
+ * it inherits the full pipeline (recipient resolution, `in_app` suppression,
11
+ * replay-safe idempotency, Redis realtime publish).
12
+ */
13
+ export interface SendSurveyOptions extends SurveyBlockFields {
14
+ recipient: { userId?: string; email?: string; anonymousId?: string };
15
+ title?: string;
16
+ category?: string;
17
+ idempotencyKey?: string;
18
+ idempotencyLabel?: string;
19
+ }
20
+
21
+ /**
22
+ * Journey-callable in-app survey send — producer sugar over {@link sendFeedItem}.
23
+ * Builds a single `survey` feed block from `opts` and delegates, so the in-app
24
+ * survey/rating primitive gets the SAME exactly-once replay-safety and `in_app`
25
+ * suppression as any other feed send. The answer the recipient picks is captured
26
+ * onto the spine by `<SurveyBlockView>` and lands in `user_events` — readable by
27
+ * a journey via `ctx.waitForEvent → properties` and by
28
+ * `GET /v1/admin/reporting/breakdown`.
29
+ */
30
+ export function sendSurvey(
31
+ opts: SendSurveyOptions,
32
+ ): Promise<SendFeedItemResult> {
33
+ const {
34
+ recipient,
35
+ title,
36
+ category,
37
+ idempotencyKey,
38
+ idempotencyLabel,
39
+ ...survey
40
+ } = opts;
41
+ return sendFeedItem({
42
+ recipient,
43
+ type: "survey",
44
+ ...(title !== undefined ? { title } : {}),
45
+ blocks: [{ type: "survey", ...survey }],
46
+ ...(category !== undefined ? { category } : {}),
47
+ ...(idempotencyKey !== undefined ? { idempotencyKey } : {}),
48
+ ...(idempotencyLabel !== undefined ? { idempotencyLabel } : {}),
49
+ });
50
+ }
@@ -1,4 +1,4 @@
1
- import { emailSends } from "@hogsend/db";
1
+ import { emailSends, userEvents } from "@hogsend/db";
2
2
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
3
  import {
4
4
  and,
@@ -143,6 +143,47 @@ const contactActivityRoute = createRoute({
143
143
  },
144
144
  });
145
145
 
146
+ // ---------------------------------------------------------------------------
147
+ // GET /breakdown — aggregate ANY event by a scalar property value (count,
148
+ // average, optional NPS) over user_events.properties. Surveys are one caller.
149
+ // ---------------------------------------------------------------------------
150
+
151
+ const breakdownRoute = createRoute({
152
+ method: "get",
153
+ path: "/breakdown",
154
+ tags: ["Admin — Reporting"],
155
+ summary:
156
+ "Aggregate any event by a property value (count, average, optional NPS)",
157
+ request: {
158
+ query: z.object({
159
+ event: z.string().min(1),
160
+ property: z.string().default("value"),
161
+ from: z.string().datetime().optional(),
162
+ to: z.string().datetime().optional(),
163
+ metric: z.enum(["nps"]).optional(),
164
+ }),
165
+ },
166
+ responses: {
167
+ 200: {
168
+ content: {
169
+ "application/json": {
170
+ schema: z.object({
171
+ event: z.string(),
172
+ property: z.string(),
173
+ total: z.number(),
174
+ breakdown: z.array(
175
+ z.object({ answer: z.string(), count: z.number() }),
176
+ ),
177
+ average: z.number().nullable(),
178
+ nps: z.number().nullable(),
179
+ }),
180
+ },
181
+ },
182
+ description: "Per-answer counts plus computed average / NPS",
183
+ },
184
+ },
185
+ });
186
+
146
187
  const MAX_EXPORT_ROWS = 50_000;
147
188
 
148
189
  function csvCell(value: unknown): string {
@@ -282,6 +323,78 @@ export const reportingRouter = new OpenAPIHono<AppEnv>()
282
323
  },
283
324
  200,
284
325
  );
326
+ })
327
+ .openapi(breakdownRoute, async (c) => {
328
+ const { db } = c.get("container");
329
+ const { event, property, from, to, metric } = c.req.valid("query");
330
+
331
+ // GROUP BY user_events.properties ->> '<property>'. The property key is a
332
+ // bound parameter (never interpolated); the `::text` cast disambiguates
333
+ // `->>` from its integer (array-index) overload so Postgres can resolve it.
334
+ const answerExpr = sql<string>`${userEvents.properties} ->> ${property}::text`;
335
+
336
+ const conditions = [
337
+ eq(userEvents.event, event),
338
+ sql`${answerExpr} is not null`,
339
+ ];
340
+ if (from) conditions.push(gte(userEvents.occurredAt, new Date(from)));
341
+ if (to) conditions.push(lte(userEvents.occurredAt, new Date(to)));
342
+
343
+ // GROUP BY / ORDER BY the first output column by ordinal (the spec's
344
+ // `GROUP BY 1 ORDER BY 1`) — matching the grouped expression by position
345
+ // avoids Postgres treating the repeated `->>` param as a distinct column.
346
+ const rows = await db
347
+ .select({ answer: answerExpr, count: count() })
348
+ .from(userEvents)
349
+ .where(and(...conditions))
350
+ .groupBy(sql`1`)
351
+ .orderBy(sql`1`);
352
+
353
+ const breakdown = rows.map((r) => ({
354
+ answer: String(r.answer),
355
+ count: Number(r.count),
356
+ }));
357
+ const total = breakdown.reduce((sum, b) => sum + b.count, 0);
358
+
359
+ // average = Σ(numeric(answer) * count) / total — only when EVERY answer
360
+ // parses numeric (else null). NaN/empty short-circuits to non-numeric.
361
+ let numericSum = 0;
362
+ let allNumeric = breakdown.length > 0;
363
+ for (const b of breakdown) {
364
+ const n = Number(b.answer);
365
+ if (b.answer === "" || Number.isNaN(n)) {
366
+ allNumeric = false;
367
+ break;
368
+ }
369
+ numericSum += n * b.count;
370
+ }
371
+ const average =
372
+ allNumeric && total > 0
373
+ ? Math.round((numericSum / total) * 100) / 100
374
+ : null;
375
+
376
+ // nps = %(answer ∈ 9..10) − %(answer ∈ 0..6), when metric === "nps" or the
377
+ // answers look like a 0..10 integer scale (else null).
378
+ const looks0to10 =
379
+ allNumeric &&
380
+ breakdown.length > 0 &&
381
+ breakdown.every((b) => {
382
+ const n = Number(b.answer);
383
+ return Number.isInteger(n) && n >= 0 && n <= 10;
384
+ });
385
+ let nps: number | null = null;
386
+ if ((metric === "nps" || looks0to10) && allNumeric && total > 0) {
387
+ let promoters = 0;
388
+ let detractors = 0;
389
+ for (const b of breakdown) {
390
+ const n = Number(b.answer);
391
+ if (n >= 9 && n <= 10) promoters += b.count;
392
+ else if (n >= 0 && n <= 6) detractors += b.count;
393
+ }
394
+ nps = Math.round(((promoters - detractors) / total) * 100);
395
+ }
396
+
397
+ return c.json({ event, property, total, breakdown, average, nps }, 200);
285
398
  });
286
399
 
287
400
  // CSV export — plain route (non-JSON response) under the same auth as the rest
@@ -49,6 +49,7 @@ function emitMarkEvents(
49
49
  eventType: string;
50
50
  feedId: string;
51
51
  recipientKey: string;
52
+ contactId?: string;
52
53
  },
53
54
  ): Promise<unknown> {
54
55
  return Promise.allSettled(
@@ -60,6 +61,11 @@ function emitMarkEvents(
60
61
  // recipientKey IS the canonical contact key — pass it as userId so
61
62
  // the resolver lands on the SAME contact.
62
63
  userId: args.recipientKey,
64
+ // ENGINE-INTERNAL provenance (server-derived, never from the body):
65
+ // pin to the recipient's own contact row so an anon visitor's mark
66
+ // re-ingest folds in by row id instead of minting a phantom
67
+ // external_id=<anonId> twin that would 403-lock their own feed.
68
+ contactId: args.contactId,
63
69
  eventProperties: { feedItemId: r.id, feedId: args.feedId },
64
70
  idempotencyKey: `inapp:${args.feedId}:${r.id}:${args.eventType}`,
65
71
  source: "inapp",
@@ -407,7 +413,13 @@ export const feedRouter = new OpenAPIHono<AppEnv>()
407
413
  // absorbed by `user_events.idempotencyKey`), so the journey fires once.
408
414
  await emitMarkEvents(
409
415
  { db, registry, hatchet, logger, analytics },
410
- { ids: updated, eventType, feedId, recipientKey: rec.recipientKey },
416
+ {
417
+ ids: updated,
418
+ eventType,
419
+ feedId,
420
+ recipientKey: rec.recipientKey,
421
+ contactId: rec.contactId,
422
+ },
411
423
  );
412
424
 
413
425
  return c.json({ updated: updated.length }, 200);
@@ -443,6 +455,9 @@ export const feedRouter = new OpenAPIHono<AppEnv>()
443
455
  event: {
444
456
  event: "inapp.feed_cleared",
445
457
  userId: rec.recipientKey,
458
+ // ENGINE-INTERNAL provenance — fold into the recipient's own contact
459
+ // row by id, never mint a phantom twin (see emitMarkEvents).
460
+ contactId: rec.contactId,
446
461
  eventProperties: { feedId },
447
462
  idempotencyKey: `inapp:${feedId}:all:inapp.feed_cleared`,
448
463
  source: "inapp",
@@ -451,7 +466,13 @@ export const feedRouter = new OpenAPIHono<AppEnv>()
451
466
  } else {
452
467
  await emitMarkEvents(
453
468
  { db, registry, hatchet, logger, analytics },
454
- { ids: updated, eventType, feedId, recipientKey: rec.recipientKey },
469
+ {
470
+ ids: updated,
471
+ eventType,
472
+ feedId,
473
+ recipientKey: rec.recipientKey,
474
+ contactId: rec.contactId,
475
+ },
455
476
  );
456
477
  }
457
478
 
@@ -13,7 +13,7 @@ import {
13
13
  } from "../../lib/user-token.js";
14
14
 
15
15
  export type FeedRecipient =
16
- | { ok: true; recipientKey: string }
16
+ | { ok: true; recipientKey: string; contactId?: string }
17
17
  | { ok: false; status: 400 | 403; error: string };
18
18
 
19
19
  export interface FeedRecipientParams {
@@ -71,18 +71,17 @@ export async function resolveFeedRecipient(
71
71
  }
72
72
  throw err;
73
73
  }
74
- return { ok: true, recipientKey: await canonicalKey(db, { userId }) };
74
+ const ck = await canonicalKey(db, { userId });
75
+ return { ok: true, recipientKey: ck.recipientKey, contactId: ck.contactId };
75
76
  }
76
77
 
77
78
  // 2. Secret key: trust userId/email directly.
78
79
  if (!publishable && (params.userId || params.email)) {
79
- return {
80
- ok: true,
81
- recipientKey: await canonicalKey(db, {
82
- userId: params.userId,
83
- email: params.email,
84
- }),
85
- };
80
+ const ck = await canonicalKey(db, {
81
+ userId: params.userId,
82
+ email: params.email,
83
+ });
84
+ return { ok: true, recipientKey: ck.recipientKey, contactId: ck.contactId };
86
85
  }
87
86
 
88
87
  // 3. Publishable anon: its raw anon id IS its recipientKey (no resolver — see
@@ -100,7 +99,27 @@ export async function resolveFeedRecipient(
100
99
  error: "anonymousId is not addressable",
101
100
  };
102
101
  }
103
- return { ok: true, recipientKey: params.anonymousId };
102
+ // Surface the anon contact's row id (when it exists) as engine-internal
103
+ // provenance. The feed's OWN mark/clear re-ingests (emitMarkEvents,
104
+ // inapp.feed_cleared) re-ingest keyed `userId: recipientKey` = this raw anon
105
+ // id; threading the row id makes them fold into THIS contact by id instead of
106
+ // minting a phantom `external_id=<anonId>` twin — the twin that then trips
107
+ // collidesWithIdentified and 403-locks the visitor out of their own feed.
108
+ const anonRow = await db
109
+ .select({ id: contacts.id })
110
+ .from(contacts)
111
+ .where(
112
+ and(
113
+ eq(contacts.anonymousId, params.anonymousId),
114
+ isNull(contacts.deletedAt),
115
+ ),
116
+ )
117
+ .limit(1);
118
+ return {
119
+ ok: true,
120
+ recipientKey: params.anonymousId,
121
+ contactId: anonRow[0]?.id,
122
+ };
104
123
  }
105
124
 
106
125
  // 4. No identity → fail-closed.
@@ -163,7 +182,7 @@ async function collidesWithIdentified(
163
182
  async function canonicalKey(
164
183
  db: Database,
165
184
  ident: { userId?: string; email?: string },
166
- ): Promise<string> {
185
+ ): Promise<{ recipientKey: string; contactId?: string }> {
167
186
  if (ident.email) {
168
187
  const email = normalizeEmail(ident.email);
169
188
  const rows = await db
@@ -171,13 +190,14 @@ async function canonicalKey(
171
190
  .from(contacts)
172
191
  .where(and(eq(contacts.email, email), isNull(contacts.deletedAt)))
173
192
  .limit(1);
174
- if (rows[0]) return contactKey(rows[0]);
175
- return email;
193
+ if (rows[0])
194
+ return { recipientKey: contactKey(rows[0]), contactId: rows[0].id };
195
+ return { recipientKey: email };
176
196
  }
177
197
  if (ident.userId) {
178
198
  const row = await resolveContact({ db, id: ident.userId });
179
- if (row) return contactKey(row);
180
- return ident.userId;
199
+ if (row) return { recipientKey: contactKey(row), contactId: row.id };
200
+ return { recipientKey: ident.userId };
181
201
  }
182
- return "";
202
+ return { recipientKey: "" };
183
203
  }
@@ -26,6 +26,21 @@ const listSummarySchema = z.object({
26
26
  name: z.string(),
27
27
  description: z.string().optional(),
28
28
  defaultOptIn: z.boolean(),
29
+ // The resolved opt-in state for the identity in the query (`categories[id] ??
30
+ // defaultOptIn`). An anon / publishable / no-identity read degrades to
31
+ // `defaultOptIn` (never leaks another contact's state — mirrors the
32
+ // `/preferences` gate). This makes ONE catalog call power a preference matrix.
33
+ subscribed: z.boolean(),
34
+ });
35
+
36
+ // `GET /` accepts the SAME identity query as `/preferences` so a single call can
37
+ // return the catalog WITH each list's resolved `subscribed`. Identity is
38
+ // OPTIONAL here (the catalog itself is always returned); when absent (or on a
39
+ // publishable key) every `subscribed` falls back to `defaultOptIn`.
40
+ const listQuerySchema = z.object({
41
+ userId: z.string().optional(),
42
+ email: z.string().optional(),
43
+ anonymousId: z.string().optional(),
29
44
  });
30
45
 
31
46
  const bodySchema = z.object({
@@ -41,7 +56,8 @@ const listRoute = createRoute({
41
56
  tags: ["Lists"],
42
57
  summary: "List defined email lists",
43
58
  description:
44
- "Returns the enabled, code-defined email lists (D3). Membership lives in `email_preferences.categories`; this only enumerates the catalog.",
59
+ "Returns the enabled, code-defined email lists (D3) with each list's resolved `subscribed` state for the (optional) identity in the query. Membership lives in `email_preferences.categories`; this enumerates the catalog and folds in the contact's opt-in map in one call.",
60
+ request: { query: listQuerySchema },
45
61
  responses: {
46
62
  200: {
47
63
  content: {
@@ -251,15 +267,44 @@ async function applyListSubscription(opts: {
251
267
  // `requireScope("ingest")` to `/v1/lists` (bare + `/*`) before requests reach
252
268
  // this router. Mounting auth here too would double the middleware.
253
269
  export const listsRouter = new OpenAPIHono<AppEnv>()
254
- .openapi(listRoute, (c) => {
255
- const lists = getListRegistry()
256
- .getEnabled()
257
- .map((l) => ({
258
- id: l.id,
259
- name: l.name,
260
- ...(l.description !== undefined ? { description: l.description } : {}),
261
- defaultOptIn: l.defaultOptIn,
262
- }));
270
+ .openapi(listRoute, async (c) => {
271
+ const { db } = c.get("container");
272
+ const { userId, email } = c.req.valid("query");
273
+ const enabled = getListRegistry().getEnabled();
274
+
275
+ // Best-effort subscription enrichment. ONLY a secret key with a concrete
276
+ // identity (email/userId) reads another contact's category map; a
277
+ // publishable key — or an anon / no-identity read — degrades to
278
+ // `defaultOptIn` (no leak, mirroring the `/preferences` 403 on a publishable
279
+ // concrete read). Reuses the same `resolveRecipient` + `extId` lookup so the
280
+ // catalog and the matrix stay one call.
281
+ let categories: Record<string, boolean> = {};
282
+ if ((userId || email) && !c.get("publishable")) {
283
+ const recipient = await resolveRecipient({ db, userId, email });
284
+ if (recipient) {
285
+ const extId = recipient.externalId ?? recipient.contactId;
286
+ const rows = await db
287
+ .select()
288
+ .from(emailPreferences)
289
+ .where(
290
+ and(
291
+ eq(emailPreferences.userId, extId),
292
+ eq(emailPreferences.email, recipient.email),
293
+ ),
294
+ )
295
+ .limit(1);
296
+ const row = rows[0];
297
+ if (row) categories = serializePrefs(row).categories;
298
+ }
299
+ }
300
+
301
+ const lists = enabled.map((l) => ({
302
+ id: l.id,
303
+ name: l.name,
304
+ ...(l.description !== undefined ? { description: l.description } : {}),
305
+ defaultOptIn: l.defaultOptIn,
306
+ subscribed: categories[l.id] ?? l.defaultOptIn,
307
+ }));
263
308
 
264
309
  return c.json({ lists }, 200);
265
310
  })