@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.
@@ -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 { AnalyticsProvider } from "@hogsend/core";
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
- * Resolve a contact for an outbound action by email, external id, or a platform
16
- * id (e.g. a Discord snowflake). Matches text columns only (NOT the uuid `id`,
17
- * which would force an invalid-uuid cast error for an email ref). First live
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
  )
@@ -1,5 +1,8 @@
1
1
  import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
- import type { AnalyticsProvider } from "@hogsend/core";
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`, or "discord:<id>" for
202
- * a Discord member) — a raw snowflake or anonymous id would fork an orphan
203
- * contact. Null ⇒ a broadcast/public link (no person) ⇒ no re-ingest.
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;