socialcastr 0.0.1 → 0.1.0

data/.gitignore

@@ -9,3 +9,4 @@ coverage/*
 doc/*
 log/*
 pkg/*
+examples/socialcast.yml

data/README.markdown

@@ -4,31 +4,54 @@ SocialCast gem is a ruby interface to the SocialCast REST API
 
 ## INSTALLATION
 
-    gem install socialcast4r
+    gem install socialcastr
 
 ## Usage
 
+    # configure the connection 
     Socialcastr.configuration do |socialcast|
       socialcast.username = "user@example.com"
       socialcast.password = "password"
       socialcast.domain   = "demo.socialcast.com"
     end
     
+    # obtain an instance of the API (useful to directly issue get, put, post, delete commands)
     api = Socialcastr.api
     
-    messages = api.messages
+    # find all messages (currently returns just one page - 20 elements)
+    messages = Socialcastr::Message.find(:all)
+   
+    # build a new message object 
+    message = Socialcastr::Message.new(
+                  :title => "hallo world!", 
+                  "body" => "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
+              )
     
-    message_params = { "message[title]" => "hallo world!", "message[body]" => "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."  }
-    reply = api.add_message(message_params)
-    message = Socialcastr::Message.parse(reply)
+    message.new? # => true
+
+    # persist the message to Socialcast
+    message.save
+
+    # comment a message
+    message.comment! :text => "Hallo world"
+
+    # search for messages
+    messages = Socialcastr::Message.search(:q => "test")
+
+
 
 
 ## Status
 
 This is just the first draft of the wrapper. It can be improved in many, many ways.
-The API is not completely covered either: a lot of interesing stuff, like (un)liking and attachments have been left out. 
+The API is not completely covered either: some of interesing stuff, like message and comments attachments have been left out. 
 Feel free to help (see Contributing below)
 
+## TODO
+
+* Base
+  * CRUD for nested objects (comments, likes, attachments)
+
 ## Contributing to the code (a.k.a. submitting a pull request)
 
 1. Fork the project.

data/examples/parse_messages.rb

@@ -0,0 +1,16 @@
+$:.unshift("./lib")
+require 'rubygems'
+require 'socialcastr'
+
+Socialcastr.configuration do |config|
+  config.username = "username"
+  config.password = "password"
+  config.domain = "domain"
+end
+
+xml = File.read("/Users/bru/Desktop/socialcast.xml")
+start_time = Time.new
+messages = Socialcastr::Message.parse(xml)
+end_time = Time.new
+
+puts "Found #{messages.count} messages in #{end_time - start_time} seconds"

data/examples/post_comment.rb

@@ -0,0 +1,11 @@
+$:.unshift('./lib')
+require 'rubygems'
+require 'socialcastr'
+
+Socialcastr.configuration do |c|
+  c.config_file = File.join(File.dirname(__FILE__), "socialcast.yml")
+end
+
+message = Socialcastr::Message.last
+
+message.comment! :text => "hallo from Socialcastr"

data/examples/post_message.rb

@@ -0,0 +1,15 @@
+$:.unshift('./lib')
+require 'rubygems'
+require 'socialcastr'
+
+Socialcastr.configuration do |c|
+  c.config_file = File.join(File.dirname(__FILE__), "socialcast.yml")
+end
+
+message = Socialcastr::Message.new( :title => "hello world", :body => "yet another message")
+
+puts "message created: #{message.to_params.inspect}"
+
+message.save
+
+puts "message now is #{ message.new? ? "still new" : "persisted"} with id #{message.id}"

data/examples/search.rb

@@ -0,0 +1,19 @@
+$:.unshift('./lib')
+require 'rubygems'
+require 'socialcastr'
+
+NEEDLE="welcome"
+Socialcastr.configuration do |c|
+  c.config_file = File.join(File.dirname(__FILE__), 'socialcast.yml')
+end
+
+
+puts "Searching for #{NEEDLE}..."
+messages = Socialcastr::Message.search(:q => NEEDLE)
+puts "found #{messages.size} results:"
+
+messages.each do |message|
+  puts "#{message.user.name}:\n\t#{message.title}\n\t#{message.body}"
+end
+
+

data/lib/socialcastr/api.rb

@@ -5,8 +5,6 @@ require 'uri'
 require 'digest/md5'
 require 'cgi'
 
-
-
 module Socialcastr
   class API
     attr_accessor :debug
@@ -19,102 +17,86 @@ module Socialcastr
       @endpoint = "https://#{domain}/api/"
       return self
     end
+
+    def get(path, args={})
+      https_request(:get, path, args)
+    end   
     
-    def messages(stream=nil, query={})
-      method="messages"
-      method.insert(0, "streams/#{stream.id}/") if stream
-      xml = api_get(method, query)
-      return Socialcastr::MessageList.parse(xml).messages
-    end
-    
-    def search(query)
-      method="messages/search"
-      xml = api_get(method, query)
-      return Socialcastr::MessageList.parse(xml).messages
-    end
-    
-    def groups
-      method = "group_memberships"
-      xml = api_get(method)
-      return Socialcastr::GroupMembershipList.parse(xml).group_memberships
-    end
-    
-    def streams
-      method = "streams"
-      xml = api_get(method)
-      return Socialcastr::StreamList.parse(xml).streams
-    end
-    
-    def add_message(message)
-      xml = api_post("messages", message)
-      return xml
-    end
-    
-    def add_comment(message_id, comment)
-      xml = api_post("messages/#{message_id}/comments", comment)
-      return xml
+    def put(path, args={})
+      https_request(:put, path, args)
     end
-    
-    def like_comment(message_id,comment_id)
-      xml = api_post("messages/#{message_id.to_s}/comments/#{comment_id.to_s}/likes")
-      return xml
+
+    def post(path, args={})
+      https_request(:post, path, args)
     end
     
-    def unlike_comment(message_id,comment_id,like_id)
-      xml = api_delete("messages/#{message_id}/comments/#{comment_id}/likes/#{like_id}")
-      return xml
+    def delete(path, args={})
+      https_request(:delete, path, args)
     end
-    
+
     def https_request(method, path, args)
       https = setup_https
-      response = ""
-      
-      # HACK
-      # if path == "messages/search"
-      #   path = "messages"
-      # end
-      # data = File.read(File.join('/tmp','fixtures','xml', "#{path}.#{@format}"))
-      # return data
-      # # /HACK
 
       case method
-        when 'get'
-        request_class = Net::HTTP::Get
-        query=args
-        when 'post'
-        request_class = Net::HTTP::Post
-        form_data = args
-        when 'put'
-        request_class = Net::HTTP::Put
-        form_data = args
-        when 'delete'
-        request_class = Net::HTTP::Delete
+        when :get
+          request_class = Net::HTTP::Get
+          query=args
+        when :post
+          request_class = Net::HTTP::Post
+          form_data = args
+        when :put
+          request_class = Net::HTTP::Put
+          form_data = args
+        when :delete
+          request_class = Net::HTTP::Delete
+        else
+          raise InvalidMethod
       end
+      response = nil
       https.start do |session|
-        query_string = "/api/#{path}.#{@format}"
-        query_string += "?" + (query.collect { |k,v| "#{k}=#{CGI::escape(v.to_s)}" }.join('&')) unless query.nil?
+        query_string = build_query_string(path, query)
         req = request_class.new(query_string)
         req.basic_auth @username, @password
         if form_data
           req.set_form_data(args, ';')
         end
-        response = session.request(req).body
+        response = session.request(req)
       end
 
-      response  
-    end
-    
-    def api_get(path, args={})
-      https_request('get', path, args)
-    end   
-    
-    
-    def api_post(path, args={})
-      https_request('post', path, args)
+      return handle_response(response).body
     end
     
-    def api_delete(path, args={})
-      https_request('delete', path, args)
+
+    # Handles response and error codes from the remote service.
+    def handle_response(response)
+      case response.code.to_i
+        when 301,302
+          raise(Redirection.new(response))
+        when 200...400
+          response
+        when 400
+          raise(BadRequest.new(response))
+        when 401
+          raise(UnauthorizedAccess.new(response))
+        when 403
+          raise(ForbiddenAccess.new(response))
+        when 404
+          raise(ResourceNotFound.new(response))
+        when 405
+          raise(MethodNotAllowed.new(response))
+        when 409
+          raise(ResourceConflict.new(response))
+        when 410
+          raise(ResourceGone.new(response))
+        when 422
+          raise(ResourceInvalid.new(response))
+        when 401...500
+          raise(ClientError.new(response))
+        when 500...600
+          raise(ServerError.new(response))
+        else
+          raise(ConnectionError.new(response, "Unknown response code: #{response.code}"))
+      end
     end
     
     def setup_https
@@ -124,5 +106,15 @@ module Socialcastr
       https.use_ssl = true
       return https
     end
+
+    def build_query_string(path, query=nil)
+      params = []
+      unless query.nil?
+        params = query.collect do |k,v| 
+          "#{k.to_s}=#{CGI::escape(v.to_s)}" 
+        end
+      end
+      "/api#{path.to_s =~ /\// ? path.to_s : "/" + path.to_s }.#{@format}" + (params.any? ? "?" + params.join('&') : "")
+    end
   end
 end

data/lib/socialcastr/base.rb

@@ -1,6 +1,157 @@
 require 'sax-machine'
+
 module Socialcastr
   class Base 
     include SAXMachine 
+
+    def initialize(arguments={})
+      arguments.map do |k,v|
+        self.send((k.to_s + "=").to_sym, v)
+      end
+    end
+
+    def id
+      begin
+        tmp_id = send self.class.id_attribute
+        tmp_id.to_i unless tmp_id.nil?
+      rescue
+        nil
+      end
+    end
+
+    def save
+      new? ? create : update
+    end
+
+    def create
+        api.post(collection_path, to_params).tap do |xml|
+          copy_attributes_from_object(self.class.parse(xml))
+        end
+    end
+
+    def update
+        api.put(element_path, to_params).tap do |xml|
+          copy_attributes_from_object(self.class.parse(xml))
+        end
+    end
+    
+    def copy_attributes_from_object(object=nil)
+      object.instance_variables.each do |v|
+        instance_variable_set(v, object.instance_variable_get(v))
+      end
+    end
+
+    def new?
+      id.nil?
+    end
+
+    def api
+      self.class.api
+    end
+
+    def element_path
+      self.class.element_path(self.id)
+    end
+
+    def collection_path
+      self.class.collection_path
+    end
+
+    def to_params
+      params = {}
+      instance_variables.each do |variable| 
+        params[param_name(variable)] = instance_variable_get(variable)
+      end
+      params
+    end
+
+    def param_name(variable_name)
+      "#{self.class.model_name.downcase}[#{variable_name.to_s.gsub /@/,''}]"
+    end
+
+    class << self
+      def api
+        @api ||= Socialcastr.api
+      end
+
+      def find(*arguments)
+        scope = arguments.slice!(0)
+        options = arguments.slice!(0) || {}
+        case scope
+          when :all   then find_every(options)
+          when :first then find_every(options).first
+          when :last  then find_every(options).to_a.last
+          #when :one   then find_one(options)
+          else             find_single(scope, options)
+        end
+      end
+
+      def find_single(id, options)
+        path = element_path(id, options)
+        parse(api.get(path))
+      end
+
+      def find_every(options)
+        path = collection_path(options)
+        parse_collection(api.get(path))
+      end
+
+      def all(*arguments)
+        find(:all, *arguments)
+      end
+
+      def first(*arguments)
+        find(:first, *arguments)
+      end
+
+      def last(*arguments)
+        find(:last, *arguments)
+      end
+
+      def element_path(id, prefix_options = {})
+        "#{prefix(prefix_options)}#{collection_name}/#{URI.escape id.to_s}"
+      end
+
+      def collection_path(options = {})
+        "#{prefix(options)}#{collection_name}"
+      end
+
+      def prefix(options)
+        options.map { |k,v| k.to_s.gsub("_id", 's') + "/" + v.to_s }.join("/") + "/"
+      end
+
+      def model_name
+        self.to_s.gsub(/^.*::/, '')
+      end
+
+      def collection_name
+        model_name.downcase + "s"
+      end
+
+      def parse_collection(data)
+        collection_class.parse(data)
+      end
+
+      def id_attribute
+        model_name.downcase + "_id"
+      end
+
+      def collection_class
+        return @collection_class if @collection_class
+        class_name = model_name + "List"
+        model_class = self
+        c_element = model_name.downcase.to_sym
+        c_name = collection_name.to_sym
+        klass = Object.const_set(class_name,Class.new(Socialcastr::Collection))
+        klass.class_eval do
+          collection_of c_element, :as => c_name, :class => model_class
+        end
+        return @collection_class = klass
+      end
+
+      def id_element(name=:id)
+        element name, :as => id_attribute.to_sym
+      end
+    end
   end
 end

data/lib/socialcastr/collection.rb

@@ -0,0 +1,30 @@
+module Socialcastr
+  class Collection < Base
+    include Enumerable
+
+    def each &block
+      members.each{|member| block.call(member)}
+    end
+
+    def size
+      members.size
+    end
+
+    def members
+      send self.class.members_method
+    end
+
+    def self.collection_of(name, options={})
+      if options[:as]
+        @members_method = options[:as]
+      else
+        @members_method = name
+      end
+      elements name, options
+    end
+
+    def self.members_method
+      @members_method
+    end
+  end
+end

data/lib/socialcastr/comment.rb

@@ -1,10 +1,10 @@
 module Socialcastr
   class Comment < Base
     element :editable
-    element :attachments, :as => :attachment_list, :class => Socialcastr::AttachmentList
+    elements :attachment, :as => :attachments, :class => Socialcastr::Attachment
     element :likable
     element :deletable
-    element :likes, :as => :like_list, :class => Socialcastr::LikeList
+    elements :like, :as => :likes, :class => Socialcastr::Like
     element :permalink_url
     element :text
     element :user, :class => Socialcastr::User

data/lib/socialcastr/exceptions.rb

@@ -0,0 +1,75 @@
+module Socialcastr
+  class InvalidMethod < StandardError
+  end
+  class ConnectionError < StandardError # :nodoc:
+    attr_reader :response
+
+    def initialize(response, message = nil)
+      @response = response
+      @message  = message
+    end
+
+    def to_s
+      message = "Failed."
+      message << "  Response code = #{response.code}." if response.respond_to?(:code)
+      message << "  Response message = #{response.message}." if response.respond_to?(:message)
+      message
+    end
+  end
+
+  # Raised when a Timeout::Error occurs.
+  class TimeoutError < ConnectionError
+    def initialize(message)
+      @message = message
+    end
+    def to_s; @message ;end
+  end
+
+  # Raised when a OpenSSL::SSL::SSLError occurs.
+  class SSLError < ConnectionError
+    def initialize(message)
+      @message = message
+    end
+    def to_s; @message ;end
+  end
+
+  # 3xx Redirection
+  class Redirection < ConnectionError # :nodoc:
+    def to_s; response['Location'] ? "#{super} => #{response['Location']}" : super; end
+  end
+
+  # 4xx Client Error
+  class ClientError < ConnectionError; end # :nodoc:
+
+  # 400 Bad Request
+  class BadRequest < ClientError; end # :nodoc
+
+  # 401 Unauthorized
+  class UnauthorizedAccess < ClientError; end # :nodoc
+
+  # 403 Forbidden
+  class ForbiddenAccess < ClientError; end # :nodoc
+
+  # 404 Not Found
+  class ResourceNotFound < ClientError; end # :nodoc:
+
+  # 409 Conflict
+  class ResourceConflict < ClientError; end # :nodoc:
+
+  # 410 Gone
+  class ResourceGone < ClientError; end # :nodoc:
+
+  # 422 Invalid
+  class ResourceInvalid < ClientError; end # :nodoc:
+
+
+  # 5xx Server Error
+  class ServerError < ConnectionError; end # :nodoc:
+
+  # 405 Method Not Allowed
+  class MethodNotAllowed < ClientError # :nodoc:
+    def allowed_methods
+      @response['Allow'].split(',').map { |verb| verb.strip.downcase.to_sym }
+    end
+  end
+end

data/lib/socialcastr/external_resource.rb

@@ -1,10 +1,10 @@
 module Socialcastr
   class ExternalResource < Base
     element :type
-    element :tags, :as => :tag_list, :class => Socialcastr::TagList
+    elements :tag, :as => :tags, :class => Socialcastr::Tag
     element :canonical_hashtag
     element :source, :class => Socialcastr::Source
-    element :media_files, :as => :media_file_list, :class => Socialcastr::MediaFileList 
+    elements :media_file, :as => :media_files, :class => Socialcastr::MediaFile
     element :url
     element :title
     element :description

data/lib/socialcastr/flag.rb

@@ -0,0 +1,5 @@
+module Socialcastr
+  class Flag < Base
+    id_element
+  end
+end

data/lib/socialcastr/like.rb

@@ -1,9 +1,9 @@
 module Socialcastr
   class Like < Base
+    id_element
     element :unlikable
     element :user, :class => Socialcastr::User
     element :created_at
-    element :id
     def unlikable_by?(api_id)
       @unlikable && api_id == self.user_id ? true : false
     end