twsms2 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 548eb03c93dd04ba44a85593a17e14a6d77c85da
-  data.tar.gz: 0eb4402e4e51a566c8476b88d84a43a9c5b40993
+SHA256:
+  metadata.gz: ed7351473d76e0ad230808dc4ac38abb5609887a79efef9b40a3d6a6e4587019
+  data.tar.gz: 36a0052de311fde0274c540b08b6a91cdb56127b80e02112dc9245387350025d
 SHA512:
-  metadata.gz: 38bd3975a7334dddb430b45269e3f6204ebfd4b6407fe669486b13927c467585342f125be252f41886dae0f06e036d0745d7acfedc03ca03d6a323b682583bd6
-  data.tar.gz: f9b5043d50a38004a9d8f8948202dc7054f0b0e8c12a8477d45fae48c94e954c09b1a2660c356a0e16250cac265db0da19939fd829be5327b5afcf9d12befb6c
+  metadata.gz: b595982bb5db4ba708c67a59b893901ad831d35d7310fdd2b7fe44b5563128deffb68294592f79e5a745a58dfcc97df5307830e408b83b9f0dfc533afee5bedf
+  data.tar.gz: 6374876b1a82e0804ecb16850ffcbea004b7a25f93dac4614714e3cda311f89112129a5a060a3ba15388d86b32cfeb3b382fa7806066ab3f58aa90f996041901

data/README.md

@@ -1,7 +1,8 @@
-Twsms2 ( 2016 新版 台灣簡訊 TwSMS API Ruby 版套件 )
+Twsms2 ( 台灣簡訊 TwSMS API Ruby 版套件 )
 =================================================
 
