ketchup 1.0.0

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Paul Campbell, Pat Allan
+
+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.textile

@@ -0,0 +1,123 @@
+h1. Ketchup
+
+This is the official Ruby interface to the API for  "Ketchup":http://www.useketchup.com: A place for all your meeting notes.
+
+h2. Installation
+
+<pre><code>gem install ketchup</code></pre>
+
+h2. Usage
+
+Everything in Ketchup comes down to the user you're logged in as, and this library reflects that - you create a new connection and manage everything through a profile object:
+
+<pre><code>profile = Ketchup.authenticate('user@domain.com', 'password')</code></pre>
+
+None of the usage is particularly complex, but if you're confused with any of the notes below, either read "the documentation":http://rdoc.info/projects/hypertiny/ketchup or "the sauce":http://github.com/hypertiny/ketchup.
+
+h3. Meetings
+
+A profile object provides access to all your meetings simply enough:
+
+<pre><code>profile.meetings.each do |meeting|
+  puts meeting.title
+end
+meeting = profile.meetings.create 'title' => 'Important Discussion'
+meeting.title = 'Nothing Important'
+meeting.save</code></pre>
+
+All of a meeting's details are accesible through these meeting objects.
+
+<pre><code>meeting.location #=> 'Abbey Road'
+meeting.attendees #=> 'John, Paul, George and Ringo'</code></pre>
+
+Meeting dates are parsed from natural language, just like in Ketchup's web interface.
+
+<pre><code>meeting.date = 'Tomorrow at 4pm'</code></pre>
+
+You can also filter meetings by the same categories as the web interface:
+
+<pre><code>profile.meetings.today
+profile.meetings.upcoming
+profile.meetings.previous</code></pre>
+
+h3. Items
+
+Agenda items can be manipulated for each meeting. They're pretty slim objects through - the only editable attribute is their content.
+
+<pre><code>meeting.items.each do |item|
+  puts item.content
+end
+item = meeting.items.build 'content' => 'What are we talking about?'
+item.content = 'Minutes from Last Meeting'
+item.save</code></pre>
+
+You can also re-order a full set of items for a given meeting:
+
+<pre><code>meeting.items.reorder item_b, item_c, item_a</code></pre>
+
+h3. Notes
+
+Notes are the bullet points under each item, and behave in much the same way. Also, the only piece of information that they have of any interest is the content attribute.
+
+<pre><code>item.notes.each do |note|
+  puts note.content
+end
+note = item.notes.create 'content' => 'Are we done yet?'
+note.content = 'Next meeting will be shorter'
+note.save</code></pre>
+
+Just like with items, you can re-order a full set of notes:
+
+<pre><code>item.notes.reorder note_b, note_c, note_a</code></pre>
+
+h3. Projects
+
+Projects are implicitly created through meetings:
+
+<pre><code>profile.meetings.create(
+  'title' => 'Monday',
+  'project_name' => 'Stand ups'
+)</code></pre>
+
+You can access these projects through the profile object, and the meetings that are in each of them:
+
+<pre><code>profile.projects.each do |project|
+  puts project.name
+end
+project = profiles.project.first
+project.meetings.each do |meeting|
+  puts meeting.title
+end</code></pre>
+
+You can also change the names of projects through these objects:
+
+<pre><code>project.name = 'Sit downs'
+project.save</code></pre>
+
+h3. User Accounts
+
+Your profile object allows you to change the email, name and timezone associated with that account:
+
+<pre><code>profile.email = 'baz@foo.com'
+profile.name = 'Bazza'
+profile.timezone = 'Melbourne'
+profile.save</code></pre>
+
+You can also change the password, if you so desire:
+
+<pre><code>profile.change_password '12345'</code></pre>
+
+And there's also the ability to create completely new accounts:
+
+<pre><code>Ketchup::Profile.create 'who@first.base.com', 'secret',
+  'name' => 'Who', 'timezone' => 'Dublin'</code></pre>
+
+The name and timezone arguments are optional, though - and please note that you don't get a profile object back from that request, but will need to authenticate like normal to get access to that account's meetings.
+
+h2. Contribution
+
+Fork and patch as you see fit - and please send pull requests if you think it's useful for others. Don't forget to write specs and features first, and don't mess with the version numbers please (or at least: only do so in a different branch).
+
+h2. Copyright
+
+Copyright (c) 2010 "Pat Allan":http://freelancing-gods.com and "Paul Campbell":http://pabcas.com/, released under an open licence.

