@hogsend/engine 0.33.0 → 0.34.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 +7 -7
- package/src/container.ts +23 -1
- package/src/env.ts +7 -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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.34.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -40,14 +40,14 @@
|
|
|
40
40
|
"svix": "^1.95.1",
|
|
41
41
|
"winston": "^3.19.0",
|
|
42
42
|
"zod": "^4.4.3",
|
|
43
|
-
"@hogsend/core": "^0.
|
|
44
|
-
"@hogsend/db": "^0.
|
|
45
|
-
"@hogsend/email": "^0.
|
|
46
|
-
"@hogsend/plugin-posthog": "^0.
|
|
47
|
-
"@hogsend/plugin-resend": "^0.
|
|
43
|
+
"@hogsend/core": "^0.34.0",
|
|
44
|
+
"@hogsend/db": "^0.34.0",
|
|
45
|
+
"@hogsend/email": "^0.34.0",
|
|
46
|
+
"@hogsend/plugin-posthog": "^0.34.0",
|
|
47
|
+
"@hogsend/plugin-resend": "^0.34.0"
|
|
48
48
|
},
|
|
49
49
|
"optionalDependencies": {
|
|
50
|
-
"@hogsend/plugin-postmark": "^0.
|
|
50
|
+
"@hogsend/plugin-postmark": "^0.34.0"
|
|
51
51
|
},
|
|
52
52
|
"devDependencies": {
|
|
53
53
|
"@types/node": "^22.15.3",
|
package/src/container.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
2
2
|
import type {
|
|
3
|
+
AnalyticsEventMirrorConfig,
|
|
3
4
|
AnalyticsProvider,
|
|
4
5
|
EmailProvider,
|
|
5
6
|
PostHogService,
|
|
@@ -47,7 +48,10 @@ import {
|
|
|
47
48
|
} from "./lib/analytics-adapter.js";
|
|
48
49
|
import { AnalyticsProviderRegistry } from "./lib/analytics-provider-registry.js";
|
|
49
50
|
import { analyticsProvidersFromEnv } from "./lib/analytics-providers-from-env.js";
|
|
50
|
-
import {
|
|
51
|
+
import {
|
|
52
|
+
setAnalytics,
|
|
53
|
+
setAnalyticsEventMirror,
|
|
54
|
+
} from "./lib/analytics-singleton.js";
|
|
51
55
|
import { type Auth, createAuth } from "./lib/auth.js";
|
|
52
56
|
import {
|
|
53
57
|
createDomainStatusService,
|
|
@@ -271,6 +275,7 @@ export interface HogsendClientOptions {
|
|
|
271
275
|
provider?: AnalyticsProvider;
|
|
272
276
|
providers?: AnalyticsProvider[];
|
|
273
277
|
defaultProvider?: string;
|
|
278
|
+
eventMirror?: AnalyticsEventMirrorConfig;
|
|
274
279
|
};
|
|
275
280
|
/**
|
|
276
281
|
* Code-defined outbound DESTINATIONS (Phase 3). Each is a
|
|
@@ -588,6 +593,7 @@ export function createHogsendClient(
|
|
|
588
593
|
provider?: AnalyticsProvider;
|
|
589
594
|
providers?: AnalyticsProvider[];
|
|
590
595
|
defaultProvider?: string;
|
|
596
|
+
eventMirror?: AnalyticsEventMirrorConfig;
|
|
591
597
|
})
|
|
592
598
|
: undefined;
|
|
593
599
|
|
|
@@ -647,6 +653,22 @@ export function createHogsendClient(
|
|
|
647
653
|
// undefined (no provider configured) — the reads stay no-ops.
|
|
648
654
|
setAnalytics(analytics);
|
|
649
655
|
|
|
656
|
+
// Event mirror (operator policy): resolve the ingest→analytics capture config
|
|
657
|
+
// once and install it on the same singleton seam as `analytics`, so
|
|
658
|
+
// `ingestEvent` mirrors events into the active provider on EVERY ingest path
|
|
659
|
+
// (not just the routes that thread `analytics`). Off by default. The env flag
|
|
660
|
+
// is an explicit OVERRIDE in both directions when set ("true"/"false"); unset
|
|
661
|
+
// ⇒ the code option wins. Allow/deny stay code-only (env is not list config).
|
|
662
|
+
const eventMirror: AnalyticsEventMirrorConfig = {
|
|
663
|
+
enabled:
|
|
664
|
+
env.ANALYTICS_EVENT_MIRROR != null
|
|
665
|
+
? env.ANALYTICS_EVENT_MIRROR === "true"
|
|
666
|
+
: (analyticsGroup?.eventMirror?.enabled ?? false),
|
|
667
|
+
allow: analyticsGroup?.eventMirror?.allow,
|
|
668
|
+
deny: analyticsGroup?.eventMirror?.deny,
|
|
669
|
+
};
|
|
670
|
+
setAnalyticsEventMirror(eventMirror);
|
|
671
|
+
|
|
650
672
|
// Identity-attach helper (§7): bound to THIS container's db + resolved
|
|
651
673
|
// analytics provider so a contact-merge outside the `/v1/events` ingest path
|
|
652
674
|
// (Discord `/link`) propagates the analytics merge through the same engine
|
package/src/env.ts
CHANGED
|
@@ -149,6 +149,13 @@ export const env = createEnv({
|
|
|
149
149
|
// Selects the ACTIVE analytics provider id out of the registry (env
|
|
150
150
|
// presets + consumer-registered providers). Mirrors EMAIL_PROVIDER.
|
|
151
151
|
ANALYTICS_PROVIDER: z.string().min(1).default("posthog"),
|
|
152
|
+
// Override for the ingest→analytics event mirror (capture every ingested
|
|
153
|
+
// event into the active analytics provider, keyed to the resolved contact).
|
|
154
|
+
// The code option `analytics.eventMirror.enabled` is the default; this env,
|
|
155
|
+
// when set, OVERRIDES it in both directions. Enum (not z.coerce.boolean) so
|
|
156
|
+
// an explicit "false" actually disables (coerce.boolean treats "false" as
|
|
157
|
+
// true). Unset ⇒ the code option wins. Allow/deny lists stay code-only.
|
|
158
|
+
ANALYTICS_EVENT_MIRROR: z.enum(["true", "false"]).optional(),
|
|
152
159
|
POSTHOG_WEBHOOK_SECRET: z.string().min(1).optional(),
|
|
153
160
|
// When true AND POSTHOG_API_KEY is set, the engine idempotently auto-seeds
|
|
154
161
|
// ONE kind="posthog" webhook endpoint subscribed to the email funnel so the
|
|
@@ -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;
|