@hogsend/engine 0.33.0 → 0.35.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 +9 -7
- package/src/container.ts +23 -1
- package/src/env.ts +24 -0
- package/src/index.ts +8 -0
- package/src/lib/agent/config.ts +19 -0
- package/src/lib/agent/proposals.ts +210 -0
- package/src/lib/agent/provider.ts +18 -0
- package/src/lib/agent/risk.ts +71 -0
- package/src/lib/agent/system-prompt.ts +30 -0
- package/src/lib/agent/tools.ts +465 -0
- package/src/lib/analytics-singleton.ts +18 -1
- package/src/lib/connector-actions.ts +19 -3
- package/src/lib/ingestion.ts +62 -2
- package/src/lib/tracking-events.ts +6 -3
- package/src/routes/admin/agent.ts +402 -0
- package/src/routes/admin/index.ts +2 -0
|
@@ -0,0 +1,465 @@
|
|
|
1
|
+
import { criteriaBuilder, days, evaluateCondition } from "@hogsend/core";
|
|
2
|
+
import {
|
|
3
|
+
contacts,
|
|
4
|
+
emailPreferences,
|
|
5
|
+
emailSends,
|
|
6
|
+
journeyStates,
|
|
7
|
+
userEvents,
|
|
8
|
+
} from "@hogsend/db";
|
|
9
|
+
import { tool } from "ai";
|
|
10
|
+
import { and, count, desc, eq, inArray, isNull } from "drizzle-orm";
|
|
11
|
+
import { z } from "zod";
|
|
12
|
+
import type { HogsendClient } from "../../container.js";
|
|
13
|
+
import {
|
|
14
|
+
contactKey,
|
|
15
|
+
contactSearchFilter,
|
|
16
|
+
resolveContact,
|
|
17
|
+
} from "../contacts.js";
|
|
18
|
+
import { mintProposal } from "./proposals.js";
|
|
19
|
+
import { effectiveTier } from "./risk.js";
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* The agent's tool set. READ tools auto-run (in-process against the container,
|
|
23
|
+
* the same query the corresponding admin route runs). WRITE tools are MINT-ONLY:
|
|
24
|
+
* their execute() builds a human summary, mints a single-use proposal token, and
|
|
25
|
+
* returns `{ status: "needs_confirmation", ... }` — they NEVER perform the side
|
|
26
|
+
* effect. The real write happens only in POST /v1/admin/agent/confirm.
|
|
27
|
+
*/
|
|
28
|
+
export function buildAgentTools({
|
|
29
|
+
container,
|
|
30
|
+
actorEmail,
|
|
31
|
+
sessionId,
|
|
32
|
+
}: {
|
|
33
|
+
container: HogsendClient;
|
|
34
|
+
actorEmail: string;
|
|
35
|
+
sessionId?: string;
|
|
36
|
+
}) {
|
|
37
|
+
const { db, env, registry, bucketRegistry, domainStatus } = container;
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Shared body for every write tool. NEVER performs the write. The recorded
|
|
41
|
+
* tier is the EFFECTIVE tier at mint time (test-mode-aware) so the confirm
|
|
42
|
+
* route can detect a test-mode change between propose and confirm. The args
|
|
43
|
+
* are stored server-side in Redis and deliberately NOT returned to the browser.
|
|
44
|
+
*/
|
|
45
|
+
const mintWrite = async (
|
|
46
|
+
toolName: string,
|
|
47
|
+
args: Record<string, unknown>,
|
|
48
|
+
summary: string,
|
|
49
|
+
) => {
|
|
50
|
+
const tier = effectiveTier(toolName, {
|
|
51
|
+
testMode: domainStatus.testModeCached(),
|
|
52
|
+
});
|
|
53
|
+
const { proposalId, token, expiresAt } = await mintProposal({
|
|
54
|
+
secret: env.BETTER_AUTH_SECRET,
|
|
55
|
+
tool: toolName,
|
|
56
|
+
args,
|
|
57
|
+
tier,
|
|
58
|
+
actorEmail,
|
|
59
|
+
sessionId,
|
|
60
|
+
});
|
|
61
|
+
return {
|
|
62
|
+
status: "needs_confirmation" as const,
|
|
63
|
+
proposalId,
|
|
64
|
+
token,
|
|
65
|
+
tool: toolName,
|
|
66
|
+
summary,
|
|
67
|
+
tier,
|
|
68
|
+
expiresAt,
|
|
69
|
+
};
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
return {
|
|
73
|
+
// ---- READ TOOLS (auto-run) ----------------------------------------------
|
|
74
|
+
list_journeys: tool({
|
|
75
|
+
description:
|
|
76
|
+
"List the journeys (lifecycle email sequences) registered in this Hogsend instance: id, name, whether enabled, and the event that triggers each.",
|
|
77
|
+
inputSchema: z.object({}),
|
|
78
|
+
execute: async () =>
|
|
79
|
+
registry.getAll().map((j) => ({
|
|
80
|
+
id: j.id,
|
|
81
|
+
name: j.name,
|
|
82
|
+
enabled: j.enabled,
|
|
83
|
+
trigger: j.trigger?.event,
|
|
84
|
+
})),
|
|
85
|
+
}),
|
|
86
|
+
|
|
87
|
+
list_buckets: tool({
|
|
88
|
+
description:
|
|
89
|
+
"List the buckets (real-time segments) registered in this instance: id and name.",
|
|
90
|
+
inputSchema: z.object({}),
|
|
91
|
+
execute: async () =>
|
|
92
|
+
bucketRegistry.getAll().map((b) => ({ id: b.id, name: b.name })),
|
|
93
|
+
}),
|
|
94
|
+
|
|
95
|
+
overview_stats: tool({
|
|
96
|
+
description:
|
|
97
|
+
"High-level instance stats: total (non-deleted) contacts and the count of active/waiting journey enrollments right now.",
|
|
98
|
+
inputSchema: z.object({}),
|
|
99
|
+
execute: async () => {
|
|
100
|
+
const [totalContacts, activeJourneyEnrollments] = await Promise.all([
|
|
101
|
+
db
|
|
102
|
+
.select({ c: count() })
|
|
103
|
+
.from(contacts)
|
|
104
|
+
.where(isNull(contacts.deletedAt))
|
|
105
|
+
.then((r) => r[0]?.c ?? 0),
|
|
106
|
+
db
|
|
107
|
+
.select({ c: count() })
|
|
108
|
+
.from(journeyStates)
|
|
109
|
+
.where(
|
|
110
|
+
and(
|
|
111
|
+
inArray(journeyStates.status, ["active", "waiting"]),
|
|
112
|
+
isNull(journeyStates.deletedAt),
|
|
113
|
+
),
|
|
114
|
+
)
|
|
115
|
+
.then((r) => r[0]?.c ?? 0),
|
|
116
|
+
]);
|
|
117
|
+
return { totalContacts, activeJourneyEnrollments };
|
|
118
|
+
},
|
|
119
|
+
}),
|
|
120
|
+
|
|
121
|
+
query_events: tool({
|
|
122
|
+
description:
|
|
123
|
+
"List recently ingested events, most recent first. Optionally filter by exact event name (e.g. 'checkout.completed'). Use this to investigate what users have done.",
|
|
124
|
+
inputSchema: z.object({
|
|
125
|
+
event: z.string().optional().describe("exact event name to filter by"),
|
|
126
|
+
limit: z.number().int().min(1).max(100).default(20),
|
|
127
|
+
}),
|
|
128
|
+
execute: async ({ event, limit }) => {
|
|
129
|
+
const where = event ? eq(userEvents.event, event) : undefined;
|
|
130
|
+
return db
|
|
131
|
+
.select({
|
|
132
|
+
event: userEvents.event,
|
|
133
|
+
userId: userEvents.userId,
|
|
134
|
+
source: userEvents.source,
|
|
135
|
+
occurredAt: userEvents.occurredAt,
|
|
136
|
+
})
|
|
137
|
+
.from(userEvents)
|
|
138
|
+
.where(where)
|
|
139
|
+
.orderBy(desc(userEvents.occurredAt))
|
|
140
|
+
.limit(limit);
|
|
141
|
+
},
|
|
142
|
+
}),
|
|
143
|
+
|
|
144
|
+
find_contacts: tool({
|
|
145
|
+
description:
|
|
146
|
+
"Search contacts by email / external id / anonymous id / discord id (substring match). Returns up to `limit` non-deleted contacts, most recently seen first.",
|
|
147
|
+
inputSchema: z.object({
|
|
148
|
+
search: z.string().min(1),
|
|
149
|
+
limit: z.number().int().min(1).max(50).default(10),
|
|
150
|
+
}),
|
|
151
|
+
execute: async ({ search, limit }) =>
|
|
152
|
+
db
|
|
153
|
+
.select({
|
|
154
|
+
id: contacts.id,
|
|
155
|
+
email: contacts.email,
|
|
156
|
+
externalId: contacts.externalId,
|
|
157
|
+
lastSeenAt: contacts.lastSeenAt,
|
|
158
|
+
})
|
|
159
|
+
.from(contacts)
|
|
160
|
+
.where(and(contactSearchFilter(search), isNull(contacts.deletedAt)))
|
|
161
|
+
.orderBy(desc(contacts.lastSeenAt))
|
|
162
|
+
.limit(limit),
|
|
163
|
+
}),
|
|
164
|
+
|
|
165
|
+
get_contact: tool({
|
|
166
|
+
description:
|
|
167
|
+
"Fetch a single contact (by uuid or external id) plus its email preferences.",
|
|
168
|
+
inputSchema: z.object({ id: z.string().min(1) }),
|
|
169
|
+
execute: async ({ id }) => {
|
|
170
|
+
const contact = await resolveContact({ db, id });
|
|
171
|
+
if (!contact) return { error: `No contact for "${id}"` };
|
|
172
|
+
const prefs = await db
|
|
173
|
+
.select()
|
|
174
|
+
.from(emailPreferences)
|
|
175
|
+
.where(eq(emailPreferences.userId, contact.externalId ?? contact.id))
|
|
176
|
+
.limit(1);
|
|
177
|
+
return { contact, preferences: prefs[0] ?? null };
|
|
178
|
+
},
|
|
179
|
+
}),
|
|
180
|
+
|
|
181
|
+
get_contact_timeline: tool({
|
|
182
|
+
description:
|
|
183
|
+
"A contact's recent activity: events and journey enrollments. Pass the contact uuid or external id.",
|
|
184
|
+
inputSchema: z.object({
|
|
185
|
+
id: z.string().min(1),
|
|
186
|
+
limit: z.number().int().min(1).max(50).default(20),
|
|
187
|
+
}),
|
|
188
|
+
execute: async ({ id, limit }) => {
|
|
189
|
+
const contact = await resolveContact({ db, id });
|
|
190
|
+
if (!contact) return { error: `No contact for "${id}"` };
|
|
191
|
+
const key = contactKey(contact);
|
|
192
|
+
const [events, journeys] = await Promise.all([
|
|
193
|
+
db
|
|
194
|
+
.select({
|
|
195
|
+
event: userEvents.event,
|
|
196
|
+
source: userEvents.source,
|
|
197
|
+
occurredAt: userEvents.occurredAt,
|
|
198
|
+
})
|
|
199
|
+
.from(userEvents)
|
|
200
|
+
.where(eq(userEvents.userId, key))
|
|
201
|
+
.orderBy(desc(userEvents.occurredAt))
|
|
202
|
+
.limit(limit),
|
|
203
|
+
db
|
|
204
|
+
.select({
|
|
205
|
+
journeyId: journeyStates.journeyId,
|
|
206
|
+
status: journeyStates.status,
|
|
207
|
+
createdAt: journeyStates.createdAt,
|
|
208
|
+
})
|
|
209
|
+
.from(journeyStates)
|
|
210
|
+
.where(
|
|
211
|
+
and(
|
|
212
|
+
eq(journeyStates.userId, key),
|
|
213
|
+
isNull(journeyStates.deletedAt),
|
|
214
|
+
),
|
|
215
|
+
)
|
|
216
|
+
.orderBy(desc(journeyStates.createdAt))
|
|
217
|
+
.limit(limit),
|
|
218
|
+
]);
|
|
219
|
+
return { contactKey: key, events, journeys };
|
|
220
|
+
},
|
|
221
|
+
}),
|
|
222
|
+
|
|
223
|
+
list_sends: tool({
|
|
224
|
+
description:
|
|
225
|
+
"List recent email sends, most recent first: template, recipient, status, and timestamps.",
|
|
226
|
+
inputSchema: z.object({
|
|
227
|
+
limit: z.number().int().min(1).max(50).default(20),
|
|
228
|
+
}),
|
|
229
|
+
execute: async ({ limit }) =>
|
|
230
|
+
db
|
|
231
|
+
.select({
|
|
232
|
+
id: emailSends.id,
|
|
233
|
+
templateKey: emailSends.templateKey,
|
|
234
|
+
to: emailSends.toEmail,
|
|
235
|
+
status: emailSends.status,
|
|
236
|
+
sentAt: emailSends.sentAt,
|
|
237
|
+
openedAt: emailSends.openedAt,
|
|
238
|
+
clickedAt: emailSends.clickedAt,
|
|
239
|
+
})
|
|
240
|
+
.from(emailSends)
|
|
241
|
+
.orderBy(desc(emailSends.createdAt))
|
|
242
|
+
.limit(limit),
|
|
243
|
+
}),
|
|
244
|
+
|
|
245
|
+
build_audience: tool({
|
|
246
|
+
description:
|
|
247
|
+
"Count contacts matching an ad-hoc criterion (a property comparison OR an event-occurred-within-window check). Returns the matched count and a sample of contact ids. Read-only — does NOT create a bucket or campaign. Scans up to 5000 contacts.",
|
|
248
|
+
inputSchema: z.object({
|
|
249
|
+
kind: z.enum(["property", "event"]),
|
|
250
|
+
property: z.string().optional(),
|
|
251
|
+
op: z
|
|
252
|
+
.enum(["eq", "neq", "gt", "gte", "lt", "lte", "contains", "exists"])
|
|
253
|
+
.optional(),
|
|
254
|
+
value: z.union([z.string(), z.number(), z.boolean()]).optional(),
|
|
255
|
+
event: z.string().optional(),
|
|
256
|
+
withinDays: z.number().int().min(1).max(365).optional(),
|
|
257
|
+
}),
|
|
258
|
+
execute: async (input) => {
|
|
259
|
+
const condition =
|
|
260
|
+
input.kind === "event"
|
|
261
|
+
? criteriaBuilder
|
|
262
|
+
.event(input.event ?? "")
|
|
263
|
+
.within(days(input.withinDays ?? 7))
|
|
264
|
+
.exists()
|
|
265
|
+
: (() => {
|
|
266
|
+
const m = criteriaBuilder.prop(input.property ?? "");
|
|
267
|
+
switch (input.op) {
|
|
268
|
+
case "exists":
|
|
269
|
+
return m.exists();
|
|
270
|
+
case "neq":
|
|
271
|
+
return m.neq(input.value ?? "");
|
|
272
|
+
case "gt":
|
|
273
|
+
return m.gt(Number(input.value));
|
|
274
|
+
case "gte":
|
|
275
|
+
return m.gte(Number(input.value));
|
|
276
|
+
case "lt":
|
|
277
|
+
return m.lt(Number(input.value));
|
|
278
|
+
case "lte":
|
|
279
|
+
return m.lte(Number(input.value));
|
|
280
|
+
case "contains":
|
|
281
|
+
return m.contains(input.value ?? "");
|
|
282
|
+
default:
|
|
283
|
+
return m.eq(input.value ?? "");
|
|
284
|
+
}
|
|
285
|
+
})();
|
|
286
|
+
|
|
287
|
+
const all = await db
|
|
288
|
+
.select()
|
|
289
|
+
.from(contacts)
|
|
290
|
+
.where(isNull(contacts.deletedAt))
|
|
291
|
+
.limit(5000);
|
|
292
|
+
const matched: string[] = [];
|
|
293
|
+
for (const c of all) {
|
|
294
|
+
const ok = await evaluateCondition({
|
|
295
|
+
condition,
|
|
296
|
+
ctx: {
|
|
297
|
+
db,
|
|
298
|
+
userId: contactKey(c),
|
|
299
|
+
journeyContext: (c.properties ?? {}) as Record<string, unknown>,
|
|
300
|
+
},
|
|
301
|
+
});
|
|
302
|
+
if (ok) matched.push(c.id);
|
|
303
|
+
}
|
|
304
|
+
return {
|
|
305
|
+
count: matched.length,
|
|
306
|
+
sample: matched.slice(0, 10),
|
|
307
|
+
capped: all.length === 5000,
|
|
308
|
+
};
|
|
309
|
+
},
|
|
310
|
+
}),
|
|
311
|
+
|
|
312
|
+
// ---- WRITE TOOLS (mint-only — NO side effect here) -----------------------
|
|
313
|
+
fire_event: tool({
|
|
314
|
+
description:
|
|
315
|
+
"Fire an event for a contact through the full ingest pipeline (triggers journeys/buckets). REQUIRES operator confirmation — returns a proposal, does not fire.",
|
|
316
|
+
inputSchema: z.object({
|
|
317
|
+
event: z.string().min(1),
|
|
318
|
+
userId: z.string().optional(),
|
|
319
|
+
userEmail: z.string().email().optional(),
|
|
320
|
+
eventProperties: z.record(z.string(), z.unknown()).default({}),
|
|
321
|
+
}),
|
|
322
|
+
execute: async (args) =>
|
|
323
|
+
mintWrite(
|
|
324
|
+
"fire_event",
|
|
325
|
+
args,
|
|
326
|
+
`Fire event "${args.event}" for ${args.userEmail ?? args.userId ?? "(no recipient)"}`,
|
|
327
|
+
),
|
|
328
|
+
}),
|
|
329
|
+
|
|
330
|
+
send_transactional_email: tool({
|
|
331
|
+
description:
|
|
332
|
+
"Send one transactional email from a registered template to one recipient. REQUIRES confirmation — returns a proposal, does not send.",
|
|
333
|
+
inputSchema: z.object({
|
|
334
|
+
template: z.string().min(1),
|
|
335
|
+
to: z.string().email(),
|
|
336
|
+
props: z.record(z.string(), z.unknown()).default({}),
|
|
337
|
+
subject: z.string().optional(),
|
|
338
|
+
userId: z.string().optional(),
|
|
339
|
+
}),
|
|
340
|
+
execute: async (args) =>
|
|
341
|
+
mintWrite(
|
|
342
|
+
"send_transactional_email",
|
|
343
|
+
args,
|
|
344
|
+
`Send "${args.template}" to ${args.to}`,
|
|
345
|
+
),
|
|
346
|
+
}),
|
|
347
|
+
|
|
348
|
+
send_campaign: tool({
|
|
349
|
+
description:
|
|
350
|
+
"Broadcast a template to every subscribed member of a list OR every active member of a bucket. REQUIRES confirmation — returns a proposal, does not send.",
|
|
351
|
+
inputSchema: z
|
|
352
|
+
.object({
|
|
353
|
+
name: z.string().optional(),
|
|
354
|
+
list: z.string().optional(),
|
|
355
|
+
bucket: z.string().optional(),
|
|
356
|
+
template: z.string().min(1),
|
|
357
|
+
props: z.record(z.string(), z.unknown()).default({}),
|
|
358
|
+
subject: z.string().optional(),
|
|
359
|
+
from: z.string().optional(),
|
|
360
|
+
})
|
|
361
|
+
.refine((b) => (b.list ? 1 : 0) + (b.bucket ? 1 : 0) === 1, {
|
|
362
|
+
message: "Exactly one of `list` or `bucket` is required",
|
|
363
|
+
}),
|
|
364
|
+
execute: async (args) =>
|
|
365
|
+
mintWrite(
|
|
366
|
+
"send_campaign",
|
|
367
|
+
args,
|
|
368
|
+
`Broadcast "${args.template}" to ${args.list ? `list ${args.list}` : `bucket ${args.bucket}`}`,
|
|
369
|
+
),
|
|
370
|
+
}),
|
|
371
|
+
|
|
372
|
+
enroll_in_journey: tool({
|
|
373
|
+
description:
|
|
374
|
+
"Manually enroll a contact in a journey by firing its trigger event. REQUIRES confirmation.",
|
|
375
|
+
inputSchema: z.object({
|
|
376
|
+
journeyId: z.string().min(1),
|
|
377
|
+
userId: z.string().optional(),
|
|
378
|
+
userEmail: z.string().email().optional(),
|
|
379
|
+
properties: z.record(z.string(), z.unknown()).default({}),
|
|
380
|
+
}),
|
|
381
|
+
execute: async (args) =>
|
|
382
|
+
mintWrite(
|
|
383
|
+
"enroll_in_journey",
|
|
384
|
+
args,
|
|
385
|
+
`Enroll ${args.userEmail ?? args.userId ?? "(no recipient)"} in journey ${args.journeyId}`,
|
|
386
|
+
),
|
|
387
|
+
}),
|
|
388
|
+
|
|
389
|
+
subscribe_list: tool({
|
|
390
|
+
description:
|
|
391
|
+
"Subscribe a contact to an email list (opt-in). REQUIRES confirmation.",
|
|
392
|
+
inputSchema: z.object({
|
|
393
|
+
list: z.string().min(1),
|
|
394
|
+
userId: z.string().optional(),
|
|
395
|
+
email: z.string().email().optional(),
|
|
396
|
+
}),
|
|
397
|
+
execute: async (args) =>
|
|
398
|
+
mintWrite(
|
|
399
|
+
"subscribe_list",
|
|
400
|
+
args,
|
|
401
|
+
`Subscribe ${args.email ?? args.userId} to list ${args.list}`,
|
|
402
|
+
),
|
|
403
|
+
}),
|
|
404
|
+
|
|
405
|
+
unsubscribe_list: tool({
|
|
406
|
+
description:
|
|
407
|
+
"Unsubscribe a contact from an email list (opt-out). REQUIRES confirmation.",
|
|
408
|
+
inputSchema: z.object({
|
|
409
|
+
list: z.string().min(1),
|
|
410
|
+
userId: z.string().optional(),
|
|
411
|
+
email: z.string().email().optional(),
|
|
412
|
+
}),
|
|
413
|
+
execute: async (args) =>
|
|
414
|
+
mintWrite(
|
|
415
|
+
"unsubscribe_list",
|
|
416
|
+
args,
|
|
417
|
+
`Unsubscribe ${args.email ?? args.userId} from list ${args.list}`,
|
|
418
|
+
),
|
|
419
|
+
}),
|
|
420
|
+
|
|
421
|
+
upsert_contact: tool({
|
|
422
|
+
description:
|
|
423
|
+
"Create or update a contact by email / external id, optionally setting properties. REQUIRES confirmation.",
|
|
424
|
+
inputSchema: z.object({
|
|
425
|
+
userId: z.string().optional(),
|
|
426
|
+
email: z.string().email().optional(),
|
|
427
|
+
anonymousId: z.string().optional(),
|
|
428
|
+
properties: z.record(z.string(), z.unknown()).default({}),
|
|
429
|
+
}),
|
|
430
|
+
execute: async (args) =>
|
|
431
|
+
mintWrite(
|
|
432
|
+
"upsert_contact",
|
|
433
|
+
args,
|
|
434
|
+
`Upsert contact ${args.email ?? args.userId ?? args.anonymousId}`,
|
|
435
|
+
),
|
|
436
|
+
}),
|
|
437
|
+
|
|
438
|
+
update_contact: tool({
|
|
439
|
+
description:
|
|
440
|
+
"Update an existing contact's email and/or properties (by uuid or external id). REQUIRES confirmation.",
|
|
441
|
+
inputSchema: z.object({
|
|
442
|
+
id: z.string().min(1),
|
|
443
|
+
email: z.string().email().optional(),
|
|
444
|
+
properties: z.record(z.string(), z.unknown()).default({}),
|
|
445
|
+
}),
|
|
446
|
+
execute: async (args) =>
|
|
447
|
+
mintWrite("update_contact", args, `Update contact ${args.id}`),
|
|
448
|
+
}),
|
|
449
|
+
|
|
450
|
+
delete_contact: tool({
|
|
451
|
+
description:
|
|
452
|
+
"Soft-delete a contact (sets deletedAt). DESTRUCTIVE — requires confirmation.",
|
|
453
|
+
inputSchema: z.object({
|
|
454
|
+
email: z.string().email().optional(),
|
|
455
|
+
userId: z.string().optional(),
|
|
456
|
+
}),
|
|
457
|
+
execute: async (args) =>
|
|
458
|
+
mintWrite(
|
|
459
|
+
"delete_contact",
|
|
460
|
+
args,
|
|
461
|
+
`Delete contact ${args.email ?? args.userId}`,
|
|
462
|
+
),
|
|
463
|
+
}),
|
|
464
|
+
};
|
|
465
|
+
}
|
|
@@ -1,4 +1,7 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type {
|
|
2
|
+
AnalyticsEventMirrorConfig,
|
|
3
|
+
AnalyticsProvider,
|
|
4
|
+
} from "@hogsend/core";
|
|
2
5
|
import { createOptionalSingleton } from "./singleton.js";
|
|
3
6
|
|
|
4
7
|
/**
|
|
@@ -30,3 +33,17 @@ export const setAnalytics = singleton.set;
|
|
|
30
33
|
export const getAnalytics = singleton.get;
|
|
31
34
|
/** Reset the singleton — only for test cleanup. */
|
|
32
35
|
export const resetAnalytics = singleton.reset;
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* The resolved {@link AnalyticsEventMirrorConfig} — set once by
|
|
39
|
+
* `createHogsendClient` alongside {@link setAnalytics}, read by `ingestEvent`
|
|
40
|
+
* to decide whether to mirror each ingested event into the active provider.
|
|
41
|
+
* Optional singleton: when the container resolves no mirror config the read
|
|
42
|
+
* stays `undefined` and the mirror no-ops (DB-only behaviour).
|
|
43
|
+
*/
|
|
44
|
+
const mirrorSingleton = createOptionalSingleton<AnalyticsEventMirrorConfig>();
|
|
45
|
+
|
|
46
|
+
export const setAnalyticsEventMirror = mirrorSingleton.set;
|
|
47
|
+
export const getAnalyticsEventMirror = mirrorSingleton.get;
|
|
48
|
+
/** Reset the singleton — only for test cleanup. */
|
|
49
|
+
export const resetAnalyticsEventMirror = mirrorSingleton.reset;
|
|
@@ -12,9 +12,23 @@ import { getDb } from "./db.js";
|
|
|
12
12
|
import { createLogger } from "./logger.js";
|
|
13
13
|
|
|
14
14
|
/**
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
15
|
+
* Matches the canonical UUID form of `contacts.id` (8-4-4-4-12 hex). Gates the
|
|
16
|
+
* `eq(contacts.id, ref)` leg so a uuid comparison only runs for a genuinely
|
|
17
|
+
* uuid-shaped ref — an email/snowflake ref would otherwise raise a Postgres
|
|
18
|
+
* `22P02 invalid input syntax for type uuid`.
|
|
19
|
+
*/
|
|
20
|
+
const CONTACT_ID_UUID =
|
|
21
|
+
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Resolve a contact for an outbound action by its canonical key in ANY form:
|
|
25
|
+
* email, external id, a platform id (a Discord snowflake / anonymous id), or —
|
|
26
|
+
* when the ref is uuid-shaped — the contact's row `id`. Matching every canonical
|
|
27
|
+
* key form (the journey subject key is `external_id ?? anonymous_id ?? id`) lets
|
|
28
|
+
* `member: user.id` resolve a member who has NOT linked (an anonymous Discord
|
|
29
|
+
* contact keyed by its uuid) or an email-only member. The uuid `id` leg is
|
|
30
|
+
* shape-gated: `contacts.id` is a uuid column and an unguarded `eq(id, ref)`
|
|
31
|
+
* against an email/snowflake text ref throws an invalid-uuid cast. First live
|
|
18
32
|
* match wins.
|
|
19
33
|
*/
|
|
20
34
|
async function resolveContact(
|
|
@@ -38,6 +52,8 @@ async function resolveContact(
|
|
|
38
52
|
eq(contacts.email, ref),
|
|
39
53
|
eq(contacts.externalId, ref),
|
|
40
54
|
eq(contacts.discordId, ref),
|
|
55
|
+
eq(contacts.anonymousId, ref),
|
|
56
|
+
...(CONTACT_ID_UUID.test(ref) ? [eq(contacts.id, ref)] : []),
|
|
41
57
|
),
|
|
42
58
|
),
|
|
43
59
|
)
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
2
|
-
import type {
|
|
2
|
+
import type {
|
|
3
|
+
AnalyticsEventMirrorConfig,
|
|
4
|
+
AnalyticsProvider,
|
|
5
|
+
} from "@hogsend/core";
|
|
3
6
|
import { evaluatePropertyConditions } from "@hogsend/core";
|
|
4
7
|
import type { JourneyRegistry } from "@hogsend/core/registry";
|
|
5
8
|
import { type Database, journeyStates, userEvents } from "@hogsend/db";
|
|
@@ -9,6 +12,10 @@ import {
|
|
|
9
12
|
logResidualTwins,
|
|
10
13
|
mergeAnalyticsIdentities,
|
|
11
14
|
} from "./analytics-identity.js";
|
|
15
|
+
import {
|
|
16
|
+
getAnalytics,
|
|
17
|
+
getAnalyticsEventMirror,
|
|
18
|
+
} from "./analytics-singleton.js";
|
|
12
19
|
import { resolveOrCreateContact } from "./contacts.js";
|
|
13
20
|
import type { Logger } from "./logger.js";
|
|
14
21
|
|
|
@@ -122,6 +129,20 @@ export async function ingestTransformResult(opts: {
|
|
|
122
129
|
return { ingested, exits };
|
|
123
130
|
}
|
|
124
131
|
|
|
132
|
+
/**
|
|
133
|
+
* Event-name filter for the {@link AnalyticsEventMirrorConfig}: an `allow` list
|
|
134
|
+
* (when set) gates to those names, then `deny` removes any. The `source` filter
|
|
135
|
+
* (never mirror `"posthog"`-origin events) is enforced at the call site.
|
|
136
|
+
*/
|
|
137
|
+
function shouldMirrorEvent(
|
|
138
|
+
eventName: string,
|
|
139
|
+
cfg: AnalyticsEventMirrorConfig,
|
|
140
|
+
): boolean {
|
|
141
|
+
if (cfg.allow && !cfg.allow.includes(eventName)) return false;
|
|
142
|
+
if (cfg.deny?.includes(eventName)) return false;
|
|
143
|
+
return true;
|
|
144
|
+
}
|
|
145
|
+
|
|
125
146
|
export async function ingestEvent(opts: {
|
|
126
147
|
db: Database;
|
|
127
148
|
registry: JourneyRegistry;
|
|
@@ -137,8 +158,16 @@ export async function ingestEvent(opts: {
|
|
|
137
158
|
* provider without `identityMerge` no-ops cleanly.
|
|
138
159
|
*/
|
|
139
160
|
analytics?: AnalyticsProvider;
|
|
161
|
+
/**
|
|
162
|
+
* Operator policy for mirroring THIS event into `analytics` via `capture()`.
|
|
163
|
+
* Test/advanced override: real call sites omit it and the resolved config is
|
|
164
|
+
* read from the analytics singleton (installed by `createHogsendClient`), so
|
|
165
|
+
* the mirror fires on every ingest path without threading. Absent on both ⇒
|
|
166
|
+
* no mirror.
|
|
167
|
+
*/
|
|
168
|
+
eventMirror?: AnalyticsEventMirrorConfig;
|
|
140
169
|
}): Promise<IngestResult> {
|
|
141
|
-
const { db, registry, hatchet, logger, event, analytics } = opts;
|
|
170
|
+
const { db, registry, hatchet, logger, event, analytics, eventMirror } = opts;
|
|
142
171
|
|
|
143
172
|
// (1) Resolve identity FIRST (awaited — no longer fire-and-forget). The
|
|
144
173
|
// contact-referencing tables join on a NOT NULL text key, so an email-only /
|
|
@@ -232,6 +261,37 @@ export async function ingestEvent(opts: {
|
|
|
232
261
|
}
|
|
233
262
|
}
|
|
234
263
|
|
|
264
|
+
// (2c) Event mirror — best-effort `capture()` into the active analytics
|
|
265
|
+
// provider, gated by operator policy. Placed on the fresh-insert side of the
|
|
266
|
+
// idempotency guard (the duplicate path returned at the early `stored:false`
|
|
267
|
+
// above), so a same-key retry NEVER double-mirrors — `capture` is NOT
|
|
268
|
+
// idempotent, and this is the ONLY site that calls it on the ingest spine
|
|
269
|
+
// (never a journey task). Provider + config fall back to the container
|
|
270
|
+
// singletons so the mirror fires on EVERY ingest path, not just the routes
|
|
271
|
+
// that thread `analytics`. `source === "posthog"` events are excluded
|
|
272
|
+
// unconditionally (they came FROM PostHog — re-capturing them would loop).
|
|
273
|
+
const mirrorProvider = analytics ?? getAnalytics();
|
|
274
|
+
const mirrorConfig = eventMirror ?? getAnalyticsEventMirror();
|
|
275
|
+
if (
|
|
276
|
+
mirrorConfig?.enabled &&
|
|
277
|
+
mirrorProvider?.capabilities.personWrites &&
|
|
278
|
+
event.source !== "posthog" &&
|
|
279
|
+
shouldMirrorEvent(event.event, mirrorConfig)
|
|
280
|
+
) {
|
|
281
|
+
try {
|
|
282
|
+
mirrorProvider.capture({
|
|
283
|
+
distinctId: resolvedKey,
|
|
284
|
+
event: event.event,
|
|
285
|
+
properties: event.eventProperties,
|
|
286
|
+
});
|
|
287
|
+
} catch (err) {
|
|
288
|
+
logger.debug("event mirror capture failed (non-fatal)", {
|
|
289
|
+
event: event.event,
|
|
290
|
+
error: err instanceof Error ? err.message : String(err),
|
|
291
|
+
});
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
|
|
235
295
|
// (3) Build the JSON-serializable subset of eventProperties for the Hatchet
|
|
236
296
|
// push payload (scalars only — the SDK serializes the envelope).
|
|
237
297
|
const serializableProperties = Object.fromEntries(
|
|
@@ -198,9 +198,12 @@ export interface PushLinkClickEventOpts {
|
|
|
198
198
|
linkUrl: string;
|
|
199
199
|
/**
|
|
200
200
|
* The personal link's canonical contact key (`links.distinct_id`). MUST be the
|
|
201
|
-
* subject's EXTERNAL canonical key (an app `external_id
|
|
202
|
-
*
|
|
203
|
-
* contact.
|
|
201
|
+
* subject's EXTERNAL canonical key (an app `external_id`) or the contact's
|
|
202
|
+
* canonical uuid key — a raw snowflake or anonymous id would fork an orphan
|
|
203
|
+
* contact. NOTE: a Discord member is keyed by the `discord_id` COLUMN, not an
|
|
204
|
+
* `external_id`, so a `"discord:<id>"` value here would fork an orphan contact;
|
|
205
|
+
* reach a discord-keyed contact by its resolved canonical key instead. Null ⇒
|
|
206
|
+
* a broadcast/public link (no person) ⇒ no re-ingest.
|
|
204
207
|
*/
|
|
205
208
|
distinctId: string | null;
|
|
206
209
|
idempotencyKey?: string;
|