pigeon_fu 0.1.1

data/Changelog

@@ -0,0 +1,2 @@
+Changelog for the PigeonFu Ruby Gem
+================================================================================

data/MIT-LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2010 Why404.
+
+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.markdown

@@ -0,0 +1,35 @@
+### About PigeonFu
+
+PigeonFu is a Ruby gem for building voice and SMS applications. It allows your web application to easily make and receive phone calls and SMS text messages using the ChinaTelecom Open API. You can send E-FAX by using PigeonFu or build hosted IVR, WebCall and SMS applications easily and quickly.
+
+
+### Installation
+
+    $ gem install pigeon_fu
+
+
+### Usage
+
+First, you need to register for an authorized app-account on the ChinaTelecom open platform(http://www.189works.com/).
+
+Then allow me writen an example show you how to send a phone text message to some body.
+
+    require 'pigeon_fu'
+
+    ENV["PIGEON_ACCOUNT_SID"]   = '1000XXXX'                         # YOUR_APP_KEY
+    ENV["PIGEON_ACCOUNT_TOKEN"] = '76e9bde81f1e4e51ac8d86517e4bXXXX' # YOUR_APP_SECRET_KEY
+
+    PigeonFu.send_sms :to  => '1318698XXXX',
+                      :say => 'Just testing to send a sms from my program what I am writting now!'
+
+See the examples/ folder for more examples.
+
+
+### TODO
+
+I am working on it currently, more features will be added in later versions, and it will support both Ruby on Rails 3.0 and Sinatra ASAP.
+
+
+### Copyright
+
+Copyright (c) 2010 why404(why404#gmail), released under the MIT license.

data/Rakefile

@@ -0,0 +1,29 @@
+require 'rake'
+require 'rake/gempackagetask'
+require File.dirname(__FILE__) + '/lib/pigeon_fu/version'
+
+PKG_FILES = FileList[
+  '[a-zA-Z-]*', 
+  'lib/**/*',
+  'examples/*', 
+  'bin/*'
+]
+
+spec = Gem::Specification.new do |s|
+  s.name = "pigeon_fu" 
+  s.version = PigeonFu::VERSION 
+  s.author = "why404" 
+  s.email = "why404@gmail.com" 
+  s.homepage = "http://rubygems.org/gems/pigeon_fu" 
+  s.platform = Gem::Platform::RUBY 
+  s.summary = "SDK written in Ruby for the ChinaTelecom Open Platform." 
+  s.description = "PigeonFu is a Ruby gem (also can be as a Rails plugin, it'll support Rails 3.0.0 or above ASAP) as an unofficial Ruby SDK for the ChinaTelecom Open Platform(http://open.189works.com/)." 
+  s.files = PKG_FILES.to_a 
+  s.require_path = "lib" 
+  s.has_rdoc = false 
+  s.extra_rdoc_files = ["README.markdown"] 
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end

data/bin/pigeonfu.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+ 
+require 'optparse'
+require 'fileutils'
+
+#TODO
+OptionParser.new do |opts|
+  opts.banner = "Usage: pigeonfu [path] \n(should be the applition root path)\n e.g \"pigeonfu . \"."
+ 
+  begin
+    opts.parse!(ARGV)
+  rescue OptionParser::ParseError => e
+    warn e.message
+    puts opts
+    exit 1
+  end
+end

data/examples/send_sms.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + "/../lib"))
+
+require 'pigeon_fu'
+
+ENV["PIGEON_ACCOUNT_SID"] = '1000XXXX' # YOUR_APP_KEY
+ENV["PIGEON_ACCOUNT_TOKEN"] = '76e9bde81f1e4e51ac8d86517e4bXXXX' # YOUR_APP_SECRET_KEY
+
+PigeonFu.send_sms :to  => '13186988528',
+                  :say => 'Just testing to send a sms from my program what I am writting now!'

data/lib/pigeon_fu.rb

@@ -0,0 +1,19 @@
+require 'rubygems'
+require 'time'
+require 'net/http'
+require 'uri'
+require 'cgi'
+require 'digest/sha1'
+require 'base64'
+require 'logger'
+require 'pigeon_fu/base'
+require 'pigeon_fu/utils'
+require 'pigeon_fu/rest'
+require 'pigeon_fu/exceptions'
+require 'pigeon_fu/authenticate'
+require 'pigeon_fu/sms'
+require 'pigeon_fu/call'
+require 'pigeon_fu/ivr'
+require 'pigeon_fu/fax'
+require 'pigeon_fu/version.rb'
+#require 'pigeon_fu/command_line.rb'

data/lib/pigeon_fu/authenticate.rb

