@stacksjs/sms 0.75.139 → 0.75.141

package/dist/inbound.d.ts

@@ -0,0 +1,43 @@
+import { type InboundSmsKind } from './opt-out';
+/**
+ * Which keyword a message is. Twilio's Advanced Opt-Out names it in
+ * `OptOutType` (and knows any custom keywords configured there); otherwise
+ * the standard CTIA keywords decide.
+ */
+export declare function inboundSmsKind(fields: Record<string, string | undefined>): InboundSmsKind;
+export declare function handleTwilioInbound(request: Request, options?: TwilioInboundOptions): Promise<Response>;
+/**
+ * A Twilio "a message comes in" webhook, end to end: verify Twilio's
+ * signature, read the message, record STOP/START in `sms_opt_outs`, tell the
+ * app (so it can switch its own preferences), and answer with TwiML.
+ *
+ * ```ts
+ * // routes: route.post('/sms/inbound', 'Actions/SmsInboundAction').skipCsrf()
+ * export default new Action({ method: 'POST', handle: request => handleTwilioInbound(request, {
+ *   onConsentChange: ({ phone, kind }) => setMarketingSms(phone, kind === 'start'),
+ * }) })
+ * ```
+ *
+ * Point the number's (or messaging service's) incoming-message webhook at
+ * that route, as an HTTP POST.
+ */
+export declare interface InboundConsentChange {
+  phone: string
+  kind: 'stop' | 'start'
+}
+export declare interface InboundSmsMessage {
+  from: string
+  to: string
+  body: string
+  messageId?: string
+  kind: InboundSmsKind
+}
+export declare interface TwilioInboundOptions {
+  authToken?: string
+  publicUrl?: string
+  reply?: boolean
+  appName?: string
+  helpContact?: string
+  onConsentChange?: (change: InboundConsentChange) => unknown
+  onMessage?: (message: InboundSmsMessage) => unknown
+}

package/dist/inbound.js

@@ -0,0 +1 @@
+import process from"node:process";import{verifyTwilioWebhook}from"./compliance";import{classifyInboundSms,inboundSmsReply,normalizePhone,optInPhone,optOutPhone}from"./opt-out";function twiml(message){const escaped=message?.replace(/[&<>"']/g,(c)=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&apos;"})[c]),body=escaped?`<?xml version="1.0" encoding="UTF-8"?><Response><Message>${escaped}</Message></Response>`:'<?xml version="1.0" encoding="UTF-8"?><Response></Response>';return new Response(body,{status:200,headers:{"Content-Type":"text/xml; charset=utf-8"}})}function signedUrl(request,publicUrl){if(publicUrl)return publicUrl;const url=new URL(request.url,"http://localhost"),base=String(process.env.APP_URL||"").replace(/\/$/,"");return base?`${base}${url.pathname}${url.search}`:url.href}export function inboundSmsKind(fields){const optOutType=String(fields.OptOutType||"").toUpperCase();if(optOutType==="STOP")return"stop";if(optOutType==="START")return"start";if(optOutType==="HELP")return"help";return classifyInboundSms(fields.Body??"")}export async function handleTwilioInbound(request,options={}){const authToken=options.authToken??process.env.TWILIO_AUTH_TOKEN??"";if(!authToken)return new Response("Inbound SMS is not configured",{status:503});const fields={};for(const[key,value]of new URLSearchParams(await request.text()))fields[key]=value;const signature=request.headers.get("x-twilio-signature")||"";if(!verifyTwilioWebhook(signedUrl(request,options.publicUrl),fields,signature,authToken))return new Response("Invalid signature",{status:403});const from=normalizePhone(fields.From??"");if(!from)return twiml();const kind=inboundSmsKind(fields);if(kind==="stop")await optOutPhone(from);if(kind==="start")await optInPhone(from);if(kind==="stop"||kind==="start")await options.onConsentChange?.({phone:from,kind});await options.onMessage?.({from,to:fields.To??"",body:fields.Body??"",messageId:fields.MessageSid??fields.SmsSid,kind});return twiml(options.reply?inboundSmsReply(kind,options):void 0)}

package/dist/index.d.ts

@@ -4,6 +4,7 @@
  * Provides SMS messaging capabilities with support for multiple providers.
  */
 // Main SMS facade
+export * from './inbound';
 export * from './opt-out';
 export * from './sms';
 export { default as SMS } from './sms';

package/dist/index.js

@@ -1 +1 @@
-export*from"./opt-out";export*from"./sms";export{default as SMS}from"./sms";export*from"./drivers";export{TwilioDriver,createTwilioDriver}from"./drivers/twilio";export{VonageDriver,createVonageDriver}from"./drivers/vonage";export*from"./compliance";
+export*from"./inbound";export*from"./opt-out";export*from"./sms";export{default as SMS}from"./sms";export*from"./drivers";export{TwilioDriver,createTwilioDriver}from"./drivers/twilio";export{VonageDriver,createVonageDriver}from"./drivers/vonage";export*from"./compliance";

package/dist/opt-out.d.ts

@@ -4,10 +4,13 @@ export declare function optOutPhone(phone: string, reason?: string): Promise<voi
 export declare function optInPhone(phone: string): Promise<void>;
 /** Check before EVERY non-emergency send. */
 export declare function isPhoneOptedOut(phone: string): Promise<boolean>;
