@hogsend/engine 0.55.0 → 0.57.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.
Files changed (37) hide show
  1. package/package.json +11 -11
  2. package/src/buckets/bucket-access.ts +5 -10
  3. package/src/buckets/check-membership.ts +91 -6
  4. package/src/index.ts +31 -1
  5. package/src/journeys/execute-journey-run.ts +56 -1
  6. package/src/journeys/journey-context.ts +59 -0
  7. package/src/lib/bucket-emit.test.ts +83 -2
  8. package/src/lib/bucket-emit.ts +16 -0
  9. package/src/lib/contacts.ts +1031 -141
  10. package/src/lib/crm-ingest.ts +9 -0
  11. package/src/lib/enrichment-ledger.ts +1 -1
  12. package/src/lib/feed.ts +64 -3
  13. package/src/lib/identity-service.ts +15 -2
  14. package/src/lib/ingestion.ts +191 -14
  15. package/src/lib/outbound.ts +3 -3
  16. package/src/lib/refine-chain.test.ts +83 -25
  17. package/src/lib/refine-chain.ts +124 -23
  18. package/src/lib/refine-traits.test.ts +74 -41
  19. package/src/lib/refine-traits.ts +107 -52
  20. package/src/lib/refine.ts +28 -27
  21. package/src/lib/tracking-events.ts +33 -6
  22. package/src/routes/admin/agent.ts +26 -0
  23. package/src/routes/admin/contacts.ts +65 -5
  24. package/src/routes/admin/identity.ts +197 -0
  25. package/src/routes/admin/index.ts +2 -0
  26. package/src/routes/contacts/index.ts +50 -7
  27. package/src/routes/events/index.ts +94 -6
  28. package/src/routes/feed/index.ts +36 -0
  29. package/src/routes/feed/recipient.ts +44 -2
  30. package/src/routes/lists/index.ts +21 -0
  31. package/src/routes/tracking/arrive.ts +42 -3
  32. package/src/worker.ts +18 -0
  33. package/src/workflows/bucket-backfill.ts +1 -1
  34. package/src/workflows/bucket-reconcile.ts +129 -4
  35. package/src/workflows/identity-alias-backfill.ts +448 -0
  36. package/src/workflows/import-contacts.ts +10 -0
  37. package/src/workflows/send-campaign.ts +31 -13
@@ -1,27 +1,54 @@
1
1
  import type { EnrichmentResult } from "@hogsend/core";
2
2
 
3
3
  /**
4
- * Identity of the lookup that produced a patch — the two synthetic traits every
5
- * successful refinement stamps alongside the vendor's own fields.
4
+ * Identity of the lookup that produced a patch — the provenance every
5
+ * successful refinement stamps alongside the vendor's own facts.
6
6
  */
7
7
  export interface RefinedTraitsMeta {
8
- /** The enrichment provider id that answered (`refined_provider`). */
8
+ /** The enrichment provider id that answered (`enrichment.provider`). */
9
9
  provider: string;
10
- /** The lookup instant, written as an ISO string (`refined_at`). */
10
+ /** The lookup instant, written as an ISO string (`enrichment.at`). */
11
11
  refinedAt: Date;
12
12
  }
13
13
 
