twsms2 0.9.0 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c364ff8657babc7b1f0a6ffaf9a47fd1e90e427a
-  data.tar.gz: 93cde1c61bf791e3076aadf52c26cb1e9f3db347
+  metadata.gz: e5a9a3ef4feed05f9a86b7bd560496befd38d3ae
+  data.tar.gz: 3e7a3ea26b4277b4de7a3cecb506f61f587a1449
 SHA512:
-  metadata.gz: c9ed81c3fea24c3fa7c267c906fb5240f245fa98a9663e602e08808d9f35d9fd7a245012bdeda5ef872a217154f01f62b30388edc9ca9ff5314a04cefca65bc1
-  data.tar.gz: bc2d634dc09216746267526735643629d13b9b3c32d026575c7d806b8de4e2019fa20132d1fccc6cb66e19b30a03826a64d013c60436ab3976a68a037d337fab
+  metadata.gz: 27af245bfc614037b1f24fcca4cf9cc5d85107b60e3b81585181e3e131d2a15262f60e058439ec4497b004bf002fb047f0720c3807e3a115e7d527ced2d7cb06
+  data.tar.gz: 5dcc9589447a55a6c98f025fbdfddffddda4b60a5df9070b8cc89a07d89e05f04eef0a7dbdd88065dcb76ed30628e8a1017837bb25a771c96ea72ef78b94eee7

data/README.md

@@ -1,36 +1,141 @@
-# Twsms2
+Twsms2 ( 2016 台灣簡訊 TwSMS API 套件 )
+======================================
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/twsms2`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Gem Version](https://badge.fury.io/rb/twsms2.svg)](https://badge.fury.io/rb/twsms2)
 
-TODO: Delete this and the text above, and describe your gem
+![twsms](http://i.imgur.com/KVuaBIm.png)
 
-## Installation
+此為針對 [台灣簡訊][twsms_homepage] TwSMS API 開發的專屬套件，支援 Ruby ( >= 2.1 ) 或 Ruby On Rails 
 
-Add this line to your application's Gemfile:
+您可以透過該套件來實作台灣簡訊的基本簡訊發送 與 簡訊餘額查詢 的程式
+
+安裝方式
+--------
+
+請在您的 Ruby 或 Rails 專案裡的 Gemfile 加入以下指令
 
 ```ruby
-gem 'twsms2'
+gem 'twsms2', '~> 0.9.5'
 ```
 
-And then execute:
+然後執行 bundle install 更新套件組
 
     $ bundle
 
-Or install it yourself as:
+或也可以直接將 twsms2 裝在系統上
 
     $ gem install twsms2
 
-## Usage
+使用方式
+--------
+
+本 API 套件，提供幾組以下方法來方便您開發簡訊相關服務
+
+但要使用前，需要先[註冊台灣簡訊的會員][twsms_signup]，否則您的程式無法存取台灣簡訊的 API 管道
+
+```ruby
+require 'twsms2'
+
+# Twsms2 是走 https 的方式進行系統操作
+sms_client = Twsms2::Client.new(username: '台灣簡訊的會員帳號', password: '台灣簡訊的會員密碼')
+```
+
+使用範例
+--------
+
+### 系統檢查
+
+檢查帳號是否有效、是否可以發送簡訊，有效為 true、無效則為 false
+
+```ruby
+sms_client.account_is_available
+```
+
+----
+
+### 發送簡訊
+
+手機號碼可以為 8869XXYYYZZZ 或 09XXYYYZZZ 的格式 ( 以簡訊系統商建議的格式為主 )
+
+一般方式
+
+```ruby
+sms_client.send_message to: '手機號碼', content: "簡訊內容 #{Time.now}"
+```
+
+你可以加入 popup 參數告訴簡訊系統，發送簡訊到收訊人的手機時要直接顯示 ( 但不會儲存在手機 )
+
+```ruby
+sms_client.send_message to: '手機號碼', content: "簡訊內容 #{Time.now}", popup: true
+```
+
+本套件發送簡訊時，預設為長簡訊發送，因此若超 SMS 短信字元長度，將會以第二封起開始計算
+
+當然您可以關閉該設計，請加入 long 參數，並指定為 false 即可
+
+```ruby
+sms_client.send_message to: '手機號碼', content: "簡訊內容 #{Time.now}", long: false
+```
 
-TODO: Write usage instructions here
 
-## Development
+### 發送簡訊 的 回傳結果
+
+當你執行完成後，send_message 方法會回傳一組 hash 型態的結果
+
+只要 access_success 的值為 true 就一定代表發送成功，若為 false 則表示過程有出現錯誤
+
+```ruby
+{:access_success=>true, :message_id=>"217620029", :error=>nil}
+```
+
+例如：以下為帳號密碼的錯誤，error 將會記錄台灣簡訊的 error code
+
+error code 的部分，請以 台灣簡訊 API 文件的定義為主，本套件不處理相關結果
+
+```ruby
+{:access_success=>false, :message_id=>nil, :error=>"TWSMS:00010"}
+```
+
+----
+
+### 查詢簡訊餘額
+
+若你需要查詢您會員帳號的簡訊餘額，可以用以下指令處理
+
+```ruby
+sms_client.get_balance
+```
+
+
+### 查詢簡訊餘額 的 回傳結果
+
+當你執行完成後，get_balance 方法會回傳一組 hash 型態的結果
+
+只要 access_success 的值為 true 就一定代表系統有成功取得資料
+
+message_quota 則是簡訊餘額，代表你還剩幾封可以用，若為 0 就代表都沒有
+
+```ruby
+# 備註：簡訊商若發送過程中出現意外狀況，會晚點將簡訊額度補回您的會員帳號
+{:access_success=>true, :message_quota=>77, :error=>nil}
+```
+
+若 access_success 為 false 則表示過程有出現錯誤，同時 message_quota 會為 0
+
+```ruby
+{:access_success=>false, :message_quota=>0, :error=>"TWSMS:00010"}
+```
+
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+LICENSE
+--------
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+本專案原始碼採 MIT LICENSE 授權 ( 詳見 LICENSE 檔案 )
 
-## Contributing
+連結分享
+--------
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/twsms2.
+[註冊台灣簡訊的會員][twsms_signup]、[台灣簡訊官網 與 API 文件][twsms_homepage]
 
+[twsms_signup]: https://www.twsms.com/accjoin.php
+[twsms_homepage]: https://www.twsms.com/

data/lib/twsms2/version.rb

@@ -1,3 +1,3 @@
 module Twsms2
-  VERSION = "0.9.0"
+  VERSION = "0.9.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twsms2
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.5
 platform: ruby
 authors:
 - Guanting Chen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-02 00:00:00.000000000 Z
+date: 2016-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler