mitake_sms 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39775d8249e44177aa4d89da4716abc178ccd834e6c653549389a419f305d08c
-  data.tar.gz: c47d00857751465b785cfe5da97b858b7c78722a8f65fd81d6e965de06541730
+  metadata.gz: 0cf544b42ee5585ab48ee884c607ac8172d612050808ad6d7a04d3d1b50f84de
+  data.tar.gz: 5ab5cb554757c3f064c130941bc5f6c7e1fb46b861d80f07031dbdc466eccf19
 SHA512:
-  metadata.gz: 04bea4cc56b8294f4e5ecc6667a6378ed49bc13221c4766e6b3102421ad598b118d0793bdf7cf900340013fcfe83484f6b64b75d55c1f2e508330c7aef26c49c
-  data.tar.gz: df170765544707a1b51ee0240811f4b379211f146725504d5b496c41792be713f13cf86ed4565689d51f2d09510f1b0a6df72a43512753bdc901fdb632402a38
+  metadata.gz: 528e04551ed3d097c43c513ea289096167b58c16b0a11637fc6ba0baa414a1082cc0ffbbac11ea470349aab2f536fe4280736340929d5eb468bbe7680ff72b29
+  data.tar.gz: f40efa10e466af71bea9cabb2d5f18dbf82a38250528f7cf319d7aac19ab02141fd0759105890f08c82f7e03e44f8881a801382a6cffbaca90bc747a35cdcdd6

data/CHANGELOG.md

@@ -5,7 +5,59 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [3.0.0] - 2026-07-28
+### Changed
+- Raised `required_ruby_version` to `>= 3.3.0`, from `>= 2.6.0`. CI now runs against
+  3.3, 3.4 and ruby/head rather than 3.3 alone
+- Raised the Faraday floor to `>= 2.14.3`, which is the oldest release without
+  CVE-2026-54297 (`NestedParamsEncoder` recursion DoS), CVE-2026-33637 and
+  CVE-2026-25765 (SSRF via protocol-relative URL host override). This drops support
+  for the Faraday 1.x line, whose patched `1.10.6` cannot be expressed alongside the
+  2.x floor in a single requirement
+
+### Added
+- `Response#message_ids`, `#client_id`, `#duplicate?`, `#sms_point` and `#records`, exposing the
+  `[clientid]`, `Duplicate` and `smsPoint` fields the API returns but the parser previously dropped
+
+### Fixed
+- `batch_send` raises `ArgumentError` when a field other than `:text` contains `$$` or a line break.
+  Both are `SmBulkSend` delimiters, so a `destname` holding either one silently shifted the remaining
+  fields or split the row in two, corrupting that message and every field after it
+- `batch_send` forwards options such as `:objectID` and `:smsPointFlag` to the API. It previously
+  accepted and discarded everything except `:charset`, so `smsPoint` could never be requested
+- Message bodies containing `\r\n` or a bare `\r` are now converted to ASCII code 6 like `\n` already
+  was. A `\r\n` body previously kept a stray carriage return, and a `\r`-only body was left unconverted
+- Message bodies are transcoded to UTF-8 before sending, so a Big5 or otherwise non-UTF-8 string
+  arrives intact instead of as mojibake, and a batch mixing encodings no longer raises
+  `Encoding::CompatibilityError` while being assembled
+- `Response#success?` returns false for a reply containing no records at all, rather than reporting
+  success off a vacuously true empty check
+- `Response` now parses the reply as a list of records split on the `[clientid]` header, instead of
+  flattening every line into one hash. A `SmBulkSend` reply previously kept only the last message's
+  `msgid` and `statuscode`, silently discarding the result of every other message in the batch
+- `Response#error` returns the documented reason for a failing `statuscode` (附錄二). It previously
+  read an `Error` field that does not exist in the API, so it was always `nil`
+- `Response#success?` accepts statuscode `0` (預約傳送中), `2` and `4` in addition to `1`. Scheduled
+  sends were previously reported as failures. For a batch it is now true only if every record was
+  accepted
+- `Response#account_point` is read as a reply-level value rather than being attached to whichever
+  record happened to be last
+- `send_sms` now sends the callback URL as `response` and the dedup key as `clientid`, matching the
+  Mitake API spec. They were previously sent as `response_url` and `client_id`, which the API ignores,
+  so delivery report callbacks and 12-hour duplicate suppression never took effect
+
+### Removed
+- Removed `advanced_batch_send` and `advanced_batch_send_with_limit`. They posted to a `SmPost`
+  endpoint that does not exist in the Mitake API, and passed recipient numbers and message bodies in
+  the query string, which leaked them into access logs and broke on large batches due to URL length
+  limits. Use `batch_send`, which implements the same `$$` format against `SmBulkSend`
+- Removed the `charset` option from `send_sms` and `batch_send`. It only labelled the payload and
+  never converted it, so `charset: 'BIG5'` sent UTF-8 bytes tagged as Big5, guaranteeing mojibake.
+  Requests are now always UTF8 and non-UTF-8 input is transcoded for you
+- Removed `batch_send_with_limit`. The 500 message cap is an API constraint rather than a tuning
+  knob, and `batch_send` already applies it
+- Dropped the `faraday-multipart` runtime dependency. The multipart middleware was registered after
+  `url_encoded`, so it never handled a request, and the gem never sends file uploads
 
 ## [2.0.0] - 2025-05-26
 ### Changed

