@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,207 @@
1
+ import { type Database, enrichmentLookups } from "@hogsend/db";
2
+ import { and, eq, sql, sum } from "drizzle-orm";
3
+
4
+ /** The lookup subject's kind — mirrors the `enrichment_lookup_kind` pgEnum. */
5
+ export type EnrichmentLookupKind = "email" | "domain";
6
+
7
+ /**
8
+ * The lookup's outcome — mirrors the `enrichment_lookup_status` pgEnum.
9
+ * `found`/`not_found` are both PAID answers and suppress re-spend until the row
10
+ * expires; `error` is not a paid answer and must never suppress a retry.
11
+ */
12
+ export type EnrichmentLookupStatus = "found" | "not_found" | "error";
13
+
14
+ /** A ledger row as the refinement gate chain reads it. */
15
+ export interface EnrichmentLookupRow {
16
+ id: string;
17
+ provider: string;
18
+ lookupKind: EnrichmentLookupKind;
19
+ lookupKey: string;
20
+ status: EnrichmentLookupStatus;
21
+ contactId: string | null;
22
+ refinedAt: Date;
23
+ expiresAt: Date;
24
+ raw: Record<string, unknown> | null;
25
+ /** The normalized `refined_*` patch the paid answer produced. */
26
+ traits: Record<string, unknown> | null;
27
+ spendWindow: Date | null;
28
+ spendCount: number;
29
+ lastErrorAt: Date | null;
30
+ }
31
+
32
+ /**
33
+ * The ledger row for a `(provider, lookupKind, lookupKey)` triple, or null when
34
+ * this subject has never been looked up by this provider.
35
+ *
36
+ * Deliberately returns the row REGARDLESS of status and expiry: the gate chain
37
+ * owns the "unexpired AND paid" verdict so the `error`-never-short-circuits rule
38
+ * lives next to the rest of the gate ordering rather than being buried in a
39
+ * WHERE clause.
40
+ */
41
+ export async function findEnrichmentLookup(opts: {
42
+ db: Database;
43
+ provider: string;
44
+ lookupKind: EnrichmentLookupKind;
45
+ lookupKey: string;
46
+ }): Promise<EnrichmentLookupRow | null> {
47
+ const rows = await opts.db
48
+ .select()
49
+ .from(enrichmentLookups)
50
+ .where(
51
+ and(
52
+ eq(enrichmentLookups.provider, opts.provider),
53
+ eq(enrichmentLookups.lookupKind, opts.lookupKind),
54
+ eq(enrichmentLookups.lookupKey, opts.lookupKey),
55
+ ),
56
+ )
57
+ .limit(1);
58
+ return (rows[0] as EnrichmentLookupRow | undefined) ?? null;
59
+ }
60
+
61
+ /**
62
+ * Record a lookup against the `(provider, lookup_kind, lookup_key)` unique index
63
+ * — the Layer-2, version-independent exactly-once backstop for refinement — AND
64
+ * the spend it cost.
65
+ *
66
+ * Conflict behaviour is status-dependent, and deliberately asymmetric:
67
+ *
68
+ * - a PAID answer (`found` / `not_found`) UPDATES the existing row, so a
69
+ * `force: true` re-lookup refreshes the TTL + the stored traits in place
70
+ * instead of inserting a duplicate (the unique index would reject one
71
+ * anyway);
72
+ * - an `error` never touches the CACHE columns (`status`/`expiresAt`/`raw`/
73
+ * `traits`/`refinedAt`), so a transient vendor 5xx during a forced re-lookup
74
+ * can never clobber a live, good cached row.
75
+ *
76
+ * What BOTH branches always do is bump the spend counter and stamp
77
+ * `spend_window`. That is the whole point: the row is one-per-key, so counting
78
+ * rows counts SUBJECTS, not vendor calls — a `force` loop, or an outage
79
+ * retrying an already-refined base, would otherwise spend real money without
80
+ * ever moving the budget cap. `spend_count` resets to 1 whenever the call lands
81
+ * in a window later than the one on the row, so a previous month's attempts can
82
+ * never be pulled into this month's ceiling.
83
+ */
84
+ export async function upsertEnrichmentLookup(opts: {
85
+ db: Database;
86
+ provider: string;
87
+ lookupKind: EnrichmentLookupKind;
88
+ lookupKey: string;
89
+ status: EnrichmentLookupStatus;
90
+ contactId?: string | null;
91
+ refinedAt: Date;
92
+ expiresAt: Date;
93
+ raw?: unknown;
94
+ traits?: Record<string, unknown> | null;
95
+ /** First instant of the budget window this call is charged to. */
96
+ spendWindow: Date;
97
+ }): Promise<void> {
98
+ const isError = opts.status === "error";
99
+ const values = {
100
+ provider: opts.provider,
101
+ lookupKind: opts.lookupKind,
102
+ lookupKey: opts.lookupKey,
103
+ status: opts.status,
104
+ contactId: opts.contactId ?? null,
105
+ refinedAt: opts.refinedAt,
106
+ expiresAt: opts.expiresAt,
107
+ raw: toJsonbRecord(opts.raw),
108
+ traits: opts.traits ?? null,
109
+ spendWindow: opts.spendWindow,
110
+ spendCount: 1,
111
+ lastErrorAt: isError ? opts.refinedAt : null,
112
+ };
113
+
114
+ // A call that lands in the SAME window as the one already on the row extends
115
+ // that window's tally; a call in a LATER window starts a fresh tally. Written
116
+ // as SQL so the whole thing is one atomic statement — a read-modify-write
117
+ // here would lose concurrent lookups, which is exactly the spend the cap
118
+ // exists to bound.
119
+ const bumpedSpend = sql`case
120
+ when ${enrichmentLookups.spendWindow} = excluded.spend_window
121
+ then ${enrichmentLookups.spendCount} + 1
122
+ else 1
123
+ end`;
124
+
125
+ const spend = {
126
+ spendWindow: opts.spendWindow,
127
+ spendCount: bumpedSpend,
128
+ updatedAt: new Date(),
129
+ };
130
+
131
+ const insert = opts.db.insert(enrichmentLookups).values(values);
132
+ const target = [
133
+ enrichmentLookups.provider,
134
+ enrichmentLookups.lookupKind,
135
+ enrichmentLookups.lookupKey,
136
+ ];
137
+
138
+ if (isError) {
139
+ // Spend + forensics ONLY. Every cache column is left exactly as it was.
140
+ await insert.onConflictDoUpdate({
141
+ target,
142
+ set: { ...spend, lastErrorAt: opts.refinedAt },
143
+ });
144
+ return;
145
+ }
146
+
147
+ await insert.onConflictDoUpdate({
148
+ target,
149
+ set: {
150
+ ...spend,
151
+ status: values.status,
152
+ refinedAt: values.refinedAt,
153
+ expiresAt: values.expiresAt,
154
+ raw: values.raw,
155
+ traits: values.traits,
156
+ // Only ever ATTACH a contact, never detach one: a later lookup that
157
+ // resolved no contact must not erase the contact the first one attributed
158
+ // the spend to.
159
+ ...(values.contactId ? { contactId: values.contactId } : {}),
160
+ },
161
+ });
162
+ }
163
+
164
+ /**
165
+ * How many provider LOOKUPS the ledger recorded in the budget window starting
166
+ * at `since` — the number behind `ENRICHMENT_MONTHLY_LOOKUPS`.
167
+ *
168
+ * A SUM of `spend_count` over the rows stamped with this window, not a COUNT of
169
+ * rows: the table holds one row per subject, so a row count would answer "how
170
+ * many distinct subjects were touched", which equals spend only when nothing is
171
+ * ever re-looked-up. Errors are included — an `error` row still represents a
172
+ * request that left the building, and the operator's cap is a ceiling on
173
+ * requests, not on successful matches. Served by
174
+ * `enrichment_lookups_spend_window_idx`.
175
+ */
176
+ export async function countEnrichmentLookups(opts: {
177
+ db: Database;
178
+ since: Date;
179
+ }): Promise<number> {
180
+ const rows = await opts.db
181
+ .select({ total: sum(enrichmentLookups.spendCount) })
182
+ .from(enrichmentLookups)
183
+ .where(eq(enrichmentLookups.spendWindow, opts.since));
184
+ return Number(rows[0]?.total ?? 0);
185
+ }
186
+
187
+ /**
188
+ * The first instant of `at`'s calendar month in UTC — the lower bound of the
189
+ * monthly budget window. UTC (not local) so the cap resets at the same instant
190
+ * for every process regardless of the host's timezone.
191
+ */
192
+ export function startOfUtcMonth(at: Date): Date {
193
+ return new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), 1));
194
+ }
195
+
196
+ /**
197
+ * Narrow a provider's verbatim payload to something the `raw` jsonb column
198
+ * accepts. A plain object is stored as-is; anything else (array, scalar) is
199
+ * wrapped so it stays inspectable without widening the column's type.
200
+ */
201
+ function toJsonbRecord(raw: unknown): Record<string, unknown> | null {
202
+ if (raw === null || raw === undefined) return null;
203
+ if (typeof raw === "object" && !Array.isArray(raw)) {
204
+ return raw as Record<string, unknown>;
205
+ }
206
+ return { value: raw as never };
207
+ }
@@ -0,0 +1,64 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { EnrichmentProvider } from "@hogsend/core";
4
+ import { EnrichmentProviderRegistry } from "./enrichment-provider-registry.js";
5
+ import {
6
+ getEnrichmentProvider,
7
+ getEnrichmentProviderRegistry,
8
+ resetEnrichmentProviders,
9
+ setEnrichmentProviders,
10
+ } from "./enrichment-registry-singleton.js";
11
+
12
+ function fakeProvider(id: string, name = id): EnrichmentProvider {
13
+ return {
14
+ meta: { id, name },
15
+ capabilities: { personLookup: true, companyLookup: false },
16
+ async enrichPerson() {
17
+ return { found: false, raw: null };
18
+ },
19
+ };
20
+ }
21
+
22
+ test("registry keys providers by meta.id", () => {
23
+ const apollo = fakeProvider("apollo");
24
+ const clay = fakeProvider("clay");
25
+ const registry = new EnrichmentProviderRegistry([apollo, clay]);
26
+
27
+ assert.equal(registry.get("apollo"), apollo);
28
+ assert.equal(registry.get("clay"), clay);
29
+ assert.equal(registry.get("clearbit"), undefined);
30
+ assert.equal(registry.count(), 2);
31
+ assert.deepEqual(registry.getAll(), [apollo, clay]);
32
+ });
33
+
34
+ test("duplicate meta.id is last-writer-wins (constructor order + register)", () => {
35
+ const first = fakeProvider("apollo", "first");
36
+ const second = fakeProvider("apollo", "second");
37
+ const registry = new EnrichmentProviderRegistry([first, second]);
38
+
39
+ assert.equal(registry.count(), 1);
40
+ assert.equal(registry.get("apollo"), second);
41
+
42
+ const third = fakeProvider("apollo", "third");
43
+ registry.register(third);
44
+ assert.equal(registry.count(), 1);
45
+ assert.equal(registry.get("apollo"), third);
46
+ });
47
+
48
+ test("singleton: set → get (registry + active), reset clears", () => {
49
+ const apollo = fakeProvider("apollo");
50
+ const registry = new EnrichmentProviderRegistry([apollo]);
51
+
52
+ setEnrichmentProviders(registry, apollo);
53
+ assert.equal(getEnrichmentProviderRegistry(), registry);
54
+ assert.equal(getEnrichmentProvider(), apollo);
55
+
56
+ // Active is legitimately undefined (registered-but-inert deploy).
57
+ setEnrichmentProviders(registry, undefined);
58
+ assert.equal(getEnrichmentProviderRegistry(), registry);
59
+ assert.equal(getEnrichmentProvider(), undefined);
60
+
61
+ resetEnrichmentProviders();
62
+ assert.equal(getEnrichmentProviderRegistry(), undefined);
63
+ assert.equal(getEnrichmentProvider(), undefined);
64
+ });
@@ -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,28 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { env as envSchema } from "../env.js";
4
+ import { enrichmentProvidersFromEnv } from "./enrichment-providers-from-env.js";
5
+
6
+ // This test process never sets APOLLO_API_KEY, so the module-scope guarded
7
+ // dynamic import in enrichment-providers-from-env.ts must not have fired —
8
+ // which is exactly the AC 6 posture the assertions below pin.
9
+ const baseEnv = { APOLLO_API_KEY: undefined } as unknown as typeof envSchema;
10
+
11
+ test("AC 6: no APOLLO_API_KEY → empty preset list (no import attempted)", () => {
12
+ assert.deepEqual(enrichmentProvidersFromEnv(baseEnv), []);
13
+ });
14
+
15
+ test("AC 7 (preset half): key set but factory unresolved → empty list, no throw", () => {
16
+ // APOLLO_API_KEY was unset at module load, so the factory is null even when
17
+ // the *passed* env carries a key — the same degraded state as "key set but
18
+ // package not installed". The preset must skip, never throw.
19
+ const envWithKey = {
20
+ APOLLO_API_KEY: "apollo-test-key",
21
+ } as unknown as typeof envSchema;
22
+ assert.deepEqual(enrichmentProvidersFromEnv(envWithKey), []);
23
+ });
24
+
25
+ // The guard itself now lives in `load-optional-plugin.ts` and is covered by
26
+ // `load-optional-plugin.test.ts` — including the classification this preset
27
+ // depends on (absent package vs installed-but-broken). Only the preset's own
28
+ // behaviour is asserted here.
@@ -0,0 +1,52 @@
1
+ import type { EnrichmentProvider } from "@hogsend/core";
2
+ import type { env as envSchema } from "../env.js";
3
+ import { loadOptionalPlugin } from "./load-optional-plugin.js";
4
+
5
+ /**
6
+ * `@hogsend/plugin-apollo` is an OPT-IN, deferred-publish package — an engine
7
+ * `optionalDependency`, NOT a hard one. Mirroring the Postmark/Twilio pattern
8
+ * in `email-providers-from-env.ts` / `sms-providers-from-env.ts`, we MUST NOT
9
+ * statically import it: a static import would make the package mandatory at
10
+ * engine load and break `npm install @hogsend/engine` for every consumer
11
+ * without it.
12
+ *
13
+ * Instead we load it lazily, ONCE, behind a top-level guarded dynamic import
14
+ * gated on `APOLLO_API_KEY` being present. The specifier is assembled at
15
+ * runtime (not a literal) so `tsc` never tries to resolve the module's types
16
+ * for a consumer that doesn't have the opt-in package installed.
17
+ */
18
+ type CreateApolloProvider = (cfg: { apiKey: string }) => EnrichmentProvider;
19
+
20
+ const APOLLO_PACKAGE = ["@hogsend", "plugin-apollo"].join("/");
21
+
22
+ let createApolloProvider: CreateApolloProvider | null = null;
23
+ if (process.env.APOLLO_API_KEY) {
24
+ createApolloProvider = await loadOptionalPlugin<CreateApolloProvider>({
25
+ specifier: APOLLO_PACKAGE,
26
+ exportName: "createApolloProvider",
27
+ enabledBy: "APOLLO_API_KEY is set",
28
+ // Module scope ⇒ logs ONCE per process, and only when the key is set.
29
+ onFailure: (message) => console.warn(message),
30
+ });
31
+ }
32
+
33
+ /**
34
+ * Build the env-enabled enrichment-provider presets. A preset is constructed
35
+ * ONLY when its credential is present AND the opt-in package resolved (see the
36
+ * guarded dynamic import above), so a deploy without an Apollo key never
37
+ * touches the package and contributes no provider.
38
+ *
39
+ * These presets come FIRST in the container's merge — a consumer-supplied
40
+ * provider of the same id wins (last-writer-wins on the registry).
41
+ */
42
+ export function enrichmentProvidersFromEnv(
43
+ env: typeof envSchema,
44
+ ): EnrichmentProvider[] {
45
+ const providers: EnrichmentProvider[] = [];
46
+
47
+ if (env.APOLLO_API_KEY && createApolloProvider) {
48
+ providers.push(createApolloProvider({ apiKey: env.APOLLO_API_KEY }));
49
+ }
50
+
51
+ return providers;
52
+ }
@@ -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
+ }
@@ -778,6 +778,11 @@ export async function ingestEvent(opts: {
778
778
  hatchet,
779
779
  logger,
780
780
  userId: resolvedKey,
781
+ // The resolved row id rides along as the ENGINE-INTERNAL provenance pin
782
+ // for the bucket transition re-ingests: `resolvedKey` may be the
783
+ // contact's `anonymous_id`, which a bare re-ingest would treat as an
784
+ // external key and mint a phantom twin for (issue #608).
785
+ contactId,
781
786
  userEmail: event.userEmail || null,
782
787
  event: event.event,
783
788
  eventProperties: event.eventProperties,
@@ -0,0 +1,133 @@
1
+ import assert from "node:assert/strict";
2
+ import { mkdtemp, rm, writeFile } from "node:fs/promises";
3
+ import { tmpdir } from "node:os";
4
+ import { join } from "node:path";
5
+ import test from "node:test";
6
+ import { pathToFileURL } from "node:url";
7
+ import {
8
+ loadOptionalPlugin,
9
+ type PluginLoadOutcome,
10
+ } from "./load-optional-plugin.js";
11
+
12
+ function collect() {
13
+ const seen: Array<{ message: string; outcome: PluginLoadOutcome }> = [];
14
+ return {
15
+ seen,
16
+ onFailure: (message: string, outcome: PluginLoadOutcome) =>
17
+ seen.push({ message, outcome }),
18
+ };
19
+ }
20
+
21
+ test("resolvable specifier → returns the named export, logs nothing", async () => {
22
+ // The control. Proves a null below comes from the specifier, not a broken
23
+ // loader.
24
+ const { seen, onFailure } = collect();
25
+ const factory = await loadOptionalPlugin<typeof import("node:path")["join"]>({
26
+ specifier: "node:path",
27
+ exportName: "join",
28
+ enabledBy: "TEST is set",
29
+ onFailure,
30
+ });
31
+ assert.equal(typeof factory, "function");
32
+ assert.equal(seen.length, 0);
33
+ });
34
+
35
+ test("absent package → not-installed, names the install command", async () => {
36
+ // An INJECTED unresolvable specifier, never a real @hogsend plugin: those are
37
+ // engine optionalDependencies, so an absence-based test would silently invert
38
+ // its own meaning the moment the package resolves.
39
+ const { seen, onFailure } = collect();
40
+ const factory = await loadOptionalPlugin({
41
+ specifier: "@hogsend/plugin-test-does-not-exist",
42
+ exportName: "createTestProvider",
43
+ enabledBy: "TEST_TOKEN is set",
44
+ onFailure,
45
+ });
46
+ assert.equal(factory, null);
47
+ assert.equal(seen.length, 1);
48
+ assert.equal(seen[0]?.outcome, "not-installed");
49
+ assert.match(
50
+ seen[0]?.message ?? "",
51
+ /pnpm add @hogsend\/plugin-test-does-not-exist/,
52
+ );
53
+ // The reason it was attempted at all must be in the message — otherwise the
54
+ // operator cannot tell which credential switched this on.
55
+ assert.match(seen[0]?.message ?? "", /TEST_TOKEN is set/);
56
+ // The direct-dependency nuance is the entire point: an engine
57
+ // optionalDependency is installed but never linked at the consumer's top
58
+ // level, so a bundled app cannot resolve it.
59
+ assert.match(seen[0]?.message ?? "", /DIRECT dependency/);
60
+ });
61
+
62
+ test("present but broken → load-failed, and does NOT say 'not installed'", async () => {
63
+ // The regression that motivated this module. The old loader reported every
64
+ // failure as "is not installed", so an operator whose package WAS installed
65
+ // (but shipped raw .ts that Node cannot type-strip under node_modules) was
66
+ // told to reinstall it — advice that could never work. A load failure must
67
+ // never be described as an absence.
68
+ const { seen, onFailure } = collect();
69
+ const factory = await loadOptionalPlugin({
70
+ // Resolves, then throws on evaluation.
71
+ specifier: "data:text/javascript,throw new Error('boom on evaluate')",
72
+ exportName: "createTestProvider",
73
+ enabledBy: "TEST_TOKEN is set",
74
+ onFailure,
75
+ });
76
+ assert.equal(factory, null);
77
+ assert.equal(seen[0]?.outcome, "load-failed");
78
+ assert.doesNotMatch(seen[0]?.message ?? "", /is not installed/);
79
+ assert.match(seen[0]?.message ?? "", /boom on evaluate/);
80
+ assert.match(seen[0]?.message ?? "", /packaging bug/);
81
+ });
82
+
83
+ test("a MISSING TRANSITIVE dep is not reported as the plugin being absent", async () => {
84
+ // The case that forces classification to inspect the message, not just the
85
+ // code. "plugin-twilio is installed but `twilio` is not" throws the SAME
86
+ // ERR_MODULE_NOT_FOUND as "plugin-twilio is not installed"; keying on the
87
+ // code alone would tell the operator to reinstall a package that is already
88
+ // there while the real gap goes unnamed.
89
+ //
90
+ // This needs a real file on disk. A `data:` URL cannot resolve bare
91
+ // specifiers at all (ERR_UNSUPPORTED_RESOLVE_REQUEST), and a `node:`-prefixed
92
+ // miss throws ERR_UNKNOWN_BUILTIN_MODULE — neither reaches this branch, so
93
+ // either would pass while testing nothing.
94
+ const dir = await mkdtemp(join(tmpdir(), "hogsend-plugin-load-"));
95
+ try {
96
+ const file = join(dir, "broken.mjs");
97
+ await writeFile(
98
+ file,
99
+ 'import "totally-not-a-real-package-xyz";\nexport const createTestProvider = () => {};\n',
100
+ );
101
+ const { seen, onFailure } = collect();
102
+ const factory = await loadOptionalPlugin({
103
+ specifier: pathToFileURL(file).href,
104
+ exportName: "createTestProvider",
105
+ enabledBy: "TEST_TOKEN is set",
106
+ onFailure,
107
+ });
108
+ assert.equal(factory, null);
109
+ assert.equal(seen[0]?.outcome, "load-failed");
110
+ assert.doesNotMatch(seen[0]?.message ?? "", /is not installed/);
111
+ // The missing package must be named, or the operator learns nothing.
112
+ assert.match(seen[0]?.message ?? "", /totally-not-a-real-package-xyz/);
113
+ } finally {
114
+ await rm(dir, { recursive: true, force: true });
115
+ }
116
+ });
117
+
118
+ test("resolvable but missing the named export → missing-export, flags version skew", async () => {
119
+ const { seen, onFailure } = collect();
120
+ const factory = await loadOptionalPlugin({
121
+ specifier: "node:path",
122
+ exportName: "createApolloProvider",
123
+ enabledBy: "APOLLO_API_KEY is set",
124
+ onFailure,
125
+ });
126
+ assert.equal(factory, null);
127
+ assert.equal(seen[0]?.outcome, "missing-export");
128
+ assert.match(
129
+ seen[0]?.message ?? "",
130
+ /does not export "createApolloProvider"/,
131
+ );
132
+ assert.match(seen[0]?.message ?? "", /version/);
133
+ });