@hogsend/engine 0.52.1 → 0.54.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 +12 -11
- package/src/connectors/define-action.ts +15 -2
- package/src/container.ts +85 -0
- package/src/env.ts +21 -0
- package/src/index.ts +20 -0
- package/src/journeys/durable-law-harness.test.ts +107 -0
- package/src/journeys/durable-law-harness.ts +139 -0
- package/src/journeys/journey-boundary.test.ts +70 -0
- package/src/journeys/journey-boundary.ts +10 -1
- package/src/journeys/with-durable-gate.test.ts +258 -0
- package/src/journeys/with-durable-gate.ts +141 -0
- package/src/lib/connector-actions.test.ts +292 -1
- package/src/lib/connector-actions.ts +65 -6
- package/src/lib/enrichment-ledger.ts +207 -0
- package/src/lib/enrichment-provider-registry.test.ts +64 -0
- package/src/lib/enrichment-provider-registry.ts +35 -0
- package/src/lib/enrichment-providers-from-env.apollo.test.ts +30 -0
- package/src/lib/enrichment-providers-from-env.test.ts +67 -0
- package/src/lib/enrichment-providers-from-env.ts +85 -0
- package/src/lib/enrichment-registry-singleton.ts +45 -0
- package/src/lib/links.ts +118 -7
- package/src/lib/outbound.ts +27 -0
- package/src/lib/refine-chain.test.ts +764 -0
- package/src/lib/refine-chain.ts +583 -0
- package/src/lib/refine-traits.test.ts +141 -0
- package/src/lib/refine-traits.ts +128 -0
- package/src/lib/refine.ts +287 -0
- package/src/lib/webhook-catalog-sync.test.ts +112 -0
- package/src/lib/webhook-signing.ts +5 -1
- package/src/routes/admin/contacts.ts +113 -13
- package/src/routes/admin/links.ts +57 -25
|
@@ -65,22 +65,55 @@ const contactGroupSchema = z.object({
|
|
|
65
65
|
joinedAt: z.string(),
|
|
66
66
|
});
|
|
67
67
|
|
|
68
|
+
/**
|
|
69
|
+
* PRD 06 — validation gate for a jsonb property key used in ordering or
|
|
70
|
+
* filtering. This is a REJECTION layer only: the key is additionally ALWAYS
|
|
71
|
+
* bound as a SQL parameter in the query builder (never interpolated), so the
|
|
72
|
+
* two layers are independent defences, not substitutes for each other.
|
|
73
|
+
*/
|
|
74
|
+
const PROPERTY_KEY_RE = /^[A-Za-z0-9_.-]{1,64}$/;
|
|
75
|
+
|
|
68
76
|
const listRoute = createRoute({
|
|
69
77
|
method: "get",
|
|
70
78
|
path: "/",
|
|
71
79
|
tags: ["Admin"],
|
|
72
80
|
summary: "List contacts",
|
|
73
81
|
request: {
|
|
74
|
-
query: z
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
82
|
+
query: z
|
|
83
|
+
.object({
|
|
84
|
+
limit: z.coerce.number().min(1).max(100).default(50),
|
|
85
|
+
offset: z.coerce.number().min(0).default(0),
|
|
86
|
+
search: z.string().optional(),
|
|
87
|
+
// Long-tail value filters (plan §4b.3): the "find my value customers"
|
|
88
|
+
// query surface.
|
|
89
|
+
minRevenue: z.coerce.number().optional(),
|
|
90
|
+
// Plain string: valid stages are the deployment's configured ladder.
|
|
91
|
+
dealStage: z.string().optional(),
|
|
92
|
+
// Leaderboard surface (PRD 06): rank contacts by the NUMERIC value of
|
|
93
|
+
// a jsonb property ("who do I call today"). Defaults reproduce the
|
|
94
|
+
// pre-existing behaviour exactly (ORDER BY last_seen_at DESC).
|
|
95
|
+
orderBy: z
|
|
96
|
+
.enum(["lastSeenAt", "firstSeenAt", "property"])
|
|
97
|
+
.default("lastSeenAt"),
|
|
98
|
+
orderProperty: z.string().regex(PROPERTY_KEY_RE).optional(),
|
|
99
|
+
orderDir: z.enum(["asc", "desc"]).default("desc"),
|
|
100
|
+
// Numeric property filter: only contacts whose value at `propertyKey`
|
|
101
|
+
// is a real JSON number ≥ `propertyGte`. Composable with ordering.
|
|
102
|
+
propertyKey: z.string().regex(PROPERTY_KEY_RE).optional(),
|
|
103
|
+
propertyGte: z.coerce.number().optional(),
|
|
104
|
+
})
|
|
105
|
+
.refine(
|
|
106
|
+
(q) => q.orderBy !== "property" || q.orderProperty !== undefined,
|
|
107
|
+
{
|
|
108
|
+
message: "orderProperty is required when orderBy=property",
|
|
109
|
+
},
|
|
110
|
+
)
|
|
111
|
+
.refine(
|
|
112
|
+
(q) => q.propertyGte === undefined || q.propertyKey !== undefined,
|
|
113
|
+
{
|
|
114
|
+
message: "propertyKey is required when propertyGte is set",
|
|
115
|
+
},
|
|
116
|
+
),
|
|
84
117
|
},
|
|
85
118
|
responses: {
|
|
86
119
|
200: {
|
|
@@ -96,6 +129,16 @@ const listRoute = createRoute({
|
|
|
96
129
|
},
|
|
97
130
|
description: "Paginated contact list",
|
|
98
131
|
},
|
|
132
|
+
400: {
|
|
133
|
+
content: {
|
|
134
|
+
"application/json": {
|
|
135
|
+
// zod-openapi's default validation hook shape (ZodError passthrough).
|
|
136
|
+
schema: z.object({ success: z.boolean() }).passthrough(),
|
|
137
|
+
},
|
|
138
|
+
},
|
|
139
|
+
description:
|
|
140
|
+
"Invalid query (bad property key, or orderBy=property without orderProperty)",
|
|
141
|
+
},
|
|
99
142
|
},
|
|
100
143
|
});
|
|
101
144
|
|
|
@@ -246,11 +289,67 @@ const serializeContact = (row: typeof contacts.$inferSelect) =>
|
|
|
246
289
|
export const contactsRouter = new OpenAPIHono<AppEnv>()
|
|
247
290
|
.openapi(listRoute, async (c) => {
|
|
248
291
|
const { db } = c.get("container");
|
|
249
|
-
const {
|
|
250
|
-
|
|
292
|
+
const {
|
|
293
|
+
limit,
|
|
294
|
+
offset,
|
|
295
|
+
search,
|
|
296
|
+
minRevenue,
|
|
297
|
+
dealStage,
|
|
298
|
+
orderBy,
|
|
299
|
+
orderProperty,
|
|
300
|
+
orderDir,
|
|
301
|
+
propertyKey,
|
|
302
|
+
propertyGte,
|
|
303
|
+
} = c.req.valid("query");
|
|
251
304
|
|
|
252
305
|
const searchFilter = search ? contactSearchFilter(search) : undefined;
|
|
253
306
|
|
|
307
|
+
// Type-guarded numeric read of a jsonb property (PRD 06 / DECISIONS §3.4).
|
|
308
|
+
// `contacts.properties` is untyped jsonb and `/v1/events` accepts arbitrary
|
|
309
|
+
// values, so a bare `(properties->>key)::numeric` raises Postgres 22P02 —
|
|
310
|
+
// and 500s the whole request — the first time ONE contact holds e.g. "n/a"
|
|
311
|
+
// at the key. Only real JSON numbers count; anything else yields NULL
|
|
312
|
+
// (sorted last, excluded by the ≥ filter). The key rides as a BOUND
|
|
313
|
+
// PARAMETER — never interpolated — with the regex validation above as a
|
|
314
|
+
// second, independent layer.
|
|
315
|
+
const numericProperty = (key: string) =>
|
|
316
|
+
sql`CASE WHEN jsonb_typeof(${contacts.properties} -> ${key}) = 'number' THEN (${contacts.properties} ->> ${key})::numeric END`;
|
|
317
|
+
|
|
318
|
+
// Filter applies only when both halves are present (the schema 400s a
|
|
319
|
+
// dangling propertyGte). A NULL from the guard fails the ≥ comparison, so
|
|
320
|
+
// non-numeric holders are excluded rather than erroring.
|
|
321
|
+
const propertyFilter =
|
|
322
|
+
propertyKey !== undefined && propertyGte !== undefined
|
|
323
|
+
? sql`${numericProperty(propertyKey)} >= ${propertyGte}`
|
|
324
|
+
: undefined;
|
|
325
|
+
|
|
326
|
+
// NULLS LAST in BOTH directions so unscored (or non-numeric) contacts
|
|
327
|
+
// never top the list; last_seen_at breaks ties deterministically. The
|
|
328
|
+
// default path (`orderBy=lastSeenAt`, `orderDir=desc`) is byte-identical
|
|
329
|
+
// to the pre-PRD-06 hardcoded ORDER BY — existing callers see no change.
|
|
330
|
+
// NOTE: the GIN index on `properties` accelerates containment filters
|
|
331
|
+
// only; this ORDER BY is a sequential scan — fine at GTM volume
|
|
332
|
+
// (thousands of contacts), not at analytics volume.
|
|
333
|
+
const orderClauses =
|
|
334
|
+
orderBy === "property" && orderProperty !== undefined
|
|
335
|
+
? [
|
|
336
|
+
orderDir === "asc"
|
|
337
|
+
? sql`${numericProperty(orderProperty)} asc nulls last`
|
|
338
|
+
: sql`${numericProperty(orderProperty)} desc nulls last`,
|
|
339
|
+
desc(contacts.lastSeenAt),
|
|
340
|
+
]
|
|
341
|
+
: orderBy === "firstSeenAt"
|
|
342
|
+
? [
|
|
343
|
+
orderDir === "asc"
|
|
344
|
+
? asc(contacts.firstSeenAt)
|
|
345
|
+
: desc(contacts.firstSeenAt),
|
|
346
|
+
]
|
|
347
|
+
: [
|
|
348
|
+
orderDir === "asc"
|
|
349
|
+
? asc(contacts.lastSeenAt)
|
|
350
|
+
: desc(contacts.lastSeenAt),
|
|
351
|
+
];
|
|
352
|
+
|
|
254
353
|
// Valued events are keyed by the contact's canonical event key
|
|
255
354
|
// (external_id ?? anonymous_id ?? id) — same precedence ingestEvent
|
|
256
355
|
// resolves. Served by the partial user_events_valued_user_idx.
|
|
@@ -284,6 +383,7 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
|
|
|
284
383
|
...(searchFilter ? [searchFilter] : []),
|
|
285
384
|
...(revenueFilter ? [revenueFilter] : []),
|
|
286
385
|
...(dealStageFilter ? [dealStageFilter] : []),
|
|
386
|
+
...(propertyFilter ? [propertyFilter] : []),
|
|
287
387
|
);
|
|
288
388
|
|
|
289
389
|
const [rows, totalRows] = await Promise.all([
|
|
@@ -291,7 +391,7 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
|
|
|
291
391
|
.select()
|
|
292
392
|
.from(contacts)
|
|
293
393
|
.where(where)
|
|
294
|
-
.orderBy(
|
|
394
|
+
.orderBy(...orderClauses)
|
|
295
395
|
.limit(limit)
|
|
296
396
|
.offset(offset),
|
|
297
397
|
db.select({ count: count() }).from(contacts).where(where),
|
|
@@ -17,6 +17,7 @@ import {
|
|
|
17
17
|
assertHttpUrl,
|
|
18
18
|
canonicalTrackedRowFilter,
|
|
19
19
|
ensureQrTrackedLink,
|
|
20
|
+
IdempotencyConflictError,
|
|
20
21
|
isSlugUniqueViolation,
|
|
21
22
|
mintLink,
|
|
22
23
|
normalizeSlug,
|
|
@@ -118,6 +119,12 @@ const destinationStatSchema = z.object({
|
|
|
118
119
|
lastAt: z.string(),
|
|
119
120
|
});
|
|
120
121
|
|
|
122
|
+
// POST-only extension of the shared flat shape: `existing` reports whether the
|
|
123
|
+
// mint recovered an already-live link (idempotent re-mint) instead of
|
|
124
|
+
// inserting. Deliberately NOT on linkSchema — GET/list/PATCH/DELETE have no
|
|
125
|
+
// mint semantics.
|
|
126
|
+
const createdLinkSchema = linkSchema.extend({ existing: z.boolean() });
|
|
127
|
+
|
|
121
128
|
const linkDetailSchema = linkSchema.extend({
|
|
122
129
|
clicks: z.array(clickSchema),
|
|
123
130
|
destinations: z.array(destinationStatSchema),
|
|
@@ -183,29 +190,47 @@ const createLinkRoute = createRoute({
|
|
|
183
190
|
body: {
|
|
184
191
|
content: {
|
|
185
192
|
"application/json": {
|
|
186
|
-
schema: z
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
193
|
+
schema: z
|
|
194
|
+
.object({
|
|
195
|
+
url: z.string().url(),
|
|
196
|
+
type: z.enum(["personal", "public"]).default("public"),
|
|
197
|
+
// Optional vanity slug (`/l/:slug`). Normalized lowercase; 409 if
|
|
198
|
+
// already taken by a different destination (same destination +
|
|
199
|
+
// type recovers the existing link — see idempotencyKey).
|
|
200
|
+
slug: z.string().optional(),
|
|
201
|
+
label: z.string().optional(),
|
|
202
|
+
description: z.string().optional(),
|
|
203
|
+
appendRef: z.boolean().optional(),
|
|
204
|
+
campaign: z.string().optional(),
|
|
205
|
+
// Honoured ONLY for personal links (the share-safe invariant in
|
|
206
|
+
// mintLink drops it for public). A canonical contact key the click
|
|
207
|
+
// should stitch the visitor's anon session into.
|
|
208
|
+
distinctId: z.string().optional(),
|
|
209
|
+
// Honest originating channel: Studio UI mints say "studio", SDK/
|
|
210
|
+
// programmatic mints say "api".
|
|
211
|
+
source: z.enum(["studio", "api"]).default("studio"),
|
|
212
|
+
// Idempotent-mint key for slugless links: same key + same url
|
|
213
|
+
// returns the existing link (existing: true); same key +
|
|
214
|
+
// different url is a 409. Mutually exclusive with slug (a slug
|
|
215
|
+
// IS an idempotency key).
|
|
216
|
+
idempotencyKey: z
|
|
217
|
+
.string()
|
|
218
|
+
.min(1)
|
|
219
|
+
.max(255)
|
|
220
|
+
.regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*$/)
|
|
221
|
+
.optional(),
|
|
222
|
+
})
|
|
223
|
+
.refine((d) => !(d.slug && d.idempotencyKey), {
|
|
224
|
+
message: "slug and idempotencyKey are mutually exclusive",
|
|
225
|
+
}),
|
|
201
226
|
},
|
|
202
227
|
},
|
|
203
228
|
},
|
|
204
229
|
},
|
|
205
230
|
responses: {
|
|
206
231
|
200: {
|
|
207
|
-
content: { "application/json": { schema:
|
|
208
|
-
description: "Minted link",
|
|
232
|
+
content: { "application/json": { schema: createdLinkSchema } },
|
|
233
|
+
description: "Minted link (existing: true = idempotent re-mint)",
|
|
209
234
|
},
|
|
210
235
|
400: {
|
|
211
236
|
content: { "application/json": { schema: errorSchema } },
|
|
@@ -213,7 +238,7 @@ const createLinkRoute = createRoute({
|
|
|
213
238
|
},
|
|
214
239
|
409: {
|
|
215
240
|
content: { "application/json": { schema: errorSchema } },
|
|
216
|
-
description: "Slug already taken",
|
|
241
|
+
description: "Slug or idempotency key already taken",
|
|
217
242
|
},
|
|
218
243
|
},
|
|
219
244
|
});
|
|
@@ -415,7 +440,7 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
415
440
|
db,
|
|
416
441
|
url: body.url,
|
|
417
442
|
baseUrl: env.API_PUBLIC_URL,
|
|
418
|
-
source:
|
|
443
|
+
source: body.source,
|
|
419
444
|
type: body.type,
|
|
420
445
|
slug: body.slug,
|
|
421
446
|
label: body.label,
|
|
@@ -424,6 +449,7 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
424
449
|
campaign: body.campaign,
|
|
425
450
|
distinctId: body.distinctId,
|
|
426
451
|
createdBy: resolveActor(c) ?? undefined,
|
|
452
|
+
idempotencyKey: body.idempotencyKey,
|
|
427
453
|
});
|
|
428
454
|
|
|
429
455
|
const [row] = await db
|
|
@@ -436,16 +462,22 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
|
|
|
436
462
|
return c.json({ error: "Mint succeeded but link not found" }, 400);
|
|
437
463
|
}
|
|
438
464
|
|
|
465
|
+
// One aggregate path for BOTH fresh and recovered mints: a fresh mint
|
|
466
|
+
// aggregates to clicks:0/scans:0 with the canonical trackedLinkId; a
|
|
467
|
+
// recovered link reports its real counts.
|
|
468
|
+
const agg = await aggregateFor(db, [minted.linkId]);
|
|
439
469
|
return c.json(
|
|
440
|
-
|
|
441
|
-
row,
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
),
|
|
470
|
+
{
|
|
471
|
+
...serializeLink(row, agg.get(minted.linkId), env.API_PUBLIC_URL),
|
|
472
|
+
existing: minted.existing,
|
|
473
|
+
},
|
|
445
474
|
200,
|
|
446
475
|
);
|
|
447
476
|
} catch (err) {
|
|
448
|
-
if (
|
|
477
|
+
if (
|
|
478
|
+
err instanceof SlugTakenError ||
|
|
479
|
+
err instanceof IdempotencyConflictError
|
|
480
|
+
) {
|
|
449
481
|
return c.json({ error: err.message }, 409);
|
|
450
482
|
}
|
|
451
483
|
const message = err instanceof Error ? err.message : "Mint failed";
|