datasift 3.1.5 → 3.2.0

data/lib/managed_source.rb

@@ -1,28 +1,48 @@
 module DataSift
+  # Methods for using {http://dev.datasift.com/docs/sources/managed-sources
+  #   DataSift Managed Sources}
   class ManagedSource < DataSift::ApiResource
-
-    ##
     # Creates a new managed source
-    #+source_type+:: can be facebook_page, googleplus, instagram or yammer
+    #
+    # @param source_type [String] Type of Managed Source you are creating. e.g.
+    #   facebook_page, instagram, etc
+    # @param name [String] Name of this Managed Source
+    # @param parameters [Hash] Source-specific configuration parameters
+    # @param resources [Array] Array of source-specific resources
+    # @param auth [Array] Array of source-specific auth credentials
     def create(source_type, name, parameters = {}, resources = [], auth = [], options = {})
-      raise BadParametersError.new('source_type and name are required') if source_type.nil? || name.nil?
+      fail BadParametersError, 'source_type and name are required' if source_type.nil? || name.nil?
       params = {
-          :source_type => source_type,
-          :name        => name
+        :source_type => source_type,
+        :name => name
       }
       params.merge!(options) unless options.empty?
-      params.merge!({:auth => auth.is_a?(String) ? auth : MultiJson.dump(auth)}) unless auth.empty?
-      params.merge!({:parameters => parameters.is_a?(String) ? parameters : MultiJson.dump(parameters)}) unless parameters.empty?
-      params.merge!({:resources => resources.is_a?(String) ? resources : MultiJson.dump(resources)}) if resources.length > 0
+      params.merge!(
+        { :auth => auth.is_a?(String) ? auth : MultiJson.dump(auth) }
+      ) unless auth.empty?
+      params.merge!(
+        { :parameters => parameters.is_a?(String) ? parameters : MultiJson.dump(parameters) }
+      ) unless parameters.empty?
+      params.merge!(
+        { :resources => resources.is_a?(String) ? resources : MultiJson.dump(resources) }
+      ) if resources.length > 0
       DataSift.request(:POST, 'source/create', @config, params)
     end
 
+    # Update a Managed Source
+    #
+    # @param id [String] ID of the Managed Source you are updating
+    # @param source_type [String] Type of Managed Source you are updating
+    # @param name [String] Name (or new name) of the Managed Source
+    # @param parameters [Hash] Source-specific configuration parameters
+    # @param resources [Array] Array of source-specific resources
+    # @param auth [Array] Array of source-specific auth credentials
     def update(id, source_type, name, parameters = {}, resources = [], auth = [], options = {})
-      raise BadParametersError.new('id,source_type and name are required') if id.nil? || source_type.nil? || name.nil?
+      fail BadParametersError, 'ID, source_type and name are required' if id.nil? || source_type.nil? || name.nil?
       params = {
-          :id          => id,
-          :source_type => source_type,
-          :name        => name
+        :id => id,
+        :source_type => source_type,
+        :name => name
       }
       params.merge!(options) unless options.empty?
       params.merge!({:auth => MultiJson.dump(auth)}) if !auth.empty?
@@ -32,33 +52,57 @@ module DataSift
       DataSift.request(:POST, 'source/update', @config, params)
     end
 
+    # Delete a Managed Source
+    #
+    # @param id [String] ID of the Managed Source you are deleting
     def delete(id)
-      raise BadParametersError.new('id is required') if id.nil?
-      DataSift.request(:DELETE, 'source/delete', @config, {:id => id})
+      fail BadParametersError, 'ID is required' if id.nil?
+      DataSift.request(:DELETE, 'source/delete', @config, { :id => id })
     end
 
+    # Stop a Managed Source
+    #
+    # @param id [String] ID of the Managed Source you are stopping
     def stop(id)
-      raise BadParametersError.new('id is required') if id.nil?
-      DataSift.request(:POST, 'source/stop', @config, {:id => id})
+      fail BadParametersError, 'ID is required' if id.nil?
+      DataSift.request(:POST, 'source/stop', @config, { :id => id })
     end
 
+    # Start a Managed Source
+    #
+    # @param id [String] ID of the Managed Source you are starting
     def start(id)
-      raise BadParametersError.new('id is required') if id.nil?
-      DataSift.request(:POST, 'source/start', @config, {:id => id})
+      fail BadParametersError, 'ID is required' if id.nil?
+      DataSift.request(:POST, 'source/start', @config, { :id => id })
     end
 
+    # Retrieve details of a Managed Source
+    #
+    # @param id [String] ID of the Managed Source you are getting. Omitting the
+    #   ID will return a list of Managed Sources
+    # @param source_type [String] Limits the list of Managed Sources returned to
+    #   only sources of a specific source type if specified
+    # @param page [Integer] Number of Managed Sources to return on one page of
+    #   results
+    # @param per_page [Integer] Number of Managed Sources to return per page
     def get(id = nil, source_type = nil, page = 1, per_page = 20)
