@stacksjs/sms 0.70.88 → 0.70.91

package/dist/drivers/gupshup.d.ts

@@ -0,0 +1 @@
+

package/dist/drivers/index.d.ts

@@ -0,0 +1,5 @@
+// Primary SMS Drivers
+export * from './twilio';
+export * from './vonage';
+// Legacy driver aliases
+export * as nexmo from './vonage';

package/dist/drivers/index.js

@@ -0,0 +1,3 @@
+export * from "./twilio";
+export * from "./vonage";
+export * as nexmo from "./vonage";

package/dist/drivers/nexmo.d.ts

@@ -0,0 +1 @@
+

package/dist/drivers/plivo.d.ts

@@ -0,0 +1 @@
+

package/dist/drivers/sms77.d.ts

@@ -0,0 +1 @@
+

package/dist/drivers/sns.d.ts

@@ -0,0 +1 @@
+

package/dist/drivers/telnyx.d.ts

@@ -0,0 +1 @@
+

package/dist/drivers/termii.d.ts

@@ -0,0 +1 @@
+

package/dist/drivers/twilio.d.ts

@@ -0,0 +1,17 @@
+import type { SmsDriver, SmsMessage, SmsSendResult, SmsStatusUpdate, SmsVerificationDriver, TwilioConfig, VerificationCheckRequest, VerificationRequest, VerificationResult } from '@stacksjs/types';
+// =============================================================================
+// Factory Function
+// =============================================================================
+export declare function createTwilioDriver(config: TwilioConfig, verifyServiceSid?: string): TwilioDriver;
+export declare class TwilioDriver implements SmsDriver, SmsVerificationDriver {
+  constructor(config: TwilioConfig, verifyServiceSid?: string);
+  send(message: SmsMessage): Promise<SmsSendResult>;
+  sendBulk(messages: SmsMessage[]): Promise<SmsSendResult[]>;
+  getStatus(messageId: string): Promise<SmsStatusUpdate>;
+  verify(phoneNumber: string): Promise<{ valid: boolean, carrier?: string, type?: string }>;
+  getBalance(): Promise<{ balance: number, currency: string }>;
+  startVerification(request: VerificationRequest): Promise<VerificationResult>;
+  checkVerification(request: VerificationCheckRequest): Promise<VerificationResult>;
+  cancelVerification(verificationId: string): Promise<boolean>;
+}
+export { TwilioDriver as default };

package/dist/drivers/twilio.js

