ovh-http2sms 0.1.0

data/lib/generators/ovh/http2sms/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Ovh
+  module Http2sms
+    module Generators
+      # Rails generator for OVH HTTP2SMS initializer
+      #
+      # @example
+      #   rails g ovh:http2sms:install
+      class InstallGenerator < Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Creates an OVH HTTP2SMS initializer file"
+
+        # Create the initializer file
+        def create_initializer_file
+          template "initializer.rb", "config/initializers/ovh_http2sms.rb"
+        end
+
+        # Show instructions after installation
+        def show_instructions
+          say ""
+          say "OVH HTTP2SMS initializer created!", :green
+          say ""
+          say "Next steps:"
+          say "  1. Edit config/initializers/ovh_http2sms.rb with your credentials"
+          say "  2. Or set environment variables: OVH_SMS_ACCOUNT, OVH_SMS_LOGIN, OVH_SMS_PASSWORD"
+          say "  3. Or use Rails credentials: rails credentials:edit"
+          say ""
+          say "Example credentials structure:"
+          say "  ovh_sms:"
+          say "    account: sms-xx11111-1"
+          say "    login: your_login"
+          say "    password: your_password"
+          say ""
+        end
+      end
+    end
+  end
+end

data/lib/generators/ovh/http2sms/templates/initializer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# OVH HTTP2SMS configuration
+#
+# You can configure the gem using:
+# 1. This initializer (direct values or Rails credentials)
+# 2. Environment variables: OVH_SMS_ACCOUNT, OVH_SMS_LOGIN, OVH_SMS_PASSWORD, etc.
+#
+# Environment variables take precedence if this block doesn't set values.
+
+Ovh::Http2sms.configure do |config|
+  # Required credentials
+  # Option 1: Direct configuration (not recommended for production)
+  # config.account = "sms-xx11111-1"
+  # config.login = "your_login"
+  # config.password = "your_password"
+
+  # Option 2: Using Rails credentials (recommended)
+  # Run: rails credentials:edit
+  # Add:
+  #   ovh_sms:
+  #     account: sms-xx11111-1
+  #     login: your_login
+  #     password: your_password
+  #
+  if Rails.application.credentials.ovh_sms.present?
+    config.account = Rails.application.credentials.dig(:ovh_sms, :account)
+    config.login = Rails.application.credentials.dig(:ovh_sms, :login)
+    config.password = Rails.application.credentials.dig(:ovh_sms, :password)
+    config.default_sender = Rails.application.credentials.dig(:ovh_sms, :default_sender)
+  end
+
+  # Optional settings
+
+  # Default sender name (must be registered in OVH account)
+  # config.default_sender = "MyApp"
+
+  # Default country code for phone number formatting (default: "33" for France)
+  # config.default_country_code = "33"
+
+  # Response content type: application/json, text/xml, text/plain, text/html
+  # config.default_content_type = "application/json"
+
+  # HTTP timeout in seconds (default: 15)
+  # config.timeout = 15
+
+  # Raise error if message exceeds SMS length limits (default: true)
+  # config.raise_on_length_error = true
+
+  # Logger for debugging (uses Rails.logger by default in Rails apps)
+  config.logger = Rails.logger if defined?(Rails.logger)
+end

