ovh-http2sms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7cab24237194aeab0d46e5b7d5bde5679ddca4018ec7f61c47e4bb01e58c7971
+  data.tar.gz: 15ee708e4911827648e2f3f221029b510c2eedf694fd7e4bac34dcd9add7b8ba
+SHA512:
+  metadata.gz: 232378bd0d9f850989b6c608b1c90b0c1399870f920fb2faf5aaad288b92025b1e099d4bf0a73c903f7245c647c465be6b933dbcf12e7b07a054356db01cce75
+  data.tar.gz: ad6bc71528908dd2ebf9985efa2d6f7d3d720811f1d52624ab9f50311b23df43f2296d949e1110115be1f7e52cf4b0dc972a8ceb81adeca6598d150a2f786f17

data/.dockerignore

@@ -0,0 +1,9 @@
+.git
+.github
+*.gem
+coverage/
+doc/
+pkg/
+tmp/
+vendor/bundle
+.rspec_status

data/.env.example

@@ -0,0 +1,12 @@
+# OVH SMS API credentials
+# Copy this file to .env and fill in your values
+# Get your credentials from OVH Manager: https://www.ovh.com/manager/
+
+OVH_SMS_ACCOUNT=sms-xx11111-1
+OVH_SMS_LOGIN=your_login
+OVH_SMS_PASSWORD=your_password
+
+# Optional settings
+# OVH_SMS_DEFAULT_SENDER=MyApp
+# OVH_SMS_DEFAULT_COUNTRY_CODE=33
+# OVH_SMS_TIMEOUT=15

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-01-28
+
+### Added
+
+- Initial release
+- Core SMS sending functionality via OVH http2sms API
+- Support for single and multiple recipients
+- Scheduled (deferred) message sending with Time objects or OVH format
+- GSM 03.38 encoding detection using `gsm_encoder` gem
+- Unicode encoding support with automatic detection
+- Phone number formatting (local to international format)
+- Configurable country codes for international support
+- Commercial SMS handling with STOP clause character limits
+- Reply-enabled SMS (senderForResponse)
+- Response parsing for all formats: JSON, XML, HTML, text/plain
+- Configuration via block, environment variables, or options hash
+- Rails integration with generator (`rails g ovh:http2sms:install`)
+- Rails credentials support
+- Comprehensive error handling with custom exception classes:
+  - `ConfigurationError`
+  - `AuthenticationError`
+  - `MissingParameterError`
+  - `InvalidParameterError`
+  - `NetworkError`
+  - `MessageLengthError`
+  - `PhoneNumberError`
+  - `ValidationError`
+- Thread-safe client implementation
+- Full YARD documentation
+- RSpec test suite with WebMock
+- Rubocop configuration
+- GitHub Actions CI workflow
+
+### Dependencies
+
+- Ruby >= 3.0.0
+- Faraday >= 1.0, < 3.0
+- gsm_encoder ~> 0.1.7
+
+[Unreleased]: https://github.com/fkiene/ovh-http2sms/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/fkiene/ovh-http2sms/releases/tag/v0.1.0

data/Dockerfile