data/lib/ketchup.rb

@@ -0,0 +1,36 @@
+# Ketchup Ruby API
+# 
+# @author Pat Allan
+# @see http://useketchup.com
+# 
+module Ketchup
+  # An exception thrown when invalid authentication details are provided.
+  # 
+  class AccessDenied < StandardError
+  end
+  
+  # Creates a new profile authenticated against the Ketchup API. This is the
+  # recommended method to get access to an account's meetings, notes and items.
+  # 
+  # @example
+  #   profile = Ketchup.authenticate '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.authenticate(email, password)
+    Ketchup::Profile.load(email, password)
+  end
+end
+
+require 'ketchup/api'
+require 'ketchup/item'
+require 'ketchup/item_array'
+require 'ketchup/meeting'
+require 'ketchup/meeting_array'
+require 'ketchup/note'
+require 'ketchup/note_array'
+require 'ketchup/profile'
+require 'ketchup/project'

data/lib/ketchup/api.rb

@@ -0,0 +1,80 @@
+require 'httparty'
+
+# The direct interface with Ketchup's RESTful API. You should generally not have
+# any need to use this class yourself, unless you're playing around with the
+# internals. That said, it's a simple class - with get, post, put and delete
+# instance methods for matching HTTP requests, that automatically include the
+# access token.
+# 
+# For pure access to the API, without any implicit authentication, use the class
+# level methods, which are provided by the mixed-in HTTParty module.
+# 
+# @see http://rdoc.info/projects/jnunemaker/httparty HTTParty
+# 
+class Ketchup::API
+  include HTTParty
+  base_uri 'https://useketchup.com/api/v1'
+  
+  attr_reader :access_token
+  
+  # Creates a new API instance for the given profile, as determined by the email
+  # and password. This API object can then be used by all other objects to
+  # interact with the API without having to re-authenticate.
+  # 
+  # @param [String] email The user's email address
+  # @param [String] password The user's password
+  # @raise [Ketchup::AccessDenied] if the email or password are incorrect
+  # 
+  def initialize(email, password)
+    response = self.class.get '/profile.json', :basic_auth => {
+      :username => email,
+      :password => password
+    }
+    
+    if response == 'Access Denied'
+      raise Ketchup::AccessDenied
+    else
+      @access_token = response['single_access_token']
+    end
+  end
+  
+  # Execute a GET request to the API server using the stored access token.
+  # 
+  # @param [String] path The URL path
+  # @param [Hash] data Parameters for the request
+  # @return The web response
+  # 
+  def get(path, data = {})
+    self.class.get path, :query => data.merge(:u => access_token)
+  end
+  
+  # Execute a POST request to the API server using the stored access token.
+  # 
+  # @param [String] path The URL path
+  # @param [Hash] data Parameters for the request
+  # @return The web response
+  # 
+  def post(path, data = {})
+    self.class.post path, :body => data.merge(:u => access_token)
+  end
+  
+  # Execute a PUT request to the API server using the stored access token.
+  # 
+  # @param [String] path The URL path
+  # @param [Hash] data Parameters for the request
+  # @return The web response
+  # 
+  def put(path, data = {})
+    self.class.put path, :body => data.merge(:u => access_token)
+  end
+  
+  # Execute a DELETE request to the API server using the stored access token.
+  # 
+  # @param [String] path The URL path
+  # @param [Hash] data Parameters for the request
+  # @return The web response
+  #
+  def delete(path, data = {})
+    self.class.delete path, :body => data.merge(:u => access_token)
+  end
+end

data/lib/ketchup/item.rb