data/README.md

@@ -8,13 +8,17 @@ 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 with automatic handling of the 500 message API limit
-- UTF-8 encoding support by default
+- Send single SMS messages (`SmSend`)
+- Send batch SMS messages (`SmBulkSend`) with automatic handling of the 500 message API limit
+- Always sends UTF-8, transcoding input in other encodings
+- Parses every record of a reply, not just the first
 - Configurable API settings
-- Simple and intuitive API
 - Comprehensive error handling
 
+Status queries (`SmQuery`) and cancelling a scheduled send (`SmCancel`) are not
+implemented yet. To learn whether a message reached the handset, have Mitake call
+the `response_url` callback.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -48,9 +52,14 @@ 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.timeout = 30       # Read timeout in seconds, default 30
+  config.open_timeout = 5   # Connection timeout in seconds, default 5
 end
 ```
 
+The default `api_url` targets the HTTP API. If your account is provisioned for the
+B2C variant, set the path to `/b2c/mtk/` instead; the endpoints are otherwise identical.
+
 ### Sending a Single SMS
 
 ```ruby
@@ -68,153 +77,129 @@ end
 response = MitakeSms.send_sms(
   to: '0912345678',
   text: 'Hello with options!',
-  destname: 'John Doe',  # Recipient name or integration key value
-  response_url: 'https://your-callback-url.com/delivery-reports',
-  client_id: 'your-client-reference-id',
-  charset: 'BIG5'  # Override the default UTF-8 encoding if needed
+  destname: 'John Doe',  # Recipient name or integration key value (sent as `destname`)
+  response_url: 'https://your-callback-url.com/delivery-reports', # Sent as `response`
+  client_id: 'your-client-reference-id', # Sent as `clientid`, used by Mitake to de-duplicate
+  dlvtime: '20250526120000',             # Any other documented SmSend field is forwarded as-is
+  vldtime: '20250527120000'
 )
 ```
 
+Requests are always sent as UTF-8. Strings in another encoding are transcoded for
+you, so `text: '中文'.encode('BIG5')` arrives intact.
+
 ### Sending Multiple SMS in Batch
 
+Each message accepts the same fields as a single send. `client_id` is generated for
+you when omitted; Mitake uses it to suppress duplicates within 12 hours.
+
 ```ruby
 messages = [
-  { to: '0912345678', text: 'First message' },
-  { to: '0922333444', text: 'Second message', from: 'YourBrand' },
-  { to: '0933555777', text: 'Third message', response_url: 'https://your-callback-url.com/reports' }
+  {
+    client_id: 'unique-id-20250525-001', # Optional, auto-generated when absent
+    to: '0912345678',                    # Required
+    dlvtime: '20250526120000',           # Optional scheduled delivery (YYYYMMDDhhmmss)
+    vldtime: '20250527120000',           # Optional validity deadline (YYYYMMDDhhmmss)
+    destname: '大寶',                    # Optional recipient name
+    response_url: 'https://callback.url', # Optional per-message callback
+    text: '這是一則測試簡訊'             # Required
+  },
+  { to: '0922333444', text: '這是另一則測試簡訊' }
 ]
 