14
14
  /**
15
- * Map a normalized {@link EnrichmentResult} onto the FLAT, top-level,
16
- * `refined_`-prefixed contact-property patch that `ingestEvent` merges into
17
- * `contacts.properties`.
15
+ * The single nested key that carries refinement PROVENANCE — who answered and
16
+ * when. Split out from the vendor FACTS on purpose:
18
17
  *
19
- * Two rules make this function load-bearing rather than cosmetic:
18
+ * - Facts land on the CANONICAL, flat property keys a contact already carries
19
+ * (`title`, `company`, `company_employees`, …) so a bucket segments on the
20
+ * field it already knows — `b.prop("company_employees").gte(100)` — instead
21
+ * of a parallel `refined_*` vocabulary sitting next to the real one.
22
+ * - Provenance is NEVER read by `evaluatePropertyConditions` (segmentation is
23
+ * about facts, not who told us), so it nests freely under one key with no
24
+ * dotted-path support required from the condition engine. That is the whole
25
+ * reason the facts must stay flat and the provenance is free to be an object.
26
+ */
27
+ export const ENRICHMENT_KEY = "enrichment";
28
+
29
+ /** The provenance object stored under {@link ENRICHMENT_KEY}. */
30
+ export interface EnrichmentProvenance {
31
+ /** The enrichment provider id that answered. */
32
+ provider: string;
33
+ /** ISO — the instant the vendor answer was obtained. */
34
+ at: string;
35
+ }
36
+
37
+ /**
38
+ * Map a normalized {@link EnrichmentResult} onto a CANONICAL contact-property
39
+ * patch that `ingestEvent` merges into `contacts.properties`. The vendor facts
40
+ * fill the fields a contact already segments and personalizes on; a single
41
+ * nested `enrichment` object records the provenance.
42
+ *
43
+ * Three rules make this function load-bearing rather than cosmetic:
20
44
  *
21
- * - **Flat keys only.** `evaluatePropertyConditions` reads
22
- * `journeyContext[condition.property]`, so a bucket authors
23
- * `b.prop("refined_seniority")`. A dotted path would never resolve, which is
24
- * why nothing here nests.
45
+ * - **Facts are flat + canonical.** `evaluatePropertyConditions` reads
46
+ * `properties[condition.property]` — a flat lookup with no dotted-path
47
+ * traversal — so every fact key is a top-level string a bucket can author
48
+ * verbatim (`company_industry`, not `company.industry`).
49
+ * - **Provenance is one nested object.** The condition engine never reads it,
50
+ * so `enrichment: { provider, at }` replaces the old flat `refined_at` /
51
+ * `refined_provider` sibling keys without touching the evaluator.
25
52
  * - **Absent means ABSENT.** An undefined vendor field is omitted from the
26
53
  * patch entirely — never written as `null`. `mergePropertiesSql` wraps the
27
54
  * patch in `jsonb_strip_nulls`, so a null would DELETE a previously-good key
@@ -29,6 +56,13 @@ export interface RefinedTraitsMeta {
29
56
  *
30
57
  * Numeric traits are written as real JSON numbers: `conditions/property.ts` does
31
58
  * no coercion, so a `"42"` would silently never match a `gte`.
59
+ *
60
+ * The patch is the vendor's FULL answer, keyed canonically. Whether an
61
+ * individual fact actually overwrites what a contact already holds is decided at
62
+ * LANDING time (fill-if-absent, in `refine-chain.ts`), because that answer
63
+ * depends on the specific contact — the same stored patch lands on every contact
64
+ * that shares a company domain, and each may already carry different first-party
65
+ * fields.
32
66
  */
