@hogsend/engine 0.41.0 → 0.43.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 (43) hide show
  1. package/package.json +12 -9
  2. package/src/container.ts +192 -4
  3. package/src/env.ts +28 -0
  4. package/src/index.ts +53 -0
  5. package/src/journeys/execute-journey-run.ts +50 -17
  6. package/src/journeys/journey-boundary.ts +5 -1
  7. package/src/journeys/journey-context.ts +58 -0
  8. package/src/lib/blueprint-lock.ts +21 -0
  9. package/src/lib/blueprints.ts +273 -46
  10. package/src/lib/event-names.ts +143 -0
  11. package/src/lib/journey-suppress.ts +33 -2
  12. package/src/lib/outbound.ts +58 -0
  13. package/src/lib/phone.ts +19 -0
  14. package/src/lib/preferences.ts +32 -0
  15. package/src/lib/sms-frequency-cap.ts +47 -0
  16. package/src/lib/sms-inbound.ts +200 -0
  17. package/src/lib/sms-link-tracking.ts +160 -0
  18. package/src/lib/sms-mailer.ts +338 -0
  19. package/src/lib/sms-provider-registry.ts +35 -0
  20. package/src/lib/sms-providers-from-env.ts +100 -0
  21. package/src/lib/sms-service-types.ts +169 -0
  22. package/src/lib/sms-tracked.ts +590 -0
  23. package/src/lib/sms.ts +117 -0
  24. package/src/lib/tracking-event-names.ts +6 -0
  25. package/src/lib/tracking-events.ts +107 -1
  26. package/src/lib/tracking.ts +3 -6
  27. package/src/lib/webhook-signing.ts +17 -1
  28. package/src/lists/channels.ts +21 -0
  29. package/src/mcp/authoring-guide.ts +160 -0
  30. package/src/mcp/blueprint-tools.ts +38 -108
  31. package/src/middleware/require-admin.ts +13 -0
  32. package/src/routes/admin/api-keys.ts +72 -0
  33. package/src/routes/admin/blueprints.ts +94 -10
  34. package/src/routes/admin/events.ts +55 -0
  35. package/src/routes/email/unsubscribe.ts +1 -0
  36. package/src/routes/index.ts +6 -0
  37. package/src/routes/lists/index.ts +54 -7
  38. package/src/routes/tracking/click-pipeline.ts +83 -2
  39. package/src/routes/tracking/short.ts +61 -0
  40. package/src/routes/webhooks/index.ts +5 -1
  41. package/src/routes/webhooks/sms-provider.ts +110 -0
  42. package/src/workflows/import-contacts.ts +61 -4
  43. package/src/workflows/journey-blueprint-interpreter.ts +128 -33
@@ -76,6 +76,19 @@ export interface OutboundPayloads {
76
76
  category: string | null;
77
77
  scope: "all" | "category";
78
78
  };