-# 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)
 
-# You can specify a different character encoding if needed
-response = MitakeSms.batch_send(messages, charset: 'BIG5')
+# Any other documented SmBulkSend field is forwarded as a query parameter
+response = MitakeSms.batch_send(messages, smsPointFlag: '1', objectID: 'nightly-run')
+```
 
-# 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}"
+Batches over 500 messages are split automatically, which is the API's per-request
+limit. Under the limit you get one `Response`; over it you get an array of them.
 
-# 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
+```ruby
+Array(response).each_with_index do |batch, index|
+  if batch.success?
+    puts "Batch #{index + 1} sent. Message IDs: #{batch.message_ids.join(', ')}"
+    puts "Remaining points: #{batch.account_point}"
+  else
+    puts "Batch #{index + 1} failed: #{batch.error}"
   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
+Line breaks in `text` are converted to ASCII code 6, as the API requires, so
+`"First line\nSecond line"` renders as two lines on the handset. Messages longer
+than one SMS are split by Mitake unless your account has long-message permission.
 
-# 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)
+#### Delimiters in batch fields
 
-# You can specify a different character encoding if needed
-responses = MitakeSms.batch_send_with_limit(messages, 300, charset: 'BIG5')
+The batch wire format separates fields with `$$` and rows with a newline. Either
+one inside `client_id`, `to`, `dlvtime`, `vldtime`, `destname` or `response_url`
+would shift every field after it, so `batch_send` raises `ArgumentError` naming
+the offending message and field instead of sending a corrupted row:
 
-# 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
+```ruby
+MitakeSms.batch_send([{ to: '0912345678', destname: 'A$$B', text: 'hi' }])
+# => ArgumentError: messages[0][:destname] must not contain "$$" or a line break, ...
 ```
 
-### Sending Batch SMS with Advanced Format
+`text` is exempt because it is the last field on the row, so a message body may
+contain `$$` freely. Mitake's documentation does not define an escape sequence,
+though, so if a body containing `$$` ever comes back truncated, send it through
+`send_sms` instead.
+
+### Reading a Response
 
-The batch_send method now uses the advanced format by default, which provides more control over each message in the batch, including scheduled delivery, validity period, recipient name, and more:
+A batch reply contains one record per message, each introduced by a `[clientid]` line,
+followed by an `AccountPoint` shared by the whole reply. A single send may omit the
+`[clientid]` header; either shape is parsed the same way. `MitakeSms::Response` keeps
+every record rather than collapsing them:
 
 ```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)
-    destname: '大寶',                    # Optional recipient name
-    response_url: '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
-  }
-]
+response.success?      # true only if there is at least one record and every one was accepted
+response.error?        # the inverse of success?
+response.error         # nil on success, otherwise the documented reason for each failed record
+response.code          # statuscode of the first record
+response.message_id    # msgid of the first record
+response.message_ids   # msgid of every record, for batch sends
+response.client_id     # clientid of the first record
+response.account_point # remaining points, shared by the whole reply
+response.duplicate?    # true when Mitake suppressed a resend of the same clientid
+response.sms_point     # points deducted, only present when smsPointFlag=1 was sent
+response.records       # raw per-message hashes, if you need a field not listed above
+response.raw_response  # the untouched reply body
+```
 
-# 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 batch_send (automatically handles the advanced format)
-response = MitakeSms.batch_send(messages)
+Accepted status codes are `0`, `1`, `2` and `4`. An empty or unparseable body is not a
+success, and `error` reports `'Empty or unparseable response'` for it.
 
