@hogsend/engine 0.52.1 → 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
+ }
package/src/lib/links.ts CHANGED
@@ -59,6 +59,15 @@ export interface MintLinkOptions {
59
59
  * OAuth redirect_uri destinations.
60
60
  */
61
61
  appendRef?: boolean;
62
+ /**
63
+ * Idempotent-mint key for slugless links: re-minting with the same key +
64
+ * same destination returns the EXISTING link (`existing: true`) instead of
65
+ * a duplicate; same key + different destination is an
66
+ * IdempotencyConflictError (→ 409). Unique among LIVE links only (partial
67
+ * index) — archiving frees the key. Mutually exclusive with `slug` (a slug
68
+ * IS an idempotency key: same slug + same url + same type recovers too).
69
+ */
70
+ idempotencyKey?: string;
62
71
  }
63
72
 
64
73
  export interface MintedLink {
@@ -72,6 +81,11 @@ export interface MintedLink {
72
81
  slug: string | null;
73
82
  /** The vanity short URL (`${baseUrl}/l/:slug`), if a slug was minted. */
74
83
  vanityUrl: string | null;
84
+ /**
85
+ * True when the mint RECOVERED an existing live link (same slug or
86
+ * idempotencyKey + same destination) instead of inserting a new one.
87
+ */
88
+ existing: boolean;
75
89
  }
76
90
 
77
91
  // ---------------------------------------------------------------------------
@@ -105,11 +119,12 @@ export function normalizeSlug(raw: string): string {
105
119
  }
106
120
 
107
121
  /**
108
- * True when a DB error is the Postgres unique_violation on the slug index.
109
- * Walks the cause chain — drizzle wraps the driver's PostgresError in a
110
- * DrizzleQueryError whose `cause` carries the actual code/constraint.
122
+ * True when a DB error is the Postgres unique_violation on the named
123
+ * constraint. Walks the cause chain — drizzle wraps the driver's
124
+ * PostgresError in a DrizzleQueryError whose `cause` carries the actual
125
+ * code/constraint.
111
126
  */
112
- export function isSlugUniqueViolation(err: unknown): boolean {
127
+ function isUniqueViolationOn(err: unknown, constraint: string): boolean {
113
128
  for (let e = err, depth = 0; e && depth < 5; depth++) {
114
129
  const candidate = e as {
115
130
  code?: string;
@@ -119,8 +134,8 @@ export function isSlugUniqueViolation(err: unknown): boolean {
119
134
  };
120
135
  if (
121
136
  candidate.code === "23505" &&
122
- (candidate.constraint_name === "links_slug_unique" ||
123
- (candidate.message?.includes("links_slug_unique") ?? false))
137
+ (candidate.constraint_name === constraint ||
138
+ (candidate.message?.includes(constraint) ?? false))
124
139
  ) {
125
140
  return true;
126
141
  }
@@ -129,6 +144,31 @@ export function isSlugUniqueViolation(err: unknown): boolean {
129
144
  return false;
130
145
  }
131
146
 
147
+ /** True when a DB error is the unique_violation on the slug index. */
148
+ export function isSlugUniqueViolation(err: unknown): boolean {
149
+ return isUniqueViolationOn(err, "links_slug_unique");
150
+ }
151
+
152
+ /**
153
+ * True when a DB error is the unique_violation on the partial (live-rows-only)
154
+ * idempotency-key index.
155
+ */
156
+ export function isIdempotencyKeyViolation(err: unknown): boolean {
157
+ return isUniqueViolationOn(err, "links_idempotency_key_unique");
158
+ }
159
+
160
+ /**
161
+ * Thrown when an idempotencyKey is already held by a LIVE link with a
162
+ * DIFFERENT destination → HTTP 409. (Same destination is not a conflict — it
163
+ * recovers the existing link.)
164
+ */
165
+ export class IdempotencyConflictError extends Error {
166
+ constructor(key: string) {
167
+ super(`Idempotency key "${key}" already used for a different destination`);
168
+ this.name = "IdempotencyConflictError";
169
+ }
170
+ }
171
+
132
172
  export function vanityUrlFor(baseUrl: string, slug: string): string {
133
173
  return `${baseUrl}/l/${slug}`;
134
174
  }
@@ -240,8 +280,39 @@ export function assertHttpUrl(url: string): void {
240
280
  }
241
281
  }
242
282
 
283
+ /**
284
+ * Build the MintedLink for an already-existing LIVE links row (idempotent
285
+ * recovery): resolves its CANONICAL tracked row (the redirect row, never the
286
+ * lazily-minted QR scan row) via the shared canonical-row predicate. Returns
287
+ * null if the link somehow has no tracked row — callers fall back to their
288
+ * conflict path rather than fabricating a dead redirect URL.
289
+ */
290
+ async function recoverExistingLink(
291
+ db: Database,
292
+ baseUrl: string,
293
+ row: { id: string; slug: string | null },
294
+ ): Promise<MintedLink | null> {
295
+ const [tracked] = await db
296
+ .select({ id: sql<string | null>`min(${trackedLinks.id}::text)` })
297
+ .from(trackedLinks)
298
+ .where(and(eq(trackedLinks.linkId, row.id), canonicalTrackedRowFilter()));
299
+ const trackedLinkId = tracked?.id ?? null;
300
+ if (!trackedLinkId) return null;
301
+ return {
302
+ linkId: row.id,
303
+ trackedLinkId,
304
+ url: `${baseUrl}/v1/t/c/${trackedLinkId}`,
305
+ slug: row.slug,
306
+ vanityUrl: row.slug ? vanityUrlFor(baseUrl, row.slug) : null,
307
+ existing: true,
308
+ };
309
+ }
310
+
243
311
  export async function mintLink(opts: MintLinkOptions): Promise<MintedLink> {
244
312
  assertHttpUrl(opts.url);
313
+ if (opts.slug !== undefined && opts.idempotencyKey !== undefined) {
314
+ throw new Error("mintLink: slug and idempotencyKey are mutually exclusive");
315
+ }
245
316
  const type: LinkType = opts.type ?? "public";
246
317
  // A public link must NEVER carry a person token — drop any distinctId.
247
318
  const distinctId = type === "personal" ? (opts.distinctId ?? null) : null;
@@ -267,6 +338,7 @@ export async function mintLink(opts: MintLinkOptions): Promise<MintedLink> {
267
338
  source: opts.source,
268
339
  distinctId,
269
340
  createdBy: opts.createdBy ?? null,
341
+ idempotencyKey: opts.idempotencyKey ?? null,
270
342
  });
271
343
  await tx.insert(trackedLinks).values({
272
344
  id: trackedLinkId,
@@ -278,7 +350,45 @@ export async function mintLink(opts: MintLinkOptions): Promise<MintedLink> {
278
350
  });
279
351
  });
280
352
  } catch (err) {
281
- if (slug && isSlugUniqueViolation(err)) throw new SlugTakenError(slug);
353
+ // Idempotent recovery. NOTE: these queries run AFTER the aborted
354
+ // transaction, on opts.db directly — the tx object is dead.
355
+ if (slug && isSlugUniqueViolation(err)) {
356
+ // A slug re-mint with the SAME destination + type is the same intent —
357
+ // return the existing LIVE link instead of 409ing a retry.
358
+ const [row] = await opts.db
359
+ .select()
360
+ .from(links)
361
+ .where(and(eq(links.slug, slug), isNull(links.archivedAt)))
362
+ .limit(1);
363
+ if (row && row.originalUrl === opts.url && row.type === type) {
364
+ const recovered = await recoverExistingLink(opts.db, opts.baseUrl, row);
365
+ if (recovered) return recovered;
366
+ }
367
+ // Slug held by an ARCHIVED link (the live lookup misses — archived
368
+ // links keep their slug reserved), a different destination, or a
369
+ // different type → conflict.
370
+ throw new SlugTakenError(slug);
371
+ }
372
+ if (opts.idempotencyKey && isIdempotencyKeyViolation(err)) {
373
+ const [row] = await opts.db
374
+ .select()
375
+ .from(links)
376
+ .where(
377
+ and(
378
+ eq(links.idempotencyKey, opts.idempotencyKey),
379
+ isNull(links.archivedAt),
380
+ ),
381
+ )
382
+ .limit(1);
383
+ if (row && row.originalUrl === opts.url) {
384
+ const recovered = await recoverExistingLink(opts.db, opts.baseUrl, row);
385
+ if (recovered) return recovered;
386
+ }
387
+ if (row) throw new IdempotencyConflictError(opts.idempotencyKey);
388
+ // Defensive: the partial index only covers live rows, so the winning
389
+ // row should always be live — if it vanished, surface the raw error.
390
+ throw err;
391
+ }
282
392
  throw err;
283
393
  }
284
394
 
@@ -288,5 +398,6 @@ export async function mintLink(opts: MintLinkOptions): Promise<MintedLink> {
288
398
  url: `${opts.baseUrl}/v1/t/c/${trackedLinkId}`,
289
399
  slug,
290
400
  vanityUrl: slug ? vanityUrlFor(opts.baseUrl, slug) : null,
401
+ existing: false,
291
402
  };
292
403
  }
@@ -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;