ovh-http2sms 0.1.0

data/lib/ovh/http2sms/validators.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Ovh
+  module Http2sms
+    # Validators for SMS parameters
+    #
+    # Provides validation for all SMS parameters before sending to ensure
+    # they meet OVH API requirements.
+    module Validators
+      # Maximum tag length allowed by OVH API
+      MAX_TAG_LENGTH = 20
+
+      # Valid SMS class values
+      VALID_SMS_CLASSES = (0..3).to_a.freeze
+
+      # Valid smsCoding values
+      VALID_SMS_CODINGS = [1, 2].freeze
+
+      # Deferred date format: hhmmddMMYYYY
+      DEFERRED_FORMAT_PATTERN = /\A\d{12}\z/
+
+      class << self
+        # Validate all parameters for an SMS delivery
+        #
+        # @param params [Hash] Parameters to validate
+        # @option params [String, Array<String>] :to Recipient phone number(s)
+        # @option params [String] :message SMS content
+        # @option params [String] :sender Sender name (optional)
+        # @option params [Time, String] :deferred Scheduled send time (optional)
+        # @option params [String] :tag Custom tag (optional, max 20 chars)
+        # @option params [Integer] :sms_class SMS class 0-3 (optional)
+        # @option params [Integer] :sms_coding Encoding 1=7bit, 2=Unicode (optional)
+        # @option params [Boolean] :no_stop Disable STOP clause (optional)
+        # @option params [Boolean] :sender_for_response Enable reply capability (optional)
+        # @raise [ValidationError, PhoneNumberError, MessageLengthError] if validation fails
+        # @return [void]
+        def validate!(params)
+          validate_required_params!(params)
+          validate_phone_numbers!(params[:to])
+          validate_message!(params[:message], no_stop: params[:no_stop])
+          validate_tag!(params[:tag]) if params[:tag]
+          validate_deferred!(params[:deferred]) if params[:deferred]
+          validate_sms_class!(params[:sms_class]) if params[:sms_class]
+          validate_sms_coding!(params[:sms_coding]) if params[:sms_coding]
+          validate_sender_for_response!(params) if params[:sender_for_response]
+        end
+
+        # Validate presence of required parameters
+        #
+        # @param params [Hash] Parameters to validate
+        # @raise [ValidationError] if required params are missing
+        def validate_required_params!(params)
+          missing = []
+          missing << "to" if params[:to].nil? || params[:to].to_s.empty?
+          missing << "message" if params[:message].nil? || params[:message].to_s.empty?
+
+          return if missing.empty?
+
+          raise ValidationError, "Missing required parameters: #{missing.join(", ")}"
+        end
+
+        # Validate phone number(s)
+        #
+        # @param phones [String, Array<String>] Phone number(s) to validate
+        # @raise [PhoneNumberError] if any phone number is invalid
+        def validate_phone_numbers!(phones)
+          phone_list = phones.is_a?(Array) ? phones : [phones]
+          phone_list.each do |phone|
+            PhoneNumber.validate!(PhoneNumber.format(phone))
+          end
+        end
+
+        # Validate message content and length
+        #
+        # @param message [String] Message content
+        # @param no_stop [Boolean] Whether STOP clause is disabled
+        # @raise [MessageLengthError] if message exceeds limits (when raise_on_length_error is true)
+        def validate_message!(message, no_stop: false)
+          info = GsmEncoding.message_info(message, commercial: !no_stop)
+          log_unicode_warning(info)
+          validate_message_length!(info)
+        end
+
+        def log_unicode_warning(info)
+          logger = Ovh::Http2sms.configuration.logger
+          return unless info[:encoding] == :unicode && logger
+
+          non_gsm = info[:non_gsm_chars].join(", ")
+          logger.warn(
+            "[OVH HTTP2SMS] Message requires Unicode encoding due to characters: #{non_gsm}. " \
+            "This reduces maximum SMS length from 160 to 70 characters."
+          )
+        end
+
+        def validate_message_length!(info)
+          return unless info[:sms_count] > 10
+
+          if Ovh::Http2sms.configuration.raise_on_length_error
+            raise_length_error(info)
+          else
+            log_length_warning(info)
+          end
+        end
+
+        def raise_length_error(info)
+          raise MessageLengthError.new(
+            "Message is very long and will be sent as #{info[:sms_count]} SMS segments. " \
+            "Current length: #{info[:characters]} characters (#{info[:encoding]} encoding).",
+            encoding: info[:encoding],
+            length: info[:characters],
+            max_length: info[:max_single_sms]
+          )
+        end
+
+        def log_length_warning(info)
+          logger = Ovh::Http2sms.configuration.logger
+          return unless logger
+
+          logger.warn(
+            "[OVH HTTP2SMS] Message will be sent as #{info[:sms_count]} SMS segments " \
+            "(#{info[:characters]} characters, #{info[:encoding]} encoding). This may incur additional charges."
+          )
+        end
+
+        # Validate tag length
+        #
+        # @param tag [String] Tag to validate
+        # @raise [ValidationError] if tag exceeds maximum length
+        def validate_tag!(tag)
+          return if tag.to_s.length <= MAX_TAG_LENGTH
+
+          raise ValidationError,
+                "Tag exceeds maximum length of #{MAX_TAG_LENGTH} characters (got #{tag.length})"
+        end
+
+        # Validate deferred date format
+        #
+        # @param deferred [Time, String] Deferred send time
+        # @raise [ValidationError] if format is invalid
+        def validate_deferred!(deferred)
+          return if deferred.is_a?(Time) || deferred.is_a?(DateTime)
+
+          deferred_str = deferred.to_s
+          return if deferred_str.match?(DEFERRED_FORMAT_PATTERN)
+
+          raise ValidationError,
+                "Invalid deferred format: '#{deferred}'. " \
+                "Expected hhmmddMMYYYY format (e.g., 125025112024 for 25/11/2024 at 12:50) " \
+                "or a Ruby Time/DateTime object."
+        end
+
+        # Validate SMS class
+        #
+        # @param sms_class [Integer] SMS class value
+        # @raise [ValidationError] if class is invalid
+        def validate_sms_class!(sms_class)
+          return if VALID_SMS_CLASSES.include?(sms_class.to_i)
+
+          raise ValidationError,
+                "Invalid SMS class: #{sms_class}. Must be 0, 1, 2, or 3."
+        end
+
+        # Validate SMS coding
+        #
+        # @param sms_coding [Integer] SMS coding value
+        # @raise [ValidationError] if coding is invalid
+        def validate_sms_coding!(sms_coding)
+          return if VALID_SMS_CODINGS.include?(sms_coding.to_i)
+
+          raise ValidationError,
+                "Invalid SMS coding: #{sms_coding}. Must be 1 (7-bit) or 2 (Unicode)."
+        end
+
+        # Validate sender_for_response compatibility
+        #
+        # @param params [Hash] Full parameters hash
+        # @return [void]
+        def validate_sender_for_response!(params)
+          return unless params[:sender_for_response] && params[:sender]
+
+          # Log warning but don't raise error
+          Ovh::Http2sms.configuration.logger&.warn(
+            "[OVH HTTP2SMS] senderForResponse is enabled but a sender is also specified. " \
+            "The 'from' parameter will be ignored. Leave sender empty when using senderForResponse."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ovh/http2sms/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ovh
+  module Http2sms
+    VERSION = "0.1.0"
+  end
+end

data/lib/ovh/http2sms.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "http2sms/version"
+require_relative "http2sms/errors"
+require_relative "http2sms/configuration"
+require_relative "http2sms/gsm_encoding"
+require_relative "http2sms/phone_number"
+require_relative "http2sms/response"
+require_relative "http2sms/validators"
+require_relative "http2sms/client"
+
+# Load Rails integration if Rails is defined
+require_relative "http2sms/railtie" if defined?(Rails::Railtie)
+
+module Ovh
+  # OVH HTTP2SMS Ruby client
+  #
+  # Send SMS via OVH's http2sms API using simple HTTP GET requests.
+  # Supports single and bulk sending, scheduled messages, GSM/Unicode encoding,
+  # phone number formatting, and Rails integration.
+  #
+  # @example Configuration
+  #   Ovh::Http2sms.configure do |config|
+  #     config.account = "sms-xx11111-1"
+  #     config.login = "user"
+  #     config.password = "secret"
+  #   end
+  #
+  # @example Simple send
+  #   response = Ovh::Http2sms.deliver(to: "33601020304", message: "Hello!")
+  #   response.success? # => true
+  #   response.sms_ids # => ["123456789"]
+  #
+  # @example With options
+  #   Ovh::Http2sms.deliver(
+  #     to: ["33601020304", "33602030405"],
+  #     message: "Meeting reminder",
+  #     sender: "MyCompany",
+  #     deferred: 1.hour.from_now,
+  #     tag: "meeting-reminders"
+  #   )
+  #
+  # @example Check message length
+  #   Ovh::Http2sms.message_info("Hello!")
+  #   # => { characters: 6, encoding: :gsm, sms_count: 1, remaining: 143 }
+  #
+  module Http2sms
+    class << self
+      # @return [Configuration] Current configuration
+      attr_writer :configuration
+
+      # Get the current configuration
+      #
+      # @return [Configuration] Configuration instance
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configure the gem
+      #
+      # @yield [Configuration] Configuration block
+      # @return [Configuration] The configuration object
+      #
+      # @example
+      #   Ovh::Http2sms.configure do |config|
+      #     config.account = "sms-xx11111-1"
+      #     config.login = "user"
+      #     config.password = "secret"
+      #     config.default_sender = "MyApp"
+      #     config.timeout = 30
+      #   end
+      def configure
+        yield(configuration)
+        configuration
+      end
+
+      # Reset configuration to defaults
+      #
+      # @return [Configuration] New configuration with defaults
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      # Send an SMS message using the global configuration
+      #
+      # @param (see Client#deliver)
+      # @return (see Client#deliver)
+      # @raise (see Client#deliver)
+      #
+      # @example
+      #   Ovh::Http2sms.deliver(to: "33601020304", message: "Hello!")
+      def deliver(**options)
+        client.deliver(**options)
+      end
+
+      # Get a new client instance with optional configuration overrides
+      #
+      # @param options [Hash] Configuration options to override
+      # @return [Client] New client instance
+      #
+      # @example Use different credentials
+      #   client = Ovh::Http2sms.client(account: "sms-other-1")
+      #   client.deliver(to: "33601020304", message: "Hello!")
+      def client(**options)
+        Client.new(**options)
+      end
+
+      # Get message information (character count, encoding, SMS count)
+      #
+      # @param message [String] Message to analyze
+      # @param commercial [Boolean] Whether this is a commercial SMS (default: true)
+      # @return [Hash] Message information
+      #
+      # @example
+      #   Ovh::Http2sms.message_info("Hello!")
+      #   # => { characters: 6, encoding: :gsm, sms_count: 1, remaining: 143, ... }
+      #
+      # @example Non-commercial SMS
+      #   Ovh::Http2sms.message_info("Hello!", commercial: false)
+      #   # => { characters: 6, encoding: :gsm, sms_count: 1, remaining: 154, ... }
+      def message_info(message, commercial: true)
+        GsmEncoding.message_info(message, commercial: commercial)
+      end
+
+      # Check if a message uses only GSM characters
+      #
+      # @param message [String] Message to check
+      # @return [Boolean] true if all characters are GSM compatible
+      #
+      # @example
+      #   Ovh::Http2sms.gsm_compatible?("Hello!") # => true
+      #   Ovh::Http2sms.gsm_compatible?("Привет") # => false
+      def gsm_compatible?(message)
+        GsmEncoding.gsm_compatible?(message)
+      end
+
+      # Format a phone number to international format
+      #
+      # @param phone [String] Phone number in local or international format
+      # @param country_code [String] Country code for local numbers (default: from config)
+      # @return [String] Phone number in OVH format (00 prefix)
+      #
+      # @example
+      #   Ovh::Http2sms.format_phone("0601020304") # => "0033601020304"
+      #   Ovh::Http2sms.format_phone("+33601020304") # => "0033601020304"
+      def format_phone(phone, country_code: nil)
+        PhoneNumber.format(phone, country_code: country_code)
+      end
+    end
+  end
+end

data/ovh-http2sms.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/ovh/http2sms/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ovh-http2sms"
+  spec.version = Ovh::Http2sms::VERSION
+  spec.authors = ["François Kiene"]
+
+  spec.summary = "Ruby gem to send SMS via OVH's http2sms API"
+  spec.description = "A production-ready Ruby gem that wraps OVH's http2sms API to send SMS via simple HTTP GET requests. " \
+                     "Supports single and bulk sending, scheduled messages, GSM/Unicode encoding detection, " \
+                     "phone number formatting, and Rails integration."
+  spec.homepage = "https://github.com/fkiene/ovh-http2sms"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/fkiene/ovh-http2sms"
+  spec.metadata["changelog_uri"] = "https://github.com/fkiene/ovh-http2sms/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/ovh-http2sms"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.start_with?(*%w[bin/ spec/ .git .github .rspec .rubocop])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", ">= 1.0", "< 3.0"
+  spec.add_dependency "gsm_encoder", "~> 0.1.7"
+
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "webmock", "~> 3.18"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

data/sig/ovh/http2sms.rbs

@@ -0,0 +1,6 @@
+module Ovh
+  module Http2sms
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,205 @@
+--- !ruby/object:Gem::Specification
+name: ovh-http2sms
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- François Kiene
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: gsm_encoder
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.7
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.20'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A production-ready Ruby gem that wraps OVH's http2sms API to send SMS
+  via simple HTTP GET requests. Supports single and bulk sending, scheduled messages,
+  GSM/Unicode encoding detection, phone number formatting, and Rails integration.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".dockerignore"
+- ".env.example"
+- CHANGELOG.md
+- Dockerfile
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- docker-compose.yml
+- lib/generators/ovh/http2sms/install_generator.rb
+- lib/generators/ovh/http2sms/templates/initializer.rb
+- lib/ovh/http2sms.rb
+- lib/ovh/http2sms/client.rb
+- lib/ovh/http2sms/configuration.rb
+- lib/ovh/http2sms/errors.rb
+- lib/ovh/http2sms/gsm_encoding.rb
+- lib/ovh/http2sms/phone_number.rb
+- lib/ovh/http2sms/railtie.rb
+- lib/ovh/http2sms/response.rb
+- lib/ovh/http2sms/validators.rb
+- lib/ovh/http2sms/version.rb
+- ovh-http2sms.gemspec
+- sig/ovh/http2sms.rbs
+homepage: https://github.com/fkiene/ovh-http2sms
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/fkiene/ovh-http2sms
+  source_code_uri: https://github.com/fkiene/ovh-http2sms
+  changelog_uri: https://github.com/fkiene/ovh-http2sms/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/ovh-http2sms
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby gem to send SMS via OVH's http2sms API
+test_files: []