mitake_sms 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0145815894a3f478ba54c0cc151d8753f0dd99bab584128fdeaad3a5e37bf7b
-  data.tar.gz: 8a83a7ed6f9b43cced0aa4a1130f361669f0043d78767603f505d7465b3aa773
+  metadata.gz: 46484a48ae04607708212f2512b21b7a941a365f3282783beca9f695a79c0fc6
+  data.tar.gz: 446cc3b004842cede09f38f6516a5a03ada342a50d0d79e840a7eefdbc6ba398
 SHA512:
-  metadata.gz: ec120586bd986581175e851ed2a974cc9452ba1e8f964fa59dad0b23a9564671f62d205339d5f82e90d0fcd21f696c115ef4159c60a88d78a6be6255421e36d4
-  data.tar.gz: 1716857937144e700d23a88445468856cbd67c7bd5e921e2ac32987216f24acaab4ebba161dadd58fbcce9641c11fbcfe6be307a940e315b3f0b803237818363
+  metadata.gz: e1fcbca7044f634e710b7fc34afbf19f576529bd1b155d212b1d4be158ea31cee05e950c5089517ae4112a9c63251af462f8df7213ccde4c517a622b4fa4b214
+  data.tar.gz: c3a4955cd4c9b4476bc36bf032b3af9effc002ccd2646db04d3df195d116ca885e76bb03c6f8a5ce1c7fe423a01fa33510774938729040b5d8d7a6da8ef7dff4

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2025-05-25
+### Added
+- Added proper handling of newlines in message text (converts to ASCII code 6)
+- Added URL encoding for message content to handle special characters
+- Added advanced batch SMS format support using ClientID $$ dstaddr $$ dlvtime $$ vldtime $$ destname $$ response $$ smbody
+- Added automatic generation of unique ClientIDs for advanced batch SMS
+
+### Changed
+- Improved message formatting to comply with Mitake API requirements
+- Enhanced test coverage to 92.81%
+
+## [1.1.0] - 2025-05-24
+### Added
+- Added automatic handling of the 500 message limit for batch SMS sending
+- Added UTF-8 encoding support by default for all SMS messages
+- Added `CharsetURL` parameter for single SMS messages
+- Added `Encoding_PostIn` parameter for batch SMS messages
+- Added ability to customize character encoding via options
+
+### Changed
+- Updated documentation to reflect new encoding options
+- Improved batch sending with automatic splitting of large batches
+
 ## [1.0.0] - 2025-05-24
 ### Added
 - Initial stable release

data/README.md

@@ -7,7 +7,8 @@ A Ruby client for the Mitake SMS API, providing a simple and efficient way to se
 ## Features
 
 - Send single SMS messages
-- Send batch SMS messages
+- Send batch SMS messages with automatic handling of the 500 message API limit
+- UTF-8 encoding support by default
 - Configurable API settings
 - Simple and intuitive API
 - Comprehensive error handling
@@ -44,14 +45,14 @@ require 'mitake_sms'
 MitakeSms.configure do |config|
   config.username = 'your_username'  # Your Mitake SMS API username
   config.password = 'your_password'  # Your Mitake SMS API password
-  config.api_url = 'https://smsapi.mitake.com.tw/api/mtk/'  # Default API URL
+  config.api_url = 'https://smsapi.mitake.com.tw/b2c/mtk/'  # Default API URL
 end
 ```
 
 ### Sending a Single SMS
 
 ```ruby
-# Send a simple SMS
+# Send a simple SMS (uses UTF-8 encoding by default)
 response = MitakeSms.send_sms('0912345678', 'Hello, this is a test message!')
 
 if response.success?