data/lib/ovh/http2sms/client.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "uri"
+
+module Ovh
+  module Http2sms
+    # HTTP client for OVH HTTP2SMS API
+    #
+    # Handles building requests, making HTTP calls, and processing responses.
+    # Thread-safe for use in multi-threaded environments.
+    #
+    # @example Direct usage
+    #   client = Client.new(account: "sms-xx111-1", login: "user", password: "pass")
+    #   response = client.deliver(to: "33601020304", message: "Hello!")
+    class Client
+      # @return [Configuration] Client configuration
+      attr_reader :config
+
+      # Initialize a new client
+      #
+      # @param options [Hash] Configuration options (overrides global config)
+      # @option options [String] :account SMS account identifier
+      # @option options [String] :login SMS user login
+      # @option options [String] :password SMS user password
+      # @option options [String] :default_sender Default sender name
+      # @option options [String] :default_content_type Response format
+      # @option options [Integer] :timeout HTTP timeout in seconds
+      # @option options [Logger] :logger Logger for debugging
+      # @option options [String] :default_country_code Default country code
+      def initialize(**options)
+        @config = build_config(options)
+      end
+
+      # Send an SMS message
+      #
+      # @param to [String, Array<String>] Recipient phone number(s)
+      # @param message [String] SMS content
+      # @param sender [String, nil] Sender name (uses default if nil)
+      # @param deferred [Time, String, nil] Scheduled send time
+      # @param tag [String, nil] Custom tag for tracking (max 20 chars)
+      # @param sms_class [Integer, nil] SMS class (0-3)
+      # @param sms_coding [Integer, nil] Encoding (1=7bit, 2=Unicode)
+      # @param no_stop [Boolean] Set to true for non-commercial SMS
+      # @param sender_for_response [Boolean] Enable reply capability
+      # @param content_type [String, nil] Response format (uses default if nil)
+      # @return [Response] Parsed response object
+      # @raise [ConfigurationError] if configuration is invalid
+      # @raise [ValidationError] if parameters are invalid
+      # @raise [NetworkError] if HTTP request fails
+      # @raise [AuthenticationError] if IP is not authorized
+      # @raise [MissingParameterError] if required parameter is missing
+      # @raise [InvalidParameterError] if parameter value is invalid
+      #
+      # @example Simple send
+      #   client.deliver(to: "33601020304", message: "Hello!")
+      #
+      # @example With options
+      #   client.deliver(
+      #     to: ["33601020304", "33602030405"],
+      #     message: "Meeting at 3pm",
+      #     sender: "MyCompany",
+      #     deferred: 1.hour.from_now,
+      #     tag: "reminders"
+      #   )
+      # rubocop:disable Metrics/ParameterLists
+      def deliver(to:, message:, sender: nil, deferred: nil, tag: nil,
+                  sms_class: nil, sms_coding: nil, no_stop: false,
+                  sender_for_response: false, content_type: nil)
+        # rubocop:enable Metrics/ParameterLists
+        @config.validate!
+
+        params = build_delivery_params(to, message, sender, deferred, tag, sms_class,
+                                       sms_coding, no_stop, sender_for_response)
+        Validators.validate!(params)
+
+        query_params = build_query_params(params, content_type)
+        execute_request(query_params, content_type)
+      end
+
+      ERROR_HANDLERS = {
+        401 => AuthenticationError,
+        201 => MissingParameterError,
+        202 => InvalidParameterError,
+        241 => SenderNotFoundError
+      }.freeze
+      private_constant :ERROR_HANDLERS
+
+      private
+
+      # rubocop:disable Metrics/ParameterLists
+      def build_delivery_params(to, message, sender, deferred, tag, sms_class,
+                                sms_coding, no_stop, sender_for_response)
+        # rubocop:enable Metrics/ParameterLists
+        {
+          to: to, message: message, sender: sender, deferred: deferred, tag: tag,
+          sms_class: sms_class, sms_coding: sms_coding, no_stop: no_stop,
+          sender_for_response: sender_for_response
+        }
+      end
+
+      def build_config(options)
+        return Ovh::Http2sms.configuration.dup if options.empty?
+
+        Configuration.new.tap { |config| merge_config_options(config, options) }
+      end
+
+      def merge_config_options(config, options)
+        global = Ovh::Http2sms.configuration
+        merge_credentials(config, options, global)
+        merge_defaults(config, options, global)
+      end
+
+      def merge_credentials(config, options, global)
+        config.account = options[:account] || global.account
+        config.login = options[:login] || global.login
+        config.password = options[:password] || global.password
+      end
+
+      def merge_defaults(config, options, global)
+        config.default_sender = options[:default_sender] || global.default_sender
+        config.default_content_type = options[:default_content_type] || global.default_content_type
+        config.timeout = options[:timeout] || global.timeout
+        config.logger = options[:logger] || global.logger
+        config.default_country_code = options[:default_country_code] || global.default_country_code
+        config.raise_on_length_error = options.fetch(:raise_on_length_error, global.raise_on_length_error)
+        config.api_endpoint = options[:api_endpoint] || global.api_endpoint
+      end
+
+      def build_query_params(params, content_type)
+        query = build_base_params(params)
+        add_sender_params(query, params)
+        add_optional_params(query, params)
+        query[:contentType] = content_type || @config.default_content_type
+        query
+      end
+
+      def build_base_params(params)
+        {
+          account: @config.account,
+          login: @config.login,
+          password: @config.password,
+          to: format_recipients(params[:to]),
+          message: encode_message(params[:message])
+        }
+      end
+
+      def add_sender_params(query, params)
+        if params[:sender_for_response]
+          query[:from] = ""
+          query[:senderForResponse] = "1"
+        else
+          sender = params[:sender] || @config.default_sender
+          query[:from] = sender if sender
+        end
+      end
+
+      def add_optional_params(query, params)
+        query[:deferred] = format_deferred(params[:deferred]) if params[:deferred]
+        query[:tag] = params[:tag] if params[:tag]
+        query[:class] = params[:sms_class].to_s if params[:sms_class]
+        query[:smsCoding] = params[:sms_coding].to_s if params[:sms_coding]
+        query[:noStop] = "1" if params[:no_stop]
+      end
+
+      def format_recipients(to)
+        phones = PhoneNumber.format_multiple(to, country_code: @config.default_country_code)
+        phones.join(",")
+      end
+
+      def encode_message(message)
+        # URL encoding is handled by Faraday, but we need to handle line breaks
+        # OVH uses %0d for line breaks in the URL
+        message.to_s.gsub("\n", "%0d").gsub("\r", "")
+      end
+
+      def format_deferred(deferred)
+        if deferred.respond_to?(:strftime)
+          # Format Time/DateTime as hhmmddMMYYYY
+          deferred.strftime("%H%M%d%m%Y")
+        else
+          deferred.to_s
+        end
+      end
+
+      def execute_request(query_params, content_type)
+        log_request(query_params)
+
+        response = make_http_request(query_params)
+        parsed_response = parse_response(response, content_type)
+
+        log_response(parsed_response)
+        handle_error_response(parsed_response) if parsed_response.failure?
+
+        parsed_response
+      rescue Faraday::Error => e
+        raise NetworkError.new(
+          "HTTP request failed: #{e.message}",
+          original_error: e
+        )
+      end
+
+      def make_http_request(query_params)
+        connection.get do |req|
+          req.params = query_params
+        end
+      end
+
+      def connection
+        @connection ||= Faraday.new(url: @config.api_endpoint) do |faraday|
+          faraday.options.timeout = @config.timeout
+          faraday.options.open_timeout = @config.timeout
+          faraday.adapter Faraday.default_adapter
+        end
+      end
+
+      def parse_response(http_response, content_type)
+        Response.parse(
+          http_response.body,
+          content_type: content_type || @config.default_content_type
+        )
+      end
+
+      def handle_error_response(response)
+        error_class = ERROR_HANDLERS[response.status]
+        return unless error_class
+
+        message = response.error_message || default_error_message(response.status)
+        raise error_class.new(message, raw_response: response.raw_response)
+      end
+
+      def default_error_message(status)
+        status == 401 ? "IP not authorized" : nil
+      end
+
+      def log_request(params)
+        return unless @config.logger
+
+        safe_params = params.dup
+        safe_params[:password] = "[FILTERED]"
+        @config.logger.debug("[OVH HTTP2SMS] Request: #{safe_params}")
+      end
+
+      def log_response(response)
+        return unless @config.logger
+
+        @config.logger.debug(
+          "[OVH HTTP2SMS] Response: status=#{response.status} success=#{response.success?}"
+        )
+      end
+    end
+  end
+end