79
+ /**
80
+ * A genuine opt-IN (resubscribe-all or a category/channel grant) — the
81
+ * mirror of `contact.unsubscribed`, emitted from the same preference-write
82
+ * choke. `source` is the grant provenance: `"api"` (default),
83
+ * `"preference_center"`, `"started_keyword"`, `"import"`.
84
+ */
85
+ "contact.subscribed": {
86
+ externalId: string | null;
87
+ email: string | null;
88
+ category: string | null;
89
+ scope: "all" | "category";
90
+ source: string;
91
+ };
79
92
  "email.sent": {
80
93
  emailSendId: string;
81
94
  messageId: string;
@@ -152,6 +165,51 @@ export interface OutboundPayloads {
152
165
  complaintType?: string;
153
166
  reason?: string;
154
167
  };
168
+ "sms.sent": {
169
+ smsSendId: string;
170
+ messageId: string;
171
+ templateKey: string | null;
172
+ to: string;
173
+ userId: string | null;
174
+ category: string | null;
175
+ journeyStateId: string | null;
176
+ segments: number | null;
177
+ sentAt: string;
178
+ };
179
+ "sms.delivered": {
180
+ smsSendId: string;
181
+ messageId: string;
182
+ templateKey: string | null;
183
+ userId: string | null;
184
+ to: string;
185
+ at: string;
186
+ };
187
+ "sms.failed": {
188
+ smsSendId: string;
189
+ messageId: string;
190
+ templateKey: string | null;
191
+ userId: string | null;
192
+ to: string;
193
+ at: string;
194
+ errorCode?: string;
195
+ errorReason?: string;
196
+ };
197
+ /**
198
+ * A tracked SMS short link was clicked (first-party, PER-HIT — the SMS
199
+ * sibling of `email.clicked`). `linkId` is the `tracked_links.id`,
200
+ * `linkUrl` the original destination. `userId` is null for a raw send with
201
+ * no resolvable contact.
202
+ */
203
+ "sms.clicked": {
204
+ smsSendId: string;
205
+ messageId: string | null;
206
+ templateKey: string | null;
207
+ userId: string | null;
208
+ to: string;
209
+ at: string;
210
+ linkUrl: string;
211
+ linkId: string;
212
+ };
155
213
  "journey.completed": {
156
214
  journeyId: string;
157
215
  journeyName: string;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Strict E.164 normalization. Strips common human separators (spaces, dashes,
3
+ * parens, dots) then requires a leading `+`, a non-zero country digit, and
4
+ * 7–15 total digits (the E.164 max is 15). Fail-closed: anything that doesn't
5
+ * match returns `null` — the caller rejects it rather than guessing a country
6
+ * code (no libphonenumber dependency, no implicit `+1`).
7
+ */
8
+ export function normalizePhone(
9
+ input: string | null | undefined,
10
+ ): string | null {
11
+ if (!input) return null;
12
+ const stripped = input.trim().replace(/[\s\-().]/g, "");
13
+ return /^\+[1-9]\d{6,14}$/.test(stripped) ? stripped : null;
14
+ }
15
+
16
+ /** Whether `input` is already a valid E.164 number (post-normalization). */
17
+ export function isE164(input: string | null | undefined): boolean {
18
+ return normalizePhone(input) !== null;
19
+ }
@@ -43,6 +43,12 @@ export async function upsertEmailPreference(opts: {
43
43
  categoryValue?: boolean;
44
44
  };
45
45
  emitOutbound?: boolean;
46
+ /**
47
+ * Grant provenance carried on the `contact.subscribed` emit: `"api"`
48
+ * (default), `"preference_center"`, `"started_keyword"`, `"import"`.
49
+ * TCPA record-keeping is the "how" as much as the "when".
50
+ */
51
+ source?: string;
46
52
  }): Promise<void> {
47
53
  const { db, externalId, email, update } = opts;
48
54
 
@@ -119,6 +125,32 @@ export async function upsertEmailPreference(opts: {
119
125
  },
120
126
  }).catch(logger.warn);
121
127
  }
128
+
129
+ // The opt-IN mirror: `contact.subscribed` on a genuine grant (resubscribe-all
130
+ // or a category flip to true) — the consent audit signal for opt-in channels
131
+ // (the explicit-consent `sms` channel above all). Same choke, same
132
+ // fire-and-forget semantics, same `emitOutbound: false` escape for bulk
133
+ // imports. A redundant re-grant re-emits, identical to the opt-out side.
134
+ const isSubscribe =
135
+ !isUnsubscribe &&
136
+ (update.unsubscribedAll === false || update.categoryValue === true);
137
+ if (isSubscribe && (opts.emitOutbound ?? true)) {
138
+ const scope: "all" | "category" =
139
+ update.categoryKey !== undefined ? "category" : "all";
140
+ void emitOutbound({
141
+ db,
142
+ hatchet,
143
+ logger,
144
+ event: "contact.subscribed",
145
+ payload: {
146
+ externalId,
147
+ email,
148
+ category: update.categoryKey ?? null,
149
+ scope,
150
+ source: opts.source ?? "api",
151
+ },
152
+ }).catch(logger.warn);
153
+ }
122
154
  }
123
155
 