@@ -0,0 +1,78 @@
+module PigeonFu
+  class Authenticate
+  
+    def self.start(options={})
+      new(options).run
+    end
+    
+    # 调用相关API之前需要获得电信开放平台的认证授权
+    def initialize(with_interface_code)
+      raise RuntimeError, "constant PIGEON_ACCOUNT_SID sould be defined" unless defined?(ENV["PIGEON_ACCOUNT_SID"])
+      raise RuntimeError, "constant PIGEON_ACCOUNT_TOKEN sould be defined" unless defined?(ENV["PIGEON_ACCOUNT_TOKEN"])
+      @result = Hash.new
+      @options = Hash.new
+      @options[:account_sid] = ENV["PIGEON_ACCOUNT_SID"]     # 开发者的用户ID
+      @options[:account_token] = ENV["PIGEON_ACCOUNT_TOKEN"] # 开发者访问电信API的密钥
+      @options[:api_id] ||= with_interface_code              # API功能接口的编号（电信为每种API定义了一个数字编号，比如发短信的接口ID为10000033）
+      @options[:url] ||= PigeonFu::AUTH_INTERFACE_URL
+      @options[:timestamp] = (Time.now.to_f * 1000).to_i
+      @options[:session_id] = session_id
+    end
+    
+    def run
+      parse_result(make_request)
+    end
+    
+    private
+      
+      def session_id
+        PigeonFu::Rest.get(PigeonFu::SESS_INTERFACE_URL)
+      end
+
+      # 生成当前用于发起认证请求的签名（signature）
+      # 格式：Base64(SHA1(TimeStamp + "$" + APID + "$" + APUserAccount + "$" + FunID + "$" + APKEY))
+      def generate_signature
+        string_for_token = [@options[:session_id],
+                            @options[:account_sid],
+                            @options[:account_nick],
+                            @options[:api_id],
+                            @options[:account_token]
+                           ].join("$")
+        CGI.escape(Base64.encode64(Digest::SHA1.digest(string_for_token)).chomp!)
+      end
+      
+      # 构造发起认证请求需要的查询字符串
+      # 格式：TimeStamp + "$" + APID + "$" + APUserAccount + "$" + FunID + "$" + UrlEncode(Authenticator)
+      def generate_query_string
+        [@options[:session_id], @options[:account_sid], @options[:account_nick],\
+          @options[:api_id], generate_signature].join("$")
+      end
+      
+      # 发起认证请求
+      def make_request
+        PigeonFu::Rest.get(@options[:url], {'AuthRequest' => generate_query_string})
+      end
+      
+      # 解析认证过后的返回结果
+      # 返回数据格式：Result + "$" + TransactionID + "$" + Token+ "$" + ErrorDescription+ "$" + TimeStamp
+      def parse_result(data)
+        if data.include?("$")
+          @result[:number], @result[:transaction_id], @result[:token],\
+            @result[:error_description], @result[:timestamp]  = data.split("$")
+        end
+        # 返回认证后的通行证
+        authorized_token
+      end
+      
+      # 是否认证通过？
+      def authenticated?
+        @result[:number].to_i == 0 ? true : false
+      end
+      
+      # 根据认证结果取得行使指定API功能的凭证
+      def authorized_token
+        authenticated? ? @result[:token] : (raise Unauthorized, @result)
+      end
+    
+  end
+end

data/lib/pigeon_fu/base.rb

@@ -0,0 +1,34 @@
+module PigeonFu
+
+  SESS_INTERFACE_URL = 'http://open.189works.com/InterfaceForAP/GetSessionID.aspx'
+  AUTH_INTERFACE_URL = 'http://open.189works.com/InterfaceForAP/Authv1.1.aspx'
+  
+  SMS_INTERFACE_CODE = 10000033
+  SMS_INTERFACE_URL = 'http://ims.open.ctfactory.com/ims/ghsendim.php'
+  
+  CALL_INTERFACE_CODE = 10000034
+  CALL_INTERFACE_URL = ''
+  
+  IVR_INTERFACE_CODE = 10000108
+  IVR_INTERFACE_URL  = ''
+  
+  FAX_INTERFACE_CODE = 0
+  FAX_INTERFACE_URL = ''
+  
+  PHONE_NUMBER_REGEX = /^\d{8,13}$/ # The overwhelming majority phone numbers in China should be supported.
+  
+  class << self
+    def send_sms(options={})
+      PigeonFu::Sms.send_message(options)
+    end
+  end
+  
+  
+  module Base
+    # In fact it will as a class-methods module mix-in class object. For example see PigeonFu::Sms::ClassMethods
+    module InstanceMethods
+    end
+    
+  end
+ 
+end

data/lib/pigeon_fu/call.rb