@@ -0,0 +1,75 @@
+# Represents a list/agenda item in a meeting. Only the content is editable.
+# 
+# If you want to change the order of items, you can do that using
+# Ketchup::ItemArray (the meeting's item array).
+# 
+class Ketchup::Item
+  attr_reader :shortcode_url, :updated_at, :created_at, :meeting_id, :notes,
+    :position, :meeting, :api
+  attr_accessor :content
+  
+  # Create a new item for a given meeting, using an existing api connection. You
+  # generally won't want to call this yourself - the better interface to create
+  # new items is via a meeting's item 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::Item.new api, meeting, 'content' => "Treasurer's Report"
+  # 
+  # @param [Ketchup::API] api The API connection
+  # @param [Ketchup::Meeting] meeting The meeting the item will belong to
+  # @param [Hash] params Any other details for the item.
+  # @see Ketchup::ItemArray#build
+  # @see Ketchup::ItemArray#create
+  # 
+  def initialize(api, meeting, params = {})
+    @api     = api
+    @meeting = meeting
+    
+    overwrite params
+    
+    @notes = Ketchup::NoteArray.new @api, self, (params['notes'] || [])
+  end
+  
+  # Indicates whether the item exists on the server yet.
+  # 
+  # @return [Boolean] True if the item does not exist on the server.
+  # 
+  def new_record?
+    shortcode_url.nil?
+  end
+  
+  # Saves the item to the server, whether it's a new item or an existing one.
+  # This does not save underlying notes.
+  # 
+  def save
+    if new_record?
+      overwrite @api.post("/meetings/#{meeting.shortcode_url}/items.json",
+        'content' => content)
+    else
+      overwrite @api.put("/items/#{shortcode_url}.json", 'content' => content)
+    end
+  end
+  
+  # Deletes the item from the server. If the item has never been saved, this
+  # method will do nothing at all.
+  # 
+  def destroy
+    return if new_record?
+    
+    @api.delete "/items/#{shortcode_url}.json"
+  end
+  
+  private
+  
+  def overwrite(attributes = {})
+    @shortcode_url = attributes['shortcode_url']
+    @created_at    = attributes['created_at']
+    @updated_at    = attributes['updated_at']
+    @meeting_id    = attributes['meeting_id']
+    @position      = attributes['position']
+    @content       = attributes['content']
+  end
+end

data/lib/ketchup/item_array.rb

@@ -0,0 +1,85 @@
+# A collection of items for a specific meeting, and allows for the creation of
+# new items, and re-ordering of the full set of items. It's really just a
+# slightly special subclass of Array.
+# 
+class Ketchup::ItemArray < Array
+  # Create a new ItemArray for a given api, meeting, and set of items. The set
+  # of items should be hashes taken from the API server, not actual item
+  # objects.
+  # 
+  # Like many of the methods in this library, you really don't need to call this
+  # one yourself. A meeting object will create its own ItemArray without any
+  # help.
+  # 
+  # @example
+  #   Ketchup::ItemArray.new api, meeting, [{'content' => 'foo', #... }]
+  # 
+  # @param [Ketchup::API] api A connected API instance
+  # @param [Ketchup::Meeting] meeting The meeting all items are attached to.
+  # @param [Array] items An array of hashes that map to attributes of items.
+  # 
+  def initialize(api, meeting, items = [])
+    @api     = api
+    @meeting = meeting
+    
+    replace items.collect { |hash|
+      Ketchup::Item.new(@api, @meeting, hash)
+    }
+  end
+  
+  # Create a new unsaved item 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
+  #   meeting.items.build 'content' => 'Petty Cash'
+  # 
+  # @param [Hash] params The item's details
+  # @return [Ketchup::Item] An unsaved item
+  # 
+  def build(params = {})
+    item = Ketchup::Item.new @api, @meeting, params
+    push item
+    item
+  end
+  
+  # Create a new (saved) item 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
+  #   meeting.items.create 'content' => 'Petty Cash'
+  # 
+  # @param [Hash] params The item's details
+  # @return [Ketchup::Item] An item, already saved to the server.
+  # 
+  def create(params = {})
+    item = build(params)
+    item.save
+    item
+  end
+  
+  # Re-order the items 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 items that are in this array, and no
+  # others. This can't be used as a shortcut to add new items.
+  # 
+  # @example
+  #   meeting.items.reorder second_item, fourth_item, first_item, third_item
+  # 
+  # @param [Ketchup::Item] items The items of the array, in a new order.
+  # @raise ArgumentError if you don't provide the exact same set of items.
+  # 
+  def reorder(*items)
+    if items.collect(&:shortcode_url).sort != collect(&:shortcode_url).sort
+      raise ArgumentError, 'cannot sort a different set of items'
+    end
+    
+    @api.put "/meetings/#{@meeting.shortcode_url}/sort_items.json", {
+      'items' => items.collect(&:shortcode_url)
+    }
+    replace items
+  end
+end