data/lib/ovh/http2sms/configuration.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Ovh
+  module Http2sms
+    # Configuration class for OVH HTTP2SMS gem
+    #
+    # @example Block configuration
+    #   Ovh::Http2sms.configure do |config|
+    #     config.account = "sms-xx11111-1"
+    #     config.login = "user"
+    #     config.password = "secret"
+    #   end
+    #
+    # @example Environment variables
+    #   # Set OVH_SMS_ACCOUNT, OVH_SMS_LOGIN, OVH_SMS_PASSWORD
+    #   Ovh::Http2sms.deliver(to: "33601020304", message: "Hello!")
+    #
+    class Configuration
+      # @return [String, nil] SMS account identifier (ex: sms-xx11111-1)
+      attr_accessor :account
+
+      # @return [String, nil] SMS user login
+      attr_accessor :login
+
+      # @return [String, nil] SMS user password
+      attr_accessor :password
+
+      # @return [String, nil] Default sender name
+      attr_accessor :default_sender
+
+      # @return [String] Default response content type
+      attr_accessor :default_content_type
+
+      # @return [Integer] HTTP request timeout in seconds
+      attr_accessor :timeout
+
+      # @return [Logger, nil] Optional logger for debugging
+      attr_accessor :logger
+
+      # @return [String] Default country code for phone number formatting
+      attr_accessor :default_country_code
+
+      # @return [Boolean] Whether to raise errors on message length violations
+      attr_accessor :raise_on_length_error
+
+      # @return [String] API endpoint URL
+      attr_accessor :api_endpoint
+
+      # Environment variable prefix
+      ENV_PREFIX = "OVH_SMS_"
+
+      # Default values
+      DEFAULTS = {
+        default_content_type: "application/json",
+        timeout: 15,
+        default_country_code: "33",
+        raise_on_length_error: true,
+        api_endpoint: "https://www.ovh.com/cgi-bin/sms/http2sms.cgi"
+      }.freeze
+
+      def initialize
+        reset!
+      end
+
+      # Reset configuration to defaults and environment variables
+      #
+      # @return [void]
+      def reset!
+        # Set defaults
+        DEFAULTS.each do |key, value|
+          send("#{key}=", value)
+        end
+
+        # Clear credentials
+        self.account = nil
+        self.login = nil
+        self.password = nil
+        self.default_sender = nil
+        self.logger = nil
+
+        # Load from environment variables
+        load_from_env
+      end
+
+      # Check if the configuration is valid for making API requests
+      #
+      # @return [Boolean] true if required fields are present
+      def valid?
+        !account.nil? && !account.empty? &&
+          !login.nil? && !login.empty? &&
+          !password.nil? && !password.empty?
+      end
+
+      # Validate configuration and raise error if invalid
+      #
+      # @raise [ConfigurationError] if configuration is invalid
+      # @return [void]
+      def validate!
+        missing = find_missing_credentials
+        return if missing.empty?
+
+        raise ConfigurationError, build_validation_error_message(missing)
+      end
+
+      def find_missing_credentials
+        missing = []
+        missing << "account" if blank?(account)
+        missing << "login" if blank?(login)
+        missing << "password" if blank?(password)
+        missing
+      end
+
+      def blank?(value)
+        value.nil? || value.empty?
+      end
+
+      def build_validation_error_message(missing)
+        env_vars = missing.map { |m| "#{ENV_PREFIX}#{m.upcase}" }.join(", ")
+        "Missing required configuration: #{missing.join(", ")}. " \
+          "Set via Ovh::Http2sms.configure block or environment variables (#{env_vars})"
+      end
+
+      private
+
+      def load_from_env
+        self.account ||= ENV.fetch("#{ENV_PREFIX}ACCOUNT", nil)
+        self.login ||= ENV.fetch("#{ENV_PREFIX}LOGIN", nil)
+        self.password ||= ENV.fetch("#{ENV_PREFIX}PASSWORD", nil)
+        self.default_sender ||= ENV.fetch("#{ENV_PREFIX}DEFAULT_SENDER", nil)
+        self.default_content_type = ENV.fetch("#{ENV_PREFIX}DEFAULT_CONTENT_TYPE", default_content_type)
+        self.default_country_code = ENV.fetch("#{ENV_PREFIX}DEFAULT_COUNTRY_CODE", default_country_code)
+
+        env_timeout = ENV.fetch("#{ENV_PREFIX}TIMEOUT", nil)
+        self.timeout = env_timeout.to_i if env_timeout
+
+        env_raise_on_length = ENV.fetch("#{ENV_PREFIX}RAISE_ON_LENGTH_ERROR", nil)
+        self.raise_on_length_error = env_raise_on_length != "false" if env_raise_on_length
+      end
+    end
+  end
+end

