davetron5000-rtm 0.1.1

data/README.rdoc

@@ -0,0 +1,107 @@
+= Ruby Client for Remember The Milk
+
+Author::   Dave Copeland (mailto:davetron5000 at g mail dot com)
+Copyright:: Copyright (c) 2009 by Dave Copeland
+License:: Distributes under the Apache License, see LICENSE.txt in the source distro
+
+== Overview
+
+This is a very lightweight and easy-to-use client for Remember[http://www.rememberthemilk.com] The[http://www.rememberthemilk.com] Milk[http://www.rememberthemilk.com]
+
+    rtm = RTM.new(Endpoint.new(your_api_key,your_secret))
+    rtm.token = user_token
+    response = rtm.tasks.getList
+    response.tasks.list.as_array.each do |list|
+      # this is an RTM list of taskseries
+    end
+
+=== Authorization
+
+Authorization is a bit tricky, but you only need to do it one time.  This example shows
+command line/desktop usage
+
+    rtm = RTM.new(Endpoint.new(your_api_key,your_secret))
+    auth = rtm.auth
+    url = auth.url
+    frob = auth.frob
+    # Send user to this URL
+    # They will authorize your app's api_key via the RTM website.  
+    # store the frob somewhere, you will need it
+    #
+    # When they return...
+    auth.frob=frob
+    rtm.token=auth.get_token
+    # store the token for all time
+    
+    rtm.tasks.getList
+    rtm.groups.delete
+    rtm.tasks.notes.add
+
+And so forth.  Basically, you can call the RTM methods as if they were real methods.
+
+=== Responses
+
+As shown above, you can simply navigate the XML returned by method names.  This uses Hash.method_missing and can be dicey, so you can also navigate a bit safer via
+
+    response = rtm.tasks.getList
+    response['tasks']['list'].as_array.each do |list|
+      # this is an RTM list of taskseries
+    end
+
+Note that for any element that you want to treat as a list, you must call as_array on it, to ensure that it gets turned into a list.  The underlying HTTParty code doesn't know if an XML element is supposed to be a list or just a singular.
+
+<i>Note that you can use Ruby-style conventions instead of camel-case, e.g. <tt>rtm.tasks.get_list</tt></i>
+
+=== Timelines
+
+Many methods require timelines; this is the way that RTM provides for undo-type features.  If you don't really care about this, or want it done for you, you can specify auto timeline creation:
+
+
+    rtm.auto_timeline=true
+    rtm.tasks.add(:name => 'My new task')
+    timeline = rtm.last_timeline
+
+This will create a timeline for you, and use it to create the task.  The list of methods that <b>do not</b> require timelines is used to determine if this is done, and is based on the RTM documentation at the time of this writing.
+
+== Basic Command Line
+
+To verify and play with the RTM API, there is a command-line tool called <tt>rtm</tt>.  It takes the following commands:
+
+[any] executes any RTM method
+[auth] Prints out the auth URL to authorize your api key/ruby client. Do not do this after getting a token
+[chktoken] Checks that your token is valid
+[help] Shows list of commands or help for one command
+[ls] Lists incomplete tasks
+[token] Gets your token; do this only once and put it in your api.yaml file
+
+The easiest way to get started is to get your API Key and Secret from RTM and then:
+
+   rtm ls
+
+This will init your api.yaml file
+
+   rtm auth
+
+Go to this URL and authorize your API Key.  Save the frob that is printed out
+
+    rtm token <<frob>>
+
+This will authorize your app and print out your token.  Edit <tt>api.yaml</tt> and add your token.
+
+    :token: <<your token>>
+
+To verify:
+
+    rtm ls
+
+This should list your incomplete tasks if all is well.
+
+    rtm any contacts.getList
+
+Will print out a hashdump of what RTM returns for this method.
+   
+== Links
+
+* http://github.com/davetron5000/rtm - Source code
+* http://davetron5000.github.com/rtm - Rubydoc
+* http://www.rememberthemilk.com/services/api/methods/ - RTM API documentation

data/bin/rtm

@@ -0,0 +1,113 @@
+#!/usr/bin/ruby
+$: << File.expand_path(File.dirname(__FILE__) + '/../lib')
+$: << File.expand_path(File.dirname(__FILE__) + '/../ext')
+require 'rubygems'
+require 'gli'
+require 'httparty'
+require 'rtm'
+require 'hash_array'
+
+include GLI
+
+arg_name 'method.call'
+desc 'executes any RTM method.  Do not include the "rtm." in the method name'
+command :any do |c|
+  c.action do |global_options,options,args|
+    parts = args[0].split(/\./)
+    obj = $rtm.send(parts.shift.to_s)
+    response = obj
+    parts.each do |p|
+      response = response.send(p.to_sym)
+    end
+    puts response.inspect
+  end
+end
+
+desc 'Lists incomplete tasks'
+arg_name 'list_name'
+command :ls do |c|
+  c.action do |global_options,options,args|
+    params = { :filter => 'status:incomplete' }
+    params[:filter] += " AND list:#{args[0]}" if args.length > 0
+    response = $rtm.tasks.get_list(params)
+    tasks = Array.new
+    if response.tasks
+    response.tasks.list.as_array.each do |l|
+      l.taskseries.as_array.each do |task|
+        tasks << task
+      end
+    end
+    end
+    tasks.sort {|a,b| a.name.upcase <=> b.name.upcase }.each do |task|
+      printf "%10d - %s\n",task['id'],task.name
+    end
+  end
+end
+
+desc 'Prints out the auth URL to authorize your api key/ruby client and the frob that was used.  Do not do this after getting a token'
+command :auth do |c|
+  c.action do |global_options,options,args|
+    auth = $rtm.auth
+    puts auth.url
+    puts auth.frob
+  end
+end
+
+desc 'Gets your token; do this only once and put it in your api.yaml file'
+arg_name "frob"
+command :token do |c|
+  c.action do |global_options,options,args|
+    if args.length == 1
+      auth = $rtm.auth
+      auth.frob = args[0]
+      puts "Use frob '#{args[0]}'?"
+      a = $stdin.gets.chomp
+      if a == 'yes'
+        puts auth.get_token
+      else
+        puts "You must provide your frob as the argument"
+      end
+    else
+      puts "You didn't say 'yes'"
+    end
+  end
+end
+
+desc 'Checks that your token is valid'
+command :chktoken do |c|
+  c.action do |global_options,options,args|
+    begin
+      $rtm.check_token
+      puts "Token good"
+    rescue RTM::InvalidTokenException
+      puts "Token bad"
+    end
+  end
+end
+
+pre do |global_options,command,options,args|
+  if !command.nil? && command.name != :help
+    return_val = true
+    if File.exists? 'api.yaml'
+    api_info = File.open('api.yaml') { |file| YAML::load(file) }
+    if !(api_info[:api_key] && api_info[:secret])
+      puts "api.yaml isn't complete"
+      return_val = false;
+    else
+      ep = RTM::Endpoint.new(api_info[:api_key],api_info[:secret])
+      ep.token=api_info[:token]
+      $rtm = RTM::RTM.new(ep)
+    end
+    else
+      puts "api.yaml not found; this is a YAML hash of your API key, secret key, and token"
+      File.open('api.yaml','w') { |file| YAML::dump({:api_key => 'your api key', :secret => 'your secret'},file); }
+      puts "it has been created for you with dummy values"
+      return_val = false
+    end
+    return_val
+  else
+    true
+  end
+end
+
+GLI.run(ARGV)

data/ext/hash_array.rb

@@ -0,0 +1,22 @@
+
+# These give Hash and Array a common method that returns an array.
+# HTTParty doesn't know if a particular XML element is expected to be
+# a list, so when it gets one of that element, it returns it as a Hash.
+# So, one can simply call as_array on any part of the XML navigation
+# that is expected to be an array, as such:
+#
+#     response['rsp']['tasks']['list'].as_array.each {|a| }
+#
+# 
+
+class Hash
+  def as_array; [self]; end
+
+  def method_missing(symbol)
+    return self[symbol.to_s]
+  end
+end
+
+class Array
+  def as_array; self; end
+end

data/ext/string_camelize.rb

@@ -0,0 +1,10 @@
+
+class String
+  # Stolen from sequel; gives String a camelize method
+  def camelize(first_letter_in_uppercase = :lower)
+    s = gsub(/\/(.?)/){|x| "::#{x[-1..-1].upcase unless x == '/'}"}.gsub(/(^|_)(.)/){|x| x[-1..-1].upcase}
+    s[0...1] = s[0...1].downcase unless first_letter_in_uppercase == :upper
+    s
+  end
+end
+

data/lib/rtm.rb

@@ -0,0 +1,3 @@
+require 'rtm/rtm'
+require 'rtm/auth'
+require 'rtm/endpoint'

data/lib/rtm/auth.rb

@@ -0,0 +1,58 @@
+require 'string_camelize'
+module RTM
+
+  # Implements authorization related tasks.  These are to be used one-time only
+  # when the user first uses your application.
+  # 
+  #     auth = RTMAuth.new(api_key,secret)
+  #     url = auth.get_auth_url
+  #     # send user to url
+  #     # When they have done so
+  #     token = auth.get_token
+  #     # object auth no longer needed; use token with RTM
+  class RTMAuth
+    def initialize(endpoint)
+      @endpoint = endpoint
+    end
+
+    # Get the URL to allow the user to authorize the application
+    # [perms] the permissions you wish to get, either :read, :write, or :delete
+    # [application_type] if :desktop, a frob is gotten and the URL is suitable for a desktop application.  if :web, a url suitable for the web is returned. 
+    # [callback_url] the callback URL you want the user sent to after they authorize.  This will have the frob and you must call frob= before get_token with the frob that was given to you.
+    def url(perms = :delete, application_type=:desktop, callback_url=nil)
+      @frob = get_frob if application_type == :desktop
+      params = {'perms' => perms.to_s}
+      params['frob'] = @frob if @frob
+      params['callbackURL'] = callback_url if callback_url
+      @endpoint.url_for(nil,{'frob' => @frob, 'perms' => 'delete'},'auth')
+    end
+
+    # After the user has authorized, gets the token
+    def get_token
+      response = @endpoint.call_method('rtm.auth.getToken', { 'frob' => @frob }, false)
+      response['auth']['token']
+    end
+    alias :getToken :get_token
+
+    def check_token
+      raise "checkToken should be called on the RTM object directly";
+    end
+    alias :checkToken :check_token
+
+    def get_frob
+      response = @endpoint.call_method('rtm.auth.getFrob',nil,false)
+      @frob = response['frob']
+      @frob
+    end
+    alias :getFrob :get_frob
+
+    # After a call to get_frob, this returns the frob that was gotten.
+    def frob
+      @frob
+    end
+
+    def frob=(frob)
+      @frob=frob
+    end
+  end
+end

data/lib/rtm/endpoint.rb

@@ -0,0 +1,146 @@
+require 'httparty'
+
+module RTM
+  # Acts as the endopint to RTM actions, providing a means to separate the API's behavior
+  # with interaction with RTM.
+  class Endpoint
+    NO_TIMELINE = {
+      "rtm.contacts.getList" => true,
+      "rtm.groups.getList" => true,
+      "rtm.lists.getList" => true,
+      "rtm.reflection.getMethodInfo" => true,
+      "rtm.reflection.getMethods" => true,
+      "rtm.settings.getList" => true,
+      "rtm.tasks.getList" => true,
+      "rtm.test.echo" => true,
+      "rtm.test.login" => true,
+      "rtm.time.convert" => true,
+      "rtm.time.parse" => true,
+      "rtm.timelines.create" => true,
+      "rtm.timezones.getList" => true,
+      "rtm.transactions.undo" => true,
+    }
+    BASE_URL = 'http://www.rememberthemilk.com/services/'
+
+    # Create an endpoint to RTM, upon which methods may be called.
+    # [api_key] your api key
+    # [secret] your secret
+    # [http] a class that acts like HTTParty (omit; this is used for testing mostly)
+    def initialize(api_key,secret,http=HTTParty)
+      @api_key = api_key
+      @secret = secret
+      @http=http
+      raise "Cannot work with a secret key" if @secret.nil?
+      raise "Cannot work with a api_key key" if @api_key.nil?
+    end
+
+    def auto_timeline=(auto)
+      @auto_timeline = auto
+    end
+
+    # Update the token used to access this endpoint
+    def token=(token)
+      @token = token
+    end
+
+    def last_timeline
+      @last_timeline
+    end
+
+    # Calls the RTM method with the given parameters
+    # [method] the full RTM method, e.g. rtm.tasks.getList
+    # [params] the parameters to pass, can be symbols.  api_key, token, and signature not required
+    # [token_required] if false, this method will not require a token
+    def call_method(method,params={},token_required=true)
+      @last_timeline = nil
+      raise NoTokenException if token_required && (!@token || @token.nil?)
+      params = {} if params.nil?
+      params[:auth_token] = @token if !@token.nil?
+
+      if (@auto_timeline && !NO_TIMELINE[method])
+        response = @http.get(url_for('rtm.timelines.create',{'auth_token' => @token}));
+        if response['timeline']
+          @last_timeline = response['timeline']
+          params[:timeline] = @last_timeline
+        else
+          raise BadResponseException, "Expected a <timeline></timeline> type response, but got: #{response.body}"
+        end
+      end
+
+      params_no_symbols = Hash.new
+      params.each do |k,v|
+        params_no_symbols[k.to_s] = v
+      end
+
+      response = @http.get(url_for(method,params_no_symbols))
+      verify(response)
+      return response['rsp']
+    end
+
+    # Get the url for a particular call, doing the signing and all that other stuff.
+    #
+    # [method] the RTM method to call
+    # [params] hash of parameters.  The +method+, +api_key+, and +api_sig+ parameters should _not_ be included.
+    # [endpoint] the endpoint relate to BASE_URL at which this request should be made.  
+    def url_for(method,params={},endpoint='rest')
+      params['api_key'] = @api_key
+      params['method'] = method if method
+      signature = sign(params)
+      url = BASE_URL + endpoint + '/' + params_to_url(params.merge({'api_sig' => signature}))
+      url
+    end
+
+
+    private
+
+    # quick and dirty way to check the response we got back from RTM.
+    # Call this after every call to RTM.  This will verify that you got <rsp> with a "stat='ok'"
+    # and, if not, make a best effort at raising the error message from RTM.
+    #
+    # [response] the response from HTTParty from RTM
+    def verify(response)
+      raise BadResponseException, "No response at all" if !response || response.nil?
+      raise BadResponseException, "Got response with no body" if !response.body
+      raise BadResponseException, "Didn't find an rsp element, response body was #{response.body}" if !response["rsp"]
+      raise BadResponseException, "Didn't find a stat in the <rsp> element, response body was #{response.body}" if !response["rsp"]["stat"]
+      if response['rsp']['stat'] != 'ok'
+        err = response['rsp']['err']
+        if err
+          code = err['code']
+          msg = err['msg']
+          raise VerificationException, "ERROR: Code: #{code}, Message: #{msg}"
+        else
+          raise VerificationException, "Didn't find an <err> tag in the response for stat #{response['rsp']['stat']}, response body was #{response.body}" 
+        end
+      end
+    end
+
+    # Turns params into a URL
+    def params_to_url(params)
+      string = '?'
+      params.each do |k,v|
+        string += CGI::escape(k)
+        string += '='
+        string += CGI::escape(v)
+        string += '&'
+      end
+      string
+    end
+
+    # Signs the request given the params and secret key
+    #
+    # [params] hash of parameters
+    #
+    def sign(params)
+      raise "Something's wrong; @secret is nil" if @secret.nil?
+      sign_me = @secret
+      params.keys.sort.each do |key|
+        sign_me += key
+        raise "Omit params with nil values; key #{key} was nil" if params[key].nil?
+        sign_me += params[key]
+      end
+      return Digest::MD5.hexdigest(sign_me)
+    end
+
+  end
+end

data/lib/rtm/rtm.rb

@@ -0,0 +1,145 @@
+require 'rubygems'
+require 'string_camelize'
+require 'digest/md5'
+require 'cgi'
+require 'rtm/auth'
+require 'rtm/endpoint'
+
+module RTM
+
+  # Root access to RTM api.
+  # Most methods work just like the api demonstrates, however auth is a bit different:
+  #
+  #     rtm = RTM.new(Endpoint.new(api_key,secret))
+  #     auth_url = rtm.auth.url
+  #     # Send user to url
+  #     # When they click authorize and return to your app do:
+  #     rtm.token=rtm.auth.get_token
+  #
+  # This is a one time thing, so cache the token somewhere and you are good to go:
+  #
+  #     response = rtm.tasks.getList(:filter => 'location:Work and status:completed')
+  #     response = rtm.groups.add(:group => 'My New Group')
+  #
+  # If you don't supply timelines, they will be created for you each time as needed.
+  # Also note that you can use Ruby-style method calls instead of filthy camel-case, e.g.
+  #
+  #     response = rtm.tasks.get_list(:filter => 'location:Work and status:completed')
+  #     # Same as 
+  #     response = rtm.tasks.getList(:filter => 'location:Work and status:completed')
+  #
+  class RTM
+
+    # Create access to RTM
+    # 
+    # [endpoint] an Endpoint to RTM
+    def initialize(endpoint)
+      @endpoint = endpoint
+    end
+
+    # Set the token
+    def token=(token)
+      @endpoint.token=token
+    end
+
+    def auto_timeline=(a)
+      @endpoint.auto_timeline=a
+    end
+
+    # Gets the last timeline that was used if in auto-timeline mode
+    def last_timeline
+      @endpoint.last_timeline
+    end
+
+    # Get the auth method-space
+    def auth
+      RTMAuth.new(@endpoint)
+    end
+
+    # Raises an InvalidTokenException if the token is not valid
+    def check_token
+      begin
+        response = @endpoint.call_method('rtm.auth.checkToken')
+      rescue VerificationException
+        raise InvalidTokenException
+      end
+    end
+    alias :checkToken :check_token
+
+    # Get the test method-space (Kernel defines a test method, making method_missing problematic)
+    def test
+      return RTMMethodSpace.new('test',@endpoint)
+    end
+
+    # Gateway to all other method-spaces.  Assumes you are making a valid call
+    # on RTM.  Essentially, *any* method will give you an RTMMethodSpace object keyed to the
+    # method name, e.g. rtm.foobar will assume that RTM has a "foobar" methodspace.
+    # method names are converted to camelcase.
+    def method_missing(symbol,*args)
+      if !args || args.empty?
+        rtm_object = symbol.to_s.camelize
+        return RTMMethodSpace.new(rtm_object,@endpoint)
+      else
+        return super(symbol,*args)
+      end
+    end
+
+  end
+
+  # Generic means of calling an RTM method.  This is returned by RTM.method_missing and, in most cases, is
+  # the end point that calls an RTM method.  
+  class RTMMethodSpace
+
+    # Create an RTMMethodSpace
+    #
+    # [name] the name of this method space, e.g. 'tasks'
+    # [endpoint] an endpoing to RTM
+    def initialize(name,endpoint)
+      @name = name
+      @endpoint = endpoint
+      raise "No endpoint" if @endpoint.nil?
+    end
+
+    # Calls the method on RTM in most cases.  The only exception is if this RTMMethodSpace is 'tasks' and you
+    # call the 'notes' method on it: a new RTMMethodSpace is returned for the 'rtm.tasks.notes' method-space.
+    #
+    # This returns a response object as from HTTParty, dereferenced into <rsp>.  So, for example, if you called
+    # the 'tasks.getList' method, you would get a hash that could be accessed via response['tasks'].
+    # This object is a Hash and Array structure that mimcs the XML returned by RTM.  One quirk is that for methods that could return 1 or more
+    # of the same item (tasks.getList is a good example; it will return multilple <list> elements unless you restrict by list, in which case
+    # it returns only one <list> element).   Because HTTParty doesn't understand this, you may find it convienient to convert such
+    # results to arrays.  the to_array extension on Hash and Array accomplish this:
+    #
+    #     response = rtm.tasks.getList(:filter => 'list:Work')
+    #     response['tasks']['list'].as_array.eadch do |list|
+    #       list['taskseries'].as_array.each do |task|
+    #         puts task['name']
+    #       end
+    #     end
+    #
+    # So, call to_array on anything you expect to be a list.
+    #
+    # This method raises either a BadResponseException if you got a bad or garbled response from RTM or a VerificationException
+    # if you got a non-OK response.
+    def method_missing(symbol,*args)
+      if (@name == 'tasks' && symbol.to_s == 'notes')
+        return RTMMethodSpace.new("tasks.notes",@endpoint)
+      else
+        rtm_method = "rtm.#{@name}.#{symbol.to_s.camelize}"
+        @endpoint.call_method(rtm_method,*args)
+      end
+    end
+  end
+
+  class VerificationException < Exception
+  end
+
+  class BadResponseException < Exception
+  end
+
+  class InvalidTokenException < Exception
+  end
+
+  class NoTokenException < Exception
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification 
+name: davetron5000-rtm
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- David Copeland
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-25 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.3.1
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: davetron5000-gli
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.5
+    version: 
+description: 
+email: davidcopeland@naildrivin5.com
+executables: 
+- rtm
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- ext/hash_array.rb
+- ext/string_camelize.rb
+- lib/rtm/auth.rb
+- lib/rtm/endpoint.rb
+- lib/rtm/rtm.rb
+- lib/rtm.rb
+- bin/rtm
+- README.rdoc
+has_rdoc: true
+homepage: http://davetron5000.github.com/rtm
+post_install_message: 
+rdoc_options: 
+- --title
+- Remember The Milk Ruby Client
+- --main
+- README.rdoc
+- -ri
+require_paths: 
+- lib
+- ext
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: client to access the Remember The Milk API
+test_files: []
+