-      params = {:page => page, :per_page => per_page}
-      params.merge!({:id => id}) if id != nil
-      params.merge!({:source_type => source_type}) if source_type != nil
+      params = { :page => page, :per_page => per_page }
+      params.merge!({ :id => id }) if !id.nil?
+      params.merge!({ :source_type => source_type }) if !source_type.nil?
 
       DataSift.request(:GET, 'source/get', @config, params)
     end
 
+    # Retrieve log details of Managed Sources
+    #
+    # @param id [String] ID of the Managed Source for which you are collecting
+    #   logs
+    # @param page [Integer] Number of Managed Source logs to return on one page
+    #   of results
+    # @param per_page [Integer] Number of Managed Source logs to return per page
     def log(id, page = 1, per_page = 20)
-      raise BadParametersError.new('id is required') if id.nil?
-      DataSift.request(:POST, 'source/log', @config, {:id => id, :page => page, :per_page => per_page})
+      fail BadParametersError, 'ID is required' if id.nil?
+      DataSift.request(:POST, 'source/log', @config, { :id => id, :page => page, :per_page => per_page })
     end
-
   end
 end

data/lib/managed_source_auth.rb

@@ -1,20 +1,35 @@
 module DataSift
+  # Methods for using Auth specific Managed Sources API endpoints
   class ManagedSourceAuth < DataSift::ApiResource
-
+    # Add auth tokens to a Managed Source
+    #
+    # @param id [String] ID of the Managed Source you are adding Auth tokens to
+    # @param auth [Array] Array of auth tokens you are adding to your source
+    # @param validate [Boolean] Whether you want to validate your new tokens
+    #   against the third party API (i.e. the Facebook or Instagram API)
     def add(id, auth, validate = 'true')
       params = {
-        id:       id,
+        id: id,
+        auth: auth,
         validate: validate
       }
-      params.merge!({:auth => auth})
+      requires params
       DataSift.request(:PUT, 'source/auth/add', @config, params)
     end
 
+    # Remove auth tokens from a Managed Source
+    #
+    # @param id [String] ID of the Managed Source you are removing auth tokens
+    #   from
+    # @param auth_ids [Array] Array of auth_id strings you need to remove from
+    #   your source
     def remove(id, auth_ids)
-      params = {id: id}
-      params.merge!({:auth_ids => auth_ids})
+      params = {
+        id: id,
+        auth: auth_ids
+      }
+      requires params
       DataSift.request(:PUT, 'source/auth/remove', @config, params)
     end
-
   end
 end

data/lib/managed_source_resource.rb

@@ -1,20 +1,35 @@
 module DataSift
+  # Methods for using Auth specific Managed Sources API endpoints
   class ManagedSourceResource < DataSift::ApiResource
-
+    # Add resources to a Managed Source
+    #
+    # @param id [String] ID of the Managed Source you are adding resources to
+    # @param resources [Array] Array of resources you are adding to your source
+    # @param validate [Boolean] Whether you want to validate your new resources
+    #   against the third party API (i.e. the Facebook or Instagram API)
     def add(id, resources, validate = 'true')
       params = {
-        id:       id,
+        id: id,
+        resources: resources,
         validate: validate
       }
-      params.merge!({:resources => resources})
+      requires params
       DataSift.request(:PUT, 'source/resource/add', @config, params)
     end
 
+    # Remove resources from a Managed Source
+    #
+    # @param id [String] ID of the Managed Source you are removing resources
+    #   from
+    # @param resource_ids [Array] Array of resource_id strings you need to
+    #   remove from your source
     def remove(id, resource_ids)
-      params = {id: id}
-      params.merge!({:resource_ids => resource_ids})
+      params = {
+        id: id,
+        resource_ids: resource_ids
+      }
+      requires params
       DataSift.request(:PUT, 'source/resource/remove', @config, params)
     end
-
   end
 end

data/lib/push.rb

@@ -1,148 +1,215 @@
 module DataSift
   ##
-  # Push is a simple and robust mechanism for periodically delivering your data directly to a given destination
-  # Several widely adopted storage locations are available including Amazon S3, FTP, HTTP, SFTP, DynamoDB, CouchDB
-  # MongoDB, Splunk, Elastic search and more! See http://dev.datasift.com/docs/push/connectors
+  # Push is a simple and robust mechanism for periodically delivering your data
+  #   directly to a given destination. Several widely adopted storage locations
+  #   are available including Amazon S3, (S)FTP, HTTP, DynamoDB, CouchDB,
+  #   MongoDB, Splunk, ElasticSearch and more! See
+  #   http://dev.datasift.com/docs/push/connectors
   class Push < DataSift::ApiResource
