datasift 2.0.4 → 2.1.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 --- 
-SHA1: 
-  data.tar.gz: 39c802a214147e3719a2515ca3de7cbdf0aac410
-  metadata.gz: 000329ea9766929bd49de5c246fbc145e4eea595
 SHA512: 
-  data.tar.gz: ab1a7dab1880c639e5fbce11a72a2b70445d2f1f057fe43d7a48f8ba8f30d412500d993fce4e2edd08cbd98003dabe4a8decf3c82a3de0273e323e0f6ff1b07e
-  metadata.gz: e4dc436e565ee2b2e34dfb18aa2e7c8e2b30fb2065af25a496ca0424504baaa22e9e0bfa638ab04e92ce92b35021d0f8abb249fed39bdf135fc6b3da1e0b0ff5
+  metadata.gz: 02bf11099c9d26f748777eb250a2012e6ca492f03ea6463f15f0dacae1f6881452254ddd7b7e6328c8d4118b0f5ea6c4cf29d72db1d0cca83c6f373ff4248f2e
+  data.tar.gz: a81b1b1f678cf752e7178954d805f8389e4ffd022cb080abc34c3d448ab6290e38493800265a809b9a75355f60d1812ff9d5b4e17ecabc5350fc73614c7df762
+SHA1: 
+  metadata.gz: bf41f27515af94fb037c2525301e1a731c5e2416
+  data.tar.gz: 98567da3573cccd91e78618ef0ad65744c871016

data/README.md

@@ -55,6 +55,7 @@ more details.
 
 Changelog
 ---------