+/** The compliance reply to a keyword, or undefined for an ordinary message. */
+export declare function inboundSmsReply(kind: InboundSmsKind, options?: { appName?: string, helpContact?: string }): string | undefined;
 /**
  * Process one inbound SMS (a provider webhook's job): record STOP/START,
  * return the compliance reply to send. Ordinary messages pass through as
- * `kind: 'message'` for the app to route (or ignore).
+ * `kind: 'message'` for the app to route (or ignore). For Twilio,
+ * `handleTwilioInbound` does this and the signature check in one call.
  */
 export declare function handleInboundSms(input: { from: string, body: string }, options?: { appName?: string, helpContact?: string }): Promise<InboundSmsResult>;
 export declare interface InboundSmsResult {

package/dist/opt-out.js

@@ -1 +1 @@
-import{db,sqlDateTime}from"@stacksjs/database/runtime";const STOP_WORDS=new Set(["stop","stopall","unsubscribe","cancel","end","quit"]),START_WORDS=new Set(["start","yes","unstop"]),HELP_WORDS=new Set(["help","info"]);export function normalizePhone(raw){const digits=raw.replace(/[^\d+]/g,"");if(/^\d{10}$/.test(digits))return`+1${digits}`;if(/^1\d{10}$/.test(digits))return`+${digits}`;return digits}export function classifyInboundSms(body){const word=body.trim().toLowerCase().split(/\s+/)[0]??"";if(STOP_WORDS.has(word))return"stop";if(START_WORDS.has(word))return"start";if(HELP_WORDS.has(word))return"help";return"message"}export async function optOutPhone(phone,reason="stop-keyword"){const normalized=normalizePhone(phone);if(!normalized)return;await db.deleteFrom("sms_opt_outs").where("phone","=",normalized).execute();await db.insertInto("sms_opt_outs").values({phone:normalized,reason,opted_out_at:sqlDateTime(new Date),created_at:sqlDateTime(new Date),updated_at:sqlDateTime(new Date)}).execute()}export async function optInPhone(phone){const normalized=normalizePhone(phone);if(!normalized)return;await db.deleteFrom("sms_opt_outs").where("phone","=",normalized).execute()}export async function isPhoneOptedOut(phone){const normalized=normalizePhone(phone);if(!normalized)return!1;return!!await db.selectFrom("sms_opt_outs").where("phone","=",normalized).select(["id"]).executeTakeFirst()}export async function handleInboundSms(input,options={}){const kind=classifyInboundSms(input.body),name=options.appName??"this service";switch(kind){case"stop":await optOutPhone(input.from);return{kind,reply:`You are unsubscribed from ${name} texts. No more messages will be sent. Reply START to resubscribe.`};case"start":await optInPhone(input.from);return{kind,reply:`You are resubscribed to ${name} texts. Reply STOP to unsubscribe.`};case"help":return{kind,reply:`${name}: reply STOP to unsubscribe, START to resubscribe.${options.helpContact?` Contact: ${options.helpContact}`:""}`};default:return{kind}}}
+import{db,sqlDateTime}from"@stacksjs/database/runtime";const STOP_WORDS=new Set(["stop","stopall","unsubscribe","cancel","end","quit"]),START_WORDS=new Set(["start","yes","unstop"]),HELP_WORDS=new Set(["help","info"]);export function normalizePhone(raw){const digits=raw.replace(/[^\d+]/g,"");if(/^\d{10}$/.test(digits))return`+1${digits}`;if(/^1\d{10}$/.test(digits))return`+${digits}`;return digits}export function classifyInboundSms(body){const word=body.trim().toLowerCase().split(/\s+/)[0]??"";if(STOP_WORDS.has(word))return"stop";if(START_WORDS.has(word))return"start";if(HELP_WORDS.has(word))return"help";return"message"}export async function optOutPhone(phone,reason="stop-keyword"){const normalized=normalizePhone(phone);if(!normalized)return;await db.deleteFrom("sms_opt_outs").where("phone","=",normalized).execute();await db.insertInto("sms_opt_outs").values({phone:normalized,reason,opted_out_at:sqlDateTime(new Date),created_at:sqlDateTime(new Date),updated_at:sqlDateTime(new Date)}).execute()}export async function optInPhone(phone){const normalized=normalizePhone(phone);if(!normalized)return;await db.deleteFrom("sms_opt_outs").where("phone","=",normalized).execute()}export async function isPhoneOptedOut(phone){const normalized=normalizePhone(phone);if(!normalized)return!1;return!!await db.selectFrom("sms_opt_outs").where("phone","=",normalized).select(["id"]).executeTakeFirst()}export function inboundSmsReply(kind,options={}){const name=options.appName??"this service";if(kind==="stop")return`You are unsubscribed from ${name} texts. No more messages will be sent. Reply START to resubscribe.`;if(kind==="start")return`You are resubscribed to ${name} texts. Reply STOP to unsubscribe.`;if(kind==="help")return`${name}: reply STOP to unsubscribe, START to resubscribe.${options.helpContact?` Contact: ${options.helpContact}`:""}`;return}export async function handleInboundSms(input,options={}){const kind=classifyInboundSms(input.body);if(kind==="stop")await optOutPhone(input.from);if(kind==="start")await optInPhone(input.from);const reply=inboundSmsReply(kind,options);return reply?{kind,reply}:{kind}}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/sms",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.139",
+  "version": "0.75.141",
   "description": "The Stacks SMS integration. Painlessly create & manage your inboxes, templates, and send sms.",
   "author": "Chris Breuer",
   "contributors": [
@@ -63,13 +63,13 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/database": "0.75.139"
+    "@stacksjs/database": "0.75.141"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.75.139",
-    "@stacksjs/config": "0.75.139",
-    "@stacksjs/error-handling": "0.75.139",
-    "@stacksjs/types": "0.75.139",
+    "@stacksjs/cli": "0.75.141",
+    "@stacksjs/config": "0.75.141",
+    "@stacksjs/error-handling": "0.75.141",
+    "@stacksjs/types": "0.75.141",
     "better-dx": "^0.2.24"
   }
 }