-
     ##
-    # Check that a subscription is defined correctly
+    # Check that a Push subscription definition is valid
+    #
+    # @param params [Hash] Hash of Push subscription parameters
+    # @param bool_response [Boolean] True if you want a boolean response. False
+    #   if you want the full response object
     def valid?(params, bool_response = true)
       requires params
       res = DataSift.request(:POST, 'push/validate', @config, params)
       bool_response ? res[:http][:status] == 200 : res
     end
 
-    ##
-    #Create a new subscription to a live stream or historics query
-    # Possible params are
-    # hash, historics_id, name, output_type, initial_status, start, end and output_params.*
-    # where output_params.* depends on the output_type for specific options see the documentation at
-    # http://dev.datasift.com/docs/rest-api/pushcreate
-    # For a list of available connectors see http://dev.datasift.com/docs/push/connectors
+    # Create a new subscription to a live stream or historics query. Possible
+    #   params are hash, historics_id, name, output_type, initial_status, start,
+    #   end and output_params.* where output_params.* depends on the output_type
+    #   for specific options see the documentation at
+    #   http://dev.datasift.com/docs/rest-api/pushcreate For a list of available
+    #   connectors see http://dev.datasift.com/docs/push/connectors
+    #
+    # @param params [Hash] Hash of Push subscription parameters
     def create(params)
       DataSift.request(:POST, 'push/create', @config, params)
     end
 
-    ##
     # Update the name or output parameters for an existing subscription
-    def update (params)
+    #
+    # @param params [Hash] Hash of Push subscription parameters
+    def update(params)
       DataSift.request(:POST, 'push/update', @config, params)
     end
 
-    ##
-    #Pause a subscription and buffer the data for up to an hour
+    # Pause a subscription and buffer the data for up to an hour
+    #
+    # @param id [String] ID of the Push subscription to pause
     def pause(id)
-      params = {:id => id}
+      params = { :id => id }
       requires params
       DataSift.request(:PUT, 'push/pause', @config, params)
     end
 
-    ##
-    #Restart a job that was previously paused
+    # Resume a Push subscription that was previously paused
+    #
+    # @param id [String] ID of the Push subscription to resume
     def resume(id)
-      params = {:id => id}
+      params = { :id => id }
       requires params
       DataSift.request(:PUT, 'push/resume', @config, params)
     end
 
-    ##
-    # Stop a historics query or a live stream that is running with push
+    # Stop a Push subscription; you will not be able to resume this
+    #
+    # @param id [String] ID of the Push subscription to stop
     def stop(id)
-      params = {:id => id}
+      params = { :id => id }
       requires params
       DataSift.request(:PUT, 'push/stop', @config, params)
     end
 
-    ##
     # Deletes an existing push subscription
+    #
+    # @param id [String] ID of the Push subscription to delete
     def delete(id)
       params = {:id => id}
       requires params
       DataSift.request(:DELETE, 'push/delete', @config, params)
     end
 
-    ##
     # Retrieve log messages for a specific subscription
+    #
+    # @param id [String] ID of the Push subscription to retrieve logs for
+    # @param page [Integer] Which page of logs to retreive
+    # @param per_page [Integer] How many logs to return per page
+    # @param order_by [String, Symbol] Which field to sort results by
+    # @param order_dir [String, Symbol] Order results in ascending or descending
     def log_for(id, page = 1, per_page = 20, order_by = :request_time, order_dir = :desc)
       params = {
-          :id => id,
-          :page => page,
-          :per_page => per_page,
-          :order_by => order_by,
-          :order_dir => order_dir
+        :id => id
       }
+      requires params
+      params.merge!(
+        :page => page,
+        :per_page => per_page,
+        :order_by => order_by,
+        :order_dir => order_dir
+      )
       DataSift.request(:GET, 'push/log', @config, params)
     end
 
-    ##
     # Retrieve log messages for all subscriptions
+    #
+    # @param page [Integer] Which page of logs to retreive
+    # @param per_page [Integer] How many logs to return per page
+    # @param order_by [String, Symbol] Which field to sort results by
+    # @param order_dir [String, Symbol] Order results in ascending or descending
     def log(page = 1, per_page = 20, order_by = :request_time, order_dir = :desc)
       params = {
-          :page => page,
-          :per_page => per_page,
-          :order_by => order_by,
-          :order_dir => order_dir
+        :page => page,
+        :per_page => per_page,
+        :order_by => order_by,
+        :order_dir => order_dir
       }
       DataSift.request(:GET, 'push/log', @config, params)
     end
 
-    ##
     # Get details of the subscription with the given ID
+    #
+    # @param id [String] ID of the subscription to retrieve
     def get_by_subscription(id)
       params = { :id => id }
       DataSift.request(:GET, 'push/get', @config, params)
     end
 
