Class: Twingly::LiveFeed::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/twingly/livefeed/client.rb

Overview

Twingly LiveFeed API client

Constant Summary collapse

BASE_URL = 
"https://api.twingly.com"
LIVEFEED_API_VERSION = 
"v5"
LIVEFEED_PATH = 
"/blog/livefeed/api/#{LIVEFEED_API_VERSION}/getdata"
DEFAULT_USER_AGENT = 
"Twingly LiveFeed Ruby Client/#{VERSION}"
DEFAULT_MAX_POSTS = 
1000
TIMESTAMP_FORMAT = 
"%Y-%m-%dT%H:%M:%S.%3N%z"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key = nil, options = {}) {|_self| ... } ⇒ Client

Creates a new Twingly Search API client

Parameters:

  • api_key (String) (defaults to: nil) —

    the API key provided by Twingly. If nil, reads key from environment (TWINGLY_SEARCH_KEY).

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :user_agent (String) —

    the user agent to be used for all requests

  • :max_posts (String) —

    the maximum number of posts that can be returned for each request

  • :timestamp (String) —

    the timestamp to start the client at

Yields:

  • (_self)

Yield Parameters:

Raises:



36
37
38
39
40
41
42
43
44
45
 
# File 'lib/twingly/livefeed/client.rb', line 36

def initialize(api_key = nil, options = {})
  @api_key    = api_key
  @user_agent = options.fetch(:user_agent) { DEFAULT_USER_AGENT }
  @max_posts  = options.fetch(:max_posts)  { DEFAULT_MAX_POSTS }
  @timestamp  = options.fetch(:timestamp)  { Time.now }

  yield self if block_given?

  @api_key ||= env_api_key || api_key_missing
end

Instance Attribute Details

#api_key ⇒ String

the API key

Returns:

  • (String) —

    the current value of api_key



14
15
16
 
# File 'lib/twingly/livefeed/client.rb', line 14

def api_key
  @api_key
end

#max_posts ⇒ Integer

the maximum number of posts that each request can return

Returns:

  • (Integer) —

    the current value of max_posts



14
15
16
 
# File 'lib/twingly/livefeed/client.rb', line 14

def max_posts
  @max_posts
end

#timestamp ⇒ Time

the timestamp that will be used in the next request

Returns:

  • (Time) —

    the current value of timestamp



14
15
16
 
# File 'lib/twingly/livefeed/client.rb', line 14

def timestamp
  @timestamp
end

#user_agent ⇒ String

the user agent to be used for all API requests

Returns:

  • (String) —

    the current value of user_agent



14
15
16
 
# File 'lib/twingly/livefeed/client.rb', line 14

def user_agent
  @user_agent
end

Instance Method Details

#endpoint_url ⇒ String

Returns the API endpoint URL.

Returns:

  • (String) —

    the API endpoint URL.



71
72
73
 
# File 'lib/twingly/livefeed/client.rb', line 71

def endpoint_url
  "#{BASE_URL}#{LIVEFEED_PATH}"
end

#next_result ⇒ Result

Get the next result from the API and updates the next timestamp

Sends a request to the API using the timestamp set with #timestamp, updates the timestamp that should be used in the next request and then returns the result.

Returns:

  • (Result) —

    the result for this request.

Raises:

  • (QueryError) —

    if the timestamp is invalid.

  • (AuthenticationError) —

    if the API couldn’t authenticate you. Make sure your API key is correct.

  • (ServerError) —

    if the query could not be executed due to a server error.



57
58
59
60
61
62
63
 
# File 'lib/twingly/livefeed/client.rb', line 57

def next_result
  assert_valid_time(timestamp)

  get_and_parse_result.tap do |result|
    update_timestamp(result.next_timestamp)
  end
end

#request_parameters ⇒ Hash

Returns the request parameters.

Returns:

  • (Hash) —

    the request parameters.



82
83
84
85
86
87
88
 
# File 'lib/twingly/livefeed/client.rb', line 82

def request_parameters
  {
    apikey:    api_key,
    timestamp: timestamp.to_time.utc.strftime(TIMESTAMP_FORMAT),
    maxPosts:  max_posts,
  }
end

#url ⇒ String

Returns the request url for the next request.

Returns:

  • (String) —

    the request url for the next request.



66
67
68
 
# File 'lib/twingly/livefeed/client.rb', line 66

def url
  "#{endpoint_url}?#{url_parameters}"
end

#url_parameters ⇒ String

Returns the query part of the request url.

Returns:

  • (String) —

    the query part of the request url.

See Also:



77
78
79
 
# File 'lib/twingly/livefeed/client.rb', line 77

def url_parameters
  Faraday::Utils.build_query(request_parameters)
end