@hogsend/engine 0.44.0 → 0.46.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 +12 -10
- package/src/container.ts +86 -11
- package/src/journeys/graph/build-graph.ts +95 -2
- package/src/lib/analytics-providers-from-env.ts +106 -43
- package/src/lib/posthog-scopes.ts +30 -6
- package/src/lib/provision-posthog-loop.ts +37 -10
- package/src/lib/unconfigured-email-provider.ts +45 -0
- package/src/routes/admin/analytics.ts +28 -6
- package/src/routes/admin/events.ts +44 -20
- package/src/routes/admin/journeys.ts +28 -33
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.46.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -15,6 +15,8 @@
|
|
|
15
15
|
"./worker": "./src/worker.ts",
|
|
16
16
|
"./auth": "./src/lib/auth.ts",
|
|
17
17
|
"./create-admin": "./src/lib/create-admin.ts",
|
|
18
|
+
"./api-key-hash": "./src/lib/api-key-hash.ts",
|
|
19
|
+
"./posthog-scopes": "./src/lib/posthog-scopes.ts",
|
|
18
20
|
"./mcp/authoring-guide": "./src/mcp/authoring-guide.ts",
|
|
19
21
|
"./package.json": "./package.json"
|
|
20
22
|
},
|
|
@@ -49,17 +51,17 @@
|
|
|
49
51
|
"svix": "^1.95.1",
|
|
50
52
|
"winston": "^3.19.0",
|
|
51
53
|
"zod": "^4.4.3",
|
|
52
|
-
"@hogsend/attribution": "^0.
|
|
53
|
-
"@hogsend/core": "^0.
|
|
54
|
-
"@hogsend/db": "^0.
|
|
55
|
-
"@hogsend/email": "^0.
|
|
56
|
-
"@hogsend/plugin-posthog": "^0.
|
|
57
|
-
"@hogsend/plugin-resend": "^0.
|
|
58
|
-
"@hogsend/sms": "^0.
|
|
54
|
+
"@hogsend/attribution": "^0.46.0",
|
|
55
|
+
"@hogsend/core": "^0.46.0",
|
|
56
|
+
"@hogsend/db": "^0.46.0",
|
|
57
|
+
"@hogsend/email": "^0.46.0",
|
|
58
|
+
"@hogsend/plugin-posthog": "^0.46.0",
|
|
59
|
+
"@hogsend/plugin-resend": "^0.46.0",
|
|
60
|
+
"@hogsend/sms": "^0.46.0"
|
|
59
61
|
},
|
|
60
62
|
"optionalDependencies": {
|
|
61
|
-
"@hogsend/plugin-postmark": "^0.
|
|
62
|
-
"@hogsend/plugin-twilio": "^0.
|
|
63
|
+
"@hogsend/plugin-postmark": "^0.46.0",
|
|
64
|
+
"@hogsend/plugin-twilio": "^0.46.0"
|
|
63
65
|
},
|
|
64
66
|
"devDependencies": {
|
|
65
67
|
"@types/node": "^22.15.3",
|
package/src/container.ts
CHANGED
|
@@ -65,7 +65,10 @@ import {
|
|
|
65
65
|
wrapLegacyAnalyticsService,
|
|
66
66
|
} from "./lib/analytics-adapter.js";
|
|
67
67
|
import { AnalyticsProviderRegistry } from "./lib/analytics-provider-registry.js";
|
|
68
|
-
import {
|
|
68
|
+
import {
|
|
69
|
+
analyticsProvidersFromEnv,
|
|
70
|
+
buildStoredPosthogProvider,
|
|
71
|
+
} from "./lib/analytics-providers-from-env.js";
|
|
69
72
|
import {
|
|
70
73
|
setAnalytics,
|
|
71
74
|
setAnalyticsEventMirror,
|
|
@@ -111,6 +114,7 @@ import { SmsProviderRegistry } from "./lib/sms-provider-registry.js";
|
|
|
111
114
|
import { smsProvidersFromEnv } from "./lib/sms-providers-from-env.js";
|
|
112
115
|
import type { SmsService } from "./lib/sms-service-types.js";
|
|
113
116
|
import { prepareTrackedHtml } from "./lib/tracking.js";
|
|
117
|
+
import { createUnconfiguredEmailProvider } from "./lib/unconfigured-email-provider.js";
|
|
114
118
|
import { synthesizeChannelLists } from "./lists/channels.js";
|
|
115
119
|
import {
|
|
116
120
|
type DefinedList,
|
|
@@ -235,6 +239,16 @@ export interface HogsendClient {
|
|
|
235
239
|
* with acorn to derive a visual workflow. Empty when no journeys are wired.
|
|
236
240
|
*/
|
|
237
241
|
journeySources: Map<string, string>;
|
|
242
|
+
/**
|
|
243
|
+
* The consumer's `Templates`/`Events` `as const` maps, normalized to always
|
|
244
|
+
* be present (`{ templates: {}, events: {} }` when unwired). Consumed by the
|
|
245
|
+
* Studio journey-graph route to resolve `Templates.X` / `Events.X` member
|
|
246
|
+
* expressions to their real values, for exact previews + stable node ids.
|
|
247
|
+
*/
|
|
248
|
+
journeyConstants: {
|
|
249
|
+
templates: Record<string, string>;
|
|
250
|
+
events: Record<string, string>;
|
|
251
|
+
};
|
|
238
252
|
/**
|
|
239
253
|
* Map of enabled journey id → its `defineJourney` call-site `{ path, line }`.
|
|
240
254
|
* Populated by `buildJourneyRegistry`. Consumed by the Studio journey-graph
|
|
@@ -304,6 +318,18 @@ export interface HogsendClient {
|
|
|
304
318
|
export interface HogsendClientOptions {
|
|
305
319
|
/** Journeys to register in the {@link JourneyRegistry}. Defaults to none. */
|
|
306
320
|
journeys?: DefinedJourney[];
|
|
321
|
+
/**
|
|
322
|
+
* The consumer's `Templates`/`Events` `as const` maps (each a
|
|
323
|
+
* `CONST_NAME -> "value"` record). Threaded into the Studio journey-graph
|
|
324
|
+
* route so `Templates.X` / `Events.X` member expressions in a journey's `run`
|
|
325
|
+
* source resolve to their real runtime values — yielding exact email-template
|
|
326
|
+
* previews and stable, join-safe `wait-event:${value}` / `digest:${value}`
|
|
327
|
+
* node ids (instead of positional `unstable` synthetics). Defaults to none.
|
|
328
|
+
*/
|
|
329
|
+
journeyConstants?: {
|
|
330
|
+
templates?: Record<string, string>;
|
|
331
|
+
events?: Record<string, string>;
|
|
332
|
+
};
|
|
307
333
|
/** Buckets to register in the {@link BucketRegistry}. Defaults to none. */
|
|
308
334
|
buckets?: DefinedBucket[];
|
|
309
335
|
/**
|
|
@@ -886,16 +912,30 @@ export function createHogsendClient(
|
|
|
886
912
|
// SINGLE place Resend is constructed from env — so resolution is just a
|
|
887
913
|
// registry lookup that throws if the active id resolves to nothing. NEVER
|
|
888
914
|
// silently fall back for a non-resend id.
|
|
889
|
-
const
|
|
890
|
-
|
|
891
|
-
|
|
915
|
+
const explicitId = opts.email?.defaultProvider ?? env.EMAIL_PROVIDER;
|
|
916
|
+
const activeId = explicitId ?? "resend";
|
|
917
|
+
let provider = emailProviders.get(activeId);
|
|
892
918
|
|
|
893
919
|
if (!provider) {
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
920
|
+
// An EXPLICITLY requested id that resolves to nothing is a config error —
|
|
921
|
+
// throw (typo safety). So is an implicit default when OTHER providers are
|
|
922
|
+
// registered (e.g. Postmark-only without EMAIL_PROVIDER=postmark).
|
|
923
|
+
if (explicitId !== undefined || emailProviders.count() > 0) {
|
|
924
|
+
throw new Error(
|
|
925
|
+
`email provider "${activeId}" is not registered (registered: ${emailProviders
|
|
926
|
+
.getAll()
|
|
927
|
+
.map((p) => p.meta?.id ?? "resend")
|
|
928
|
+
.join(", ")})`,
|
|
929
|
+
);
|
|
930
|
+
}
|
|
931
|
+
// Zero providers + nothing requested = a fresh app without email creds
|
|
932
|
+
// yet. Boot INERT instead of crashing (mirrors the SMS channel's
|
|
933
|
+
// operator-opt-in stub): Studio, ingest and non-email journeys all work;
|
|
934
|
+
// each send fails per-call with an actionable message. The stub is NOT
|
|
935
|
+
// registered in the registry, so no webhook route resolves it.
|
|
936
|
+
provider = createUnconfiguredEmailProvider();
|
|
937
|
+
logger.warn(
|
|
938
|
+
"no email provider configured — email sends will fail until RESEND_API_KEY (or POSTMARK_SERVER_TOKEN with EMAIL_PROVIDER=postmark) is set. Everything else works without one.",
|
|
899
939
|
);
|
|
900
940
|
}
|
|
901
941
|
|
|
@@ -909,7 +949,7 @@ export function createHogsendClient(
|
|
|
909
949
|
logger.warn(
|
|
910
950
|
`provider ${
|
|
911
951
|
provider.meta?.id ?? "resend"
|
|
912
|
-
}
|
|
952
|
+
} can't disable its native open/click tracking per-send (account-level setting) — if it's enabled in the provider dashboard, turn it off there; first-party tracking is Hogsend's source of truth.`,
|
|
913
953
|
);
|
|
914
954
|
}
|
|
915
955
|
|
|
@@ -1389,7 +1429,7 @@ export function createHogsendClient(
|
|
|
1389
1429
|
`Destination registry loaded: ${destinationRegistry.count()} destinations`,
|
|
1390
1430
|
);
|
|
1391
1431
|
|
|
1392
|
-
|
|
1432
|
+
const client: HogsendClient = {
|
|
1393
1433
|
env,
|
|
1394
1434
|
logger,
|
|
1395
1435
|
db,
|
|
@@ -1410,6 +1450,10 @@ export function createHogsendClient(
|
|
|
1410
1450
|
identity,
|
|
1411
1451
|
registry,
|
|
1412
1452
|
journeySources: getJourneySources(),
|
|
1453
|
+
journeyConstants: {
|
|
1454
|
+
templates: opts.journeyConstants?.templates ?? {},
|
|
1455
|
+
events: opts.journeyConstants?.events ?? {},
|
|
1456
|
+
},
|
|
1413
1457
|
journeySourceLocations: getJourneySourceLocations(),
|
|
1414
1458
|
bucketRegistry,
|
|
1415
1459
|
listRegistry,
|
|
@@ -1421,4 +1465,35 @@ export function createHogsendClient(
|
|
|
1421
1465
|
clientJournal: opts.clientJournal ?? { entries: [] },
|
|
1422
1466
|
defaults,
|
|
1423
1467
|
};
|
|
1468
|
+
|
|
1469
|
+
// Boot-time reader for `hogsend connect posthog`'s persisted phc_: when no
|
|
1470
|
+
// provider resolved AND no POSTHOG_API_KEY is set, activate PostHog from the
|
|
1471
|
+
// stored derived credential (async, fire-and-forget — the container is built
|
|
1472
|
+
// synchronously; a failure leaves the container exactly as booted). ALL
|
|
1473
|
+
// activation effects live here, in one block, so "who mutates what" has a
|
|
1474
|
+
// single answer. Skipped under NODE_ENV=test so suites stay hermetic.
|
|
1475
|
+
if (!analytics && !env.POSTHOG_API_KEY && env.NODE_ENV !== "test") {
|
|
1476
|
+
void buildStoredPosthogProvider({ env, db, logger })
|
|
1477
|
+
.then((provider) => {
|
|
1478
|
+
if (!provider) return;
|
|
1479
|
+
// Someone claimed the slot while we read (consumer provider, race).
|
|
1480
|
+
if (client.analytics || analyticsProviders.get("posthog")) return;
|
|
1481
|
+
analyticsProviders.register(provider);
|
|
1482
|
+
client.analytics = provider;
|
|
1483
|
+
setAnalytics(provider);
|
|
1484
|
+
// Rebuild the boot closure that captured `analytics: undefined` so
|
|
1485
|
+
// identity merges propagate to the newly-live provider too.
|
|
1486
|
+
client.identity = createIdentityService({
|
|
1487
|
+
db,
|
|
1488
|
+
analytics: provider,
|
|
1489
|
+
logger,
|
|
1490
|
+
});
|
|
1491
|
+
logger.info(
|
|
1492
|
+
'analytics provider "posthog" activated from the stored `hogsend connect posthog` credential — outbound capture is live without POSTHOG_API_KEY.',
|
|
1493
|
+
);
|
|
1494
|
+
})
|
|
1495
|
+
.catch(() => {});
|
|
1496
|
+
}
|
|
1497
|
+
|
|
1498
|
+
return client;
|
|
1424
1499
|
}
|
|
@@ -120,8 +120,12 @@ interface Raw {
|
|
|
120
120
|
timeout?: Record<string, number>;
|
|
121
121
|
eventLiteral?: string;
|
|
122
122
|
eventIdent?: string;
|
|
123
|
+
/** OBJECT qualifier of an `X.PROP` event member-expr (`Events.NPS` → "Events"). */
|
|
124
|
+
eventObject?: string;
|
|
123
125
|
templateLiteral?: string;
|
|
124
126
|
templateIdent?: string;
|
|
127
|
+
/** OBJECT qualifier of an `X.PROP` template member-expr (`Templates.WELCOME` → "Templates"). */
|
|
128
|
+
templateObject?: string;
|
|
125
129
|
connectorId?: string;
|
|
126
130
|
action?: string;
|
|
127
131
|
idempotencyLabel?: string;
|
|
@@ -129,16 +133,31 @@ interface Raw {
|
|
|
129
133
|
calleeName?: string;
|
|
130
134
|
}
|
|
131
135
|
|
|
136
|
+
/**
|
|
137
|
+
* The consumer's `Templates`/`Events` `as const` maps (`CONST_NAME -> "value"`),
|
|
138
|
+
* threaded through so `Templates.X` / `Events.X` member expressions in a
|
|
139
|
+
* journey's source resolve to their REAL runtime values. This is what makes the
|
|
140
|
+
* derived node ids deterministic (stable `wait-event:${value}` / `digest:${value}`
|
|
141
|
+
* ids that join to `journeyStates.currentNodeId`) and populates `meta.template` /
|
|
142
|
+
* `meta.event` for exact previews — with NO other extraction changes.
|
|
143
|
+
*/
|
|
144
|
+
export interface JourneyGraphConsts {
|
|
145
|
+
templates?: Record<string, string>;
|
|
146
|
+
events?: Record<string, string>;
|
|
147
|
+
}
|
|
148
|
+
|
|
132
149
|
export function buildJourneyGraph({
|
|
133
150
|
runSource,
|
|
134
151
|
meta,
|
|
152
|
+
consts,
|
|
135
153
|
}: {
|
|
136
154
|
runSource?: string;
|
|
137
155
|
meta: JourneyMeta;
|
|
156
|
+
consts?: JourneyGraphConsts;
|
|
138
157
|
}): JourneyGraph {
|
|
139
158
|
if (!runSource) return degradedGraphFromMeta(meta);
|
|
140
159
|
try {
|
|
141
|
-
return extract(runSource, meta);
|
|
160
|
+
return extract(runSource, meta, consts);
|
|
142
161
|
} catch {
|
|
143
162
|
return degradedGraphFromMeta(meta);
|
|
144
163
|
}
|
|
@@ -165,7 +184,57 @@ export function degradedGraphFromMeta(meta: JourneyMeta): JourneyGraph {
|
|
|
165
184
|
};
|
|
166
185
|
}
|
|
167
186
|
|
|
168
|
-
|
|
187
|
+
/**
|
|
188
|
+
* Deterministic const-resolution pass: for each raw whose template/event slot
|
|
189
|
+
* is a member-expr IDENTIFIER (`Templates.DOCS_WELCOME` → ident `DOCS_WELCOME`)
|
|
190
|
+
* but has no literal, fill the literal from the matching const map value. Only
|
|
191
|
+
* fills from the ident (never overwrites an existing literal) and only for own,
|
|
192
|
+
* non-empty-string entries — so prototype keys can't leak in. Filling the
|
|
193
|
+
* literal is enough: the node builders already prefer the literal for the id,
|
|
194
|
+
* `meta`, subtitle, and the `unstable` flag, so everything downstream becomes
|
|
195
|
+
* deterministic with no other change.
|
|
196
|
+
*
|
|
197
|
+
* The fill is GATED on the OBJECT qualifier being the conventional const-object
|
|
198
|
+
* name — `Templates` for templates, `Events` for events (the documented
|
|
199
|
+
* consumer convention: CLAUDE.md's `Templates`/`Events` `as const` maps + the
|
|
200
|
+
* create-hogsend scaffold). This prevents a property-name collision — e.g. an
|
|
201
|
+
* unrelated `SomeEnum.SUBMITTED` whose `SUBMITTED` key also lives in the events
|
|
202
|
+
* map but maps to a different value — from confidently resolving to a WRONG
|
|
203
|
+
* literal. An aliased/non-conventional object name degrades gracefully to the
|
|
204
|
+
* pre-fill fallback (positional id / heuristic) instead of risking a wrong value.
|
|
205
|
+
*/
|
|
206
|
+
function resolveRawConsts(raws: Raw[], consts?: JourneyGraphConsts): void {
|
|
207
|
+
if (!consts) return;
|
|
208
|
+
const fill = (
|
|
209
|
+
map: Record<string, string> | undefined,
|
|
210
|
+
ident: string | undefined,
|
|
211
|
+
): string | undefined => {
|
|
212
|
+
if (!map || ident === undefined || !Object.hasOwn(map, ident)) {
|
|
213
|
+
return undefined;
|
|
214
|
+
}
|
|
215
|
+
const value = map[ident];
|
|
216
|
+
return typeof value === "string" && value.length > 0 ? value : undefined;
|
|
217
|
+
};
|
|
218
|
+
for (const raw of raws) {
|
|
219
|
+
if (
|
|
220
|
+
raw.templateLiteral === undefined &&
|
|
221
|
+
raw.templateObject === "Templates"
|
|
222
|
+
) {
|
|
223
|
+
const value = fill(consts.templates, raw.templateIdent);
|
|
224
|
+
if (value !== undefined) raw.templateLiteral = value;
|
|
225
|
+
}
|
|
226
|
+
if (raw.eventLiteral === undefined && raw.eventObject === "Events") {
|
|
227
|
+
const value = fill(consts.events, raw.eventIdent);
|
|
228
|
+
if (value !== undefined) raw.eventLiteral = value;
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
function extract(
|
|
234
|
+
runSource: string,
|
|
235
|
+
meta: JourneyMeta,
|
|
236
|
+
consts?: JourneyGraphConsts,
|
|
237
|
+
): JourneyGraph {
|
|
169
238
|
const wrapped = `(${runSource})`;
|
|
170
239
|
const ast = acorn.parse(wrapped, {
|
|
171
240
|
ecmaVersion: "latest",
|
|
@@ -190,6 +259,11 @@ function extract(runSource: string, meta: JourneyMeta): JourneyGraph {
|
|
|
190
259
|
});
|
|
191
260
|
raws.sort((a, b) => a.start - b.start);
|
|
192
261
|
|
|
262
|
+
// Resolve `Templates.X` / `Events.X` member-expr idents to their real runtime
|
|
263
|
+
// values from the consumer's const maps BEFORE id assignment, so the node
|
|
264
|
+
// builders (which already prefer the literal) mint deterministic ids + meta.
|
|
265
|
+
resolveRawConsts(raws, consts);
|
|
266
|
+
|
|
193
267
|
// --- Pass B: assign ids (A2 join-key rules) ---
|
|
194
268
|
const emitted = assignNodes(raws, meta.trigger.event);
|
|
195
269
|
dedupeIds(emitted);
|
|
@@ -316,6 +390,21 @@ function lastIdentOf(node: Node | undefined): string | undefined {
|
|
|
316
390
|
return undefined;
|
|
317
391
|
}
|
|
318
392
|
|
|
393
|
+
/**
|
|
394
|
+
* The OBJECT identifier of a simple `Object.PROP` member expression
|
|
395
|
+
* (`Templates.DOCS_WELCOME` → "Templates", `Events.NPS_SUBMITTED` → "Events").
|
|
396
|
+
* Returns undefined for anything that isn't `<plain Identifier>.<prop>` —
|
|
397
|
+
* nested member exprs (`Foo.Bar.BAZ`), computed access (`Map[k]`), or a bare
|
|
398
|
+
* identifier. Used to gate const resolution on the CONVENTIONAL object name so a
|
|
399
|
+
* property-name collision on an unrelated enum can't resolve to a wrong value.
|
|
400
|
+
*/
|
|
401
|
+
function objectIdentOf(node: Node | undefined): string | undefined {
|
|
402
|
+
if (!node || node.type !== "MemberExpression" || node.computed) {
|
|
403
|
+
return undefined;
|
|
404
|
+
}
|
|
405
|
+
return node.object.type === "Identifier" ? node.object.name : undefined;
|
|
406
|
+
}
|
|
407
|
+
|
|
319
408
|
function objectProp(
|
|
320
409
|
obj: acorn.ObjectExpression,
|
|
321
410
|
key: string,
|
|
@@ -536,6 +625,7 @@ function ctxNodeFields(
|
|
|
536
625
|
labelUnstable: label?.unstable,
|
|
537
626
|
eventLiteral: stringLiteral(eventNode),
|
|
538
627
|
eventIdent: lastIdentOf(eventNode),
|
|
628
|
+
eventObject: objectIdentOf(eventNode),
|
|
539
629
|
timeout: arg ? extractDuration(objectProp(arg, "timeout")) : undefined,
|
|
540
630
|
};
|
|
541
631
|
}
|
|
@@ -549,6 +639,7 @@ function ctxNodeFields(
|
|
|
549
639
|
labelUnstable: label?.unstable,
|
|
550
640
|
eventLiteral: stringLiteral(eventNode),
|
|
551
641
|
eventIdent: lastIdentOf(eventNode),
|
|
642
|
+
eventObject: objectIdentOf(eventNode),
|
|
552
643
|
duration: arg ? extractDuration(objectProp(arg, "window")) : undefined,
|
|
553
644
|
};
|
|
554
645
|
}
|
|
@@ -558,6 +649,7 @@ function ctxNodeFields(
|
|
|
558
649
|
kind,
|
|
559
650
|
eventLiteral: stringLiteral(eventNode),
|
|
560
651
|
eventIdent: lastIdentOf(eventNode),
|
|
652
|
+
eventObject: objectIdentOf(eventNode),
|
|
561
653
|
};
|
|
562
654
|
}
|
|
563
655
|
|
|
@@ -568,6 +660,7 @@ function sendFields(arg: acorn.ObjectExpression): ClassifiedFields {
|
|
|
568
660
|
kind: "send",
|
|
569
661
|
templateLiteral: stringLiteral(templateNode),
|
|
570
662
|
templateIdent: lastIdentOf(templateNode),
|
|
663
|
+
templateObject: objectIdentOf(templateNode),
|
|
571
664
|
// Only a literal idempotencyLabel is a stable id "site".
|
|
572
665
|
idempotencyLabel: idem && !idem.unstable ? idem.value : undefined,
|
|
573
666
|
};
|
|
@@ -2,11 +2,13 @@ import type { AnalyticsProvider } from "@hogsend/core";
|
|
|
2
2
|
import type { Database } from "@hogsend/db";
|
|
3
3
|
import {
|
|
4
4
|
createPostHogProvider,
|
|
5
|
+
deriveIngestHost,
|
|
5
6
|
type PostHogAuthTokenAccessor,
|
|
6
7
|
} from "@hogsend/plugin-posthog";
|
|
7
8
|
import type { env as envSchema } from "../env.js";
|
|
8
9
|
import type { Logger } from "./logger.js";
|
|
9
10
|
import { createTokenManager } from "./oauth-token-manager.js";
|
|
11
|
+
import { getDerivedCredential } from "./provider-credentials.js";
|
|
10
12
|
import { getRedis } from "./redis.js";
|
|
11
13
|
|
|
12
14
|
/**
|
|
@@ -28,52 +30,113 @@ export function analyticsProvidersFromEnv(
|
|
|
28
30
|
const providers: AnalyticsProvider[] = [];
|
|
29
31
|
|
|
30
32
|
if (env.POSTHOG_API_KEY) {
|
|
31
|
-
// Token-manager-backed accessor: the manager re-checks the DB (30s
|
|
32
|
-
// negative cache), so a credential stored at RUNTIME via
|
|
33
|
-
// `hogsend connect posthog` comes alive without a restart.
|
|
34
|
-
let authToken: PostHogAuthTokenAccessor | undefined;
|
|
35
|
-
if (deps?.db) {
|
|
36
|
-
const tokenManager = createTokenManager({
|
|
37
|
-
db: deps.db,
|
|
38
|
-
providerId: "posthog",
|
|
39
|
-
logger: deps.logger,
|
|
40
|
-
});
|
|
41
|
-
// Load-only warm-up (no refresh, never blocks construction). The
|
|
42
|
-
// person-reads nudge logs HERE, after the load settles — the container
|
|
43
|
-
// can't log it truthfully at boot because capabilities resolve async
|
|
44
|
-
// for OAuth-capable providers (a connected instance would otherwise
|
|
45
|
-
// log "DISABLED" once on every boot).
|
|
46
|
-
const personalKeySet = Boolean(env.POSTHOG_PERSONAL_API_KEY);
|
|
47
|
-
void tokenManager
|
|
48
|
-
.prime()
|
|
49
|
-
.then(() => {
|
|
50
|
-
if (!personalKeySet && tokenManager.credentialState() !== "present") {
|
|
51
|
-
deps.logger?.info(
|
|
52
|
-
'analytics provider "posthog" has person reads DISABLED — ' +
|
|
53
|
-
"timezone resolution falls back to contact properties. Set " +
|
|
54
|
-
"POSTHOG_PERSONAL_API_KEY or run `hogsend connect posthog`. " +
|
|
55
|
-
"Docs: https://hogsend.com/docs/guides/analytics-access",
|
|
56
|
-
);
|
|
57
|
-
}
|
|
58
|
-
})
|
|
59
|
-
.catch(() => {});
|
|
60
|
-
authToken = {
|
|
61
|
-
getToken: () => tokenManager.getAccessToken(),
|
|
62
|
-
isAvailable: () => tokenManager.credentialState() === "present",
|
|
63
|
-
};
|
|
64
|
-
}
|
|
65
33
|
providers.push(
|
|
66
|
-
|
|
67
|
-
apiKey: env.POSTHOG_API_KEY,
|
|
68
|
-
host: env.POSTHOG_HOST,
|
|
69
|
-
personalApiKey: env.POSTHOG_PERSONAL_API_KEY,
|
|
70
|
-
projectId: env.POSTHOG_PROJECT_ID,
|
|
71
|
-
privateHost: env.POSTHOG_PRIVATE_HOST,
|
|
72
|
-
redis: getRedis(),
|
|
73
|
-
authToken,
|
|
74
|
-
}),
|
|
34
|
+
buildPosthogProvider(env, deps, { apiKey: env.POSTHOG_API_KEY }),
|
|
75
35
|
);
|
|
76
36
|
}
|
|
77
37
|
|
|
78
38
|
return providers;
|
|
79
39
|
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Construct the PostHog provider with the token-manager-backed OAuth accessor.
|
|
43
|
+
* Shared by the env preset above (`POSTHOG_API_KEY`) and the stored-credential
|
|
44
|
+
* activation below (`hogsend connect posthog`'s persisted phc_). Env values
|
|
45
|
+
* win over `source` overrides so a hand-set var still takes precedence.
|
|
46
|
+
*/
|
|
47
|
+
function buildPosthogProvider(
|
|
48
|
+
env: typeof envSchema,
|
|
49
|
+
deps: { db?: Database; logger?: Logger } | undefined,
|
|
50
|
+
source: {
|
|
51
|
+
apiKey: string;
|
|
52
|
+
host?: string;
|
|
53
|
+
projectId?: string;
|
|
54
|
+
privateHost?: string;
|
|
55
|
+
},
|
|
56
|
+
): AnalyticsProvider {
|
|
57
|
+
// Token-manager-backed accessor: the manager re-checks the DB (30s
|
|
58
|
+
// negative cache), so a credential stored at RUNTIME via
|
|
59
|
+
// `hogsend connect posthog` comes alive without a restart.
|
|
60
|
+
let authToken: PostHogAuthTokenAccessor | undefined;
|
|
61
|
+
if (deps?.db) {
|
|
62
|
+
const tokenManager = createTokenManager({
|
|
63
|
+
db: deps.db,
|
|
64
|
+
providerId: "posthog",
|
|
65
|
+
logger: deps.logger,
|
|
66
|
+
});
|
|
67
|
+
// Load-only warm-up (no refresh, never blocks construction). The
|
|
68
|
+
// person-reads nudge logs HERE, after the load settles — the container
|
|
69
|
+
// can't log it truthfully at boot because capabilities resolve async
|
|
70
|
+
// for OAuth-capable providers (a connected instance would otherwise
|
|
71
|
+
// log "DISABLED" once on every boot).
|
|
72
|
+
const personalKeySet = Boolean(env.POSTHOG_PERSONAL_API_KEY);
|
|
73
|
+
void tokenManager
|
|
74
|
+
.prime()
|
|
75
|
+
.then(() => {
|
|
76
|
+
if (!personalKeySet && tokenManager.credentialState() !== "present") {
|
|
77
|
+
deps.logger?.info(
|
|
78
|
+
'analytics provider "posthog" has person reads DISABLED — ' +
|
|
79
|
+
"timezone resolution falls back to contact properties. Set " +
|
|
80
|
+
"POSTHOG_PERSONAL_API_KEY or run `hogsend connect posthog`. " +
|
|
81
|
+
"Docs: https://hogsend.com/docs/guides/analytics-access",
|
|
82
|
+
);
|
|
83
|
+
}
|
|
84
|
+
})
|
|
85
|
+
.catch(() => {});
|
|
86
|
+
authToken = {
|
|
87
|
+
getToken: () => tokenManager.getAccessToken(),
|
|
88
|
+
isAvailable: () => tokenManager.credentialState() === "present",
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
return createPostHogProvider({
|
|
92
|
+
apiKey: source.apiKey,
|
|
93
|
+
host: env.POSTHOG_HOST ?? source.host,
|
|
94
|
+
personalApiKey: env.POSTHOG_PERSONAL_API_KEY,
|
|
95
|
+
projectId: env.POSTHOG_PROJECT_ID ?? source.projectId,
|
|
96
|
+
privateHost: env.POSTHOG_PRIVATE_HOST ?? source.privateHost,
|
|
97
|
+
redis: getRedis(),
|
|
98
|
+
authToken,
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Boot-time reader for the phc_ persisted by `hogsend connect posthog`
|
|
104
|
+
* (provider_credentials kind="derived", `projectApiKey`): a PURE builder —
|
|
105
|
+
* reads the stored credential and constructs the PostHog provider from it, or
|
|
106
|
+
* resolves null when there is nothing stored (or it can't be decrypted, which
|
|
107
|
+
* must behave exactly like "unconfigured"). ALL activation side effects
|
|
108
|
+
* (registry, `client.analytics`, the module singleton, identity rebind) live
|
|
109
|
+
* at the single call site in `container.ts`. Without this reader the
|
|
110
|
+
* persisted key is dead weight and outbound capture silently keeps requiring
|
|
111
|
+
* a hand-pasted env var.
|
|
112
|
+
*
|
|
113
|
+
* The capture host resolves env-first, then the ingestion host derived from
|
|
114
|
+
* the stored PRIVATE host (`eu.posthog.com` → `eu.i.posthog.com`) so an
|
|
115
|
+
* EU-connected instance never captures to the US default.
|
|
116
|
+
*/
|
|
117
|
+
export async function buildStoredPosthogProvider(opts: {
|
|
118
|
+
env: typeof envSchema;
|
|
119
|
+
db: Database;
|
|
120
|
+
logger: Logger;
|
|
121
|
+
}): Promise<AnalyticsProvider | null> {
|
|
122
|
+
let derived: Awaited<ReturnType<typeof getDerivedCredential>>;
|
|
123
|
+
try {
|
|
124
|
+
derived = await getDerivedCredential(opts.db, "posthog");
|
|
125
|
+
} catch {
|
|
126
|
+
return null;
|
|
127
|
+
}
|
|
128
|
+
if (!derived?.projectApiKey) return null;
|
|
129
|
+
|
|
130
|
+
return buildPosthogProvider(
|
|
131
|
+
opts.env,
|
|
132
|
+
{ db: opts.db, logger: opts.logger },
|
|
133
|
+
{
|
|
134
|
+
apiKey: derived.projectApiKey,
|
|
135
|
+
projectId: derived.projectId,
|
|
136
|
+
privateHost: derived.privateHost,
|
|
137
|
+
host: derived.privateHost
|
|
138
|
+
? deriveIngestHost(derived.privateHost)
|
|
139
|
+
: undefined,
|
|
140
|
+
},
|
|
141
|
+
);
|
|
142
|
+
}
|
|
@@ -5,12 +5,14 @@
|
|
|
5
5
|
* so future read/write features activate without forcing a reconnect. Every
|
|
6
6
|
* name is validated against PostHog's published `scopes_supported`.
|
|
7
7
|
*
|
|
8
|
-
* LOCKSTEP (3 places
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
8
|
+
* LOCKSTEP (3 places): this constant, the CLI's `POSTHOG_SCOPES`
|
|
9
|
+
* (`packages/cli/src/lib/oauth.ts` — the CLI avoids the engine ROOT import
|
|
10
|
+
* because the barrel does import-time env validation, but this module is
|
|
11
|
+
* dependency-free and exported as the `@hogsend/engine/posthog-scopes`
|
|
12
|
+
* subpath), and the `scope` field of the hosted CIMD document
|
|
13
|
+
* (`apps/docs/public/.well-known/hogsend-posthog-client.json`) — that one is
|
|
14
|
+
* genuinely un-importable. PostHog gates the scopes it will grant by the CIMD
|
|
15
|
+
* doc, so grep all three and keep them identical before changing any of them.
|
|
14
16
|
*/
|
|
15
17
|
export const EXPECTED_POSTHOG_SCOPES: string[] = [
|
|
16
18
|
"person:read",
|
|
@@ -27,3 +29,25 @@ export const EXPECTED_POSTHOG_SCOPES: string[] = [
|
|
|
27
29
|
"event_definition:read",
|
|
28
30
|
"property_definition:read",
|
|
29
31
|
];
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* PostHog's scope model is hierarchical — `X:write` implies `X:read` — and
|
|
35
|
+
* the grant NORMALIZES a request for both halves down to `X:write` alone. A
|
|
36
|
+
* literal set-difference against the requested list therefore reports the
|
|
37
|
+
* implied `:read` halves as "missing" on every fully-successful consent
|
|
38
|
+
* (e.g. person:read, hog_function:read, cohort:read). Treat a requested
|
|
39
|
+
* `X:read` as satisfied when the grant carries `X:write`.
|
|
40
|
+
*
|
|
41
|
+
* The CLI imports this via the `@hogsend/engine/posthog-scopes` subpath —
|
|
42
|
+
* single implementation, no mirror.
|
|
43
|
+
*/
|
|
44
|
+
export function posthogScopeSatisfied(
|
|
45
|
+
granted: string[],
|
|
46
|
+
scope: string,
|
|
47
|
+
): boolean {
|
|
48
|
+
return (
|
|
49
|
+
granted.includes(scope) ||
|
|
50
|
+
(scope.endsWith(":read") &&
|
|
51
|
+
granted.includes(scope.replace(/:read$/, ":write")))
|
|
52
|
+
);
|
|
53
|
+
}
|
|
@@ -46,8 +46,21 @@ export interface ProvisionPostHogLoopOptions {
|
|
|
46
46
|
logger: Logger;
|
|
47
47
|
/** Display name for a NEWLY created function. Default: MANAGED_NAME. */
|
|
48
48
|
name?: string;
|
|
49
|
+
/**
|
|
50
|
+
* Placeholder mode (local instances PostHog can't reach): provision the
|
|
51
|
+
* destination DISABLED, pointing at the obvious stand-in
|
|
52
|
+
* `https://CHANGEME.yourdomain.com/...` instead of `apiPublicUrl`. The
|
|
53
|
+
* destination then EXISTS in PostHog — name, filters, secret header, all
|
|
54
|
+
* inspectable — with zero failed deliveries. Going live after deploy is one
|
|
55
|
+
* re-run WITHOUT this flag (`--provision-only --url https://real`): the
|
|
56
|
+
* reconciler swaps the URL and re-enables in a single PATCH.
|
|
57
|
+
*/
|
|
58
|
+
placeholder?: boolean;
|
|
49
59
|
}
|
|
50
60
|
|
|
61
|
+
/** The stand-in base URL placeholder mode provisions against. */
|
|
62
|
+
export const PLACEHOLDER_PUBLIC_URL = "https://CHANGEME.yourdomain.com";
|
|
63
|
+
|
|
51
64
|
export interface ProvisionPostHogLoopResult {
|
|
52
65
|
action: "created" | "updated" | "unchanged";
|
|
53
66
|
/** Hog function UUID. */
|
|
@@ -64,6 +77,8 @@ export interface ProvisionPostHogLoopResult {
|
|
|
64
77
|
projectApiKey?: string;
|
|
65
78
|
/** Best-effort deep link (pattern unverified — cosmetic, confirm in e2e). */
|
|
66
79
|
dashboardUrl: string;
|
|
80
|
+
/** false ⇒ placeholder mode: disabled destination, CHANGEME URL. */
|
|
81
|
+
enabled: boolean;
|
|
67
82
|
}
|
|
68
83
|
|
|
69
84
|
export type ProvisionPostHogLoopErrorCode =
|
|
@@ -243,6 +258,8 @@ interface HogFunctionDetail {
|
|
|
243
258
|
interface DesiredLoop {
|
|
244
259
|
webhookUrl: string;
|
|
245
260
|
webhookSecret: string;
|
|
261
|
+
/** false only in placeholder mode — see ProvisionPostHogLoopOptions. */
|
|
262
|
+
enabled: boolean;
|
|
246
263
|
}
|
|
247
264
|
|
|
248
265
|
/**
|
|
@@ -266,7 +283,11 @@ export async function provisionPostHogLoop(
|
|
|
266
283
|
});
|
|
267
284
|
}
|
|
268
285
|
|
|
269
|
-
const
|
|
286
|
+
const placeholder = opts.placeholder === true;
|
|
287
|
+
const webhookUrl = joinUrl(
|
|
288
|
+
placeholder ? PLACEHOLDER_PUBLIC_URL : apiPublicUrl,
|
|
289
|
+
HOGSEND_LOOP_PATH,
|
|
290
|
+
);
|
|
270
291
|
const hostname = tryParseUrl(webhookUrl)?.hostname;
|
|
271
292
|
if (hostname === "localhost" || hostname === "127.0.0.1") {
|
|
272
293
|
logger.warn(
|
|
@@ -282,7 +303,11 @@ export async function provisionPostHogLoop(
|
|
|
282
303
|
});
|
|
283
304
|
|
|
284
305
|
const basePath = `/api/environments/${projectId}/hog_functions/`;
|
|
285
|
-
const desired: DesiredLoop = {
|
|
306
|
+
const desired: DesiredLoop = {
|
|
307
|
+
webhookUrl,
|
|
308
|
+
webhookSecret,
|
|
309
|
+
enabled: !placeholder,
|
|
310
|
+
};
|
|
286
311
|
|
|
287
312
|
const found = await findLoopFunction({ privateHost, accessToken, basePath });
|
|
288
313
|
|
|
@@ -339,6 +364,7 @@ export async function provisionPostHogLoop(
|
|
|
339
364
|
dashboardUrl:
|
|
340
365
|
`${privateHost.replace(/\/+$/, "")}/project/${projectId}` +
|
|
341
366
|
`/pipeline/destinations/hog-${functionId}/configuration`,
|
|
367
|
+
enabled: desired.enabled,
|
|
342
368
|
};
|
|
343
369
|
}
|
|
344
370
|
|
|
@@ -562,7 +588,7 @@ async function findLoopFunction(opts: {
|
|
|
562
588
|
|
|
563
589
|
/** true ⇒ no PATCH needed. */
|
|
564
590
|
function isCompliant(fn: HogFunctionDetail, desired: DesiredLoop): boolean {
|
|
565
|
-
if (fn.enabled !==
|
|
591
|
+
if (fn.enabled !== desired.enabled) return false;
|
|
566
592
|
if (inputValue(fn.inputs, "url") !== desired.webhookUrl) return false;
|
|
567
593
|
if (inputValue(fn.inputs, "method") !== "POST") return false;
|
|
568
594
|
if (!deepEquals(inputValue(fn.inputs, "body"), CANONICAL_BODY)) return false;
|
|
@@ -614,7 +640,7 @@ function buildCreatePayload(
|
|
|
614
640
|
name: name ?? MANAGED_NAME,
|
|
615
641
|
description: MANAGED_DESCRIPTION,
|
|
616
642
|
template_id: "template-webhook",
|
|
617
|
-
enabled:
|
|
643
|
+
enabled: desired.enabled,
|
|
618
644
|
inputs: {
|
|
619
645
|
url: { value: desired.webhookUrl },
|
|
620
646
|
method: { value: "POST" },
|
|
@@ -636,11 +662,12 @@ function buildCreatePayload(
|
|
|
636
662
|
|
|
637
663
|
/**
|
|
638
664
|
* Reconciled PATCH body: enforce what we manage, preserve the rest.
|
|
639
|
-
* `enabled
|
|
640
|
-
* re-enabling a paused loop is the expected
|
|
641
|
-
*
|
|
642
|
-
*
|
|
643
|
-
*
|
|
665
|
+
* `enabled` follows `desired` — true on a real provision (connect is an
|
|
666
|
+
* explicit operator action, so re-enabling a paused loop is the expected
|
|
667
|
+
* outcome), false in placeholder mode (a CHANGEME URL must never receive
|
|
668
|
+
* deliveries). PostHog replaces `inputs` WHOLESALE on PATCH (verified), so
|
|
669
|
+
* all five keys are always sent. `name`/`description` are never touched on
|
|
670
|
+
* adopt — the operator may have renamed deliberately.
|
|
644
671
|
*/
|
|
645
672
|
function buildUpdatePayload(
|
|
646
673
|
fn: HogFunctionDetail,
|
|
@@ -665,7 +692,7 @@ function buildUpdatePayload(
|
|
|
665
692
|
filters.properties = properties;
|
|
666
693
|
|
|
667
694
|
const payload: Record<string, unknown> = {
|
|
668
|
-
enabled:
|
|
695
|
+
enabled: desired.enabled,
|
|
669
696
|
inputs: {
|
|
670
697
|
url: { value: desired.webhookUrl },
|
|
671
698
|
method: { value: "POST" },
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { defineEmailProvider } from "@hogsend/core";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The inert email provider a container boots with when NO provider is
|
|
5
|
+
* configured and none was explicitly requested (mirrors the SMS channel's
|
|
6
|
+
* operator-opt-in posture: unconfigured ⇒ inert stub, not a boot crash).
|
|
7
|
+
*
|
|
8
|
+
* A fresh scaffold has no RESEND_API_KEY yet — it should still boot, serve
|
|
9
|
+
* Studio, ingest events and run non-email journeys. Every email send fails
|
|
10
|
+
* per-call with this actionable message instead; the container logs one boot
|
|
11
|
+
* warning. Never registered in the provider registry, so no webhook route
|
|
12
|
+
* resolves it.
|
|
13
|
+
*
|
|
14
|
+
* DELIBERATE seam choice (vs SMS's service-level stub): the stub is the WIRE
|
|
15
|
+
* inside the real tracked mailer, so an unconfigured send still runs the
|
|
16
|
+
* pipeline (preferences → render → tracking → `email_sends` write) and fails
|
|
17
|
+
* at dispatch — leaving a failed-send row visible in Studio, which is exactly
|
|
18
|
+
* the operator-facing breadcrumb a "why didn't my email go out?" moment needs.
|
|
19
|
+
*/
|
|
20
|
+
export const UNCONFIGURED_EMAIL_MESSAGE =
|
|
21
|
+
"no email provider configured — set RESEND_API_KEY (or POSTMARK_SERVER_TOKEN " +
|
|
22
|
+
"with EMAIL_PROVIDER=postmark), or pass `email: { provider }` to " +
|
|
23
|
+
"createHogsendClient().";
|
|
24
|
+
|
|
25
|
+
export function createUnconfiguredEmailProvider() {
|
|
26
|
+
return defineEmailProvider({
|
|
27
|
+
meta: {
|
|
28
|
+
id: "unconfigured",
|
|
29
|
+
name: "No email provider configured",
|
|
30
|
+
},
|
|
31
|
+
capabilities: {},
|
|
32
|
+
async send() {
|
|
33
|
+
throw new Error(UNCONFIGURED_EMAIL_MESSAGE);
|
|
34
|
+
},
|
|
35
|
+
async sendBatch() {
|
|
36
|
+
throw new Error(UNCONFIGURED_EMAIL_MESSAGE);
|
|
37
|
+
},
|
|
38
|
+
verifyWebhook() {
|
|
39
|
+
throw new Error(UNCONFIGURED_EMAIL_MESSAGE);
|
|
40
|
+
},
|
|
41
|
+
parseWebhook() {
|
|
42
|
+
throw new Error(UNCONFIGURED_EMAIL_MESSAGE);
|
|
43
|
+
},
|
|
44
|
+
});
|
|
45
|
+
}
|
|
@@ -3,7 +3,10 @@ import { DEFAULT_HOST, derivePrivateHost } from "@hogsend/plugin-posthog";
|
|
|
3
3
|
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
4
4
|
import type { AppEnv } from "../../app.js";
|
|
5
5
|
import { createTokenManager } from "../../lib/oauth-token-manager.js";
|
|
6
|
-
import {
|
|
6
|
+
import {
|
|
7
|
+
EXPECTED_POSTHOG_SCOPES,
|
|
8
|
+
posthogScopeSatisfied,
|
|
9
|
+
} from "../../lib/posthog-scopes.js";
|
|
7
10
|
import {
|
|
8
11
|
getDerivedCredential,
|
|
9
12
|
getProviderCredential,
|
|
@@ -120,6 +123,8 @@ const provisionLoopResponseSchema = z.object({
|
|
|
120
123
|
hogFunctionId: z.string(),
|
|
121
124
|
webhookUrl: z.string(),
|
|
122
125
|
dashboardUrl: z.string(),
|
|
126
|
+
/** false ⇒ placeholder mode: destination is DISABLED with a CHANGEME URL. */
|
|
127
|
+
enabled: z.boolean(),
|
|
123
128
|
});
|
|
124
129
|
|
|
125
130
|
const provisionFailureSchema = z.object({
|
|
@@ -154,6 +159,12 @@ const provisionLoopRoute = createRoute({
|
|
|
154
159
|
path: "/provision-loop",
|
|
155
160
|
tags: ["Admin — Analytics"],
|
|
156
161
|
summary: "Provision the PostHog → Hogsend event loop (webhook destination)",
|
|
162
|
+
request: {
|
|
163
|
+
// `?placeholder=true` — pre-create the destination DISABLED with the
|
|
164
|
+
// CHANGEME stand-in URL (for local instances PostHog can't reach). A
|
|
165
|
+
// query param (not a body) keeps older CLIs' bare POST byte-compatible.
|
|
166
|
+
query: z.object({ placeholder: z.enum(["true", "false"]).optional() }),
|
|
167
|
+
},
|
|
157
168
|
responses: {
|
|
158
169
|
200: {
|
|
159
170
|
content: {
|
|
@@ -202,8 +213,12 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
|
|
|
202
213
|
try {
|
|
203
214
|
const oauth = await getProviderCredential(db, "posthog");
|
|
204
215
|
if (oauth) {
|
|
216
|
+
// Hierarchical scopes: a granted `X:write` satisfies `X:read` (the
|
|
217
|
+
// grant normalizes both-halves requests down to write-only).
|
|
205
218
|
const granted = oauth.payload.scopes;
|
|
206
|
-
scopeGap = EXPECTED_POSTHOG_SCOPES.filter(
|
|
219
|
+
scopeGap = EXPECTED_POSTHOG_SCOPES.filter(
|
|
220
|
+
(s) => !posthogScopeSatisfied(granted, s),
|
|
221
|
+
);
|
|
207
222
|
}
|
|
208
223
|
} catch {
|
|
209
224
|
scopeGap = [];
|
|
@@ -217,6 +232,7 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
|
|
|
217
232
|
.openapi(provisionLoopRoute, async (c) => {
|
|
218
233
|
const { db, env, logger } = c.get("container");
|
|
219
234
|
const info = resolveConnectInfo(env);
|
|
235
|
+
const placeholder = c.req.valid("query").placeholder === "true";
|
|
220
236
|
|
|
221
237
|
// Credential check FIRST (M3), secret refusal second (enforced by the
|
|
222
238
|
// provisioner itself). The container does NOT expose the token manager
|
|
@@ -245,7 +261,9 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
|
|
|
245
261
|
// PostHog Cloud cannot deliver webhooks to a loopback address — and a
|
|
246
262
|
// local instance with a misconfigured API_PUBLIC_URL must never repoint
|
|
247
263
|
// a production destination at localhost. Refuse BEFORE any PostHog call.
|
|
248
|
-
|
|
264
|
+
// Placeholder mode is exempt: it never uses apiPublicUrl (the destination
|
|
265
|
+
// is created DISABLED against the CHANGEME stand-in URL).
|
|
266
|
+
if (!placeholder && isLoopbackPublicUrl(info.apiPublicUrl)) {
|
|
249
267
|
return c.json(
|
|
250
268
|
{
|
|
251
269
|
error: "api_public_url_unreachable",
|
|
@@ -290,12 +308,15 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
|
|
|
290
308
|
apiPublicUrl: info.apiPublicUrl,
|
|
291
309
|
webhookSecret,
|
|
292
310
|
logger,
|
|
311
|
+
placeholder,
|
|
293
312
|
});
|
|
294
313
|
|
|
295
314
|
// Opportunistically persist the phc_ (project api_token) the provisioner
|
|
296
|
-
// read on its way through — it powers the OPTIONAL outbound capture path
|
|
297
|
-
//
|
|
298
|
-
//
|
|
315
|
+
// read on its way through — it powers the OPTIONAL outbound capture path.
|
|
316
|
+
// `activateStoredPosthogAnalytics` (container boot) reads it back, so
|
|
317
|
+
// capture comes alive on the next boot with NO hand-pasted
|
|
318
|
+
// POSTHOG_API_KEY. Re-read the stored payload to merge over the
|
|
319
|
+
// just-persisted webhook secret.
|
|
299
320
|
if (result.projectApiKey) {
|
|
300
321
|
const cur = (await getDerivedCredential(db, "posthog")) ?? {};
|
|
301
322
|
await saveDerivedCredential(db, "posthog", {
|
|
@@ -316,6 +337,7 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
|
|
|
316
337
|
hogFunctionId: result.functionId,
|
|
317
338
|
webhookUrl: result.webhookUrl,
|
|
318
339
|
dashboardUrl: result.dashboardUrl,
|
|
340
|
+
enabled: result.enabled,
|
|
319
341
|
},
|
|
320
342
|
200,
|
|
321
343
|
);
|
|
@@ -2,6 +2,7 @@ import { contacts, userEvents } from "@hogsend/db";
|
|
|
2
2
|
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
3
3
|
import { and, count, desc, eq, gte, isNull, lte, or, sql } from "drizzle-orm";
|
|
4
4
|
import type { AppEnv } from "../../app.js";
|
|
5
|
+
import type { HogsendClient } from "../../container.js";
|
|
5
6
|
import {
|
|
6
7
|
eventNameEntrySchema,
|
|
7
8
|
listEventNameVocabulary,
|
|
@@ -16,8 +17,8 @@ const eventSchema = z.object({
|
|
|
16
17
|
occurredAt: z.string(),
|
|
17
18
|
// Where the event entered the pipeline ("posthog", "api", "studio", …).
|
|
18
19
|
source: z.string().nullable(),
|
|
19
|
-
// Resolved from
|
|
20
|
-
//
|
|
20
|
+
// Resolved from THE live contact whose key (externalId, anonymousId, or
|
|
21
|
+
// id) matches user_events.userId — shows WHO an event is from.
|
|
21
22
|
userEmail: z.string().nullable(),
|
|
22
23
|
contactId: z.string().nullable(),
|
|
23
24
|
});
|
|
@@ -45,21 +46,36 @@ function serializeEvent(row: JoinedEvent) {
|
|
|
45
46
|
}
|
|
46
47
|
|
|
47
48
|
/**
|
|
48
|
-
*
|
|
49
|
-
* resolved canonical key (`external_id ?? anonymous_id ?? id`), so
|
|
50
|
-
* three — covering email-only/anonymous contacts, not just
|
|
51
|
-
* ones. Each
|
|
52
|
-
*
|
|
49
|
+
* LATERAL pick of THE live contact for an event's userId. `userEvents.userId`
|
|
50
|
+
* holds the resolved canonical key (`external_id ?? anonymous_id ?? id`), so
|
|
51
|
+
* match all three — covering email-only/anonymous contacts, not just
|
|
52
|
+
* externalId-keyed ones. Each column is partial-unique among live rows, but
|
|
53
|
+
* the three namespaces are NOT guaranteed disjoint across contacts: a
|
|
54
|
+
* mis-keyed emitter can park one contact's key in another contact's
|
|
55
|
+
* anonymous_id, and a bare OR-join then matches BOTH — fanning every event
|
|
56
|
+
* out into one display row per matching contact. The lateral picks exactly
|
|
57
|
+
* one, by the same precedence ingest resolves keys with.
|
|
53
58
|
*/
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
)
|
|
62
|
-
|
|
59
|
+
function liveContactFor(db: HogsendClient["db"]) {
|
|
60
|
+
return db
|
|
61
|
+
.select({ id: contacts.id, email: contacts.email })
|
|
62
|
+
.from(contacts)
|
|
63
|
+
.where(
|
|
64
|
+
and(
|
|
65
|
+
or(
|
|
66
|
+
eq(contacts.externalId, userEvents.userId),
|
|
67
|
+
eq(contacts.anonymousId, userEvents.userId),
|
|
68
|
+
eq(sql`${contacts.id}::text`, userEvents.userId),
|
|
69
|
+
),
|
|
70
|
+
isNull(contacts.deletedAt),
|
|
71
|
+
),
|
|
72
|
+
)
|
|
73
|
+
.orderBy(
|
|
74
|
+
sql`case when ${contacts.externalId} = ${userEvents.userId} then 0 when ${contacts.anonymousId} = ${userEvents.userId} then 1 else 2 end`,
|
|
75
|
+
)
|
|
76
|
+
.limit(1)
|
|
77
|
+
.as("live_contact");
|
|
78
|
+
}
|
|
63
79
|
|
|
64
80
|
const listRoute = createRoute({
|
|
65
81
|
method: "get",
|
|
@@ -234,11 +250,15 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
|
|
|
234
250
|
|
|
235
251
|
const where = conditions.length > 0 ? and(...conditions) : undefined;
|
|
236
252
|
|
|
253
|
+
const liveContact = liveContactFor(db);
|
|
237
254
|
const [rows, totalRows] = await Promise.all([
|
|
238
255
|
db
|
|
239
|
-
.select({
|
|
256
|
+
.select({
|
|
257
|
+
event: userEvents,
|
|
258
|
+
contact: { id: liveContact.id, email: liveContact.email },
|
|
259
|
+
})
|
|
240
260
|
.from(userEvents)
|
|
241
|
-
.
|
|
261
|
+
.leftJoinLateral(liveContact, sql`true`)
|
|
242
262
|
.where(where)
|
|
243
263
|
.orderBy(desc(userEvents.occurredAt))
|
|
244
264
|
.limit(limit)
|
|
@@ -276,10 +296,14 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
|
|
|
276
296
|
const { db } = c.get("container");
|
|
277
297
|
const { id } = c.req.valid("param");
|
|
278
298
|
|
|
299
|
+
const liveContact = liveContactFor(db);
|
|
279
300
|
const rows = await db
|
|
280
|
-
.select({
|
|
301
|
+
.select({
|
|
302
|
+
event: userEvents,
|
|
303
|
+
contact: { id: liveContact.id, email: liveContact.email },
|
|
304
|
+
})
|
|
281
305
|
.from(userEvents)
|
|
282
|
-
.
|
|
306
|
+
.leftJoinLateral(liveContact, sql`true`)
|
|
283
307
|
.where(eq(userEvents.id, id))
|
|
284
308
|
.limit(1);
|
|
285
309
|
|
|
@@ -1,4 +1,8 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import {
|
|
2
|
+
type JourneyGraph,
|
|
3
|
+
journeyGraphSchema,
|
|
4
|
+
resolveTemplateKeyFromConst,
|
|
5
|
+
} from "@hogsend/core";
|
|
2
6
|
import {
|
|
3
7
|
type Database,
|
|
4
8
|
emailSends,
|
|
@@ -900,8 +904,14 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
|
|
|
900
904
|
);
|
|
901
905
|
})
|
|
902
906
|
.openapi(graphRoute, async (c) => {
|
|
903
|
-
const {
|
|
904
|
-
|
|
907
|
+
const {
|
|
908
|
+
db,
|
|
909
|
+
registry,
|
|
910
|
+
journeySources,
|
|
911
|
+
journeySourceLocations,
|
|
912
|
+
journeyConstants,
|
|
913
|
+
templates,
|
|
914
|
+
} = c.get("container");
|
|
905
915
|
const { id } = c.req.valid("param");
|
|
906
916
|
|
|
907
917
|
const meta = registry.get(id);
|
|
@@ -914,7 +924,11 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
|
|
|
914
924
|
// call-site (also static per process) is baked into the cached graph.
|
|
915
925
|
let graph = journeyGraphCache.get(id);
|
|
916
926
|
if (!graph) {
|
|
917
|
-
graph = buildJourneyGraph({
|
|
927
|
+
graph = buildJourneyGraph({
|
|
928
|
+
runSource: journeySources.get(id),
|
|
929
|
+
meta,
|
|
930
|
+
consts: journeyConstants,
|
|
931
|
+
});
|
|
918
932
|
const source = journeySourceLocations.get(id);
|
|
919
933
|
if (source) graph.source = source;
|
|
920
934
|
journeyGraphCache.set(id, graph);
|
|
@@ -972,13 +986,13 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
|
|
|
972
986
|
// the React Email component — no send data), so STATIC resolution is the
|
|
973
987
|
// primary mechanism and a never-sent journey still previews. Priority:
|
|
974
988
|
// (1) literal `meta.template` — already the registry key.
|
|
975
|
-
// (2) STATIC
|
|
976
|
-
// member-expr sends
|
|
977
|
-
// (`
|
|
978
|
-
//
|
|
979
|
-
//
|
|
980
|
-
//
|
|
981
|
-
//
|
|
989
|
+
// (2) STATIC segment match (`resolveTemplateKeyFromConst`): the node's
|
|
990
|
+
// `subtitle` is the Templates const name for member-expr sends
|
|
991
|
+
// (`FEEDBACK_NPS_SURVEY`, `DOCS_WELCOME`). Split it and each registry
|
|
992
|
+
// key on any of `/ _ -` and compare SEGMENTS, so slash-namespaced keys
|
|
993
|
+
// (`docs/welcome`) resolve too — else the unique longest segment-prefix
|
|
994
|
+
// key (`activation-nudge-series` → `activation-nudge`). Ambiguous ties
|
|
995
|
+
// stay unresolved — a wrong preview is worse than none.
|
|
982
996
|
// (3) journey_logs rows (action='send') whose `to_node_id` is this send
|
|
983
997
|
// node's site id (`send:<site>`), reading `detail.template` — site-
|
|
984
998
|
// keyed, so two sends of one template on different branches stay
|
|
@@ -1010,31 +1024,12 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
|
|
|
1010
1024
|
}
|
|
1011
1025
|
|
|
1012
1026
|
// (2/2b) static const-name → registry key (no runtime data needed):
|
|
1013
|
-
//
|
|
1027
|
+
// separator-agnostic SEGMENT match, so slash-namespaced keys
|
|
1028
|
+
// (`docs/welcome`) resolve from `DOCS_WELCOME` just as hyphen ones do.
|
|
1014
1029
|
const registryKeys = getTemplateNames(templates) as string[];
|
|
1015
|
-
const registeredKeys = new Set<string>(registryKeys);
|
|
1016
|
-
const resolveStatic = (constName: string): string | undefined => {
|
|
1017
|
-
const kebab = constName.toLowerCase().replace(/_/g, "-");
|
|
1018
|
-
if (registeredKeys.has(kebab)) return kebab;
|
|
1019
|
-
// Longest registry key that is a segment-prefix of the kebab'd name.
|
|
1020
|
-
let best: string | undefined;
|
|
1021
|
-
let bestLen = -1;
|
|
1022
|
-
let ambiguous = false;
|
|
1023
|
-
for (const key of registryKeys) {
|
|
1024
|
-
if (!kebab.startsWith(`${key}-`)) continue;
|
|
1025
|
-
if (key.length > bestLen) {
|
|
1026
|
-
best = key;
|
|
1027
|
-
bestLen = key.length;
|
|
1028
|
-
ambiguous = false;
|
|
1029
|
-
} else if (key.length === bestLen) {
|
|
1030
|
-
ambiguous = true;
|
|
1031
|
-
}
|
|
1032
|
-
}
|
|
1033
|
-
return ambiguous ? undefined : best;
|
|
1034
|
-
};
|
|
1035
1030
|
for (const node of sendNodes) {
|
|
1036
1031
|
if (nodeMetrics[node.id]?.templateKey || !node.subtitle) continue;
|
|
1037
|
-
const key =
|
|
1032
|
+
const key = resolveTemplateKeyFromConst(node.subtitle, registryKeys);
|
|
1038
1033
|
if (key) setTemplate(node.id, key);
|
|
1039
1034
|
}
|
|
1040
1035
|
|