kwtsms 0.1.0

data/lib/kwtsms/client.rb

@@ -0,0 +1,395 @@
+# frozen_string_literal: true
+
+require "set"
+
+module KwtSMS
+  # InvalidEntry represents a phone number that failed local pre-validation.
+  InvalidEntry = Struct.new(:input, :error, keyword_init: true) do
+    def to_h
+      { "input" => input, "error" => error }
+    end
+  end
+
+  # kwtSMS API client. Zero external dependencies. Ruby 2.7+
+  #
+  # Server timezone: Asia/Kuwait (GMT+3).
+  # unix-timestamp values in API responses are GMT+3 server time, not UTC.
+  # Log timestamps written by this client are always UTC ISO-8601.
+  #
+  # Quick start:
+  #   sms = KwtSMS::Client.from_env
+  #   ok, balance, err = sms.verify
+  #   result = sms.send_sms("96598765432", "Your OTP for MYAPP is: 123456")
+  #   result = sms.send_sms("96598765432", "Hello", sender: "OTHER-ID")
+  #   report = sms.validate(["96598765432", "+96512345678"])
+  #   balance = sms.balance
+  class Client
+    attr_reader :username, :sender_id, :test_mode, :log_file,
+                :cached_balance, :cached_purchased
+
+    # @param username [String] API username (not your account phone number)
+    # @param password [String] API password
+    # @param sender_id [String] Sender ID shown on recipient's phone (default: "KWT-SMS")
+    # @param test_mode [Boolean] When true, messages are queued but not delivered (default: false)
+    # @param log_file [String] Path to JSONL log file. Set to "" to disable logging.
+    def initialize(username, password, sender_id: "KWT-SMS", test_mode: false, log_file: "kwtsms.log")
+      raise ArgumentError, "username and password are required" if username.nil? || username.empty? || password.nil? || password.empty?
+
+      @username = username
+      @password = password
+      @sender_id = sender_id
+      @test_mode = test_mode
+      @log_file = log_file
+      @cached_balance = nil
+      @cached_purchased = nil
+    end
+
+    # Load credentials from environment variables, falling back to .env file.
+    #
+    # Required env vars:
+    #   KWTSMS_USERNAME : API username
+    #   KWTSMS_PASSWORD : API password
+    #
+    # Optional env vars:
+    #   KWTSMS_SENDER_ID : Sender ID (default: "KWT-SMS")
+    #   KWTSMS_TEST_MODE : "1" to queue without delivering (default: "0")
+    #   KWTSMS_LOG_FILE  : JSONL log path (default: "kwtsms.log")
+    def self.from_env(env_file: ".env")
+      file_env = KwtSMS.load_env_file(env_file)
+
+      get = lambda do |key, default = ""|
+        val = ENV[key]
+        return val unless val.nil?
+
+        val = file_env[key]
+        return val unless val.nil?
+
+        default
+      end
+
+      username  = get.call("KWTSMS_USERNAME")
+      password  = get.call("KWTSMS_PASSWORD")
+      sender_id = get.call("KWTSMS_SENDER_ID", "KWT-SMS")
+      test_mode = get.call("KWTSMS_TEST_MODE", "0") == "1"
+      log_file  = get.call("KWTSMS_LOG_FILE", "kwtsms.log")
+
+      missing = []
+      missing << "KWTSMS_USERNAME" if username.empty?
+      missing << "KWTSMS_PASSWORD" if password.empty?
+      raise ArgumentError, "Missing credentials: #{missing.join(', ')}" unless missing.empty?
+
+      new(username, password, sender_id: sender_id, test_mode: test_mode, log_file: log_file)
+    end
+
+    # Test credentials by calling /balance/.
+    # Returns: [ok, balance, error]
+    #   ok:      true/false
+    #   balance: Float or nil
+    #   error:   nil or error message string
+    def verify
+      data = KwtSMS.api_request("balance", creds, @log_file)
+      if data["result"] == "OK"
+        @cached_balance = data["available"].to_f
+        @cached_purchased = data["purchased"].to_f
+        [true, @cached_balance, nil]
+      else
+        data = KwtSMS.enrich_error(data)
+        description = data["description"] || data["code"] || "Unknown error"
+        action = data["action"]
+        error = action ? "#{description} > #{action}" : description
+        [false, nil, error]
+      end
+    rescue RuntimeError => e
+      [false, nil, e.message]
+    end
+
+    # Get current balance via /balance/ API call.
+    # Returns Float or nil on error (returns cached value if available).
+    def balance
+      ok, bal, = verify
+      ok ? bal : @cached_balance
+    end
+
+    # Get delivery status for a sent message via /report/.
+    #
+    # @param msg_id [String] The message ID returned by send_sms in result["msg-id"]
+    # @return [Hash] OK or ERROR hash with action guidance
+    def status(msg_id)
+      data = KwtSMS.api_request("report", creds.merge("msgid" => msg_id.to_s), @log_file)
+      KwtSMS.enrich_error(data)
+    rescue RuntimeError => e
+      { "result" => "ERROR", "code" => "NETWORK", "description" => e.message,
+        "action" => "Check your internet connection and try again." }
+    end
+
+    # List sender IDs registered on this account via /senderid/.
+    # Returns a consistent hash. Never raises, never crashes.
+    def senderids
+      data = KwtSMS.api_request("senderid", creds, @log_file)
+      if data["result"] == "OK"
+        { "result" => "OK", "senderids" => data["senderid"] || [] }
+      else
+        KwtSMS.enrich_error(data)
+      end
+    rescue RuntimeError => e
+      { "result" => "ERROR", "code" => "NETWORK", "description" => e.message,
+        "action" => "Check your internet connection and try again." }
+    end
+
+    # List active country prefixes via /coverage/.
+    # Returns the full API response hash with error enrichment.
+    def coverage
+      data = KwtSMS.api_request("coverage", creds, @log_file)
+      KwtSMS.enrich_error(data)
+    rescue RuntimeError => e
+      { "result" => "ERROR", "code" => "NETWORK", "description" => e.message,
+        "action" => "Check your internet connection and try again." }
+    end
+
+    # Validate and normalize phone numbers via /validate/.
+    #
+    # Numbers that fail local validation are rejected immediately with a clear error.
+    # Numbers that pass local validation are sent to the kwtSMS /validate/ endpoint.
+    #
+    # @param phones [Array<String>] List of phone numbers to validate
+    # @return [Hash] with keys: ok, er, nr, raw, error, rejected
+    def validate(phones)
+      valid_normalized = []
+      pre_rejected = []
+
+      Array(phones).each do |raw|
+        is_valid, error, normalized = KwtSMS.validate_phone_input(raw)
+        if is_valid
+          valid_normalized << normalized
+        else
+          pre_rejected << { "input" => raw.to_s, "error" => error }
+        end
+      end
+
+      result = {
+        "ok" => [],
+        "er" => pre_rejected.map { |r| r["input"] },
+        "nr" => [],
+        "raw" => nil,
+        "error" => nil,
+        "rejected" => pre_rejected
+      }
+
+      if valid_normalized.empty?
+        result["error"] = if pre_rejected.length == 1
+                            pre_rejected[0]["error"]
+                          else
+                            "All #{pre_rejected.length} phone numbers failed validation"
+                          end
+        return result
+      end
+
+      payload = creds.merge("mobile" => valid_normalized.join(","))
+      begin
+        data = KwtSMS.api_request("validate", payload, @log_file)
+        if data["result"] == "OK"
+          mobile = data["mobile"] || {}
+          result["ok"] = mobile["OK"] || []
+          result["er"] = (mobile["ER"] || []) + result["er"]
+          result["nr"] = mobile["NR"] || []
+          result["raw"] = data
+        else
+          data = KwtSMS.enrich_error(data)
+          result["er"] = valid_normalized + result["er"]
+          result["raw"] = data
+          result["error"] = data["description"] || data["code"]
+          result["error"] = "#{result['error']} > #{data['action']}" if data["action"]
+        end
+      rescue RuntimeError => e
+        result["er"] = valid_normalized + result["er"]
+        result["error"] = e.message
+      end
+
+      result
+    end
+
+    # Send SMS to one or more numbers.
+    #
+    # @param mobile [String, Array<String>] Phone number(s). Normalized automatically.
+    # @param message [String] SMS text. Cleaned automatically.
+    # @param sender [String, nil] Optional sender ID override for this call only.
+    # @return [Hash] API response with result, msg-id, balance-after, etc.
+    def send_sms(mobile, message, sender: nil)
+      effective_sender = sender || @sender_id
+
+      raw_list = mobile.is_a?(Array) ? mobile : [mobile]
+
+      valid_numbers = []
+      invalid = []
+
+      raw_list.each do |raw|
+        is_valid, error, normalized = KwtSMS.validate_phone_input(raw)
+        if is_valid
+          valid_numbers << normalized
+        else
+          invalid << { "input" => raw.to_s, "error" => error }
+        end
+      end
+
+      if valid_numbers.empty?
+        description = if invalid.length == 1
+                        invalid[0]["error"]
+                      else
+                        "All #{invalid.length} phone numbers are invalid"
+                      end
+        return KwtSMS.enrich_error({
+          "result" => "ERROR",
+          "code" => "ERR_INVALID_INPUT",
+          "description" => description,
+          "invalid" => invalid
+        })
+      end
+
+      # Deduplicate normalized numbers
+      valid_numbers = valid_numbers.uniq
+
+      # Clean message before routing
+      cleaned_message = KwtSMS.clean_message(message)
+      if cleaned_message.strip.empty?
+        return KwtSMS.enrich_error({
+          "result" => "ERROR",
+          "code" => "ERR009",
+          "description" => "Message is empty after cleaning (contained only emojis or invisible characters)."
+        })
+      end
+
+      if valid_numbers.length > 200
+        result = send_bulk(valid_numbers, cleaned_message, effective_sender)
+      else
+        payload = creds.merge(
+          "sender" => effective_sender,
+          "mobile" => valid_numbers.join(","),
+          "message" => cleaned_message,
+          "test" => @test_mode ? "1" : "0"
+        )
+        begin
+          result = KwtSMS.api_request("send", payload, @log_file)
+        rescue RuntimeError => e
+          return {
+            "result" => "ERROR",
+            "code" => "NETWORK",
+            "description" => e.message,
+            "action" => "Check your internet connection and try again."
+          }
+        end
+        if result["result"] == "OK" && result.key?("balance-after")
+          @cached_balance = result["balance-after"].to_f
+        else
+          result = KwtSMS.enrich_error(result)
+        end
+      end
+
+      result["invalid"] = invalid unless invalid.empty?
+      result
+    end
+
+    # Send SMS, retrying automatically on ERR028 (rate limit: wait 15 seconds).
+    #
+    # Waits 16 seconds between retries (15s required + 1s buffer).
+    # All other errors are returned immediately without retry.
+    #
+    # @param mobile [String, Array<String>] Phone number(s)
+    # @param message [String] Message text
+    # @param sender [String, nil] Sender ID override
+    # @param max_retries [Integer] Max ERR028 retries after first attempt (default 3)
+    # @return [Hash] Same shape as send_sms. Never raises.
+    def send_with_retry(mobile, message, sender: nil, max_retries: 3)
+      result = send_sms(mobile, message, sender: sender)
+      retries = 0
+      while result["code"] == "ERR028" && retries < max_retries
+        sleep(16)
+        result = send_sms(mobile, message, sender: sender)
+        retries += 1
+      end
+      result
+    end
+
+    private
+
+    def creds
+      { "username" => @username, "password" => @password }
+    end
+
+    # Internal: send to >200 pre-normalized numbers in batches of 200.
+    def send_bulk(numbers, message, sender)
+      batch_size = 200
+      batch_delay = 0.5
+      err013_wait = [30, 60, 120]
+
+      batches = numbers.each_slice(batch_size).to_a
+      total_batches = batches.length
+
+      msg_ids = []
+      errors = []
+      total_nums = 0
+      total_pts = 0
+      last_balance = nil
+
+      batches.each_with_index do |batch, i|
+        payload = creds.merge(
+          "sender" => sender,
+          "mobile" => batch.join(","),
+          "message" => message,
+          "test" => @test_mode ? "1" : "0"
+        )
+
+        data = nil
+        waits = [0] + err013_wait
+        waits.each_with_index do |wait, attempt|
+          sleep(wait) if wait > 0
+          begin
+            data = KwtSMS.api_request("send", payload, @log_file)
+          rescue RuntimeError => e
+            errors << { "batch" => i + 1, "code" => "NETWORK", "description" => e.message }
+            data = nil
+            break
+          end
+          break if data["code"] != "ERR013" || attempt == err013_wait.length
+        end
+
+        if data && data["result"] == "OK"
+          msg_ids << (data["msg-id"] || "")
+          total_nums += (data["numbers"] || batch.length).to_i
+          total_pts += (data["points-charged"] || 0).to_i
+          if data.key?("balance-after")
+            last_balance = data["balance-after"].to_f
+            @cached_balance = last_balance
+          end
+        elsif data && data["result"] == "ERROR"
+          errors << {
+            "batch" => i + 1,
+            "code" => data["code"],
+            "description" => data["description"]
+          }
+        end
+
+        sleep(batch_delay) if i < total_batches - 1
+      end
+
+      ok_count = msg_ids.length
+      overall = if ok_count == total_batches
+                  "OK"
+                elsif ok_count == 0
+                  "ERROR"
+                else
+                  "PARTIAL"
+                end
+
+      {
+        "result" => overall,
+        "bulk" => true,
+        "batches" => total_batches,
+        "numbers" => total_nums,
+        "points-charged" => total_pts,
+        "balance-after" => last_balance,
+        "msg-ids" => msg_ids,
+        "errors" => errors
+      }
+    end
+  end
+end

