kwtsms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c507b4a27f1627ba000c997feb953c77a79d2f3328848c251d3159e18cc9007c
+  data.tar.gz: e645bfa974ec35ab4ed008258aa255a05fe3153ed433658c8fbcc4a3c88413bf
+SHA512:
+  metadata.gz: fbe4ee64c98c0335646327309248eebe99336e96da957fc23341de1ddd0801957a98306a57c33d7043ac21c4ef8e843c91d804e7354b3ab2eeb61430b1cc6a00
+  data.tar.gz: 37a77cce2060b5a97682e7dc74b5c13c80cfc1d5dfb8f8ba8fae7206ce402e97bfce0ff5f90b0a648bf139bc6878bbf84e94979d876b1a2625877dc2c4f22f32

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+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).
+
+## [0.1.0] - 2026-03-06
+
+### Added
+
+- Initial release of the kwtsms Ruby gem
+- `KwtSMS::Client` class with full API coverage:
+  - `verify` : test credentials and check balance
+  - `balance` : get current balance
+  - `send_sms` : send SMS to one or more numbers
+  - `send_with_retry` : send with automatic ERR028 retry
+  - `status` : get delivery report for a message
+  - `senderids` : list registered sender IDs
+  - `coverage` : list active country prefixes
+  - `validate` : validate phone numbers
+- `KwtSMS::Client.from_env` factory method for loading credentials from environment variables or `.env` file
+- Utility functions:
+  - `KwtSMS.normalize_phone` : normalize phone numbers (Arabic digits, strip non-digits, strip leading zeros)
+  - `KwtSMS.validate_phone_input` : validate phone input with detailed error messages
+  - `KwtSMS.clean_message` : clean SMS text (strip emojis, HTML, hidden chars, convert Arabic digits)
+  - `KwtSMS.enrich_error` : add developer-friendly action messages to API errors
+- `KwtSMS::API_ERRORS` constant with all 33 kwtSMS error codes mapped to action messages
+- Bulk send support: auto-batching for >200 numbers with ERR013 retry and backoff
+- Phone number deduplication before sending
+- JSONL logging with password masking
+- CLI tool (`kwtsms`) with setup, verify, balance, senderid, coverage, send, and validate commands
+- Zero external runtime dependencies (uses Ruby stdlib only)
+- Comprehensive test suite: unit tests, mocked API tests, and real integration tests
+- Examples: basic usage, OTP flow, bulk SMS, Rails endpoint, error handling, production OTP
+
+[0.1.0]: https://github.com/boxlinknet/kwtsms-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 boxlink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,386 @@
+# kwtSMS Ruby Client
+
+[![Gem Version](https://badge.fury.io/rb/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)
+[![Security Audit](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/codeql.yml/badge.svg)](https://github.com/boxlinknet/kwtsms-ruby/actions/workflows/codeql.yml)
+[![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)
+
+Ruby client for the [kwtSMS API](https://www.kwtsms.com). Send SMS, check balance, validate numbers, list sender IDs, check coverage, get delivery reports.
+
+## About kwtSMS
+
+kwtSMS is a Kuwaiti SMS gateway trusted by top businesses to deliver messages anywhere in the world, with private Sender ID, free API testing, non-expiring credits, and competitive flat-rate pricing. Secure, simple to integrate, built to last. Open a free account in under 1 minute, no paperwork or payment required. [Click here to get started](https://www.kwtsms.com/signup/)
+
+## Prerequisites
+
+You need **Ruby** (>= 2.7) installed.
+
+### Check if Ruby is installed
+
+```bash
+ruby -v
+```
+
+If not installed, see [ruby-lang.org/en/downloads](https://www.ruby-lang.org/en/downloads/).
+
+## Install
+
+```bash
+gem install kwtsms
+```
+
+Or add to your `Gemfile`:
+
+```ruby
+gem "kwtsms"
+```
+
+## Quick Start
+
+```ruby
+require "kwtsms"
+
+sms = KwtSMS::Client.from_env
+
+# Verify credentials
+ok, balance, err = sms.verify
+puts "Balance: #{balance}" if ok
+
+# Send SMS
+result = sms.send_sms("96598765432", "Your OTP for MyApp is: 123456")
+puts "msg-id: #{result['msg-id']}" if result["result"] == "OK"
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file or set environment variables:
+
+```ini
+KWTSMS_USERNAME=ruby_username
+KWTSMS_PASSWORD=ruby_password
+KWTSMS_SENDER_ID=YOUR-SENDER
+KWTSMS_TEST_MODE=1
+KWTSMS_LOG_FILE=kwtsms.log
+```
+
+### Direct Construction
+
+```ruby
+sms = KwtSMS::Client.new(
+  "ruby_username",
+  "ruby_password",
+  sender_id: "YOUR-SENDER",
+  test_mode: true,
+  log_file: "kwtsms.log"
+)
+```
+
+## API Reference
+
+### verify
+
+Test credentials and check balance.
+
+```ruby
+ok, balance, err = sms.verify
+# ok:      true/false
+# balance: Float or nil
+# err:     nil or error message string
+```
+
+### balance
+
+Get current balance.
+
+```ruby
+balance = sms.balance  # Float or nil
+```
+
+### send_sms
+
+Send SMS to one or more numbers.
+
+```ruby
+# Single number
+result = sms.send_sms("96598765432", "Hello!")
+
+# Multiple numbers
+result = sms.send_sms(["96598765432", "96512345678"], "Bulk message")
+
+# Override sender ID
+result = sms.send_sms("96598765432", "Hello!", sender: "MY-APP")
+```
+
+Response on success:
+```ruby
+{
+  "result" => "OK",
+  "msg-id" => "12345",
+  "numbers" => 1,
+  "points-charged" => 1,
+  "balance-after" => 149.0
+}
+```
+
+**Always save `msg-id` immediately after a successful send.** You need it for status checks and delivery reports.
+
+**Never call `balance` after `send_sms`.** The send response already includes your updated balance in `balance-after`.
+
+### send_with_retry
+
+Send with automatic retry on ERR028 (15-second rate limit).
+
+```ruby
+result = sms.send_with_retry("96598765432", "Hello!", max_retries: 3)
+```
+
+### status
+
+Get delivery report for a message.
+
+```ruby
+result = sms.status("12345")  # pass the msg-id from send_sms
+# result["status"] => "DELIVERED", "FAILED", "PENDING", "REJECTED"
+```
+
+### senderids
+
+List sender IDs registered on your account.
+
+```ruby
+result = sms.senderids
+puts result["senderids"]  # => ["KWT-SMS", "MY-APP"]
+```
+
+### coverage
+
+List active country prefixes.
+
+```ruby
+result = sms.coverage
+```
+
+### validate
+
+Validate phone numbers.
+
+```ruby
+result = sms.validate(["96598765432", "invalid", "+96512345678"])
+puts result["ok"]        # valid numbers
+puts result["er"]        # error numbers
+puts result["rejected"]  # locally rejected with error messages
+```
+
+## Utility Functions
+
+```ruby
+# Normalize phone number: Arabic digits, strip non-digits, strip leading zeros
+KwtSMS.normalize_phone("+965 9876 5432")  # => "96598765432"
+
+# Validate phone input (returns [valid, error, normalized])
+valid, error, normalized = KwtSMS.validate_phone_input("user@email.com")
+# => [false, "'user@email.com' is an email address, not a phone number", ""]
+
+# Clean message: strip emojis, HTML, hidden chars, convert Arabic digits
+KwtSMS.clean_message("Hello \u{1F600} <b>world</b>")  # => "Hello  world"
+
+# Enrich error with developer-friendly action message
+KwtSMS.enrich_error({"result" => "ERROR", "code" => "ERR003"})
+# => adds "action" key with guidance
+
+# Access all error codes
+KwtSMS::API_ERRORS  # => Hash of all 29 error codes with action messages
+```
+
+## Bulk Send (>200 Numbers)
+
+When passing more than 200 numbers to `send_sms`, the library automatically:
+
+1. Splits into batches of 200
+2. Sends each batch with a 0.5s delay
+3. Retries ERR013 (queue full) up to 3 times with 30s/60s/120s backoff
+4. Returns aggregated result: `OK`, `PARTIAL`, or `ERROR`
+
+```ruby
+result = sms.send_sms(large_number_list, "Announcement")
+puts result["batches"]         # number of batches
+puts result["msg-ids"]         # array of message IDs
+puts result["points-charged"]  # total points
+puts result["balance-after"]   # final balance
+puts result["errors"]          # any batch errors
+```
+
+## Phone Number Handling
+
+Phone numbers are normalized automatically before sending:
+
+- Arabic-Indic and Extended Arabic-Indic digits converted to Latin
+- Non-digit characters stripped (`+`, spaces, dashes, dots, brackets)
+- Leading zeros stripped (handles `00` country code prefix)
+- Duplicate numbers deduplicated before sending
+- Invalid numbers rejected locally with clear error messages
+
+## Message Cleaning
+
+Messages are cleaned automatically before sending to prevent silent delivery failures:
+
+- Emojis stripped (cause messages to get stuck in queue)
+- HTML tags stripped (causes ERR027)
+- Hidden characters stripped (BOM, zero-width spaces, soft hyphens, directional marks)
+- Arabic-Indic digits converted to Latin
+- C0/C1 control characters removed (except `\n` and `\t`)
+
+## CLI
+
+```bash
+kwtsms setup                              # Interactive credential wizard
+kwtsms verify                             # Test credentials, show balance
+kwtsms balance                            # Show available + purchased credits
+kwtsms senderid                           # List sender IDs
+kwtsms coverage                           # List active country prefixes
+kwtsms send 96598765432 "Hello!"          # Send SMS
+kwtsms send 965xxx,965yyy "Bulk message"  # Multiple numbers
+kwtsms send 96598765432 "Hi" --sender X   # Override sender ID
+kwtsms validate 96598765432 96512345678   # Validate numbers
+kwtsms version                            # Show version
+```
+
+## Credential Management
+
+**Never hardcode credentials in source code.** Credentials must be changeable without recompiling or redeploying.
+
+### Environment variables (recommended for servers)
+
+```ruby
+sms = KwtSMS::Client.from_env  # reads KWTSMS_USERNAME, KWTSMS_PASSWORD, etc.
+```
+
+### Rails initializer
+
+```ruby
+# config/initializers/kwtsms.rb
+KWTSMS_CLIENT = KwtSMS::Client.from_env
+```
+
+### Constructor injection (for custom config systems)
+
+```ruby
+sms = KwtSMS::Client.new(
+  config[:username],
+  config[:password],
+  sender_id: config[:sender_id]
+)
+```
+
+## Best Practices
+
+### Validate before calling the API
+
+```ruby
+valid, error, normalized = KwtSMS.validate_phone_input(user_input)
+unless valid
+  # Don't waste an API call on invalid input
+  return { error: error }
+end
+result = sms.send_sms(normalized, message)
+```
+
+### User-facing error messages
+
+Never expose raw API errors to end users:
+
+| Situation | API Code | Show to User |
+|-----------|----------|--------------|
+| Invalid phone | ERR006, ERR025 | "Please enter a valid phone number in international format." |
+| Auth error | ERR003 | "SMS service temporarily unavailable. Please try again later." |
+| No balance | ERR010, ERR011 | "SMS service temporarily unavailable. Please try again later." |
+| Rate limited | ERR028 | "Please wait a moment before requesting another code." |
+| Content rejected | ERR031, ERR032 | "Your message could not be sent. Please try again with different content." |
+
+### Sender ID
+
+- `KWT-SMS` is a shared test sender: delays, blocked on some carriers. Never use in production.
+- Register a private Sender ID at kwtsms.com (takes ~5 working days for Kuwait).
+- **Sender ID is case sensitive:** `Kuwait` is not the same as `KUWAIT`.
+- **For OTP, use Transactional Sender ID.** Promotional IDs are filtered by DND on Zain and Ooredoo.
+
+### Timezone
+
+`unix-timestamp` in API responses is GMT+3 (Asia/Kuwait server time), not UTC. Always convert when storing or displaying. Log timestamps written by this client are UTC.
+
+### Security Checklist
+
+Before going live:
+
+- [ ] Bot protection enabled (CAPTCHA for web)
+- [ ] Rate limit per phone number (max 3-5/hour)
+- [ ] Rate limit per IP address (max 10-20/hour)
+- [ ] Rate limit per user/session if authenticated
+- [ ] Monitoring/alerting on abuse patterns
+- [ ] Admin notification on low balance
+- [ ] Test mode OFF (`KWTSMS_TEST_MODE=0`)
+- [ ] Private Sender ID registered (not KWT-SMS)
+- [ ] Transactional Sender ID for OTP (not promotional)
+
+## JSONL Logging
+
+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}
+```
+
+Passwords are always masked as `***`. Logging never crashes the main flow.
+
+Disable logging by setting `log_file: ""` in the constructor.
+
+## Examples
+
+See the [examples/](examples/) directory:
+
+| # | Example | Description |
+|---|---------|-------------|
+| 01 | [Basic Usage](examples/01_basic_usage.rb) | Connect, verify, send SMS, validate |
+| 02 | [OTP Flow](examples/02_otp_flow.rb) | Send OTP codes |
+| 03 | [Bulk SMS](examples/03_bulk_sms.rb) | Send to many recipients |
+| 04 | [Rails Endpoint](examples/04_rails_endpoint.rb) | Rails controller |
+| 05 | [Error Handling](examples/05_error_handling.rb) | Handle every error type |
+| 06 | [OTP Production](examples/06-otp-production/) | Production OTP with rate limiting, CAPTCHA, Redis |
+
+## Requirements
+
+- Ruby >= 2.7
+- No external runtime dependencies
+
+## Publishing to RubyGems
+
+```bash
+# 1. Create account at https://rubygems.org/sign_up
+# 2. Build the gem
+gem build kwtsms.gemspec
+
+# 3. Push to RubyGems
+gem push kwtsms-0.1.0.gem
+
+# 4. Or use the automated GitHub Actions workflow:
+#    Push a tag and it publishes automatically
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Links
+
+- [kwtSMS Website](https://www.kwtsms.com)
+- [kwtSMS API Best Practices](https://www.kwtsms.com/articles/sms-api-implementation-best-practices.html)
+- [RubyGems](https://rubygems.org/gems/kwtsms)
+- [GitHub](https://github.com/boxlinknet/kwtsms-ruby)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)

data/exe/kwtsms

@@ -0,0 +1,222 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "kwtsms"
+require "optparse"
+
+module KwtSMS
+  module CLI
+    def self.run(args = ARGV)
+      command = args.shift
+
+      case command
+      when "setup"
+        setup
+      when "verify"
+        verify
+      when "balance"
+        show_balance
+      when "senderid"
+        list_senderids
+      when "coverage"
+        list_coverage
+      when "send"
+        send_sms(args)
+      when "validate"
+        validate_numbers(args)
+      when "version", "--version", "-v"
+        puts "kwtsms #{KwtSMS::VERSION}"
+      when "help", "--help", "-h", nil
+        print_help
+      else
+        $stderr.puts "Unknown command: #{command}"
+        $stderr.puts "Run 'kwtsms help' for usage."
+        exit 1
+      end
+    rescue => e
+      $stderr.puts "Error: #{e.message}"
+      exit 1
+    end
+
+    def self.print_help
+      puts <<~HELP
+        kwtsms #{KwtSMS::VERSION} - kwtSMS API client
+
+        Usage:
+          kwtsms setup                              Interactive credential wizard
+          kwtsms verify                             Test credentials, show balance
+          kwtsms balance                            Show available + purchased credits
+          kwtsms senderid                           List sender IDs
+          kwtsms coverage                           List active country prefixes
+          kwtsms send <mobile> <message> [options]  Send SMS
+          kwtsms validate <number> [number2 ...]    Validate numbers
+          kwtsms version                            Show version
+
+        Send options:
+          --sender SENDER_ID    Override sender ID
+
+        Environment variables:
+          KWTSMS_USERNAME       API username (required)
+          KWTSMS_PASSWORD       API password (required)
+          KWTSMS_SENDER_ID      Sender ID (default: KWT-SMS)
+          KWTSMS_TEST_MODE      Set to 1 for test mode
+          KWTSMS_LOG_FILE       Log file path (default: kwtsms.log)
+
+        Or create a .env file with these variables.
+      HELP
+    end
+
+    def self.client
+      KwtSMS::Client.from_env
+    end
+
+    def self.setup
+      puts "kwtsms setup wizard"
+      puts "=" * 40
+      print "API Username: "
+      username = $stdin.gets&.strip
+      print "API Password: "
+      password = $stdin.gets&.strip
+      print "Sender ID (default: KWT-SMS): "
+      sender = $stdin.gets&.strip
+      sender = "KWT-SMS" if sender.nil? || sender.empty?
+      print "Test mode? (y/N): "
+      test = $stdin.gets&.strip&.downcase == "y"
+
+      env_content = <<~ENV
+        KWTSMS_USERNAME=#{username}
+        KWTSMS_PASSWORD=#{password}
+        KWTSMS_SENDER_ID=#{sender}
+        KWTSMS_TEST_MODE=#{test ? '1' : '0'}
+        KWTSMS_LOG_FILE=kwtsms.log
+      ENV
+
+      File.write(".env", env_content)
+      puts "\n.env file created. Testing credentials..."
+
+      sms = KwtSMS::Client.new(username, password, sender_id: sender, test_mode: test)
+      ok, balance, err = sms.verify
+      if ok
+        puts "Credentials verified. Balance: #{balance} credits."
+      else
+        puts "Credential verification failed: #{err}"
+      end
+    end
+
+    def self.verify
+      sms = client
+      ok, balance, err = sms.verify
+      if ok
+        puts "Credentials: OK"
+        puts "Balance: #{balance} credits"
+        puts "Purchased: #{sms.cached_purchased} credits" if sms.cached_purchased
+      else
+        $stderr.puts "Verification failed: #{err}"
+        exit 1
+      end
+    end
+
+    def self.show_balance
+      sms = client
+      ok, balance, err = sms.verify
+      if ok
+        puts "Available: #{balance} credits"
+        puts "Purchased: #{sms.cached_purchased} credits" if sms.cached_purchased
+      else
+        $stderr.puts "Failed to get balance: #{err}"
+        exit 1
+      end
+    end
+
+    def self.list_senderids
+      sms = client
+      result = sms.senderids
+      if result["result"] == "OK"
+        ids = result["senderids"]
+        if ids.empty?
+          puts "No sender IDs registered."
+        else
+          puts "Sender IDs:"
+          ids.each { |id| puts "  - #{id}" }
+        end
+      else
+        $stderr.puts "Error: #{result['description']}"
+        $stderr.puts result["action"] if result["action"]
+        exit 1
+      end
+    end
+
+    def self.list_coverage
+      sms = client
+      result = sms.coverage
+      if result["result"] == "OK"
+        puts "Active coverage:"
+        puts JSON.pretty_generate(result)
+      else
+        $stderr.puts "Error: #{result['description']}"
+        $stderr.puts result["action"] if result["action"]
+        exit 1
+      end
+    end
+
+    def self.send_sms(args)
+      sender = nil
+      opts = OptionParser.new do |o|
+        o.on("--sender SENDER_ID", "Override sender ID") { |s| sender = s }
+      end
+      opts.parse!(args)
+
+      if args.length < 2
+        $stderr.puts "Usage: kwtsms send <mobile> <message> [--sender SENDER_ID]"
+        $stderr.puts "Multiple numbers: kwtsms send 965xxx,965yyy \"message\""
+        exit 1
+      end
+
+      mobile_input = args[0]
+      message = args[1]
+
+      mobiles = mobile_input.include?(",") ? mobile_input.split(",").map(&:strip) : mobile_input
+
+      sms = client
+
+      if sms.test_mode
+        $stderr.puts "WARNING: Test mode is ON. Messages will be queued but NOT delivered."
+      end
+
+      result = sms.send_sms(mobiles, message, sender: sender)
+
+      if result["result"] == "OK"
+        puts "Message sent successfully."
+        puts "  msg-id: #{result['msg-id']}" if result["msg-id"]
+        puts "  Numbers: #{result['numbers']}" if result["numbers"]
+        puts "  Points charged: #{result['points-charged']}" if result["points-charged"]
+        puts "  Balance after: #{result['balance-after']}" if result["balance-after"]
+      else
+        $stderr.puts "Send failed: #{result['description']}"
+        $stderr.puts "Action: #{result['action']}" if result["action"]
+        exit 1
+      end
+    end
+
+    def self.validate_numbers(args)
+      if args.empty?
+        $stderr.puts "Usage: kwtsms validate <number> [number2 ...]"
+        exit 1
+      end
+
+      sms = client
+      result = sms.validate(args)
+
+      puts "Valid (OK): #{result['ok'].inspect}" unless result["ok"].empty?
+      puts "Errors (ER): #{result['er'].inspect}" unless result["er"].empty?
+      puts "No route (NR): #{result['nr'].inspect}" unless result["nr"].empty?
+      if result["rejected"] && !result["rejected"].empty?
+        puts "Locally rejected:"
+        result["rejected"].each { |r| puts "  #{r['input']}: #{r['error']}" }
+      end
+      puts "Error: #{result['error']}" if result["error"]
+    end
+  end
+end
+
+KwtSMS::CLI.run