@hogsend/engine 0.66.0 → 0.67.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,49 @@
1
+ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
+ import type { AnalyticsProvider } from "@hogsend/core";
3
+ import type { JourneyRegistry } from "@hogsend/core/registry";
4
+ import type { Database } from "@hogsend/db";
5
+ import type { Logger } from "./logger.js";
6
+ import type { ReferralRegistry } from "./referral-registry.js";
7
+ import { createOptionalSingleton } from "./singleton.js";
8
+
9
+ /**
10
+ * The handles the referral wiring needs at sites that hold no container:
11
+ * `lib/contacts.ts` (bind, post-commit), `lib/ingestion.ts` (qualify +
12
+ * convert) and journey-runtime `getReferralLink`. Installed once by
13
+ * `createHogsendClient`.
14
+ */
15
+ export interface ReferralRuntime {
16
+ referrals: ReferralRegistry;
17
+ db: Database;
18
+ /** `env.API_PUBLIC_URL` - the tracking host every minted link is built on. */
19
+ baseUrl: string;
20
+ /**
21
+ * The container's emit handles, so a library-code site (the bind in
22
+ * `lib/contacts.ts`) reaches the SAME Hatchet client the container was built
23
+ * with. Without them the intent layer would fall back to importing
24
+ * `lib/hatchet.js`, whose module load runs `HatchetClient.init` and throws
25
+ * where no real token exists.
26
+ */
27
+ hatchet: HatchetClient;
28
+ registry: JourneyRegistry;
29
+ logger: Logger;
30
+ analytics?: AnalyticsProvider;
31
+ }
32
+
33
+ const _runtime = createOptionalSingleton<ReferralRuntime>();
34
+
35
+ export const setReferralRuntime = _runtime.set;
36
+
37
+ /**
38
+ * The installed referral runtime, or `undefined`.
39
+ *
40
+ * OPTIONAL, not required: unlike the email/SMS services there is no stub to
41
+ * install, and every consumer of this is a wired site that must stay INERT on
42
+ * a deploy with no referrals. `undefined` therefore means "no referrals
43
+ * configured", which is a legitimate steady state and never an error - so this
44
+ * must not be switched to `createSingleton`, whose getter throws.
45
+ */
46
+ export const getReferralRuntime = _runtime.get;
47
+
48
+ /** Reset the singleton - only for test cleanup. */
49
+ export const resetReferralRuntime = _runtime.reset;
@@ -0,0 +1,109 @@
1
+ import assert from "node:assert/strict";
2
+ import { readFileSync } from "node:fs";
3
+ import test from "node:test";
4
+ import { fileURLToPath } from "node:url";
5
+
6
+ /**
7
+ * THE NO-EMIT LAW for the referral store (PRD 05 §6, mirroring the
8
+ * account-link twin in `account-links-emit.test.ts`). `lib/referrals.ts`
9
+ * returns mutation facts; its callers emit `referral.*` outbound AND re-ingest
10
+ * for journeys, side by side.
11
+ *
12
+ * Both assertions are SOURCE reads, deliberately. A store emit plus an
13
+ * intent-layer emit for the same mutation share a dedupe key, so
14
+ * `emitOutbound`'s `onConflictDoNothing` would silently swallow the duplicate
15
+ * and no behavioural test in this repo could go red - the only symptom would
16
+ * be that nobody can say which layer owns the fact.
17
+ */
18
+
19
+ const STORE_SOURCE = readFileSync(
20
+ fileURLToPath(new URL("./referrals.ts", import.meta.url)),
21
+ "utf8",
22
+ );
23
+
24
+ /** Every symbol that reaches the outbound spine, the bus, or analytics. */
25
+ const EMIT_SYMBOLS = [
26
+ "emitOutbound",
27
+ "ingestEvent",
28
+ "hatchet",
29
+ "Hatchet",
30
+ "capture",
31
+ "emitReferral",
32
+ "ingestReferral",
33
+ ];
34
+
35
+ /**
36
+ * The store's permitted RUNTIME imports (`import type` is erased, so it cannot
37
+ * carry a call). Anything else - including a FOURTH emit helper nobody has
38
+ * written yet, under any name - trips this guard, because emitting requires
39
+ * importing something that can emit.
40
+ *
41
+ * KNOWN LIMIT, stated rather than papered over: this reads LITERAL import
42
+ * specifiers and LITERAL symbol names. An emit routed through both a renamed
43
+ * re-export AND a computed `import(someVariable)` would evade it. Every
44
+ * single-step variant is caught; a non-literal `import(...)` in
45
+ * `lib/referrals.ts` is the bypass, not this guard's silence.
46
+ */
47
+ const ALLOWED_RUNTIME_IMPORTS = ["@hogsend/core", "@hogsend/db", "drizzle-orm"];
48
+
49
+ /** STATIC runtime (non-`import type`) module specifiers. */
50
+ function staticImports(source: string): string[] {
51
+ const specifiers = new Set<string>();
52
+ for (const m of source.matchAll(
53
+ /^import\s+(?!type\s)(?:[\s\S]*?\s+from\s+)?["']([^"']+)["']/gm,
54
+ )) {
55
+ if (m[1]) specifiers.add(m[1]);
56
+ }
57
+ return [...specifiers];
58
+ }
59
+
60
+ /** DYNAMIC `import("…")` module specifiers. */
61
+ function dynamicImports(source: string): string[] {
62
+ const specifiers = new Set<string>();
63
+ for (const m of source.matchAll(/\bimport\s*\(\s*["']([^"']+)["']/g)) {
64
+ if (m[1]) specifiers.add(m[1]);
65
+ }
66
+ return [...specifiers];
67
+ }
68
+
69
+ function runtimeImports(source: string): string[] {
70
+ return [...new Set([...staticImports(source), ...dynamicImports(source)])];
71
+ }
72
+
73
+ test("the referral store reaches no emit surface", () => {
74
+ const hits = STORE_SOURCE.split("\n")
75
+ .map((line, i) => [i + 1, line] as const)
76
+ .filter(([, line]) => {
77
+ const trimmed = line.trimStart();
78
+ if (
79
+ trimmed.startsWith("*") ||
80
+ trimmed.startsWith("//") ||
81
+ trimmed.startsWith("/*")
82
+ ) {
83
+ return false;
84
+ }
85
+ return EMIT_SYMBOLS.some((symbol) => line.includes(symbol));
86
+ });
87
+
88
+ assert.deepEqual(
89
+ hits,
90
+ [],
91
+ "lib/referrals.ts must reach NEITHER the outbound spine " +
92
+ "(`emitOutbound`) NOR the journey plane (`ingestEvent`, Hatchet) NOR " +
93
+ `analytics (\`capture\`); found: ${JSON.stringify(hits)}`,
94
+ );
95
+ });
96
+
97
+ test("the referral store imports nothing new at runtime", () => {
98
+ // The symbol scan above only catches emit surfaces we already know the name
99
+ // of. This one catches the NEXT one: a store that emits has to import
100
+ // something that emits, so pinning the import list makes any such edge fail
101
+ // here first, whatever it gets called.
102
+ assert.deepEqual(
103
+ runtimeImports(STORE_SOURCE).sort(),
104
+ [...ALLOWED_RUNTIME_IMPORTS].sort(),
105
+ "lib/referrals.ts changed its runtime imports. If the new import cannot " +
106
+ "emit (the store returns facts, its callers emit - PRD 05 §6), add it " +
107
+ "to ALLOWED_RUNTIME_IMPORTS.",
108
+ );
109
+ });