@@ -67,7 +68,8 @@ response = MitakeSms.send_sms(
   'Hello with options!',
   from: 'YourBrand',
   response_url: 'https://your-callback-url.com/delivery-reports',
-  client_id: 'your-client-reference-id'
+  client_id: 'your-client-reference-id',
+  charset: 'BIG5'  # Override the default UTF-8 encoding if needed
 )
 ```
 
@@ -80,17 +82,119 @@ messages = [
   { to: '0933555777', text: 'Third message', response_url: 'https://your-callback-url.com/reports' }
 ]
 
+# Automatically handles batches according to the Mitake SMS API limit (500 messages per request)
+# If you send more than 500 messages, they will be automatically split into multiple requests
+# Uses UTF-8 encoding by default
 response = MitakeSms.batch_send(messages)
 
-if response.success?
+# You can specify a different character encoding if needed
+response = MitakeSms.batch_send(messages, charset: 'BIG5')
+
+# If fewer than 500 messages, you'll get a single response
+if response.is_a?(MitakeSms::Response) && response.success?
   puts "Batch sent successfully!"
   puts "Message ID: #{response.message_id}"
   puts "Remaining points: #{response.account_point}"
+
+# If more than 500 messages, you'll get an array of responses
+elsif response.is_a?(Array)
+  response.each_with_index do |batch_response, index|
+    if batch_response.success?
+      puts "Batch #{index + 1} sent successfully!"
+      puts "Message ID: #{batch_response.message_id}"
+      puts "Remaining points: #{batch_response.account_point}"
+    else
+      puts "Batch #{index + 1} failed: #{batch_response.error}"
+    end
+  end
 else
   puts "Failed to send batch: #{response.error}"
 end
 ```
 
+### Sending Large Batches with Custom Limit
+
+```ruby
+# Create a large batch of messages
+messages = (1..1000).map do |i|
+  { to: '0912345678', text: "Message #{i}" }
+end
+
+# The Mitake SMS API has a limit of 500 messages per request
+# However, you can set a lower limit if needed for your use case
+# This will split into batches of 300 messages each
+# Uses UTF-8 encoding by default
+responses = MitakeSms.batch_send_with_limit(messages, 300)
+
+# You can specify a different character encoding if needed
+responses = MitakeSms.batch_send_with_limit(messages, 300, charset: 'BIG5')
+
+# Process the array of responses
+responses.each_with_index do |batch_response, index|
+  if batch_response.success?
+    puts "Batch #{index + 1} sent successfully!"
+  else
+    puts "Batch #{index + 1} failed: #{batch_response.error}"
+  end
+end
+```
+
+### Sending Advanced Format Batch SMS
+
+The advanced format allows more control over each message in the batch, including scheduled delivery, validity period, recipient name, and more:
+
+```ruby
+# Create messages with advanced options
+messages = [
+  {
+    client_id: 'unique-id-20250525-001', # Client reference ID (auto-generated if not provided)
+    to: '0912345678',                    # Required recipient phone number
+    dlvtime: '20250526120000',           # Optional delivery time (YYYYMMDDhhmmss)
+    vldtime: '20250527120000',           # Optional validity period (YYYYMMDDhhmmss)
+    dest_name: '大寶',                   # Optional recipient name
+    response: 'https://callback.url',    # Optional callback URL
+    text: '這是一則測試簡訊'             # Required message content
+  },
+  {
+    # client_id will be auto-generated if not provided
+    to: '0922333444',
+    text: '這是另一則測試簡訊'
+    # Other fields are optional
+  }
+]
+
+# Note about ClientID:
+# - ClientID is used by Mitake to prevent duplicate message sending within 12 hours
+# - If not provided, a unique ID will be automatically generated using timestamp and random values
+# - For custom tracking, you can provide your own unique ClientID
+#
+# Note about message text formatting:
+# - If your message text contains line breaks (\n), they will be automatically converted
+#   to ASCII code 6 as required by the Mitake API
+# - Example: "First line\nSecond line" will be properly displayed with a line break on the recipient's device
+# - Special characters like '&' are automatically URL encoded to ensure proper transmission
+# - Long messages will be automatically split into multiple SMS messages if your account doesn't
+#   have long message permissions
+
+# Send using advanced format (automatically handles 500 message limit)
+response = MitakeSms.advanced_batch_send(messages)
+
+# Process response similar to regular batch sending
+if response.is_a?(MitakeSms::Response) && response.success?
+  puts "Advanced batch sent successfully!"
+  puts "Message ID: #{response.message_id}"
+  puts "Remaining points: #{response.account_point}"
+elsif response.is_a?(Array)
+  response.each_with_index do |batch_response, index|
+    if batch_response.success?
+      puts "Batch #{index + 1} sent successfully!"
+    else
+      puts "Batch #{index + 1} failed: #{batch_response.error}"
+    end
+  end
+end
+```
+
 ### Error Handling
 
 The gem provides specific error classes for different types of errors:

