kotsms2 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5296875c0b1b8a755e8552f54a58660f26349f70
-  data.tar.gz: 22e473ec7a42c8b02a2f2c84ea096a0e24e3dc7e
+  metadata.gz: 683a33d67cc7f8b8c5f25c39a2b24a9d9f20b000
+  data.tar.gz: ca2fad420aaff2d8851673ba906d3748561c72a7
 SHA512:
-  metadata.gz: 8e6301990768aa5a7ea71ea42a7bf039bbaf8a75cb7ceefbc827ecdfbe3f413e5fa6eb8eb880f1e96097f131f5d405bfec562579670975452e90f03f964a386a
-  data.tar.gz: f7e1889421d00d4bea51523c8fee0969d18434c29feca67faa556d55128c15b587e9737a872d514b722ff1743a11a9a5832acbedc0669d92fa3b104ba075722d
+  metadata.gz: bab1abc6f97a79aa52631491e826086fa5d654985bb7405554d4b4e61562812645b88b05d856699f08d340136e9b864ba9631eb7b9a4998f4d4642daa2fdf76b
+  data.tar.gz: 67ce2000bf30f8aa860aee138d061e779593dd26ec5e92368f1f3f4ee23a8e1ad7854fe0c638870b3f3651906dc836dc20d1cb9e4a7e04da2a37b12cb85afbaf

data/README.md

@@ -22,7 +22,7 @@ Ruby 2 以上的版本，也可在 Ruby On Rails 專案引入
 請在您的 Ruby 或 Rails 專案裡的 Gemfile 加入以下指令
 
 ```ruby
-gem 'kotsms2', '~> 1.0.0'
+gem 'kotsms2', '~> 1.1.0'
 ```
 
 然後執行 bundle install 更新套件組
@@ -43,9 +43,18 @@ gem 'kotsms2', '~> 1.0.0'
 ```ruby
 require 'kotsms2'
 
-# Kotsms2 是走 https 的方式進行系統操作
+# 程式將會以 SSL 的方式，走 https 連線到簡訊商的系統
+sms_client = Kotsms2::Client.new(username: '會員帳號', password: '會員密碼')
+```
+
+也可以加入 agent ( user-agent ) 跟 timeout ( 逾時時間/秒 ) 參數 至 client 物件
+
+```ruby
 sms_client = Kotsms2::Client.new(
-  username: '會員帳號', password: '會員密碼', agent: "Mozilla/5.0 (可自訂 user-agent)"
+  username: '會員帳號',
+  password: '會員密碼',
+  agent: "Mozilla/5.0 ( Hello World )",
+  timeout: 10
 )
 ```
 
@@ -131,7 +140,7 @@ error code 的部分，請以 簡訊王 API 文件的定義為主，本套件不
 
 ----
 
-### 查詢簡訊餘額
+### 查詢目前帳號所持有的簡訊餘額
 
 若你需要查詢您會員帳號的簡訊餘額，可以用以下指令處理
 
@@ -139,7 +148,7 @@ error code 的部分，請以 簡訊王 API 文件的定義為主，本套件不
 sms_client.get_balance
 ```
 
-### 查詢簡訊餘額 的 回傳結果
+### 查詢目前帳號所持有的簡訊餘額 的 回傳結果
 
 #### 得到簡訊餘額
 
@@ -162,6 +171,75 @@ message_quota 則是簡訊餘額，代表你還剩幾封可以用，若為 0 就
 {:access_success=>false, :message_quota=>0, :error=>"KOTSMS:-2"}
 ```
 