@@ -0,0 +1,263 @@
+const API_BASE = "https://api.twilio.com/2010-04-01", VERIFY_API_BASE = "https://verify.twilio.com/v2";
+async function fetchWithRetry(url, init, maxRetries = 3) {
+  let attempt = 0;
+  while (!0) {
+    const response = await fetch(url, init);
+    if (response.status !== 429 && response.status !== 503)
+      return response;
+    if (attempt >= maxRetries)
+      return response;
+    const retryAfter = Number(response.headers.get("retry-after")) || 2 ** attempt;
+    await new Promise((r) => setTimeout(r, Math.min(retryAfter, 30) * 1000));
+    attempt++;
+  }
+}
+
+export class TwilioDriver {
+  config;
+  verifyServiceSid;
+  constructor(config, verifyServiceSid) {
+    this.config = config;
+    this.verifyServiceSid = verifyServiceSid;
+  }
+  async send(message) {
+    const recipients = Array.isArray(message.to) ? message.to : [message.to];
+    if (recipients.length > 1)
+      return (await this.sendBulk(recipients.map((to) => ({ ...message, to }))))[0] ?? {
+        success: !1,
+        to: recipients[0] ?? "",
+        error: "No recipients supplied",
+        provider: "twilio"
+      };
+    const to = recipients[0];
+    if (!to)
+      return {
+        success: !1,
+        to: "",
+        error: "No recipient supplied",
+        provider: "twilio"
+      };
+    const from = message.from || this.config.from;
+    if (!from && !this.config.messagingServiceSid)
+      return {
+        success: !1,
+        to,
+        error: 'No "from" number or messaging service SID configured',
+        provider: "twilio"
+      };
+    try {
+      const body = new URLSearchParams;
+      body.append("To", to);
+      body.append("Body", message.body);
+      if (this.config.messagingServiceSid)
+        body.append("MessagingServiceSid", this.config.messagingServiceSid);
+      else if (from)
+        body.append("From", from);
+      if (message.statusCallback || this.config.statusCallback)
+        body.append("StatusCallback", message.statusCallback || this.config.statusCallback);
+      if (message.mediaUrls && message.mediaUrls.length > 0)
+        for (const mediaUrl of message.mediaUrls)
+          body.append("MediaUrl", mediaUrl);
+      const response = await fetchWithRetry(`${API_BASE}/Accounts/${this.config.accountSid}/Messages.json`, {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${btoa(`${this.config.accountSid}:${this.config.authToken}`)}`,
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: body.toString()
+      }), data = await response.json();
+      if (!response.ok)
+        return {
+          success: !1,
+          to,
+          error: data.message || `HTTP ${response.status}`,
+          provider: "twilio"
+        };
+      return {
+        success: !0,
+        messageId: data.sid,
+        status: mapTwilioStatus(data.status),
+        to,
+        provider: "twilio",
+        segments: data.num_segments ? Number.parseInt(data.num_segments, 10) : void 0,
+        price: data.price ? Math.abs(Number.parseFloat(data.price)) : void 0,
+        currency: data.price_unit
+      };
+    } catch (error) {
+      return {
+        success: !1,
+        to,
+        error: error instanceof Error ? error.message : "Unknown error",
+        provider: "twilio"
+      };
+    }
+  }
+  async sendBulk(messages) {
+    return Promise.all(messages.map((msg) => this.send(msg)));
+  }
+  async getStatus(messageId) {
+    const response = await fetch(`${API_BASE}/Accounts/${this.config.accountSid}/Messages/${messageId}.json`, {
+      headers: {
+        Authorization: `Basic ${btoa(`${this.config.accountSid}:${this.config.authToken}`)}`
+      }
+    });
+    if (!response.ok)
+      throw Error(`Twilio message status API error: ${response.status}`);
+    const data = await response.json();
+    return {
+      messageId: data.sid,
+      to: data.to,
+      status: mapTwilioStatus(data.status),
+      timestamp: new Date(data.date_updated || data.date_created),
+      errorCode: data.error_code?.toString(),
+      errorMessage: data.error_message
+    };
+  }
+  async verify(phoneNumber) {
+    try {
+      const response = await fetch(`https://lookups.twilio.com/v2/PhoneNumbers/${encodeURIComponent(phoneNumber)}?Fields=line_type_intelligence`, {
+        headers: {
+          Authorization: `Basic ${btoa(`${this.config.accountSid}:${this.config.authToken}`)}`
+        }
+      });
+      if (!response.ok)
+        return { valid: !1 };
+      const data = await response.json();
+      return {
+        valid: data.valid,
+        carrier: data.line_type_intelligence?.carrier_name,
+        type: data.line_type_intelligence?.type
+      };
+    } catch {
+      return { valid: !1 };
+    }
+  }
+  async getBalance() {
+    const response = await fetch(`${API_BASE}/Accounts/${this.config.accountSid}/Balance.json`, {
+      headers: {
+        Authorization: `Basic ${btoa(`${this.config.accountSid}:${this.config.authToken}`)}`
+      }
+    });
+    if (!response.ok)
+      throw Error(`Twilio balance API error: ${response.status}`);
+    const data = await response.json();
+    return {
+      balance: Number.parseFloat(data.balance),
+      currency: data.currency
+    };
+  }
+  async startVerification(request) {
+    if (!this.verifyServiceSid)
+      return {
+        success: !1,
+        status: "denied",
+        error: "Verify service SID not configured"
+      };
+    try {
+      const body = new URLSearchParams;
+      body.append("To", request.to);
+      body.append("Channel", request.channel || "sms");
+      if (request.locale)
+        body.append("Locale", request.locale);
+      if (request.customMessage)
+        body.append("CustomMessage", request.customMessage);
+      const response = await fetch(`${VERIFY_API_BASE}/Services/${this.verifyServiceSid}/Verifications`, {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${btoa(`${this.config.accountSid}:${this.config.authToken}`)}`,
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: body.toString()
+      }), data = await response.json();
+      if (!response.ok)
+        return {
+          success: !1,
+          status: "denied",
+          error: data.message || `HTTP ${response.status}`
+        };
+      return {
+        success: !0,
+        verificationId: data.sid,
+        status: data.status === "pending" ? "pending" : "denied"
+      };
+    } catch (error) {
+      return {
+        success: !1,
+        status: "denied",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  async checkVerification(request) {
+    if (!this.verifyServiceSid)
+      return {
+        success: !1,
+        status: "denied",
+        error: "Verify service SID not configured"
+      };
+    try {
+      const body = new URLSearchParams;
+      body.append("To", request.to);
+      body.append("Code", request.code);
+      const response = await fetch(`${VERIFY_API_BASE}/Services/${this.verifyServiceSid}/VerificationCheck`, {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${btoa(`${this.config.accountSid}:${this.config.authToken}`)}`,
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: body.toString()
+      }), data = await response.json();
+      if (!response.ok)
+        return {
+          success: !1,
+          status: "denied",
+          error: data.message || `HTTP ${response.status}`
+        };
+      return {
+        success: data.status === "approved",
+        verificationId: data.sid,
+        status: data.status === "approved" ? "approved" : "denied"
+      };
+    } catch (error) {
+      return {
+        success: !1,
+        status: "denied",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  async cancelVerification(verificationId) {
+    if (!this.verifyServiceSid)
+      return !1;
+    try {
+      const body = new URLSearchParams;
+      body.append("Status", "canceled");
+      return (await fetch(`${VERIFY_API_BASE}/Services/${this.verifyServiceSid}/Verifications/${verificationId}`, {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${btoa(`${this.config.accountSid}:${this.config.authToken}`)}`,
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: body.toString()
+      })).ok;
+    } catch {
+      return !1;
+    }
+  }
+}
+function mapTwilioStatus(status) {
+  return {
+    queued: "queued",
+    sending: "sending",
+    sent: "sent",
+    delivered: "delivered",
+    undelivered: "undelivered",
+    failed: "failed",
+    canceled: "failed"
+  }[status] || "unknown";
+}
+export function createTwilioDriver(config, verifyServiceSid) {
+  return new TwilioDriver(config, verifyServiceSid);
+}
+
+export { TwilioDriver as default };

package/dist/drivers/vonage.d.ts

@@ -0,0 +1,17 @@
+import type { SmsDriver, SmsMessage, SmsSendResult, SmsStatusUpdate, SmsVerificationDriver, VerificationCheckRequest, VerificationRequest, VerificationResult, VonageConfig } from '@stacksjs/types';
+// =============================================================================
+// Factory Function
+// =============================================================================
+export declare function createVonageDriver(config: VonageConfig, useMessagesApi?: boolean): VonageDriver;
+export declare class VonageDriver implements SmsDriver, SmsVerificationDriver {
+  constructor(config: VonageConfig, useMessagesApi?: boolean);
+  send(message: SmsMessage): Promise<SmsSendResult>;
+  sendBulk(messages: SmsMessage[]): Promise<SmsSendResult[]>;
+  getStatus(messageId: string): Promise<SmsStatusUpdate>;
+  verify(phoneNumber: string): Promise<{ valid: boolean, carrier?: string, type?: string }>;
+  getBalance(): Promise<{ balance: number, currency: string }>;
+  startVerification(request: VerificationRequest): Promise<VerificationResult>;
+  checkVerification(request: VerificationCheckRequest): Promise<VerificationResult>;
+  cancelVerification(verificationId: string): Promise<boolean>;
+}
+export { VonageDriver as default };

package/dist/drivers/vonage.js

@@ -0,0 +1,333 @@
+const API_BASE = "https://rest.nexmo.com", MESSAGES_API_BASE = "https://api.nexmo.com/v1/messages", _VERIFY_API_BASE = "https://api.nexmo.com/verify", VERIFY_V2_API_BASE = "https://api.nexmo.com/v2/verify";
+
+export class VonageDriver {
+  config;
+  useMessagesApi;
+  constructor(config, useMessagesApi = !1) {
+    this.config = config;
+    this.useMessagesApi = useMessagesApi;
+  }
+  async send(message) {
+    const recipients = Array.isArray(message.to) ? message.to : [message.to];
+    if (recipients.length > 1)
+      return (await this.sendBulk(recipients.map((to) => ({ ...message, to }))))[0] ?? {
+        success: !1,
+        to: recipients[0] ?? "",
+        error: "No recipients supplied",
+        provider: "vonage"
+      };
+    const to = recipients[0];
+    if (!to)
+      return {
+        success: !1,
+        to: "",
+        error: "No recipient supplied",
+        provider: "vonage"
+      };
+    const from = message.from || this.config.from;
+    if (!from)
+      return {
+        success: !1,
+        to,
+        error: 'No "from" number configured',
+        provider: "vonage"
+      };
+    if (!/^\+?[1-9]\d{1,14}$/.test(to))
+      return {
+        success: !1,
+        to,
+        error: `Invalid E.164 phone number: ${to}. Expected +<country><number> with 8\u201315 digits.`,
+        provider: "vonage"
+      };
+    try {
+      if (this.useMessagesApi)
+        return await this.sendWithMessagesApi(to, from, message);
+      return await this.sendWithSmsApi(to, from, message);
+    } catch (error) {
+      return {
+        success: !1,
+        to,
+        error: error instanceof Error ? error.message : "Unknown error",
+        provider: "vonage"
+      };
+    }
+  }
+  async sendWithSmsApi(to, from, message) {
+    const body = new URLSearchParams;
+    body.append("api_key", this.config.apiKey);
+    body.append("api_secret", this.config.apiSecret);
+    body.append("to", to);
+    body.append("from", from);
+    body.append("text", message.body);
+    if (message.statusCallback)
+      body.append("callback", message.statusCallback);
+    const response = await fetch(`${API_BASE}/sms/json`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: body.toString()
+    });
+    if (!response.ok)
+      throw Error(`Vonage SMS API error: ${response.status}`);
+    const data = await response.json(), [msg] = data.messages ?? [];
+    if (msg) {
+      if (msg.status !== "0")
+        return {
+          success: !1,
+          to,
+          error: msg["error-text"] || `Status: ${msg.status}`,
+          provider: "vonage"
+        };
+      return {
+        success: !0,
+        messageId: msg["message-id"],
+        status: "sent",
+        to,
+        provider: "vonage",
+        price: msg["message-price"] ? Number.parseFloat(msg["message-price"]) : void 0,
+        currency: "EUR"
+      };
+    }
+    return {
+      success: !1,
+      to,
+      error: "No response from Vonage",
+      provider: "vonage"
+    };
+  }
+  async sendWithMessagesApi(to, from, message) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    let authHeader;
+    if (this.config.applicationId && this.config.privateKey)
+      authHeader = `Bearer ${await this.generateJwt()}`;
+    else
+      authHeader = `Basic ${btoa(`${this.config.apiKey}:${this.config.apiSecret}`)}`;
+    headers.Authorization = authHeader;
+    const body = {
+      message_type: "text",
+      channel: "sms",
+      to,
+      from,
+      text: message.body
+    };
+    if (message.statusCallback)
+      body.webhook_url = message.statusCallback;
+    const response = await fetch(MESSAGES_API_BASE, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    }), data = await response.json();
+    if (!response.ok)
+      return {
+        success: !1,
+        to,
+        error: data.title || data.detail || `HTTP ${response.status}`,
+        provider: "vonage"
+      };
+    return {
+      success: !0,
+      messageId: data.message_uuid,
+      status: "sent",
+      to,
+      provider: "vonage"
+    };
+  }
+  async sendBulk(messages) {
+    return Promise.all(messages.map((msg) => this.send(msg)));
+  }
+  async getStatus(messageId) {
+    const headers = {};
+    if (this.config.applicationId && this.config.privateKey) {
+      const jwt = await this.generateJwt();
+      headers.Authorization = `Bearer ${jwt}`;
+    } else
+      headers.Authorization = `Basic ${btoa(`${this.config.apiKey}:${this.config.apiSecret}`)}`;
+    const response = await fetch(`${MESSAGES_API_BASE}/${messageId}`, {
+      headers
+    });
+    if (!response.ok)
+      throw Error(`Vonage message status API error: ${response.status}`);
+    const data = await response.json();
+    return {
+      messageId: data.message_uuid,
+      to: data.to,
+      status: mapVonageStatus(data.status),
+      timestamp: new Date(data.timestamp),
+      errorCode: data.error?.code?.toString(),
+      errorMessage: data.error?.reason
+    };
+  }
+  async verify(phoneNumber) {
+    try {
+      const body = new URLSearchParams;
+      body.append("api_key", this.config.apiKey);
+      body.append("api_secret", this.config.apiSecret);
+      body.append("number", phoneNumber);
+      const response = await fetch(`${API_BASE}/ni/basic/json`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: body.toString()
+      });
+      if (!response.ok)
+        throw Error(`Vonage number insight API error: ${response.status}`);
+      const data = await response.json();
+      if (data.status !== 0)
+        return { valid: !1 };
+      return {
+        valid: !0,
+        carrier: data.current_carrier?.name,
+        type: data.current_carrier?.network_type
+      };
+    } catch {
+      return { valid: !1 };
+    }
+  }
+  async getBalance() {
+    const auth = typeof Buffer < "u" ? Buffer.from(`${this.config.apiKey}:${this.config.apiSecret}`).toString("base64") : btoa(`${this.config.apiKey}:${this.config.apiSecret}`), response = await fetch(`${API_BASE}/account/get-balance`, {
+      headers: { Authorization: `Basic ${auth}` }
+    });
+    if (!response.ok)
+      throw Error(`Vonage balance API error: ${response.status}`);
+    return {
+      balance: (await response.json()).value,
+      currency: "EUR"
+    };
+  }
+  async startVerification(request) {
+    try {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (this.config.applicationId && this.config.privateKey) {
+        const jwt = await this.generateJwt();
+        headers.Authorization = `Bearer ${jwt}`;
+      } else
+        headers.Authorization = `Basic ${btoa(`${this.config.apiKey}:${this.config.apiSecret}`)}`;
+      const body = {
+        brand: this.config.from || "Verification",
+        workflow: [
+          {
+            channel: request.channel === "whatsapp" ? "whatsapp_interactive" : "sms",
+            to: request.to
+          }
+        ]
+      };
+      if (request.codeLength)
+        body.code_length = request.codeLength;
+      if (request.locale)
+        body.locale = request.locale;
+      const response = await fetch(VERIFY_V2_API_BASE, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body)
+      }), data = await response.json();
+      if (!response.ok)
+        return {
+          success: !1,
+          status: "denied",
+          error: data.title || data.detail || `HTTP ${response.status}`
+        };
+      return {
+        success: !0,
+        verificationId: data.request_id,
+        status: "pending"
+      };
+    } catch (error) {
+      return {
+        success: !1,
+        status: "denied",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  async checkVerification(request) {
+    if (!request.verificationId)
+      return {
+        success: !1,
+        status: "denied",
+        error: "Verification ID is required"
+      };
+    try {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (this.config.applicationId && this.config.privateKey) {
+        const jwt = await this.generateJwt();
+        headers.Authorization = `Bearer ${jwt}`;
+      } else
+        headers.Authorization = `Basic ${btoa(`${this.config.apiKey}:${this.config.apiSecret}`)}`;
+      const response = await fetch(`${VERIFY_V2_API_BASE}/${request.verificationId}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ code: request.code })
+      }), data = await response.json();
+      if (!response.ok)
+        return {
+          success: !1,
+          status: "denied",
+          error: data.title || data.detail || `HTTP ${response.status}`
+        };
+      return {
+        success: data.status === "completed",
+        verificationId: request.verificationId,
+        status: data.status === "completed" ? "approved" : "denied"
+      };
+    } catch (error) {
+      return {
+        success: !1,
+        status: "denied",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  async cancelVerification(verificationId) {
+    try {
+      const headers = {};
+      if (this.config.applicationId && this.config.privateKey) {
+        const jwt = await this.generateJwt();
+        headers.Authorization = `Bearer ${jwt}`;
+      } else
+        headers.Authorization = `Basic ${btoa(`${this.config.apiKey}:${this.config.apiSecret}`)}`;
+      return (await fetch(`${VERIFY_V2_API_BASE}/${verificationId}`, {
+        method: "DELETE",
+        headers
+      })).ok;
+    } catch {
+      return !1;
+    }
+  }
+  async generateJwt() {
+    if (!this.config.applicationId || !this.config.privateKey)
+      throw Error("Application ID and private key required for JWT auth");
+    const header = {
+      typ: "JWT",
+      alg: "RS256"
+    }, now = Math.floor(Date.now() / 1000), payload = {
+      application_id: this.config.applicationId,
+      iat: now,
+      exp: now + 900,
+      jti: crypto.randomUUID()
+    }, encodedHeader = btoa(JSON.stringify(header)), encodedPayload = btoa(JSON.stringify(payload));
+    return `${encodedHeader}.${encodedPayload}.signature`;
+  }
+}
+function mapVonageStatus(status) {
+  return {
+    submitted: "queued",
+    delivered: "delivered",
+    expired: "undelivered",
+    failed: "failed",
+    rejected: "failed",
+    accepted: "sent"
+  }[status] || "unknown";
+}
+export function createVonageDriver(config, useMessagesApi = !1) {
+  return new VonageDriver(config, useMessagesApi);
+}
+
+export { VonageDriver as default };

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SMS Package
+ *
+ * Provides SMS messaging capabilities with support for multiple providers.
+ */
+// Main SMS facade
+export * from './sms';
+export { default as SMS } from './sms';
+// Drivers
+export * from './drivers/index';
+export { TwilioDriver, createTwilioDriver } from './drivers/twilio';
+export { VonageDriver, createVonageDriver } from './drivers/vonage';

package/dist/index.js

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

package/dist/sms.d.ts

@@ -0,0 +1,115 @@
+import type { SmsDriver, SmsMessage, SmsOptions, SmsProvider, SmsSendResult, SmsStatusUpdate, SmsVerificationDriver, VerificationCheckRequest, VerificationRequest, VerificationResult } from '@stacksjs/types';
+/**
+ * Configure the SMS system
+ */
+export declare function configure(config: Partial<SmsOptions>): void;
+/**
+ * Get the default SMS driver based on configuration
+ */
+export declare function getDriver(provider?: SmsProvider): SmsDriver;
+/**
+ * Get the verification driver
+ */
+export declare function getVerificationDriver(provider?: SmsProvider): SmsVerificationDriver;
+/**
+ * Send an SMS message
+ */
+export declare function send(message: SmsMessage): Promise<SmsSendResult>;
+/**
+ * Send multiple SMS messages
+ */
+export declare function sendBulk(messages: SmsMessage[]): Promise<SmsSendResult[]>;
+/**
+ * Get message status
+ */
+export declare function getStatus(messageId: string): Promise<SmsStatusUpdate | null>;
+/**
+ * Verify a phone number format and carrier
+ */
+export declare function verifyNumber(phoneNumber: string): Promise<{ valid: boolean, carrier?: string, type?: string }>;
+/**
+ * Get account balance
+ */
+export declare function getBalance(): Promise<{ balance: number, currency: string } | null>;
+/**
+ * Start a phone verification (send OTP)
+ */
+export declare function startVerification(request: VerificationRequest): Promise<VerificationResult>;
+/**
+ * Check a verification code
+ */
+export declare function checkVerification(request: VerificationCheckRequest): Promise<VerificationResult>;
+/**
+ * Cancel a pending verification
+ */
+export declare function cancelVerification(verificationId: string): Promise<boolean>;
+/**
+ * Create a new SMS builder
+ */
+export declare function sms(): SmsBuilder;
+/**
+ * Send an SMS using a template
+ */
+export declare function sendTemplate(to: string | string[], templateName: string, variables?: Record<string, string>): Promise<SmsSendResult>;
+/**
+ * Format a phone number to E.164 format
+ */
+export declare function formatE164(phoneNumber: string, defaultCountryCode?: string): string;
+/**
+ * Check if a phone number appears valid
+ */
+export declare function isValidPhoneNumber(phoneNumber: string): boolean;
+/**
+ * Initialize the SMS system (loads config)
+ */
+export declare function init(): Promise<void>;
+/**
+ * Check if SMS is enabled in config
+ */
+export declare function isEnabled(): boolean;
+/**
+ * Get the current SMS configuration
+ */
+export declare function getConfig(): Partial<SmsOptions>;
+/**
+ * Send an SMS message (alias)
+ */
+export declare const sendSms: unknown;
+// =============================================================================
+// SMS Facade Object
+// =============================================================================
+export declare const SMS: {
+  init: typeof init;
+  configure: typeof configure;
+  isEnabled: typeof isEnabled;
+  getConfig: typeof getConfig;
+  send: typeof send;
+  sendSms: typeof sendSms;
+  sendBulk: typeof sendBulk;
+  sendTemplate: typeof sendTemplate;
+  getStatus: typeof getStatus;
+  getBalance: typeof getBalance;
+  verifyNumber: typeof verifyNumber;
+  startVerification: typeof startVerification;
+  checkVerification: typeof checkVerification;
+  cancelVerification: typeof cancelVerification;
+  formatE164: typeof formatE164;
+  isValidPhoneNumber: typeof isValidPhoneNumber;
+  sms: typeof sms;
+  getDriver: typeof getDriver;
+  getVerificationDriver: typeof getVerificationDriver
+};
+// =============================================================================
+// SMS Builder (Fluent API)
+// =============================================================================
+export declare class SmsBuilder {
+  to(phoneNumber: string | string[]): this;
+  body(text: string): this;
+  text(text: string): this;
+  from(sender: string): this;
+  media(urls: string | string[]): this;
+  callback(url: string): this;
+  via(provider: SmsProvider): this;
+  send(): Promise<SmsSendResult>;
+}
+export default SMS;

package/dist/sms.js

@@ -0,0 +1,220 @@
+import { TwilioDriver } from "./drivers/twilio";
+import { VonageDriver } from "./drivers/vonage";
+let defaultDriver = null, verificationDriver = null, smsConfig = {}, _configPromise = null;
+async function loadConfig() {
+  try {
+    smsConfig = (await import("../../../../../config/sms")).default;
+  } catch {}
+}
+async function ensureConfig() {
+  if (!_configPromise)
+    _configPromise = loadConfig();
+  await _configPromise;
+}
+export function configure(config) {
+  smsConfig = { ...smsConfig, ...config };
+  defaultDriver = null;
+  verificationDriver = null;
+}
+export function getDriver(provider) {
+  const targetProvider = provider || smsConfig.provider || "twilio";
+  switch (targetProvider) {
+    case "twilio": {
+      const twilioConfig = smsConfig.drivers?.twilio;
+      if (!twilioConfig?.accountSid || !twilioConfig?.authToken)
+        throw Error("Twilio configuration is incomplete. Please provide accountSid and authToken.");
+      return new TwilioDriver({
+        ...twilioConfig,
+        from: twilioConfig.from || smsConfig.from
+      });
+    }
+    case "vonage": {
+      const vonageConfig = smsConfig.drivers?.vonage;
+      if (!vonageConfig?.apiKey || !vonageConfig?.apiSecret)
+        throw Error("Vonage configuration is incomplete. Please provide apiKey and apiSecret.");
+      return new VonageDriver({
+        ...vonageConfig,
+        from: vonageConfig.from || smsConfig.from
+      });
+    }
+    default:
+      throw Error(`Unsupported SMS provider: ${targetProvider}`);
+  }
+}
+export function getVerificationDriver(provider) {
+  const driver = getDriver(provider);
+  if (!("startVerification" in driver))
+    throw Error(`Provider does not support verification: ${provider || smsConfig.provider}`);
+  return driver;
+}
+function getDefaultDriver() {
+  if (!defaultDriver)
+    defaultDriver = getDriver();
+  return defaultDriver;
+}
+function getDefaultVerificationDriver() {
+  if (!verificationDriver)
+    verificationDriver = getVerificationDriver();
+  return verificationDriver;
+}
+export async function send(message) {
+  await ensureConfig();
+  return getDefaultDriver().send(message);
+}
+export const sendSms = send;
+export async function sendBulk(messages) {
+  await ensureConfig();
+  return getDefaultDriver().sendBulk(messages);
+}
+export async function getStatus(messageId) {
+  await ensureConfig();
+  const driver = getDefaultDriver();
+  if (driver.getStatus)
+    return driver.getStatus(messageId);
+  return null;
+}
+export async function verifyNumber(phoneNumber) {
+  await ensureConfig();
+  const driver = getDefaultDriver();
+  if (driver.verify)
+    return driver.verify(phoneNumber);
+  return { valid: !0 };
+}
+export async function getBalance() {
+  await ensureConfig();
+  const driver = getDefaultDriver();
+  if (driver.getBalance)
+    return driver.getBalance();
+  return null;
+}
+export async function startVerification(request) {
+  await ensureConfig();
+  return getDefaultVerificationDriver().startVerification(request);
+}
+export async function checkVerification(request) {
+  await ensureConfig();
+  return getDefaultVerificationDriver().checkVerification(request);
+}
+export async function cancelVerification(verificationId) {
+  await ensureConfig();
+  const driver = getDefaultVerificationDriver();
+  if (driver.cancelVerification)
+    return driver.cancelVerification(verificationId);
+  return !1;
+}
+
+export class SmsBuilder {
+  message = {};
+  provider;
+  to(phoneNumber) {
+    this.message.to = phoneNumber;
+    return this;
+  }
+  body(text) {
+    this.message.body = text;
+    return this;
+  }
+  text(text) {
+    return this.body(text);
+  }
+  from(sender) {
+    this.message.from = sender;
+    return this;
+  }
+  media(urls) {
+    this.message.mediaUrls = Array.isArray(urls) ? urls : [urls];
+    return this;
+  }
+  callback(url) {
+    this.message.statusCallback = url;
+    return this;
+  }
+  via(provider) {
+    this.provider = provider;
+    return this;
+  }
+  async send() {
+    await ensureConfig();
+    if (!this.message.to)
+      return {
+        success: !1,
+        to: "",
+        error: "Recipient is required",
+        provider: this.provider || smsConfig.provider || "twilio"
+      };
+    if (!this.message.body)
+      return {
+        success: !1,
+        to: Array.isArray(this.message.to) ? this.message.to[0] ?? "" : this.message.to,
+        error: "Message body is required",
+        provider: this.provider || smsConfig.provider || "twilio"
+      };
+    return (this.provider ? getDriver(this.provider) : getDefaultDriver()).send(this.message);
+  }
+}
+export function sms() {
+  return new SmsBuilder;
+}
+export async function sendTemplate(to, templateName, variables = {}) {
+  await ensureConfig();
+  const template = smsConfig.templates?.find((t) => t.name === templateName);
+  if (!template)
+    return {
+      success: !1,
+      to: Array.isArray(to) ? to[0] ?? "" : to,
+      error: `Template not found: ${templateName}`,
+      provider: smsConfig.provider || "twilio"
+    };
+  let body = template.body;
+  for (const [key, value] of Object.entries(variables)) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    body = body.replace(new RegExp(`\\{${escapedKey}\\}`, "g"), value);
+  }
+  return send({ to, body });
+}
+export function formatE164(phoneNumber, defaultCountryCode) {
+  let cleaned = phoneNumber.replace(/[\s\-()]/g, "");
+  if (cleaned.startsWith("+"))
+    return cleaned;
+  const countryCode = defaultCountryCode || smsConfig.defaultCountryCode || "1";
+  if (cleaned.startsWith("00"))
+    cleaned = `+${cleaned.slice(2)}`;
+  else if (!cleaned.startsWith("+"))
+    cleaned = `+${countryCode}${cleaned}`;
+  return cleaned;
+}
+export function isValidPhoneNumber(phoneNumber) {
+  const e164Regex = /^\+[1-9]\d{6,14}$/, formatted = formatE164(phoneNumber);
+  return e164Regex.test(formatted);
+}
+export async function init() {
+  await loadConfig();
+}
+export function isEnabled() {
+  return smsConfig.enabled === !0;
+}
+export function getConfig() {
+  return { ...smsConfig };
+}
+export const SMS = {
+  init,
+  configure,
+  isEnabled,
+  getConfig,
+  send,
+  sendSms,
+  sendBulk,
+  sendTemplate,
+  getStatus,
+  getBalance,
+  verifyNumber,
+  startVerification,
+  checkVerification,
+  cancelVerification,
+  formatE164,
+  isValidPhoneNumber,
+  sms,
+  getDriver,
+  getVerificationDriver
+};
+export default SMS;

package/package.json

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