data/lib/mitake_sms/client.rb

@@ -26,13 +26,26 @@ module MitakeSms
     # @option options [String] :from sender ID
     # @option options [String] :response_url callback URL for delivery reports
     # @option options [String] :client_id client reference ID
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
     # @return [MitakeSms::Response] response object
     def send_sms(to, text, options = {})
+      require 'uri'
+      charset = options.delete(:charset) || 'UTF8'
+      
+      # Replace any newline characters with ASCII code 6 (ACK)
+      # This is required by the Mitake API to represent line breaks
+      processed_text = text.to_s.gsub("\n", 6.chr)
+      
+      # URL encode the message content to handle special characters like '&'
+      # This is required by the Mitake API
+      message_text = URI.encode_www_form_component(processed_text)
+
       params = {
         username: @config.username,
         password: @config.password,
         dstaddr: to,
-        smbody: text.encode('BIG5', invalid: :replace, undef: :replace, replace: '?')
+        smbody: message_text,
+        CharsetURL: charset
       }.merge(options.slice(:from, :response_url, :client_id))
 
       response = @connection.post('SmSend', params)
@@ -42,22 +55,161 @@ module MitakeSms
     # Send multiple SMS in a single request
     # @param messages [Array<Hash>] array of message hashes
     #   Each hash should contain :to and :text keys, and can include :from, :response_url, :client_id
+    # @param options [Hash] additional options
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
+    # @option options [Boolean] :skip_encoding skip URL encoding (for tests)
+    # @return [MitakeSms::Response, Array<MitakeSms::Response>] response object or array of response objects if batch was split
+    def batch_send(messages, options = {})
+      # Mitake SMS API has a limit of 500 messages per request
+      # Automatically split larger batches into multiple requests of 500 messages each
+      batch_send_with_limit(messages, 500, options)
+    end
+
+    # Send multiple SMS in a single request with a limit per request
+    # @param messages [Array<Hash>] array of message hashes
+    #   Each hash should contain :to and :text keys, and can include :from, :response_url, :client_id
+    # @param limit [Integer] maximum number of messages per request (default: 500)
+    # @param options [Hash] additional options
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
+    # @option options [Boolean] :skip_encoding skip URL encoding (for tests)
+    # @return [MitakeSms::Response, Array<MitakeSms::Response>] response object or array of response objects if batch was split
+    def batch_send_with_limit(messages, limit = 500, options = {})
+      charset = options[:charset] || 'UTF8'
+
+      # If messages count is within the limit, use the regular batch send
+      return send_batch(messages, charset, options) if messages.size <= limit
+
+      # Otherwise, split into batches of the specified limit
+      responses = []
+      messages.each_slice(limit) do |batch|
+        responses << send_batch(batch, charset, options)
+      end
+
+      # Return array of responses
+      responses
+    end
+
+    # Send multiple SMS in a single request using advanced format
+    # @param messages [Array<Hash>] array of message hashes with advanced options
+    #   Each hash can contain the following keys:
+    #   - :client_id [String] client reference ID (required)
+    #   - :to [String] recipient phone number (required)
+    #   - :dlvtime [String] delivery time in format YYYYMMDDHHMMSS (optional)
+    #   - :vldtime [String] valid until time in format YYYYMMDDHHMMSS (optional)
+    #   - :dest_name [String] recipient name (optional)
+    #   - :response [String] callback URL for delivery reports (optional)
+    #   - :text [String] message content (required)
+    # @param options [Hash] additional options
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
+    # @option options [Boolean] :skip_encoding skip URL encoding (for tests)
+    # @return [MitakeSms::Response, Array<MitakeSms::Response>] response object or array of response objects if batch was split
+    def advanced_batch_send(messages, options = {})
+      # Mitake SMS API has a limit of 500 messages per request
+      # Automatically split larger batches into multiple requests of 500 messages each
+      advanced_batch_send_with_limit(messages, 500, options)
+    end
+
+    # Send multiple SMS in a single request with a limit per request using advanced format
+    # @param messages [Array<Hash>] array of message hashes with advanced options
+    # @param limit [Integer] maximum number of messages per request (default: 500)
+    # @param options [Hash] additional options
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
+    # @option options [Boolean] :skip_encoding skip URL encoding (for tests)
+    # @return [MitakeSms::Response, Array<MitakeSms::Response>] response object or array of response objects if batch was split
+    def advanced_batch_send_with_limit(messages, limit = 500, options = {})
+      charset = options[:charset] || 'UTF8'
+
+      # If messages count is within the limit, use the regular batch send
+      return send_advanced_batch(messages, charset, options) if messages.size <= limit
+
+      # Otherwise, split into batches of the specified limit
+      responses = []
+      messages.each_slice(limit) do |batch|
+        responses << send_advanced_batch(batch, charset, options)
+      end
+
+      # Return array of responses
+      responses
+    end
+
+    private
+
+    # Internal method to send a single batch
+    # @param batch [Array<Hash>] array of message hashes for a single batch
+    # @param charset [String] character encoding, defaults to 'UTF8'
+    # @param options [Hash] additional options
     # @return [MitakeSms::Response] response object