@@ -0,0 +1,14 @@
+module PigeonFu
+  class Call
+    
+    module ClassMethods #TODO
+    end
+    
+    module InstanceMethods #TODO
+    end
+    
+    extend self::ClassMethods
+    include self::InstanceMethods
+        
+  end
+end

data/lib/pigeon_fu/command_line.rb

@@ -0,0 +1,5 @@
+module PigeonFu #:nodoc:
+  class CommandLine #:nodoc:
+  #TODO    
+  end
+end

data/lib/pigeon_fu/exceptions.rb

@@ -0,0 +1,36 @@
+module PigeonFu #:nodoc:
+  
+  class Exception < RuntimeError #:nodoc:
+    def message(default=nil)
+      self.class::ErrorMessage
+    end
+  end
+
+  class Unauthorized < Exception #:nodoc:
+    ErrorMessage = 'Unauthorized'
+
+    def initialize(response)
+      @error_code = response[:number]
+      @error_desc = response[:error_description]
+    end
+
+    def message
+      "Error code #{@error_code}, #{@error_desc}."
+    end
+
+    def to_s
+      message
+    end
+  end
+
+  class SendSMSFailed < Exception #:nodoc:
+    ErrorMessage = 'Message was send failed!'
+    
+    attr_accessor :message
+
+    def initialize(response_code)
+      @message = "Message was send failed! Error: #{response_code}."
+    end
+  end
+
+end

data/lib/pigeon_fu/fax.rb

@@ -0,0 +1,14 @@
+module PigeonFu
+  class Fax
+    
+    module ClassMethods #TODO
+    end
+    
+    module InstanceMethods #TODO
+    end
+    
+    extend self::ClassMethods
+    include self::InstanceMethods
+    
+  end
+end

data/lib/pigeon_fu/ivr.rb

@@ -0,0 +1,14 @@
+module PigeonFu
+  class Ivr
+    
+    module ClassMethods #TODO
+    end
+    
+    module InstanceMethods #TODO
+    end
+    
+    extend self::ClassMethods
+    include self::InstanceMethods
+    
+  end
+end

data/lib/pigeon_fu/rest.rb

@@ -0,0 +1,99 @@
+module PigeonFu
+  module Rest
+    class << self
+      def get(url, hashed_vars = {})
+        res = request(url, 'GET', hashed_vars)
+        process_result(res, url)
+      end
+      
+      def post(url, hashed_vars)
+        res = request(url, 'POST', hashed_vars)
+        process_result(res, url)
+      end
+      
+      def put(url, hashed_vars)
+        res = request(url, 'PUT', hashed_vars)
+        process_result(res, url)
+      end
+      
+      def delete(url, hashed_vars)
+        res = request(url, 'DELETE', hashed_vars)
+        process_result(res, url)
+      end
+      
+      protected
+      
+        def request(url, method=nil, params = {})
+          if !url || url.length < 1
+            raise ArgumentError, 'Invalid url parameter'
+          end
+          if method && !['GET', 'POST', 'DELETE', 'PUT'].include?(method)
+            raise NotImplementedError, 'HTTP %s not implemented' % method
+          end
+          
+          if method && method == 'GET'
+            url = build_get_uri(url, params)
+          end
+
+          uri = URI.parse(url)
+          
+          http = Net::HTTP.new(uri.host, uri.port)
+          
+          if method && method == 'GET'
+            req = Net::HTTP::Get.new(uri.request_uri)
+          elsif method && method == 'DELETE'
+            req = Net::HTTP::Delete.new(uri.request_uri)
+          elsif method && method == 'PUT'
+            req = Net::HTTP::Put.new(uri.request_uri)
+            req.set_form_data(params)
+          else
+            req = Net::HTTP::Post.new(uri.request_uri)
+            req.set_form_data(params)
+          end
+          
+          http.request(req)
+        end
+        
+        def build_get_uri(uri, params)
+          if params && params.length > 0
+            if uri.include?('?')
+              if uri[-1, 1] != '&'
+                uri += '&'
+              end
+              uri += urlencode(params)
+            else
+              uri += '?' + urlencode(params)
+            end
+          end
+          uri
+        end
+        
+        def urlencode(params)
+          params.to_a.collect! { |k, v| "#{k.to_s}=#{v.to_s}" }.join("&")
+        end
+        
+        def process_result(res, raw_url)
+          if res.code =~ /\A2\d{2}\z/
+            res.body
+          elsif %w(301 302 303).include? res.code
+            url = res.header['Location']
+            if url !~ /^http/
+              uri = URI.parse(raw_url)
+              uri.path = "/#{url}".squeeze('/')
+              url = uri.to_s
+            end
+            raise RuntimeError, "Redirect #{url}"
+          elsif res.code == "304"
+            raise RuntimeError, "NotModified #{res}"
+          elsif res.code == "401"
+            raise RuntimeError, "Unauthorized #{res}"
+          elsif res.code == "404"
+            raise RuntimeError, "Resource not found #{res}"
+          else
+            raise RuntimeError, "Maybe request timed out #{res}. HTTP status code #{res.code}"
+          end
+        end
+      
+    end
+  end
+end

