ketchup 1.0.0

data/lib/ketchup/meeting_array.rb

@@ -0,0 +1,92 @@
+# A collection of meeting for the current profile, which allows for the creation
+# of new meetings. It's really just a slightly special subclass of Array.
+# 
+class Ketchup::MeetingArray < Array
+  # Create a new array from a given api connection. This will make the request
+  # to the API to retrieve all meetings for the profile.
+  # 
+  # This isn't something you need to call yourself - just call the meetings
+  # method on your profile object instead.
+  # 
+  # @example
+  #   meetings = Ketchup::MeetingArray.new api
+  # 
+  # @param [Ketchup::API] api an API instance
+  # @see Ketchup::Profile#meetings
+  # 
+  def initialize(api)
+    @api = api
+    
+    replace @api.get('/meetings.json').collect { |hash|
+      Ketchup::Meeting.new(@api, hash)
+    }
+  end
+  
+  # Create a new unsaved meeting object. The only parameters you really need to
+  # worry about are the title and date - the rest are optional, but mentioned in
+  # the notes for the Meeting class.
+  # 
+  # Don't forget: the parameter keys need to be strings, not symbols.
+  # 
+  # @example
+  #   profile.meetings.build 'title' => 'Job Interview', 'date' => 'Tomorrow'
+  # 
+  # @param [Hash] params The meeting's details
+  # @return [Ketchup::Meeting] An unsaved meeting
+  # @see Ketchup::Meeting
+  # 
+  def build(params = {})
+    meeting = Ketchup::Meeting.new @api, params
+    push meeting
+    meeting
+  end
+  
+  # Create a new (saved) meeting object. The only parameters you really need to
+  # worry about are the title and date - the rest are optional, but mentioned in
+  # the notes for the Meeting class.
+  # 
+  # Don't forget: the parameter keys need to be strings, not symbols.
+  # 
+  # @example
+  #   profile.meetings.create 'title' => 'Job Interview', 'date' => 'Tomorrow'
+  # 
+  # @param [Hash] params The meeting's details
+  # @return [Ketchup::Meeting] A saved meeting
+  # @see Ketchup::Meeting
+  # 
+  def create(params = {})
+    meeting = build(params)
+    meeting.save
+    meeting
+  end
+  
+  # Requests a set of meetings that happen on days after today from the API.
+  # 
+  # @return [Array] An array of upcoming meetings
+  # 
+  def upcoming
+    @upcoming ||= @api.get('/meetings/upcoming.json').collect { |hash|
+      Ketchup::Meeting.new(@api, hash)
+    }
+  end
+  
+  # Requests a set of meetings that have already happened from the API.
+  # 
+  # @return [Array] An array of previous meetings
+  # 
+  def previous
+    @previous ||= @api.get('/meetings/previous.json').collect { |hash|
+      Ketchup::Meeting.new(@api, hash)
+    }
+  end
+  
+  # Requests a set of meetings that will happen today from the API.
+  # 
+  # @return [Array] An array of today's meetings
+  # 
+  def today
+    @today ||= @api.get('/meetings/todays.json').collect { |hash|
+      Ketchup::Meeting.new(@api, hash)
+    }
+  end
+end

data/lib/ketchup/note.rb

@@ -0,0 +1,73 @@
+# Represents a note for list/agenda item in a meeting. Only the content is
+# editable.
+# 
+# If you want to change the order of notes, you can do that using
+# Ketchup::NoteArray (the item's note array).
+# 
+class Ketchup::Note
+  attr_reader :shortcode_url, :updated_at, :created_at, :item_id, :position,
+    :item, :api
+  attr_accessor :content
+  
+  # Create a new note for a given item, using an existing api connection. You
+  # generally won't want to call this yourself - the better interface to create
+  # new notes is via a item's note array.
+  # 
+  # However, if you are doing some internal hacking, it's worth noting that all
+  # keys for parameters in the hash should be strings, not symbols.
+  # 
+  # @example
+  #   Ketchup::Note.new api, item, 'content' => "Motion passed."
+  # 
+  # @param [Ketchup::API] api The API connection
+  # @param [Ketchup::Item] item The item the note will belong to
+  # @param [Hash] params Any other details for the note.
+  # @see Ketchup::NoteArray#build
+  # @see Ketchup::NoteArray#create
+  # 
+  def initialize(api, item, params = {})
+    @api  = api
+    @item = item
+    
+    overwrite params
+  end
+  
+  # Indicates whether the note exists on the server yet.
+  # 
+  # @return [Boolean] True if the note does not exist on the server.
+  # 
+  def new_record?
+    shortcode_url.nil?
+  end
+  
+  # Saves the note to the server, whether it's a new note or an existing one.
+  # 
+  def save
+    if new_record?
+      overwrite @api.post("/items/#{item.shortcode_url}/notes.json",
+        'content' => content)
+    else
+      overwrite @api.put("/notes/#{shortcode_url}.json", 'content' => content)
+    end
+  end
+  
+  # Deletes the note from the server. If the note has never been saved, this
+  # method will do nothing at all.
+  # 
+  def destroy
+    return if new_record?
+    
+    @api.delete "/notes/#{shortcode_url}.json"
+  end
+  
+  private
+  
+  def overwrite(attributes = {})
+    @shortcode_url = attributes['shortcode_url']
+    @created_at    = attributes['created_at']
+    @updated_at    = attributes['updated_at']
+    @item_id       = attributes['item_id']
+    @position      = attributes['position']
+    @content       = attributes['content']
+  end
+end

