@hogsend/engine 0.42.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.
@@ -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
+ }