data/lib/pigeon_fu/sms.rb

@@ -0,0 +1,69 @@
+module PigeonFu
+  class Sms
+    
+    module ClassMethods
+      # include PigeonFu::Base::InstanceMethods
+      
+      def send_message(options={})
+        raise ArgumentError, "You must pass the :to argument to specify the receiver." unless options[:to]
+        raise ArgumentError, "You must pass the :say argument to specify the short message." unless options[:say]
+        @sms = PigeonFu::Sms.new
+        @sms.auth = PigeonFu::Authenticate.new(PigeonFu::SMS_INTERFACE_CODE)
+        @sms.content = encoded_message_from(options[:say])
+        @sms.receivers = fetch_receivers_from(options[:to])
+        @sms.sender = fetch_sender_from(options[:from])
+        @sms.send_phone_text_message
+      end
+      
+      def send_message_to_me(text_content)
+        send_message :to => default_contact, :say => text_content, :from => default_ims
+      end
+      
+      def encoded_message_from(content)
+        Base64.encode64(content.strip).gsub('+', '%2B').gsub('&','%26').gsub("\n","") # CGI.escape
+      end
+      
+      def fetch_receivers_from(given_receivers)
+        receiver_phone_numbers = []
+        if given_receivers.is_a?(String)
+          receivers = given_receivers.include?(',') ? given_receivers.split(',') : [given_receivers]
+        end
+        receivers.each do |receiver|
+          if receiver.is_a_phone_number?
+            receiver_phone_numbers << receiver
+          else
+            raise ArgumentError, "#{receiver} haven't or isn't a valid phone number"
+          end
+        end
+        receiver_phone_numbers
+      end
+      
+      def fetch_sender_from(given_sender = nil)
+        unless given_sender.nil?
+          raise ArgumentError, "#{sender} is not a valid phone number." unless sender.is_a_phone_number?
+        end
+        given_sender
+      end
+    end
+    
+    module InstanceMethods
+      attr_writer :auth, :content, :receivers, :sender
+      
+      def send_phone_text_message
+        @receivers.each { |receiver| send_message_to(receiver) }
+      end
+      
+      def send_message_to(receiver)
+        auth_token = @auth.run
+        request_vars = {'SendMsgRequest' => [auth_token, receiver, @content, @sender].join("$")}
+        response = PigeonFu::Rest.get(PigeonFu::SMS_INTERFACE_URL, request_vars)
+        response_code = response.split("=")[1]
+        raise SendSMSFailed, response_code unless response_code.to_i == 200
+      end
+    end
+    
+    extend self::ClassMethods
+    include self::InstanceMethods
+    
+  end
+end

data/lib/pigeon_fu/utils.rb

@@ -0,0 +1,5 @@
+class String
+  def is_a_phone_number?
+    self =~ PigeonFu::PHONE_NUMBER_REGEX
+  end
+end

data/lib/pigeon_fu/version.rb

@@ -0,0 +1,3 @@
+module PigeonFu
+  VERSION = '0.1.1' 
+end unless defined?(PigeonFu::VERSION)

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification 
+name: pigeon_fu
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- why404
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-10 00:00:00 +08:00
+default_executable: 
+dependencies: []
+
+description: PigeonFu is a Ruby gem (also can be as a Rails plugin, it'll support Rails 3.0.0 or above ASAP) as an unofficial Ruby SDK for the ChinaTelecom Open Platform(http://open.189works.com/).
+email: why404@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+files: 
+- Changelog
+- MIT-LICENSE
+- README.markdown
+- Rakefile
+- lib/pigeon_fu/authenticate.rb
+- lib/pigeon_fu/version.rb
+- lib/pigeon_fu/call.rb
+- lib/pigeon_fu/rest.rb
+- lib/pigeon_fu/ivr.rb
+- lib/pigeon_fu/base.rb
+- lib/pigeon_fu/exceptions.rb
+- lib/pigeon_fu/fax.rb
+- lib/pigeon_fu/sms.rb
+- lib/pigeon_fu/command_line.rb
+- lib/pigeon_fu/utils.rb
+- lib/pigeon_fu.rb
+- examples/send_sms.rb
+- bin/pigeonfu.rb
+has_rdoc: true
+homepage: http://rubygems.org/gems/pigeon_fu
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: SDK written in Ruby for the ChinaTelecom Open Platform.
+test_files: []
+