124
156
  /**
@@ -0,0 +1,47 @@
1
+ import { durationToMs } from "@hogsend/core";
2
+ import type { Database } from "@hogsend/db";
3
+ import { smsSends } from "@hogsend/db";
4
+ import { and, count, eq, gte, ne } from "drizzle-orm";
5
+ import type { FrequencyCapConfig } from "./email-service-types.js";
6
+
7
+ const DEFAULT_EXEMPT = ["transactional"];
8
+
9
+ /**
10
+ * The SMS sibling of {@link isFrequencyCapped}: true if this recipient has hit
11
+ * the configured send cap within the window, counted over `sms_sends` by
12
+ * `to_phone` (served by `sms_sends_freq_cap_idx`). Kept SEPARATE from the email
13
+ * cap so email and SMS budgets never consume each other. Failed rows are
14
+ * excluded; an exempt category (default "transactional") short-circuits.
15
+ */
16
+ export async function isSmsFrequencyCapped(opts: {
17
+ db: Database;
18
+ to: string;
19
+ category?: string;
20
+ config?: FrequencyCapConfig;
21
+ }): Promise<boolean> {
22
+ const { db, to, category, config } = opts;
23
+ if (!config) return false;
24
+
25
+ const exempt = config.exemptCategories ?? DEFAULT_EXEMPT;
26
+ if (category && exempt.includes(category)) return false;
27
+
28
+ const override = category ? config.byCategory?.[category] : undefined;
29
+ const rule = override ?? { count: config.count, window: config.window };
30
+ const since = new Date(Date.now() - durationToMs(rule.window));
31
+
32
+ const conditions = [
33
+ eq(smsSends.toPhone, to),
34
+ gte(smsSends.createdAt, since),
35
+ ne(smsSends.status, "failed"),
36
+ ];
37
+ if (override && category) {
38
+ conditions.push(eq(smsSends.category, category));
39
+ }
40
+
41
+ const [row] = await db
42
+ .select({ n: count() })
43
+ .from(smsSends)
44
+ .where(and(...conditions));
45
+
46
+ return (row?.n ?? 0) >= rule.count;
47
+ }
@@ -0,0 +1,200 @@
1
+ import type { SmsEvent, SmsProvider } from "@hogsend/core";
2
+ import type { Database } from "@hogsend/db";
3
+ import { contacts, smsSuppressions } from "@hogsend/db";
4
+ import { and, eq, isNull } from "drizzle-orm";
5
+ import type { Logger } from "./logger.js";
6
+ import { upsertEmailPreference } from "./preferences.js";
7
+ import { SMS_CHANNEL_ID } from "./sms-tracked.js";
8
+
9
+ /** Standard opt-out keywords (case-insensitive, punctuation-stripped). */
10
+ const STOP_KEYWORDS = new Set([
11
+ "STOP",
12
+ "STOPALL",
13
+ "UNSUBSCRIBE",
14
+ "CANCEL",
15
+ "END",
16
+ "QUIT",
17
+ ]);
18
+ /** Standard resubscribe keywords. */
19
+ const START_KEYWORDS = new Set(["START", "UNSTOP", "YES"]);
20
+ const HELP_KEYWORDS = new Set(["HELP", "INFO"]);
21
+
22
+ /** Normalize an inbound body to a single keyword token for matching. */
23
+ export function normalizeKeyword(body: string): string {
24
+ return body
25
+ .trim()
26
+ .replace(/[^a-zA-Z]/g, "")
27
+ .toUpperCase();
28
+ }
29
+
30
+ /**
31
+ * The FIRST whitespace-delimited token, letter-normalized. Matched alongside
32
+ * the whole-message keyword so "STOP texting me" / "STOP please" still opt
33
+ * out — the whole-message normalization concatenates ("STOPTEXTINGME") and
34
+ * misses them. Exact single-keyword matching is the carrier norm, but honoring
35
+ * a leading keyword costs nothing and only ever widens opt-out (never opt-in
36
+ * beyond START itself leading the message).
37
+ */
38
+ function firstToken(body: string): string {
39
+ return normalizeKeyword(body.trim().split(/\s+/)[0] ?? "");
40
+ }
41
+
42
+ interface InboundDeps {
43
+ db: Database;
44
+ provider: SmsProvider;
45
+ logger: Logger;
46
+ /** Send STOP/START/HELP confirmation replies (default off). */
47
+ optOutReplies?: boolean;
48
+ from?: string;
49
+ }
50
+
51
+ /**
52
+ * Handle a normalized inbound (mobile-originated) SMS. Detects STOP/START/HELP
53
+ * keywords and records the opt-out in BOTH tracks: the phone-keyed
54
+ * `sms_suppressions` table (authoritative — works even for a number with no
55
+ * contact) and, when the phone resolves to a contact with an email, the `sms`
56
+ * channel category on `email_preferences` (keeps the preference center
57
+ * consistent and reuses the single `upsertEmailPreference` write choke, which
58
+ * emits `contact.unsubscribed`). TCPA/CTIA compliant.
59
+ */
60
+ export async function handleInboundSms(
61
+ event: SmsEvent,
62
+ deps: InboundDeps,
63
+ ): Promise<void> {
64
+ if (event.type !== "sms.inbound" || !event.inbound) return;
65
+ const phone = event.phone;
66
+ const keyword = normalizeKeyword(event.inbound.body);
67
+ const lead = firstToken(event.inbound.body);
68
+
69
+ if (STOP_KEYWORDS.has(keyword) || STOP_KEYWORDS.has(lead)) {
70
+ await recordPhoneOptOut(deps.db, phone, "inbound_stop");
71
+ await flipContactChannel(deps.db, phone, false, "stopped_keyword");
72
+ deps.logger.info("sms inbound STOP processed", { phone, keyword });
73
+ if (deps.optOutReplies) {
74
+ await safeReply(
75
+ deps,
76
+ phone,
77
+ "You have been unsubscribed. Reply START to resubscribe.",
78
+ );
79
+ }
80
+ return;
81
+ }
82
+
83
+ if (START_KEYWORDS.has(keyword)) {
84
+ await grantPhoneConsent(deps.db, phone, { reason: "inbound_start" });
85
+ await flipContactChannel(deps.db, phone, true, "started_keyword");
86
+ deps.logger.info("sms inbound START processed", { phone, keyword });
87
+ if (deps.optOutReplies) {
88
+ await safeReply(deps, phone, "You have been resubscribed.");
89
+ }
90
+ return;
91
+ }
92
+
93
+ if (
94
+ (HELP_KEYWORDS.has(keyword) || HELP_KEYWORDS.has(lead)) &&
95
+ deps.optOutReplies
96
+ ) {
97
+ await safeReply(
98
+ deps,
99
+ phone,
100
+ "Reply STOP to unsubscribe. Msg & data rates may apply.",
101
+ );
102
+ }
103
+ }
104
+
105
+ /** Suppress a phone (STOP / manual). Upsert: re-STOP after START resets the flag. */
106
+ export async function recordPhoneOptOut(
107
+ db: Database,
108
+ phone: string,
109
+ reason: "inbound_stop" | "manual",
110
+ ): Promise<void> {
111
+ const now = new Date();
112
+ await db
113
+ .insert(smsSuppressions)
114
+ .values({ phone, reason, suppressedAt: now })
115
+ .onConflictDoUpdate({
116
+ target: smsSuppressions.phone,
117
+ set: {
118
+ reason,
119
+ suppressedAt: now,
120
+ resubscribedAt: null,
121
+ updatedAt: now,
122
+ },
123
+ });
124
+ }
125
+
126
+ /**
127
+ * Record express phone-level consent: an `sms_suppressions` row with
128
+ * `resubscribed_at` set. Under the explicit opt-in model this row IS the
129
+ * consent record for a number with no (or a phone-only) contact — texting
130
+ * START is express consent, so a fresh START with no prior STOP row must
131
+ * still grant (hence upsert, not update).
132
+ */
133
+ export async function grantPhoneConsent(
134
+ db: Database,
135
+ phone: string,
136
+ opts?: { reason?: "inbound_start" | "api_grant" },
137
+ ): Promise<void> {
138
+ const now = new Date();
139
+ await db
140
+ .insert(smsSuppressions)
141
+ .values({
142
+ phone,
143
+ reason: opts?.reason ?? "inbound_start",
144
+ suppressedAt: now,
145
+ resubscribedAt: now,
146
+ })
147
+ .onConflictDoUpdate({
148
+ target: smsSuppressions.phone,
149
+ set: { resubscribedAt: now, updatedAt: now },
150
+ });
151
+ }
152
+
153
+ /**
154
+ * When the phone resolves to a contact with an email, flip the `sms` channel
155
+ * category on `email_preferences` so the preference center agrees with the
156
+ * suppression list. `false` emits `contact.unsubscribed`; `true` (a consent
157
+ * grant) emits `contact.subscribed` — both from the single write choke, with
158
+ * the keyword provenance in `source`.
159
+ */
160
+ async function flipContactChannel(
161
+ db: Database,
162
+ phone: string,
163
+ subscribed: boolean,
164
+ source: string,
165
+ ): Promise<void> {
166
+ const rows = await db
167
+ .select({
168
+ id: contacts.id,
169
+ externalId: contacts.externalId,
170
+ email: contacts.email,
171
+ })
172
+ .from(contacts)
173
+ .where(and(eq(contacts.phone, phone), isNull(contacts.deletedAt)))
174
+ .limit(1);
175
+ const contact = rows[0];
176
+ if (!contact?.email) return;
177
+ await upsertEmailPreference({
178
+ db,
179
+ externalId: contact.externalId ?? contact.id,
180
+ email: contact.email,
181
+ update: { categoryKey: SMS_CHANNEL_ID, categoryValue: subscribed },
182
+ source,
183
+ });
184
+ }
185
+
186
+ /** Send a confirmation reply, swallowing errors (never fail the webhook). */
187
+ async function safeReply(
188
+ deps: InboundDeps,
189
+ to: string,
190
+ body: string,
191
+ ): Promise<void> {
192
+ try {
193
+ await deps.provider.send({ to, body, from: deps.from });
194
+ } catch (err) {
195
+ deps.logger.warn("sms confirmation reply failed", {
196
+ to,
197
+ error: err instanceof Error ? err.message : String(err),
198
+ });
199
+ }
200
+ }
@@ -0,0 +1,160 @@
1
+ import { randomBytes } from "node:crypto";
2
+ import { shouldSkipUrl } from "./tracking.js";
3
+
4
+ /**
5
+ * SMS link shortening — the plain-text sibling of `rewriteLinks` (which is
6
+ * HTML-anchor/email-only). `planSmsLinkRewrite` is PURE: it returns the
7
+ * rewritten body plus the pending `tracked_links` rows; the caller inserts
8
+ * them in the SAME transaction as the `sms_sends` row (the FK forces the
9
+ * order, and the transaction closes both crash windows — no queued row ever
10
+ * carries codes whose tracked rows are missing, and a short-code unique
11
+ * collision rolls the whole attempt back for a clean replan).
12
+ *
13
+ * Why short links at all: a full `/v1/t/c/<uuid>` tracking URL eats a third
14
+ * of a 160-char GSM-7 segment, and US carriers filter public shorteners —
15
+ * first-party short codes on the operator's own domain are the practice.
16
+ */
17
+
18
+ /**
19
+ * Crockford-style base32 (no `i l o u`), all GSM-7 basic-set characters — a
20
+ * code can never flip a message to UCS-2. 8 chars = 40 bits: birthday
21
+ * collision odds reach 50% only around ~1.2M live codes; the insert-time
22
+ * unique index + replan retry is a correctness backstop, not an expected path.
23
+ */
24
+ export const SHORT_CODE_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
25
+ export const SHORT_CODE_LENGTH = 8;
26
+
27
+ export function generateShortCode(): string {
28
+ // 256 / 32 is exact, so byte % 32 carries no modulo bias.
29
+ const bytes = randomBytes(SHORT_CODE_LENGTH);
30
+ let out = "";
31
+ for (const b of bytes) {
32
+ out += SHORT_CODE_ALPHABET[b % SHORT_CODE_ALPHABET.length];
33
+ }
34
+ return out;
35
+ }
36
+
37
+ export interface PendingSmsLink {
38
+ shortCode: string;
39
+ originalUrl: string;
40
+ }
41
+
42
+ export interface SmsLinkRewritePlan {
43
+ /** The body with every rewritable URL replaced by `${linkHost}/s/${code}`. */
44
+ body: string;
45
+ /** One entry per DISTINCT rewritten URL (occurrences share one code). */
46
+ links: PendingSmsLink[];
47
+ }
48
+
49
+ const BARE_URL_RE = /https?:\/\/[^\s<>"']+/gi;
50
+
51
+ /** Trailing punctuation that reads as sentence punctuation, not URL. */
52
+ const TRAILING_PUNCT = new Set([".", ",", "!", "?", ";", ":", "'", '"']);
53
+
54
+ /**
55
+ * Strip sentence punctuation from the end of a bare-URL match — the classic
56
+ * bare-URL-regex bug ("Visit https://x.com/a." must not link the dot).
57
+ * Closing brackets are stripped only when UNBALANCED within the URL, so
58
+ * `https://en.wikipedia.org/wiki/Foo_(bar)` keeps its paren while
59
+ * `(see https://x.com)` loses it.
60
+ */
61
+ function trimTrailingPunctuation(url: string): string {
62
+ let end = url.length;
63
+ while (end > 0) {
64
+ const ch = url[end - 1] as string;
65
+ if (TRAILING_PUNCT.has(ch)) {
66
+ end -= 1;
67
+ continue;
68
+ }
69
+ if (ch === ")" || ch === "]") {
70
+ const open = ch === ")" ? "(" : "[";
71
+ const slice = url.slice(0, end);
72
+ const opens = slice.split(open).length - 1;
73
+ const closes = slice.split(ch).length - 1;
74
+ if (closes > opens) {
75
+ end -= 1;
76
+ continue;
77
+ }
78
+ }
79
+ break;
80
+ }
81
+ return url.slice(0, end);
82
+ }
83
+
84
+ /**
85
+ * Pure rewrite pass over a rendered SMS body. Skips unsubscribe/preference
86
+ * URLs (shared `shouldSkipUrl`) and the engine's OWN short/vanity/tracking
87
+ * URLs (`/s/`, `/l/`, `/v1/t/` under `linkHost`) — a pasted tracked URL
88
+ * already counts its click; wrapping it would add a hop and double-count.
89
+ *
90
+ * `generateCode` is injectable for deterministic tests.
91
+ */
92
+ export function planSmsLinkRewrite(opts: {
93
+ body: string;
94
+ /** Full origin the short links are served from, no trailing slash. */
95
+ linkHost: string;
96
+ generateCode?: () => string;
97
+ }): SmsLinkRewritePlan {
98
+ const { body, linkHost } = opts;
99
+ const generate = opts.generateCode ?? generateShortCode;
100
+
101
+ const byUrl = new Map<string, PendingSmsLink>();
102
+ let out = "";
103
+ let cursor = 0;
104
+
105
+ for (const match of body.matchAll(BARE_URL_RE)) {
106
+ const raw = match[0];
107
+ const start = match.index;
108
+ const url = trimTrailingPunctuation(raw);
109
+ if (
110
+ url.length === 0 ||
111
+ shouldSkipUrl(url) ||
112
+ url.startsWith(`${linkHost}/s/`) ||
113
+ url.startsWith(`${linkHost}/l/`) ||
114
+ url.startsWith(`${linkHost}/v1/t/`)
115
+ ) {
116
+ continue;
117
+ }
118
+
119
+ let pending = byUrl.get(url);
120
+ if (!pending) {
121
+ pending = { shortCode: generate(), originalUrl: url };
122
+ byUrl.set(url, pending);
123
+ }
124
+
125
+ // Index-splice (never String.replace — URLs carry regex metachars and a
126
+ // URL that prefixes another would mis-replace).
127
+ out += body.slice(cursor, start);
128
+ out += `${linkHost}/s/${pending.shortCode}`;
129
+ cursor = start + url.length;
130
+ }
131
+
132
+ if (byUrl.size === 0) return { body, links: [] };
133
+ out += body.slice(cursor);
134
+ return { body: out, links: [...byUrl.values()] };
135
+ }
136
+
137
+ /**
138
+ * True when `err` is the `tracked_links_short_code_unique` partial-unique
139
+ * violation (an astronomically-rare 40-bit code collision). Walks the drizzle
140
+ * cause chain for PG 23505, mirroring `isSlugUniqueViolation` in links.ts.
141
+ */
142
+ export function isShortCodeCollision(err: unknown): boolean {
143
+ let candidate: unknown = err;
144
+ while (candidate && typeof candidate === "object") {
145
+ const c = candidate as {
146
+ code?: string;
147
+ constraint_name?: string;
148
+ constraint?: string;
149
+ message?: string;
150
+ cause?: unknown;
151
+ };
152
+ if (c.code === "23505") {
153
+ const constraint = c.constraint_name ?? c.constraint ?? "";
154
+ if (constraint.includes("tracked_links_short_code_unique")) return true;
155
+ return (c.message ?? "").includes("tracked_links_short_code_unique");
156
+ }
157
+ candidate = c.cause;
158
+ }
159
+ return false;
160
+ }