data/lib/ketchup/meeting.rb

@@ -0,0 +1,96 @@
+# A Meeting - the cornerstone of Ketchup. This object tracks the meeting's
+# key details: the title, whether it's public or not, the date, attendees, a
+# description, location, project name, and the agenda items.
+# 
+# While you won't want to create a new meeting from this class itself - it's far
+# easier to do so using a profile's meetings array - this is a good reference
+# point for changing and deleting meetings.
+# 
+# @see Ketchup::MeetingArray#build
+# @see Ketchup::MeetingArray#create
+# 
+class Ketchup::Meeting
+  attr_reader :shortcode_url, :public_url, :user_id, :created_at, :updated_at,
+    :project_id, :items, :api
+  
+  WriteableAttributes = [:title, :quick, :public, :date, :attendees,
+    :description, :project_name, :location]
+  attr_accessor *WriteableAttributes
+  
+  # Create a new meeting, using an active API object. Keep in mind that all
+  # parameter keys must be provided as strings. The key attributes are the title
+  # and the date (the rest are optional).
+  # 
+  # The date can be defined using natural language, and the server will figure
+  # out what you mean (just like when you create a meeting on the website).
+  # 
+  # @example
+  #   Ketchup::Meeting.new api,
+  #     'title'        => 'White Album Cover Brainstorming',
+  #     'date'         => 'Tomorrow at 4pm',
+  #     'attendees'    => 'John, Paul, George and Ringo',
+  #     'location'     => 'Abbey Road',
+  #     'project_name' => 'New Releases'
+  # 
+  # @param [Ketchup::API] api A connected API instance
+  # @param [Hash] params The attributes for the meeting.
+  # 
+  def initialize(api, params = {})
+    @api = api
+    
+    overwrite params
+    
+    @items = Ketchup::ItemArray.new @api, self, (params['items'] || [])
+  end
+  
+  # Saves the meeting to the server, whether it's a new meeting or an existing
+  # one. This does not save underlying items or notes.
+  # 
+  def save
+    if new_record?
+      overwrite @api.post("/meetings.json", writeable_attributes)
+    else
+      overwrite @api.put("/meetings/#{shortcode_url}.json",
+        writeable_attributes)
+    end
+  end
+  
+  # Deletes the meeting from the server. If the meeting has never been saved,
+  # this method will do nothing at all.
+  # 
+  def destroy
+    return if new_record?
+    
+    @api.delete "/meetings/#{shortcode_url}.json"
+  end
+  
+  # Indicates whether the meeting exists on the server yet.
+  # 
+  # @return [Boolean] True if the meeting does not exist on the server.
+  # 
+  def new_record?
+    shortcode_url.nil?
+  end
+  
+  private
+  
+  def overwrite(attributes)
+    @shortcode_url = attributes['shortcode_url']
+    @public_url    = attributes['public_url']
+    @user_id       = attributes['user_id']
+    @created_at    = attributes['created_at']
+    @updated_at    = attributes['updated_at']
+    @project_id    = attributes['project_id']
+    
+    WriteableAttributes.each do |attrib|
+      instance_variable_set "@#{attrib}".to_sym, attributes[attrib.to_s]
+    end
+  end
+  
+  def writeable_attributes
+    WriteableAttributes.inject({}) do |hash, attrib|
+      hash[attrib.to_s] = instance_variable_get "@#{attrib}".to_sym
+      hash
+    end
+  end
+end