data/lib/kwtsms/env_loader.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module KwtSMS
+  # Load key=value pairs from a .env file. Returns empty hash if not found.
+  # Never raises. Never modifies ENV.
+  def self.load_env_file(env_file = ".env")
+    env = {}
+    begin
+      File.foreach(env_file, encoding: "utf-8") do |line|
+        line = line.strip
+        next if line.empty? || line.start_with?("#")
+        next unless line.include?("=")
+
+        key, _, value = line.partition("=")
+        val = value.strip
+
+        # Strip inline comments from unquoted values
+        unless val.start_with?('"') || val.start_with?("'")
+          val = val.sub(/\s+#.*\z/, "")
+        end
+
+        # Strip one matching outer quote pair
+        if val.length >= 2 && val[0] == val[-1] && (val[0] == '"' || val[0] == "'")
+          val = val[1..-2]
+        end
+
+        env[key.strip] = val
+      end
+    rescue Errno::ENOENT
+      # File not found, return empty hash silently
+    end
+    env
+  end
+end

data/lib/kwtsms/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module KwtSMS
+  # Maps every kwtSMS error code to a developer-friendly action message.
+  # Appended as result["action"] on any ERROR response so callers know what to do.
+  API_ERRORS = {
+    "ERR001" => "API is disabled on this account. Enable it at kwtsms.com > Account > API.",
+    "ERR002" => "A required parameter is missing. Check that username, password, sender, mobile, and message are all provided.",
+    "ERR003" => "Wrong API username or password. Check KWTSMS_USERNAME and KWTSMS_PASSWORD. These are your API credentials, not your account mobile number.",
+    "ERR004" => "This account does not have API access. Contact kwtSMS support to enable it.",
+    "ERR005" => "This account is blocked. Contact kwtSMS support.",
+    "ERR006" => "No valid phone numbers. Make sure each number includes the country code (e.g., 96598765432 for Kuwait, not 98765432).",
+    "ERR007" => "Too many numbers in a single request (maximum 200). Split into smaller batches.",
+    "ERR008" => "This sender ID is banned or not found. Sender IDs are case sensitive (\"Kuwait\" is not the same as \"KUWAIT\"). Check your registered sender IDs at kwtsms.com.",
+    "ERR009" => "Message is empty. Provide a non-empty message text.",
+    "ERR010" => "Account balance is zero. Recharge credits at kwtsms.com.",
+    "ERR011" => "Insufficient balance for this send. Buy more credits at kwtsms.com.",
+    "ERR012" => "Message is too long (over 6 SMS pages). Shorten your message.",
+    "ERR013" => "Send queue is full (1000 messages). Wait a moment and try again.",
+    "ERR019" => "No delivery reports found for this message.",
+    "ERR020" => "Message ID does not exist. Make sure you saved the msg-id from the send response.",
+    "ERR021" => "No delivery report available for this message yet.",
+    "ERR022" => "Delivery reports are not ready yet. Try again after 24 hours.",
+    "ERR023" => "Unknown delivery report error. Contact kwtSMS support.",
+    "ERR024" => "Your IP address is not in the API whitelist. Add it at kwtsms.com > Account > API > IP Lockdown, or disable IP lockdown.",
+    "ERR025" => "Invalid phone number. Make sure the number includes the country code (e.g., 96598765432 for Kuwait, not 98765432).",
+    "ERR026" => "This country is not activated on your account. Contact kwtSMS support to enable the destination country.",
+    "ERR027" => "HTML tags are not allowed in the message. Remove any HTML content and try again.",
+    "ERR028" => "You must wait at least 15 seconds before sending to the same number again. No credits were consumed.",
+    "ERR029" => "Message ID does not exist or is incorrect.",
+    "ERR030" => "Message is stuck in the send queue with an error. Delete it at kwtsms.com > Queue to recover credits.",
+    "ERR031" => "Message rejected: bad language detected.",
+    "ERR032" => "Message rejected: spam detected.",
+    "ERR033" => "No active coverage found. Contact kwtSMS support.",
+    "ERR_INVALID_INPUT" => "One or more phone numbers are invalid. See details above."
+  }.freeze
+
+  # Add an "action" field to API error responses with developer-friendly guidance.
+  # Returns a new hash. Never mutates the original response.
+  # Has no effect on OK responses.
+  def self.enrich_error(data)
+    return data unless data.is_a?(Hash) && data["result"] == "ERROR"
+
+    code = data["code"].to_s
+    if API_ERRORS.key?(code)
+      data = data.dup
+      data["action"] = API_ERRORS[code]
+    end
+    data
+  end
+end

data/lib/kwtsms/logger.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module KwtSMS
+  # Append a JSONL log entry. Never raises. Logging must not break main flow.
+  def self.write_log(log_file, entry)
+    return if log_file.nil? || log_file.empty?
+
+    begin
+      File.open(log_file, "a", encoding: "utf-8") do |f|
+        f.puts(JSON.generate(entry))
+      end
+    rescue StandardError
+      # Logging must never crash the main flow
+    end
+  end
+end

data/lib/kwtsms/message.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module KwtSMS
+  # Hidden / invisible characters that break SMS delivery
+  HIDDEN_CHARS = [
+    "\u200B", # zero-width space
+    "\u200C", # zero-width non-joiner
+    "\u200D", # zero-width joiner
+    "\u2060", # word joiner
+    "\u00AD", # soft hyphen
+    "\uFEFF", # BOM / zero-width no-break space
+    "\uFFFC"  # object replacement character
+  ].freeze
+
+  # Directional formatting characters
+  DIRECTIONAL_CHARS = [
+    "\u200E", # left-to-right mark
+    "\u200F", # right-to-left mark
+    "\u202A", "\u202B", "\u202C", "\u202D", "\u202E", # LRE, RLE, PDF, LRO, RLO
+    "\u2066", "\u2067", "\u2068", "\u2069"             # LRI, RLI, FSI, PDI
+  ].freeze
+
+  STRIP_CHARS_SET = (HIDDEN_CHARS + DIRECTIONAL_CHARS).to_set.freeze
+
+  # Check if a Unicode codepoint is an emoji or pictographic symbol that breaks SMS delivery.
+  def self.emoji_codepoint?(cp)
+    (cp >= 0x1F600 && cp <= 0x1F64F) ||   # emoticons
+      (cp >= 0x1F300 && cp <= 0x1F5FF) ||  # misc symbols and pictographs
+      (cp >= 0x1F680 && cp <= 0x1F6FF) ||  # transport and map
+      (cp >= 0x1F700 && cp <= 0x1F77F) ||  # alchemical symbols
+      (cp >= 0x1F780 && cp <= 0x1F7FF) ||  # geometric shapes extended
+      (cp >= 0x1F800 && cp <= 0x1F8FF) ||  # supplemental arrows-C
+      (cp >= 0x1F900 && cp <= 0x1F9FF) ||  # supplemental symbols and pictographs
+      (cp >= 0x1FA00 && cp <= 0x1FA6F) ||  # chess symbols
+      (cp >= 0x1FA70 && cp <= 0x1FAFF) ||  # symbols and pictographs extended-A
+      (cp >= 0x2600 && cp <= 0x26FF) ||    # miscellaneous symbols
+      (cp >= 0x2700 && cp <= 0x27BF) ||    # dingbats
+      (cp >= 0xFE00 && cp <= 0xFE0F) ||    # variation selectors
+      (cp >= 0x1F000 && cp <= 0x1F0FF) ||  # mahjong tiles + playing cards
+      (cp >= 0x1F1E0 && cp <= 0x1F1FF) ||  # regional indicator symbols (country flags)
+      cp == 0x20E3 ||                       # combining enclosing keycap
+      (cp >= 0xE0000 && cp <= 0xE007F)     # tags block (subdivision flags)
+  end
+
+  # Clean SMS message text before sending to kwtSMS.
+  #
+  # Called automatically by KwtSMS::Client#send. No manual call needed.
+  #
+  # Strips content that silently breaks delivery:
+  # - Arabic-Indic / Extended Arabic-Indic digits converted to Latin digits
+  # - Emojis and pictographic symbols (silently stuck in queue)
+  # - Hidden control characters: BOM, zero-width space, soft hyphen, etc.
+  # - Directional formatting characters
+  # - C0/C1 control characters (except \n and \t)
+  # - HTML tags (causes ERR027)
+  #
+  # Does NOT strip Arabic letters. Arabic text is fully supported.
+  # Returns "" if the entire message was emoji or invisible characters.
+  def self.clean_message(text)
+    text = text.to_s
+
+    # 1. Convert Arabic-Indic and Extended Arabic-Indic digits to Latin
+    text = text.tr(ARABIC_DIGITS + EXTENDED_ARABIC_DIGITS, LATIN_DIGITS)
+
+    # 2. Strip HTML tags
+    text = text.gsub(/<[^>]*>/, "")
+
+    # 3. Remove emojis and pictographic characters, hidden chars, directional chars,
+    #    and C0/C1 control characters (except \n and \t)
+    text = text.each_char.select do |c|
+      cp = c.ord
+      next false if emoji_codepoint?(cp)
+      next false if STRIP_CHARS_SET.include?(c)
+      # C0 controls (U+0000..U+001F) except TAB (0x09) and LF (0x0A)
+      next false if cp <= 0x1F && cp != 0x09 && cp != 0x0A
+      # DEL
+      next false if cp == 0x7F
+      # C1 controls (U+0080..U+009F)
+      next false if cp >= 0x80 && cp <= 0x9F
+
+      true
+    end.join
+
+    text
+  end
+end

data/lib/kwtsms/phone.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module KwtSMS
+  # Arabic-Indic digits (U+0660..U+0669) and Extended Arabic-Indic / Persian digits (U+06F0..U+06F9)
+  ARABIC_DIGITS = "\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669"
+  EXTENDED_ARABIC_DIGITS = "\u06F0\u06F1\u06F2\u06F3\u06F4\u06F5\u06F6\u06F7\u06F8\u06F9"
+  LATIN_DIGITS = "01234567890123456789"
+
+  # Normalize phone to kwtSMS format: digits only, no leading zeros.
+  # Converts Arabic-Indic and Extended Arabic-Indic digits to Latin,
+  # strips all non-digit characters, strips leading zeros.
+  def self.normalize_phone(phone)
+    phone = phone.to_s
+    # 1. Convert Arabic-Indic and Extended Arabic-Indic digits to Latin
+    phone = phone.tr(ARABIC_DIGITS + EXTENDED_ARABIC_DIGITS, LATIN_DIGITS)
+    # 2. Strip every non-digit character
+    phone = phone.gsub(/\D/, "")
+    # 3. Strip leading zeros
+    phone = phone.sub(/\A0+/, "")
+    phone
+  end
+
+  # Validate a raw phone number input before sending to the kwtSMS API.
+  #
+  # Returns: [is_valid, error, normalized]
+  #   is_valid:   true/false
+  #   error:      nil or error message string
+  #   normalized: normalized phone string
+  #
+  # Catches every common mistake without crashing:
+  # - Empty or blank input
+  # - Email address entered instead of a phone number
+  # - Non-numeric text with no digits
+  # - Too short after normalization (< 7 digits)
+  # - Too long after normalization (> 15 digits, E.164 maximum)
+  def self.validate_phone_input(phone)
+    raw = phone.to_s.strip
+
+    # 1. Empty / blank
+    return [false, "Phone number is required", ""] if raw.empty?
+
+    # 2. Email address entered by mistake
+    return [false, "'#{raw}' is an email address, not a phone number", ""] if raw.include?("@")
+
+    # 3. Normalize
+    normalized = normalize_phone(raw)
+
+    # 4. No digits survived normalization
+    return [false, "'#{raw}' is not a valid phone number, no digits found", ""] if normalized.empty?
+
+    # 5. Too short
+    if normalized.length < 7
+      digit_word = normalized.length == 1 ? "digit" : "digits"
+      return [false, "'#{raw}' is too short to be a valid phone number (#{normalized.length} #{digit_word}, minimum is 7)", normalized]
+    end
+
+    # 6. Too long
+    if normalized.length > 15
+      return [false, "'#{raw}' is too long to be a valid phone number (#{normalized.length} digits, maximum is 15)", normalized]
+    end
+
+    [true, nil, normalized]
+  end
+end