@hogsend/engine 0.53.0 → 0.55.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 -11
- package/src/buckets/check-membership.ts +45 -3
- package/src/connectors/define-action.ts +15 -2
- package/src/container.ts +85 -0
- package/src/env.ts +21 -0
- package/src/index.ts +19 -0
- package/src/journeys/durable-law-harness.test.ts +107 -0
- package/src/journeys/durable-law-harness.ts +139 -0
- package/src/journeys/journey-boundary.test.ts +70 -0
- package/src/journeys/journey-boundary.ts +10 -1
- package/src/journeys/with-durable-gate.test.ts +258 -0
- package/src/journeys/with-durable-gate.ts +141 -0
- package/src/lib/bucket-emit.test.ts +145 -0
- package/src/lib/bucket-emit.ts +29 -3
- package/src/lib/connector-actions.test.ts +292 -1
- package/src/lib/connector-actions.ts +65 -6
- package/src/lib/email-providers-from-env.ts +15 -16
- package/src/lib/enrichment-ledger.ts +207 -0
- package/src/lib/enrichment-provider-registry.test.ts +64 -0
- package/src/lib/enrichment-provider-registry.ts +35 -0
- package/src/lib/enrichment-providers-from-env.apollo.test.ts +30 -0
- package/src/lib/enrichment-providers-from-env.test.ts +28 -0
- package/src/lib/enrichment-providers-from-env.ts +52 -0
- package/src/lib/enrichment-registry-singleton.ts +45 -0
- package/src/lib/ingestion.ts +5 -0
- package/src/lib/load-optional-plugin.test.ts +133 -0
- package/src/lib/load-optional-plugin.ts +142 -0
- package/src/lib/outbound.ts +27 -0
- package/src/lib/refine-chain.test.ts +764 -0
- package/src/lib/refine-chain.ts +583 -0
- package/src/lib/refine-traits.test.ts +141 -0
- package/src/lib/refine-traits.ts +128 -0
- package/src/lib/refine.ts +287 -0
- package/src/lib/sms-providers-from-env.ts +11 -11
- package/src/lib/webhook-catalog-sync.test.ts +112 -0
- package/src/lib/webhook-signing.ts +5 -1
- package/src/routes/admin/contacts.ts +113 -13
- package/src/workflows/bucket-backfill.ts +14 -0
- package/src/workflows/bucket-reconcile.ts +74 -15
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared loader for the engine's OPT-IN plugin packages (`@hogsend/plugin-apollo`,
|
|
3
|
+
* `-postmark`, `-twilio`). Each is an engine `optionalDependency`, never a hard
|
|
4
|
+
* one: a static import would make the package mandatory at engine load and break
|
|
5
|
+
* `npm install @hogsend/engine` for every consumer without it.
|
|
6
|
+
*
|
|
7
|
+
* So each preset loads its package lazily, ONCE, behind a guarded dynamic import
|
|
8
|
+
* gated on the relevant credential. The specifier is assembled at runtime (not a
|
|
9
|
+
* literal) so `tsc` never resolves the module's types for a consumer that does
|
|
10
|
+
* not have the opt-in package.
|
|
11
|
+
*
|
|
12
|
+
* ## Why the failure message matters so much
|
|
13
|
+
*
|
|
14
|
+
* All three presets previously swallowed the failure — SMS silently, enrichment
|
|
15
|
+
* behind a message that said "is not installed" for EVERY failure mode. That
|
|
16
|
+
* message was actively wrong in the most common real case (installed, but the
|
|
17
|
+
* package shipped raw `.ts` that Node cannot type-strip inside node_modules), so
|
|
18
|
+
* an operator following it reinstalled a package they already had. The whole
|
|
19
|
+
* point of this module is that the two failure modes are DIFFERENT problems with
|
|
20
|
+
* different fixes, and conflating them sends people to fix the wrong thing.
|
|
21
|
+
*
|
|
22
|
+
* `not-installed` is a configuration problem the operator can fix.
|
|
23
|
+
* `load-failed` is OUR bug and should be reported, not worked around.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
export type PluginLoadOutcome =
|
|
27
|
+
| "not-installed"
|
|
28
|
+
| "load-failed"
|
|
29
|
+
| "missing-export";
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Distinguish "the package itself is absent" from "the package is present but
|
|
33
|
+
* blew up while loading".
|
|
34
|
+
*
|
|
35
|
+
* Both surface as `ERR_MODULE_NOT_FOUND` in the general case — a plugin whose
|
|
36
|
+
* own npm dependency is missing throws exactly the same code. So a bare code
|
|
37
|
+
* check would mislabel "plugin-twilio is installed but `twilio` isn't" as
|
|
38
|
+
* "plugin-twilio is not installed" and send the operator to reinstall the wrong
|
|
39
|
+
* package. Requiring the message to name the specifier keeps the two apart.
|
|
40
|
+
*/
|
|
41
|
+
function classify(error: unknown, specifier: string): PluginLoadOutcome {
|
|
42
|
+
const err = error as { code?: string; message?: string } | undefined;
|
|
43
|
+
const notFound =
|
|
44
|
+
err?.code === "ERR_MODULE_NOT_FOUND" || err?.code === "MODULE_NOT_FOUND";
|
|
45
|
+
return notFound && (err?.message ?? "").includes(specifier)
|
|
46
|
+
? "not-installed"
|
|
47
|
+
: "load-failed";
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function describe(error: unknown): string {
|
|
51
|
+
const err = error as { code?: string; message?: string } | undefined;
|
|
52
|
+
const code = err?.code ? `${err.code}: ` : "";
|
|
53
|
+
return `${code}${(err?.message ?? String(error)).split("\n")[0]}`;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function messageFor(opts: {
|
|
57
|
+
specifier: string;
|
|
58
|
+
exportName: string;
|
|
59
|
+
enabledBy: string;
|
|
60
|
+
outcome: PluginLoadOutcome;
|
|
61
|
+
error?: unknown;
|
|
62
|
+
}): string {
|
|
63
|
+
const { specifier, exportName, enabledBy, outcome, error } = opts;
|
|
64
|
+
const skipped = `${enabledBy}, but its env preset is skipped`;
|
|
65
|
+
|
|
66
|
+
if (outcome === "not-installed") {
|
|
67
|
+
return (
|
|
68
|
+
`${skipped}: "${specifier}" is not installed. ` +
|
|
69
|
+
`Add it as a DIRECT dependency of your app: pnpm add ${specifier}. ` +
|
|
70
|
+
`Note that the engine listing it under optionalDependencies is NOT enough — ` +
|
|
71
|
+
`your app bundles the engine, so this import resolves against YOUR ` +
|
|
72
|
+
`node_modules, where an engine-only optional dependency is never linked.`
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
if (outcome === "missing-export") {
|
|
77
|
+
return (
|
|
78
|
+
`${skipped}: "${specifier}" loaded but does not export "${exportName}". ` +
|
|
79
|
+
`This usually means the package version does not match @hogsend/engine — ` +
|
|
80
|
+
`align them on the same engine line (pnpm add ${specifier}@<engine version>).`
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
return (
|
|
85
|
+
`${skipped}: "${specifier}" IS installed but failed to load — ` +
|
|
86
|
+
`${describe(error)}. This is a packaging bug in Hogsend rather than ` +
|
|
87
|
+
`anything wrong with your configuration; please report it. ` +
|
|
88
|
+
`Reinstalling the package will not help.`
|
|
89
|
+
);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Resolve a named factory export from an optional plugin package.
|
|
94
|
+
*
|
|
95
|
+
* Returns the factory, or `null` when the package cannot be loaded — in which
|
|
96
|
+
* case `onFailure` fires (once, since every call site runs at module scope, once
|
|
97
|
+
* per process) and NOTHING throws. A credential set without a working plugin
|
|
98
|
+
* degrades gracefully; if the provider was EXPLICITLY selected the container
|
|
99
|
+
* still throws its own clear "not registered" error at boot.
|
|
100
|
+
*
|
|
101
|
+
* Deliberately testable against an INJECTED specifier so the guard can be
|
|
102
|
+
* exercised without depending on a real package being absent — once these
|
|
103
|
+
* packages are engine optionalDependencies, an absence-based test would silently
|
|
104
|
+
* assert the opposite of what it means.
|
|
105
|
+
*/
|
|
106
|
+
export async function loadOptionalPlugin<T>(opts: {
|
|
107
|
+
specifier: string;
|
|
108
|
+
exportName: string;
|
|
109
|
+
/** What switched this on, e.g. `"APOLLO_API_KEY is set"`. Named in the message. */
|
|
110
|
+
enabledBy: string;
|
|
111
|
+
onFailure?: (message: string, outcome: PluginLoadOutcome) => void;
|
|
112
|
+
}): Promise<T | null> {
|
|
113
|
+
const { specifier, exportName, enabledBy, onFailure } = opts;
|
|
114
|
+
|
|
115
|
+
let mod: Record<string, unknown>;
|
|
116
|
+
try {
|
|
117
|
+
mod = (await import(specifier)) as Record<string, unknown>;
|
|
118
|
+
} catch (error) {
|
|
119
|
+
const outcome = classify(error, specifier);
|
|
120
|
+
onFailure?.(
|
|
121
|
+
messageFor({ specifier, exportName, enabledBy, outcome, error }),
|
|
122
|
+
outcome,
|
|
123
|
+
);
|
|
124
|
+
return null;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
const factory = mod[exportName];
|
|
128
|
+
if (typeof factory !== "function") {
|
|
129
|
+
onFailure?.(
|
|
130
|
+
messageFor({
|
|
131
|
+
specifier,
|
|
132
|
+
exportName,
|
|
133
|
+
enabledBy,
|
|
134
|
+
outcome: "missing-export",
|
|
135
|
+
}),
|
|
136
|
+
"missing-export",
|
|
137
|
+
);
|
|
138
|
+
return null;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
return factory as T;
|
|
142
|
+
}
|
package/src/lib/outbound.ts
CHANGED
|
@@ -108,6 +108,33 @@ export interface OutboundPayloads {
|
|
|
108
108
|
scope: "all" | "category";
|
|
109
109
|
source: string;
|
|
110
110
|
};
|
|
111
|
+
/**
|
|
112
|
+
* A refinement landed vendor traits on a contact (`refineContact`). Emitted
|
|
113
|
+
* ONLY on a genuine `status: "refined"` — never on `cached`, `not_found` or
|
|
114
|
+
* `skipped`, because a cache hit is a spend decision, not a change.
|
|
115
|
+
*
|
|
116
|
+
* `traits` carries the mapped trait KEY NAMES only — `["refined_title",
|
|
117
|
+
* "refined_company_domain"]` — never their values. That is deliberate: the
|
|
118
|
+
* payload says WHAT CHANGED, and a subscriber that wants the values reads
|
|
119
|
+
* the contact (`GET /v1/contacts`). So vendor-licensed person data never
|
|
120
|
+
* leaves the building inside a webhook body, and the envelope stays a fixed
|
|
121
|
+
* size whatever the provider returned.
|
|
122
|
+
*
|
|
123
|
+
* `userId` is the canonical contact key (`external_id ?? anonymous_id ??
|
|
124
|
+
* id`); `email` / `contactId` ride alongside so a subscriber can look the
|
|
125
|
+
* contact up by whichever key it holds.
|
|
126
|
+
*/
|
|
127
|
+
"contact.refined": {
|
|
128
|
+
userId: string | null;
|
|
129
|
+
email: string | null;
|
|
130
|
+
contactId: string | null;
|
|
131
|
+
/** The enrichment provider id that answered. */
|
|
132
|
+
provider: string;
|
|
133
|
+
/** Mapped trait key NAMES, sorted. Values are deliberately absent. */
|
|
134
|
+
traits: string[];
|
|
135
|
+
/** ISO — the lookup instant (the same value as `refined_at`). */
|
|
136
|
+
at: string;
|
|
137
|
+
};
|
|
111
138
|
"email.sent": {
|
|
112
139
|
emailSendId: string;
|
|
113
140
|
messageId: string;
|