-    def batch_send(messages)
+    def send_batch(batch, charset = 'UTF8', options = {})
+      require 'uri'
+      
       params = {
         username: @config.username,
         password: @config.password,
-        smbody: messages.map do |msg|
+        smbody: batch.map do |msg|
           to = msg[:to]
-          text = msg[:text].to_s.encode('BIG5', invalid: :replace, undef: :replace, replace: '?')
-          "#{to}:#{text}"
-        end.join("\n")
+          
+          # Replace any newline characters with ASCII code 6 (ACK)
+          # This is required by the Mitake API to represent line breaks
+          processed_text = msg[:text].to_s.gsub("\n", 6.chr)
+          
+          # URL encode the message content to handle special characters like '&'
+          # This is required by the Mitake API
+          message_text = URI.encode_www_form_component(processed_text)
+          
+          "#{to}:#{message_text}"
+        end.join("\n"),
+        Encoding_PostIn: charset
       }
+      
       response = @connection.post('SmBulkSend', params)
       handle_response(response)
     end
 
-    private
+    # Internal method to send a single batch using advanced format
+    # @param batch [Array<Hash>] array of message hashes for a single batch with advanced options
+    # @param charset [String] character encoding, defaults to 'UTF8'
+    # @param options [Hash] additional options
+    # @return [MitakeSms::Response] response object
+    def send_advanced_batch(batch, charset = 'UTF8', options = {})
+      require 'uri'
+      
+      # Format each message according to the advanced format
+      # ClientID $$ dstaddr $$ dlvtime $$ vldtime $$ destname $$ response $$ smbody
+      body = batch.map do |msg|
+        # ClientID is required and must be unique
+        # If not provided, generate a unique ID
+        client_id = msg[:client_id]
+        if client_id.nil? || client_id.empty?
+          client_id = generate_unique_client_id
+        end
+
+        to = msg[:to]
+        dlvtime = msg[:dlvtime] || ''
+        vldtime = msg[:vldtime] || ''
+        dest_name = msg[:dest_name] || ''
+        response_url = msg[:response] || ''
+        
+        # Replace any newline characters in the message text with ASCII code 6 (ACK)
+        # This is required by the Mitake API to represent line breaks within message content
+        processed_text = msg[:text].to_s.gsub("\n", 6.chr)
+        
+        # URL encode the message content to handle special characters like '&'
+        # This is required by the Mitake API
+        text = URI.encode_www_form_component(processed_text)
+
+        [client_id, to, dlvtime, vldtime, dest_name, response_url, text].join('$$')
+      end.join("\n")
+
+      params = {
+        username: @config.username,
+        password: @config.password,
+        data: body,
+        Encoding_PostIn: charset
+      }
+
+      response = @connection.post('SmPost', params)
+      handle_response(response)
+    end
 
     def build_connection
       Faraday.new(url: @config.api_url) do |conn|
