@hogsend/engine 0.35.0 → 0.36.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 +7 -7
- package/src/app.ts +22 -1
- package/src/index.ts +48 -0
- package/src/lib/api-key-hash.ts +7 -2
- package/src/lib/banner.ts +71 -0
- package/src/lib/contacts.ts +57 -0
- package/src/lib/feed.ts +233 -0
- package/src/lib/ingestion.ts +10 -0
- package/src/lib/user-token.ts +100 -0
- package/src/middleware/api-key.ts +4 -0
- package/src/middleware/publishable-key.ts +119 -0
- package/src/middleware/require-admin.ts +18 -2
- package/src/routes/_shared.ts +61 -0
- package/src/routes/admin/api-keys.ts +46 -10
- package/src/routes/contacts/index.ts +38 -12
- package/src/routes/events/index.ts +70 -30
- package/src/routes/feed/index.ts +503 -0
- package/src/routes/feed/recipient.ts +183 -0
- package/src/routes/index.ts +65 -7
- package/src/routes/lists/index.ts +126 -6
- package/src/worker.ts +2 -0
- package/src/workflows/send-feed.ts +44 -0
package/src/routes/index.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { OpenAPIHono } from "@hono/zod-openapi";
|
|
|
2
2
|
import type { AppEnv } from "../app.js";
|
|
3
3
|
import type { HogsendClient } from "../container.js";
|
|
4
4
|
import { requireApiKey, requireScope } from "../middleware/api-key.js";
|
|
5
|
+
import { requirePublishableOrIngest } from "../middleware/publishable-key.js";
|
|
5
6
|
import { createRateLimit } from "../middleware/rate-limit.js";
|
|
6
7
|
import { adminRouter } from "./admin/index.js";
|
|
7
8
|
import { campaignsRouter } from "./campaigns/index.js";
|
|
@@ -10,6 +11,7 @@ import { contactsRouter } from "./contacts/index.js";
|
|
|
10
11
|
import { emailRouter } from "./email/index.js";
|
|
11
12
|
import { emailsRouter } from "./emails/index.js";
|
|
12
13
|
import { eventsRouter } from "./events/index.js";
|
|
14
|
+
import { feedRouter } from "./feed/index.js";
|
|
13
15
|
import { healthRouter } from "./health.js";
|
|
14
16
|
import { listsRouter } from "./lists/index.js";
|
|
15
17
|
import { trackingRouter } from "./tracking/index.js";
|
|
@@ -52,16 +54,71 @@ export function registerRoutes(
|
|
|
52
54
|
prefix: "ratelimit:emails",
|
|
53
55
|
max: EMAIL_RATE_LIMIT_MAX,
|
|
54
56
|
});
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
57
|
+
|
|
58
|
+
// ---- Browser-reachable subset (publishable OR secret-ingest) ----
|
|
59
|
+
// Registered BEFORE the secret-only prefix loop so these specific patterns
|
|
60
|
+
// win Hono's match order. `requirePublishableOrIngest` accepts EITHER a
|
|
61
|
+
// secret ingest-scoped key (unchanged) OR a pk_/ingest-public key (Origin-
|
|
62
|
+
// allowlisted, fail-closed). Everything NOT listed here stays secret-only.
|
|
63
|
+
//
|
|
64
|
+
// `/events` has no subtree (only `POST /`), so the bare pattern is complete.
|
|
65
|
+
v1.use("/events", requirePublishableOrIngest);
|
|
66
|
+
// `/lists` catalog + the new static `/preferences` read + subscribe/unsub.
|
|
67
|
+
v1.use("/lists", requirePublishableOrIngest);
|
|
68
|
+
v1.use("/lists/preferences", requirePublishableOrIngest);
|
|
69
|
+
v1.use("/lists/:id/subscribe", requirePublishableOrIngest);
|
|
70
|
+
v1.use("/lists/:id/unsubscribe", requirePublishableOrIngest);
|
|
71
|
+
// Feed: `GET /feed` list/stream + `POST /feed/mark`/`mark-all` — publishable OR
|
|
72
|
+
// secret. Both the bare `/feed` (GET list) and the `/feed/*` subtree
|
|
73
|
+
// (mark/mark-all/stream) are covered (Hono treats them as distinct patterns).
|
|
74
|
+
// Recipient scoping is enforced server-side in `resolveFeedRecipient`, never
|
|
75
|
+
// from the request.
|
|
76
|
+
v1.use("/feed", requirePublishableOrIngest);
|
|
77
|
+
v1.use("/feed/*", requirePublishableOrIngest);
|
|
78
|
+
// Bare `/contacts` is dual-purpose: PUT/POST = the publishable upsert;
|
|
79
|
+
// DELETE = secret-only. Hono runs ALL matching `use`s, so a single guard must
|
|
80
|
+
// branch by method rather than stacking two guards (which would 403 a valid
|
|
81
|
+
// pk_ upsert via the secret guard). Any OTHER `/contacts/*` (incl. /find)
|
|
82
|
+
// stays secret-only below.
|
|
83
|
+
const contactsDeleteGuard = requireScope("ingest");
|
|
84
|
+
v1.use("/contacts", async (c, next) => {
|
|
85
|
+
if (c.req.method !== "DELETE") {
|
|
86
|
+
return requirePublishableOrIngest(c, next);
|
|
87
|
+
}
|
|
88
|
+
// DELETE is secret-only: chain `requireApiKey` then `requireScope("ingest")`
|
|
89
|
+
// exactly as the secret prefix loop does. `requireApiKey` only runs its
|
|
90
|
+
// `next` on a successful auth (else it returns 401/expired), so use a flag
|
|
91
|
+
// to detect that and surface its short-circuit response; otherwise hand off
|
|
92
|
+
// to the scope guard (which itself returns its 403 or calls `next`).
|
|
93
|
+
let authed = false;
|
|
94
|
+
const res = await requireApiKey(c, async () => {
|
|
95
|
+
authed = true;
|
|
96
|
+
});
|
|
97
|
+
if (!authed) return res;
|
|
98
|
+
return contactsDeleteGuard(c, next);
|
|
99
|
+
});
|
|
100
|
+
|
|
101
|
+
// ---- Secret-only prefixes (unchanged behavior) ----
|
|
102
|
+
// `/emails`, `/campaigns`: bare + subtree. A pk_ key hitting these fails
|
|
103
|
+
// `requireScope("ingest")` (its `["ingest-public"]` scope is neither `ingest`
|
|
104
|
+
// nor `full-admin`) → 403, no escalation.
|
|
105
|
+
//
|
|
106
|
+
// NOTE: deliberately NO `/lists/*` OR `/contacts/*` secret catch-all. Hono
|
|
107
|
+
// runs ALL matching `use`s, AND a `/<prefix>/*` `use` ALSO matches the bare
|
|
108
|
+
// `/<prefix>` path — so a `/contacts/*` guard would re-run on the bare
|
|
109
|
+
// `/contacts` upsert and 403 a valid pk_ key AFTER the method-branch
|
|
110
|
+
// publishable guard above already accepted it (the exact `/lists/*` collision
|
|
111
|
+
// we avoid the same way). The only secret-only `/contacts` subtree route is
|
|
112
|
+
// `GET /contacts/find`, so guard it EXPLICITLY; the bare-`/contacts`
|
|
113
|
+
// method-branch guard above is the sole authority on the bare path (DELETE is
|
|
114
|
+
// secret-only there, PUT/POST publishable). Any FUTURE secret-only
|
|
115
|
+
// `/contacts/<x>` or `/lists/<x>` route must mount its own
|
|
116
|
+
// `requireApiKey + requireScope("ingest")` (fail-closed by construction).
|
|
117
|
+
for (const base of ["/emails", "/campaigns"]) {
|
|
62
118
|
v1.use(base, requireApiKey, requireScope("ingest"));
|
|
63
119
|
v1.use(`${base}/*`, requireApiKey, requireScope("ingest"));
|
|
64
120
|
}
|
|
121
|
+
v1.use("/contacts/find", requireApiKey, requireScope("ingest"));
|
|
65
122
|
// Register the email rate-limit ONCE. The wildcard pattern `/emails/*` matches
|
|
66
123
|
// BOTH the bare `POST /v1/emails` and any subtree, so a single registration
|
|
67
124
|
// covers the whole emails surface. Registering both bare AND wildcard with the
|
|
@@ -71,6 +128,7 @@ export function registerRoutes(
|
|
|
71
128
|
|
|
72
129
|
v1.route("/contacts", contactsRouter);
|
|
73
130
|
v1.route("/events", eventsRouter);
|
|
131
|
+
v1.route("/feed", feedRouter);
|
|
74
132
|
v1.route("/emails", emailsRouter);
|
|
75
133
|
v1.route("/lists", listsRouter);
|
|
76
134
|
v1.route("/campaigns", campaignsRouter);
|
|
@@ -1,18 +1,25 @@
|
|
|
1
1
|
import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
2
|
-
import type
|
|
2
|
+
import { type Database, emailPreferences } from "@hogsend/db";
|
|
3
3
|
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
4
|
+
import { and, eq } from "drizzle-orm";
|
|
4
5
|
import type { AppEnv } from "../../app.js";
|
|
5
6
|
import {
|
|
6
7
|
resolveContact,
|
|
7
8
|
resolveOrCreateContact,
|
|
9
|
+
resolveRecipient,
|
|
8
10
|
serializeContact,
|
|
11
|
+
serializePrefs,
|
|
9
12
|
} from "../../lib/contacts.js";
|
|
10
13
|
import type { Logger } from "../../lib/logger.js";
|
|
11
14
|
import { emitOutbound } from "../../lib/outbound.js";
|
|
12
15
|
import { applyListMembership } from "../../lib/preferences.js";
|
|
13
16
|
import { errorSchema } from "../../lib/schemas.js";
|
|
14
17
|
import { getListRegistry } from "../../lists/registry-singleton.js";
|
|
15
|
-
import {
|
|
18
|
+
import {
|
|
19
|
+
gatePublishableIdentity,
|
|
20
|
+
listMembershipError,
|
|
21
|
+
requireIdentity,
|
|
22
|
+
} from "../_shared.js";
|
|
16
23
|
|
|
17
24
|
const listSummarySchema = z.object({
|
|
18
25
|
id: z.string(),
|
|
@@ -24,6 +31,8 @@ const listSummarySchema = z.object({
|
|
|
24
31
|
const bodySchema = z.object({
|
|
25
32
|
email: z.string().optional(),
|
|
26
33
|
userId: z.string().optional(),
|
|
34
|
+
// Publishable-key identity assertion (§Phase 1). Ignored on the secret path.
|
|
35
|
+
userToken: z.string().optional(),
|
|
27
36
|
});
|
|
28
37
|
|
|
29
38
|
const listRoute = createRoute({
|
|
@@ -45,6 +54,44 @@ const listRoute = createRoute({
|
|
|
45
54
|
},
|
|
46
55
|
});
|
|
47
56
|
|
|
57
|
+
// STATIC `/preferences` read. MUST be registered before any `/:id` GET so the
|
|
58
|
+
// literal path wins matching (there is no `/:id` GET today, so order is safe
|
|
59
|
+
// regardless — but keep it adjacent to `GET /` to preserve that invariant).
|
|
60
|
+
const prefsQuerySchema = z.object({
|
|
61
|
+
userId: z.string().optional(),
|
|
62
|
+
email: z.string().optional(),
|
|
63
|
+
anonymousId: z.string().optional(),
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
const prefsResponseSchema = z.object({
|
|
67
|
+
categories: z.record(z.string(), z.boolean()),
|
|
68
|
+
unsubscribedAll: z.boolean(),
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
const preferencesRoute = createRoute({
|
|
72
|
+
method: "get",
|
|
73
|
+
path: "/preferences",
|
|
74
|
+
tags: ["Lists"],
|
|
75
|
+
summary: "Read a contact's list/email preferences",
|
|
76
|
+
description:
|
|
77
|
+
"Returns `{ categories, unsubscribedAll }` for the resolved contact. Behind the publishable gate: a pk_ key may read anon-only (anonymousId) — a concrete `email`/`userId` read requires a verified userToken (v3).",
|
|
78
|
+
request: { query: prefsQuerySchema },
|
|
79
|
+
responses: {
|
|
80
|
+
200: {
|
|
81
|
+
content: { "application/json": { schema: prefsResponseSchema } },
|
|
82
|
+
description: "The contact's list/email preferences",
|
|
83
|
+
},
|
|
84
|
+
400: {
|
|
85
|
+
content: { "application/json": { schema: errorSchema } },
|
|
86
|
+
description: "Missing identity",
|
|
87
|
+
},
|
|
88
|
+
403: {
|
|
89
|
+
content: { "application/json": { schema: errorSchema } },
|
|
90
|
+
description: "Publishable key may not read a concrete identity",
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
});
|
|
94
|
+
|
|
48
95
|
const subscribeRoute = createRoute({
|
|
49
96
|
method: "post",
|
|
50
97
|
path: "/{id}/subscribe",
|
|
@@ -72,6 +119,11 @@ const subscribeRoute = createRoute({
|
|
|
72
119
|
content: { "application/json": { schema: errorSchema } },
|
|
73
120
|
description: "Missing recipient or no resolvable email",
|
|
74
121
|
},
|
|
122
|
+
403: {
|
|
123
|
+
content: { "application/json": { schema: errorSchema } },
|
|
124
|
+
description:
|
|
125
|
+
"Publishable key attempted to act on another identity without a verified userToken",
|
|
126
|
+
},
|
|
75
127
|
404: {
|
|
76
128
|
content: { "application/json": { schema: errorSchema } },
|
|
77
129
|
description: "Unknown list id",
|
|
@@ -106,6 +158,11 @@ const unsubscribeRoute = createRoute({
|
|
|
106
158
|
content: { "application/json": { schema: errorSchema } },
|
|
107
159
|
description: "Missing recipient or no resolvable email",
|
|
108
160
|
},
|
|
161
|
+
403: {
|
|
162
|
+
content: { "application/json": { schema: errorSchema } },
|
|
163
|
+
description:
|
|
164
|
+
"Publishable key attempted to act on another identity without a verified userToken",
|
|
165
|
+
},
|
|
109
166
|
404: {
|
|
110
167
|
content: { "application/json": { schema: errorSchema } },
|
|
111
168
|
description: "Unknown list id",
|
|
@@ -206,10 +263,66 @@ export const listsRouter = new OpenAPIHono<AppEnv>()
|
|
|
206
263
|
|
|
207
264
|
return c.json({ lists }, 200);
|
|
208
265
|
})
|
|
266
|
+
.openapi(preferencesRoute, async (c) => {
|
|
267
|
+
const { db } = c.get("container");
|
|
268
|
+
const { userId, email } = c.req.valid("query");
|
|
269
|
+
|
|
270
|
+
// Identity gate (publishable-aware). A secret key needs email/userId via
|
|
271
|
+
// `requireIdentity`. A publishable key may read anon-only — but a concrete
|
|
272
|
+
// `email`/`userId` read would leak another person's prefs, so it is rejected
|
|
273
|
+
// unless v3's userToken arm is added. (`anonymousId` is accepted for a
|
|
274
|
+
// publishable read; it never resolves to another identity's prefs here.)
|
|
275
|
+
if (!c.get("publishable")) {
|
|
276
|
+
const guard = requireIdentity(c, { email, userId });
|
|
277
|
+
if (guard) return guard;
|
|
278
|
+
} else if (email || userId) {
|
|
279
|
+
return c.json(
|
|
280
|
+
{
|
|
281
|
+
error:
|
|
282
|
+
"publishable preference reads are anon-only without a userToken",
|
|
283
|
+
},
|
|
284
|
+
403,
|
|
285
|
+
);
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
const recipient = await resolveRecipient({ db, userId, email });
|
|
289
|
+
if (!recipient) {
|
|
290
|
+
return c.json({ categories: {}, unsubscribedAll: false }, 200);
|
|
291
|
+
}
|
|
292
|
+
// `email_preferences.user_id` is keyed on `external_id ?? contact.id`
|
|
293
|
+
// (risk 10) — mirror `resolveRecipient`'s contactId fallback.
|
|
294
|
+
const extId = recipient.externalId ?? recipient.contactId;
|
|
295
|
+
const rows = await db
|
|
296
|
+
.select()
|
|
297
|
+
.from(emailPreferences)
|
|
298
|
+
.where(
|
|
299
|
+
and(
|
|
300
|
+
eq(emailPreferences.userId, extId),
|
|
301
|
+
eq(emailPreferences.email, recipient.email),
|
|
302
|
+
),
|
|
303
|
+
)
|
|
304
|
+
.limit(1);
|
|
305
|
+
const row = rows[0];
|
|
306
|
+
if (!row) {
|
|
307
|
+
return c.json({ categories: {}, unsubscribedAll: false }, 200);
|
|
308
|
+
}
|
|
309
|
+
const prefs = serializePrefs(row);
|
|
310
|
+
return c.json(
|
|
311
|
+
{ categories: prefs.categories, unsubscribedAll: prefs.unsubscribedAll },
|
|
312
|
+
200,
|
|
313
|
+
);
|
|
314
|
+
})
|
|
209
315
|
.openapi(subscribeRoute, async (c) => {
|
|
210
|
-
const { db, hatchet, logger } = c.get("container");
|
|
316
|
+
const { db, hatchet, logger, env } = c.get("container");
|
|
211
317
|
const { id } = c.req.valid("param");
|
|
212
|
-
const { email, userId } = c.req.valid("json");
|
|
318
|
+
const { email, userId, userToken } = c.req.valid("json");
|
|
319
|
+
|
|
320
|
+
const guard = gatePublishableIdentity(
|
|
321
|
+
c,
|
|
322
|
+
{ email, userId, userToken },
|
|
323
|
+
env.BETTER_AUTH_SECRET,
|
|
324
|
+
);
|
|
325
|
+
if (guard) return guard;
|
|
213
326
|
|
|
214
327
|
const result = await applyListSubscription({
|
|
215
328
|
db,
|
|
@@ -232,9 +345,16 @@ export const listsRouter = new OpenAPIHono<AppEnv>()
|
|
|
232
345
|
return c.json({ list: id, subscribed: true as const }, 200);
|
|
233
346
|
})
|
|
234
347
|
.openapi(unsubscribeRoute, async (c) => {
|
|
235
|
-
const { db, hatchet, logger } = c.get("container");
|
|
348
|
+
const { db, hatchet, logger, env } = c.get("container");
|
|
236
349
|
const { id } = c.req.valid("param");
|
|
237
|
-
const { email, userId } = c.req.valid("json");
|
|
350
|
+
const { email, userId, userToken } = c.req.valid("json");
|
|
351
|
+
|
|
352
|
+
const guard = gatePublishableIdentity(
|
|
353
|
+
c,
|
|
354
|
+
{ email, userId, userToken },
|
|
355
|
+
env.BETTER_AUTH_SECRET,
|
|
356
|
+
);
|
|
357
|
+
if (guard) return guard;
|
|
238
358
|
|
|
239
359
|
const result = await applyListSubscription({
|
|
240
360
|
db,
|
package/src/worker.ts
CHANGED
|
@@ -31,6 +31,7 @@ import {
|
|
|
31
31
|
sendCampaignTask,
|
|
32
32
|
} from "./workflows/send-campaign.js";
|
|
33
33
|
import { sendEmailTask } from "./workflows/send-email.js";
|
|
34
|
+
import { sendFeedTask } from "./workflows/send-feed.js";
|
|
34
35
|
|
|
35
36
|
export interface CreateWorkerOptions {
|
|
36
37
|
container: HogsendClient;
|
|
@@ -89,6 +90,7 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
|
|
|
89
90
|
|
|
90
91
|
const baseWorkflows = [
|
|
91
92
|
sendEmailTask,
|
|
93
|
+
sendFeedTask,
|
|
92
94
|
importContactsTask,
|
|
93
95
|
sendCampaignTask,
|
|
94
96
|
reapStuckCampaignsTask,
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
|
|
2
|
+
import type { FeedBlock } from "@hogsend/db";
|
|
3
|
+
import { type SendFeedItemOptions, sendFeedItem } from "../lib/feed.js";
|
|
4
|
+
import { hatchet } from "../lib/hatchet.js";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* JSON-serializable input for the `send-feed` task. Mirrors the journey task
|
|
8
|
+
* convention (explicit fields + a `[key: string]: JsonValue` index signature) so
|
|
9
|
+
* Hatchet's `JsonObject` constraint is satisfied; the fn re-narrows it to the
|
|
10
|
+
* structured {@link SendFeedItemOptions} at the boundary.
|
|
11
|
+
*/
|
|
12
|
+
interface SendFeedTaskInput {
|
|
13
|
+
recipient: { userId?: string; email?: string; anonymousId?: string };
|
|
14
|
+
type: string;
|
|
15
|
+
title?: string;
|
|
16
|
+
body?: string;
|
|
17
|
+
blocks?: FeedBlock[];
|
|
18
|
+
actionUrl?: string;
|
|
19
|
+
metadata?: Record<string, JsonValue>;
|
|
20
|
+
category?: string;
|
|
21
|
+
templateKey?: string;
|
|
22
|
+
journeyStateId?: string;
|
|
23
|
+
idempotencyKey?: string;
|
|
24
|
+
[key: string]: JsonValue | undefined;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Durable wrapper around {@link sendFeedItem} — the in-app-feed sibling of the
|
|
29
|
+
* `send-email` task. `sendFeedItem` owns recipient resolution, `in_app`
|
|
30
|
+
* suppression, the replay-safe idempotency key, and the Redis publish.
|
|
31
|
+
*/
|
|
32
|
+
export const sendFeedTask = hatchet.task({
|
|
33
|
+
name: "send-feed",
|
|
34
|
+
retries: 1,
|
|
35
|
+
executionTimeout: "30s",
|
|
36
|
+
backoff: { factor: 2, maxSeconds: 30 },
|
|
37
|
+
fn: async (input: SendFeedTaskInput) => {
|
|
38
|
+
const result = await sendFeedItem(input as SendFeedItemOptions);
|
|
39
|
+
return {
|
|
40
|
+
feedItemId: result.feedItemId,
|
|
41
|
+
suppressed: result.suppressed,
|
|
42
|
+
};
|
|
43
|
+
},
|
|
44
|
+
});
|