@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.
Files changed (39) hide show
  1. package/package.json +12 -11
  2. package/src/buckets/check-membership.ts +45 -3
  3. package/src/connectors/define-action.ts +15 -2
  4. package/src/container.ts +85 -0
  5. package/src/env.ts +21 -0
  6. package/src/index.ts +19 -0
  7. package/src/journeys/durable-law-harness.test.ts +107 -0
  8. package/src/journeys/durable-law-harness.ts +139 -0
  9. package/src/journeys/journey-boundary.test.ts +70 -0
  10. package/src/journeys/journey-boundary.ts +10 -1
  11. package/src/journeys/with-durable-gate.test.ts +258 -0
  12. package/src/journeys/with-durable-gate.ts +141 -0
  13. package/src/lib/bucket-emit.test.ts +145 -0
  14. package/src/lib/bucket-emit.ts +29 -3
  15. package/src/lib/connector-actions.test.ts +292 -1
  16. package/src/lib/connector-actions.ts +65 -6
  17. package/src/lib/email-providers-from-env.ts +15 -16
  18. package/src/lib/enrichment-ledger.ts +207 -0
  19. package/src/lib/enrichment-provider-registry.test.ts +64 -0
  20. package/src/lib/enrichment-provider-registry.ts +35 -0
  21. package/src/lib/enrichment-providers-from-env.apollo.test.ts +30 -0
  22. package/src/lib/enrichment-providers-from-env.test.ts +28 -0
  23. package/src/lib/enrichment-providers-from-env.ts +52 -0
  24. package/src/lib/enrichment-registry-singleton.ts +45 -0
  25. package/src/lib/ingestion.ts +5 -0
  26. package/src/lib/load-optional-plugin.test.ts +133 -0
  27. package/src/lib/load-optional-plugin.ts +142 -0
  28. package/src/lib/outbound.ts +27 -0
  29. package/src/lib/refine-chain.test.ts +764 -0
  30. package/src/lib/refine-chain.ts +583 -0
  31. package/src/lib/refine-traits.test.ts +141 -0
  32. package/src/lib/refine-traits.ts +128 -0
  33. package/src/lib/refine.ts +287 -0
  34. package/src/lib/sms-providers-from-env.ts +11 -11
  35. package/src/lib/webhook-catalog-sync.test.ts +112 -0
  36. package/src/lib/webhook-signing.ts +5 -1
  37. package/src/routes/admin/contacts.ts +113 -13
  38. package/src/workflows/bucket-backfill.ts +14 -0
  39. 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
+ }
@@ -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;