-# 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
-```
+Note that `statuscode=0` means 預約傳送中 (queued for scheduled delivery) and counts as a success.
+Failures are the numeric codes `5`–`9` and the letter codes documented in 附錄二, such as `e`
+(帳號、密碼錯誤) or `v` (無效的手機號碼).
 
 ### Error Handling
 
-The gem provides specific error classes for different types of errors:
+HTTP status codes are mapped to specific error classes, while transport failures are
+raised as their original `Faraday::Error` subclass so you can retry on timeouts alone:
 
 ```ruby
 begin
-  response = MitakeSms.send_sms('invalid', 'test')
+  response = MitakeSms.send_sms(to: '0912345678', text: 'test')
 rescue MitakeSms::Client::AuthenticationError => e
   puts "Authentication failed: #{e.message}"
 rescue MitakeSms::Client::InvalidRequestError => e
   puts "Invalid request: #{e.message}"
 rescue MitakeSms::Client::ServerError => e
   puts "Server error: #{e.message}"
-rescue MitakeSms::Client::Error => e
-  puts "An error occurred: #{e.message}"
+rescue Faraday::TimeoutError => e
+  puts "Timed out, safe to retry: #{e.message}"
 end
 ```
 
+Note that `SmBulkSend` takes the username and password as query string parameters,
+which the API mandates and the gem cannot avoid. They are protected in transit by
+HTTPS, but if you log outbound request URLs, filter them at that layer.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -225,6 +210,7 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/7a6163/mitake_sms.
 
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/mitake_sms/client.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'faraday'
-require 'faraday/multipart'
+require 'securerandom'
 require_relative 'configuration'
 require_relative 'response'
 
@@ -12,6 +12,21 @@ module MitakeSms
     class InvalidRequestError < Error; end
     class ServerError < Error; end
 
+    # The Mitake API represents a line break inside smbody as ASCII code 6.
+    LINE_BREAK = 6.chr
+
+    BATCH_LIMIT = 500
+
+    # The API also accepts Big5, but it only labels the payload and never
+    # converts it, so sending anything other than UTF8 just invites mojibake.
+    CHARSET = 'UTF8'
+
+    FIELD_SEPARATOR = '$$'
+
+    # Every SmBulkSend field except smbody, in wire order. A '$$' or a line
+    # break in any of these shifts the remaining fields of the row.
+    STRUCTURAL_FIELDS = %i[client_id to dlvtime vldtime destname response_url].freeze
+
     # Initialize a new MitakeSms::Client
     # @param config [MitakeSms::Configuration] configuration object
     def initialize(config = nil)
@@ -25,220 +40,97 @@ module MitakeSms
     # @param destname [String] recipient name or key value for system integration (optional)
     # @param response_url [String] callback URL for delivery reports (optional)
     # @param client_id [String] client reference ID (optional)
-    # @param charset [String] character encoding, defaults to 'UTF8' (optional)
-    # @param options [Hash] additional options (optional)
+    # @param options [Hash] any other documented SmSend field, such as
+    #   :dlvtime, :vldtime, :objectID or :smsPointFlag
     # @return [MitakeSms::Response] response object
-    def send_sms(to:, text:, destname: nil, response_url: nil, client_id: nil, charset: 'UTF8', **options)
-      require 'uri'
-
-      # Create options hash with only non-nil values
-      param_options = {}
-      param_options[:destname] = destname if destname
-      param_options[:response_url] = response_url if response_url
-      param_options[:client_id] = client_id if client_id
-
-      # 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)
-
-      # Prepare query parameters - only CharsetURL is sent as query parameter
-      query_params = {
-        CharsetURL: charset
-      }
-
-      # Prepare form parameters - all other parameters are sent in the POST body
+    def send_sms(to:, text:, destname: nil, response_url: nil, client_id: nil, **options)
       form_params = {
         username: @config.username,
         password: @config.password,
         dstaddr: to,
-        smbody: processed_text
-      }.merge(param_options).merge(options)
-
-      # Construct the endpoint URL
-      endpoint = "SmSend"
+        smbody: normalize_body(text)
+      }
+      form_params[:destname] = destname if destname
+      form_params[:response] = response_url if response_url
+      form_params[:clientid] = client_id if client_id
 
-      response = @connection.post(endpoint) do |req|
-        req.params = query_params
-        req.body = form_params
+      perform_request('SmSend', params: { CharsetURL: CHARSET }) do |req|
+        req.body = form_params.merge(options)
       end
-
-      handle_response(response)
     end
 
-    # Send multiple SMS in a single request
+    # Send multiple SMS in a single request, splitting at the API's 500 message limit
     # @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)
+    #   Each hash requires :to and :text, and may include :client_id, :dlvtime,
+    #   :vldtime, :destname and :response_url
+    # @param options [Hash] any other documented SmBulkSend field, such as
+    #   :objectID or :smsPointFlag
+    # @raise [ArgumentError] if a field other than :text contains '$$' or a line break
     # @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
+      messages.each_with_index { |msg, index| validate_row!(msg, index) }
 
-      # 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
+      batch_send_with_limit(messages, BATCH_LIMIT, options)
     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 send_batch(batch, charset = 'UTF8', options = {})
-      require 'uri'
-
-      # Format each message according to the advanced format
-      # ClientID $$ dstaddr $$ dlvtime $$ vldtime $$ destname $$ response $$ smbody
-      data = 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[:destname] || ''
-        response_url = msg[:response_url] || ''
+    def batch_send_with_limit(messages, limit, options)
+      return send_batch(messages, options) if messages.size <= limit
 
-        # 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)
-
-        # Format according to API documentation: ClientID $$ dstaddr $$ dlvtime $$ vldtime $$ destname $$ response $$ smbody
-        [client_id, to, dlvtime, vldtime, dest_name, response_url, processed_text].join('$$')
-      end.join("\n")
+      messages.each_slice(limit).map { |batch| send_batch(batch, options) }
+    end
 
-      # Parameters for the request
+    def send_batch(batch, options)
       query_params = {
         username: @config.username,
         password: @config.password,
-        Encoding_PostIn: charset
-      }
+        Encoding_PostIn: CHARSET
+      }.merge(options)
 
-      # According to the API documentation, the data should be in the request body
-      response = @connection.post('SmBulkSend') do |req|
-        req.params = query_params
-        req.body = data
+      perform_request('SmBulkSend', params: query_params) do |req|
+        req.body = batch.map { |msg| format_batch_row(msg) }.join("\n")
         req.headers['Content-Type'] = 'text/plain'
       end
-
-      handle_response(response)
     end
 
-    # 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
-      data = 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] || ''
+    # ClientID $$ dstaddr $$ dlvtime $$ vldtime $$ destname $$ response $$ smbody
+    def format_batch_row(msg)
+      client_id = msg[:client_id]
+      client_id = generate_unique_client_id if client_id.to_s.empty?
+
+      [
+        client_id,
+        msg[:to],
+        msg[:dlvtime],
+        msg[:vldtime],
+        msg[:destname],
+        msg[:response_url],
+        normalize_body(msg[:text])
+      ].join(FIELD_SEPARATOR)
+    end
 
-        # 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)
+    def validate_row!(msg, index)
+      STRUCTURAL_FIELDS.each do |field|
+        value = msg[field].to_s
+        next unless value.include?(FIELD_SEPARATOR) || value.match?(/[\r\n]/)
 
-        [client_id, to, dlvtime, vldtime, dest_name, response_url, processed_text].join('$$')
-      end.join("\n")
+        raise ArgumentError,
+              "messages[#{index}][:#{field}] must not contain #{FIELD_SEPARATOR.inspect} or a line break, " \
+              'because both are SmBulkSend delimiters'
+      end
+    end
 
-      # All parameters should be sent as query string parameters
-      query_params = {
-        username: @config.username,
-        password: @config.password,
-        data: data,
-        Encoding_PostIn: charset
-      }
+    # Mitake expects UTF8 bytes with ASCII code 6 standing in for a line break.
+    # Transcoding also keeps a batch of mixed-encoding strings from failing to join.
+    def normalize_body(text)
+      text.to_s.encode(Encoding::UTF_8).gsub(/\r\n?|\n/, LINE_BREAK)
+    end
 
-      # Use empty body with all parameters in query string
-      response = @connection.post('SmPost') do |req|
-        req.params = query_params
-        req.body = {}
+    def perform_request(endpoint, params:)
+      response = @connection.post(endpoint) do |req|
+        req.params = params
+        yield req
       end
 
       handle_response(response)
@@ -247,7 +139,6 @@ module MitakeSms
     def build_connection
       Faraday.new(url: @config.api_url) do |conn|
         conn.request :url_encoded
-        conn.request :multipart
         conn.adapter Faraday.default_adapter
         conn.options.timeout = @config.timeout
         conn.options.open_timeout = @config.open_timeout
@@ -269,15 +160,10 @@ module MitakeSms
       end
     end
 
-    # Generate a unique client ID for SMS messages
-    # @return [String] a unique ID combining timestamp and random values
+    # Mitake uses the client ID to suppress duplicate sends within 12 hours,
+    # so it has to be unique per message rather than merely random.
     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}"
+      "#{Time.now.strftime('%Y%m%d%H%M%S%L')}-#{SecureRandom.uuid.delete('-')[0, 8]}"
     end
   end
 end

data/lib/mitake_sms/response.rb

@@ -2,37 +2,128 @@
 
 module MitakeSms
   class Response
-    attr_reader :raw_response, :code, :message_id, :account_point, :error
+    # 附錄一 / 附錄二：statuscode 對應說明
+    STATUS_MESSAGES = {
+      '0' => '預約傳送中',
+      '1' => '已送達業者',
+      '2' => '已送達業者',
+      '4' => '已送達手機',
+      '5' => '內容有錯誤',
+      '6' => '門號有錯誤',
+      '7' => '簡訊已停用',
+      '8' => '逾時無送達',
+      '9' => '預約已取消',
+      '*' => '系統發生錯誤，請聯絡三竹資訊窗口人員',
+      'a' => '簡訊發送功能暫時停止服務，請稍候再試',
+      'b' => '簡訊發送功能暫時停止服務，請稍候再試',
+      'c' => '請輸入帳號',
+      'd' => '請輸入密碼',
+      'e' => '帳號、密碼錯誤',
+      'f' => '帳號已過期',
+      'h' => '帳號已被停用',
+      'k' => '無效的連線位址',
+      'l' => '帳號已達到同時連線數上限',
+      'm' => '必須變更密碼，在變更密碼前，無法使用簡訊發送服務',
+      'n' => '密碼已逾期，在變更密碼前，將無法使用簡訊發送服務',
+      'p' => '沒有權限使用外部Http程式',
+      'r' => '系統暫停服務，請稍後再試',
+      's' => '帳務處理失敗，無法發送簡訊',
+      't' => '簡訊已過期',
+      'u' => '簡訊內容不得為空白',
+      'v' => '無效的手機號碼',
+      'w' => '查詢筆數超過上限',
+      'x' => '發送檔案過大，無法發送簡訊',
+      'y' => '參數錯誤',
+      'z' => '查無資料'
+    }.freeze
+
+    # 簡訊已被三竹收下或已送達。其餘 statuscode 皆視為失敗。
+    ACCEPTED_STATUS_CODES = %w[0 1 2 4].freeze
+
+    attr_reader :raw_response, :records, :account_point
 
     def initialize(raw_response)
       @raw_response = raw_response
-      parse_response(raw_response)
+      @records = []
+      @account_point = nil
+      parse(raw_response)
+    end
+
+    def code
+      first_record['statuscode']
+    end
+
+    def message_id
+      first_record['msgid']
+    end
+
+    def client_id
+      first_record['clientid']
+    end
+
+    def sms_point
+      first_record['smsPoint']
+    end
+
+    def duplicate?
+      first_record['Duplicate'] == 'Y'
+    end
+
+    def message_ids
+      @records.map { |record| record['msgid'] }.compact
     end
 
     def success?
-      @code == '1'
+      return false if @records.empty?
+
+      @records.all? { |record| accepted?(record) }
     end
 
     def error?
       !success?
     end
 
+    def error
+      return nil if success?
+
+      failures = @records.reject { |record| accepted?(record) }
+      return 'Empty or unparseable response' if failures.empty?
+
+      failures.map { |record| describe(record) }.join('; ')
+    end
+
     private
 
-    def parse_response(response)
+    def first_record
+      @records.first || {}
+    end
+
+    def accepted?(record)
+      ACCEPTED_STATUS_CODES.include?(record['statuscode'])
+    end
+
+    def describe(record)
+      status = record['statuscode']
+      description = "#{status || '?'} #{STATUS_MESSAGES.fetch(status, '未知的狀態')}"
+      record['msgid'] ? "#{record['msgid']}: #{description}" : description
+    end
+
+    def parse(response)
       return unless response.is_a?(String)
-      
-      # Split by newline and create a hash from key=value pairs
-      @parsed_response = {}
-      response.each_line do |line|
-        key, value = line.strip.split('=', 2)
-        @parsed_response[key] = value if key && value
+
+      response.each_line do |raw_line|
+        case raw_line.strip
+        # 每筆回覆以 [clientid] 開頭，例如 [1] 或 [my-guid]
+        when /\A\[(.*)\]\z/
+          @records << { 'clientid' => Regexp.last_match(1) }
+        # AccountPoint 是整批回覆共用的餘額，不屬於任何單筆簡訊
+        when /\AAccountPoint=(.*)\z/
+          @account_point = Regexp.last_match(1)
+        when /\A([^=]+)=(.*)\z/
+          @records << {} if @records.empty?
+          @records.last[Regexp.last_match(1)] = Regexp.last_match(2)
+        end
       end
-      
-      @code = @parsed_response['statuscode']
-      @message_id = @parsed_response['msgid']
-      @account_point = @parsed_response['AccountPoint']
-      @error = @parsed_response['Error']
     end
   end
 end

data/lib/mitake_sms/version.rb

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

data/lib/mitake_sms.rb

@@ -41,18 +41,15 @@ module MitakeSms
     # @param destname [String] recipient name or key value for system integration (optional)
     # @param response_url [String] callback URL for delivery reports (optional)
     # @param client_id [String] client reference ID (optional)
-    # @param charset [String] character encoding, defaults to 'UTF8' (optional)
-    # @param options [Hash] additional options (optional)
+    # @param options [Hash] any other documented SmSend field
     # @return [MitakeSms::Response] response object
-    def send_sms(to:, text:, destname: nil, response_url: nil, client_id: nil, charset: 'UTF8', **options)
-      # Forward all parameters to the client method using named parameters
+    def send_sms(to:, text:, destname: nil, response_url: nil, client_id: nil, **options)
       client.send_sms(
         to: to,
         text: text,
         destname: destname,
         response_url: response_url,
         client_id: client_id,
-        charset: charset,
         **options
       )
     end
@@ -61,45 +58,13 @@ module MitakeSms
     # 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
-    # @param options [Hash] additional options
-    # @option options [String] :charset character encoding, defaults to 'UTF8'
-
+    #   Each hash requires :to and :text, and may include :client_id, :dlvtime,
+    #   :vldtime, :destname and :response_url
+    # @param options [Hash] any other documented SmBulkSend field
+    # @raise [ArgumentError] if a field other than :text contains '$$' or a line break
     # @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)
+      client.batch_send(messages, 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
-    
-
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mitake_sms
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Zac
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 2.14.3
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -25,37 +25,17 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 2.14.3
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: faraday-multipart
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: dry-configurable
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.13.0
+        version: 1.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -65,7 +45,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.13.0
+        version: 1.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -131,28 +111,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: 1.0.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: 1.0.3
 - !ruby/object:Gem::Dependency
   name: simplecov-cobertura
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '4.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '4.0'
 description: A simple and efficient Ruby client for sending SMS messages through Mitake
   SMS API
 email:
@@ -184,14 +164,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A Ruby client for Mitake SMS API
 test_files: []