data/lib/ketchup/note_array.rb

@@ -0,0 +1,85 @@
+# A collection of notes for a specific item, and allows for the creation of
+# new notes, and re-ordering of the full set of notes. It's really just a
+# slightly special subclass of Array.
+# 
+class Ketchup::NoteArray < Array
+  # Create a new NoteArray for a given api, item, and set of notes. The set
+  # of notes should be hashes taken from the API server, not actual note
+  # objects.
+  # 
+  # Like many of the methods in this library, you really don't need to call this
+  # one yourself. An item object will create its own NoteArray without any
+  # help.
+  # 
+  # @example
+  #   Ketchup::NoteArray.new api, item, [{'content' => 'foo', #... }]
+  # 
+  # @param [Ketchup::API] api A connected API instance
+  # @param [Ketchup::Item] item The item all notes are attached to.
+  # @param [Array] items An array of hashes that map to attributes of notes.
+  # 
+  def initialize(api, item, notes = [])
+    @api  = api
+    @item = item
+    
+    replace notes.collect { |hash|
+      Ketchup::Note.new(@api, @item, hash)
+    }
+  end
+  
+  # Create a new unsaved note object. The only parameter you really need to
+  # worry about is the content - the rest is all internal values, managed by the
+  # API server.
+  # 
+  # @example
+  #   item.notes.build 'content' => 'Targets are being met.'
+  # 
+  # @param [Hash] params The note's details
+  # @return [Ketchup::Note] An unsaved note
+  # 
+  def build(params = {})
+    note = Ketchup::Note.new @api, @item, params
+    push note
+    note
+  end
+  
+  # Create a new (saved) note object. The only parameter you really need to
+  # worry about is the content - the rest is all internal values, managed by the
+  # API server.
+  # 
+  # @example
+  #   item.notes.create 'content' => 'Targets are being met.'
+  # 
+  # @param [Hash] params The note's details
+  # @return [Ketchup::Note] A saved note
+  # 
+  def create(params = {})
+    note = build(params)
+    note.save
+    note
+  end
+  
+  # Re-order the notes in this array, by passing them through in the order you
+  # would prefer. This makes the change directly to the API server, as well as
+  # within this array.
+  # 
+  # Make sure you're passing in all the notes that are in this array, and no
+  # others. This can't be used as a shortcut to add new notes.
+  # 
+  # @example
+  #   item.notes.reorder second_note, fourth_note, first_note, third_note
+  # 
+  # @param [Ketchup::Note] notes The notes of the array, in a new order.
+  # @raise ArgumentError if you don't provide the exact same set of notes.
+  # 
+  def reorder(*notes)
+    if notes.collect(&:shortcode_url).sort != collect(&:shortcode_url).sort
+      raise ArgumentError, 'cannot sort a different set of notes'
+    end
+    
+    @api.put "/items/#{@item.shortcode_url}/sort_notes.json", {
+      'notes' => notes.collect(&:shortcode_url)
+    }
+    replace notes
+  end
+end

data/lib/ketchup/profile.rb

