kotsms2 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: caba16f48eabc4f0d3067cd20b8f8ba4c67d00f1
+  data.tar.gz: adb7317fe123b5a1ed90f5062e7940002bcaf703
+SHA512:
+  metadata.gz: f743ae865b95c28a08e9ad53f753701d5ce9b92c8e243d3a02facffcbdaba43fcd2e7ad2f690aef41699d7d417e11ddcbdeca7bb160cde71f8039f692ba13573
+  data.tar.gz: d3737900c4ba72f004ac765e4bf0f85b083d6f3507c1239e54f3acbcd4585276e844e837eb92241b5961dbabda61678b7daa15580337c874bee5b74760bc7f46

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

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

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in kotsms2.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Guanting Chen
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+Kotsms2 ( 2016 新版 簡訊王 KotSMS API Ruby 版套件 )
+=================================================
+
+[![Gem Version](https://badge.fury.io/rb/kotsms2.svg)](https://badge.fury.io/rb/kotsms2) [![Build Status](https://travis-ci.org/guanting112/kotsms2.svg?branch=master)](https://travis-ci.org/guanting112/kotsms2)
+
+![kotsms](http://i.imgur.com/Q4QbtOP.png)
+
+此為針對 [簡訊王][kotsms_homepage] KotSMS API 開發的專屬套件
+
+您可以透過該套件來實作簡訊王的一般、預約簡訊發送 與 簡訊餘額查詢 的程式
+
+適用於
+--------
+
+Ruby 2 以上的版本，也可在 Ruby On Rails 專案引入
+
+安裝方式
+--------
+
+請在您的 Ruby 或 Rails 專案裡的 Gemfile 加入以下指令
+
+```ruby
+gem 'kotsms2', '~> 1.0.0'
+```
+
+然後執行 bundle install 更新套件組
+
+    $ bundle
+
+或也可以直接將 kotsms2 裝在系統上
+
+    $ gem install kotsms2
+
+使用方式
+--------
+
+本 API 套件，提供幾組以下方法來方便您開發簡訊相關服務
+
+但要使用前，需要先[註冊簡訊王的會員][kotsms_signup]，否則您的程式無法存取簡訊王的 API 管道
+
+```ruby
+require 'kotsms2'
+
+# Kotsms2 是走 https 的方式進行系統操作
+sms_client = Kotsms2::Client.new(username: '會員帳號', password: '會員密碼', agent: "Mozilla/5.0 (可自訂 user-agent)")
+```
+
+使用範例
+--------
+
+### 系統檢查
+
+檢查帳號是否有效、是否可以發送簡訊，有效為 true、無效則為 false
+
+```ruby
+sms_client.account_is_available
+```
+
+----
+
+### 發送簡訊
+
+#### 一般使用
+
+手機號碼格式 0911222333 ( 台灣手機 )、886911222333 ( 國碼 + 手機號碼 )
+
+```ruby
+# 備註：簡訊王的內容需要為 Big 5 編碼，本套件將會自動進行轉換，若有遇到無法轉換的，會將會替換成「?」號
+sms_client.send_message to: '手機號碼', content: "簡訊內容.."
+```
+
+#### 預約發送
+
+若要使用預約發送，可以指定 at 參數給 send_message 方法
+
+同時程式會自動轉換時區 至 簡訊王 適用的時區 ( +08:00 )
+
+```ruby
+# 純 Ruby 請用加秒數的方式
+sms_client.send_message to: '手機號碼', content: "預約簡訊測試: #{Time.now}", at: Time.now + 120
+
+# 在 Ruby On Rails 專案則可以用 Rails 專用的方法
+sms_client.send_message to: '手機號碼', content: "預約簡訊測試: #{Time.now}", at: Time.now + 2.days
+```
+
+#### 切換 大量發送 專用線路
+
+根據簡訊王文件說明，若要進行上千、萬數以上的大量發送，建議使用專用線路
+
+因此，本程式有提供一個 heavy_loading 參數，讓您切換至大量發送專用線路
+
+```ruby
+sms_client.send_message to: '手機號碼', content: "簡訊內容..", heavy_loading: true
+```
+
+當您指定了該參數後，將會使用另外的線路進行發送
+
+但請根據實際發送需求進行使用，小量發送可以不用加入 heavy_loading 參數
+
+因為簡訊王的大量發送專用線路，屬於另一種處理方式，小量發送並不會比較即時
+
+### 發送簡訊 的 回傳結果
+
+#### 發送成功
+
+當你執行完成後，send_message 方法會回傳一組 hash 型態的結果
+
+只要 access_success 的值為 true 就一定代表發送成功
+
+系統會另外回傳一組 message_id 用來讓你追蹤簡訊
+
+```ruby
+{:access_success=>true, :message_id=>"123456789", :error=>nil}
+```
+
+#### 發生錯誤時
+
+若 access_success 為 false 則表示過程有出現錯誤
+
+以下範例為帳號密碼的錯誤，error 參數則是簡訊王的 error code
+
+error code 的部分，請以 簡訊王 API 文件的定義為主，本套件不處理相關結果
+
+```ruby
+{:access_success=>false, :message_id=>nil, :error=>"KOTSMS:-2"}
+```
+
+----
+
+### 查詢簡訊餘額
+
+若你需要查詢您會員帳號的簡訊餘額，可以用以下指令處理
+
+```ruby
+sms_client.get_balance
+```
+
+### 查詢簡訊餘額 的 回傳結果
+
+#### 得到簡訊餘額
+
+當你執行完成後，get_balance 方法會回傳一組 hash 型態的結果
+
+只要 access_success 的值為 true 就一定代表系統有成功取得資料
+
+message_quota 則是簡訊餘額，代表你還剩幾封可以用，若為 0 就代表都沒有
+
+```ruby
+# 備註：簡訊商若發送過程中出現意外狀況，會晚點將簡訊額度補回您的會員帳號
+{:access_success=>true, :message_quota=>10, :error=>nil}
+```
+
+#### 發生錯誤
+
+若 access_success 為 false 則表示過程有出現錯誤，同時 message_quota 會為 0
+
+```ruby
+{:access_success=>false, :message_quota=>0, :error=>"KOTSMS:-2"}
+```
+
+
+LICENSE
+--------
+
+本專案原始碼採 MIT LICENSE 授權 ( 詳見 LICENSE 檔案 )
+
+連結分享
+--------
+
+[註冊簡訊王的會員][kotsms_signup]、[簡訊王官網][kotsms_homepage]、[API 技術支援][kotsms_tech]
+
+[kotsms_signup]: https://kotsms.com.tw/index.php?selectpage=MembersReg&step=viewrules
+[kotsms_homepage]: https://www.kotsms.com.tw
+[kotsms_tech]: https://kotsms.com.tw/index.php?selectpage=pagenews&kind=4

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+task :default => :spec
+
+Rake::TestTask.new(:spec) do |t|
+  t.test_files = FileList['spec/*_spec.rb']
+  t.warning = true
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "kotsms2"
+
+# 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"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/kotsms2.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kotsms2/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "kotsms2"
+  spec.version       = Kotsms2::VERSION
+  spec.authors       = ["Guanting Chen"]
+  spec.email         = ["cgt886@gmail.com"]
+  spec.license       = "MIT"
+  spec.platform      = Gem::Platform::RUBY
+  spec.summary       = %q{2016 新版 簡訊王 KotSMS API ( 純 Ruby / Rails 專案適用 )}
+  spec.description   = %q{2016 新版 簡訊王 KotSMS API ( 純 Ruby / Rails 專案適用 )}
+  spec.homepage      = "https://github.com/guanting112/kotsms2"
+  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.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  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 'minitest', '~> 5.0'
+end

data/lib/kotsms2/exception.rb

@@ -0,0 +1,5 @@
+module Kotsms2
+  class Error < StandardError; end
+  class ClientError < Error; end
+  class ServerError < Error; end
+end

data/lib/kotsms2/formatter.rb

@@ -0,0 +1,75 @@
+module Kotsms2
+  module Formatter
+    def to_big5(old_string)
+      new_string = old_string.encode("BIG5", :invalid => :replace, :undef => :replace, :replace => "?")
+    end
+
+    def to_utf8(old_string)
+      new_string = old_string.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "?")
+    end
+
+    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?
+      new_time = to_asia_taipei_timezone(time)
+      new_time.strftime('%Y/%m/%d %H:%M:%S')
+    end
+
+    def to_asia_taipei_timezone(time)
+      utc_time = time.utc? ? time.dup : time.dup.utc
+      asia_taipei_time = utc_time.getlocal('+08:00')
+      asia_taipei_time
+    end
+
+    def format_send_message_info(original_info)
+      new_info = {
+        access_success: false,
+        message_id: nil,
+        error: nil
+      }
+
+      code_text = match_string(/^kmsgid=(?<code>-?\d+)$/, original_info)
+      code_number = code_text.to_i
+
+      new_info[:access_success] = !code_text.nil? && code_number > -1
+
+      if new_info[:access_success]
+        new_info[:message_id] = code_number.to_s
+      else
+        new_info[:error] = "KOTSMS:CODE_NOT_FOUND"
+        new_info[:error] = "KOTSMS:#{code_text}" unless code_text.nil?
+        new_info[:error].upcase!
+      end
+
+      new_info
+    end
+
+    def format_balance_info(original_info)
+      new_info = {
+        access_success: false,
+        message_quota: 0,
+        error: nil
+      }
+
+      code_text = match_string(/^(?<code>-?\d+)$/, original_info)
+      code_number = code_text.to_i
+
+      new_info[:access_success] = !code_text.nil? && code_number > -1
+
+      if new_info[:access_success]
+        new_info[:message_quota] = code_number
+      else
+        new_info[:error] = "KOTSMS:CODE_NOT_FOUND"
+        new_info[:error] = "KOTSMS:#{code_text}" unless code_text.nil?
+        new_info[:error].upcase!
+      end
+
+      new_info
+    end
+
+  end
+end

data/lib/kotsms2/network.rb

@@ -0,0 +1,43 @@
+require 'net/http'
+require 'cgi'
+
+module Kotsms2
+  module Network
+    def get(host, request_uri, params = {})
+      uri = URI('https://' + host + request_uri)
+      uri.query = query_string(params.merge(username: @username, password: @password))
+
+      message = Net::HTTP::Get.new(uri.request_uri)
+      message['User-Agent'] = @user_agent
+
+      parse(request(uri, message), host)
+    end
+
+    def parse(http_response, host)
+      case http_response
+      when Net::HTTPSuccess
+        http_response.body
+      when Net::HTTPClientError
+        raise ClientError, "#{http_response.code} response from #{host}"
+      when Net::HTTPServerError
+        raise ServerError, "#{http_response.code} response from #{host}"
+      else
+        raise Error, "#{http_response.code} response from #{host}"
+      end
+    end
+
+    def request(uri, message)
+      http = Net::HTTP.new(uri.host, Net::HTTP.https_default_port)
+      http.use_ssl = true
+      http.request(message)
+    end
+
+    def query_string(params)
+      params.flat_map { |k, vs| Array(vs).map { |v| "#{escape(k)}=#{escape(v)}" } }.join('&')
+    end
+
+    def escape(component)
+      CGI.escape(component.to_s)
+    end
+  end
+end

data/lib/kotsms2/version.rb

@@ -0,0 +1,3 @@
+module Kotsms2
+  VERSION = "0.5.0"
+end

data/lib/kotsms2.rb

@@ -0,0 +1,46 @@
+require 'kotsms2/version'
+require 'kotsms2/network'
+require 'kotsms2/exception'
+require 'kotsms2/formatter'
+
+module Kotsms2
+  class Client
+    include Kotsms2::Network
+    include Kotsms2::Formatter
+
+    def initialize(options={})
+      @user_agent = options.fetch(:agent) { "kotsms2/#{VERSION}" }
+      @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') }
+    end
+
+    def account_is_available
+      balance_info = get_balance
+
+      ok = balance_info[:message_quota] > 0 && balance_info[:access_success]
+    end
+
+    def send_message(options={})
+      options[:to] ||= nil
+      options[:heavy_loading] ||= false
+
+      options[:content] = options[:content].to_s
+      options[:at] = format_time_string(options[:at])
+      options[:at] = 0 if options[:at].nil? # 據 Kotsms 文件指出，如果要更即時，可以指定為 0，比不給參數還快
+
+      api_path = '/kotsmsapi-1.php' 
+      api_path = '/kotsmsapi-2.php' if options[:heavy_loading]
+
+      response = get(@api_host, api_path, dstaddr: options[:to], smbody: to_big5(options[:content]), dlvtime: options[:at])
+
+      format_send_message_info(response)
+    end
+
+    def get_balance
+      response = get(@api_host, '/memberpoint.php')
+
+      format_balance_info(response)
+    end
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: kotsms2
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Guanting Chen
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-09-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 2016 新版 簡訊王 KotSMS API ( 純 Ruby / Rails 專案適用 )
+email:
+- cgt886@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- kotsms2.gemspec
+- lib/kotsms2.rb
+- lib/kotsms2/exception.rb
+- lib/kotsms2/formatter.rb
+- lib/kotsms2/network.rb
+- lib/kotsms2/version.rb
+homepage: https://github.com/guanting112/kotsms2
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+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
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.4
+signing_key: 
+specification_version: 4
+summary: 2016 新版 簡訊王 KotSMS API ( 純 Ruby / Rails 專案適用 )
+test_files: []