rufus-rtm 0.1

data/README.txt

@@ -0,0 +1,144 @@
+
+= rufus-rtm
+
+
+== getting it
+
+    sudo gem install -y rufus-rtm
+
+or at
+
+http://rubyforge.org/frs/?group_id=4812
+
+
+== credentials
+
+'rufus-rtm' expects to find RTM credentials in the environment. It will look for :
+
+* RTM_API_KEY
+* RTM_SHARED_SECRET
+* RTM_FROB
+* RTM_AUTH_TOKEN
+
+You have to apply for the first two ones at http://www.rememberthemilk.com/services/api/keys.rtm
+
+Once you have the API key and the shared secret, you have to get the frob and the auth token. Fire your 'irb' and
+
+    >> require 'rubygems'
+    >> require 'rufus/rtm'
+
+    please visit this URL with your browser and then hit 'enter' :
+
+    http://www.rememberthemilk.com/services/auth/?api_sig=70036e47c38da170fee431f04e29e8f0&frob=fa794036814b78fddf3e5641fe7c37f80e7d91fc&perms=delete&api_key=7f07e4fc5a944bf8c02a7d1e45c79346
+
+visit, the given URL, you should finally be greeted by a message like "You have successfully authorized the application API Application. You may now close this window and continue the authentication process with the application that sent you here.", hit enter...
+
+    ok, now getting auth token...
+
+    here are your RTM_FROB and RTM_AUTH_TOKEN, make sure to place them
+    in your environment :
+
+    export RTM_FROB=3cef465718317b837eec2faeb5340fe777d55c7c
+    export RTM_AUTH_TOKEN=ca0022d705ea1831543b7cdd2d7e3d707a0e1efb
+
+make then sure that all the 4 variables are set in the environment you use for running 'rufus-rtm'.
+
+
+== usage
+
+    require 'rubygems'
+    require 'rufus/rtm'
+
+    #
+    # listing tasks
+
+    tasks = Task.find
+        # finding all the tasks
+
+    tasks = Task.find :filter => "status:incomplete"
+        # finding all the incomplete tasks
+
+    tasks.each do |task|
+
+        puts "task id #{task.task_id}"
+        puts "   #{task.name} (#{task.tags.join(",")})"
+        puts
+    end
+
+    #
+    # adding a task
+
+    task = Task.add! "study this rufus-rtm gem"
+        # gets added to the 'Inbox' by default
+
+    puts "task id is #{task.task_id}"
+
+    #
+    # enumerating lists
+
+    lists = List.find
+
+    w = lists.find { |l| l.name == 'Work' }
+
+    puts "my Work list id is #{w.list_id}"
+
+    #
+    # adding a task to a list
+
+    task = Task.add! "work, more work", w.list_id
+
+    #
+    # completing a task
+
+    task.complete!
+
+    #
+    # deleting a task
+
+    task.delete!
+
+
+Note that the methods that change the state of the Remember The Milk dataset have names ending with an exclamation mark.
+
+
+= features yet to implement
+
+* tags modifications
+* smart lists
+* ...
+
+
+= dependencies
+
+The gem 'rufus-verbs' (http://rufus.rubyforge.org/rufus-verbs)
+
+
+== mailing list
+
+On the rufus-ruby list[http://groups.google.com/group/rufus-ruby] :
+
+    http://groups.google.com/group/rufus-ruby
+
+
+== issue tracker
+
+http://rubyforge.org/tracker/?atid=18584&group_id=4812&func=browse
+
+
+== source
+
+http://rufus.rubyforge.org/svn/trunk/rtm
+
+    svn checkout http://rufus.rubyforge.org/svn/trunk/rtm
+
+
+== author
+
+John Mettraux, jmettraux@gmail.com 
+http://jmettraux.wordpress.com
+
+
+== license
+
+MIT
+

data/lib/rufus/rtm.rb

@@ -0,0 +1,39 @@
+
+#
+#--
+# Copyright (c) 2008, John Mettraux, jmettraux@gmail.com
+#
+# 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.
+#
+# (MIT license)
+#++
+#
+
+#
+# John Mettraux
+#
+# Made in Japan
+#
+# 2008/02/07
+#
+
+require 'rufus/rtm/base'
+require 'rufus/rtm/credentials'
+require 'rufus/rtm/resources'
+

data/lib/rufus/rtm/base.rb

@@ -0,0 +1,101 @@
+
+#
+#--
+# Copyright (c) 2008, John Mettraux, jmettraux@gmail.com
+#
+# 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.
+#
+# (MIT license)
+#++
+#
+
+#
+# John Mettraux
+#
+# Made in Japan
+#
+# 2008/02/07
+#
+
+require 'rubygems'
+require 'rufus/verbs'
+
+require 'json'
+require 'md5'
+
+include Rufus::Verbs
+
+
+module Rufus
+module RTM
+    
+    AUTH_ENDPOINT = "http://www.rememberthemilk.com/services/auth/"
+    REST_ENDPOINT = "http://api.rememberthemilk.com/services/rest/"
+
+    #
+    # Signs the RTM request (sets the 'api_sig' parameter).
+    #
+    def self.sign (params) #:nodoc:
+
+        sig = MD5.md5(SHARED_SECRET + params.sort.flatten.join)
+        params['api_sig'] = sig.to_s
+
+        params
+    end
+
+    #
+    # Calls an API method (milk the cow).
+    #
+    def self.milk (params={}) #:nodoc:
+
+        sleep 1
+
+        endpoint = params.delete :endpoint
+        endpoint = AUTH_ENDPOINT if endpoint == :auth
+        endpoint = endpoint || REST_ENDPOINT
+
+        ps = params.inject({}) do |r, (k, v)|
+            r[k.to_s] = v
+            r
+        end
+
+        ps['api_key'] = API_KEY
+        ps['format'] = "json"
+
+        ps['frob'] = FROB if FROB
+        ps['auth_token'] = AUTH_TOKEN if AUTH_TOKEN
+
+        sign ps
+
+        res = get endpoint, :query => ps
+
+        JSON.parse(res.body)["rsp"]
+    end
+
+    #
+    # Requests a timeline from RTM.
+    #
+    def self.get_timeline #:nodoc:
+
+        milk(:method => "rtm.timelines.create")['timeline']
+    end
+
+end
+end
+

data/lib/rufus/rtm/credentials.rb

@@ -0,0 +1,122 @@
+
+#
+#--
+# Copyright (c) 2008, John Mettraux, jmettraux@gmail.com
+#
+# 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.
+#
+# (MIT license)
+#++
+#
+
+#
+# John Mettraux
+#
+# Made in Japan
+#
+# 2008/02/07
+#
+
+module Rufus::RTM
+    
+    def self.auth_get_frob #:nodoc:
+
+        r = milk :method => "rtm.auth.getFrob"
+        r["frob"]
+    end
+
+    def self.auth_get_frob_and_url #:nodoc:
+
+        frob = auth_get_frob
+
+        p = {}
+        p['api_key'] = API_KEY
+        p['perms'] = "delete"
+        p['frob'] = frob
+        sign p
+
+        [
+            frob,
+            AUTH_ENDPOINT + "?" + p.collect { |k, v| "#{k}=#{v}" }.join("&")
+        ]
+    end
+
+    def self.auth_get_token (frob) #:nodoc:
+
+        begin
+            milk(:method => "rtm.auth.getToken", :frob => frob)['auth']['token']
+        rescue Exception => e
+            nil
+        end
+    end
+
+    #
+    # ensuring the credentials are present...
+
+    API_KEY = ENV['RTM_API_KEY']
+    SHARED_SECRET = ENV['RTM_SHARED_SECRET']
+
+    raise "API_KEY missing from environment, cannot use Rufus::RTM" \
+        unless API_KEY
+    
+    FROB = ENV['RTM_FROB']
+    AUTH_TOKEN = ENV['RTM_AUTH_TOKEN']
+
+    unless FROB
+
+        frob, auth_url = auth_get_frob_and_url
+
+        puts <<-EOS
+
+please visit this URL with your browser and then hit 'enter' :
+
+#{auth_url}
+
+        EOS
+
+        STDIN.gets
+        puts "ok, now getting auth token...\n"
+
+        auth_token = auth_get_token frob
+
+        if auth_token
+
+            puts <<-EOS
+
+here are your RTM_FROB and RTM_AUTH_TOKEN, make sure to place them
+in your environment :
+
+export RTM_FROB=#{frob}
+export RTM_AUTH_TOKEN=#{auth_token}
+
+            EOS
+        else
+
+            puts <<-EOS
+
+couldn't get auth token, please retry...
+
+            EOS
+        end
+
+        exit 0
+    end
+
+end
+

data/lib/rufus/rtm/resources.rb

@@ -0,0 +1,347 @@
+
+#
+#--
+# Copyright (c) 2008, John Mettraux, jmettraux@gmail.com
+#
+# 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.
+#
+# (MIT license)
+#++
+#
+
+#
+# John Mettraux
+#
+# Made in Japan
+#
+# 2008/02/07
+#
+
+module Rufus::RTM
+    
+    #
+    # A parent class for Task, List and co.
+    #
+    # Never use directly.
+    #
+    class MilkResource
+
+        def initialize (hsh)
+
+            @hsh = hsh
+            @operations = []
+        end
+
+        #
+        # Saves the instance back to RTM.
+        #
+        def save!
+
+            # TODO : compact !
+
+            @operations.reverse.each do |method_name, args|
+
+                self.class.execute method_name, args
+            end
+            @operations = []
+        end
+
+        protected
+
+            #
+            # a class method for listing attributes that can be found 
+            # in the hash reply coming from RTM...
+            #
+            def self.milk_attr (*att_names) #:nodoc:
+
+                att_names.each do |att_name|
+                    class_eval """
+                        def #{att_name}
+                            @hsh['#{att_name}']
+                        end
+                    """
+                end
+            end
+
+            #
+            # Calls the milk() method (interacts with the RTM API).
+            #
+            def self.execute (method_name, args={})
+
+                args[:method] = "rtm.#{resource_name}.#{method_name}"
+
+                Rufus::RTM.milk args
+            end
+
+            #
+            # Returns the name of the resource as the API knows it
+            # (for example 'tasks' or 'lists').
+            #
+            def self.resource_name
+
+                self.to_s.split("::")[-1].downcase + "s"
+            end
+
+            #
+            # Simply calls the timeline() class method.
+            #
+            def timeline
+
+                MilkResource.timeline
+            end
+
+            #
+            # Returns the current timeline (fetches one if none has yet
+            # been prepared).
+            #
+            def self.timeline
+
+                @timeline ||= Rufus::RTM.get_timeline
+            end
+
+            def queue_operation (method_name, args)
+
+                @operations << [ method_name, args ]
+            end
+    end
+
+    #
+    # The RTM Task class.
+    #
+    class Task < MilkResource
+
+        def self.task_attr (*att_names) #:nodoc:
+
+            att_names.each do |att_name|
+                class_eval """
+                    def #{att_name}
+                        @hsh['task']['#{att_name}']
+                    end
+                """
+            end
+        end
+
+        attr_reader \
+            :list_id, 
+            :taskseries_id, 
+            :task_id, 
+            :tags
+
+        milk_attr \
+            :name, 
+            :modified, 
+            :participants, 
+            :url,
+            :notes,
+            :location_id,
+            :created,
+            :source
+
+        task_attr \
+            :completed, 
+            :added, 
+            :postponed, 
+            :priority, 
+            :deleted, 
+            :has_due_time, 
+            :estimate, 
+            :due
+
+        def initialize (list_id, h)
+
+            super(h)
+
+            t = h['task']
+
+            @list_id = list_id
+            @taskseries_id = h['id']
+            @task_id = t['id']
+
+            @tags = TagArray.new self, h['tags']
+        end
+
+        #
+        # Deletes the task.
+        #
+        def delete!
+
+            self.class.execute "delete", prepare_api_args
+        end
+
+        #
+        # Marks the task as completed.
+        #
+        def complete!
+
+            self.class.execute "complete", prepare_api_args
+        end
+
+        #
+        # Sets the tags for the task.
+        #
+        def tags= (tags)
+
+            tags = tags.split(",") if tags.is_a?(String)
+
+            @tags = TagArray.new(list_id, tags)
+
+            queue_operation("setTasks", tags.join(","))
+        end
+
+        def self.find (params={})
+
+            parse_tasks(execute("getList", params))
+        end
+
+        #
+        # Adds a new task (and returns it).
+        #
+        def self.add! (name, list_id=nil)
+
+            args = {}
+            args[:name] = name
+            args[:list_id] = list_id if list_id
+            args[:timeline] = Rufus::RTM.get_timeline
+
+            h = execute "add", args
+
+            parse_tasks(h)[0]
+        end
+
+        protected
+
+            def prepare_api_args
+                {
+                    :timeline => timeline,
+                    :list_id => list_id,
+                    :taskseries_id => taskseries_id,
+                    :task_id => task_id
+                }
+            end
+
+            def self.parse_tasks (o)
+
+                o = if o.is_a?(Hash)
+
+                    r = o[resource_name]
+                    o = r if r
+                    o['list']
+                end
+
+                o = [ o ] unless o.is_a?(Array)
+                    # Nota bene : not the same thing as  o = Array(o)
+
+                o.inject([]) do |r, h|
+
+                    list_id = h['id']
+                    s = h['taskseries']
+                    r += parse_taskseries(list_id, s) if s
+                    r
+                end
+            end
+
+            def self.parse_taskseries (list_id, o)
+
+                o = [ o ] unless o.is_a?(Array)
+                o.collect { |s| self.new list_id, s }
+            end
+    end
+
+    class List < MilkResource
+
+        attr \
+            :list_id
+
+        milk_attr \
+            :name, :sort_order, :smart, :archived, :deleted, :position, :locked
+
+        def initialize (h)
+
+            super
+            @list_id = h['id']
+        end
+
+        def self.find
+
+            execute("getList")[resource_name]['list'].collect do |h|
+                self.new h
+            end
+        end
+    end
+
+    #
+    # An array of tasks.
+    #
+    class TagArray #:nodoc:
+        include Enumerable
+
+        def initialize (task, tags)
+
+            @task = task
+
+            @tags = if tags.is_a?(Array)
+                tags
+            else
+                tags['tag']
+            end
+        end
+
+        def << (tag)
+
+            @tags << tag
+
+            args = prepare_api_args
+            args[:tags] = tag
+
+            @task.queue_operation "addTags", args
+        end
+
+        def delete (tag)
+
+            @tags.delete tag
+
+            args = prepare_api_args
+            args[:tags] = tag
+
+            @task.queue_operation "removeTags", args
+        end
+
+        def clear
+
+            @tags.clear
+
+            args = prepare_api_args
+            args[:tags] = ''
+
+            @task.queue_operation "setTags", args
+        end
+
+        def join (s)
+
+            @tags.join s
+        end
+
+        def each
+
+            @tags.each { |e| yield e }
+        end
+    end
+
+end
+

data/test/tasks_test.rb

@@ -0,0 +1,80 @@
+
+#
+# Testing rufus-rtm
+#
+# John Mettraux at openwfe.org
+#
+# Tue Feb  5 18:16:55 JST 2008
+#
+
+require 'test/unit'
+
+require 'rufus/rtm'
+
+include Rufus::RTM
+
+
+class TasksTest < Test::Unit::TestCase
+
+    #def setup
+    #end
+
+    #def teardown
+    #end
+
+    def test_0
+
+        taskname = "milk the cow #{Time.now.to_i}"
+
+        t0 = Task.add! taskname
+
+        assert_kind_of Task, t0
+        assert_equal taskname, t0.name
+
+        ts = Task.find
+
+        #puts "tasks : #{ts.size}"
+
+        t1 = ts.find { |t| t.task_id == t0.task_id }
+        assert_equal taskname, t1.name
+        assert_equal "", t1.tags.join(",")
+
+        ts = Task.find :filter => "status:incomplete"
+
+        #puts "incomplete tasks : #{ts.size}"
+
+        t1 = ts.find { |t| t.task_id == t0.task_id }
+        assert_equal taskname, t1.name
+
+        t1.delete!
+
+        ts = Task.find :filter => "status:incomplete"
+
+        t1 = ts.find { |t| t.task_id == t0.task_id }
+        assert_nil t1
+    end
+
+    def test_1
+
+        lists = List.find
+        assert_not_nil(lists.find { |e| e.name == "Inbox" })
+
+        work = lists.find { |e| e.name == "Work" }
+
+        taskname = "more work #{Time.now.to_i}"
+
+        t0 = Task.add! taskname, work.list_id
+
+        tasks = Task.find :list_id => work.list_id, :filer => "status:incomplete"
+
+        assert_not_nil(tasks.find { |t| t.task_id == t0.task_id })
+
+        t0.complete!
+
+        tasks = Task.find :list_id => work.list_id, :filer => "status:completed"
+        assert_not_nil(tasks.find { |t| t.task_id == t0.task_id })
+
+        t0.delete!
+    end
+end
+

data/test/test.rb

@@ -0,0 +1,4 @@
+
+require 'tasks_test'
+#require 'lists_test'
+

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: rufus-rtm
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- John Mettraux
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-02-14 00:00:00 +09:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rufus-verbs
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: jmettraux@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.txt
+files: 
+- lib/rufus
+- lib/rufus/rtm
+- lib/rufus/rtm/base.rb
+- lib/rufus/rtm/credentials.rb
+- lib/rufus/rtm/resources.rb
+- lib/rufus/rtm.rb
+- test/tasks_test.rb
+- test/test.rb
+- README.txt
+has_rdoc: true
+homepage: http://rufus.rubyforge.org/rufus-rtm
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- 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: 
+- rufus-verbs
+rubyforge_project: 
+rubygems_version: 0.9.5
+signing_key: 
+specification_version: 2
+summary: yet another RememberTheMilk wrapper
+test_files: 
+- test/test.rb