flareshow 0.3.1

data/.gitignore

@@ -0,0 +1 @@
+*.gem

data/Flareshow.gemspec

@@ -0,0 +1,82 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{flareshow}
+  s.version = "0.3.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Will Bailey"]
+  s.date = %q{2010-01-11}
+  s.description = %q{a ruby gem for interacting with the shareflow collaboration service by Zenbe}
+  s.email = %q{will.bailey@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.md"
+  ]
+  s.files = [
+    ".gitignore",
+     "Flareshow.gemspec",
+     "LICENSE",
+     "README.md",
+     "Rakefile",
+     "TODO",
+     "VERSION",
+     "lib/cache.rb",
+     "lib/comment.rb",
+     "lib/exceptions.rb",
+     "lib/file_attachment.rb",
+     "lib/flareshow.rb",
+     "lib/flow.rb",
+     "lib/http_encoding_helper.rb",
+     "lib/invitation.rb",
+     "lib/membership.rb",
+     "lib/mime_parts.rb",
+     "lib/post.rb",
+     "lib/resource.rb",
+     "lib/searchable.rb",
+     "lib/server.rb",
+     "lib/service.rb",
+     "lib/user.rb",
+     "lib/util.rb",
+     "test/flareshow_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/willbailey/flareshow}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{flareshow}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{a ruby gem for interacting with the shareflow collaboration service}
+  s.test_files = [
+    "test/flareshow_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<thoughtbot-shoulda>, ["> 0"])
+      s.add_runtime_dependency(%q<json>, ["> 0"])
+      s.add_runtime_dependency(%q<curb>, ["> 0"])
+      s.add_runtime_dependency(%q<facets>, ["> 0"])
+      s.add_runtime_dependency(%q<uuid>, ["> 0"])
+    else
+      s.add_dependency(%q<thoughtbot-shoulda>, ["> 0"])
+      s.add_dependency(%q<json>, ["> 0"])
+      s.add_dependency(%q<curb>, ["> 0"])
+      s.add_dependency(%q<facets>, ["> 0"])
+      s.add_dependency(%q<uuid>, ["> 0"])
+    end
+  else
+    s.add_dependency(%q<thoughtbot-shoulda>, ["> 0"])
+    s.add_dependency(%q<json>, ["> 0"])
+    s.add_dependency(%q<curb>, ["> 0"])
+    s.add_dependency(%q<facets>, ["> 0"])
+    s.add_dependency(%q<uuid>, ["> 0"])
+  end
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Will Bailey
+
+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.md

@@ -0,0 +1,122 @@
+       ___ ___                                 __                            
+     /'___\\_ \                               /\ \                           
+    /\ \__///\ \      __     _ __   __    ____\ \ \___     ___   __  __  __  
+    \ \ ,__\\ \ \   /'__`\  /\`'__\'__`\ /',__\\ \  _ `\  / __`\/\ \/\ \/\ \ 
+     \ \ \_/ \_\ \_/\ \L\.\_\ \ \/\  __//\__, `\\ \ \ \ \/\ \L\ \ \ \_/ \_/ \
+      \ \_\  /\____\ \__/.\_\\ \_\ \____\/\____/ \ \_\ \_\ \____/\ \___x___/'
+       \/_/  \/____/\/__/\/_/ \/_/\/____/\/___/   \/_/\/_/\/___/  \/__//__/
+    
+        ~ a ruby wrapper for the Zenbe Shareflow API
+
+
+### Overview
+
+Flareshow provides a ruby wrapper around the shareflow json rpc wire protocol.  
+
+For more information about the Shareflow API see:
+<http://docs.google.com/View?id=dchr4h9d_5gz6nw3cb>
+
+### Getting Started
+You'll need a shareflow account setup before you can begin interacting with the api.  Go to <http://getshareflow.com> and sign up for a free account.
+
+### Authentication
+
+All actions in Flareshow require authenticationFlareshow can automatically authenticate you against your shareflow server.  Just create a YAML formatted .flareshowrc file in your home directory with the following keys
+
+subdomain : demo.zenbe.com
+login     : demo
+password  : password
+
+To authenticate manually do the following:
+
+    Flareshow::Service.configure(<subdomain>)
+    Flareshow.authenticate(<login>, <password>)
+
+### Usage
+
+Once you've authenticated you can choose to use either interact directly with the Flareshow::Service or use the Flareshow::Resource domain models which encapsulate the domain logic of Shareflow providing a friendlier development environment.
+
+### Examples
+
+#### accessing models and associations
+
+Flareshow offers an ActiveRecord like syntax for retrieving and manipulating models.
+
+    # Get the first post from the server ordered by creation date by default
+    p = Post.first
+    
+    # Get the comments for that post
+    p.comments
+    
+    # get the file attachments for the post
+    files = p.files
+    
+    # download a file
+    files.first.download
+
+
+#### reading posts
+
+    # the following code will read all posts on the server in a loop
+    per_request = 30
+    results = []
+    offset = 0
+
+    loop do 
+      posts = Post.find(:offset => offset, :limit => per_request)
+      results += posts
+      puts results.size
+      offset += per_request
+      break if posts.empty?
+    end
+
+#### upload a file to a Post
+
+    p=Post.new()
+    p.save
+    p.create_file("/path/to/your/file")
+
+#### searching for a post
+
+    # posts, files, comments include the searchable mixin
+    # and can be searched using full text search capabilities
+    # on the server
+    results = Post.search("some keywords")
+
+#### deleting a post or comment
+
+    Post.first.destroy
+    Comment.first.destroy
+
+#### renaming a flow
+
+    f=Flow.find_by_name('test')
+    f.name = 'a different name'
+    f.save
+
+#### inviting someone to a flow (only available if you are the creator of the flow)
+
+    f=Flow.find_by_name('test')
+    f.send_invitations('test@test.com')
+    
+    # this also works
+    f.send_invitations(['test1@test.com', 'test2@test.com'])
+    
+#### canceling an invitation to a flow (only available if you are the creator of the flow)
+    
+    f=Flow.find_by_name('test')
+    # revoke an invitation by the email address that was invited
+    f.revoke_invitations('test@test.com')
+
+
+#### removing a user from a flow (only available if you are the creator of the flow)
+
+    f = Flow.find_by_name('test')
+    users = f.list_users # get a listing of the users on the flow
+    # remove the last user in the list from the flow...you cant remove yourself in this way
+    f.remove_members(users.last.id) 
+
+#### listing all the users on a flow
+
+    f=Flow.first
+    f.list_users

data/Rakefile

@@ -0,0 +1,60 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "flareshow"
+    gem.summary = %Q{a ruby gem for interacting with the shareflow collaboration service}
+    gem.description = %Q{a ruby gem for interacting with the shareflow collaboration service by Zenbe}
+    gem.email = "will.bailey@gmail.com"
+    gem.homepage = "http://github.com/willbailey/flareshow"
+    gem.authors = ["Will Bailey"]
+    gem.add_development_dependency "thoughtbot-shoulda", "> 0"
+    gem.add_dependency "json", "> 0"
+    gem.add_dependency "curb", "> 0"
+    gem.add_dependency "facets", "> 0"
+    gem.add_dependency "uuid", "> 0"
+    gem.rubyforge_project = "flareshow"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "flareshow #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO

@@ -0,0 +1,14 @@
+TODO:
+shareflow api docs
+write tests with Fakeweb
+flesh out more resource methods
+make post requests with embedded file attachments respond with the file attachments for now...later we need to allow the creation of files in the same way as posts as flat 
+  namespaced objects
+handle failure states on requests
+namespace auth requests to be consistent with other api calls
+
+TODONE:
+remove temporary auth setup logging in user automatically
+
+QUESTIONS:
+should authentication responses look like query and commit responses namespacing is applied differently in authentication currently?

data/VERSION

@@ -0,0 +1 @@
+0.3.1

data/lib/cache.rb

@@ -0,0 +1,91 @@
+# provides an interface for various
+# caches that flareshow might use
+class Flareshow::CacheManager
+  
+  class << self
+    # assimilate the resources provided in the response
+    def assimilate_resources(data)
+      # process each resource key and generate a new object
+      # or merge the object data with an existing object
+      data.inject({}) do |memo,resource_pair|
+        resource_key, resources = resource_pair[0], resource_pair[1]
+        
+        fs_resource_array = memo[resource_key] ||= []
+        klass_name = Flareshow::ResourceToClassMap[resource_key]
+        klass = Kernel.const_get(klass_name)
+        if klass_name
+          if klass
+            resources.each do |resource_data|
+              item = cache.get_resource(resource_key, resource_data["id"])
+              if item
+                item.update(resource_data, :server)
+              else
+                item = klass.new(resource_data, :server) 
+              end
+              cache.set_resource(resource_key, item.id, item)
+              fs_resource_array << item
+            end
+          end
+        end
+        memo
+      end
+    end
+    
+    # get the managed cache object
+    def cache
+      @cache ||= Flareshow::Cache.new
+    end
+    
+  end
+  
+  
+end
+
+# a simple in memory cache for Flareshow objects
+class Flareshow::Cache
+    
+    # you can create your own cache object and plug it into the cache manager.
+    # The cache class should implement the public methods 
+    # get_resource, set_resource, delete_resource, list_resource, flush and size
+    
+    # load a resource from the cache
+    def get_resource(resource_key, id)
+      resource_cache(resource_key)[id]
+    end
+    
+    # set a resource in the cache
+    def set_resource(resource_key, id, object)
+      resource_cache(resource_key)[id] = object
+    end
+    
+    # remove a resource
+    def delete_resource(resource_key, id)
+      resource_cache(resource_key).delete(id)
+    end
+    
+    def list_resource(resource_key)
+      resource_cache(resource_key)
+    end
+    
+    # remove all cached objects
+    def flush
+      data = {}
+    end
+    
+    # number of cached objects
+    def size
+      data.values.inject(0){|m,v| m+=v.size}
+    end
+    
+    private
+    # data store for the cache
+    def data
+      @cache ||= {}
+    end
+    
+    # get a specific resource dictionary
+    def resource_cache(resource_key)
+      data[resource_key] ||= Dictionary.new
+    end
+    
+end

data/lib/comment.rb

@@ -0,0 +1,28 @@
+class Comment < Flareshow::Resource
+  
+  @attr_accessible = [:content, :post_id]
+  @attr_required = [:post_id, :content]
+  
+  extend Flareshow::Searchable
+  
+  # permalink to this comment
+  def permalink(mobile=false)
+    if mobile
+      "http://#{Flareshow::Service.server.host}/#{Flareshow::Service.server.domain}/shareflow/mobile/post/#{reply_to}"
+    else
+      "http://#{Flareshow::Service.server.host}/#{Flareshow::Service.server.domain}/shareflow/p/#{reply_to}?comment_id#{id}"
+    end
+  end
+  
+  # get the post for this comment
+  def post
+    Post.first(:id => post_id)
+  end
+  
+  # user for this post
+  def user
+    return User.current unless user_id
+    User.first({:id => user_id})
+  end
+  
+end

data/lib/exceptions.rb

@@ -0,0 +1,32 @@
+module Flareshow
+  
+  class MissingRequiredField < Exception
+    def message
+      "you attempted to save an object without providing all of the required fields"
+    end
+  end
+  
+  class APIAccessException < Exception
+    def message 
+      "you've attempted to change an object in a way not permitted by the API"
+    end
+  end
+  
+  class ConfigurationException < Exception
+    def message
+      "the shareflow service connection has not been configured properly"
+    end
+  end
+
+  class AuthenticationRequired < Exception
+    def message
+      "this action requires authentication"
+    end
+  end
+
+  class AuthenticationFailed < Exception
+    def message
+      "authentication failed"
+    end
+  end
+end

data/lib/file_attachment.rb

@@ -0,0 +1,40 @@
+class FileAttachment < Flareshow::Resource
+  
+  @read_only=true
+  
+  extend Flareshow::Searchable
+  
+  # =================
+  # = Class Methods =
+  # =================
+  class << self
+    # file attachments has a resource key of files 
+    # for querying the server
+    def resource_key
+      "files"
+    end
+  end
+  
+  # download the file contents
+  def download
+    url = self.url
+    unless url.match(/http/)
+      url = "http://#{Flareshow::Service.server.host}/#{Flareshow::Service.server.domain}#{url}"
+    end
+    Flareshow::Util.log_info("getting #{url}")
+    Flareshow::Service.http_get(url)
+  end
+  
+  # post for this file
+  def post
+    return false unless post_id
+    Post.find({:id => post_id})
+  end
+  
+  # get the user for this file
+  def user
+    p = post && post.first
+    p.user && p.user.first
+  end
+  
+end

data/lib/flareshow.rb

@@ -0,0 +1,61 @@
+ROOT = File.dirname(__FILE__) unless defined? ROOT
+
+# gems
+require 'rubygems' #TODO fix
+require 'json'
+require 'facets'
+require 'facets/dictionary'
+require 'uuid'
+require 'mime/types'
+require 'cgi'
+
+# std lib
+require 'net/http'
+require 'net/https'
+require 'ostruct'
+require 'yaml'
+require 'logger'
+require 'ruby-debug'
+
+# Application Constants and configuration
+module Flareshow
+  
+  # mappings to allow easy conversion from the
+  # response keys the server sends back in JSUP
+  # messages
+  ResourceToClassMap = {
+    "flows"       => "Flow",
+    "posts"       => "Post",
+    "comments"    => "Comment",
+    "files"       => "FileAttachment",
+    "memberships" => "Membership",
+    "invitations" => "Invitation",
+    "users"       => "User"
+  } unless defined? ResourceToClassMap
+  ClassToResourceMap = ResourceToClassMap.invert unless defined? ClassToResourceMap
+end
+
+# app
+require File.join(ROOT, 'service')
+require File.join(ROOT, 'resource')
+require File.join(ROOT, 'cache')
+require File.join(ROOT, 'searchable')
+
+# logging
+DEFAULT_LOGGER = Logger.new(STDOUT) unless defined?(DEFAULT_LOGGER)
+DEFAULT_LOGGER.level = Logger::ERROR
+Dir.glob(File.join(ROOT, "*.rb")).each{|lib| require lib}
+
+# check for presence of config file
+config_file_path = File.expand_path("~/.flareshowrc")
+if File.exists?(config_file_path) && !Flareshow::Service.authenticated?
+  data = YAML.load_file(config_file_path)
+  Flareshow::Service.debug_output=true if data["debug_http"]
+  host = data["host"] || "biz.zenbe.com"
+  subdomain = data["subdomain"]
+  DEFAULT_LOGGER.level = data["log_level"].to_i if data["log_level"]
+  Flareshow::Service.configure(subdomain, host)
+  if data["login"] && data["password"]
+    User.log_in(data["login"], data["password"])
+  end
+end

data/lib/flow.rb

@@ -0,0 +1,78 @@
+class Flow < Flareshow::Resource
+  
+  @attr_accessible = [:name, :remove_members, :uninvite, :invite]
+  @attr_required = [:name]
+  
+  # =================
+  # = Class Methods =
+  # =================
+  class << self
+    # find a flow by name
+    def find_by_name(name)
+      self.first({:name => name})
+    end
+  end
+  
+  # permalink for this flow
+  def permalink(mobile=false)
+    if mobile
+      "http://#{Flareshow::Service.server.host}/#{Flareshow::Service.server.domain}/shareflow/mobile/flows/#{id}"
+    else
+      "http://#{Flareshow::Service.server.host}/#{Flareshow::Service.server.domain}/shareflow/c/#{id}"
+    end
+  end
+  
+  #invite/reinvite a user to a flow by email address
+  def send_invitations(email_addresses)
+    self.invite = [email_addresses].flatten
+    self.save
+  end
+  
+  # uninvite an invited user from a flow by email address
+  def revoke_invitations(email_addresses)
+    self.uninvite = [email_addresses].flatten
+    self.save
+  end
+  
+  # remove a user from a flow
+  # you must be the owner of the flow to perform
+  # this action
+  def remove_members(member_ids)
+    self.remove_members = [member_ids].flatten
+    self.save
+  end
+  
+  # build a new post but don't persist it immediatel
+  def build_post(attributes)
+    post = Post.new
+    post.update(attributes)
+    post.flow_id = id
+    post
+  end
+  
+  # create a new post in this flow
+  def create_post(attributes)
+    p=build_post(attributes)
+    p.save
+  end
+  
+  # posts for this flow...only returns the first 100 (API max)
+  # to load all posts you can interact with the Service class directly
+  # to loop through in batches of 100 using the offset parameter or 
+  # create a flow object and override this method with the looping logic
+  def posts
+    Post.find(:flow_id => id)
+  end
+  
+  # list the invitations to this flow
+  def list_invitations
+    Invitation.find(:flow_id => id)
+  end
+  
+  # list all users on the flow currently
+  def list_users
+    response = Flareshow::Service.query({:flows=>{:id => self.id, :limit => 1, :include=>['users']}})
+    (Flareshow::CacheManager.assimilate_resources(response["resources"]) || {})["users"]
+  end
+  
+end

data/lib/http_encoding_helper.rb

@@ -0,0 +1,49 @@
+# Intended to extend the Net::HTTP response object
+# and adds support for decoding gzip and deflate encoded pages
+#
+# Author: Jason Stirk <http://griffin.oobleyboo.com>
+# Home: http://griffin.oobleyboo.com/projects/http_encoding_helper
+# Created: 5 September 2007
+# Last Updated: 23 November 2007
+#
+# Usage:
+#
+# require 'net/http'
+# require 'http_encoding_helper'
+# headers={'Accept-Encoding' => 'gzip, deflate' }
+# http = Net::HTTP.new('griffin.oobleyboo.com', 80)
+# http.start do |h|
+#   request = Net::HTTP::Get.new('/', headers)
+#   response = http.request(request)
+#   content=response.plain_body     # Method from our library
+#   puts "Transferred: #{response.body.length} bytes"
+#   puts "Compression: #{response['content-encoding']}"
+#   puts "Extracted: #{response.plain_body.length} bytes"  
+# end
+#	
+
+require 'zlib'
+require 'stringio'
+
+class Net::HTTPResponse
+  # Return the uncompressed content
+  def plain_body
+    encoding=self['content-encoding']
+    content=nil
+    if encoding then
+      case encoding
+        when 'gzip'
+          i=Zlib::GzipReader.new(StringIO.new(self.body))
+          content=i.read
+        when 'deflate'
+          i=Zlib::Inflate.new
+          content=i.inflate(self.body)
+        else
+          raise "Unknown encoding - #{encoding}"
+      end
+    else
+      content=self.body
+    end
+    return content
+  end
+end