data/lib/ovh/http2sms/errors.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Ovh
+  module Http2sms
+    # Base error class for all OVH HTTP2SMS errors
+    class Error < StandardError
+      # @return [Integer, nil] API status code if available
+      attr_reader :status_code
+
+      # @return [String, nil] Raw API response if available
+      attr_reader :raw_response
+
+      def initialize(message = nil, status_code: nil, raw_response: nil)
+        @status_code = status_code
+        @raw_response = raw_response
+        super(message)
+      end
+    end
+
+    # Raised when configuration is missing or invalid
+    #
+    # @example
+    #   raise ConfigurationError, "Missing required configuration: account"
+    class ConfigurationError < Error; end
+
+    # Raised when authentication fails (API status 401)
+    #
+    # @example
+    #   raise AuthenticationError.new("IP not authorized", status_code: 401)
+    class AuthenticationError < Error
+      def initialize(message = "Authentication failed: IP not authorized", **options)
+        super(message, **options.merge(status_code: 401))
+      end
+    end
+
+    # Raised when a required parameter is missing (API status 201)
+    #
+    # @example
+    #   raise MissingParameterError.new("Missing message")
+    class MissingParameterError < Error
+      # @return [String, nil] Name of the missing parameter
+      attr_reader :parameter
+
+      def initialize(message = "Missing required parameter", parameter: nil, **options)
+        @parameter = parameter
+        super(message, **options.merge(status_code: 201))
+      end
+    end
+
+    # Raised when a parameter value is invalid (API status 202)
+    #
+    # @example
+    #   raise InvalidParameterError.new("Invalid tag: is too long", parameter: "tag")
+    class InvalidParameterError < Error
+      # @return [String, nil] Name of the invalid parameter
+      attr_reader :parameter
+
+      def initialize(message = "Invalid parameter", parameter: nil, **options)
+        @parameter = parameter
+        super(message, **options.merge(status_code: 202))
+      end
+    end
+
+    # Raised when a network error occurs (timeout, connection failure, etc.)
+    #
+    # @example
+    #   raise NetworkError.new("Connection timed out")
+    class NetworkError < Error
+      # @return [Exception, nil] Original exception that caused the network error
+      attr_reader :original_error
+
+      def initialize(message = "Network error occurred", original_error: nil, **options)
+        @original_error = original_error
+        super(message, **options)
+      end
+    end
+
+    # Raised when message length exceeds SMS limits
+    #
+    # @example
+    #   raise MessageLengthError.new("Message exceeds GSM encoding limit", encoding: :gsm, length: 161)
+    class MessageLengthError < Error
+      # @return [Symbol] Encoding type (:gsm or :unicode)
+      attr_reader :encoding
+
+      # @return [Integer] Actual message length
+      attr_reader :length
+
+      # @return [Integer] Maximum allowed length
+      attr_reader :max_length
+
+      def initialize(message = "Message length error", encoding: nil, length: nil, max_length: nil, **options)
+        @encoding = encoding
+        @length = length
+        @max_length = max_length
+        super(message, **options)
+      end
+    end
+
+    # Raised when phone number format is invalid
+    #
+    # @example
+    #   raise PhoneNumberError.new("Invalid phone number format", phone_number: "abc123")
+    class PhoneNumberError < Error
+      # @return [String, nil] The invalid phone number
+      attr_reader :phone_number
+
+      def initialize(message = "Invalid phone number", phone_number: nil, **options)
+        @phone_number = phone_number
+        super(message, **options)
+      end
+    end
+
+    # Raised when validation fails before sending
+    #
+    # @example
+    #   raise ValidationError.new("Tag exceeds maximum length of 20 characters")
+    class ValidationError < Error; end
+
+    # Raised when the sender does not exist (API status 241)
+    #
+    # @example
+    #   raise SenderNotFoundError.new("Sender 'MyApp' not found")
+    class SenderNotFoundError < Error
+      # @return [String, nil] The sender that was not found
+      attr_reader :sender
+
+      def initialize(message = "Sender not found", sender: nil, **options)
+        @sender = sender
+        super(message, **options.merge(status_code: 241))
+      end
+    end
+
+    # Raised when the API response cannot be parsed
+    #
+    # @example
+    #   raise ResponseParseError.new("Invalid JSON", raw_response: "not json")
+    class ResponseParseError < Error
+      # @return [String, nil] The content type that failed to parse
+      attr_reader :content_type
+
+      def initialize(message = "Failed to parse API response", content_type: nil, **options)
+        @content_type = content_type
+        super(message, **options)
+      end
+    end
+  end
+end