@@ -0,0 +1,125 @@
+# A user profile, which provides an interface to the user's meetings and
+# projects. You can either create it yourself, using an email and password, or
+# through the Ketchup module's authenticate method - they're exactly the same.
+# 
+# This is the central object for all of your operations through the Ketchup API.
+# You don't need to create or manually request any other objects, but instead,
+# access them all through the collections on this class.
+# 
+# @example
+#   profile = Ketchup::Profile.load 'foo@bar.com', 'secret'
+#   profile.meetings.each do |meeting|
+#     puts meeting.title
+#   end
+# 
+class Ketchup::Profile
+  attr_reader :api, :single_access_token
+  attr_accessor :name, :timezone, :email
+  
+  # Set up a connection to an existing profile.
+  # 
+  # @example
+  #   profile = Ketchup::Profile.load 'foo@bar.com', 'secret'
+  # 
+  # @param [String] email The user's email address
+  # @param [String] password The user's passwords
+  # @return [Ketchup::Profile] A new profile instance
+  # @raise [Ketchup::AccessDenied] when the email or password is incorrect
+  # 
+  def self.load(email, password)
+    Ketchup::Profile.new Ketchup::API.new(email, password)
+  end
+  
+  # Create a completely new user account. You (currently) don't need to have
+  # any existing authentication to the server to call this method - just specify
+  # the new user's email address and password.
+  # 
+  # Other extra parameters are the name and timezone of the user account, but
+  # these are optional.
+  # 
+  # Please note: This method doesn't return a new profile, just sets the account
+  # up.
+  # 
+  # @example
+  #   Ketchup::Profile.create 'bar@foo.com', 'swordfish', 'name' => 'Bruce'
+  # 
+  # @param [String] email The email address of the new user.
+  # @param [String] password The chosen password of the new user.
+  # @param [Hash] options Other optional user details, such as the name and
+  #   timezone.
+  # 
+  def self.create(email, password, options = {})
+    Ketchup::API.post '/users.json', :body => options.merge(
+      'email'     => email,
+      'password'  => password
+    )
+  end
+  
+  # Set up a new profile object with an active API connection.
+  # 
+  # @param [Ketchup::API] api An authenticated API object
+  # 
+  def initialize(api)
+    @api = api
+    
+    overwrite @api.get('/profile.json')
+  end
+  
+  # Reset the meeting and project objects of this profile, allowing them to
+  # be reloaded from the server when next requested.
+  # 
+  def reload!
+    @meetings = nil
+    @projects = nil
+  end
+  
+  # Get an array of meetings attached to this profile. Note that the returned
+  # object is actually an instance of Ketchup::MeetingArray, which has helper
+  # methods for creating and re-ordering meetings.
+  # 
+  # @return [Ketchup::MeetingArray] The collection of meetings.
+  # 
+  def meetings
+    @meetings ||= Ketchup::MeetingArray.new api
+  end
+  
+  # Get an array of projects attached to this profile. This is not a special
+  # project array, as you can only edit projects, not create them. They are
+  # created explicitly from meetings.
+  # 
+  # @return [Array] The collection of projects.
+  # 
+  def projects
+    @projects ||= api.get('/projects.json').collect { |hash|
+      Ketchup::Project.new(api, hash)
+    }
+  end
+  
+  # Saves any profile changes to the name, timezone and/or email. This does not
+  # save any changes made to underlying meetings and projects.
+  # 
+  def save
+    overwrite @api.put('/profile.json',
+      'name'      => name,
+      'timezone'  => timezone,
+      'email'     => email
+    )
+  end
+  
+  # Change the password for this profile account.
+  # 
+  # @param [String] password The new password for the account.
+  # 
+  def change_password(password)
+    @api.put '/profile.json', 'password' => password
+  end
+  
+  private
+  
+  def overwrite(attributes = {})
+    @single_access_token = attributes['single_access_token']
+    @name                = attributes['name']
+    @timezone            = attributes['timezone']
+    @email               = attributes['email']
+  end
+end

data/lib/ketchup/project.rb