@@ -83,5 +235,16 @@ module MitakeSms
         raise Error, "Unexpected error: #{response.status}"
       end
     end
+
+    # Generate a unique client ID for SMS messages
+    # @return [String] a unique ID combining timestamp and random values
+    def generate_unique_client_id
+      require 'securerandom'
+
+      # Generate a unique ID using timestamp (to milliseconds) and a random UUID portion
+      timestamp = Time.now.strftime('%Y%m%d%H%M%S%L')
+      random_part = SecureRandom.uuid.gsub('-', '')[0, 8]
+      "#{timestamp}-#{random_part}"
+    end
   end
 end

data/lib/mitake_sms/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MitakeSms
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/mitake_sms.rb

@@ -42,17 +42,65 @@ module MitakeSms
     # @option options [String] :from sender ID
     # @option options [String] :response_url callback URL for delivery reports
     # @option options [String] :client_id client reference ID
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
+
     # @return [MitakeSms::Response] response object
     def send_sms(to, text, options = {})
       client.send_sms(to, text, options)
     end
 
     # Send multiple SMS messages in a single request
+    # The Mitake SMS API has a limit of 500 messages per request
+    # If more than 500 messages are provided, they will be automatically split into multiple requests
     # @param messages [Array<Hash>] array of message hashes
     #   Each hash should contain :to and :text keys, and can include :from, :response_url, :client_id
-    # @return [MitakeSms::Response] response object
-    def batch_send(messages)
-      client.batch_send(messages)
+    # @param options [Hash] additional options
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
+
+    # @return [MitakeSms::Response, Array<MitakeSms::Response>] response object or array of response objects if batch was split
+    def batch_send(messages, options = {})
+      client.batch_send_with_limit(messages, 500, options)
+    end
+
+    # Send multiple SMS messages in a single request with a limit per request
+    # @param messages [Array<Hash>] array of message hashes
+    #   Each hash should contain :to and :text keys, and can include :from, :response_url, :client_id
+    # @param limit [Integer] maximum number of messages per request (default: 500)
+    # @param options [Hash] additional options
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
+
+    # @return [MitakeSms::Response, Array<MitakeSms::Response>] response object or array of response objects if batch was split
+    def batch_send_with_limit(messages, limit = 500, options = {})
+      client.batch_send_with_limit(messages, limit, options)
+    end
+    
+    # Send multiple SMS messages in a single request using advanced format
+    # @param messages [Array<Hash>] array of message hashes with advanced options
+    #   Each hash can contain the following keys:
+    #   - :client_id [String] client reference ID (optional)
+    #   - :to [String] recipient phone number (required)
+    #   - :dlvtime [String] delivery time in format YYYYMMDDHHMMSS (optional)
+    #   - :vldtime [String] valid until time in format YYYYMMDDHHMMSS (optional)
+    #   - :dest_name [String] recipient name (optional)
+    #   - :response [String] callback URL for delivery reports (optional)
+    #   - :text [String] message content (required)
+    # @param options [Hash] additional options
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
+
+    # @return [MitakeSms::Response, Array<MitakeSms::Response>] response object or array of response objects if batch was split
+    def advanced_batch_send(messages, options = {})
+      client.advanced_batch_send(messages, options)
+    end
+    
+    # Send multiple SMS messages in a single request with a limit per request using advanced format
+    # @param messages [Array<Hash>] array of message hashes with advanced options
+    # @param limit [Integer] maximum number of messages per request (default: 500)
+    # @param options [Hash] additional options
+    # @option options [String] :charset character encoding, defaults to 'UTF8'
+
+    # @return [MitakeSms::Response, Array<MitakeSms::Response>] response object or array of response objects if batch was split
+    def advanced_batch_send_with_limit(messages, limit = 500, options = {})
+      client.advanced_batch_send_with_limit(messages, limit, options)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mitake_sms
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Zac