@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.
- 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 +20 -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/links.ts +118 -7
- 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
- package/src/routes/admin/links.ts +57 -25
|
@@ -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
|
|
109
|
-
* Walks the cause chain — drizzle wraps the driver's
|
|
110
|
-
* DrizzleQueryError whose `cause` carries the actual
|
|
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
|
-
|
|
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 ===
|
|
123
|
-
(candidate.message?.includes(
|
|
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
|
-
|
|
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
|
}
|
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;
|