@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.
@@ -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.object({
75
- limit: z.coerce.number().min(1).max(100).default(50),
76
- offset: z.coerce.number().min(0).default(0),
77
- search: z.string().optional(),
78
- // Long-tail value filters (plan §4b.3): the "find my value customers"
79
- // query surface.
80
- minRevenue: z.coerce.number().optional(),
81
- // Plain string: valid stages are the deployment's configured ladder.
82
- dealStage: z.string().optional(),
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 { limit, offset, search, minRevenue, dealStage } =
250
- c.req.valid("query");
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(desc(contacts.lastSeenAt))
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.object({
187
- url: z.string().url(),
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(),
192
- label: z.string().optional(),
193
- description: z.string().optional(),
194
- appendRef: z.boolean().optional(),
195
- campaign: z.string().optional(),
196
- // Honoured ONLY for personal links (the share-safe invariant in
197
- // mintLink drops it for public). A canonical contact key the click
198
- // should stitch the visitor's anon session into.
199
- distinctId: z.string().optional(),
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: linkSchema } },
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: "studio",
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
- serializeLink(
441
- row,
442
- { clicks: 0, scans: 0, trackedLinkId: minted.trackedLinkId },
443
- env.API_PUBLIC_URL,
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 (err instanceof SlugTakenError) {
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";