@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.
- package/package.json +12 -12
- package/src/container.ts +77 -0
- package/src/index.ts +78 -0
- package/src/lib/contacts.ts +70 -0
- package/src/lib/ingestion.ts +61 -0
- package/src/lib/links.ts +94 -11
- package/src/lib/outbound.ts +94 -0
- package/src/lib/referral-intent.ts +723 -0
- package/src/lib/referral-link.ts +200 -0
- package/src/lib/referral-registry.ts +83 -0
- package/src/lib/referral-report.ts +739 -0
- package/src/lib/referral-runtime.ts +49 -0
- package/src/lib/referrals-no-emit.test.ts +109 -0
- package/src/lib/referrals.ts +712 -0
- package/src/lib/webhook-signing.ts +10 -0
- package/src/routes/admin/api-keys.ts +5 -0
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/admin/links.ts +14 -5
- package/src/routes/admin/referrals.ts +565 -0
- package/src/routes/contacts/index.ts +78 -0
- package/src/routes/index.ts +39 -0
- package/src/routes/referrals/index.ts +41 -0
- package/src/routes/referrals/me.ts +123 -0
- package/src/routes/referrals/report.ts +285 -0
- package/src/routes/referrals/shared.ts +34 -0
- package/src/routes/referrals/touch.ts +313 -0
- package/src/routes/tracking/arrive.ts +90 -0
- package/src/routes/tracking/click-pipeline.ts +8 -0
|
@@ -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
|
+
});
|