@hogsend/engine 0.40.0 → 0.41.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 +9 -7
- package/src/buckets/check-membership.ts +6 -1
- package/src/campaigns/cohort-sql.ts +198 -0
- package/src/campaigns/define-campaign.ts +207 -28
- package/src/campaigns/reconcile.ts +105 -11
- package/src/campaigns/steps.ts +48 -0
- package/src/connectors/define-action.ts +70 -0
- package/src/container.ts +124 -42
- package/src/destinations/presets/posthog.ts +7 -1
- package/src/index.ts +82 -2
- package/src/journeys/constants.ts +10 -0
- package/src/journeys/define-journey.ts +14 -405
- package/src/journeys/execute-journey-run.ts +608 -0
- package/src/journeys/graph/build-graph.ts +212 -56
- package/src/journeys/journey-boundary.ts +54 -0
- package/src/journeys/journey-context.ts +374 -59
- package/src/journeys/record-once.ts +110 -0
- package/src/lib/blueprints.ts +576 -0
- package/src/lib/campaign-send-key.ts +58 -0
- package/src/lib/connector-actions.ts +203 -19
- package/src/lib/contacts.ts +54 -0
- package/src/lib/email-service-types.ts +4 -1
- package/src/lib/email.ts +13 -2
- package/src/lib/feed.ts +77 -57
- package/src/lib/frequency-cap.ts +45 -15
- package/src/lib/hatchet-duration.ts +22 -0
- package/src/lib/html.ts +1 -0
- package/src/lib/ingestion.ts +145 -4
- package/src/lib/journey-suppress.ts +87 -0
- package/src/lib/links.ts +204 -18
- package/src/lib/outbound.ts +20 -0
- package/src/lib/preferences.ts +80 -1
- package/src/lib/tracked.ts +44 -29
- package/src/lib/tracking-event-names.ts +8 -0
- package/src/lib/webhook-signing.ts +6 -1
- package/src/lists/channels.ts +75 -0
- package/src/lists/define-list.ts +34 -0
- package/src/lists/registry.ts +29 -2
- package/src/mcp/blueprint-tools.ts +460 -0
- package/src/routes/admin/blueprints.ts +711 -0
- package/src/routes/admin/campaigns.ts +179 -3
- package/src/routes/admin/emails.ts +13 -0
- package/src/routes/admin/index.ts +4 -0
- package/src/routes/admin/journeys.ts +4 -2
- package/src/routes/admin/links.ts +303 -36
- package/src/routes/admin/lists.ts +51 -0
- package/src/routes/campaigns/index.ts +44 -6
- package/src/routes/email/preferences.ts +50 -13
- package/src/routes/feed/recipient.ts +2 -43
- package/src/routes/index.ts +6 -0
- package/src/routes/lists/index.ts +138 -18
- package/src/routes/tracking/arrive.ts +260 -0
- package/src/routes/tracking/click-pipeline.ts +329 -0
- package/src/routes/tracking/click.ts +5 -270
- package/src/routes/tracking/index.ts +2 -0
- package/src/routes/tracking/vanity.ts +64 -0
- package/src/worker.ts +5 -0
- package/src/workflows/bucket-backfill.ts +4 -2
- package/src/workflows/bucket-reconcile.ts +11 -4
- package/src/workflows/check-alerts.ts +130 -1
- package/src/workflows/journey-blueprint-interpreter.ts +561 -0
- package/src/workflows/send-campaign.ts +574 -180
|
@@ -1,8 +1,29 @@
|
|
|
1
1
|
import { linkClicks, links, trackedLinks } from "@hogsend/db";
|
|
2
2
|
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
3
|
-
import {
|
|
3
|
+
import {
|
|
4
|
+
and,
|
|
5
|
+
count,
|
|
6
|
+
desc,
|
|
7
|
+
eq,
|
|
8
|
+
exists,
|
|
9
|
+
inArray,
|
|
10
|
+
isNull,
|
|
11
|
+
sql,
|
|
12
|
+
sum,
|
|
13
|
+
} from "drizzle-orm";
|
|
14
|
+
import QRCode from "qrcode";
|
|
4
15
|
import type { AppEnv } from "../../app.js";
|
|
5
|
-
import {
|
|
16
|
+
import {
|
|
17
|
+
assertHttpUrl,
|
|
18
|
+
canonicalTrackedRowFilter,
|
|
19
|
+
ensureQrTrackedLink,
|
|
20
|
+
isSlugUniqueViolation,
|
|
21
|
+
mintLink,
|
|
22
|
+
normalizeSlug,
|
|
23
|
+
QR_TRACKED_SOURCE,
|
|
24
|
+
SlugTakenError,
|
|
25
|
+
vanityUrlFor,
|
|
26
|
+
} from "../../lib/links.js";
|
|
6
27
|
import { errorSchema } from "../../lib/schemas.js";
|
|
7
28
|
|
|
8
29
|
// ---------------------------------------------------------------------------
|
|
@@ -46,13 +67,24 @@ const linkSchema = z.object({
|
|
|
46
67
|
trackedLinkId: z.string().nullable(),
|
|
47
68
|
originalUrl: z.string(),
|
|
48
69
|
type: z.enum(["personal", "public"]),
|
|
70
|
+
// Vanity slug (normalized lowercase, unique per instance) + its short URL
|
|
71
|
+
// (`${API_PUBLIC_URL}/l/:slug`). Both null when no slug is set.
|
|
72
|
+
slug: z.string().nullable(),
|
|
73
|
+
vanityUrl: z.string().nullable(),
|
|
49
74
|
label: z.string().nullable(),
|
|
75
|
+
// Longer operator note for bulk identification ("sticker on the door").
|
|
76
|
+
description: z.string().nullable(),
|
|
77
|
+
// Arrival attribution opt-in: redirects append `hs_ref=<click id>`.
|
|
78
|
+
appendRef: z.boolean(),
|
|
50
79
|
campaign: z.string().nullable(),
|
|
51
80
|
source: z.string(),
|
|
52
81
|
distinctId: z.string().nullable(),
|
|
53
82
|
createdBy: z.string().nullable(),
|
|
54
|
-
// Computed on read (summed across the link's tracked_links rows).
|
|
83
|
+
// Computed on read (summed across the link's tracked_links rows). The total
|
|
84
|
+
// across ALL entry paths — vanity, UUID, and QR scans.
|
|
55
85
|
clickCount: z.number(),
|
|
86
|
+
// The QR-only subtotal (clicks recorded on the link's `source: "qr"` row).
|
|
87
|
+
scanCount: z.number(),
|
|
56
88
|
// The short redirect URL: `${API_PUBLIC_URL}/v1/t/c/:trackedLinkId`.
|
|
57
89
|
url: z.string(),
|
|
58
90
|
archivedAt: z.string().nullable(),
|
|
@@ -66,14 +98,41 @@ const clickSchema = z.object({
|
|
|
66
98
|
ipAddress: z.string().nullable(),
|
|
67
99
|
userAgent: z.string().nullable(),
|
|
68
100
|
clickedAt: z.string(),
|
|
101
|
+
// Arrival stamp (POST /v1/t/arrive): who landed from THIS hit.
|
|
102
|
+
// `visitorKind` is the trust tier — 'token' = verified userId ("known
|
|
103
|
+
// contact"), 'anon' = the visitor's raw anon id (provenance only).
|
|
104
|
+
visitorDistinctId: z.string().nullable(),
|
|
105
|
+
visitorKind: z.string().nullable(),
|
|
106
|
+
arrivedAt: z.string().nullable(),
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
// Per-destination stats bucket: hits grouped by the destination that was live
|
|
110
|
+
// when they landed (link_clicks.destination_url). `url: null` = hits recorded
|
|
111
|
+
// before provenance stamping existed. `clicks` is the all-paths total for the
|
|
112
|
+
// bucket; `scans` its QR subtotal — mirroring clickCount/scanCount semantics.
|
|
113
|
+
const destinationStatSchema = z.object({
|
|
114
|
+
url: z.string().nullable(),
|
|
115
|
+
clicks: z.number(),
|
|
116
|
+
scans: z.number(),
|
|
117
|
+
firstAt: z.string(),
|
|
118
|
+
lastAt: z.string(),
|
|
69
119
|
});
|
|
70
120
|
|
|
71
121
|
const linkDetailSchema = linkSchema.extend({
|
|
72
122
|
clicks: z.array(clickSchema),
|
|
123
|
+
destinations: z.array(destinationStatSchema),
|
|
124
|
+
// Landing-confirmed arrivals (stamped hits). `identifiedArrivalCount` is
|
|
125
|
+
// the token-verified subset — "how many KNOWN contacts arrived".
|
|
126
|
+
arrivalCount: z.number(),
|
|
127
|
+
identifiedArrivalCount: z.number(),
|
|
73
128
|
});
|
|
74
129
|
|
|
75
130
|
type LinkRow = typeof links.$inferSelect;
|
|
76
|
-
type ClickAgg = {
|
|
131
|
+
type ClickAgg = {
|
|
132
|
+
clicks: number;
|
|
133
|
+
scans: number;
|
|
134
|
+
trackedLinkId: string | null;
|
|
135
|
+
};
|
|
77
136
|
|
|
78
137
|
// The short redirect URL for a link's tracked row, or a bare prefix if the link
|
|
79
138
|
// has no tracked row (should not happen for a minted link, but keep it total).
|
|
@@ -93,12 +152,17 @@ function serializeLink(
|
|
|
93
152
|
originalUrl: row.originalUrl,
|
|
94
153
|
// The column is a free text; mintLink only ever writes these two values.
|
|
95
154
|
type: row.type === "personal" ? "personal" : "public",
|
|
155
|
+
slug: row.slug,
|
|
156
|
+
vanityUrl: row.slug ? vanityUrlFor(baseUrl, row.slug) : null,
|
|
96
157
|
label: row.label,
|
|
158
|
+
description: row.description,
|
|
159
|
+
appendRef: row.appendRef,
|
|
97
160
|
campaign: row.campaign,
|
|
98
161
|
source: row.source,
|
|
99
162
|
distinctId: row.distinctId,
|
|
100
163
|
createdBy: row.createdBy,
|
|
101
164
|
clickCount: agg?.clicks ?? 0,
|
|
165
|
+
scanCount: agg?.scans ?? 0,
|
|
102
166
|
url: shortUrlFor(baseUrl, trackedLinkId),
|
|
103
167
|
archivedAt: row.archivedAt ? row.archivedAt.toISOString() : null,
|
|
104
168
|
createdAt: row.createdAt.toISOString(),
|
|
@@ -122,7 +186,12 @@ const createLinkRoute = createRoute({
|
|
|
122
186
|
schema: z.object({
|
|
123
187
|
url: z.string().url(),
|
|
124
188
|
type: z.enum(["personal", "public"]).default("public"),
|
|
189
|
+
// Optional vanity slug (`/l/:slug`). Normalized lowercase; 409 if
|
|
190
|
+
// already taken.
|
|
191
|
+
slug: z.string().optional(),
|
|
125
192
|
label: z.string().optional(),
|
|
193
|
+
description: z.string().optional(),
|
|
194
|
+
appendRef: z.boolean().optional(),
|
|
126
195
|
campaign: z.string().optional(),
|
|
127
196
|
// Honoured ONLY for personal links (the share-safe invariant in
|
|
128
197
|
// mintLink drops it for public). A canonical contact key the click
|
|
@@ -140,7 +209,11 @@ const createLinkRoute = createRoute({
|
|
|
140
209
|
},
|
|
141
210
|
400: {
|
|
142
211
|
content: { "application/json": { schema: errorSchema } },
|
|
143
|
-
description: "Invalid destination URL",
|
|
212
|
+
description: "Invalid destination URL or slug",
|
|
213
|
+
},
|
|
214
|
+
409: {
|
|
215
|
+
content: { "application/json": { schema: errorSchema } },
|
|
216
|
+
description: "Slug already taken",
|
|
144
217
|
},
|
|
145
218
|
},
|
|
146
219
|
});
|
|
@@ -156,6 +229,11 @@ const listLinksRoute = createRoute({
|
|
|
156
229
|
offset: z.coerce.number().min(0).default(0),
|
|
157
230
|
type: z.enum(["personal", "public"]).optional(),
|
|
158
231
|
includeArchived: z.coerce.boolean().default(false),
|
|
232
|
+
// true = only links whose QR scan row exists — the "QR codes" lens
|
|
233
|
+
// (a QR code IS a managed link whose QR row has been minted).
|
|
234
|
+
// stringbool, NOT coerce.boolean: coerce turns the string "false" into
|
|
235
|
+
// true (any non-empty string is truthy), inverting ?hasQr=false.
|
|
236
|
+
hasQr: z.stringbool().optional(),
|
|
159
237
|
}),
|
|
160
238
|
},
|
|
161
239
|
responses: {
|
|
@@ -207,7 +285,12 @@ const updateLinkRoute = createRoute({
|
|
|
207
285
|
// NOT NULL on both tables — omit = no change, provide = re-target
|
|
208
286
|
// both links.originalUrl and the linked tracked_links row.
|
|
209
287
|
originalUrl: z.string().url().optional(),
|
|
288
|
+
// omit = no change; string = set/replace (409 if taken); null =
|
|
289
|
+
// clear the slug (frees it for reuse).
|
|
290
|
+
slug: z.string().nullable().optional(),
|
|
210
291
|
label: z.string().nullable().optional(),
|
|
292
|
+
description: z.string().nullable().optional(),
|
|
293
|
+
appendRef: z.boolean().optional(),
|
|
211
294
|
campaign: z.string().nullable().optional(),
|
|
212
295
|
}),
|
|
213
296
|
},
|
|
@@ -221,12 +304,44 @@ const updateLinkRoute = createRoute({
|
|
|
221
304
|
},
|
|
222
305
|
400: {
|
|
223
306
|
content: { "application/json": { schema: errorSchema } },
|
|
224
|
-
description: "Invalid destination URL",
|
|
307
|
+
description: "Invalid destination URL or slug",
|
|
225
308
|
},
|
|
226
309
|
404: {
|
|
227
310
|
content: { "application/json": { schema: errorSchema } },
|
|
228
311
|
description: "Link not found",
|
|
229
312
|
},
|
|
313
|
+
409: {
|
|
314
|
+
content: { "application/json": { schema: errorSchema } },
|
|
315
|
+
description: "Slug already taken",
|
|
316
|
+
},
|
|
317
|
+
},
|
|
318
|
+
});
|
|
319
|
+
|
|
320
|
+
const qrLinkRoute = createRoute({
|
|
321
|
+
method: "get",
|
|
322
|
+
path: "/{id}/qr",
|
|
323
|
+
tags: ["Admin — Links"],
|
|
324
|
+
summary: "Render a link's QR code (lazy-mints its scan row)",
|
|
325
|
+
request: {
|
|
326
|
+
params: z.object({ id: z.string().uuid() }),
|
|
327
|
+
query: z.object({
|
|
328
|
+
format: z.enum(["svg", "png"]).default("svg"),
|
|
329
|
+
// Rendered pixel width. QR content is size-independent (same encoded
|
|
330
|
+
// URL), so this only affects raster/viewport dimensions.
|
|
331
|
+
size: z.coerce.number().min(64).max(2048).default(512),
|
|
332
|
+
// Transparent background (both formats) — for print/overlay use where
|
|
333
|
+
// the artwork supplies its own background. stringbool, NOT
|
|
334
|
+
// coerce.boolean: coerce would turn ?transparent=false into true and
|
|
335
|
+
// ship an invisible-on-white QR.
|
|
336
|
+
transparent: z.stringbool().default(false),
|
|
337
|
+
}),
|
|
338
|
+
},
|
|
339
|
+
responses: {
|
|
340
|
+
200: { description: "QR image (SVG or PNG) encoding the scan URL" },
|
|
341
|
+
404: {
|
|
342
|
+
content: { "application/json": { schema: errorSchema } },
|
|
343
|
+
description: "Link not found",
|
|
344
|
+
},
|
|
230
345
|
},
|
|
231
346
|
});
|
|
232
347
|
|
|
@@ -252,9 +367,10 @@ type Db = AppEnv["Variables"]["container"]["db"];
|
|
|
252
367
|
|
|
253
368
|
// Aggregates each link's tracked_links rows in ONE grouped query: the summed
|
|
254
369
|
// click_count (computed on read — no denormalized counter on `links`) and the
|
|
255
|
-
// link's redirect id
|
|
256
|
-
//
|
|
257
|
-
//
|
|
370
|
+
// link's redirect id — the CANONICAL tracked row (minted alongside the link),
|
|
371
|
+
// never the per-link QR scan row, via the shared canonical-row predicate.
|
|
372
|
+
// Returns a map keyed by link id; links with no tracked rows are simply absent
|
|
373
|
+
// (callers default to 0 / a bare prefix).
|
|
258
374
|
async function aggregateFor(
|
|
259
375
|
db: Db,
|
|
260
376
|
linkIds: string[],
|
|
@@ -267,7 +383,12 @@ async function aggregateFor(
|
|
|
267
383
|
clicks: sql<number>`coalesce(${sum(trackedLinks.clickCount)}, 0)`.mapWith(
|
|
268
384
|
Number,
|
|
269
385
|
),
|
|
270
|
-
|
|
386
|
+
// QR-only subtotal — the complement of the canonical-row predicate.
|
|
387
|
+
scans:
|
|
388
|
+
sql<number>`coalesce(${sum(trackedLinks.clickCount)} filter (where not (${canonicalTrackedRowFilter()})), 0)`.mapWith(
|
|
389
|
+
Number,
|
|
390
|
+
),
|
|
391
|
+
trackedLinkId: sql<string>`min(${trackedLinks.id}::text) filter (where ${canonicalTrackedRowFilter()})`,
|
|
271
392
|
})
|
|
272
393
|
.from(trackedLinks)
|
|
273
394
|
.where(inArray(trackedLinks.linkId, linkIds))
|
|
@@ -276,6 +397,7 @@ async function aggregateFor(
|
|
|
276
397
|
if (r.linkId) {
|
|
277
398
|
map.set(r.linkId, {
|
|
278
399
|
clicks: r.clicks,
|
|
400
|
+
scans: r.scans,
|
|
279
401
|
trackedLinkId: r.trackedLinkId ?? null,
|
|
280
402
|
});
|
|
281
403
|
}
|
|
@@ -295,7 +417,10 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
295
417
|
baseUrl: env.API_PUBLIC_URL,
|
|
296
418
|
source: "studio",
|
|
297
419
|
type: body.type,
|
|
420
|
+
slug: body.slug,
|
|
298
421
|
label: body.label,
|
|
422
|
+
description: body.description,
|
|
423
|
+
appendRef: body.appendRef,
|
|
299
424
|
campaign: body.campaign,
|
|
300
425
|
distinctId: body.distinctId,
|
|
301
426
|
createdBy: resolveActor(c) ?? undefined,
|
|
@@ -314,23 +439,42 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
314
439
|
return c.json(
|
|
315
440
|
serializeLink(
|
|
316
441
|
row,
|
|
317
|
-
{ clicks: 0, trackedLinkId: minted.trackedLinkId },
|
|
442
|
+
{ clicks: 0, scans: 0, trackedLinkId: minted.trackedLinkId },
|
|
318
443
|
env.API_PUBLIC_URL,
|
|
319
444
|
),
|
|
320
445
|
200,
|
|
321
446
|
);
|
|
322
447
|
} catch (err) {
|
|
448
|
+
if (err instanceof SlugTakenError) {
|
|
449
|
+
return c.json({ error: err.message }, 409);
|
|
450
|
+
}
|
|
323
451
|
const message = err instanceof Error ? err.message : "Mint failed";
|
|
324
452
|
return c.json({ error: message }, 400);
|
|
325
453
|
}
|
|
326
454
|
})
|
|
327
455
|
.openapi(listLinksRoute, async (c) => {
|
|
328
456
|
const { db, env } = c.get("container");
|
|
329
|
-
const { limit, offset, type, includeArchived } =
|
|
457
|
+
const { limit, offset, type, includeArchived, hasQr } =
|
|
458
|
+
c.req.valid("query");
|
|
330
459
|
|
|
331
460
|
const where = and(
|
|
332
461
|
includeArchived ? undefined : isNull(links.archivedAt),
|
|
333
462
|
type ? eq(links.type, type) : undefined,
|
|
463
|
+
// The QR lens: membership = the QR scan row exists (lazily minted on
|
|
464
|
+
// first QR render), not "has been scanned".
|
|
465
|
+
hasQr
|
|
466
|
+
? exists(
|
|
467
|
+
db
|
|
468
|
+
.select({ one: sql`1` })
|
|
469
|
+
.from(trackedLinks)
|
|
470
|
+
.where(
|
|
471
|
+
and(
|
|
472
|
+
eq(trackedLinks.linkId, links.id),
|
|
473
|
+
eq(trackedLinks.source, QR_TRACKED_SOURCE),
|
|
474
|
+
),
|
|
475
|
+
),
|
|
476
|
+
)
|
|
477
|
+
: undefined,
|
|
334
478
|
);
|
|
335
479
|
|
|
336
480
|
const [rows, totalRows] = await Promise.all([
|
|
@@ -376,8 +520,11 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
376
520
|
}
|
|
377
521
|
|
|
378
522
|
// Recent clicks joined via the link's tracked_links rows, newest first,
|
|
379
|
-
// capped. The aggregate gives the summed count + the redirect id.
|
|
380
|
-
|
|
523
|
+
// capped. The aggregate gives the summed count + the redirect id. The
|
|
524
|
+
// destination buckets group EVERY hit by the target that was live when it
|
|
525
|
+
// landed (per-hit provenance) — most-recent activity first, so the current
|
|
526
|
+
// destination leads.
|
|
527
|
+
const [agg, clickRows, destinationRows, arrivalAgg] = await Promise.all([
|
|
381
528
|
aggregateFor(db, [id]),
|
|
382
529
|
db
|
|
383
530
|
.select({
|
|
@@ -386,12 +533,45 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
386
533
|
ipAddress: linkClicks.ipAddress,
|
|
387
534
|
userAgent: linkClicks.userAgent,
|
|
388
535
|
clickedAt: linkClicks.clickedAt,
|
|
536
|
+
visitorDistinctId: linkClicks.visitorDistinctId,
|
|
537
|
+
visitorKind: linkClicks.visitorKind,
|
|
538
|
+
arrivedAt: linkClicks.arrivedAt,
|
|
389
539
|
})
|
|
390
540
|
.from(linkClicks)
|
|
391
541
|
.innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
|
|
392
542
|
.where(eq(trackedLinks.linkId, id))
|
|
393
543
|
.orderBy(desc(linkClicks.clickedAt))
|
|
394
544
|
.limit(50),
|
|
545
|
+
db
|
|
546
|
+
.select({
|
|
547
|
+
url: linkClicks.destinationUrl,
|
|
548
|
+
clicks: count().mapWith(Number),
|
|
549
|
+
scans:
|
|
550
|
+
sql<number>`count(*) filter (where not (${canonicalTrackedRowFilter()}))`.mapWith(
|
|
551
|
+
Number,
|
|
552
|
+
),
|
|
553
|
+
firstAt: sql<string>`min(${linkClicks.clickedAt})`,
|
|
554
|
+
lastAt: sql<string>`max(${linkClicks.clickedAt})`,
|
|
555
|
+
})
|
|
556
|
+
.from(linkClicks)
|
|
557
|
+
.innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
|
|
558
|
+
.where(eq(trackedLinks.linkId, id))
|
|
559
|
+
.groupBy(linkClicks.destinationUrl)
|
|
560
|
+
.orderBy(desc(sql`max(${linkClicks.clickedAt})`)),
|
|
561
|
+
db
|
|
562
|
+
.select({
|
|
563
|
+
arrivals:
|
|
564
|
+
sql<number>`count(*) filter (where ${linkClicks.visitorDistinctId} is not null)`.mapWith(
|
|
565
|
+
Number,
|
|
566
|
+
),
|
|
567
|
+
identified:
|
|
568
|
+
sql<number>`count(*) filter (where ${linkClicks.visitorKind} = 'token')`.mapWith(
|
|
569
|
+
Number,
|
|
570
|
+
),
|
|
571
|
+
})
|
|
572
|
+
.from(linkClicks)
|
|
573
|
+
.innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
|
|
574
|
+
.where(eq(trackedLinks.linkId, id)),
|
|
395
575
|
]);
|
|
396
576
|
|
|
397
577
|
return c.json(
|
|
@@ -403,7 +583,19 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
403
583
|
ipAddress: cl.ipAddress,
|
|
404
584
|
userAgent: cl.userAgent,
|
|
405
585
|
clickedAt: cl.clickedAt.toISOString(),
|
|
586
|
+
visitorDistinctId: cl.visitorDistinctId,
|
|
587
|
+
visitorKind: cl.visitorKind,
|
|
588
|
+
arrivedAt: cl.arrivedAt ? cl.arrivedAt.toISOString() : null,
|
|
589
|
+
})),
|
|
590
|
+
destinations: destinationRows.map((d) => ({
|
|
591
|
+
url: d.url,
|
|
592
|
+
clicks: d.clicks,
|
|
593
|
+
scans: d.scans,
|
|
594
|
+
firstAt: new Date(d.firstAt).toISOString(),
|
|
595
|
+
lastAt: new Date(d.lastAt).toISOString(),
|
|
406
596
|
})),
|
|
597
|
+
arrivalCount: arrivalAgg[0]?.arrivals ?? 0,
|
|
598
|
+
identifiedArrivalCount: arrivalAgg[0]?.identified ?? 0,
|
|
407
599
|
},
|
|
408
600
|
200,
|
|
409
601
|
);
|
|
@@ -427,39 +619,72 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
427
619
|
}
|
|
428
620
|
|
|
429
621
|
const patch: Partial<
|
|
430
|
-
Pick<
|
|
622
|
+
Pick<
|
|
623
|
+
LinkRow,
|
|
624
|
+
| "label"
|
|
625
|
+
| "description"
|
|
626
|
+
| "appendRef"
|
|
627
|
+
| "campaign"
|
|
628
|
+
| "originalUrl"
|
|
629
|
+
| "slug"
|
|
630
|
+
>
|
|
431
631
|
> & {
|
|
432
632
|
updatedAt: Date;
|
|
433
633
|
} = { updatedAt: new Date() };
|
|
434
634
|
if (body.label !== undefined) patch.label = body.label;
|
|
635
|
+
if (body.description !== undefined) patch.description = body.description;
|
|
636
|
+
if (body.appendRef !== undefined) patch.appendRef = body.appendRef;
|
|
435
637
|
if (body.campaign !== undefined) patch.campaign = body.campaign;
|
|
436
638
|
if (body.originalUrl !== undefined) patch.originalUrl = body.originalUrl;
|
|
639
|
+
// Slug: string = set/replace (normalized, 409 on conflict below); null =
|
|
640
|
+
// clear, freeing it for reuse.
|
|
641
|
+
if (body.slug !== undefined) {
|
|
642
|
+
if (body.slug === null) {
|
|
643
|
+
patch.slug = null;
|
|
644
|
+
} else {
|
|
645
|
+
try {
|
|
646
|
+
patch.slug = normalizeSlug(body.slug);
|
|
647
|
+
} catch (err) {
|
|
648
|
+
const message = err instanceof Error ? err.message : "Invalid slug";
|
|
649
|
+
return c.json({ error: message }, 400);
|
|
650
|
+
}
|
|
651
|
+
}
|
|
652
|
+
}
|
|
437
653
|
|
|
438
654
|
// Both writes in ONE transaction so the two originalUrls can never diverge.
|
|
439
655
|
// CRITICAL: the click redirect reads tracked_links.originalUrl fresh per
|
|
440
656
|
// hit (no cache), NOT links.originalUrl — so re-targeting MUST also update
|
|
441
|
-
// the
|
|
442
|
-
//
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
657
|
+
// the link's tracked_links rows (scoped by link_id — the managed redirect
|
|
658
|
+
// row, plus the QR scan row once one is minted). The links row is the
|
|
659
|
+
// display/source of truth.
|
|
660
|
+
let updated: LinkRow | null;
|
|
661
|
+
try {
|
|
662
|
+
updated = await db.transaction(async (tx) => {
|
|
663
|
+
const [row] = await tx
|
|
664
|
+
.update(links)
|
|
665
|
+
.set(patch)
|
|
666
|
+
.where(eq(links.id, id))
|
|
667
|
+
.returning();
|
|
668
|
+
|
|
669
|
+
// Signal 404 to the caller; returning null (vs throwing) commits an
|
|
670
|
+
// empty tx and avoids bubbling as a 500.
|
|
671
|
+
if (!row) return null;
|
|
672
|
+
|
|
673
|
+
if (body.originalUrl !== undefined) {
|
|
674
|
+
await tx
|
|
675
|
+
.update(trackedLinks)
|
|
676
|
+
.set({ originalUrl: body.originalUrl, updatedAt: new Date() })
|
|
677
|
+
.where(eq(trackedLinks.linkId, id));
|
|
678
|
+
}
|
|
679
|
+
|
|
680
|
+
return row;
|
|
681
|
+
});
|
|
682
|
+
} catch (err) {
|
|
683
|
+
if (patch.slug && isSlugUniqueViolation(err)) {
|
|
684
|
+
return c.json({ error: new SlugTakenError(patch.slug).message }, 409);
|
|
459
685
|
}
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
});
|
|
686
|
+
throw err;
|
|
687
|
+
}
|
|
463
688
|
|
|
464
689
|
if (!updated) {
|
|
465
690
|
return c.json({ error: "Link not found" }, 404);
|
|
@@ -471,6 +696,48 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
471
696
|
200,
|
|
472
697
|
);
|
|
473
698
|
})
|
|
699
|
+
.openapi(qrLinkRoute, async (c) => {
|
|
700
|
+
const { db, env } = c.get("container");
|
|
701
|
+
const { id } = c.req.valid("param");
|
|
702
|
+
const { format, size, transparent } = c.req.valid("query");
|
|
703
|
+
|
|
704
|
+
// Lazy-mints the link's QR scan row on first render (race-safe via the
|
|
705
|
+
// partial unique index). An archived link still renders — archive never
|
|
706
|
+
// kills distributed artifacts, and a printed code is the most distributed
|
|
707
|
+
// artifact there is.
|
|
708
|
+
const qr = await ensureQrTrackedLink({ db, linkId: id });
|
|
709
|
+
if (!qr) {
|
|
710
|
+
return c.json({ error: "Link not found" }, 404);
|
|
711
|
+
}
|
|
712
|
+
|
|
713
|
+
// The QR encodes the DURABLE UID redirect — never the vanity slug — so a
|
|
714
|
+
// printed code survives slug changes AND re-targeting (PATCH updates the
|
|
715
|
+
// scan row's destination alongside the canonical row).
|
|
716
|
+
const scanUrl = `${env.API_PUBLIC_URL}/v1/t/c/${qr.trackedLinkId}`;
|
|
717
|
+
|
|
718
|
+
// Same-content caching: the encoded URL is immutable for the link's
|
|
719
|
+
// lifetime, so clients (the Studio <img>) may cache; private because the
|
|
720
|
+
// endpoint is admin-authed.
|
|
721
|
+
c.header("Cache-Control", "private, max-age=3600");
|
|
722
|
+
|
|
723
|
+
const render = {
|
|
724
|
+
width: size,
|
|
725
|
+
errorCorrectionLevel: "M" as const,
|
|
726
|
+
// "#0000" = fully transparent light modules; default is opaque white.
|
|
727
|
+
...(transparent ? { color: { light: "#0000" } } : {}),
|
|
728
|
+
};
|
|
729
|
+
|
|
730
|
+
if (format === "png") {
|
|
731
|
+
const png = await QRCode.toBuffer(scanUrl, render);
|
|
732
|
+
c.header("Content-Type", "image/png");
|
|
733
|
+
// Re-wrap: hono's `c.body` Data type doesn't accept Node's Buffer.
|
|
734
|
+
return c.body(new Uint8Array(png));
|
|
735
|
+
}
|
|
736
|
+
|
|
737
|
+
const svg = await QRCode.toString(scanUrl, { ...render, type: "svg" });
|
|
738
|
+
c.header("Content-Type", "image/svg+xml");
|
|
739
|
+
return c.body(svg);
|
|
740
|
+
})
|
|
474
741
|
.openapi(archiveLinkRoute, async (c) => {
|
|
475
742
|
const { db, env } = c.get("container");
|
|
476
743
|
const { id } = c.req.valid("param");
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
2
|
+
import type { AppEnv } from "../../app.js";
|
|
3
|
+
import { getListRegistry } from "../../lists/registry-singleton.js";
|
|
4
|
+
|
|
5
|
+
const listSchema = z.object({
|
|
6
|
+
id: z.string(),
|
|
7
|
+
name: z.string(),
|
|
8
|
+
description: z.string().optional(),
|
|
9
|
+
defaultOptIn: z.boolean(),
|
|
10
|
+
enabled: z.boolean(),
|
|
11
|
+
// `"topic"` = author-defined (`defineList`); `"channel"` = engine-synthesized
|
|
12
|
+
// delivery channel (the in-app feed + one per member-directed connector).
|
|
13
|
+
kind: z.enum(["channel", "topic"]),
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
const listRoute = createRoute({
|
|
17
|
+
method: "get",
|
|
18
|
+
path: "/",
|
|
19
|
+
tags: ["Admin — Lists"],
|
|
20
|
+
summary: "List all registered lists",
|
|
21
|
+
description:
|
|
22
|
+
"Returns EVERY registered list — author-defined topics AND engine-synthesized channels — with its `kind`. Reads the process `ListRegistry` directly (no DB); mirrors the catalog the mailer and preference center resolve against.",
|
|
23
|
+
responses: {
|
|
24
|
+
200: {
|
|
25
|
+
content: {
|
|
26
|
+
"application/json": {
|
|
27
|
+
schema: z.object({ lists: z.array(listSchema) }),
|
|
28
|
+
},
|
|
29
|
+
},
|
|
30
|
+
description: "All registered lists (topics + channels)",
|
|
31
|
+
},
|
|
32
|
+
},
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
export const adminListsRouter = new OpenAPIHono<AppEnv>().openapi(
|
|
36
|
+
listRoute,
|
|
37
|
+
(c) => {
|
|
38
|
+
const lists = getListRegistry()
|
|
39
|
+
.getAll()
|
|
40
|
+
.map((l) => ({
|
|
41
|
+
id: l.id,
|
|
42
|
+
name: l.name,
|
|
43
|
+
...(l.description !== undefined ? { description: l.description } : {}),
|
|
44
|
+
defaultOptIn: l.defaultOptIn,
|
|
45
|
+
enabled: l.enabled,
|
|
46
|
+
kind: l.kind ?? "topic",
|
|
47
|
+
}));
|
|
48
|
+
|
|
49
|
+
return c.json({ lists }, 200);
|
|
50
|
+
},
|
|
51
|
+
);
|
|
@@ -54,10 +54,26 @@ export const campaignSchema = z.object({
|
|
|
54
54
|
audienceKind: z.string(),
|
|
55
55
|
audienceId: z.string(),
|
|
56
56
|
templateKey: z.string(),
|
|
57
|
+
subject: z.string().nullable(),
|
|
58
|
+
fromEmail: z.string().nullable(),
|
|
57
59
|
totalRecipients: z.number(),
|
|
58
60
|
sentCount: z.number(),
|
|
59
61
|
skippedCount: z.number(),
|
|
60
62
|
failedCount: z.number(),
|
|
63
|
+
/**
|
|
64
|
+
* Multi-step wave definition — the stored blob's steps array verbatim
|
|
65
|
+
* (`docs/campaign-steps-spec.md`; elements are `CampaignStep` data). NULL =
|
|
66
|
+
* legacy single-send campaign (templateKey/subject/fromEmail are the whole
|
|
67
|
+
* send).
|
|
68
|
+
*/
|
|
69
|
+
steps: z.array(z.record(z.string(), z.unknown())).nullable(),
|
|
70
|
+
/** The next step to execute — the wave runtime's sole resume cursor. */
|
|
71
|
+
currentStep: z.number(),
|
|
72
|
+
/**
|
|
73
|
+
* When a `waiting` campaign's pending wait elapses (ISO 8601). Mirror of
|
|
74
|
+
* `scheduledAt`; null unless a wait is pending.
|
|
75
|
+
*/
|
|
76
|
+
nextStepAt: z.string().nullable(),
|
|
61
77
|
scheduledAt: z.string().nullable(),
|
|
62
78
|
canceledAt: z.string().nullable(),
|
|
63
79
|
startedAt: z.string().nullable(),
|
|
@@ -77,10 +93,15 @@ export function serializeCampaign(
|
|
|
77
93
|
audienceKind: campaign.audienceKind,
|
|
78
94
|
audienceId: campaign.audienceId,
|
|
79
95
|
templateKey: campaign.templateKey,
|
|
96
|
+
subject: campaign.subject,
|
|
97
|
+
fromEmail: campaign.fromEmail,
|
|
80
98
|
totalRecipients: campaign.totalRecipients,
|
|
81
99
|
sentCount: campaign.sentCount,
|
|
82
100
|
skippedCount: campaign.skippedCount,
|
|
83
101
|
failedCount: campaign.failedCount,
|
|
102
|
+
steps: campaign.steps?.steps ?? null,
|
|
103
|
+
currentStep: campaign.currentStep,
|
|
104
|
+
nextStepAt: campaign.nextStepAt?.toISOString() ?? null,
|
|
84
105
|
scheduledAt: campaign.scheduledAt?.toISOString() ?? null,
|
|
85
106
|
canceledAt: campaign.canceledAt?.toISOString() ?? null,
|
|
86
107
|
startedAt: campaign.startedAt?.toISOString() ?? null,
|
|
@@ -178,7 +199,7 @@ const cancelRouteDef = createRoute({
|
|
|
178
199
|
tags: ["Campaigns"],
|
|
179
200
|
summary: "Cancel a campaign",
|
|
180
201
|
description:
|
|
181
|
-
"Cancels a `scheduled`, `queued`, or `
|
|
202
|
+
"Cancels a `scheduled`, `queued`, `sending`, or `waiting` campaign. A mid-send cancel stops the blast at the next chunk boundary — recipients not yet dispatched are spared; already-dispatched sends are not recalled. Canceling a `waiting` multi-step campaign spares every remaining wave (its pending next-step run no-ops on the terminal guard).",
|
|
182
203
|
request: {
|
|
183
204
|
params: z.object({ id: z.string() }),
|
|
184
205
|
},
|
|
@@ -263,6 +284,16 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
|
|
|
263
284
|
if (audienceKind === "list" && !listRegistry.has(audienceId)) {
|
|
264
285
|
return c.json({ error: `Unknown list: ${audienceId}` }, 404);
|
|
265
286
|
}
|
|
287
|
+
// A list-audience campaign resolves recipients by SUBSCRIPTION. A channel
|
|
288
|
+
// preference list (`kind:"channel"`) gates a delivery transport (the in-app
|
|
289
|
+
// feed, a connector), not an email topic — a channel audience would EMAIL
|
|
290
|
+
// everyone not opted out of e.g. the discord channel. Reject it.
|
|
291
|
+
if (audienceKind === "list" && listRegistry.isChannel(audienceId)) {
|
|
292
|
+
return c.json(
|
|
293
|
+
{ error: `a channel preference list cannot be a campaign audience` },
|
|
294
|
+
400,
|
|
295
|
+
);
|
|
296
|
+
}
|
|
266
297
|
if (audienceKind === "bucket" && !bucketRegistry.has(audienceId)) {
|
|
267
298
|
return c.json({ error: `Unknown bucket: ${audienceId}` }, 404);
|
|
268
299
|
}
|
|
@@ -421,10 +452,12 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
|
|
|
421
452
|
const { db } = c.get("container");
|
|
422
453
|
const { id } = c.req.valid("param");
|
|
423
454
|
|
|
424
|
-
// CAS: only a cancelable status transitions
|
|
425
|
-
//
|
|
426
|
-
//
|
|
427
|
-
//
|
|
455
|
+
// CAS: only a cancelable status transitions (allowed from
|
|
456
|
+
// scheduled/queued/sending/waiting), so a concurrent completion (or a
|
|
457
|
+
// second cancel) is never overwritten. The punctual Hatchet scheduled run
|
|
458
|
+
// for a canceled campaign — a `scheduled` row's send or a `waiting` row's
|
|
459
|
+
// pending next-step — still fires but no-ops on the terminal guard; a
|
|
460
|
+
// `sending` blast stops at its next chunk boundary.
|
|
428
461
|
const canceled = await db
|
|
429
462
|
.update(campaigns)
|
|
430
463
|
.set({
|
|
@@ -435,7 +468,12 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
|
|
|
435
468
|
.where(
|
|
436
469
|
and(
|
|
437
470
|
eq(campaigns.id, id),
|
|
438
|
-
inArray(campaigns.status, [
|
|
471
|
+
inArray(campaigns.status, [
|
|
472
|
+
"scheduled",
|
|
473
|
+
"queued",
|
|
474
|
+
"sending",
|
|
475
|
+
"waiting",
|
|
476
|
+
]),
|
|
439
477
|
),
|
|
440
478
|
)
|
|
441
479
|
.returning();
|