+### 查詢特定的簡訊發送狀態
+
+若你需要查詢特定的簡訊發送狀態，您可以指定 message id 向簡訊商查詢該封簡訊最後是否已發送成功
+
+```ruby
+sms_client.get_message_status message_id: '在 send_message 得到的 message_id'
+```
+
+### 查詢特定的簡訊發送狀態 的 回傳結果
+
+#### 得到發送狀況
+
+當你執行完成後，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' # 簡訊商編碼錯誤 
+'status_undefined'            # 核心 API 無法得知狀況 
+```
+
+#### 發生錯誤時
+
+若 access_success 為 false 則表示過程有出現錯誤，同時 is_delivered 會為 false，message_status 會是 'status_undefined'
+
+```ruby
+{:access_success=>false, :is_delivered=>false, :message_status=>nil, :error=>"KOTSMS:MEMBERERROR"}
+{:access_success=>false, :is_delivered=>false, :message_status=>nil, :error=>"KOTSMS:NOSMS"}
+```
+
+----
+
+例外狀況的處理
+--------
+
+在某些情況下，程式會擲出一些例外給 ruby 去處理，你可以先用 Kotsms2 自帶的 Error 來先做 rescue
+
+```ruby
+
+begin
+  sms_client.account_is_available
+rescue Kotsms2::ClientError
+  'Client 物件有內部錯誤'
+rescue Kotsms2::ServerError => error
+  "伺服器端有一些無法處理的狀況 #{error.message}"
+rescue Kotsms2::ClientTimeoutError
+  "發生 Timeout 囉"
+rescue Kotsms2::Error => error
+  "發生非預期的錯誤 #{error.message}"
+end
+
+```
 
 LICENSE
 --------

data/lib/kotsms2/exception.rb

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

data/lib/kotsms2/formatter.rb

@@ -25,6 +25,45 @@ module Kotsms2
       asia_taipei_time
     end
 
+    def message_status_sanitize(original_text)
+      status_table = {
+        'SUCCESSED' => 'delivered',
+        'DELIVRD' => 'delivered',
+        'EXPIRED' => 'expired',
+        'DELETED' => 'deleted',
+        'UNDELIV' => 'undelivered',
+        'ACCEPTD' => 'transmitting',
+        'UNKNOWN' => 'unknown',
+        'REJECTD' => 'rejected',
+        'SYNTAXE' => 'incorrect_sms_system_syntax'
+      }
+
+      new_text = status_table[original_text]
+      new_text.nil? ? 'status_undefined' : new_text
+    end
+
+    def format_message_status(original_info)
+      new_info = {
+        access_success: false,
+        is_delivered: false,
+        message_status: nil,
+        error: nil
+      }
+
+      status_text = match_string(/^statusstr=(?<status>\w+)$/, original_info)
+
+      new_info[:access_success] = !status_text.nil? && status_text != 'MEMBERERROR' && status_text != 'NOSMS'
+
+      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] = status_text.nil? ? "KOTSMS:CODE_NOT_FOUND" : "KOTSMS:#{status_text}".upcase
+      end
+
+      new_info
+    end
+
     def format_send_message_info(original_info)
       new_info = {
         access_success: false,

data/lib/kotsms2/network.rb

@@ -21,6 +21,8 @@ module Kotsms2
         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 Kotsms2
 
     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/kotsms2/version.rb

@@ -1,3 +1,3 @@
 module Kotsms2
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

data/lib/kotsms2.rb

@@ -13,6 +13,7 @@ module Kotsms2
       @api_host   = options.fetch(:host) { 'api.kotsms.com.tw' }
       @username   = options.fetch(:username) { ENV.fetch('KOTSMS_USERNAME') }
       @password   = options.fetch(:password) { ENV.fetch('KOTSMS_PASSWORD') }
+      @timeout    = options.fetch(:timeout) { 10 }
     end
 
     def account_is_available
@@ -41,5 +42,14 @@ module Kotsms2
 
       format_balance_info(response)
     end
+
+    def get_message_status(options={})
+      options[:message_id] ||= nil
+
+      response = get(@api_host, '/msgstatus.php', kmsgid: options[:message_id])
+
+      format_message_status(response)
+    end
+
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kotsms2
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Guanting Chen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-04 00:00:00.000000000 Z
+date: 2016-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.4
 signing_key: 
 specification_version: 4
 summary: 2016 新版 簡訊王 KotSMS API ( 純 Ruby / Rails 專案適用 )