podio 0.4.1 → 0.5.0

data/README.md

@@ -48,7 +48,7 @@ If you're writing a batch job or are just playing around with the API, this is t
 Basic Usage
 -----------
 
-After you configured the `Podio.client` singleton you can use all of the wrapper functions to do API requests. The functions are organized into modules corresponding to the official API documentation. The functions follow a common naming pattern that should be familiar to ActiveRecord users. For example:
+After you configured the `Podio.client` singleton you can use all of the wrapper functions to do API requests. The functions are organized into models corresponding to the official API documentation, although most API areas have multiple models associated. The method follow a common naming pattern that should be familiar to ActiveRecord users. For example:
 
     # Getting an item
     Podio::Item.find(42)
@@ -69,7 +69,7 @@ If there is a method missing or you want to do something special, you can use th
     end
     response.body
 
-All the wrapped methods either return a single Ruby hash, an array of Ruby hashes, or a simple Struct in case of pagination:
+All the wrapped methods either return a single model instance, an array of instances, or a simple Struct in case of pagination:
 
     # Find all items in an app (paginated)
     items = Podio::Item.find_all(app_id, :limit => 20)
@@ -84,10 +84,26 @@ All the wrapped methods either return a single Ruby hash, an array of Ruby hashe
     items.total_count
 
 
+Active Podio
+------------
+
+The Podio API is based on REST requests passing JSON back and forth, but we have tried to make the use of this client an experience more similar to using ActiveRecord from Rails. That means that all find methods return model instances with attributes cast to the expected type (string, integer, boolean, datetime, etc.). Also, models can be instantiated using a params hash, just like with ActiveRecord models.
+
+While the models can be used directly from this gem, we encourage everyone using Podio in a Rails project to add models that extend the standard models:
+
+    class Item < Podio::Item # Inherits from the base model in the Podio gem
+
+      # Your custom methods, e.g.:
+      def application
+        @app_instance ||= Application.find(self.app_id)
+      end
+    end
+
+
 Error Handling
 --------------
 
-All unsuccessful responses returned by the API (everything that has a 4xx or 5xx HTTP status code) will throw an exception. All exceptions inherit from `Podio::PodioError` and have three additional properties which give you more information about the error:
+All unsuccessful responses returned by the API (everything that has a 4xx or 5xx HTTP status code) will throw exceptions. All exceptions inherit from `Podio::PodioError` and have three additional properties which give you more information about the error:
 
     begin
       Podio::Space.create({:name => 'New Space', :org_id => 42})
