ovh-http2sms 0.1.0

data/lib/ovh/http2sms/gsm_encoding.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "gsm_encoder"
+
+module Ovh
+  module Http2sms
+    # GSM 03.38 encoding utilities for SMS character counting
+    #
+    # Uses the gsm_encoder gem for character validation and provides
+    # OVH-specific SMS limits accounting for the STOP clause.
+    #
+    # Standard SMS messages use GSM 7-bit encoding which allows 160 characters.
+    # Extension characters (€, |, ^, {, }, [, ], ~, \) count as 2 characters.
+    # Non-GSM characters force Unicode encoding which limits messages to 70 characters.
+    #
+    # Commercial SMS must include STOP clause which uses 11 characters,
+    # reducing the first SMS limit.
+    module GsmEncoding
+      # SMS limits for GSM 7-bit encoding
+      GSM_SINGLE_SMS_LIMIT = 160
+      GSM_CONCAT_SMS_LIMIT = 153 # 7 chars used for UDH header in concatenated SMS
+      GSM_FIRST_COMMERCIAL_LIMIT = 149 # After STOP clause (11 chars)
+      GSM_CONCAT_COMMERCIAL_LIMIT = 153
+
+      # SMS limits for Unicode encoding
+      UNICODE_SINGLE_SMS_LIMIT = 70
+      UNICODE_CONCAT_SMS_LIMIT = 67 # 3 chars used for UDH header
+      UNICODE_FIRST_COMMERCIAL_LIMIT = 59 # After STOP clause (11 chars)
+      UNICODE_CONCAT_COMMERCIAL_LIMIT = 70
+
+      # Extension characters that count as 2 in GSM encoding
+      EXTENSION_CHARACTERS = Set["€", "|", "^", "{", "}", "[", "]", "~", "\\"].freeze
+
+      class << self
+        # Check if a message contains only GSM 03.38 characters
+        #
+        # @param message [String] The message to check
+        # @return [Boolean] true if all characters are GSM compatible
+        #
+        # @example
+        #   GsmEncoding.gsm_compatible?("Hello!") # => true
+        #   GsmEncoding.gsm_compatible?("Hello 👋") # => false
+        def gsm_compatible?(message)
+          GSMEncoder.can_encode?(message)
+        end
+
+        # Detect the required encoding for a message
+        #
+        # @param message [String] The message to analyze
+        # @return [Symbol] :gsm or :unicode
+        #
+        # @example
+        #   GsmEncoding.detect_encoding("Hello!") # => :gsm
+        #   GsmEncoding.detect_encoding("Привет") # => :unicode
+        def detect_encoding(message)
+          gsm_compatible?(message) ? :gsm : :unicode
+        end
+
+        # Calculate the GSM character count (extension chars count as 2)
+        #
+        # @param message [String] The message to count
+        # @return [Integer] Character count in GSM encoding
+        #
+        # @example
+        #   GsmEncoding.gsm_char_count("Hello") # => 5
+        #   GsmEncoding.gsm_char_count("Price: €10") # => 11 (€ counts as 2)
+        def gsm_char_count(message)
+          message.each_char.sum do |char|
+            EXTENSION_CHARACTERS.include?(char) ? 2 : 1
+          end
+        end
+
+        # Find all non-GSM characters in a message
+        #
+        # @param message [String] The message to check
+        # @return [Array<String>] Array of non-GSM characters found
+        #
+        # @example
+        #   GsmEncoding.non_gsm_characters("Hello 👋 World") # => ["👋"]
+        def non_gsm_characters(message)
+          message.each_char.reject { |char| can_encode_char?(char) }.uniq
+        end
+
+        # Calculate message info including SMS count
+        #
+        # @param message [String] The message to analyze
+        # @param commercial [Boolean] Whether this is a commercial SMS (includes STOP clause)
+        # @return [Hash] Message information with keys:
+        #   - :characters - Character count (accounting for extension chars in GSM)
+        #   - :encoding - :gsm or :unicode
+        #   - :sms_count - Number of SMS segments required
+        #   - :remaining - Characters remaining in current segment
+        #   - :max_single_sms - Maximum chars for single SMS with this encoding
+        #   - :non_gsm_chars - Array of non-GSM characters found (empty for GSM encoding)
+        #
+        # @example
+        #   GsmEncoding.message_info("Hello!")
+        #   # => { characters: 6, encoding: :gsm, sms_count: 1, remaining: 143, ... }
+        def message_info(message, commercial: true)
+          encoding = detect_encoding(message)
+
+          if encoding == :gsm
+            gsm_message_info(message, commercial: commercial)
+          else
+            unicode_message_info(message, commercial: commercial)
+          end
+        end
+
+        private
+
+        def can_encode_char?(char)
+          GSMEncoder.can_encode?(char)
+        end
+
+        def gsm_message_info(message, commercial:)
+          char_count = gsm_char_count(message)
+
+          first_limit = commercial ? GSM_FIRST_COMMERCIAL_LIMIT : GSM_SINGLE_SMS_LIMIT
+          concat_limit = commercial ? GSM_CONCAT_COMMERCIAL_LIMIT : GSM_CONCAT_SMS_LIMIT
+
+          sms_count, remaining = calculate_sms_count(char_count, first_limit, concat_limit)
+
+          {
+            characters: char_count,
+            encoding: :gsm,
+            sms_count: sms_count,
+            remaining: remaining,
+            max_single_sms: first_limit,
+            non_gsm_chars: []
+          }
+        end
+
+        def unicode_message_info(message, commercial:)
+          char_count = message.length
+
+          first_limit = commercial ? UNICODE_FIRST_COMMERCIAL_LIMIT : UNICODE_SINGLE_SMS_LIMIT
+          concat_limit = commercial ? UNICODE_CONCAT_COMMERCIAL_LIMIT : UNICODE_CONCAT_SMS_LIMIT
+
+          sms_count, remaining = calculate_sms_count(char_count, first_limit, concat_limit)
+
+          {
+            characters: char_count,
+            encoding: :unicode,
+            sms_count: sms_count,
+            remaining: remaining,
+            max_single_sms: first_limit,
+            non_gsm_chars: non_gsm_characters(message)
+          }
+        end
+
+        def calculate_sms_count(char_count, first_limit, concat_limit)
+          if char_count <= first_limit
+            [1, first_limit - char_count]
+          else
+            # Multi-part SMS calculation
+            remaining_after_first = char_count - first_limit
+            additional_sms = (remaining_after_first.to_f / concat_limit).ceil
+            total_sms = 1 + additional_sms
+
+            total_capacity = first_limit + (additional_sms * concat_limit)
+            remaining = total_capacity - char_count
+
+            [total_sms, remaining]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ovh/http2sms/phone_number.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Ovh
+  module Http2sms
+    # Phone number formatting and validation utilities
+    #
+    # Converts local phone number formats to international format required by OVH API.
+    # OVH requires the 00 prefix (e.g., 0033601020304 for French numbers).
+    # Supports configurable country codes for different regions.
+    #
+    # @example Convert French number
+    #   PhoneNumber.format("0601020304") # => "0033601020304"
+    #
+    # @example Convert UK number
+    #   PhoneNumber.format("07911123456", country_code: "44") # => "00447911123456"
+    module PhoneNumber
+      # Pattern for numbers starting with 0 but not 00 (local format)
+      LOCAL_FORMAT_PATTERN = /\A0(?!0)/
+
+      # Pattern for numbers starting with + (international format with plus)
+      PLUS_FORMAT_PATTERN = /\A\+/
+
+      # Pattern for numbers starting with 00 (already OVH format)
+      DOUBLE_ZERO_PATTERN = /\A00/
+
+      # Valid phone number pattern (digits only, 9-17 digits for 00 prefix format)
+      VALID_PHONE_PATTERN = /\A00\d{7,15}\z/
+
+      class << self
+        # Format a phone number to OVH international format (00 prefix)
+        #
+        # @param phone [String] Phone number in local or international format
+        # @param country_code [String] Country code to use for local numbers (default: from config)
+        # @return [String] Phone number in OVH format (e.g., "0033601020304")
+        # @raise [PhoneNumberError] if phone number is invalid
+        #
+        # @example Local French number
+        #   PhoneNumber.format("0601020304") # => "0033601020304"
+        #
+        # @example Already international with +
+        #   PhoneNumber.format("+33601020304") # => "0033601020304"
+        #
+        # @example Already OVH format
+        #   PhoneNumber.format("0033601020304") # => "0033601020304"
+        #
+        # @example UK number
+        #   PhoneNumber.format("07911123456", country_code: "44") # => "00447911123456"
+        def format(phone, country_code: nil)
+          return nil if phone.nil?
+
+          country_code ||= Ovh::Http2sms.configuration.default_country_code
+
+          # Remove all non-digit characters except leading +
+          cleaned = clean_phone(phone)
+
+          # Convert to OVH international format (00 prefix)
+          formatted = to_ovh_format(cleaned, country_code)
+
+          # Validate the result
+          validate!(formatted)
+
+          formatted
+        end
+
+        # Format multiple phone numbers
+        #
+        # @param phones [Array<String>, String] Phone number(s) - can be array or comma-separated string
+        # @param country_code [String] Country code to use for local numbers
+        # @return [Array<String>] Array of formatted phone numbers
+        # @raise [PhoneNumberError] if any phone number is invalid
+        #
+        # @example Array input
+        #   PhoneNumber.format_multiple(["0601020304", "0602030405"])
+        #   # => ["0033601020304", "0033602030405"]
+        #
+        # @example Comma-separated string
+        #   PhoneNumber.format_multiple("0601020304,0602030405")
+        #   # => ["0033601020304", "0033602030405"]
+        def format_multiple(phones, country_code: nil)
+          phone_array = phones.is_a?(Array) ? phones : phones.to_s.split(",")
+          phone_array.map { |p| format(p.strip, country_code: country_code) }
+        end
+
+        # Validate a phone number format
+        #
+        # @param phone [String] Phone number to validate
+        # @return [Boolean] true if valid
+        def valid?(phone)
+          return false if phone.nil? || phone.empty?
+
+          phone.match?(VALID_PHONE_PATTERN)
+        end
+
+        # Validate a phone number and raise error if invalid
+        #
+        # @param phone [String] Phone number to validate
+        # @raise [PhoneNumberError] if phone number is invalid
+        # @return [void]
+        def validate!(phone)
+          return if valid?(phone)
+
+          raise PhoneNumberError.new(
+            "Invalid phone number format: '#{phone}'. " \
+            "Expected OVH format with 00 prefix (e.g., 0033601020304)",
+            phone_number: phone
+          )
+        end
+
+        private
+
+        def clean_phone(phone)
+          # Remove all whitespace, dashes, dots, and parentheses
+          phone.to_s.gsub(/[\s\-.()\[\]]/, "")
+        end
+
+        def to_ovh_format(phone, country_code)
+          if phone.match?(PLUS_FORMAT_PATTERN)
+            # +33601020304 -> 0033601020304
+            "00#{phone.sub(PLUS_FORMAT_PATTERN, "")}"
+          elsif phone.match?(DOUBLE_ZERO_PATTERN)
+            # Already in OVH format: 0033601020304
+            phone
+          elsif phone.match?(LOCAL_FORMAT_PATTERN)
+            # 0601020304 -> 0033601020304
+            "00#{country_code}#{phone.sub(LOCAL_FORMAT_PATTERN, "")}"
+          else
+            # Assume raw country code format: 33601020304 -> 0033601020304
+            "00#{phone}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ovh/http2sms/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ovh
+  module Http2sms
+    # Rails integration for OVH HTTP2SMS
+    #
+    # Automatically loads generators and sets up Rails-specific defaults.
+    class Railtie < Rails::Railtie
+      generators do
+        require_relative "../../generators/ovh/http2sms/install_generator"
+      end
+
+      initializer "ovh_http2sms.set_defaults" do
+        # Set Rails logger as default if not already configured
+        config.after_initialize do
+          if Ovh::Http2sms.configuration.logger.nil? && defined?(Rails.logger)
+            Ovh::Http2sms.configuration.logger = Rails.logger
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ovh/http2sms/response.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ovh
+  module Http2sms
+    # Response object for OVH HTTP2SMS API responses
+    #
+    # Parses responses in all supported formats: JSON, XML, HTML, and text/plain.
+    # Provides a unified interface for accessing response data.
+    #
+    # @example Successful response
+    #   response = Response.parse(body, content_type: "application/json")
+    #   response.success? # => true
+    #   response.sms_ids # => ["123456789"]
+    #   response.credits_remaining # => 1987.0
+    #
+    # @example Error response
+    #   response = Response.parse(body, content_type: "application/json")
+    #   response.success? # => false
+    #   response.error_message # => "Missing message"
+    class Response
+      # @return [Integer] API status code (100, 101 = success; 201, 202, 401 = error)
+      attr_reader :status
+
+      # @return [Float, nil] Remaining SMS credits
+      attr_reader :credits_remaining
+
+      # @return [Array<String>] SMS IDs for sent messages
+      attr_reader :sms_ids
+
+      # @return [String, nil] Error message if request failed
+      attr_reader :error_message
+
+      # @return [String] Raw response body
+      attr_reader :raw_response
+
+      # @return [String] Content type of the response
+      attr_reader :content_type
+
+      # Success status codes
+      SUCCESS_CODES = [100, 101].freeze
+
+      # Error status codes
+      ERROR_CODES = {
+        201 => :missing_parameter,
+        202 => :invalid_parameter,
+        241 => :sender_not_found,
+        401 => :authentication_error
+      }.freeze
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(status:, credits_remaining: nil, sms_ids: [], error_message: nil,
+                     raw_response: nil, content_type: nil)
+        # rubocop:enable Metrics/ParameterLists
+        @status = status
+        @credits_remaining = credits_remaining
+        @sms_ids = Array(sms_ids).map(&:to_s)
+        @error_message = error_message
+        @raw_response = raw_response
+        @content_type = content_type
+      end
+
+      # Check if the request was successful
+      #
+      # @return [Boolean] true if status code indicates success (100 or 101)
+      def success?
+        SUCCESS_CODES.include?(status)
+      end
+
+      # Check if the request failed
+      #
+      # @return [Boolean] true if status code indicates failure
+      def failure?
+        !success?
+      end
+
+      # Get the error type based on status code
+      #
+      # @return [Symbol, nil] Error type (:missing_parameter, :invalid_parameter, :authentication_error)
+      def error_type
+        ERROR_CODES[status]
+      end
+
+      # Parse a raw API response
+      #
+      # @param body [String] Raw response body
+      # @param content_type [String] Content-Type header value
+      # @return [Response] Parsed response object
+      #
+      # @example Parse JSON response
+      #   Response.parse('{"status":100,"creditLeft":"1987","SmsIds":["123"]}', content_type: "application/json")
+      def self.parse(body, content_type: "text/plain")
+        parser = ResponseParser.new(body, content_type)
+        parser.parse
+      end
+    end
+
+    # Internal parser for different response formats
+    # @api private
+    class ResponseParser
+      def initialize(body, content_type)
+        @body = body.to_s
+        @content_type = content_type.to_s.downcase
+      end
+
+      def parse
+        case @content_type
+        when /json/
+          parse_json
+        when /xml/
+          parse_xml
+        when /html/
+          parse_html
+        else
+          parse_plain
+        end
+      rescue StandardError => e
+        # If parsing fails, raise a specific error
+        raise ResponseParseError.new(
+          "Failed to parse API response: #{e.message}",
+          content_type: @content_type,
+          raw_response: @body
+        )
+      end
+
+      private
+
+      def parse_json
+        data = JSON.parse(@body)
+
+        Response.new(
+          status: data["status"].to_i,
+          credits_remaining: parse_credits(data["creditLeft"]),
+          sms_ids: data["SmsIds"] || data["smsIds"] || [],
+          error_message: data["message"],
+          raw_response: @body,
+          content_type: @content_type
+        )
+      end
+
+      def parse_xml
+        # Simple XML parsing without additional dependencies
+        status = extract_xml_value("status").to_i
+        credits = parse_credits(extract_xml_value("creditLeft"))
+        message = extract_xml_value("message")
+        sms_ids = extract_xml_sms_ids
+
+        Response.new(
+          status: status,
+          credits_remaining: credits,
+          sms_ids: sms_ids,
+          error_message: message,
+          raw_response: @body,
+          content_type: @content_type
+        )
+      end
+
+      def parse_html
+        # HTML format: OK/KO<br>credits/message<br>sms_id<br>
+        lines = extract_html_lines
+
+        parse_text_lines(lines)
+      end
+
+      def parse_plain
+        # Text/plain format:
+        # OK\n1987\n123456789
+        # or
+        # KO\nError message
+        lines = @body.strip.split(/\r?\n/)
+
+        parse_text_lines(lines)
+      end
+
+      def parse_text_lines(lines)
+        return empty_response if lines.empty?
+
+        status_line = lines[0].to_s.strip.upcase
+
+        if status_line == "OK"
+          parse_success_lines(lines)
+        else
+          parse_error_lines(lines, status_line)
+        end
+      end
+
+      def parse_success_lines(lines)
+        credits = lines[1] ? parse_credits(lines[1]) : nil
+        sms_ids = lines[2..].map(&:strip).reject(&:empty?)
+
+        Response.new(
+          status: 100,
+          credits_remaining: credits,
+          sms_ids: sms_ids,
+          raw_response: @body,
+          content_type: @content_type
+        )
+      end
+
+      def parse_error_lines(lines, status_line)
+        # Status might be numeric (like in some error cases) or "KO"
+        status = status_line == "KO" ? 0 : status_line.to_i
+        error_message = lines[1..].join("\n").strip
+
+        # Try to extract status code from message if present
+        if error_message =~ /\A(\d{3})\s/
+          status = ::Regexp.last_match(1).to_i
+          error_message = error_message.sub(/\A\d{3}\s*/, "")
+        end
+
+        Response.new(
+          status: status,
+          error_message: error_message.empty? ? "Unknown error" : error_message,
+          raw_response: @body,
+          content_type: @content_type
+        )
+      end
+
+      def empty_response
+        Response.new(
+          status: 0,
+          error_message: "Empty response",
+          raw_response: @body,
+          content_type: @content_type
+        )
+      end
+
+      def extract_xml_value(tag)
+        match = @body.match(%r{<#{tag}>(.*?)</#{tag}>}i)
+        match ? match[1] : nil
+      end
+
+      def extract_xml_sms_ids
+        # Handle both <smsIds><smsId>...</smsId></smsIds> format
+        ids = []
+        @body.scan(%r{<smsId>(.*?)</smsId>}i) { |match| ids << match[0] }
+        ids
+      end
+
+      def extract_html_lines
+        # Extract content between <BODY> tags and split by <br>
+        body_match = @body.match(%r{<BODY>(.*?)</BODY>}im)
+        return [] unless body_match
+
+        body_content = body_match[1]
+        body_content.split(%r{<br\s*/?>}).map(&:strip).reject(&:empty?)
+      end
+
+      def parse_credits(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        Float(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end