@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.
- package/package.json +11 -11
- package/src/buckets/bucket-access.ts +5 -10
- package/src/buckets/check-membership.ts +91 -6
- package/src/index.ts +31 -1
- package/src/journeys/execute-journey-run.ts +56 -1
- package/src/journeys/journey-context.ts +59 -0
- package/src/lib/bucket-emit.test.ts +83 -2
- package/src/lib/bucket-emit.ts +16 -0
- package/src/lib/contacts.ts +1031 -141
- package/src/lib/crm-ingest.ts +9 -0
- package/src/lib/enrichment-ledger.ts +1 -1
- package/src/lib/feed.ts +64 -3
- package/src/lib/identity-service.ts +15 -2
- package/src/lib/ingestion.ts +191 -14
- package/src/lib/outbound.ts +3 -3
- package/src/lib/refine-chain.test.ts +83 -25
- package/src/lib/refine-chain.ts +124 -23
- package/src/lib/refine-traits.test.ts +74 -41
- package/src/lib/refine-traits.ts +107 -52
- package/src/lib/refine.ts +28 -27
- package/src/lib/tracking-events.ts +33 -6
- package/src/routes/admin/agent.ts +26 -0
- package/src/routes/admin/contacts.ts +65 -5
- package/src/routes/admin/identity.ts +197 -0
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/contacts/index.ts +50 -7
- package/src/routes/events/index.ts +94 -6
- package/src/routes/feed/index.ts +36 -0
- package/src/routes/feed/recipient.ts +44 -2
- package/src/routes/lists/index.ts +21 -0
- package/src/routes/tracking/arrive.ts +42 -3
- package/src/worker.ts +18 -0
- package/src/workflows/bucket-backfill.ts +1 -1
- package/src/workflows/bucket-reconcile.ts +129 -4
- package/src/workflows/identity-alias-backfill.ts +448 -0
- package/src/workflows/import-contacts.ts +10 -0
- package/src/workflows/send-campaign.ts +31 -13
package/src/lib/refine-traits.ts
CHANGED
|
@@ -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
|
|
5
|
-
* successful refinement stamps alongside the vendor's own
|
|
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 (`
|
|
8
|
+
/** The enrichment provider id that answered (`enrichment.provider`). */
|
|
9
9
|
provider: string;
|
|
10
|
-
/** The lookup instant, written as an ISO string (`
|
|
10
|
+
/** The lookup instant, written as an ISO string (`enrichment.at`). */
|
|
11
11
|
refinedAt: Date;
|
|
12
12
|
}
|
|
13
13
|
|
|
14
14
|
/**
|
|
15
|
-
*
|
|
16
|
-
*
|
|
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
|
-
*
|
|
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
|
-
* - **
|
|
22
|
-
* `
|
|
23
|
-
*
|
|
24
|
-
*
|
|
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, "
|
|
42
|
-
putString(patch, "
|
|
43
|
-
putString(patch, "
|
|
44
|
-
putString(patch, "
|
|
45
|
-
putString(patch, "
|
|
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, "
|
|
48
|
-
putString(patch, "
|
|
49
|
-
putString(patch, "
|
|
50
|
-
putNumber(patch, "
|
|
51
|
-
putNumber(patch, "
|
|
52
|
-
putString(patch, "
|
|
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
|
-
|
|
55
|
-
|
|
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
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
|
81
|
-
|
|
110
|
+
export function canonicalizeStoredTraits(
|
|
111
|
+
traits: Record<string, unknown>,
|
|
82
112
|
): Record<string, unknown> {
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
for (const [key, value] of Object.entries(
|
|
86
|
-
if (key
|
|
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
|
|
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("
|
|
112
|
-
*
|
|
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
|
|
44
|
-
*
|
|
45
|
-
*
|
|
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.
|
|
50
|
+
* → contacts.properties.{company_employees, seniority, …} (via ingestEvent)
|
|
51
51
|
* → checkBucketMembership re-runs
|
|
52
|
-
* → bucket("gtm-qualified", b => b.prop("
|
|
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
|
-
*
|
|
149
|
-
* decide
|
|
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:
|
|
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
|
|
179
|
-
// miss the row it just wrote, and charge the
|
|
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
|
-
// `
|
|
182
|
-
//
|
|
183
|
-
//
|
|
184
|
-
// `
|
|
185
|
-
//
|
|
186
|
-
//
|
|
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
|
-
|
|
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):
|
|
239
|
-
*
|
|
240
|
-
*
|
|
241
|
-
*
|
|
242
|
-
*
|
|
243
|
-
*
|
|
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
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
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
|
});
|