-    ##
-    # Get details of the subscription with the given stream ID/hash
-    def get_by_hash(hash, page = 1, per_page = 20, order_by = :created_at, order_dir = :desc)
+    # Get details of the subscription with the given filter hash
+    #
+    # @param hash [String] CSDL filter hash
+    # @param page [Integer] Which page of logs to retreive
+    # @param per_page [Integer] How many logs to return per page
+    # @param order_by [String, Symbol] Which field to sort results by
+    # @param order_dir [String, Symbol] Order results in ascending or descending
+    # @param include_finished [Integer] Include Push subscriptions in a
+    #   'finished' state in your results
+    # @param all [Boolean] Also include Push subscriptions created via the web
+    #   UI in your results
+    def get_by_hash(hash, page = 1, per_page = 20, order_by = :created_at, order_dir = :desc, include_finished = 0, all = false)
       params = {
-          :hash => hash,
-          :page => page,
-          :per_page => per_page,
-          :order_by => order_by,
-          :order_dir => order_dir
+        :hash => hash
       }
+      requires params
+      params.merge!(
+        :page => page,
+        :per_page => per_page,
+        :order_by => order_by,
+        :order_dir => order_dir,
+        :include_finished => include_finished,
+        :all => all
+      )
       DataSift.request(:GET, 'push/get', @config, params)
     end
 
-    ##
     # Get details of the subscription with the given Historics ID
-    def get_by_historics_id(id, page = 1, per_page = 20, order_by = :created_at, order_dir = :desc)
+    #
+    # @param historics_id [String] ID of the Historics query for which you are
+    #   searching for the related Push subscription
+    # @param page [Integer] Which page of logs to retreive
+    # @param per_page [Integer] How many logs to return per page
+    # @param order_by [String, Symbol] Which field to sort results by
+    # @param order_dir [String, Symbol] Order results in ascending or descending
+    # @param include_finished [Integer] Include Push subscriptions in a
+    #   'finished' state in your results
+    # @param all [Boolean] Also include Push subscriptions created via the web
+    #   UI in your results
+    def get_by_historics_id(historics_id, page = 1, per_page = 20, order_by = :created_at, order_dir = :desc, include_finished = 0, all = false)
       params = {
-          :historics_id => id,
-          :page => page,
-          :per_page => per_page,
-          :order_by => order_by,
-          :order_dir => order_dir
+        :historics_id => historics_id,
+        :page => page,
+        :per_page => per_page,
+        :order_by => order_by,
+        :order_dir => order_dir,
+        :include_finished => include_finished,
+        :all => all
       }
       DataSift.request(:GET, 'push/get', @config, params)
     end
 
-    ##
     # Get details of all subscriptions within the given page constraints
-    def get(page = 1, per_page = 20, order_by = :created_at, order_dir = :desc)
+    #
+    # @param page [Integer] Which page of logs to retreive
+    # @param per_page [Integer] How many logs to return per page
+    # @param order_by [String, Symbol] Which field to sort results by
+    # @param order_dir [String, Symbol] Order results in ascending or descending
+    # @param include_finished [Integer] Include Push subscriptions in a
+    #   'finished' state in your results
+    # @param all [Boolean] Also include Push subscriptions created via the web
+    #   UI in your results
+    def get(page = 1, per_page = 20, order_by = :created_at, order_dir = :desc, include_finished = 0, all = false)
       params = {
-          :page => page,
-          :per_page => per_page,
-          :order_by => order_by,
-          :order_dir => order_dir
+        :page => page,
+        :per_page => per_page,
+        :order_by => order_by,
+        :order_dir => order_dir,
+        :include_finished => include_finished,
+        :all => all
       }
       DataSift.request(:GET, 'push/get', @config, params)
     end
 
-    ##
     # Pull data from a 'pull' type Push Subscription
-    def pull(id, size = 52428800, cursor = '', callback = nil)
+    #
+    # @param id [String] ID of the Push subscription to pull data from
+    # @param size [Integer] Max size (bytes) of the data that should be returned
+    # @param cursor [String] Point to a specific point in your Push buffer using
+    #   a cursor
+    # @param callback [Method] Pass a callback to process each interaction
+    #   returned from a successful pull request
+    def pull(id, size = 52_428_800, cursor = '', callback = nil)
       params = {
-          :id => id,
-          :size => size,
-          :cursor => cursor
+        :id => id
       }
-      if callback
-        params.merge!({:on_interaction => callback})
-      end
+      requires params
+      params.merge!(
+        :size => size,
+        :cursor => cursor
+      )
+      params.merge!({:on_interaction => callback}) unless callback.nil?
       DataSift.request(:GET, 'pull', @config, params, {}, 30, 30, true)
     end
   end