+* v.2.1.0.beta Adding Managed Sources support. Thanks to [giovannelli](https://github.com/giovannelli) for the contribution (2013-08-05)
 
 * v.2.0.4 Bug fix to handle HTTP 202 response codes (2013-03-18)
 

data/VERSION

@@ -1 +1 @@
-2.0.4
+2.1.0.beta

data/datasift.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |s|
 	s.version = File.open('VERSION').first
 
 	s.authors     = ['DataSift']
-	s.email       = ['support@datasift.net']
+	s.email       = ['support@datasift.com']
 	s.description = %q{The official Ruby library for accessing the DataSift API. See http://datasift.com/ for full details and to sign up for an account.}
 	s.summary     = %q{DataSift is a simple wrapper for the DataSift API.}
 	s.homepage    = 'http://github.com/datasift/datasift-ruby'
@@ -17,6 +17,7 @@ Gem::Specification.new do |s|
 
 	s.add_runtime_dependency('rest-client', '~> 1.6.3')
 	s.add_runtime_dependency('yajl-ruby', '~> 1.1.0')
+	s.add_runtime_dependency('json', '~> 1.5.4')
 	s.add_development_dependency('rdoc', '> 0')
 	s.add_development_dependency('shoulda', '~> 2.11.3')
 	s.add_development_dependency('rspec', '~> 2.6.0')

data/lib/DataSift/managed_source.rb

@@ -0,0 +1,231 @@
+require 'json'
+### Usage ###
+# user = DataSift::User.new(config['username'], config['api_key'])
+# user.createManagedSource(:token => "CAAIUKbXn8xsBAILlxGCZADEZAM87tRqJXo9OqWskCs6jej3wfQ1LRRZAgHJQEZCHU0ABBXDwiq9o7D4uytC5LpsAcx7oiDusagsJiKtmPaZBeMkuGh4jYt1zsXo4EQuZCWPcZAIdQQLZBtjTpQlbbAZCTuJ4SSrlmOPQZD", :source_type => "facebook_page", :name => "test", :parameters=> {:likes => true, :posts_by_others =>  true, :comments => true}, :resources => [{ :url =>  "http://www.facebook.com/theguardian", :title =>  "The Guardian", :id => 10513336322 } ] )
+
+module DataSift
+  #The ManagedSource class represents a ManagedSource query.
+  class ManagedSource
+    #The ID of this Managed Source
+    attr_reader :managed_source_id
+    #The Managed Source type
+    attr_reader :source_type
+    #The current status of this Managed Source.
+    attr_reader :status
+    #The title for this Managed Source.
+    attr_reader :name
+    #The date/time when this Managed Source was created.
+    attr_reader :created_at
+    #The Managed Source source_type
+    attr_reader :source_type
+    #The Managed Source parameters
+    attr_reader :parameters
+    #The Managed Source resources
+    attr_reader :resources
+    #The Managed Source token
+    attr_reader :token
+    #The Managed Source auth
+    attr_reader :auth
+    #Api raw response
+    attr_reader :raw_attributes
+    
+    #Constructor. Pass all parameters to create a new Managed Source, or provide a User object and a managed_source_id to load an existing Managed Source from the API.
+    #=== Parameters
+    #* +user+ - The DataSift::User object.
+    def initialize(user, hash)
+      raise InvalidDataError, 'Please supply a valid User object when creating a Managed Source object.' unless user.is_a? DataSift::User
+      @user = user
+
+      if hash.kind_of?(Hash)
+        if hash.has_key?('id')
+          # Initialising from an array
+          @managed_source_id = hash['id']
+          initFromArray(hash)
+        else
+          @source_type = hash[:source_type]
+          @name = hash[:name]
+          @token = hash[:token]
+          @parameters = hash[:parameters]
+          @resources = hash[:resources]
+        end
+      else
+        # Fetching from the API
+        @managed_source_id = hash
+        reloadData()
+      end
+    end
+    
+    #Get a single Managed Source by ID.
+    #=== Parameters
+    #* +id+ - The Managed Source ID.
+    #=== Returns
+    #A ManagedSource object
+    def self.get(user, managed_source_id)
+      return new(user, user.callAPI('source/get', { 'id' => managed_source_id }))
+    end
+    
+    def self.list(user, page = 1, per_page = 20)
+      begin
+        res = user.callAPI(
+        'source/get', {
+          'page' => page,
+          'max' => per_page
+          })
+          retval = { 'count' => res['count'], 'managed_sources' => [] }
+          for source in res['sources']
+           retval['managed_sources'].push(new(user, source))
+          end
+          retval
+        rescue APIError => err
+          case err.http_code
+          when 400
+            #Missing or invalid parameters
+            raise InvalidDataError, err
+          else
+            raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+          end
+        end
+    end
+    
+    #Call the DataSift API to create the Managed Source
+    def create()
+      raise InvalidDataError, 'This Managed Source has already been created' unless not @managed_source_id
+
+      begin
+        res = @user.callAPI(
+        'source/create', {
+          'source_type' => @source_type,
+          'name' => @name,
+          'parameters' => @parameters.to_json,
+          'resources' => @resources.to_json,
+          'auth' => [ 'parameters' => { 'value' => @token } ].to_json
+        })
+        raise InvalidDataError, 'Prepared successfully but no managed_source_id ID in the response' unless res.has_key?('id')
+        @managed_source_id = res['id']
+
+      rescue APIError => err
+        case err.http_code
+        when 400
+          raise InvalidDataError, err
+        else
+          raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+        end
+      end
+
+      # Reload the data so we get the created_at date, initial status and the rest.
+      reloadData()
+    end
+
+    #Reload the data for this object from the API.
+    def reloadData()
+      #Can't do this without a playback ID
+      raise InvalidDataError, 'Cannot reload the data with a Managed Source with no Managed Source ID' unless @managed_source_id
+
+      begin
+        initFromArray(@user.callAPI('source/get', { 'id' => @managed_source_id }))
+      rescue APIError => err
+        case err.http_code
+        when 400
+          raise InvalidDataError, err
+        else
+          raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+        end
+      end
+    end
+     
+    #Initialise this object from the data in a Hash.
+ 		#=== Parameters
+    #* +data+ - The Hash containing the data.
+    def initFromArray(data)
+      raise APIError, 'No managed source ID in the response' unless data.has_key?('id')
+      raise APIError, 'Incorrect managed source ID in the response' unless not @managed_source_id or data['id'] == @managed_source_id
+      @managed_source_id = data['id']
+
+      raise APIError, 'No name in the response' unless data.has_key?('name')
+      @name = data['name']
+
+      raise APIError, 'No auth in the response' unless data.has_key?('auth')
+      @auth = data['auth']
+
+      raise APIError, 'No created at timstamp in the response' unless data.has_key?('created_at')
+      @created_at = DateTime.strptime(String(data['created_at']), '%s')
+
+      raise APIError, 'No status in the response' unless data.has_key?('status')
+      @status = data['status']
+
+      raise APIError, 'No source_type in the response' unless data.has_key?('source_type')
+      @source_type = data['source_type']
+
+      raise APIError, 'No parameters in the response' unless data.has_key?('parameters')
+      @parameters = data['parameters']
+      
+      raise APIError, 'No resources in the response' unless data.has_key?('resources')
+      @resources = data['resources']
+      
+      @raw_attributes = data
+      
+      return true
+    end
+     
+    #Start this Managed Source query.
+    def start()
+      raise InvalidDataError, 'Cannot start a Managed souce query that hasn\'t been created' unless @managed_source_id
+
+      begin
+        res = @user.callAPI('source/start', { 'id' => @managed_source_id })
+      rescue APIError => err
+        case err.http_code
+        when 400
+          # Missing or invalid parameters
+          raise InvalidDataError, err
+        when 404
+          # Managed Source not found
+          raise InvalidDataError, err
+        else
+          raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+        end
+      end
+    end
+
+    #Stop this Managed Source
+    def stop()
+      raise InvalidDataError, 'Cannot stop a Managed Source query that hasn\'t been prepared' unless @managed_source_id
+
+      begin
+        res = @user.callAPI('source/stop', { 'id' => @managed_source_id })
+      rescue APIError => err
+        case err.http_code
+        when 400
+          # Missing or invalid parameters
+          raise InvalidDataError, err
+        when 404
+          # Managed Source not found
+          raise InvalidDataError, err
+        else
+          raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+        end
+      end
+    end
+
+    #Delete this Managed Source
+    def delete()
+      raise InvalidDataError, 'Cannot delete a Managed source query that hasn\'t been prepared' unless @managed_source_id
+
+      begin
+        @user.callAPI('source/delete', { 'id' => @managed_source_id })
+      rescue APIError => err
+        case err.http_code
+        when 400
+          # Missing or invalid parameters
+          raise InvalidDataError, err
+        when 404
+          # Managed Source not found
+          raise InvalidDataError, err
+        else
+          raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+        end
+      end
+    end
+
+  end
+end

data/lib/DataSift/user.rb

@@ -1,267 +1,300 @@
 #This is the official DataSift client library for Ruby.
 module DataSift
-	#The User class represents a user of the API. Applications should start their
-	#API interactions by creating an instance of this class. Once initialised it
-	#provides factory methods for all of the functionality in the API.
-	class User
-		#The user agent to pass through with all HTTP requests.
-		USER_AGENT = 'DataSiftRuby/' + File.open(File.dirname(File.dirname(File.dirname(__FILE__))) + '/VERSION').first.strip!;
-		#The base URL for API requests.
-		API_BASE_URL = 'api.datasift.com/';
-		#The base URL for streams.
-		STREAM_BASE_URL = 'stream.datasift.com/';
+  #The User class represents a user of the API. Applications should start their
+  #API interactions by creating an instance of this class. Once initialised it
+  #provides factory methods for all of the functionality in the API.
+  class User
+    #The user agent to pass through with all HTTP requests.
+    USER_AGENT = 'DataSiftRuby/' + File.open(File.dirname(File.dirname(File.dirname(__FILE__))) + '/VERSION').first.strip!;
+    #The base URL for API requests.
+    API_BASE_URL = 'api.datasift.com/';
+    #The base URL for streams.
+    STREAM_BASE_URL = 'stream.datasift.com/';
 
-		#The User's DataSift username.
-		attr_reader :username
-		#The User's DataSift API key.
-		attr_reader :api_key
-		#The User's total number of available hourly API credits. This is not
-		#populated until an API request is made.
-		attr_reader :rate_limit
-		#The User's API credits remaining. This is not populated until an API
-		#request is made.
-		attr_reader :rate_limit_remaining
-		#The APIClient class to use when making API requests.
-		attr_reader :api_client
-		#True if streaming connections should use SSL.
-		attr_reader :use_ssl
+    #The User's DataSift username.
+    attr_reader :username
+    #The User's DataSift API key.
+    attr_reader :api_key
+    #The User's total number of available hourly API credits. This is not
+    #populated until an API request is made.
+    attr_reader :rate_limit
+    #The User's API credits remaining. This is not populated until an API
+    #request is made.
+    attr_reader :rate_limit_remaining
+    #The APIClient class to use when making API requests.
+    attr_reader :api_client
+    #True if streaming connections should use SSL.
+    attr_reader :use_ssl
 
-		#Constructor. A username and API key are required when constructing an
-		#instance of this class.
-		#=== Parameters
-		#* +username+ - The User's DataSift username
-		#* +api_key+ - The User's DataSift API key
-		def initialize(username, api_key, use_ssl = true)
-			username.strip!
-			api_key.strip!
+    #Constructor. A username and API key are required when constructing an
+    #instance of this class.
+    #=== Parameters
+    #* +username+ - The User's DataSift username
+    #* +api_key+ - The User's DataSift API key
+    def initialize(username, api_key, use_ssl = true)
+      username.strip!
+      api_key.strip!
 
-			raise EInvalidData, 'Please supply valid credentials when creating a User object.' unless username.size > 0 and api_key.size > 0
+      raise EInvalidData, 'Please supply valid credentials when creating a User object.' unless username.size > 0 and api_key.size > 0
 
-			@username = username
-			@api_key = api_key
-			@rate_limit = -1;
-			@rate_limit_remaining = -1
-			@use_ssl = use_ssl
-		end
+      @username = username
+      @api_key = api_key
+      @rate_limit = -1;
+      @rate_limit_remaining = -1
+      @use_ssl = use_ssl
+    end
 
-		#Creates and returns a definition object.
-		#=== Parameters
-		#* +csdl+ - Optional CSDL string with which to prime the object.
-		#=== Returns
-		#A Definition object.
-		def createDefinition(csdl = '')
-			DataSift::Definition.new(self, csdl, false)
-		end
+    #Creates and returns a definition object.
+    #=== Parameters
+    #* +csdl+ - Optional CSDL string with which to prime the object.
+    #=== Returns
+    #A Definition object.
+    def createDefinition(csdl = '')
+      DataSift::Definition.new(self, csdl, false)
+    end
 
-		#Create a Historics query based on this Definition.
-		#=== Parameters
-		#* +hash+ - The stream hash for a new Historics query.
-		#* +start_date+ - The start date for a new Historics query.
-		#* +end_date+ - The end date for a new Historics query.
-		#* +sources+ - An array of sources for a new Historics query.
-		#* +name+ - The name for a new Historics query.
-		#* +sample+ - The sample rate for the new Historics query.
-		#=== Returns
-		#A Historic object.
-		def createHistoric(hash, start_date, end_date, sources, sample, name)
-			return Historic.new(self, hash, start_date, end_date, sources, sample, name)
-		end
+    #Create a Historics query based on this Definition.
+    #=== Parameters
+    #* +hash+ - The stream hash for a new Historics query.
+    #* +start_date+ - The start date for a new Historics query.
+    #* +end_date+ - The end date for a new Historics query.
+    #* +sources+ - An array of sources for a new Historics query.
+    #* +name+ - The name for a new Historics query.
+    #* +sample+ - The sample rate for the new Historics query.
+    #=== Returns
+    #A Historic object.
+    def createHistoric(hash, start_date, end_date, sources, sample, name)
+      return Historic.new(self, hash, start_date, end_date, sources, sample, name)
+    end
 
-		#Get a Historics query from the API.
-		#=== Parameters
-		#* +playback_id+ - The playback ID of the Historics query to retrieve.
-		#=== Returns
-		#A Historic object.
-		def getHistoric(playback_id)
-			return Historic.new(self, playback_id)
-		end
+    #Get a Historics query from the API.
+    #=== Parameters
+    #* +playback_id+ - The playback ID of the Historics query to retrieve.
+    #=== Returns
+    #A Historic object.
+    def getHistoric(playback_id)
+      return Historic.new(self, playback_id)
+    end
 
-		# Get a list of Historics queries in your account.
-		#=== Parameters
-		#* +page+ - The page number to get.
-		#* +per_page+ - The number of items per page.
-		#=== Returns
-		#A Hash containing...
-		#* +count+ - The total number of Historics queries in your account.
-		#* +historics+ - An array of Hashes where each Hash is a Historics query.
-		def listHistorics(page = 1, per_page = 20)
-			return Historic::list(self, page, per_page)
-		end
+    # Get a list of Historics queries in your account.
+    #=== Parameters
+    #* +page+ - The page number to get.
+    #* +per_page+ - The number of items per page.
+    #=== Returns
+    #A Hash containing...
+    #* +count+ - The total number of Historics queries in your account.
+    #* +historics+ - An array of Hashes where each Hash is a Historics query.
+    def listHistorics(page = 1, per_page = 20)
+      return Historic::list(self, page, per_page)
+    end
 
-		#Create a new PushDefinition object for this user.
-		#=== Returns
-		#A PushDefinition object.
-		def createPushDefinition()
-			return PushDefinition.new(self)
-		end
 
-		#Get an existing PushSubscription from the API.
-		#=== Parameters
-		#* +subscription_id+ - The ID of the subscription to fetch.
-		#=== Returns
-		#A PushSubscription object.
-		def getPushSubscription(subscription_id)
-			return PushSubscription.get(self, subscription_id)
-		end
+    #Create a Managed Source query based on this Definition.
+    #=== Options
+    #* +hash+ - Contains parameters to set up your Managed Source
+    #=== Returns
+    #A Managed Source object.
+    def createManagedSource(hash = {})
+      managed_source = ManagedSource.new(self, hash)
+      managed_source.create
+      return managed_source
+    end
 
-		#Get the log entries for all push subscription or the given subscription.
-		#=== Parameters
-		#* +subscription_id+ - Optional subscription ID.
-		#=== Returns
-		#A Hash containing...
-		#* +count+ - The total number of matching log entries.
-		#* +log_entries+ - An array of Hashes where each Hash is a log entry.
-		def getPushSubscriptionLog(subscription_id = false)
-			if subscription_id
-				return getPushSubscription(subscription_id).getLog()
-			else
-				return PushSubscription.getLogs(self)
-			end
-		end
+    #Get a Manged Source query from the API.
+    #=== Parameters
+    #* +managed_source_id+ - The ID of the Managed Source to retrieve.
+    #=== Returns
+    #A Managed Source object.
+    def getManagedSource(managed_source_id)
+      return ManagedSource.get(self, managed_source_id)
+    end
 
-		#Get a page of Push subscriptions in the given user's account, where each
-		#page contains up to per_page items. Results will be ordered according to
-		#the supplied ordering parameters.
-		#=== Parameters
-		#* +page+ - The page number to get.
-		#* +per_page+ - The number of items per page.
-		#* +order_by+ - The field by which to order the results.
-		#* +order_dir+ - Ascending or descending.
-		#* +include_finished+ - True to include subscriptions against finished Historics queries.
-		#=== Returns
-		#A Hash containing...
-		#* +count+ - The total number of matching Push subscriptions in your account.
-		#* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
-		def listPushSubscriptions(page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC, include_finished = false)
-			return PushSubscription.list(self, page, per_page, order_by, order_dir, include_finished)
-		end
+    # Get a list of ManagedSources in your account.
+    #=== Parameters
+    #* +page+ - The page number to get.
+    #* +per_page+ - The number of items per page.
+    #=== Returns
+    #A Hash containing...
+    #* +count+ - The total number of Managed Sources in your account.
+    #* +managed_sources+ - An array of Hashes where each Hash is a managed source.
+    def listManagedSources(page = 1, per_page = 20)
+      return ManagedSource::list(self, page, per_page)
+    end
 
-		#Get a page of Push subscriptions in the given user's account, where each
-		#page contains up to per_page items. Results will be ordered according to
-		#the supplied ordering parameters.
-		#=== Parameters
-		#* +hash+ - The stream hash.
-		#* +page+ - The page number to get.
-		#* +per_page+ - The number of items per page.
-		#* +order_by+ - The field by which to order the results.
-		#* +order_dir+ - Ascending or descending.
-		#* +include_finished+ - True to include subscriptions against finished Historics queries.
-		#=== Returns
-		#A Hash containing...
-		#* +count+ - The total number of matching Push subscriptions in your account.
-		#* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
-		def listPushSubscriptionsToStreamHash(hash, page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC, include_finished = false)
-			return PushSubscription.listByStreamHash(self, hash, page, per_page, order_by, order_dir)
-		end
+    #Create a new PushDefinition object for this user.
+    #=== Returns
+    #A PushDefinition object.
+    def createPushDefinition()
+      return PushDefinition.new(self)
+    end
 
-		#Get a page of Push subscriptions in the given user's account, where each
-		#page contains up to per_page items. Results will be ordered according to
-		#the supplied ordering parameters.
-		#=== Parameters
-		#* +hash+ - The stream hash.
-		#* +page+ - The page number to get.
-		#* +per_page+ - The number of items per page.
-		#* +order_by+ - The field by which to order the results.
-		#* +order_dir+ - Ascending or descending.
-		#* +include_finished+ - True to include subscriptions against finished Historics queries.
-		#=== Returns
-		#A Hash containing...
-		#* +count+ - The total number of matching Push subscriptions in your account.
-		#* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
-		def listPushSubscriptionsToPlaybackId(playback_id, page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC, include_finished = false)
-			return PushSubscription.listByPlaybackId(self, playback_id, page, per_page, order_by, order_dir)
-		end
+    #Get an existing PushSubscription from the API.
+    #=== Parameters
+    #* +subscription_id+ - The ID of the subscription to fetch.
+    #=== Returns
+    #A PushSubscription object.
+    def getPushSubscription(subscription_id)
+      return PushSubscription.get(self, subscription_id)
+    end
 
-		#Returns a StreamConsumer-derived object for the given hash, for the
-		#given type.
-		#=== Parameters
-		#* +type+ - The consumer type for which to construct a consumer.
-		#* +hash+ - The hash to be consumed.
-		#=== Returns
-		#A StreamConsumer-derived object.
-		def getConsumer(type = nil, hash = nil, on_interaction = nil, on_stopped = nil)
-			StreamConsumer.factory(self, type, Definition.new(self, nil, hash))
-		end
+    #Get the log entries for all push subscription or the given subscription.
+    #=== Parameters
+    #* +subscription_id+ - Optional subscription ID.
+    #=== Returns
+    #A Hash containing...
+    #* +count+ - The total number of matching log entries.
+    #* +log_entries+ - An array of Hashes where each Hash is a log entry.
+    def getPushSubscriptionLog(subscription_id = false)
+      if subscription_id
+        return getPushSubscription(subscription_id).getLog()
+      else
+        return PushSubscription.getLogs(self)
+      end
+    end
 
-		#Returns the account balance information for this user.
-		#=== Returns
-		#A Hash containing the balance information.
-		def getBalance
-			return callAPI('balance')['balance']
-		end
+    #Get a page of Push subscriptions in the given user's account, where each
+    #page contains up to per_page items. Results will be ordered according to
+    #the supplied ordering parameters.
+    #=== Parameters
+    #* +page+ - The page number to get.
+    #* +per_page+ - The number of items per page.
+    #* +order_by+ - The field by which to order the results.
+    #* +order_dir+ - Ascending or descending.
+    #* +include_finished+ - True to include subscriptions against finished Historics queries.
+    #=== Returns
+    #A Hash containing...
+    #* +count+ - The total number of matching Push subscriptions in your account.
+    #* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
+    def listPushSubscriptions(page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC, include_finished = false)
+      return PushSubscription.list(self, page, per_page, order_by, order_dir, include_finished)
+    end
 
-		#Returns the usage data for this user. If a hash is provided then a more
-		#detailed breakdown using interaction types is retrieved and returned.
-		#=== Parameters
-		#* +period+ - An optional period for which to fetch data ('hour' or 'day')
-		#=== Returns
-		#A Hash containing the usage information.
-		def getUsage(period = 'hour')
-			params = { 'period' => period }
+    #Get a page of Push subscriptions in the given user's account, where each
+    #page contains up to per_page items. Results will be ordered according to
+    #the supplied ordering parameters.
+    #=== Parameters
+    #* +hash+ - The stream hash.
+    #* +page+ - The page number to get.
+    #* +per_page+ - The number of items per page.
+    #* +order_by+ - The field by which to order the results.
+    #* +order_dir+ - Ascending or descending.
+    #* +include_finished+ - True to include subscriptions against finished Historics queries.
+    #=== Returns
+    #A Hash containing...
+    #* +count+ - The total number of matching Push subscriptions in your account.
+    #* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
+    def listPushSubscriptionsToStreamHash(hash, page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC, include_finished = false)
+      return PushSubscription.listByStreamHash(self, hash, page, per_page, order_by, order_dir)
+    end
 
-			return callAPI('usage', params)
-		end
+    #Get a page of Push subscriptions in the given user's account, where each
+    #page contains up to per_page items. Results will be ordered according to
+    #the supplied ordering parameters.
+    #=== Parameters
+    #* +hash+ - The stream hash.
+    #* +page+ - The page number to get.
+    #* +per_page+ - The number of items per page.
+    #* +order_by+ - The field by which to order the results.
+    #* +order_dir+ - Ascending or descending.
+    #* +include_finished+ - True to include subscriptions against finished Historics queries.
+    #=== Returns
+    #A Hash containing...
+    #* +count+ - The total number of matching Push subscriptions in your account.
+    #* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
+    def listPushSubscriptionsToPlaybackId(playback_id, page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC, include_finished = false)
+      return PushSubscription.listByPlaybackId(self, playback_id, page, per_page, order_by, order_dir)
+    end
 
-		#Returns the user agent this library should use for all API calls.
-		#=== Returns
-		#The user agent string.
-		def getUserAgent()
-			return USER_AGENT
-		end
+    #Returns a StreamConsumer-derived object for the given hash, for the
+    #given type.
+    #=== Parameters
+    #* +type+ - The consumer type for which to construct a consumer.
+    #* +hash+ - The hash to be consumed.
+    #=== Returns
+    #A StreamConsumer-derived object.
+    def getConsumer(type = nil, hash = nil, on_interaction = nil, on_stopped = nil)
+      StreamConsumer.factory(self, type, Definition.new(self, nil, hash))
+    end
 
-		#Sets the ApiClient object to use to access the API
-		#=== Parameters
-		#* +client+ - The API client object to be used.
-		def setApiClient(client)
-			@api_client = client
-		end
+    #Returns the account balance information for this user.
+    #=== Returns
+    #A Hash containing the balance information.
+    def getBalance
+      return callAPI('balance')['balance']
+    end
 
-		#Sets whether to use SSL for API and stream communication.
-		#=== Parameters
-		#* +use_ssl+ - Pass true to use SSL.
-		def enableSSL(use_ssl = true)
-			@use_ssl = use_ssl
-		end
+    #Returns the usage data for this user. If a hash is provided then a more
+    #detailed breakdown using interaction types is retrieved and returned.
+    #=== Parameters
+    #* +period+ - An optional period for which to fetch data ('hour' or 'day')
+    #=== Returns
+    #A Hash containing the usage information.
+    def getUsage(period = 'hour')
+      params = { 'period' => period }
 
-		#Make a call to a DataSift API endpoint.
-		#=== Parameters
-		#* +endpoint+ - The endpoint of the API call.
-		#* +params+ - A Hash of parameters to be passed along with the request.
-		#=== Returns
-		#A Hash containing the response data.
-		def callAPI(endpoint, params = {})
-			if !@api_client
-				@api_client = ApiClient.new()
-			end
+      return callAPI('usage', params)
+    end
 
-			res = @api_client.call(self, endpoint, params, getUserAgent())
+    #Returns the user agent this library should use for all API calls.
+    #=== Returns
+    #The user agent string.
+    def getUserAgent()
+      return USER_AGENT
+    end
 
-			# Set up the return value
-			retval = res['data']
+    #Sets the ApiClient object to use to access the API
+    #=== Parameters
+    #* +client+ - The API client object to be used.
+    def setApiClient(client)
+      @api_client = client
+    end
 
-			# Update the rate limits from the headers
-			@rate_limit = res['rate_limit']
-			@rate_limit_remaining = res['rate_limit_remaining']
+    #Sets whether to use SSL for API and stream communication.
+    #=== Parameters
+    #* +use_ssl+ - Pass true to use SSL.
+    def enableSSL(use_ssl = true)
+      @use_ssl = use_ssl
+    end
 
-			case res['response_code']
-			when 200
-			when 201
-                        when 202
-			when 204
-				# Do nothing
-			when 401
-				# Authentication failure
-				raise AccessDeniedError, retval.has_key?('error') ? retval['error'] : 'Authentication failed'
-			when 403
-				# Check the rate limit
-				raise RateLimitExceededError, retval['comment'] if @rate_limit_remaining == 0
-				# Rate limit is ok, raise a generic exception
-				raise APIError.new(res['response_code']), retval.has_key?('error') ? retval['error'] : 'Unknown error'
-			else
-				raise APIError.new(res['response_code']), retval.has_key?('error') ? retval['error'] : 'Unknown error'
-			end
+    #Make a call to a DataSift API endpoint.
+    #=== Parameters
+    #* +endpoint+ - The endpoint of the API call.
+    #* +params+ - A Hash of parameters to be passed along with the request.
+    #=== Returns
+    #A Hash containing the response data.
+    def callAPI(endpoint, params = {})
+      if !@api_client
+        @api_client = ApiClient.new()
+      end
 
-			return retval
-		end
-	end
+      res = @api_client.call(self, endpoint, params, getUserAgent())
+
+      # Set up the return value
+      retval = res['data']
+
+      # Update the rate limits from the headers
+      @rate_limit = res['rate_limit']
+      @rate_limit_remaining = res['rate_limit_remaining']
+
+      case res['response_code']
+      when 200
+      when 201
+      when 202
+      when 204
+        # Do nothing
+      when 401
+        # Authentication failure
+        raise AccessDeniedError, retval.has_key?('error') ? retval['error'] : 'Authentication failed'
+      when 403
+        # Check the rate limit
+        raise RateLimitExceededError, retval['comment'] if @rate_limit_remaining == 0
+        # Rate limit is ok, raise a generic exception
+        raise APIError.new(res['response_code']), retval.has_key?('error') ? retval['error'] : 'Unknown error'
+      else
+        raise APIError.new(res['response_code']), retval.has_key?('error') ? retval['error'] : 'Unknown error'
+      end
+
+      return retval
+    end
+  end
 end

data/lib/datasift.rb

@@ -12,3 +12,4 @@ require dir + '/DataSift/push_definition'
 require dir + '/DataSift/push_subscription'
 require dir + '/DataSift/stream_consumer'
 require dir + '/DataSift/stream_consumer_http'
+require dir + '/DataSift/managed_source'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: datasift
 version: !ruby/object:Gem::Version 
-  version: 2.0.4
+  version: 2.1.0.beta
 platform: ruby
 authors: 
 - DataSift
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-03-18 00:00:00 Z
+date: 2013-08-05 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rest-client
@@ -32,38 +32,48 @@ dependencies:
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: rdoc
+  name: json
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.5.4
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">"
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
-  version_requirements: *id003
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: shoulda
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
         version: 2.11.3
   type: :development
-  version_requirements: *id004
+  version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: rspec
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id006 !ruby/object:Gem::Requirement 
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
         version: 2.6.0
   type: :development
-  version_requirements: *id005
+  version_requirements: *id006
 description: The official Ruby library for accessing the DataSift API. See http://datasift.com/ for full details and to sign up for an account.
 email: 
-- support@datasift.net
+- support@datasift.com
 executables: []
 
 extensions: []
@@ -110,6 +120,7 @@ files:
 - lib/DataSift/definition.rb
 - lib/DataSift/exceptions.rb
 - lib/DataSift/historic.rb
+- lib/DataSift/managed_source.rb
 - lib/DataSift/mockapiclient.rb
 - lib/DataSift/push_definition.rb
 - lib/DataSift/push_subscription.rb
@@ -147,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.0.5
 signing_key: 
 specification_version: 4
 summary: DataSift is a simple wrapper for the DataSift API.