-[![Gem Version](https://badge.fury.io/rb/twsms2.svg)](https://badge.fury.io/rb/twsms2) [![Build Status](https://travis-ci.org/guanting112/twsms2.svg?branch=master)](https://travis-ci.org/guanting112/twsms2)
+[![Gem Version](https://badge.fury.io/rb/twsms2.svg)](https://badge.fury.io/rb/twsms2)
+[![Code Climate](https://codeclimate.com/github/guanting112/twsms2/badges/gpa.svg)](https://codeclimate.com/github/guanting112/twsms2)
 
 ![twsms](http://i.imgur.com/KVuaBIm.png)
 
@@ -20,7 +21,7 @@ Ruby 2 以上的版本，也可在 Ruby On Rails 專案引入
 請在您的 Ruby 或 Rails 專案裡的 Gemfile 加入以下指令
 
 ```ruby
-gem 'twsms2', '~> 1.1.0'
+gem 'twsms2', '=> 1.3.0'
 ```
 
 然後執行 bundle install 更新套件組
@@ -36,13 +37,24 @@ gem 'twsms2', '~> 1.1.0'
 
 本 API 套件，提供幾組以下方法來方便您開發簡訊相關服務
 
-但要使用前，需要先[註冊台灣簡訊的會員][twsms_signup]，否則您的程式無法存取台灣簡訊的 API 管道
+基本執行範例如下，但要使用前，需要先[註冊台灣簡訊的會員][twsms_signup]，否則無法存取相關服務
 
 ```ruby
 require 'twsms2'
 
-# Twsms2 是走 https 的方式進行系統操作
-sms_client = Twsms2::Client.new(username: '會員帳號', password: '會員密碼', agent: "Mozilla/5.0 (可自訂 user-agent)")
+# 程式將會以 SSL 的方式，走 https 連線到簡訊商的系統
+sms_client = Twsms2::Client.new(username: '會員帳號', password: '會員密碼')
+```
+
+也可以加入 agent ( user-agent ) 跟 timeout ( 逾時時間/秒 ) 參數 至 client 物件
+
+```ruby
+sms_client = Twsms2::Client.new(
+  username: '會員帳號',
+  password: '會員密碼',
+  agent: "Mozilla/5.0 ( Hello World )",
+  timeout: 10
+)
 ```
 
 使用範例
@@ -56,8 +68,6 @@ sms_client = Twsms2::Client.new(username: '會員帳號', password: '會員密
 sms_client.account_is_available
 ```
 
-----
-
 ### 發送簡訊
 
 #### 一般使用
@@ -86,7 +96,7 @@ sms_client.send_message to: '手機號碼', content: "預約簡訊測試: #{Time
 
 #### 強制直接顯示簡訊內容
 
-可以加入 popup 參數，讓簡訊在收訊人的手機裝置直接顯示在上面 ( 可能不會被手機儲存 )
+可以加入 popup 參數，讓簡訊在收訊人的手機上直接顯示，但有可能不會被手機儲存
 
 ```ruby
 sms_client.send_message to: '手機號碼', content: "簡訊內容..", popup: true
@@ -94,9 +104,9 @@ sms_client.send_message to: '手機號碼', content: "簡訊內容..", popup: tr
 
 #### 關閉長簡訊支援
 
-一般發送簡訊時，預設為長簡訊發送
+一般發送簡訊時，程式預設支援長簡訊發送
 
-因此，若超 SMS 短信字元長度，將會以第二封起開始計算
+因此，若超 SMS 簡訊字元長度，將會以第二封起開始計算
 
 加入 long 參數，若指定為 false 則不會使用長簡訊格式
 
@@ -104,6 +114,8 @@ sms_client.send_message to: '手機號碼', content: "簡訊內容..", popup: tr
 sms_client.send_message to: '手機號碼', content: "簡訊內容..", long: false
 ```
 
+詳細規則請以 台灣簡訊 公告為主
+
 ### 發送簡訊 的 回傳結果
 
 #### 發送成功
@@ -132,7 +144,7 @@ error code 的部分，請以 台灣簡訊 API 文件的定義為主，本套件
 
 ----
 
-### 查詢簡訊餘額
+### 查詢目前帳號所持有的簡訊餘額
 
 若你需要查詢您會員帳號的簡訊餘額，可以用以下指令處理
 
@@ -140,7 +152,7 @@ error code 的部分，請以 台灣簡訊 API 文件的定義為主，本套件
 sms_client.get_balance
 ```
 
-### 查詢簡訊餘額 的 回傳結果
+### 查詢目前帳號所持有的簡訊餘額 的 回傳結果
 
 #### 得到簡訊餘額
 
@@ -155,7 +167,7 @@ message_quota 則是簡訊餘額，代表你還剩幾封可以用，若為 0 就
 {:access_success=>true, :message_quota=>77, :error=>nil}
 ```
 
-#### 發生錯誤
+#### 發生錯誤時
 
 若 access_success 為 false 則表示過程有出現錯誤，同時 message_quota 會為 0
 
@@ -163,6 +175,78 @@ message_quota 則是簡訊餘額，代表你還剩幾封可以用，若為 0 就
 {:access_success=>false, :message_quota=>0, :error=>"TWSMS:00010"}
 ```
 
+### 查詢特定的簡訊發送狀態
+
+若你需要查詢特定的簡訊發送狀態，您可以指定 手機號碼 跟 message id 向簡訊商查詢該封簡訊最後是否已發送成功
+
+```ruby
+sms_client.get_message_status(message_id: '在 send_message 得到的 message_id', phone_number: '手機號碼')
+```
+
+### 查詢特定的簡訊發送狀態 的 回傳結果
+
+#### 得到發送狀況
+
+當你執行完成後，get_message_status 方法會回傳一組 hash 型態的結果
+
+只要 access_success 的值為 true 就一定代表系統有成功取得資料
+
+is_delivered 代表是否已寄到用戶手機，true 為是、false 為有發生 delivered 以外的狀況
+
+message_status 代表訊息狀態，可以知道是否已抵達 或是 發生通信上的錯誤 等等的相關資訊
+
+```ruby
+{:access_success=>true, :is_delivered=>true, :message_status=>"delivered", :error=>nil}
+```
+
+#### get_message_status 裡的 message_status 涵義
+
+```ruby
+'delivered'                   # 簡訊已抵達 
+'expired'                     # 簡訊寄送超過有效時間 
+'deleted'                     # 已被刪除 
+'undelivered'                 # 無法送達 
+'transmitting'                # 傳輸中，正在接收 
+'unknown'                     # 未知錯誤，可能無效 
+'rejected'                    # 被拒絕 
+'incorrect_sms_system_syntax' # 簡訊商編碼錯誤 
+'incorrect_phone_number'      # 不正確的電話號碼 
+'incorrect_content'           # 不正確的內容 
+'sms_system_other_error'      # 簡訊商系統錯誤 
+'illegal_content'             # 不合法的簡訊內容 
+'status_undefined'            # 核心 API 無法得知狀況 
+```
+
+#### 發生錯誤時
+
+若 access_success 為 false 則表示過程有出現錯誤，同時 is_delivered 會為 false，message_status 也會是 nil
+
+```ruby
+{:access_success=>false, :is_delivered=>false, :message_status=>nil, :error=>"TWSMS:00010"})
+```
+
+----
+
+例外狀況的處理
+--------
+
+在某些情況下，程式會擲出一些例外給 ruby 去處理，你可以先用 Twsms2 自帶的 Error 來先做 rescue
+
+```ruby
+
+begin
+  sms_client.account_is_available
+rescue Twsms2::ClientError
+  'Client 物件有內部錯誤'
+rescue Twsms2::ServerError => error
+  "伺服器端有一些無法處理的狀況 #{error.message}"
+rescue Twsms2::ClientTimeoutError
+  "發生 Timeout 囉"
+rescue Twsms2::Error => error
+  "發生非預期的錯誤 #{error.message}"
+end
+
+```
 
 LICENSE
 --------
@@ -176,3 +260,4 @@ LICENSE
 
 [twsms_signup]: https://www.twsms.com/accjoin.php
 [twsms_homepage]: https://www.twsms.com/
+

data/Rakefile

@@ -1,5 +1,5 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 task :default => :spec
 

data/bin/console

@@ -1,14 +1,14 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "twsms2"
+require 'bundler/setup'
+require 'twsms2'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
+# require 'pry'
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start

data/lib/twsms2/exception.rb

@@ -2,4 +2,5 @@ module Twsms2
   class Error < StandardError; end
   class ClientError < Error; end
   class ServerError < Error; end
+  class ClientTimeoutError < Error; end
 end

data/lib/twsms2/formatter.rb

@@ -1,9 +1,7 @@
+require 'json'
+
 module Twsms2
   module Formatter
-    def match_string(rule, string)
-      match_data = rule.match(string)
-      match_data.nil? ? nil : match_data[1]
-    end
 
     def format_time_string(time)
       return nil if time.nil?
@@ -17,6 +15,53 @@ module Twsms2
       asia_taipei_time
     end
 
+    def message_status_sanitize(original_text)
+      new_text = case original_text
+                 when 'DELIVRD'  then 'delivered'
+                 when 'EXPIRED'  then 'expired'
+                 when 'DELETED'  then 'deleted'
+                 when 'UNDELIV'  then 'undelivered'
+                 when 'ACCEPTD'  then 'transmitting'
+                 when 'UNKNOWN'  then 'unknown'
+                 when 'REJECTD'  then 'rejected'
+                 when 'SYNTAXE'  then 'incorrect_sms_system_syntax'
+                 when 'MOBERROR' then 'incorrect_phone_number'
+                 when 'MSGERROR' then 'incorrect_content'
+                 when 'OTHERROR' then 'sms_system_other_error'
+                 when 'REJERROR' then 'illegal_content'
+                 when 'REJMOBIL' then 'device_rejected'
+                 else 'status_undefined'
+                 end
+
+      new_text
+    end
+
+    def format_message_status(original_info)
+      new_info = {
+        access_success: false,
+        is_delivered: false,
+        message_status: nil,
+        error: nil
+      }
+
+      json_info = JSON.parse(original_info)
+
+      code_text  = json_info['code']
+      status_text = json_info['statustext']
+
+      new_info[:access_success] =
+        !code_text.nil? && !status_text.nil? && code_text == '00000'
+
+      if new_info[:access_success]
+        new_info[:message_status] = message_status_sanitize(status_text)
+        new_info[:is_delivered]   = new_info[:message_status] == 'delivered'
+      else
+        new_info[:error] = code_text.nil? ? "TWSMS:CODE_NOT_FOUND" : "TWSMS:#{code_text}".upcase
+      end
+
+      new_info
+    end
+
     def format_send_message_info(original_info)
       new_info = {
         access_success: false,
@@ -24,17 +69,18 @@ module Twsms2
         error: nil
       }
 
-      code_text  = match_string(/<code>(?<code>\w+)<\/code>/, original_info)
-      message_id_text = match_string(/<msgid>(?<message_id>\d+)<\/msgid>/, original_info)
+      json_info = JSON.parse(original_info)
+
+      code_text  = json_info['code']
+      message_id_text = json_info['msgid']
 
-      new_info[:access_success] = !code_text.nil? && !message_id_text.nil? && code_text == '00000'
+      new_info[:access_success] =
+        !code_text.nil? && !message_id_text.nil? && code_text == '00000'
 
       if new_info[:access_success]
         new_info[:message_id] = message_id_text
       else
-        new_info[:error] = "TWSMS:CODE_NOT_FOUND"
-        new_info[:error] = "TWSMS:#{code_text}" unless code_text.nil?
-        new_info[:error].upcase!
+        new_info[:error] = code_text.nil? ? "TWSMS:CODE_NOT_FOUND" : "TWSMS:#{code_text}".upcase
       end
 
       new_info
@@ -47,17 +93,17 @@ module Twsms2
         error: nil
       }
 
-      code_text  = match_string(/<code>(?<code>\w+)<\/code>/, original_info)
-      point_text = match_string(/<point>(?<point>\d+)<\/point>/, original_info)
+      json_info = JSON.parse(original_info)
+      code_text = json_info['code']
+      point_text = json_info['point']
 
-      new_info[:access_success] = !code_text.nil? && !point_text.nil? && code_text == '00000'
+      new_info[:access_success] =
+        !code_text.nil? && !point_text.nil? && code_text == '00000'
 
       if new_info[:access_success]
         new_info[:message_quota] = point_text.to_i
       else
-        new_info[:error] = "TWSMS:CODE_NOT_FOUND"
-        new_info[:error] = "TWSMS:#{code_text}" unless code_text.nil?
-        new_info[:error].upcase!
+        new_info[:error] = code_text.nil? ? "TWSMS:CODE_NOT_FOUND" : "TWSMS:#{code_text}".upcase
       end
 
       new_info

data/lib/twsms2/network.rb

@@ -21,6 +21,8 @@ module Twsms2
         raise ClientError, "#{http_response.code} response from #{host}"
       when Net::HTTPServerError
         raise ServerError, "#{http_response.code} response from #{host}"
+      when 'READ_TIMEOUT'
+        raise ClientTimeoutError, "Read Timeout from #{host}"
       else
         raise Error, "#{http_response.code} response from #{host}"
       end
@@ -28,8 +30,11 @@ module Twsms2
 
     def request(uri, message)
       http = Net::HTTP.new(uri.host, Net::HTTP.https_default_port)
+      http.read_timeout = @timeout
       http.use_ssl = true
       http.request(message)
+    rescue Net::ReadTimeout
+      'READ_TIMEOUT'
     end
 
     def query_string(params)

data/lib/twsms2/version.rb

@@ -1,3 +1,3 @@
 module Twsms2
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/twsms2.rb

@@ -13,12 +13,12 @@ module Twsms2
       @api_host   = options.fetch(:host) { 'api.twsms.com' }
       @username   = options.fetch(:username) { ENV.fetch('TWSMS_USERNAME') }
       @password   = options.fetch(:password) { ENV.fetch('TWSMS_PASSWORD') }
+      @timeout    = options.fetch(:timeout) { 10 }
     end
 
     def account_is_available
       balance_info = get_balance
-
-      ok = balance_info[:message_quota] > 0 && balance_info[:access_success]
+      balance_info[:message_quota] > 0 && balance_info[:access_success]
     end
 
     def send_message(options={})
@@ -28,15 +28,25 @@ module Twsms2
       options[:long]    = options[:long] || options[:long].nil? ? :Y : :N
       options[:popup]   = options[:popup] ? :Y : :N
 
-      response = get(@api_host, '/smsSend.php', popup: options[:popup], mo: :N, longsms: options[:long], mobile: options[:to], message: options[:content], drurl: '', sendtime: options[:at])
+      response = get(@api_host, '/json/sms_send.php', popup: options[:popup], mo: :N, longsms: options[:long], mobile: options[:to], message: options[:content], drurl: '', sendtime: options[:at])
 
       format_send_message_info(response)
     end
 
     def get_balance
-      response = get(@api_host, '/smsQuery.php', deltime: :N, checkpoint: :Y, mobile: '', msgid: '')
+      response = get(@api_host, '/json/sms_query.php', deltime: :N, checkpoint: :Y, mobile: '', msgid: '')
 
       format_balance_info(response)
     end
+
+    def get_message_status(options={})
+      options[:message_id] ||= nil
+      options[:phone_number] ||= nil
+
+      response = get(@api_host, '/json/sms_query.php', mobile: options[:phone_number], msgid: options[:message_id])
+
+      format_message_status(response)
+    end
+
   end
 end

data/twsms2.gemspec

@@ -10,10 +10,10 @@ Gem::Specification.new do |spec|
   spec.email         = ["cgt886@gmail.com"]
   spec.license       = "MIT"
   spec.platform      = Gem::Platform::RUBY
-  spec.summary       = %q{2016 新版 台灣簡訊 TwSMS API ( 純 Ruby / Rails 專案適用 )}
-  spec.description   = %q{2016 新版 台灣簡訊 TwSMS API ( 純 Ruby / Rails 專案適用 )}
+  spec.summary       = %q{2021 新版 台灣簡訊 TwSMS API ( 純 Ruby / Rails 專案適用 )}
+  spec.description   = %q{2021 新版 台灣簡訊 TwSMS API ( 純 Ruby / Rails 專案適用 )}
   spec.homepage      = "https://github.com/guanting112/twsms2"
-  spec.required_ruby_version = '~> 2'
+  spec.required_ruby_version = '>= 2'
 
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.
@@ -28,8 +28,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "rake", "~> 10.0"
-  # spec.add_development_dependency 'webmock', '~> 1.18'
+  spec.add_development_dependency "bundler", "<3.0", ">=1.7"
+  spec.add_development_dependency "rake", ">= 12.3.3"
   spec.add_development_dependency 'minitest', '~> 5.0'
 end

metadata

@@ -1,43 +1,49 @@
 --- !ruby/object:Gem::Specification
 name: twsms2
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Guanting Chen
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2016-09-03 00:00:00.000000000 Z
+date: 2021-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 12.3.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 12.3.3
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -52,7 +58,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: 2016 新版 台灣簡訊 TwSMS API ( 純 Ruby / Rails 專案適用 )
+description: 2021 新版 台灣簡訊 TwSMS API ( 純 Ruby / Rails 專案適用 )
 email:
 - cgt886@gmail.com
 executables: []
@@ -60,7 +66,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
-- ".travis.yml"
 - Gemfile
 - LICENSE
 - README.md
@@ -78,13 +83,13 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
       version: '2'
 required_rubygems_version: !ruby/object:Gem::Requirement
@@ -93,9 +98,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.4
-signing_key: 
+rubygems_version: 3.2.15
+signing_key:
 specification_version: 4
-summary: 2016 新版 台灣簡訊 TwSMS API ( 純 Ruby / Rails 專案適用 )
+summary: 2021 新版 台灣簡訊 TwSMS API ( 純 Ruby / Rails 專案適用 )
 test_files: []

data/.travis.yml

@@ -1,6 +0,0 @@
-language: ruby
-rvm:
-  - 2.0
-  - 2.1
-  - 2.2
-  - 2.3.1