33
67
  export function flattenTraits(
34
68
  result: EnrichmentResult,
@@ -38,56 +72,77 @@ export function flattenTraits(
38
72
  const person = result.person;
39
73
  const company = result.company;
40
74
 
41
- putString(patch, "refined_title", person?.title);
42
- putString(patch, "refined_seniority", person?.seniority);
43
- putString(patch, "refined_department", person?.department);
44
- putString(patch, "refined_linkedin_url", person?.linkedinUrl);
45
- putString(patch, "refined_country", person?.country);
75
+ putString(patch, "title", person?.title);
76
+ putString(patch, "seniority", person?.seniority);
77
+ putString(patch, "department", person?.department);
78
+ putString(patch, "linkedin_url", person?.linkedinUrl);
79
+ putString(patch, "country", person?.country);
46
80
 
47
- putString(patch, "refined_company_name", company?.name);
48
- putString(patch, "refined_company_domain", company?.domain);
49
- putString(patch, "refined_company_industry", company?.industry);
50
- putNumber(patch, "refined_company_employees", company?.employeeCount);
51
- putNumber(patch, "refined_company_revenue", company?.estimatedRevenue);
52
- putString(patch, "refined_company_country", company?.country);
81
+ putString(patch, "company", company?.name);
82
+ putString(patch, "company_domain", company?.domain);
83
+ putString(patch, "company_industry", company?.industry);
84
+ putNumber(patch, "company_employees", company?.employeeCount);
85
+ putNumber(patch, "company_revenue", company?.estimatedRevenue);
86
+ putString(patch, "company_country", company?.country);
53
87
 
54
- patch.refined_at = meta.refinedAt.toISOString();
55
- patch.refined_provider = meta.provider;
88
+ const provenance: EnrichmentProvenance = {
89
+ provider: meta.provider,
90
+ at: meta.refinedAt.toISOString(),
91
+ };
92
+ patch[ENRICHMENT_KEY] = provenance;
56
93
 
57
94
  return patch;
58
95
  }
59
96
 
60
- /** The prefix every trait this module writes carries. */
61
- export const REFINED_TRAIT_PREFIX = "refined_";
62
-
63
97
  /**
64
- * The two keys {@link flattenTraits} stamps that are PROVENANCE, not vendor
65
- * facts. Named once here so a consumer of the patch (the `contact.refined`
66
- * outbound payload) can tell "what the vendor told us" apart from "when, and
67
- * who told us" without re-listing them and drifting.
68
- */
69
- export const REFINED_META_KEYS: readonly string[] = [
70
- "refined_at",
71
- "refined_provider",
72
- ];
73
-
74
- /**
75
- * The `refined_*` subset of an already-stored `contacts.properties` bag — what
76
- * a cache hit compares the ledger row's stored patch against, to tell "this
77
- * contact already has the paid answer" apart from "another contact at the same
78
- * domain paid for it and this one has never seen it".
98
+ * Translate a ledger `traits` patch written by the PRE-canonical release (flat
99
+ * `refined_*` fact keys plus flat `refined_at` / `refined_provider` provenance)
100
+ * into the canonical shape {@link flattenTraits} now produces. A cache HIT can
101
+ * land a row written by an older engine, and landing it verbatim would
102
+ * re-introduce exactly the flat vocabulary this design removed.
103
+ *
104
+ * A patch with no `refined_*` key is already canonical and passes through
105
+ * untouched (the common case, once the ledger has turned over). The two legacy
106
+ * provenance keys are dropped: they are not facts, and the fresh ISO provenance
107
+ * is not recoverable from them here, so a legacy cache hit simply lands the
108
+ * facts without a new `enrichment` stamp.
79
109
  */
80
- export function pickRefinedTraits(
81
- properties: Record<string, unknown> | null | undefined,
110
+ export function canonicalizeStoredTraits(
111
+ traits: Record<string, unknown>,
82
112
  ): Record<string, unknown> {
83
- const picked: Record<string, unknown> = {};
84
- if (!properties) return picked;
85
- for (const [key, value] of Object.entries(properties)) {
86
- if (key.startsWith(REFINED_TRAIT_PREFIX)) picked[key] = value;
113
+ let sawLegacy = false;
114
+ const out: Record<string, unknown> = {};
115
+ for (const [key, value] of Object.entries(traits)) {
116
+ if (key === "refined_at" || key === "refined_provider") {
117
+ sawLegacy = true;
118
+ continue;
119
+ }
120
+ const canonical = LEGACY_TRAIT_KEYS[key];
121
+ if (canonical) {
122
+ sawLegacy = true;
123
+ out[canonical] = value;
124
+ } else {
125
+ out[key] = value;
126
+ }
87
127
  }
88
- return picked;
128
+ return sawLegacy ? out : traits;
89
129
  }
90
130
 
131
+ /** Pre-canonical `refined_*` fact key → its canonical replacement. */
132
+ const LEGACY_TRAIT_KEYS: Record<string, string> = {
133
+ refined_title: "title",
134
+ refined_seniority: "seniority",
135
+ refined_department: "department",
136
+ refined_linkedin_url: "linkedin_url",
137
+ refined_country: "country",
138
+ refined_company_name: "company",
139
+ refined_company_domain: "company_domain",
140
+ refined_company_industry: "company_industry",
141
+ refined_company_employees: "company_employees",
142
+ refined_company_revenue: "company_revenue",
143
+ refined_company_country: "company_country",
144
+ };
145
+
91
146
  /**
92
147
  * Write a string trait, omitting anything that carries no information. An empty
93
148
  * (or whitespace-only) string is dropped for the same reason a null is: it is
@@ -108,8 +163,8 @@ function putString(
108
163
  * Write a numeric trait as a real JSON number. A provider is contractually
109
164
  * obliged to normalize to `number`, but a JS (untyped) provider can still hand
110
165
  * back a numeric string — coercing here is the difference between a working
111
- * `b.prop("refined_company_employees").gte(100)` and one that silently never
112
- * matches. Non-finite / non-numeric values are omitted entirely.
166
+ * `b.prop("company_employees").gte(100)` and one that silently never matches.
167
+ * Non-finite / non-numeric values are omitted entirely.
113
168
  */
114
169
  function putNumber(
115
170
  patch: Record<string, unknown>,
package/src/lib/refine.ts CHANGED
@@ -25,7 +25,6 @@ import {
25
25
  type RefineTarget,
26
26
  runRefineChain,
27
27
  } from "./refine-chain.js";
28
- import { pickRefinedTraits } from "./refine-traits.js";
29
28
 
30
29
  export type {
31
30
  RefineContactOptions,
@@ -40,16 +39,17 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
40
39
 
41
40
  /**
42
41
  * Refinement — the one new public function of this release. Resolves a contact,
43
- * spends AT MOST one provider lookup, and lands the vendor's answer as flat
44
- * `refined_*` contact properties THROUGH `ingestEvent`, so bucket membership
45
- * re-evaluates synchronously and the GTM loop closes:
42
+ * spends AT MOST one provider lookup, and lands the vendor's answer on the
43
+ * CANONICAL contact-property fields (fill-if-absent, so first-party data is
44
+ * never overwritten) THROUGH `ingestEvent`, so bucket membership re-evaluates
45
+ * synchronously and the GTM loop closes:
46
46
  *
47
47
  * ```
48
48
  * behaviour → bucket("gtm-high-intent").on("enter")
49
49
  * → refineContact()
50
- * → contacts.properties.refined_* (via ingestEvent)
50
+ * → contacts.properties.{company_employees, seniority, …} (via ingestEvent)
51
51
  * → checkBucketMembership re-runs
52
- * → bucket("gtm-qualified", b => b.prop("refined_company_employees").gte(100))
52
+ * → bucket("gtm-qualified", b => b.prop("company_employees").gte(100))
53
53
  * ```
54
54
  *
55
55
  * A STANDALONE import, never a `ctx` method — the journey context stays
@@ -129,6 +129,9 @@ export async function refineContact(
129
129
  ...(input.contactId ? { contactId: input.contactId } : {}),
130
130
  eventProperties: input.eventProperties,
131
131
  contactProperties: input.contactProperties,
132
+ ...(input.touchProperties
133
+ ? { touchProperties: input.touchProperties }
134
+ : {}),
132
135
  source: "enrichment",
133
136
  ...(input.idempotencyKey
134
137
  ? { idempotencyKey: input.idempotencyKey }
@@ -145,8 +148,8 @@ export async function refineContact(
145
148
  * Resolve the refinement subject and everything the lookup needs from it: the
146
149
  * canonical key the ingest writes back under, the lookup key (email first, then
147
150
  * the contact's company domain), the vendor query's name/company hints, and the
148
- * `refined_*` traits already on the row (what a cache hit compares against to
149
- * decide whether this contact still needs the stored answer landed).
151
+ * row's existing properties (which fill-if-absent reads at landing time to
152
+ * decide which vendor facts to keep).
150
153
  *
151
154
  * An email with no contact row is still refinable — the ingest at the end of the
152
155
  * chain creates the contact — so a brand-new address is not a `no_lookup_key`.
@@ -171,24 +174,28 @@ async function resolveRefineTarget(
171
174
 
172
175
  const properties = row.properties ?? {};
173
176
  const resolvedEmail = row.email ?? email;
174
- // REPLAY SAFETY: every key here must be one this function does NOT write.
175
- // The domain becomes the `lookupKey`, which is the `enrichment_lookups`
177
+ // REPLAY SAFETY: the domain this picks must be STABLE across a run and its
178
+ // replay. The domain becomes the `lookupKey`, which is the `enrichment_lookups`
176
179
  // arbiter — Layer 2, the version-independent exactly-once backstop. (Layer 1,
177
180
  // the memo key, is derived from the caller's arguments alone and is immune.)
178
- // A self-referential source would make a replay derive a DIFFERENT ledger key,
179
- // miss the row it just wrote, and charge the vendor a second time.
181
+ // A source that refinement itself changes between the run and the replay would
182
+ // derive a DIFFERENT ledger key, miss the row it just wrote, and charge the
183
+ // vendor a second time.
180
184
  //
181
- // `refined_company_domain` is deliberately EXCLUDED: `flattenTraits` writes it
182
- // (refine-traits.ts) from the vendor's canonical domain, which need not equal
183
- // the one we looked up by. A contact carrying only `domain` would resolve via
184
- // `domain` on the original run, then — once `refined_company_domain` exists and
185
- // outranks it — resolve differently on replay, deriving a different memo key.
186
- // The three keys below are externally supplied and therefore replay-stable.
185
+ // `company_domain` is the key `flattenTraits` WRITES (the vendor's canonical
186
+ // domain, which need not equal the one we looked up by), so it is listed LAST.
187
+ // That ordering — externally-supplied `companyDomain`/`domain` before the
188
+ // refinement-written `company_domain` — is what keeps the pick stable: the only
189
+ // way refinement can FILL `company_domain` is fill-if-absent (it was absent),
190
+ // and whenever it is the pick it was already present (so fill-if-absent leaves
191
+ // it untouched). A domain-only contact looked up by `domain` keeps resolving
192
+ // via `domain` even after the vendor fills `company_domain`, because `domain`
193
+ // outranks it.
187
194
  const domain = readString(
188
195
  properties,
189
- "company_domain",
190
196
  "companyDomain",
191
197
  "domain",
198
+ "company_domain",
192
199
  );
193
200
 
194
201
  return {
@@ -202,15 +209,9 @@ async function resolveRefineTarget(
202
209
  ...spread("lastName", readString(properties, "lastName", "last_name")),
203
210
  ...spread(
204
211
  "company",
205
- readString(
206
- properties,
207
- "company",
208
- "company_name",
209
- "companyName",
210
- "refined_company_name",
211
- ),
212
+ readString(properties, "company", "company_name", "companyName"),
212
213
  ),
213
- refinedProperties: pickRefinedTraits(properties),
214
+ existingProperties: properties,
214
215
  };
215
216
  }
216
217
 
@@ -235,12 +235,37 @@ export interface PushLinkClickEventOpts {
235
235
  * as the first-party `link.clicked` event so journeys can trigger / await a
236
236
  * click of a SPECIFIC managed link (filtered by `linkId`/`campaign`).
237
237
  *
238
- * IDENTITY GATE (crash-guard): `ingestEvent`→`resolveOrCreateContact` THROWS on
239
- * a zero-key event, so a broadcast/public link (`distinctId == null`) returns
240
- * `undefined` WITHOUT calling ingest. The click route ALSO suppresses
241
- * bot/prefetch hits upstream (`isBotOrPrefetch`), so an unfurl bot never reaches
242
- * here. All six payload keys are scalars (or null) so they survive ingest and
243
- * reach `trigger.where` + `waitForEvent.properties`.
238
+ * IDENTITY GATE (crash-guard): the resolve THROWS on a zero-key event, so a
239
+ * broadcast/public link (`distinctId == null`) returns `undefined` WITHOUT
240
+ * calling ingest. The click route ALSO suppresses bot/prefetch hits upstream
241
+ * (`isBotOrPrefetch`), so an unfurl bot never reaches here. All six payload
242
+ * keys are scalars (or null) so they survive ingest and reach `trigger.where` +
243
+ * `waitForEvent.properties`.
244
+ *
245
+ * NEVER MINTS (D11). This is a re-ingest DERIVED from an earlier observation,
246
+ * so it inherits that observation's refusal — `allowCreate: false`. `mintLink`
247
+ * copies whatever `distinctId` the caller passes for a `personal` link, so a
248
+ * link minted for a visitor who was never identified carries an ANON key; with
249
+ * creation allowed the create arm wrote `external_id = <anonId>`, the shape
250
+ * #621 calls strictly WORSE than the ghost it replaces (it then answers
251
+ * `collidesWithIdentified` (contacts.ts) and 403-locks the visitor out of their
252
+ * own feed). Safe by construction: a link carrying a `distinctId` was minted for
253
+ * someone already known, so either the key resolves — fill-in-link, unchanged —
254
+ * or it was refused at observation time and must STAY refused.
255
+ *
256
+ * Unlike `sendFeedItem`'s `userId` arm (lib/feed.ts), the mint here has no
257
+ * confidentiality role. There it is load-bearing: the minted row is the only
258
+ * signal `collidesWithIdentified` has, and refusing would convert a private
259
+ * feed row into an anon-addressable one. This is an event ingest, not a
260
+ * feed-read authorization — `collidesWithIdentified` is consulted only by
261
+ * `routes/feed/recipient.ts` and `routes/tracking/arrive.ts`, neither of which
262
+ * reads anything this function writes.
263
+ *
264
+ * Nothing is lost by the refusal: `resolvedKey` is always a real string (D8),
265
+ * so `user_events` still stores under the same key and journeys still trigger.
266
+ * `tracked_links` has no `contact_id` column (only `distinctId`), so inheriting
267
+ * the refusal is the correct fix rather than threading a provenance pin — if a
268
+ * later change adds `contact_id` there, revisit.
244
269
  *
245
270
  * Distinct from the per-hit OUTBOUND `link.clicked` webhook: that fires for
246
271
  * EVERY hit and carries `trackedLinks.id` + the raw mint distinctId; THIS bus
@@ -257,6 +282,8 @@ export async function pushLinkClickEvent(
257
282
  registry,
258
283
  hatchet,
259
284
  logger,
285
+ // D11 — see the header. A derived re-ingest never re-resolves into a mint.
286
+ allowCreate: false,
260
287
  event: {
261
288
  event: LINK_CLICKED,
262
289
  userId: distinctId,
@@ -21,6 +21,7 @@ import { effectiveTier } from "../../lib/agent/risk.js";
21
21
  import { buildAgentSystemPrompt } from "../../lib/agent/system-prompt.js";
22
22
  import { buildAgentTools } from "../../lib/agent/tools.js";
23
23
  import {
24
+ ALL_IDENTITY_KINDS,
24
25
  resolveContact,
25
26
  resolveOrCreateContact,
26
27
  softDeleteContact,
@@ -297,6 +298,15 @@ agentRouter.post("/confirm", async (c) => {
297
298
  db,
298
299
  userId: args.userId as string | undefined,
299
300
  email: args.email as string | undefined,
301
+ // PRD 06 T4 (L5 row 16): the subscribe/unsubscribe tool takes an
302
+ // email/userId only (the 400 above rejects neither-key calls), so
303
+ // the narrow `trustedKinds` is the honest statement; create-on-miss,
304
+ // no clamp. Enforced by T5.
305
+ policy: {
306
+ create: "on-miss",
307
+ allowMerge: "any",
308
+ trustedKinds: ["external", "email"],
309
+ },
300
310
  });
301
311
  try {
302
312
  await applyListMembership({
@@ -327,6 +337,14 @@ agentRouter.post("/confirm", async (c) => {
327
337
  email: args.email as string | undefined,
328
338
  anonymousId: args.anonymousId as string | undefined,
329
339
  contactProperties: (args.properties ?? {}) as Record<string, unknown>,
340
+ // PRD 06 T4 (L5 row 17): an admin-agent upsert may assert any kind
341
+ // (the tool accepts userId/email/anonymousId) — full grant,
342
+ // create-on-miss, no clamp. Enforced by T5.
343
+ policy: {
344
+ create: "on-miss",
345
+ allowMerge: "any",
346
+ trustedKinds: ALL_IDENTITY_KINDS,
347
+ },
330
348
  });
331
349
  break;
332
350
 
@@ -339,6 +357,14 @@ agentRouter.post("/confirm", async (c) => {
339
357
  email: (args.email as string) ?? current.email ?? undefined,
340
358
  anonymousId: current.anonymousId ?? undefined,
341
359
  contactProperties: (args.properties ?? {}) as Record<string, unknown>,
360
+ // PRD 06 T4 (L5 row 18): the update tool re-supplies the row's OWN
361
+ // keys to ride the fill-in-link path (mirrors the admin update
362
+ // route) — full grant, create-on-miss, no clamp. Enforced by T5.
363
+ policy: {
364
+ create: "on-miss",
365
+ allowMerge: "any",
366
+ trustedKinds: ALL_IDENTITY_KINDS,
367
+ },
342
368
  });
343
369
  break;
344
370
  }
@@ -5,10 +5,13 @@ import {
5
5
  groups,
6
6
  } from "@hogsend/db";
7
7
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
8
- import { and, asc, count, desc, eq, isNull, sql } from "drizzle-orm";
8
+ import { and, asc, count, desc, eq, isNull, not, sql } from "drizzle-orm";
9
9
  import type { AppEnv } from "../../app.js";
10
10
  import {
11
+ ALL_IDENTITY_KINDS,
11
12
  contactSearchFilter,
13
+ deleteIdentityAliasesForContact,
14
+ identifiedContactFilter,
12
15
  resolveContact,
13
16
  resolveOrCreateContact,
14
17
  serializeContact as serializeContactRow,
@@ -78,12 +81,33 @@ const listRoute = createRoute({
78
81
  path: "/",
79
82
  tags: ["Admin"],
80
83
  summary: "List contacts",
84
+ description:
85
+ "Paginated contact list. `identity` narrows the list by whether the " +
86
+ "contact has EVER identified — i.e. holds an `externalId`, `email`, " +
87
+ "`discordId` or `phone` (`anonymousId` alone does not count). It " +
88
+ "defaults to `all`, so existing callers (`hogsend contacts list`, the " +
89
+ "Studio contact picker) are unaffected; only Studio's contacts screen " +
90
+ "opts in to `identified`. `identified` and `anonymous` are exact " +
91
+ "complements under the same other filters, and `total` reflects the " +
92
+ "filter.",
81
93
  request: {
82
94
  query: z
83
95
  .object({
84
96
  limit: z.coerce.number().min(1).max(100).default(50),
85
97
  offset: z.coerce.number().min(0).default(0),
86
98
  search: z.string().optional(),
99
+ /**
100
+ * Display filter (PRD 01) over "has this person ever identified?".
101
+ *
102
+ * The default is `all` ON PURPOSE and must stay that way: two
103
+ * consumers other than Studio's contacts list call this route and
104
+ * neither should silently change — the published `hogsend contacts
105
+ * list` CLI (output is scripted against) and Studio's contact
106
+ * picker (an anonymous contact is a legitimate pick when a journey
107
+ * or test is aimed at an anon key). Flipping this default is an
108
+ * API behaviour change, not a display tweak.
109
+ */
110
+ identity: z.enum(["all", "identified", "anonymous"]).default("all"),
87
111
  // Long-tail value filters (plan §4b.3): the "find my value customers"
88
112
  // query surface.
89
113
  minRevenue: z.coerce.number().optional(),
@@ -293,6 +317,7 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
293
317
  limit,
294
318
  offset,
295
319
  search,
320
+ identity,
296
321
  minRevenue,
297
322
  dealStage,
298
323
  orderBy,
@@ -378,8 +403,20 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
378
403
  )`
379
404
  : undefined;
380
405
 
406
+ // PRD 01 — one conjunct, one predicate (`identifiedContactFilter`), so
407
+ // `identified` and `anonymous` stay exact complements. It rides the SAME
408
+ // `where` as every other filter below, which is what keeps the page query
409
+ // and the `count()` in lockstep.
410
+ const identityFilter =
411
+ identity === "identified"
412
+ ? identifiedContactFilter()
413
+ : identity === "anonymous"
414
+ ? not(identifiedContactFilter())
415
+ : undefined;
416
+
381
417
  const where = and(
382
418
  isNull(contacts.deletedAt),
419
+ ...(identityFilter ? [identityFilter] : []),
383
420
  ...(searchFilter ? [searchFilter] : []),
384
421
  ...(revenueFilter ? [revenueFilter] : []),
385
422
  ...(dealStageFilter ? [dealStageFilter] : []),
@@ -488,6 +525,14 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
488
525
  userId: body.externalId,
489
526
  email: body.email,
490
527
  contactProperties: body.properties,
528
+ // PRD 06 T4 (L5 row 14): an admin create asserts identity — the body
529
+ // carries `externalId`/`email` ONLY, so the narrow `trustedKinds` is the
530
+ // honest statement; create-on-miss, no clamp. Enforced by T5.
531
+ policy: {
532
+ create: "on-miss",
533
+ allowMerge: "any",
534
+ trustedKinds: ["external", "email"],
535
+ },
491
536
  });
492
537
 
493
538
  const created = await resolveContact({ db, id });
@@ -540,6 +585,15 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
540
585
  email: body.email ?? current.email ?? undefined,
541
586
  anonymousId: current.anonymousId ?? undefined,
542
587
  contactProperties: body.properties,
588
+ // PRD 06 T4 (L5 row 15): an admin update re-supplies the row's OWN
589
+ // identity keys (externalId/anonymousId/email) to ride the
590
+ // fill-in-link path — an admin may assert any kind, so the full grant
591
+ // is the honest statement; create-on-miss, no clamp. Enforced by T5.
592
+ policy: {
593
+ create: "on-miss",
594
+ allowMerge: "any",
595
+ trustedKinds: ALL_IDENTITY_KINDS,
596
+ },
543
597
  });
544
598
  } else {
545
599
  // Degenerate contact with no identity keys (resolver requires >=1 key):
@@ -591,10 +645,16 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
591
645
  return c.json({ error: "Contact not found" }, 404);
592
646
  }
593
647
 
594
- await db
595
- .update(contacts)
596
- .set({ deletedAt: new Date(), updatedAt: new Date() })
597
- .where(eq(contacts.id, contact.id));
648
+ // Soft-delete + erasure hook in ONE transaction (PRD 02 T1): every
649
+ // contact_aliases row keyed to the erased contact is that person's own
650
+ // identity data, whatever `reason`/`from_contact_id` it carries.
651
+ await db.transaction(async (tx) => {
652
+ await tx
653
+ .update(contacts)
654
+ .set({ deletedAt: new Date(), updatedAt: new Date() })
655
+ .where(eq(contacts.id, contact.id));
656
+ await deleteIdentityAliasesForContact(tx, contact.id);
657
+ });
598
658
 
599
659
  return c.json({ deleted: true }, 200);
600
660
  });