@hogsend/engine 0.53.0 → 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),