@@ -0,0 +1,25 @@
+FROM ruby:3.2-slim
+
+RUN apt-get update -qq && apt-get install -y \
+    build-essential \
+    git \
+    libyaml-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /gem
+
+# Install bundler
+RUN gem install bundler
+
+# Copy gemspec and Gemfile first for better caching
+COPY Gemfile ovh-http2sms.gemspec ./
+COPY lib/ovh/http2sms/version.rb lib/ovh/http2sms/
+
+# Install dependencies
+RUN bundle install
+
+# Copy the rest of the code
+COPY . .
+
+# Default command: interactive console
+CMD ["bin/console"]

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in ovh-http2sms.gemspec
+gemspec
+
+gem "irb"
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 François Kiene
+
+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,503 @@
+# OVH HTTP2SMS
+
+[![Gem Version](https://img.shields.io/gem/v/ovh-http2sms.svg)](https://rubygems.org/gems/ovh-http2sms)
+[![Build Status](https://github.com/fkiene/ovh-http2sms/actions/workflows/ci.yml/badge.svg)](https://github.com/fkiene/ovh-http2sms/actions)
+[![Code Coverage](https://codecov.io/gh/fkiene/ovh-http2sms/branch/main/graph/badge.svg)](https://codecov.io/gh/fkiene/ovh-http2sms)
+
+A production-ready Ruby gem to send SMS via OVH's http2sms API. Supports single and bulk sending, scheduled messages, GSM/Unicode encoding detection, phone number formatting, and seamless Rails integration.
+
+## Features
+
+- Simple API for sending SMS via OVH's http2sms endpoint
+- Support for single and multiple recipients
+- Scheduled (deferred) message sending
+- GSM 03.38 and Unicode encoding detection
+- Automatic phone number formatting (local to international)
+- Configurable country codes for international support
+- Commercial SMS with STOP clause handling
+- Reply-enabled SMS (senderForResponse)
+- All response formats (JSON, XML, HTML, text/plain)
+- Rails generator for easy setup
+- Rails credentials support
+- Thread-safe client
+- Comprehensive error handling
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "ovh-http2sms"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install ovh-http2sms
+```
+
+## Quick Start
+
+```ruby
+# Configure credentials
+Ovh::Http2sms.configure do |config|
+  config.account = "sms-xx11111-1"
+  config.login = "your_login"
+  config.password = "your_password"
+end
+
+# Send a simple SMS
+response = Ovh::Http2sms.deliver(to: "33601020304", message: "Hello!")
+
+if response.success?
+  puts "SMS sent! ID: #{response.sms_ids.first}"
+  puts "Credits remaining: #{response.credits_remaining}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+## Configuration
+
+### Block Configuration
+
+```ruby
+Ovh::Http2sms.configure do |config|
+  # Required
+  config.account = "sms-xx11111-1"
+  config.login = "your_login"
+  config.password = "your_password"
+
+  # Optional
+  config.default_sender = "MyApp"           # Default sender name
+  config.default_country_code = "33"        # For phone number formatting (default: "33" France)
+  config.default_content_type = "application/json"  # Response format
+  config.timeout = 15                       # HTTP timeout in seconds
+  config.raise_on_length_error = true       # Raise error for very long messages
+  config.logger = Logger.new($stdout)       # For debugging
+end
+```
+
+### Environment Variables
+
+```bash
+export OVH_SMS_ACCOUNT="sms-xx11111-1"
+export OVH_SMS_LOGIN="your_login"
+export OVH_SMS_PASSWORD="your_password"
+export OVH_SMS_DEFAULT_SENDER="MyApp"
+export OVH_SMS_DEFAULT_COUNTRY_CODE="33"
+export OVH_SMS_TIMEOUT="30"
+```
+
+### Rails Credentials
+
+For Rails applications, you can use encrypted credentials:
+
+```bash
+rails credentials:edit
+```
+
+Add:
+
+```yaml
+ovh_sms:
+  account: sms-xx11111-1
+  login: your_login
+  password: your_password
+  default_sender: MyApp
+```
+
+Then in your initializer:
+
+```ruby
+Ovh::Http2sms.configure do |config|
+  credentials = Rails.application.credentials.ovh_sms
+  config.account = credentials[:account]
+  config.login = credentials[:login]
+  config.password = credentials[:password]
+  config.default_sender = credentials[:default_sender]
+end
+```
+
+## Usage Examples
+
+### Basic Send
+
+```ruby
+response = Ovh::Http2sms.deliver(
+  to: "33601020304",
+  message: "Your verification code is 123456"
+)
+```
+
+### Send to Multiple Recipients
+
+```ruby
+# As array
+response = Ovh::Http2sms.deliver(
+  to: ["33601020304", "33602030405", "33603040506"],
+  message: "Team meeting at 3pm"
+)
+
+# As comma-separated string
+response = Ovh::Http2sms.deliver(
+  to: "33601020304,33602030405",
+  message: "Team meeting at 3pm"
+)
+```
+
+### Scheduled (Deferred) Sending
+
+```ruby
+# Using Ruby Time object
+response = Ovh::Http2sms.deliver(
+  to: "33601020304",
+  message: "Reminder: Meeting tomorrow",
+  deferred: Time.now + 3600  # 1 hour from now
+)
+
+# Using OVH format (hhmmddMMYYYY)
+response = Ovh::Http2sms.deliver(
+  to: "33601020304",
+  message: "Happy New Year!",
+  deferred: "000001012025"  # Midnight on Jan 1, 2025
+)
+```
+
+### Custom Sender
+
+```ruby
+response = Ovh::Http2sms.deliver(
+  to: "33601020304",
+  message: "Your order has shipped!",
+  sender: "MyShop"  # Must be registered with OVH
+)
+```
+
+### Enable Replies (Short Code)
+
+```ruby
+response = Ovh::Http2sms.deliver(
+  to: "33601020304",
+  message: "Reply YES to confirm",
+  sender_for_response: true  # Enables reply capability
+)
+```
+
+### Non-Commercial SMS (No STOP Clause)
+
+```ruby
+response = Ovh::Http2sms.deliver(
+  to: "33601020304",
+  message: "Your 2FA code is 123456",
+  no_stop: true  # Removes "STOP au XXXXX" from message
+)
+```
+
+### With Custom Tag for Tracking
+
+```ruby
+response = Ovh::Http2sms.deliver(
+  to: "33601020304",
+  message: "Order #12345 confirmed",
+  tag: "order-confirmations"  # Max 20 characters
+)
+```
+
+### Force Encoding
+
+```ruby
+# Force Unicode encoding
+response = Ovh::Http2sms.deliver(
+  to: "33601020304",
+  message: "Hello World",
+  sms_coding: 2  # 1 = GSM 7-bit, 2 = Unicode
+)
+```
+
+## Phone Number Formatting
+
+The gem automatically formats phone numbers to OVH international format (00 prefix):
+
+```ruby
+# Local French number
+Ovh::Http2sms.format_phone("0601020304")
+# => "0033601020304"
+
+# Already international
+Ovh::Http2sms.format_phone("33601020304")
+# => "0033601020304"
+
+# With plus sign
+Ovh::Http2sms.format_phone("+33601020304")
+# => "0033601020304"
+
+# With spaces and dashes
+Ovh::Http2sms.format_phone("06 01 02-03-04")
+# => "0033601020304"
+
+# Already OVH format (unchanged)
+Ovh::Http2sms.format_phone("0033601020304")
+# => "0033601020304"
+
+# UK number with custom country code
+Ovh::Http2sms.format_phone("07911123456", country_code: "44")
+# => "00447911123456"
+```
+
+## Character Encoding
+
+SMS messages use different encodings with different character limits:
+
+| Encoding | Single SMS | Concatenated SMS |
+|----------|------------|------------------|
+| GSM 7-bit | 160 chars | 153 chars/part |
+| Unicode | 70 chars | 67 chars/part |
+
+For commercial SMS (with STOP clause), limits are reduced:
+
+| Encoding | First SMS | Subsequent |
+|----------|-----------|------------|
+| GSM 7-bit | 149 chars | 153 chars |
+| Unicode | 59 chars | 70 chars |
+
+### Check Message Info
+
+```ruby
+info = Ovh::Http2sms.message_info("Hello World!")
+# => {
+#   characters: 12,
+#   encoding: :gsm,
+#   sms_count: 1,
+#   remaining: 137,
+#   max_single_sms: 149,
+#   non_gsm_chars: []
+# }
+
+# With emoji (forces Unicode)
+info = Ovh::Http2sms.message_info("Hello! 👋")
+# => {
+#   characters: 9,
+#   encoding: :unicode,
+#   sms_count: 1,
+#   remaining: 50,
+#   max_single_sms: 59,
+#   non_gsm_chars: ["👋"]
+# }
+
+# For non-commercial SMS
+info = Ovh::Http2sms.message_info("Hello!", commercial: false)
+# => { remaining: 154, max_single_sms: 160, ... }
+```
+
+### Check GSM Compatibility
+
+```ruby
+Ovh::Http2sms.gsm_compatible?("Hello World!")  # => true
+Ovh::Http2sms.gsm_compatible?("Привет мир!")   # => false
+Ovh::Http2sms.gsm_compatible?("Price: €100")   # => true (€ is GSM extension)
+```
+
+### GSM Extension Characters
+
+These characters are valid in GSM encoding but count as 2 characters:
+`€`, `|`, `^`, `{`, `}`, `[`, `]`, `~`, `\`
+
+## Error Handling
+
+```ruby
+begin
+  response = Ovh::Http2sms.deliver(to: "33601020304", message: "Hello!")
+rescue Ovh::Http2sms::ConfigurationError => e
+  puts "Missing configuration: #{e.message}"
+rescue Ovh::Http2sms::AuthenticationError => e
+  puts "IP not authorized: #{e.message}"
+rescue Ovh::Http2sms::MissingParameterError => e
+  puts "Missing parameter: #{e.message}"
+rescue Ovh::Http2sms::InvalidParameterError => e
+  puts "Invalid parameter: #{e.message}"
+rescue Ovh::Http2sms::SenderNotFoundError => e
+  puts "Sender not registered: #{e.message}"
+rescue Ovh::Http2sms::PhoneNumberError => e
+  puts "Invalid phone number: #{e.phone_number}"
+rescue Ovh::Http2sms::MessageLengthError => e
+  puts "Message too long: #{e.length} chars (#{e.encoding} encoding)"
+rescue Ovh::Http2sms::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue Ovh::Http2sms::ResponseParseError => e
+  puts "Failed to parse response: #{e.message}"
+rescue Ovh::Http2sms::Error => e
+  puts "General error: #{e.message}"
+end
+```
+
+## Rails Integration
+
+### Generate Initializer
+
+```bash
+rails g ovh:http2sms:install
+```
+
+This creates `config/initializers/ovh_http2sms.rb` with configuration options.
+
+### Using with ActiveJob
+
+Parameters are serializable and work with ActiveJob:
+
+```ruby
+class SmsNotificationJob < ApplicationJob
+  queue_as :default
+
+  def perform(phone_number, message, options = {})
+    Ovh::Http2sms.deliver(
+      to: phone_number,
+      message: message,
+      **options.symbolize_keys
+    )
+  end
+end
+
+# Enqueue
+SmsNotificationJob.perform_later("0601020304", "Your order shipped!", { tag: "shipping" })
+```
+
+### Multiple Accounts
+
+Use separate clients for different OVH accounts:
+
+```ruby
+marketing_client = Ovh::Http2sms.client(
+  account: "sms-marketing-1",
+  login: "marketing_user",
+  password: "marketing_pass",
+  default_sender: "Promo"
+)
+
+transactional_client = Ovh::Http2sms.client(
+  account: "sms-transact-1",
+  login: "transact_user",
+  password: "transact_pass",
+  default_sender: "Alerts"
+)
+
+marketing_client.deliver(to: "33601020304", message: "Special offer!")
+transactional_client.deliver(to: "33601020304", message: "Order confirmed", no_stop: true)
+```
+
+## Response Object
+
+```ruby
+response = Ovh::Http2sms.deliver(to: "33601020304", message: "Hello!")
+
+response.success?          # true/false
+response.failure?          # opposite of success?
+response.status            # API status code (100, 101 = success)
+response.sms_ids           # Array of SMS IDs
+response.credits_remaining # Remaining SMS credits
+response.error_message     # Error message if failed
+response.error_type        # :missing_parameter, :invalid_parameter, :authentication_error
+response.raw_response      # Raw API response body
+response.content_type      # Response content type
+```
+
+## API Reference
+
+### OVH Response Codes
+
+| Code | Meaning |
+|------|---------|
+| 100, 101 | Success |
+| 201 | Missing parameter |
+| 202 | Invalid parameter |
+| 241 | Sender not found |
+| 401 | IP not authorized |
+
+### SMS Classes
+
+| Class | Description |
+|-------|-------------|
+| 0 | Flash SMS (displayed immediately, not stored) |
+| 1 | Stored in phone memory (default) |
+| 2 | Stored on SIM card |
+| 3 | Transferred to external device |
+
+## Development
+
+### With Docker (recommended)
+
+```bash
+# Interactive console
+docker compose run --rm dev
+
+# Run tests
+docker compose run --rm test
+
+# Run linter
+docker compose run --rm lint
+```
+
+To test with real credentials:
+
+```bash
+cp .env.example .env
+# Edit .env with your OVH credentials
+docker compose run --rm dev
+```
+
+### Without Docker
+
+After checking out the repo, run:
+
+```bash
+bin/setup
+bundle exec rake spec
+```
+
+To install locally:
+
+```bash
+bundle exec rake install
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Code Style
+
+```bash
+bundle exec rubocop
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -am 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Create a Pull Request
+
+Please ensure:
+- All tests pass
+- Code follows Ruby style guide (Rubocop)
+- New features have tests
+- Documentation is updated
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Links
+
+- [OVH SMS Documentation](https://help.ovhcloud.com/csm/fr-sms-sending-via-url-http2sms)
+- [RubyGems](https://rubygems.org/gems/ovh-http2sms)
+- [API Documentation](https://rubydoc.info/gems/ovh-http2sms)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docker-compose.yml

@@ -0,0 +1,29 @@
+services:
+  dev:
+    build: .
+    volumes:
+      - .:/gem
+      - bundle_cache:/usr/local/bundle
+    environment:
+      - OVH_SMS_ACCOUNT=${OVH_SMS_ACCOUNT}
+      - OVH_SMS_LOGIN=${OVH_SMS_LOGIN}
+      - OVH_SMS_PASSWORD=${OVH_SMS_PASSWORD}
+    stdin_open: true
+    tty: true
+
+  test:
+    build: .
+    volumes:
+      - .:/gem
+      - bundle_cache:/usr/local/bundle
+    command: bundle exec rspec
+
+  lint:
+    build: .
+    volumes:
+      - .:/gem
+      - bundle_cache:/usr/local/bundle
+    command: bundle exec rubocop
+
+volumes:
+  bundle_cache: