broach 0.1

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2009 Manfred Stienstra, Fingertips <manfred@fngtps.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.

data/lib/broach.rb

@@ -0,0 +1,92 @@
+require 'rubygems' rescue nil
+require 'rest'
+require 'json'
+
+require 'broach/exceptions'
+
+# === Settings
+#
+# Before you can do anything else you will need to provide credentials first, this includes the account name and
+# authentication token. The +use_ssl+ parameter is optional and defaults to false.
+#
+#   Broach.settings = { 'account' => 'example', 'token' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'use_ssl' => true }
+#
+# You can find the token for any Campfire account by logging into the web interface and clicking 'My Info' in the top-right
+# corner.
+#
+# === Say someting in a room real quick
+#
+# If you just need to say something real quick in a room, you can use the speak class method.
+#
+#  Broach.speak("Office", "Manfred just deployed a new version of the weblog (http://www.fngtps.com)")
+#
+# Note that this fetches a list of all rooms so it can figure out the ID for the room you specified.
+#
+# === Post a lot of stuff to a room
+#
+# If you want to post multiple lines to one room, it's a good idea to create a Room instance.
+#
+#   room = Broach.rooms.find { |room| room.name == 'Office' }
+#   room.speak('Manfred just commited to the `weblog' repository')
+#   room.speak("commit 4578530113cb87e1e7dbd696c376181e97d429d7\n" +
+#     "Author: Manfred Stienstra <manfred@fngtps.com>\n" +
+#     "Date:   Wed Dec 16 14:03:33 2009 +0100\n\n" +
+#     "  Add a speak method to Broach to quickly say something in a room.", :type => :paste)
+module Broach
+  autoload :Attributes, 'broach/attributes'
+  autoload :Session,    'broach/session'
+  autoload :User,       'broach/user'
+  autoload :Room,       'broach/room'
+  
+  # Returns the current Broach settings
+  def self.settings
+    @settings
+  end
+  
+  # Sets the broach settings
+  def self.settings=(settings)
+    @settings = settings
+    @session  = nil
+  end
+  
+  # Returns a session object with the current settings
+  def self.session
+    @session ||= Broach::Session.new(settings)
+  end
+  
+  # Returns a User instance for the currently authenticated user
+  def self.me
+    Broach::User.me
+  end
+  
+  # Returns a Room instance for all rooms accesible to the currently authenticated user
+  def self.rooms
+    Broach::Room.all
+  end
+  
+  # Send a message to a room with a certain name.
+  #
+  # Note that you should only use this method if you're sending just one message. It fetches
+  # all rooms before sending the message to find the room with the name you're specifying.
+  #
+  # If you need to send multiple messages to the same room you should instantiate a room first.
+  # 
+  # ==== Options
+  #
+  # +room+
+  #   The name of the room, ie. 'Office'
+  # +content+
+  #   The content of the message, see Broach::Room#speak for more information.
+  # +options+
+  #   Options for the message, see Broach::Room#speak for more information.
+  #
+  # ==== Examples
+  #
+  #   Broach.speak('Office', 'Manfred just deployed a new version of the weblog (http://www.fngtps.com)')
+  #   Broach.speak('Office', 'crickets', :type => :sound)
+  def self.speak(room_name, content, options={})
+    if room = rooms.find { |room| room.name == room_name }
+      room.speak(content, options)
+    end
+  end
+end

data/lib/broach/attributes.rb

@@ -0,0 +1,18 @@
+module Broach
+  # Makes a very simple attribute driven model from the class when included.
+  module Attributes
+    def initialize(attributes)
+      @attributes = attributes
+    end
+    
+    def id; @attributes['id']; end
+    
+    def method_missing(method, *arguments, &block)
+      if value = @attributes[method.to_s]
+        value
+      else
+        super
+      end
+    end
+  end
+end

data/lib/broach/exceptions.rb

@@ -0,0 +1,12 @@
+module Broach
+  # Raised when something unexpected happened during communication with Campfire
+  class APIError < RuntimeError
+    attr_accessor :response
+  end
+  
+  # Raised when the credentials were incorrect
+  class AuthenticationError < APIError; end
+  
+  # Raised when the credentials were correct, but the resource could not be accessed
+  class AuthorizationError < APIError; end
+end

data/lib/broach/room.rb

@@ -0,0 +1,51 @@
+module Broach
+  # Represents a chat room on the server
+  class Room
+    TYPE_MAP = {
+      :text  => 'TextMessage',
+      :paste => 'PasteMessage',
+      :sound => 'SoundMessage'
+    }
+    
+    include Broach::Attributes
+    
+    # Send a message to the room
+    #
+    # ==== Parameters and options
+    #
+    # [+content+]
+    #   Content to send. For a normal text message this is the content of the message. For a paste
+    #   it's the content of the paste. For a sound it's the name of the sound.
+    #
+    # [<tt>:type</tt>]
+    #   The type of message to send, this is :text by default for normal text messages.
+    #   You can also use :paste and :sound. Valid sound messages are 'rimshot', 'crickets',
+    #   or 'trombone'.
+    #
+    # ==== Examples
+    #
+    #   room = Broach::Room.all.first
+    #   room.speak("Let's review these figures.")
+    #   room.speak("<code>$stderr.write('-')</code>", :type => :paste)
+    #   room.speak("rimshot", :type => :sound)
+    def speak(content, options={})
+      options[:type] ||= :text
+      Broach.session.post("room/#{id}/speak", 'message' => {
+        'type' => TYPE_MAP[options[:type]],
+        'body' => content
+      })['message']
+    end
+    
+    # Returns a Room instance for all rooms accessible to the authenticated user
+    def self.all
+      Broach.session.get('rooms')['rooms'].map do |attributes|
+        Broach::Room.new(attributes)
+      end
+    end
+    
+    # Returns a Room instance for a room with a specific ID
+    def self.find(id)
+      new(Broach.session.get("room/#{id.to_i}")['room'])
+    end
+  end
+end

data/lib/broach/session.rb

@@ -0,0 +1,73 @@
+module Broach
+  # Represents a session with Campfire
+  class Session
+    include Broach::Attributes
+    
+    # Returns true when the connection should use SSL and false otherwise.
+    def use_ssl?
+      @attributes['use_ssl'] || false
+    end
+    
+    # Returns either http or https depending on whether we should use SSL or not.
+    def scheme
+      use_ssl? ? 'https' : 'http'
+    end
+    
+    # Returns the full URL for a certain path
+    #
+    #   session.url_for('rooms') #=> "http://example.campfirenow.com/rooms"
+    def url_for(path)
+      ["#{scheme}:/", "#{account}.campfirenow.com", path].join('/')
+    end
+    
+    # Returns the headers to send for a specific HTTP method
+    #
+    #   session.headers_for(:get) #=> { 'Accept' => 'application/json' }
+    def headers_for(method)
+      headers = { 'Accept' => 'application/json', 'User-Agent' => 'Broach' }
+      headers['Content-type'] = 'application/json' if method == :post
+      headers
+    end
+    
+    # Returns the credentials to authenticate the current user
+    def credentials
+      { :username => token, :password => 'x' }
+    end
+    
+    # Gets a resource with a certain path on the server. When the GET is succesful
+    # the parsed body is returned, otherwise an exception is raised.
+    def get(path)
+      response = REST.get(url_for(path), headers_for(:get), credentials)
+      if response.ok?
+        return JSON.parse(response.body)
+      else
+        handle_response(:get, path, response)
+      end
+    end
+    
+    # Posts a resource to a certain path on the server. When the POST is successful
+    # the parsed body is returned, otherwise an exception is raised.
+    def post(path, payload)
+      response = REST.post(url_for(path), JSON.dump(payload), headers_for(:post), credentials)
+      if response.created?
+        return JSON.parse(response.body)
+      else
+        handle_response(:post, path, response)
+      end
+    end
+    
+    private
+    
+    def handle_response(method, path, response)
+      exception = if response.unauthorized?
+        Broach::AuthenticationError.new("Couldn't authenticate with the supplied credentials for the account `#{account}'")
+      elsif response.forbidden?
+        Broach::AuthorizationError.new("Couldn't #{method.to_s.upcase} the resource `#{path}' on the account `#{account}'")
+      else
+        Broach::APIError.new("Response from the server was unexpected (#{response.status_code})")
+      end
+      exception.response = response
+      raise exception
+    end
+  end
+end

data/lib/broach/user.rb

@@ -0,0 +1,16 @@
+module Broach
+  # Represents a user on the server
+  class User
+    include Broach::Attributes
+    
+    # Returns a User instance for the currently authenticated user
+    def self.me
+      new(Broach.session.get('users/me')['user'])
+    end
+    
+    # Returns a User instance for a user with a specific ID
+    def self.find(id)
+      new(Broach.session.get("users/#{id.to_i}")['user'])
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+name: broach
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- Manfred Stienstra
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-16 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: "    Ruby implementation of 37signal's Campfire API.\n"
+email: manfred@fngtps.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+files: 
+- LICENSE
+- lib/broach/attributes.rb
+- lib/broach/exceptions.rb
+- lib/broach/room.rb
+- lib/broach/session.rb
+- lib/broach/user.rb
+- lib/broach.rb
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=utf-8
+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: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Ruby implementation of 37signal's Campfire API.
+test_files: []
+