@@ -100,6 +116,18 @@ All unsuccessful responses returned by the API (everything that has a 4xx or 5xx
       puts exc.response_body['error_description']
     end
 
+On instance methods, however, exceptions are handled in a way similar to ActiveRecord. These methods returns a boolean indicating if the API request succeeded or not, and makes the code, description and parameters available when the request fails:
+
+    @space_contact = SpaceContact.new({:name => 'The Dude', :birthdate => 50.years.ago})
+    if @space_contact.create
+      # Success
+    else
+      # Error, check:
+      # @space_contact.error_code
+      # @space_contact.error_message
+      # @space_contact.error_parameters
+    end
+
 
 Full Example
 ------------
@@ -114,10 +142,13 @@ Full Example
     my_orgs = Podio::Organization.find_all
 
     my_orgs.each do |org|
-      puts org['name']
-      puts org['url']
+      puts org.name
+      puts org.url
     end
 
+Note on Heroku Usage
+--------------------
+If you plan on using podio-rb on Heroku please note that only the 1.9.2 stack has been tested. Specifically, bamboo-mri-1.9.2 is recommended, while 1.8.7 is still stock on Heroku. Refer to their documentation for information on how to migrate your dynos 
 
 Meta
 ----

data/Rakefile

@@ -7,6 +7,7 @@ Bundler::GemHelper.install_tasks
 desc 'Run tests'
 Rake::TestTask.new(:test) do |t|
   ENV['ENABLE_STUBS'] = 'true'
+  ENV['ENABLE_RECORD'] = 'false'
   t.ruby_opts = ["-rubygems"] if defined? Gem
   t.libs << "lib" << "test"
   t.pattern = 'test/**/*_test.rb'
@@ -16,9 +17,10 @@ end
 desc 'Record responses'
 task :record do
   ENV['ENABLE_RECORD'] = 'true'
+  ENV['ENABLE_STUBS'] = 'false'
 
   Dir['test/**/*_test.rb'].each do |f|
-    ruby('-Ilib', f)
+    ruby("-Ilib:test", f)
 
     folder_name = f.match(/test\/(.+)_test.rb/)[1]
     FileUtils.mkdir_p("test/fixtures/#{folder_name}")

data/lib/podio/active_podio/base.rb

@@ -0,0 +1,311 @@
+require 'active_model'
+
+# Extends the Ruby wrapper to behave a bit like ActiveRecord models
+module ActivePodio
+  class Base
+    extend ActiveModel::Naming, ActiveModel::Callbacks
+    include ActiveModel::Conversion
+    
+    class_inheritable_accessor :valid_attributes
+    attr_accessor :attributes, :error_code, :error_message, :error_parameters
+
+    def initialize(attributes = {})
+      self.valid_attributes ||= []
+      attributes ||= {}
+      self.attributes = Hash[*self.valid_attributes.collect { |n| [n.to_sym, nil] }.flatten].merge(attributes.symbolize_keys)
+      attributes.each do |key, value|
+        if self.respond_to?("#{key}=".to_sym)
+          self.send("#{key}=".to_sym, value) 
+        elsif valid_attributes.include?(key.to_sym)
+          self.send(:[]=, key.to_sym, value)
+        end
+      end
+    end
+    
+    def persisted?
+      ! self.new_record?
+    end
+    
+    def new_record?
+      ! (self.respond_to?(:id) && self.id.present?)
+    end
+    
+    def to_param
+      return self.id.try(:to_s) if self.respond_to?(:id)
+    end
+    
+    def [](attribute)
+      @attributes ||= {}
+      @attributes[attribute.to_sym]
+    end
+    
+    def []=(attribute, value)
+      @attributes ||= {}
+      @attributes[attribute.to_sym] = value
+    end
+    
+    def ==(other)
+      self.respond_to?(:id) && other.respond_to?(:id) && self.id == other.id
+    end
+    alias :eql? :==
+    
+    def hash
+      self.id.hash if self.respond_to?(:id)
+    end
+    
+    def as_json(options={})
+      self.attributes
+    end
+    
+    private
+    
+      def klass_for_association(options)
+        klass_name = options[:class]
+        raise "Missing class name of associated model. Provide with :class => 'MyClass'." unless klass_name.present?
+        klass = nil
+        begin
+          klass = klass_name.constantize
+        rescue
+          klass = "Podio::#{klass_name}".constantize
+        end
+        return klass
+      end
+
+    class << self
+      
+      public
+      
+      # Defines the the supported attributes of the model
+      def property(name, type = :string)
+        self.valid_attributes ||= []
+        self.valid_attributes << name
+    
+        case type
+        when :datetime
+          define_datetime_accessor(name)
+        when :date
+          define_date_accessor(name)
+        when :integer
+          define_integer_accessor(name)
+        when :boolean
+          define_generic_accessor(name, :setter => false)
+          define_boolean_accessors(name)
+        when :array
+          define_array_accessors(name)
+        else
+          define_generic_accessor(name)
+        end
+      end
+    
+      # Wraps a single hash provided from the API in the given model
+      def has_one(name, options = {})
+        self.send(:define_method, name) do
+          klass = klass_for_association(options)
+          instance = self.instance_variable_get("@#{name}_has_one_instance")
+          unless instance.present?
+            property = options[:property] || name.to_sym
+            if self[property].present?
+              instance = klass.new(self[property])
+              self.instance_variable_set("@#{name}_has_one_instance", instance)
+            else
+              instance = nil
+            end
+          end
+          instance
+        end
+      end
+    
+      # Wraps a collection of hashes from the API to a collection of the given model
+      def has_many(name, options = {})
+        self.send(:define_method, name) do
+          klass = klass_for_association(options)
+          instances = self.instance_variable_get("@#{name}_has_many_instances")
+          unless instances.present?
+            property = options[:property] || name.to_sym
+            if self[property].present?
+              instances = self[property].map { |attributes| klass.new(attributes) }
+              self.instance_variable_set("@#{name}_has_many_instances", instances)
+            else
+              instances = []
+            end
+          end
+          instances
+        end
+    
+        self.send(:define_method, "#{name}?") do
+          self.send(name).length > 0
+        end
+      end
+    
+      # Returns a single instance of the model
+      def member(response)
+        new(response)
+      end
+    
+      # Returns a simple collection model instances
+      def list(response)
+        response.map! { |item| new(item) }
+        response
+      end
+    
+      # Returns a struct that includes:
+      # * all: A collection model instances
+      # * count: The number of returned records
+      # * total_count: The total number of records matching the given conditions
+      def collection(response)
+        result = Struct.new(:all, :count, :total_count).new(response['items'], response['filtered'], response['total'])
+        result.all.map! { |item| new(item) }
+        result
+      end
+    
+      def delegate_to_hash(hash_name, *attribute_names)
+        attribute_names.each do |attribute_name|
+          hash_index = attribute_name.to_s.gsub(/[\?!]/, '')
+          self.send(:define_method, attribute_name) do
+            self.send(hash_name)[hash_index]
+          end
+        end
+      end
+      
+      # Wraps the given methods in a begin/rescue block
+      # If no error occurs, the return value of the method, or true if nil is returned, is returned
+      # If a Podio::BadRequestError occurs, the method returns false and the error can be read from the error_message accessor
+      # If another error occurs, it is still raised
+      def handle_api_errors_for(*method_names)
+        method_names.each do |method_name|
+          self.send(:define_method, "#{method_name}_with_api_errors_handled") do |*args|
+            success, code, message, parameters, result = nil
+            begin
+              result = self.send("#{method_name}_without_api_errors_handled", *args)
+              success = true
+            rescue Podio::BadRequestError, Podio::AuthorizationError => ex
+              success = false
+              code        = ex.response_body["error"]
+              message     = ex.response_body["error_description"]
+              parameters  = ex.response_body["error_parameters"]
+            end
+          
+            if success
+              return result || true
+            else
+              @error_code       = code
+              @error_message    = message
+              @error_parameters = parameters
+              return false
+            end
+          end
+        
+          alias_method_chain method_name, :api_errors_handled
+        end
+      end
+    
+      private
+    
+        def define_generic_accessor(name, options = {})
+          options.reverse_merge!(:getter => true, :setter => true)
+    
+          if(options[:getter])
+            self.send(:define_method, name) do
+              self[name.to_sym]
+            end
+          end
+    
+          if(options[:setter])
+            self.send(:define_method, "#{name}=") do |value|
+              self[name.to_sym] = value
+            end
+          end
+        end
+    
+        def define_datetime_accessor(name)
+          self.send(:define_method, name) do
+            self[name.to_sym].try(:to_datetime).try(:in_time_zone)
+          end
+    
+          self.send(:define_method, "#{name}=") do |value|
+            self[name.to_sym] = if value.is_a?(DateTime)
+              value.try(:to_s, :db)
+            else
+              value.try(:to_s)
+            end
+          end
+        end
+    
+        def define_date_accessor(name)
+          self.send(:define_method, name) do
+            self[name.to_sym].try(:to_date)
+          end
+    
+          self.send(:define_method, "#{name}=") do |value|
+            self[name.to_sym] = if value.is_a?(Date)
+              value.try(:to_s, :db)
+            else
+              value.try(:to_s)
+            end
+          end
+        end
+    
+        def define_integer_accessor(name)
+          self.send(:define_method, name) do
+            if self[name.to_sym].present?
+              self[name.to_sym].to_i
+            else
+              nil
+            end
+          end
+    
+          self.send(:define_method, "#{name}=") do |value|
+            if value.present?
+              self[name.to_sym] = value.to_i
+            else
+              self[name.to_sym] = nil
+            end
+          end
+        end
+    
+        def define_boolean_accessors(name)
+          self.send(:define_method, "#{name}?") do
+            if self[name.to_sym].present?
+              %w{ true 1 yes }.include?(self[name.to_sym].to_s.strip.downcase)
+            else
+              nil
+            end
+          end
+    
+          self.send(:define_method, "#{name}=") do |value|
+            if value == true || value == false
+              self[name.to_sym] = value
+            elsif value.present?
+              self[name.to_sym] = %w{ true 1 yes }.include?(value.to_s.strip.downcase)
+            else
+              self[name.to_sym] = nil
+            end
+          end
+        end
+    
+        def define_array_accessors(name)
+          unless name.to_s == name.to_s.pluralize
+            self.send(:define_method, name) do
+              self[name.to_sym] || []
+            end
+    
+            self.send(:define_method, "#{name}=") do |array|
+              self[name.to_sym] = array.reject(&:blank?) if array.respond_to?(:reject)
+            end
+          end
+    
+          self.send(:define_method, name.to_s.pluralize) do
+            self[name.to_sym] || []
+          end
+    
+          self.send(:define_method, "#{name.to_s.pluralize}=") do |array|
+            self[name.to_sym] = array.reject(&:blank?) if array.respond_to?(:reject)
+          end
+    
+          self.send(:define_method, "default_#{name.to_s.singularize}") do
+            self[name.to_sym].try(:first).presence
+          end
+        end
+    end
+  end
+end

data/lib/podio/active_podio/updatable.rb

@@ -0,0 +1,22 @@
+# Adds functionality related to updating to an +ActivePodio+ model
+module ActivePodio
+  module Updatable
+    extend ActiveSupport::Concern
+  
+    module InstanceMethods
+      def update_attributes(attributes)
+        attributes.each do |key, value|
+          self.send("#{key}=".to_sym, value.presence)
+        end
+      end
+
+      def remove_nil_values(input_hash)
+        input_hash.inject({}) do |hash, (key, value)|
+          hash[key] = value if value.present?
+          hash
+        end
+      end
+    end
+  
+  end
+end

data/lib/podio/client.rb

@@ -1,6 +1,6 @@
 module Podio
   class Client
-    attr_reader :api_url, :api_key, :api_secret, :connection
+    attr_reader :api_url, :api_key, :api_secret, :connection, :raw_connection
     attr_accessor :oauth_token, :stubs, :current_http_client
 
     def initialize(options = {})
@@ -95,12 +95,14 @@ module Podio
 
     def setup_connections
       @connection = configure_connection
+      @raw_connection = configure_connection(true)
       @oauth_connection = configure_oauth_connection
     end
 
-    def configure_connection
+    def configure_connection(raw=false)
       Faraday::Connection.new(:url => api_url, :headers => configured_headers, :request => {:client => self}) do |builder|
-        builder.use Middleware::JsonRequest
+        builder.use Middleware::JsonRequest unless raw
+        builder.use Faraday::Request::Multipart if raw
         builder.use Middleware::OAuth2
         builder.use Middleware::Logger
 
@@ -109,7 +111,7 @@ module Podio
         # first response middleware defined get's executed last
         builder.use Middleware::DateConversion
         builder.use Middleware::ErrorResponse
-        builder.use Middleware::JsonResponse
+        builder.use Middleware::JsonResponse unless raw
         builder.use Middleware::ResponseRecorder if @record_mode
       end
     end
@@ -128,6 +130,7 @@ module Podio
 
     def configure_oauth
       @connection = configure_connection
+      @raw_connection = configure_connection(true)
     end
   end
 end

data/lib/podio/error.rb

@@ -10,6 +10,7 @@ module Podio
   end
 
   class TokenExpired < PodioError; end
+  class InvalidGrantError < PodioError; end
   class AuthorizationError < PodioError; end
   class BadRequestError < PodioError; end
   class ServerError < PodioError; end

data/lib/podio/middleware/error_response.rb

@@ -8,7 +8,11 @@ module Podio
           when 200, 204
             # pass
           when 400
-            raise BadRequestError.new(env[:body], env[:status], env[:url])
+            if env[:body]['error'] == 'invalid_grant'
+              raise InvalidGrantError.new(env[:body], env[:status], env[:url])
+            else
+              raise BadRequestError.new(env[:body], env[:status], env[:url])
+            end
           when 401
             if env[:body]['error_description'] =~ /expired_token/
               raise TokenExpired.new(env[:body], env[:status], env[:url])

data/lib/podio/middleware/response_recorder.rb

@@ -7,7 +7,7 @@ module Podio
         response = "['#{Faraday::Utils.normalize_path(env[:url])}', :#{env[:method]}, #{env[:status]}, #{env[:response_headers]}, '#{env[:body]}']"
 
         filename = Digest::MD5.hexdigest(env[:url].request_uri)
-        File.open("#{filename}.rack", 'w') { |f| f.write(response) }
+        ::File.open("#{filename}.rack", 'w') { |f| f.write(response) }
       end
     end
   end

data/lib/podio/models/app_store_share.rb

@@ -0,0 +1,67 @@
+class Podio::AppStoreShare < ActivePodio::Base
+  property :share_id, :integer
+  property :type, :string
+  property :status, :string
+  property :parents, :hash
+  property :name, :string
+  property :description, :string
+  property :abstract, :string
+  property :language, :string
+  property :featured, :boolean
+  property :features, :array
+  property :filters, :array
+  property :integration, :string
+  property :categories, :hash
+  property :org, :hash
+  property :author, :hash
+  property :author_apps, :integer
+  property :author_packs, :integer
+  property :icon, :string
+  property :comments, :array
+  property :ratings, :hash
+  property :user_rating, :array
+  property :screenshots, :array
+  property :info, :hash
+  
+  has_many :children, :class => 'AppStoreShare'
+  has_one :author, :class => 'ByLine'
+  
+  alias_method :id, :share_id
+
+  def create
+    self.share_id = self.class.create(self.attributes)
+  end
+
+  def install(space_id, dependencies)
+    self.class.install(self.share_id, space_id, dependencies)
+  end
+  
+  class << self
+    def create(attributes)
+      response = Podio.connection.post do |req|
+        req.url "/app_store/"
+        req.body = attributes
+      end
+
+      response.body['share_id']
+    end
+
+    def install(share_id, space_id, dependencies)
+      response = Podio.connection.post do |req|
+        req.url "/app_store/#{share_id}/install/v2"
+        req.body = {:space_id => space_id, :dependencies => dependencies}
+      end
+
+      response.body
+    end
+
+    def find(id)
+      member Podio.connection.get("/app_store/#{id}/v2").body
+    end
+
+    def find_all_private_for_org(org_id)
+      list Podio.connection.get("/app_store/org/#{org_id}/").body['shares']
+    end
+  end
+end
+

data/lib/podio/{areas → models}/application.rb

@@ -1,8 +1,25 @@
-module Podio
-  module Application
-    include Podio::ResponseWrapper
-    extend self
-    
+class Podio::Application < ActivePodio::Base
+  property :app_id, :integer
+  property :original, :integer
+  property :original_revision, :integer
+  property :status, :string
+  property :icon, :string
+  property :space_id, :integer
+  property :owner_id, :integer
+  property :owner, :hash
+  property :config, :hash
+  property :fields, :array
+  property :subscribed, :boolean
+  property :integration, :hash
+  property :rights, :array
+  property :link, :string
+  
+  has_one :integration, :class => 'Integration'
+
+  alias_method :id, :app_id
+  delegate_to_hash :config, :name, :item_name, :allow_edit?, :allow_attachments?, :allow_comments?, :description
+  
+  class << self
     def find(app_id)
       member Podio.connection.get("/app/#{app_id}").body
     end
@@ -42,7 +59,6 @@ module Podio
     
     def delete(id)
       Podio.connection.delete("/app/#{id}").body
-    end    
-    
+    end
   end
 end

data/lib/podio/models/application_email.rb

@@ -0,0 +1,22 @@
+class Podio::ApplicationEmail < ActivePodio::Base
+  include ActivePodio::Updatable
+
+  property :attachments, :boolean
+  property :mappings, :hash  
+
+  class << self
+    def get_app_configuration(app_id)
+      member Podio.connection.get { |req|
+        req.url("/email/app/#{app_id}", {})
+      }.body
+    end
+
+    def update_app_configuration(app_id, options)
+      Podio.connection.put { |req|
+        req.url "/email/app/#{app_id}"
+        req.body = options
+      }.body
+    end
+    
+  end
+end

data/lib/podio/models/application_field.rb

@@ -0,0 +1,17 @@
+class Podio::ApplicationField < ActivePodio::Base
+  property :field_id, :integer
+  property :type, :string
+  property :external_id, :integer
+  property :config, :hash
+
+  alias_method :id, :field_id
+  delegate_to_hash :config, :label, :description, :delta, :settings, :required?, :visible?
+  delegate_to_hash :settings, :allowed_values, :referenceable_types, :allowed_currencies, :valid_types
+  
+  class << self
+    def find(app_id, field_id)
+      member Podio.connection.get("/app/#{app_id}/field/#{field_id}").body
+    end
+    
+  end
+end

data/lib/podio/{areas → models}/bulletin.rb

@@ -1,8 +1,18 @@
-module Podio
-  module Bulletin
-    include Podio::ResponseWrapper
-    extend self
-
+class Podio::Bulletin < ActivePodio::Base
+  property :bulletin_id, :integer
+  property :title, :string
+  property :summary, :string
+  property :text, :string
+  property :locale, :string
+  property :target_group, :string
+  property :created_on, :datetime
+  property :sent_on, :datetime
+
+  has_one :created_by, :class => 'ByLine'
+
+  alias_method :id, :bulletin_id
+  
+  class << self
     def create(attributes)
       response = Podio.connection.post do |req|
         req.url "/bulletin/"
@@ -44,5 +54,6 @@ module Podio
     def send!(id)
       Podio.connection.post("/bulletin/#{id}/send").body
     end
+    
   end
 end