kwtsms 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93dfa6c3d929f5f5767a1dd561078bf3d2e099dfbc8aea04e9d5f0ffa81fbf6a
-  data.tar.gz: 4b0c380d47b356060cbc976a1d035c167b03718572f88e2417cbd9f74d5137cd
+  metadata.gz: 8d0309851d3d99cd00dc43e57fcc1a6a3c325573a3ef5f03cc605b6155e2f8c5
+  data.tar.gz: ded82b65342f4b32e9aa42ced78bcdeeeb496efb2865b543ec4dfef1d8e8bc46
 SHA512:
-  metadata.gz: 02ef8c6d2c00049be8195aab4b359cbbd0d567c42d77f092ac50d31cb66cd021479b95ad51d46c8fae5205a0bd62b82756f6a6fd11bec40248639974a5dc7a29
-  data.tar.gz: 35bf19319f4548a648d96c2802d1176b1e5ed1c2279d4b5d29dcbcedc155b25d94fc50464165aa1c9cf4d6756566b7a0314785efd28c3e6cc36d01445e096976
+  metadata.gz: abf1aab66a4eef8ce7254f8a7963992b65a1dd70b527b893181f7b72a29f836aca7a32f76a01fe5507bc557fc8a82c4c9244b10ad9d4c0cee8a69b30327e7075
+  data.tar.gz: 5551f9ce6129a20e7f2c33c23395acf89910db177362f097f048618621624365c4b9a3add2efd8a82359f5af0f40597230dc48d3d1ca6ef96d8a17241ef8ef1b

