@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.
- package/package.json +12 -11
- 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/connector-actions.test.ts +292 -1
- package/src/lib/connector-actions.ts +65 -6
- 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 +67 -0
- package/src/lib/enrichment-providers-from-env.ts +85 -0
- package/src/lib/enrichment-registry-singleton.ts +45 -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/webhook-catalog-sync.test.ts +112 -0
- package/src/lib/webhook-signing.ts +5 -1
- package/src/routes/admin/contacts.ts +113 -13
|
@@ -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
|
+
}
|
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;
|