@@ -0,0 +1,51 @@
+# Represents a project, which meetings can be grouped under.
+# 
+# Projects cannot be created manually - just create meetings with project names,
+# and the corresponding projects will be created if they don't already exist.
+# 
+# You can, however, change the name of a project.
+# 
+class Ketchup::Project
+  attr_accessor :name
+  attr_reader :shortcode_url, :created_at, :updated_at
+  
+  # Set up a new Project object - although there's not much point calling this
+  # yourself, as it's only useful when populating with data from the server.
+  # 
+  # @param [Ketchup::API] api An established API connection.
+  # @param [Hash] params The project details
+  # 
+  def initialize(api, params = {})
+    @api = api
+    
+    overwrite params
+  end
+  
+  # Saves any changes to the project's name.
+  # 
+  def save
+    overwrite @api.put("/projects/#{shortcode_url}.json", 'name' => name)
+  end
+  
+  # Gets all the meetings tied to this particular project. This is not a special
+  # array, so it's best to create new meetings for a given project via the
+  # profile's meetings collection object instead.
+  # 
+  # @return [Array] Meetings associated with this project.
+  # 
+  def meetings
+    @meetings ||= @api.get("/projects/#{shortcode_url}/meetings.json").
+      collect { |hash|
+        Ketchup::Meeting.new @api, hash
+      }
+  end
+  
+  private
+  
+  def overwrite(attributes = {})
+    @shortcode_url = attributes['shortcode_url']
+    @created_at    = attributes['created_at']
+    @updated_at    = attributes['updated_at']
+    @name          = attributes['name']
+  end
+end

data/spec/ketchup/api_spec.rb

@@ -0,0 +1,120 @@
+require 'spec/spec_helper'
+
+describe Ketchup::API do
+  describe '#initialize' do
+    it "should return a new API object on success" do
+      FakeWeb.register_uri :get, /#{KetchupAPI}\/profile.json$/,
+        :body => '{"single_access_token":"foo"}'
+      
+      Ketchup::API.new('user@domain.com', 'secret').should be_a(Ketchup::API)
+    end
+    
+    it "should set the access token on success" do
+      stub_initial_api_request
+      
+      Ketchup::API.new('user@domain.com', 'secret').
+        access_token.should == 'y3chHxh9Qk1Drkg1j0Bw'
+    end
+    
+    it "should raise an exception on failure" do
+      FakeWeb.register_uri :get, /#{KetchupAPI}\/profile.json$/,
+        :body => 'Access Denied'
+      
+      lambda {
+        Ketchup::API.new('user@domain.com', 'secret')
+      }.should raise_error(Ketchup::AccessDenied)
+    end
+  end
+  
+  describe '#get' do
+    before :each do
+      stub_initial_api_request
+      @api = Ketchup::API.new('user@domain.com', 'secret')
+    end
+    
+    it "should include the access token" do
+      Ketchup::API.should_receive(:get) do |path, options|
+        options[:query][:u].should == 'y3chHxh9Qk1Drkg1j0Bw'
+      end
+      
+      @api.get '/'
+    end
+    
+    it "should send through any provided options" do
+      Ketchup::API.should_receive(:get) do |path, options|
+        options[:query][:page].should == 4
+      end
+      
+      @api.get '/', :page => 4
+    end
+  end
+  
+  describe '#post' do
+    before :each do
+      stub_initial_api_request
+      @api = Ketchup::API.new('user@domain.com', 'secret')
+    end
+    
+    it "should include the access token" do
+      Ketchup::API.should_receive(:post) do |path, options|
+        options[:body][:u].should == 'y3chHxh9Qk1Drkg1j0Bw'
+      end
+      
+      @api.post '/'
+    end
+    
+    it "should send through any provided options" do
+      Ketchup::API.should_receive(:post) do |path, options|
+        options[:body][:page].should == 4
+      end
+      
+      @api.post '/', :page => 4
+    end
+  end
+  
+  describe '#put' do
+    before :each do
+      stub_initial_api_request
+      @api = Ketchup::API.new('user@domain.com', 'secret')
+    end
+    
+    it "should include the access token" do
+      Ketchup::API.should_receive(:put) do |path, options|
+        options[:body][:u].should == 'y3chHxh9Qk1Drkg1j0Bw'
+      end
+      
+      @api.put '/'
+    end
+    
+    it "should send through any provided options" do
+      Ketchup::API.should_receive(:put) do |path, options|
+        options[:body][:page].should == 4
+      end
+      
+      @api.put '/', :page => 4
+    end
+  end
+  
+  describe '#delete' do
+    before :each do
+      stub_initial_api_request
+      @api = Ketchup::API.new('user@domain.com', 'secret')
+    end
+    
+    it "should include the access token" do
+      Ketchup::API.should_receive(:delete) do |path, options|
+        options[:body][:u].should == 'y3chHxh9Qk1Drkg1j0Bw'
+      end
+      
+      @api.delete '/'
+    end
+    
+    it "should send through any provided options" do
+      Ketchup::API.should_receive(:delete) do |path, options|
+        options[:body][:page].should == 4
+      end
+      
+      @api.delete '/', :page => 4
+    end
+  end
+end