data/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-11-07
+
+### Added
+- The client sends a User-Agent `kwtsms-ruby/<version>` (name and version only, no personal data) so kwtSMS can see which integrations are in use. An optional `app_name:` keyword on `KwtSMS::Client.new` puts your app's token in front, e.g. `kwtsms-wordpress/3.5.2 kwtsms-ruby/0.3.1`. New `KwtSMS.build_user_agent` and `client.user_agent`.
+
+### Changed
+- Package author and license holder are now kwtSMS; contact email support@kwtsms.com.
+
+- `send_with_retry`: ERR028 retry is now off by default (`max_retries: 0`), and the wait is a new `wait_seconds:` keyword (default 10) instead of a hardcoded 16 seconds. Duplicate SMS protection (ERR028) is opt-in per account and its window is configurable per account (10 seconds by default); when on, the whole request is rejected and nothing is charged.
+- ERR028 action text no longer states a fixed 15 seconds.
+- ERR006 and ERR025 action text, docs and examples use the placeholder `965XXXXXXXX` instead of a sample mobile number; tests read the phone number from `KWTSMS_TEST_NUMBER` and skip the tests that need it when it is unset.
+- The live 250-number bulk test is replaced by an offline mocked test of the 200 + 50 batching; live tests send only to `KWTSMS_TEST_NUMBER`.
+
+### Docs
+
+- Test mode: test messages are queued but not delivered. Their credits are held until you delete them from the Sending Queue in your kwtsms.com account.
+
 ## [0.3.1] - 2026-03-15
 
 ### Fixed

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 boxlink
+Copyright (c) 2026 kwtSMS
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -2,11 +2,11 @@
 
 [![Gem Version](https://img.shields.io/gem/v/kwtsms.svg)](https://rubygems.org/gems/kwtsms)
 [![Gem Downloads](https://img.shields.io/gem/dt/kwtsms.svg)](https://rubygems.org/gems/kwtsms)
-[![CI](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/ci.yml)
-[![CodeQL](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/codeql.yml/badge.svg)](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/codeql.yml)
-[![Bundle Audit](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/audit.yml/badge.svg)](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/audit.yml)
-[![GitGuardian](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/gitguardian.yml/badge.svg)](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/gitguardian.yml)
-[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/boxlinknet/kwtsms-ruby/badge)](https://scorecard.dev/viewer/?uri=github.com/boxlinknet/kwtsms-ruby)
+[![CI](https://github.com/kwtsms/kwtsms-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/kwtsms/kwtsms-ruby/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/kwtsms/kwtsms-ruby/actions/workflows/codeql.yml/badge.svg)](https://github.com/kwtsms/kwtsms-ruby/actions/workflows/codeql.yml)
+[![Bundle Audit](https://github.com/kwtsms/kwtsms-ruby/actions/workflows/audit.yml/badge.svg)](https://github.com/kwtsms/kwtsms-ruby/actions/workflows/audit.yml)
+[![GitGuardian](https://github.com/kwtsms/kwtsms-ruby/actions/workflows/gitguardian.yml/badge.svg)](https://github.com/kwtsms/kwtsms-ruby/actions/workflows/gitguardian.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/kwtsms/kwtsms-ruby/badge)](https://scorecard.dev/viewer/?uri=github.com/kwtsms/kwtsms-ruby)
 [![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%202.7-red.svg)](https://www.ruby-lang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
@@ -52,7 +52,7 @@ ok, balance, err = sms.verify
 puts "Balance: #{balance}" if ok
 
 # Send SMS
-result = sms.send_sms("96598765432", "Your OTP for MyApp is: 123456")
+result = sms.send_sms("965XXXXXXXX", "Your OTP for MyApp is: 123456")
 puts "msg-id: #{result['msg-id']}" if result["result"] == "OK"
 ```
 
@@ -82,6 +82,16 @@ sms = KwtSMS::Client.new(
 )
 ```
 
+### User-Agent
+
+Every API request carries the User-Agent `kwtsms-ruby/<version>`: the library name and version only, no
+personal or customer data. Pass your own product token as `app_name:` to put it in front:
+
+```ruby
+sms = KwtSMS::Client.new("ruby_username", "ruby_password", app_name: "my-shop/2.1.0")
+# User-Agent: my-shop/2.1.0 kwtsms-ruby/0.3.1
+```
+
 ## API Reference
 
 ### verify
@@ -109,13 +119,13 @@ Send SMS to one or more numbers.
 
 ```ruby
 # Single number
-result = sms.send_sms("96598765432", "Hello!")
+result = sms.send_sms("965XXXXXXXX", "Hello!")
 
 # Multiple numbers
-result = sms.send_sms(["96598765432", "96512345678"], "Bulk message")
+result = sms.send_sms(["965XXXXXXXX", "96512345678"], "Bulk message")
 
 # Override sender ID
-result = sms.send_sms("96598765432", "Hello!", sender: "MY-APP")
+result = sms.send_sms("965XXXXXXXX", "Hello!", sender: "MY-APP")
 ```
 
 Response on success:
@@ -133,10 +143,10 @@ Response on success:
 
 ### send_with_retry
 
-Send with automatic retry on ERR028 (15-second rate limit).
+Send with optional retry on ERR028. ERR028 comes from Duplicate SMS protection, which is opt-in per account (in the account's API settings). When it is on and any number in the request was sent the same message within the account's window (10 seconds by default, configurable per account), the whole request is rejected with ERR028 and nothing is charged. Retry is off by default (`max_retries: 0`); set `wait_seconds:` to your account's window.
 
 ```ruby
-result = sms.send_with_retry("96598765432", "Hello!", max_retries: 3)
+result = sms.send_with_retry("965XXXXXXXX", "Hello!", max_retries: 1, wait_seconds: 10)
 ```
 
 ### senderids
@@ -161,7 +171,7 @@ result = sms.coverage
 Validate phone numbers.
 
 ```ruby
-result = sms.validate(["96598765432", "invalid", "+96512345678"])
+result = sms.validate(["965XXXXXXXX", "invalid", "+96512345678"])
 puts result["ok"]        # valid numbers
 puts result["er"]        # error numbers
 puts result["rejected"]  # locally rejected with error messages
@@ -171,7 +181,7 @@ puts result["rejected"]  # locally rejected with error messages
 
 ```ruby
 # Normalize phone number: Arabic digits, strip non-digits, strip leading zeros
-KwtSMS.normalize_phone("+965 9876 5432")  # => "96598765432"
+KwtSMS.normalize_phone("+965 XXXX XXXX")  # => "965XXXXXXXX"
 
 # Validate phone input (returns [valid, error, normalized])
 valid, error, normalized = KwtSMS.validate_phone_input("user@email.com")
@@ -212,22 +222,24 @@ All formats are accepted and normalized automatically:
 
 | Input | Normalized | Valid? |
 |-------|-----------|--------|
-| `96598765432` | `96598765432` | Yes |
-| `+96598765432` | `96598765432` | Yes |
-| `0096598765432` | `96598765432` | Yes |
-| `965 9876 5432` | `96598765432` | Yes |
-| `965-9876-5432` | `96598765432` | Yes |
-| `(965) 98765432` | `96598765432` | Yes |
-| `٩٦٥٩٨٧٦٥٤٣٢` | `96598765432` | Yes |
-| `۹۶۵۹۸۷۶۵۴۳۲` | `96598765432` | Yes |
-| `+٩٦٥٩٨٧٦٥٤٣٢` | `96598765432` | Yes |
-| `٠٠٩٦٥٩٨٧٦٥٤٣٢` | `96598765432` | Yes |
-| `٩٦٥ ٩٨٧٦ ٥٤٣٢` | `96598765432` | Yes |
-| `٩٦٥-٩٨٧٦-٥٤٣٢` | `96598765432` | Yes |
-| `965٩٨٧٦٥٤٣٢` | `96598765432` | Yes |
+| `965XXXXXXXX` | `965XXXXXXXX` | Yes |
+| `+965XXXXXXXX` | `965XXXXXXXX` | Yes |
+| `00965XXXXXXXX` | `965XXXXXXXX` | Yes |
+| `965 XXXX XXXX` | `965XXXXXXXX` | Yes |
+| `965-XXXX-XXXX` | `965XXXXXXXX` | Yes |
+| `(965) XXXXXXXX` | `965XXXXXXXX` | Yes |
+| `٩٦٥XXXXXXXX` | `965XXXXXXXX` | Yes |
+| `۹۶۵XXXXXXXX` | `965XXXXXXXX` | Yes |
+| `+٩٦٥XXXXXXXX` | `965XXXXXXXX` | Yes |
+| `٠٠٩٦٥XXXXXXXX` | `965XXXXXXXX` | Yes |
+| `٩٦٥ XXXX XXXX` | `965XXXXXXXX` | Yes |
+| `٩٦٥-XXXX-XXXX` | `965XXXXXXXX` | Yes |
+| `965` + 8 Arabic-Indic digits | `965XXXXXXXX` | Yes |
 | `123456` (too short) | rejected | No |
 | `user@gmail.com` | rejected | No |
 
+`X` stands for any digit, in Latin, Arabic-Indic or Persian digits.
+
 Normalization rules:
 - Arabic-Indic and Extended Arabic-Indic digits converted to Latin
 - Non-digit characters stripped (`+`, spaces, dashes, dots, brackets)
@@ -247,7 +259,7 @@ Messages are cleaned automatically before sending to prevent silent delivery fai
 
 ## CLI
 
-For a standalone CLI tool that works on all operating systems, see [kwtsms-cli](https://github.com/boxlinknet/kwtsms-cli).
+For a standalone CLI tool that works on all operating systems, see [kwtsms-cli](https://github.com/kwtsms/kwtsms-cli).
 
 ## Credential Management
 
@@ -331,7 +343,7 @@ Before going live:
 Every API call is logged to a JSONL file (default: `kwtsms.log`):
 
 ```json
-{"ts":"2026-03-06T12:00:00Z","endpoint":"send","request":{"username":"ruby_username","password":"***","mobile":"96598765432","message":"Hello"},"response":{"result":"OK","msg-id":"12345"},"ok":true,"error":null}
+{"ts":"2026-03-06T12:00:00Z","endpoint":"send","request":{"username":"ruby_username","password":"***","mobile":"965XXXXXXXX","message":"Hello"},"response":{"result":"OK","msg-id":"12345"},"ok":true,"error":null}
 ```
 
 Passwords are always masked as `***`. Logging never crashes the main flow.
@@ -381,7 +393,7 @@ Check the **Sending Queue** at [kwtsms.com](https://www.kwtsms.com/login/). If y
 
 **2. What is the difference between Test mode and Live mode?**
 
-**Test mode** (`KWTSMS_TEST_MODE=1`) sends your message to the kwtSMS queue but does NOT deliver it to the handset. No SMS credits are consumed. Use this during development. **Live mode** (`KWTSMS_TEST_MODE=0`) delivers the message for real and deducts credits. Always develop in test mode and switch to live only when ready for production.
+**Test mode** (`KWTSMS_TEST_MODE=1`) sends your message to the kwtSMS queue but does NOT deliver it to the handset. Its credits are held until you delete it from the Sending Queue in your kwtsms.com account. Use this during development. **Live mode** (`KWTSMS_TEST_MODE=0`) delivers the message for real and deducts credits. Always develop in test mode and switch to live only when ready for production.
 
 **3. What is a Sender ID and why should I not use "KWT-SMS" in production?**
 
@@ -407,7 +419,7 @@ International sending is **disabled by default** on kwtSMS accounts. Log in to y
 - **[kwtSMS Dashboard](https://www.kwtsms.com/login/)**: Recharge credits, buy Sender IDs, view message logs, manage coverage
 - **[Other Integrations](https://www.kwtsms.com/integrations.html)**: Plugins and integrations for other platforms and languages
 - **[RubyGems](https://rubygems.org/gems/kwtsms)**: Package on RubyGems.org
-- **[GitHub](https://github.com/boxlinknet/kwtsms-ruby)**: Source code and issue tracker
+- **[GitHub](https://github.com/kwtsms/kwtsms-ruby)**: Source code and issue tracker
 - **[Changelog](CHANGELOG.md)** | **[Contributing](CONTRIBUTING.md)** | **[Security](SECURITY.md)**
 
 ## License

data/lib/kwtsms/client.rb

@@ -19,21 +19,27 @@ module KwtSMS
   # 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")
+  #   result = sms.send_sms("965XXXXXXXX", "Your OTP for MYAPP is: 123456")
+  #   result = sms.send_sms("965XXXXXXXX", "Hello", sender: "OTHER-ID")
+  #   2026-11-05 08:07 +03: placeholder instead of a sample mobile number (it belongs to a real person), int-testnumber.
   #   balance = sms.balance
   class Client
+    # 2026-11-05 14:19 +03: user_agent reader added, the User-Agent sent on every call (#939).
     attr_reader :username, :sender_id, :test_mode, :log_file,
-                :cached_balance, :cached_purchased
+                :cached_balance, :cached_purchased, :user_agent
 
     # @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")
+    # @param app_name [String] Optional product token of the calling app or plugin, e.g. "kwtsms-wordpress/3.5.2",
+    #   sent before the library token in the User-Agent (2026-11-05 14:19 +03, #939).
+    def initialize(username, password, sender_id: "KWT-SMS", test_mode: false, log_file: "kwtsms.log", app_name: "")
       raise ArgumentError, "username and password are required" if username.nil? || username.empty? || password.nil? || password.empty?
 
+      # 2026-11-05 14:19 +03: identify the caller to the API (name and version only, no personal data), #939.
+      @user_agent = KwtSMS.build_user_agent(app_name)
       @username = username
       @password = password
       @sender_id = sender_id
@@ -93,7 +99,7 @@ module KwtSMS
     #   balance: Float or nil
     #   error:   nil or error message string
     def verify
-      data = KwtSMS.api_request("balance", creds, @log_file)
+      data = KwtSMS.api_request("balance", creds, @log_file, @user_agent) # 2026-11-05 14:19 +03: UA (#939)
       if data["result"] == "OK"
         @cached_balance = data["available"].to_f
         @cached_purchased = data["purchased"].to_f
@@ -119,7 +125,7 @@ module KwtSMS
     # 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)
+      data = KwtSMS.api_request("senderid", creds, @log_file, @user_agent) # 2026-11-05 14:19 +03: UA (#939)
       if data["result"] == "OK"
         { "result" => "OK", "senderids" => data["senderid"] || [] }
       else
@@ -133,7 +139,7 @@ module KwtSMS
     # 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)
+      data = KwtSMS.api_request("coverage", creds, @log_file, @user_agent) # 2026-11-05 14:19 +03: UA (#939)
       KwtSMS.enrich_error(data)
     rescue RuntimeError => e
       { "result" => "ERROR", "code" => "NETWORK", "description" => e.message,
@@ -180,7 +186,7 @@ module KwtSMS
 
       payload = creds.merge("mobile" => valid_normalized.join(","))
       begin
-        data = KwtSMS.api_request("validate", payload, @log_file)
+        data = KwtSMS.api_request("validate", payload, @log_file, @user_agent) # 2026-11-05 14:19 +03: UA (#939)
         if data["result"] == "OK"
           mobile = data["mobile"] || {}
           result["ok"] = mobile["OK"] || []
@@ -262,7 +268,7 @@ module KwtSMS
           "test" => @test_mode ? "1" : "0"
         )
         begin
-          result = KwtSMS.api_request("send", payload, @log_file)
+          result = KwtSMS.api_request("send", payload, @log_file, @user_agent) # 2026-11-05 14:19 +03: UA (#939)
         rescue RuntimeError => e
           return {
             "result" => "ERROR",
@@ -282,21 +288,29 @@ module KwtSMS
       result
     end
 
-    # Send SMS, retrying automatically on ERR028 (rate limit: wait 15 seconds).
+    # Send SMS, optionally retrying on ERR028 (duplicate SMS protection).
     #
-    # Waits 16 seconds between retries (15s required + 1s buffer).
-    # All other errors are returned immediately without retry.
+    # ERR028 is opt-in per account (Duplicate SMS protection in the account's
+    # API settings). When it is on and any number in the request was sent the
+    # same message within the account's window (10 seconds by default,
+    # configurable per account), the whole request is rejected and nothing is
+    # charged. Retry is off by default: ERR028 is returned like any other error
+    # unless max_retries > 0. All other errors are returned immediately.
+    #
+    # 2026-10-22 15:34 +03: retry off by default and wait is a parameter (default 10),
+    # was a hardcoded 3 retries x 16 s. The ERR028 window is per account, not a fixed 15 s.
     #
     # @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)
+    # @param max_retries [Integer] Max ERR028 retries after first attempt (default 0, no retry)
+    # @param wait_seconds [Numeric] Seconds to wait before each retry (default 10)
     # @return [Hash] Same shape as send_sms. Never raises.
-    def send_with_retry(mobile, message, sender: nil, max_retries: 3)
+    def send_with_retry(mobile, message, sender: nil, max_retries: 0, wait_seconds: 10)
       result = send_sms(mobile, message, sender: sender)
       retries = 0
       while result["code"] == "ERR028" && retries < max_retries
-        sleep(16)
+        sleep(wait_seconds)
         result = send_sms(mobile, message, sender: sender)
         retries += 1
       end
@@ -337,7 +351,7 @@ module KwtSMS
         waits.each_with_index do |wait, attempt|
           sleep(wait) if wait > 0
           begin
-            data = KwtSMS.api_request("send", payload, @log_file)
+            data = KwtSMS.api_request("send", payload, @log_file, @user_agent) # 2026-11-05 14:19 +03: UA (#939)
           rescue RuntimeError => e
             errors << { "batch" => i + 1, "code" => "NETWORK", "description" => e.message }
             data = nil

data/lib/kwtsms/errors.rb

@@ -9,7 +9,8 @@ module KwtSMS
     "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).",
+    # 2026-11-05 08:07 +03: placeholder instead of a sample mobile number (it belongs to a real person), int-testnumber.
+    "ERR006" => "No valid phone numbers. Make sure each number includes the country code (e.g., 965XXXXXXXX for Kuwait, not XXXXXXXX).",
     "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.",
@@ -23,10 +24,11 @@ module KwtSMS
     "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).",
+    "ERR025" => "Invalid phone number. Make sure the number includes the country code (e.g., 965XXXXXXXX for Kuwait, not XXXXXXXX).",
     "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.",
+    # 2026-10-22 15:34 +03: ERR028 text corrected, the window is opt-in and per account (10 s default), never a fixed 15 s.
+    "ERR028" => "Sent to the same number too soon. Duplicate SMS protection is on for this account, so the whole request was rejected and nothing was charged. Wait for the account's window (10 seconds by default) before resending.",
     "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.",

data/lib/kwtsms/request.rb

@@ -12,13 +12,24 @@ module KwtSMS
   # unix-timestamp values in API responses are server time, not UTC.
   SERVER_TIMEZONE = "Asia/Kuwait (GMT+3)"
 
+  # Build the User-Agent "[app token ]kwtsms-ruby/<VERSION>". The app token is caller input: anything
+  # outside printable ASCII is removed (CR/LF would split the header), whitespace runs become "-",
+  # leading/trailing "-" are trimmed, and it is cut to 64 characters. Empty means the library token only.
+  # 2026-11-05 14:19 +03: added so kwtSMS can count accounts per integration (#939).
+  def self.build_user_agent(app_name = "")
+    app = app_name.to_s.gsub(/[^\x20-\x7e]+/, "").strip.gsub(/\s+/, "-").gsub(/\A-+|-+\z/, "")[0, 64]
+    lib = "kwtsms-ruby/#{VERSION}"
+    app.empty? ? lib : "#{app} #{lib}"
+  end
+
   # POST to a kwtSMS REST/JSON API endpoint.
   #
   # Always sets Content-Type and Accept: application/json.
   # Strips password from log entry.
   # Returns parsed JSON hash.
   # Raises RuntimeError on network / HTTP / parse failure.
-  def self.api_request(endpoint, payload, log_file = "")
+  # 2026-11-05 14:19 +03: user_agent parameter added, sent on every call (#939).
+  def self.api_request(endpoint, payload, log_file = "", user_agent = nil)
     url = URI.parse("#{BASE_URL}#{endpoint}/")
 
     safe_payload = payload.transform_keys(&:to_s).each_with_object({}) do |(k, v), h|
@@ -44,6 +55,7 @@ module KwtSMS
       request = Net::HTTP::Post.new(url.path)
       request["Content-Type"] = "application/json"
       request["Accept"] = "application/json"
+      request["User-Agent"] = user_agent || build_user_agent # 2026-11-05 14:19 +03: kwtsms-ruby/<version> (#939)
       request.body = JSON.generate(payload)
 
       response = http.request(request)

data/lib/kwtsms/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KwtSMS
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/kwtsms.rb

@@ -7,12 +7,14 @@
 #
 #   sms = KwtSMS::Client.from_env                          # reads .env / env vars
 #   ok, balance, err = sms.verify
-#   result = sms.send_sms("96598765432", "Your OTP is: 123456")
-#   result = sms.send_sms("96598765432", "Hello", sender: "MY-APP")
+#   result = sms.send_sms("965XXXXXXXX", "Your OTP is: 123456")
+#   result = sms.send_sms("965XXXXXXXX", "Hello", sender: "MY-APP")
 #   balance = sms.balance
 #
 # Utility functions:
-#   KwtSMS.normalize_phone("+965 9876 5432")
+#   KwtSMS.normalize_phone("+965 XXXX XXXX")
+#
+# 2026-11-05 08:07 +03: placeholder instead of a sample mobile number (it belongs to a real person), int-testnumber.
 #   KwtSMS.validate_phone_input("user@email.com")
 #   KwtSMS.clean_message("Hello \u{1F600} world")
 

metadata

@@ -1,20 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: kwtsms
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
-- boxlink
+- kwtSMS
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-15 00:00:00.000000000 Z
+date: 2026-11-07 00:00:00.000000000 Z
 dependencies: []
 description: Official Ruby client library for the kwtSMS SMS gateway. Send SMS, check
   balance, validate phone numbers, check delivery status, and manage sender IDs. Zero
   external dependencies.
 email:
-- info@boxlink.net
+- support@kwtsms.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -31,15 +31,15 @@ files:
 - lib/kwtsms/phone.rb
 - lib/kwtsms/request.rb
 - lib/kwtsms/version.rb
-homepage: https://github.com/boxlinknet/kwtsms-ruby
+homepage: https://github.com/kwtsms/kwtsms-ruby
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/boxlinknet/kwtsms-ruby
-  source_code_uri: https://github.com/boxlinknet/kwtsms-ruby
-  changelog_uri: https://github.com/boxlinknet/kwtsms-ruby/blob/main/CHANGELOG.md
-  bug_tracker_uri: https://github.com/boxlinknet/kwtsms-ruby/issues
-  documentation_uri: https://github.com/boxlinknet/kwtsms-ruby#readme
+  homepage_uri: https://github.com/kwtsms/kwtsms-ruby
+  source_code_uri: https://github.com/kwtsms/kwtsms-ruby
+  changelog_uri: https://github.com/kwtsms/kwtsms-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kwtsms/kwtsms-ruby/issues
+  documentation_uri: https://github.com/kwtsms/kwtsms-ruby#readme
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []