@hogsend/engine 0.35.1 → 0.36.1

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.
@@ -0,0 +1,524 @@
1
+ import { feedItems } from "@hogsend/db";
2
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
+ import { and, count, desc, eq, gt, inArray, lt, sql } from "drizzle-orm";
4
+ import { streamSSE } from "hono/streaming";
5
+ import type { AppEnv } from "../../app.js";
6
+ import { ingestEvent } from "../../lib/ingestion.js";
7
+ import { getRedis } from "../../lib/redis.js";
8
+ import { errorSchema } from "../../lib/schemas.js";
9
+ import { resolveFeedRecipient } from "./recipient.js";
10
+
11
+ // ---------------------------------------------------------------------------
12
+ // Serialization
13
+ // ---------------------------------------------------------------------------
14
+
15
+ type FeedItemRow = typeof feedItems.$inferSelect;
16
+
17
+ const feedItemSchema = z.object({
18
+ id: z.string(),
19
+ type: z.string(),
20
+ title: z.string().nullable(),
21
+ body: z.string().nullable(),
22
+ blocks: z.array(z.record(z.string(), z.unknown())).nullable(),
23
+ actionUrl: z.string().nullable(),
24
+ metadata: z.record(z.string(), z.unknown()).nullable(),
25
+ category: z.string(),
26
+ status: z.enum(["unseen", "seen", "read", "archived"]),
27
+ seenAt: z.string().nullable(),
28
+ readAt: z.string().nullable(),
29
+ archivedAt: z.string().nullable(),
30
+ createdAt: z.string(),
31
+ updatedAt: z.string(),
32
+ });
33
+
34
+ /** Deps the per-item `inapp.*` emit needs from the container. */
35
+ type IngestDeps = Pick<
36
+ Parameters<typeof ingestEvent>[0],
37
+ "db" | "registry" | "hatchet" | "logger" | "analytics"
38
+ >;
39
+
40
+ /**
41
+ * Emit one server-side `inapp.*` event per updated feed item id (shared by
42
+ * `/mark` and `/mark-all`'s per-item branch). The idempotency key matches the
43
+ * SDK's optimistic client capture so the journey fires once.
44
+ */
45
+ function emitMarkEvents(
46
+ deps: IngestDeps,
47
+ args: {
48
+ ids: { id: string }[];
49
+ eventType: string;
50
+ feedId: string;
51
+ recipientKey: string;
52
+ contactId?: string;
53
+ },
54
+ ): Promise<unknown> {
55
+ return Promise.allSettled(
56
+ args.ids.map((r) =>
57
+ ingestEvent({
58
+ ...deps,
59
+ event: {
60
+ event: args.eventType,
61
+ // recipientKey IS the canonical contact key — pass it as userId so
62
+ // the resolver lands on the SAME contact.
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,
69
+ eventProperties: { feedItemId: r.id, feedId: args.feedId },
70
+ idempotencyKey: `inapp:${args.feedId}:${r.id}:${args.eventType}`,
71
+ source: "inapp",
72
+ },
73
+ }),
74
+ ),
75
+ );
76
+ }
77
+
78
+ function serializeFeedItem(row: FeedItemRow) {
79
+ return {
80
+ id: row.id,
81
+ type: row.type,
82
+ title: row.title ?? null,
83
+ body: row.body ?? null,
84
+ blocks: (row.blocks ?? null) as Record<string, unknown>[] | null,
85
+ actionUrl: row.actionUrl ?? null,
86
+ metadata: (row.metadata ?? null) as Record<string, unknown> | null,
87
+ category: row.category,
88
+ status: row.status,
89
+ seenAt: row.seenAt?.toISOString() ?? null,
90
+ readAt: row.readAt?.toISOString() ?? null,
91
+ archivedAt: row.archivedAt?.toISOString() ?? null,
92
+ createdAt: row.createdAt.toISOString(),
93
+ updatedAt: row.updatedAt.toISOString(),
94
+ };
95
+ }
96
+
97
+ // ---------------------------------------------------------------------------
98
+ // Mark-state model
99
+ // ---------------------------------------------------------------------------
100
+
101
+ const markState = z.enum(["seen", "read", "archived", "unseen", "unread"]);
102
+ type MarkState = z.infer<typeof markState>;
103
+
104
+ type FeedUpdateSet = Partial<{
105
+ status: "unseen" | "seen" | "read" | "archived";
106
+ seenAt: Date | null;
107
+ readAt: Date | null;
108
+ archivedAt: Date | null;
109
+ updatedAt: Date;
110
+ }>;
111
+
112
+ /**
113
+ * Map a requested mark `state` to (a) the row UPDATE patch and (b) the server-
114
+ * side `inapp.*` event name. The DB enum is `[unseen, seen, read, archived]`;
115
+ * `unread` is a virtual state meaning "seen-but-not-read" (status `seen`, clear
116
+ * `readAt`).
117
+ */
118
+ function markStateToUpdate(state: MarkState): {
119
+ set: FeedUpdateSet;
120
+ eventType: string;
121
+ } {
122
+ const now = new Date();
123
+ switch (state) {
124
+ case "seen":
125
+ return {
126
+ set: { status: "seen", seenAt: now, updatedAt: now },
127
+ eventType: "inapp.item_seen",
128
+ };
129
+ case "read":
130
+ return {
131
+ // `seenAt` is only set here when null is desired; we always stamp it so a
132
+ // read implies seen.
133
+ set: { status: "read", readAt: now, seenAt: now, updatedAt: now },
134
+ eventType: "inapp.item_read",
135
+ };
136
+ case "archived":
137
+ return {
138
+ set: { status: "archived", archivedAt: now, updatedAt: now },
139
+ eventType: "inapp.item_archived",
140
+ };
141
+ case "unseen":
142
+ return {
143
+ set: { status: "unseen", seenAt: null, readAt: null, updatedAt: now },
144
+ eventType: "inapp.item_unseen",
145
+ };
146
+ case "unread":
147
+ return {
148
+ set: { status: "seen", readAt: null, updatedAt: now },
149
+ eventType: "inapp.item_unread",
150
+ };
151
+ }
152
+ }
153
+
154
+ // ---------------------------------------------------------------------------
155
+ // Schemas
156
+ // ---------------------------------------------------------------------------
157
+
158
+ const listQuerySchema = z.object({
159
+ feedId: z.string().optional(),
160
+ status: z.enum(["unseen", "seen", "read", "archived", "all"]).optional(),
161
+ before: z.string().optional(),
162
+ after: z.string().optional(),
163
+ pageSize: z.coerce.number().int().positive().max(100).optional(),
164
+ // Recipient resolution (server-side; never trusted as recipientKey directly).
165
+ userToken: z.string().optional(),
166
+ anonymousId: z.string().optional(),
167
+ userId: z.string().optional(),
168
+ email: z.string().optional(),
169
+ });
170
+
171
+ const listResponseSchema = z.object({
172
+ items: z.array(feedItemSchema),
173
+ pageInfo: z.object({
174
+ before: z.string().nullable(),
175
+ after: z.string().nullable(),
176
+ hasNextPage: z.boolean(),
177
+ }),
178
+ metadata: z.object({
179
+ total_count: z.number(),
180
+ unseen_count: z.number(),
181
+ unread_count: z.number(),
182
+ }),
183
+ });
184
+
185
+ const markBodySchema = z.object({
186
+ ids: z.array(z.string()).min(1),
187
+ state: markState,
188
+ feedId: z.string().optional(),
189
+ userToken: z.string().optional(),
190
+ anonymousId: z.string().optional(),
191
+ userId: z.string().optional(),
192
+ email: z.string().optional(),
193
+ });
194
+
195
+ const markAllBodySchema = z.object({
196
+ state: markState,
197
+ feedId: z.string().optional(),
198
+ userToken: z.string().optional(),
199
+ anonymousId: z.string().optional(),
200
+ userId: z.string().optional(),
201
+ email: z.string().optional(),
202
+ });
203
+
204
+ const streamQuerySchema = z.object({
205
+ feedId: z.string().optional(),
206
+ userToken: z.string().optional(),
207
+ anonymousId: z.string().optional(),
208
+ userId: z.string().optional(),
209
+ email: z.string().optional(),
210
+ });
211
+
212
+ const listRoute = createRoute({
213
+ method: "get",
214
+ path: "/",
215
+ tags: ["Feed"],
216
+ summary: "List in-app feed items for the resolved recipient",
217
+ description:
218
+ "Recipient-scoped server-side. A publishable key reads its own anon feed (anonymousId) or a token-verified userId; a secret key may pass userId/email directly. NEVER reads recipientKey from the request.",
219
+ request: { query: listQuerySchema },
220
+ responses: {
221
+ 200: {
222
+ content: { "application/json": { schema: listResponseSchema } },
223
+ description: "The recipient's feed page + counts",
224
+ },
225
+ 400: {
226
+ content: { "application/json": { schema: errorSchema } },
227
+ description: "Missing identity",
228
+ },
229
+ 403: {
230
+ content: { "application/json": { schema: errorSchema } },
231
+ description: "Invalid userToken",
232
+ },
233
+ },
234
+ });
235
+
236
+ const markRoute = createRoute({
237
+ method: "post",
238
+ path: "/mark",
239
+ tags: ["Feed"],
240
+ summary: "Mark specific feed items",
241
+ description:
242
+ "Updates the given item ids INTERSECTED with the recipient's own rows (a pk_ caller can never read or mutate another recipient's items, even by guessing ids), then emits an `inapp.*` event server-side (deduped against the client's optimistic capture by a shared idempotency key).",
243
+ request: {
244
+ body: { content: { "application/json": { schema: markBodySchema } } },
245
+ },
246
+ responses: {
247
+ 200: {
248
+ content: {
249
+ "application/json": {
250
+ schema: z.object({ updated: z.number() }),
251
+ },
252
+ },
253
+ description: "Items updated",
254
+ },
255
+ 400: {
256
+ content: { "application/json": { schema: errorSchema } },
257
+ description: "Missing identity",
258
+ },
259
+ 403: {
260
+ content: { "application/json": { schema: errorSchema } },
261
+ description: "Invalid userToken",
262
+ },
263
+ },
264
+ });
265
+
266
+ const markAllRoute = createRoute({
267
+ method: "post",
268
+ path: "/mark-all",
269
+ tags: ["Feed"],
270
+ summary: "Mark all of the recipient's feed items",
271
+ request: {
272
+ body: { content: { "application/json": { schema: markAllBodySchema } } },
273
+ },
274
+ responses: {
275
+ 200: {
276
+ content: {
277
+ "application/json": {
278
+ schema: z.object({ updated: z.number() }),
279
+ },
280
+ },
281
+ description: "Items updated",
282
+ },
283
+ 400: {
284
+ content: { "application/json": { schema: errorSchema } },
285
+ description: "Missing identity",
286
+ },
287
+ 403: {
288
+ content: { "application/json": { schema: errorSchema } },
289
+ description: "Invalid userToken",
290
+ },
291
+ },
292
+ });
293
+
294
+ const streamRoute = createRoute({
295
+ method: "get",
296
+ path: "/stream",
297
+ tags: ["Feed"],
298
+ summary: "SSE stream of realtime feed events for the resolved recipient",
299
+ description:
300
+ "Server-Sent Events over `feed:<recipientKey>` (Redis pub/sub via a DEDICATED subscriber connection). Closes the subscriber on disconnect.",
301
+ request: { query: streamQuerySchema },
302
+ responses: {
303
+ 200: { description: "SSE stream" },
304
+ 400: {
305
+ content: { "application/json": { schema: errorSchema } },
306
+ description: "Missing identity",
307
+ },
308
+ 403: {
309
+ content: { "application/json": { schema: errorSchema } },
310
+ description: "Invalid userToken",
311
+ },
312
+ },
313
+ });
314
+
315
+ // The feed router does NOT re-apply auth internally — the data-plane prefix gate
316
+ // in `routes/index.ts` (`requirePublishableOrIngest`) runs before requests reach
317
+ // here. The routes still fail-closed on identity via `resolveFeedRecipient`.
318
+ export const feedRouter = new OpenAPIHono<AppEnv>()
319
+ .openapi(listRoute, async (c) => {
320
+ const { db } = c.get("container");
321
+ const q = c.req.valid("query");
322
+
323
+ const rec = await resolveFeedRecipient(c, q);
324
+ if (!rec.ok) return c.json({ error: rec.error }, rec.status);
325
+
326
+ // EVERY query is scoped WHERE recipient_key = <server-derived key>.
327
+ const where = [eq(feedItems.recipientKey, rec.recipientKey)];
328
+ if (q.feedId) where.push(eq(feedItems.category, q.feedId));
329
+ if (q.status && q.status !== "all") {
330
+ where.push(eq(feedItems.status, q.status));
331
+ }
332
+ // Guard against an unparseable cursor: `new Date("garbage")` is `Invalid
333
+ // Date`, which drizzle would bind as an invalid timestamp (Postgres 22007 →
334
+ // 500). Skip the bound rather than error; the recipient scope still holds.
335
+ if (q.before) {
336
+ const d = new Date(q.before);
337
+ if (!Number.isNaN(d.getTime())) where.push(lt(feedItems.createdAt, d));
338
+ }
339
+ if (q.after) {
340
+ const d = new Date(q.after);
341
+ if (!Number.isNaN(d.getTime())) where.push(gt(feedItems.createdAt, d));
342
+ }
343
+
344
+ // `pageSize` is already capped at 100 by the query schema (`.max(100)`).
345
+ const pageSize = q.pageSize ?? 20;
346
+ const rows = await db
347
+ .select()
348
+ .from(feedItems)
349
+ .where(and(...where))
350
+ .orderBy(desc(feedItems.createdAt))
351
+ .limit(pageSize + 1);
352
+
353
+ const hasNextPage = rows.length > pageSize;
354
+ const page = rows.slice(0, pageSize);
355
+
356
+ // Recipient-scoped metadata counts (independent of the page filters, except
357
+ // the same recipient scope).
358
+ const metaRows = await db
359
+ .select({
360
+ total: count(),
361
+ unseen: count(sql`CASE WHEN ${feedItems.status} = 'unseen' THEN 1 END`),
362
+ unread: count(
363
+ sql`CASE WHEN ${feedItems.status} IN ('unseen', 'seen') THEN 1 END`,
364
+ ),
365
+ })
366
+ .from(feedItems)
367
+ .where(eq(feedItems.recipientKey, rec.recipientKey));
368
+ const m = metaRows[0] ?? { total: 0, unseen: 0, unread: 0 };
369
+
370
+ return c.json(
371
+ {
372
+ items: page.map(serializeFeedItem),
373
+ pageInfo: {
374
+ before: page.at(-1)?.createdAt.toISOString() ?? null,
375
+ after: page[0]?.createdAt.toISOString() ?? null,
376
+ hasNextPage,
377
+ },
378
+ metadata: {
379
+ total_count: m.total,
380
+ unseen_count: m.unseen,
381
+ unread_count: m.unread,
382
+ },
383
+ },
384
+ 200,
385
+ );
386
+ })
387
+ .openapi(markRoute, async (c) => {
388
+ const { db, registry, hatchet, logger, analytics } = c.get("container");
389
+ const body = c.req.valid("json");
390
+
391
+ const rec = await resolveFeedRecipient(c, body);
392
+ if (!rec.ok) return c.json({ error: rec.error }, rec.status);
393
+
394
+ const { set, eventType } = markStateToUpdate(body.state);
395
+ const feedId = body.feedId ?? "in_app";
396
+
397
+ // INTERSECT the requested ids with the recipient's OWN rows — fail-closed
398
+ // scoping. `recipientKey` is server-derived, NOT from the body, so a pk_
399
+ // caller can never mutate another recipient's items even by guessing ids.
400
+ const updated = await db
401
+ .update(feedItems)
402
+ .set(set)
403
+ .where(
404
+ and(
405
+ eq(feedItems.recipientKey, rec.recipientKey),
406
+ inArray(feedItems.id, body.ids),
407
+ ),
408
+ )
409
+ .returning({ id: feedItems.id });
410
+
411
+ // Emit `inapp.*` server-side per updated id. Shared idempotency key dedups
412
+ // against the SDK's optimistic client capture (whichever lands second is
413
+ // absorbed by `user_events.idempotencyKey`), so the journey fires once.
414
+ await emitMarkEvents(
415
+ { db, registry, hatchet, logger, analytics },
416
+ {
417
+ ids: updated,
418
+ eventType,
419
+ feedId,
420
+ recipientKey: rec.recipientKey,
421
+ contactId: rec.contactId,
422
+ },
423
+ );
424
+
425
+ return c.json({ updated: updated.length }, 200);
426
+ })
427
+ .openapi(markAllRoute, async (c) => {
428
+ const { db, registry, hatchet, logger, analytics } = c.get("container");
429
+ const body = c.req.valid("json");
430
+
431
+ const rec = await resolveFeedRecipient(c, body);
432
+ if (!rec.ok) return c.json({ error: rec.error }, rec.status);
433
+
434
+ const { set, eventType } = markStateToUpdate(body.state);
435
+ const feedId = body.feedId ?? "in_app";
436
+
437
+ const where = [eq(feedItems.recipientKey, rec.recipientKey)];
438
+ if (body.feedId) where.push(eq(feedItems.category, body.feedId));
439
+
440
+ const updated = await db
441
+ .update(feedItems)
442
+ .set(set)
443
+ .where(and(...where))
444
+ .returning({ id: feedItems.id });
445
+
446
+ // Mark-all-read emits a single `inapp.feed_cleared` (not per-item); other
447
+ // states emit per-item `inapp.*`, sharing the dedup key with the client.
448
+ if (body.state === "read") {
449
+ await ingestEvent({
450
+ db,
451
+ registry,
452
+ hatchet,
453
+ logger,
454
+ analytics,
455
+ event: {
456
+ event: "inapp.feed_cleared",
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,
461
+ eventProperties: { feedId },
462
+ idempotencyKey: `inapp:${feedId}:all:inapp.feed_cleared`,
463
+ source: "inapp",
464
+ },
465
+ }).catch(() => {});
466
+ } else {
467
+ await emitMarkEvents(
468
+ { db, registry, hatchet, logger, analytics },
469
+ {
470
+ ids: updated,
471
+ eventType,
472
+ feedId,
473
+ recipientKey: rec.recipientKey,
474
+ contactId: rec.contactId,
475
+ },
476
+ );
477
+ }
478
+
479
+ return c.json({ updated: updated.length }, 200);
480
+ })
481
+ .openapi(streamRoute, async (c) => {
482
+ const rec = await resolveFeedRecipient(c, c.req.valid("query"));
483
+ if (!rec.ok) return c.json({ error: rec.error }, rec.status);
484
+ const channel = `feed:${rec.recipientKey}`;
485
+
486
+ return streamSSE(c, async (stream) => {
487
+ // DEDICATED subscriber connection — NEVER `.subscribe()` on the shared
488
+ // getRedis() singleton (it would poison the rate-limiter/auth/cache).
489
+ const sub = getRedis().duplicate();
490
+ let closed = false;
491
+ const teardown = async () => {
492
+ if (closed) return;
493
+ closed = true;
494
+ try {
495
+ await sub.unsubscribe(channel);
496
+ } catch {
497
+ // best-effort
498
+ }
499
+ // Close the duplicate; no leak.
500
+ sub.disconnect();
501
+ };
502
+ stream.onAbort(() => {
503
+ void teardown();
504
+ });
505
+
506
+ sub.on("message", (_ch, msg) => {
507
+ // writeSSE rejects after close — swallow.
508
+ void stream.writeSSE({ event: "feed", data: msg }).catch(() => {});
509
+ });
510
+
511
+ try {
512
+ await sub.subscribe(channel);
513
+ await stream.writeSSE({ event: "ready", data: "{}" });
514
+ // Keep-alive heartbeat until aborted.
515
+ while (!stream.aborted && !closed) {
516
+ await stream.sleep(25_000);
517
+ if (stream.aborted || closed) break;
518
+ await stream.writeSSE({ event: "ping", data: "{}" }).catch(() => {});
519
+ }
520
+ } finally {
521
+ await teardown();
522
+ }
523
+ });
524
+ });