@hogsend/engine 0.53.0 → 0.54.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,35 @@
1
+ import type { EnrichmentProvider } from "@hogsend/core";
2
+
3
+ /**
4
+ * Container-held registry of enrichment providers, keyed by `provider.meta.id`.
5
+ * The container picks ONE active provider out of it (resolved as
6
+ * `enrichment.defaultProvider ?? ENRICHMENT_PROVIDER ?? "apollo"`) for the
7
+ * `refineContact()` pipeline.
8
+ *
9
+ * The enrichment sibling of {@link SmsProviderRegistry}. `meta` is REQUIRED on
10
+ * the enrichment contract (no pre-registry back-compat), so there is no
11
+ * fallback id — last-writer-wins on `meta.id`.
12
+ */
13
+ export class EnrichmentProviderRegistry {
14
+ private byId = new Map<string, EnrichmentProvider>();
15
+
16
+ constructor(providers: EnrichmentProvider[] = []) {
17
+ for (const provider of providers) this.register(provider);
18
+ }
19
+
20
+ register(provider: EnrichmentProvider): void {
21
+ this.byId.set(provider.meta.id, provider);
22
+ }
23
+
24
+ get(id: string): EnrichmentProvider | undefined {
25
+ return this.byId.get(id);
26
+ }
27
+
28
+ getAll(): EnrichmentProvider[] {
29
+ return [...this.byId.values()];
30
+ }
31
+
32
+ count(): number {
33
+ return this.byId.size;
34
+ }
35
+ }
@@ -0,0 +1,30 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { env as envSchema } from "../env.js";
4
+
5
+ // A SEPARATE test file from enrichment-providers-from-env.test.ts on purpose:
6
+ // that file's assertions require APOLLO_API_KEY to be UNSET when the module's
7
+ // scope runs, while this one requires it SET. The node:test runner executes
8
+ // each file in its own process, so both postures hold simultaneously.
9
+ //
10
+ // The key must be in the environment BEFORE the module is imported — the
11
+ // guarded dynamic import of @hogsend/plugin-apollo fires at module scope.
12
+ process.env.APOLLO_API_KEY = "apollo-preset-test-key";
13
+
14
+ test("PRD 04 T4.3: APOLLO_API_KEY set → env preset resolves the Apollo provider", async () => {
15
+ const { enrichmentProvidersFromEnv } = await import(
16
+ "./enrichment-providers-from-env.js"
17
+ );
18
+ const providers = enrichmentProvidersFromEnv({
19
+ APOLLO_API_KEY: "apollo-preset-test-key",
20
+ } as unknown as typeof envSchema);
21
+
22
+ // @hogsend/plugin-apollo is now in the engine's optionalDependencies, so
23
+ // the guarded dynamic import resolves and the preset produces a provider.
24
+ assert.equal(providers.length, 1);
25
+ const provider = providers[0];
26
+ assert.equal(provider?.meta.id, "apollo");
27
+ assert.equal(provider?.capabilities.personLookup, true);
28
+ assert.equal(provider?.capabilities.companyLookup, true);
29
+ assert.equal(typeof provider?.enrichPerson, "function");
30
+ });
@@ -0,0 +1,67 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { env as envSchema } from "../env.js";
4
+ import {
5
+ enrichmentProvidersFromEnv,
6
+ loadEnrichmentPluginFactory,
7
+ } from "./enrichment-providers-from-env.js";
8
+
9
+ // This test process never sets APOLLO_API_KEY, so the module-scope guarded
10
+ // dynamic import in enrichment-providers-from-env.ts must not have fired —
11
+ // which is exactly the AC 6 posture the assertions below pin.
12
+ const baseEnv = { APOLLO_API_KEY: undefined } as unknown as typeof envSchema;
13
+
14
+ test("AC 6: no APOLLO_API_KEY → empty preset list (no import attempted)", () => {
15
+ assert.deepEqual(enrichmentProvidersFromEnv(baseEnv), []);
16
+ });
17
+
18
+ test("AC 7 (preset half): key set but factory unresolved → empty list, no throw", () => {
19
+ // APOLLO_API_KEY was unset at module load, so the factory is null even when
20
+ // the *passed* env carries a key — the same degraded state as "key set but
21
+ // package not installed". The preset must skip, never throw.
22
+ const envWithKey = {
23
+ APOLLO_API_KEY: "apollo-test-key",
24
+ } as unknown as typeof envSchema;
25
+ assert.deepEqual(enrichmentProvidersFromEnv(envWithKey), []);
26
+ });
27
+
28
+ test("AC 7 (guard half): unresolvable specifier → null + logged once, no throw", async () => {
29
+ // Deliberately an INJECTED unresolvable specifier — NOT @hogsend/plugin-apollo,
30
+ // which a later PRD adds to optionalDependencies (an absence-based test would
31
+ // then silently invert its meaning).
32
+ const messages: string[] = [];
33
+ const factory = await loadEnrichmentPluginFactory({
34
+ specifier: "@hogsend/plugin-test-does-not-exist",
35
+ exportName: "createTestProvider",
36
+ onMissing: (message) => messages.push(message),
37
+ });
38
+ assert.equal(factory, null);
39
+ assert.equal(messages.length, 1);
40
+ assert.match(messages[0] ?? "", /@hogsend\/plugin-test-does-not-exist/);
41
+ });
42
+
43
+ test("AC 7 control: resolvable specifier → returns the named export", async () => {
44
+ // Proves the null above comes from the unresolvable specifier, not a broken
45
+ // loader — keeping the guard-half assertion honest.
46
+ const messages: string[] = [];
47
+ const factory = await loadEnrichmentPluginFactory<
48
+ typeof import("node:path")["join"]
49
+ >({
50
+ specifier: "node:path",
51
+ exportName: "join",
52
+ onMissing: (message) => messages.push(message),
53
+ });
54
+ assert.equal(typeof factory, "function");
55
+ assert.equal(messages.length, 0);
56
+ });
57
+
58
+ test("a resolvable specifier MISSING the named export → null + logged, no throw", async () => {
59
+ const messages: string[] = [];
60
+ const factory = await loadEnrichmentPluginFactory({
61
+ specifier: "node:path",
62
+ exportName: "createApolloProvider",
63
+ onMissing: (message) => messages.push(message),
64
+ });
65
+ assert.equal(factory, null);
66
+ assert.equal(messages.length, 1);
67
+ });
@@ -0,0 +1,85 @@
1
+ import type { EnrichmentProvider } from "@hogsend/core";
2
+ import type { env as envSchema } from "../env.js";
3
+
4
+ /**
5
+ * `@hogsend/plugin-apollo` is an OPT-IN, deferred-publish package — an engine
6
+ * `optionalDependency`, NOT a hard one. Mirroring the Postmark/Twilio pattern
7
+ * in `email-providers-from-env.ts` / `sms-providers-from-env.ts`, we MUST NOT
8
+ * statically import it: a static import would make the package mandatory at
9
+ * engine load and break `npm install @hogsend/engine` for every consumer
10
+ * without it.
11
+ *
12
+ * Instead we load it lazily, ONCE, behind a top-level guarded dynamic import
13
+ * gated on `APOLLO_API_KEY` being present. The specifier is assembled at
14
+ * runtime (not a literal) so `tsc` never tries to resolve the module's types
15
+ * for a consumer that doesn't have the opt-in package installed.
16
+ */
17
+ type CreateApolloProvider = (cfg: { apiKey: string }) => EnrichmentProvider;
18
+
19
+ const APOLLO_PACKAGE = ["@hogsend", "plugin-apollo"].join("/");
20
+
21
+ /**
22
+ * The guard around the dynamic import, extracted so it is testable against an
23
+ * INJECTED unresolvable specifier (never against `@hogsend/plugin-apollo`
24
+ * genuinely being absent — once that package lands in `optionalDependencies`,
25
+ * an absence-based test would silently assert the opposite of what it means).
26
+ *
27
+ * Resolves to the named factory export, or null when the package cannot be
28
+ * resolved / the export is missing — in which case `onMissing` fires (once,
29
+ * since the module-scope call site runs once per process) and nothing throws:
30
+ * a key set without the plugin installed degrades gracefully, and if the
31
+ * provider was EXPLICITLY requested the container still throws its clear
32
+ * "not registered" boot error.
33
+ */
34
+ export async function loadEnrichmentPluginFactory<T>(opts: {
35
+ specifier: string;
36
+ exportName: string;
37
+ onMissing?: (message: string) => void;
38
+ }): Promise<T | null> {
39
+ try {
40
+ const mod = (await import(opts.specifier)) as Record<string, unknown>;
41
+ const factory = mod[opts.exportName];
42
+ if (typeof factory !== "function") {
43
+ throw new Error(`missing export "${opts.exportName}"`);
44
+ }
45
+ return factory as T;
46
+ } catch {
47
+ opts.onMissing?.(
48
+ `enrichment plugin "${opts.specifier}" is not installed — its env preset is skipped. ` +
49
+ `Install the package (pnpm add ${opts.specifier}) to enable it.`,
50
+ );
51
+ return null;
52
+ }
53
+ }
54
+
55
+ let createApolloProvider: CreateApolloProvider | null = null;
56
+ if (process.env.APOLLO_API_KEY) {
57
+ createApolloProvider =
58
+ await loadEnrichmentPluginFactory<CreateApolloProvider>({
59
+ specifier: APOLLO_PACKAGE,
60
+ exportName: "createApolloProvider",
61
+ // Module scope ⇒ logs ONCE per process, and only when the key is set.
62
+ onMissing: (message) => console.warn(message),
63
+ });
64
+ }
65
+
66
+ /**
67
+ * Build the env-enabled enrichment-provider presets. A preset is constructed
68
+ * ONLY when its credential is present AND the opt-in package resolved (see the
69
+ * guarded dynamic import above), so a deploy without an Apollo key never
70
+ * touches the package and contributes no provider.
71
+ *
72
+ * These presets come FIRST in the container's merge — a consumer-supplied
73
+ * provider of the same id wins (last-writer-wins on the registry).
74
+ */
75
+ export function enrichmentProvidersFromEnv(
76
+ env: typeof envSchema,
77
+ ): EnrichmentProvider[] {
78
+ const providers: EnrichmentProvider[] = [];
79
+
80
+ if (env.APOLLO_API_KEY && createApolloProvider) {
81
+ providers.push(createApolloProvider({ apiKey: env.APOLLO_API_KEY }));
82
+ }
83
+
84
+ return providers;
85
+ }
@@ -0,0 +1,45 @@
1
+ import type { EnrichmentProvider } from "@hogsend/core";
2
+ import type { EnrichmentProviderRegistry } from "./enrichment-provider-registry.js";
3
+ import { createOptionalSingleton } from "./singleton.js";
4
+
5
+ /**
6
+ * The process-wide enrichment-provider state, set once by `createHogsendClient`
7
+ * at startup: the full registry plus the ONE resolved active provider (may be
8
+ * undefined — a deploy with no enrichment configured is a valid deploy).
9
+ *
10
+ * A singleton (not just a container field) because `refineContact()` (PRD 03)
11
+ * is a STANDALONE import called from journey `run` functions and crons that
12
+ * hold no container reference — the same reason `sendEmail`/`sendSms` read
13
+ * their services off singletons. Optional variant: `get` never throws;
14
+ * `refineContact` fails per-call with an actionable message when unset.
15
+ */
16
+ interface EnrichmentProviderState {
17
+ registry: EnrichmentProviderRegistry;
18
+ /** The resolved ACTIVE provider. Undefined when none is configured. */
19
+ active?: EnrichmentProvider;
20
+ }
21
+
22
+ const singleton = createOptionalSingleton<EnrichmentProviderState>();
23
+
24
+ export function setEnrichmentProviders(
25
+ registry: EnrichmentProviderRegistry,
26
+ active?: EnrichmentProvider,
27
+ ): void {
28
+ singleton.set({ registry, active });
29
+ }
30
+
31
+ export function getEnrichmentProviderRegistry():
32
+ | EnrichmentProviderRegistry
33
+ | undefined {
34
+ return singleton.get()?.registry;
35
+ }
36
+
37
+ /** The single resolved active enrichment provider (undefined = not configured). */
38
+ export function getEnrichmentProvider(): EnrichmentProvider | undefined {
39
+ return singleton.get()?.active;
40
+ }
41
+
42
+ /** Reset the installed state — only for test cleanup. */
43
+ export function resetEnrichmentProviders(): void {
44
+ singleton.reset();
45
+ }
@@ -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;