Documentation for Scout.

scout-adapter.rb

module Subscriptions
  module Adapters
    class Base
      class << self
        # One of "bill", "document", "opinion", "regulation", "speech", "state_bill", "state_legislator" or nil.
        ITEM_TYPE = nil
        # Whether the adapter supports searching.
        SEARCH_ADAPTER = false
        # Whether the adapter supports subscriptions only.
        ITEM_ADAPTER = false
        # Whether the user can filter search results to see only this adapter's items.
        SEARCH_TYPE = false
        # Whether the user can filter citations to see only this adapter's items.
        CITE_TYPE = false
        # To sort the adapters in the navigation. Adapters of less weight float to the top.
        SORT_WEIGHT = Float::Infinity
        # Whether the adapter supports syncing.
        SYNCABLE = false

        # @return [Hash] a hash in which keys are facets (status, stage, etc.)
        #   and values are a hash. The nested hash may have a key of :field,
        #   whose value is a query string key, and a key of :name, whose value
        #   is a method that accept a machine-readable facet value and returns a
        #   human-readable facet value
        #
        # @example
        #   {
        #     'status' => {
        #       field: 'status_id',
        #       name: -> (id) {
        #         {
        #           1 => 'Passed lower chamber',
        #           2 => 'Passed upper chamber',
        #           3 => 'Passed both chambers',
        #           4 => 'Signed into law',
        #         }
        #       },
        #     },
        #   }
        def filters
          {}
        end

        # Returns a URL to query the data source for items relevant to the
        # subscription.
        #
        # **Syncing**
        #
        # If a data source is paginated, allows you to query for recent items,
        # and allows you to sort in chronological order, then Scout can mirror
        # (sync with) the data source.
        #
        # While syncing a data source, if a page contains fewer items than the
        # adapter's `MAX_PER_PAGE` constant, it is assumed to be the last page
        # and the sync is complete.
        #
        # Currently, you need to hand-edit `sync.rake` to add your adapter to
        # the list of sync-able adapters.
        # MAX_PER_PAGE = 50

        # @param [Subscription] subscription
        # @param [Symbol] function
        #   * `:check`: queries the data source for initial documents and marks
        #     those items as seen, without notifying the user
        #   * `:initialize`: queries the data source for new documents, marks
        #     those items as seen, and notifies the user
        #   * `:search`: queries the data source for new documents without
        #     marking any items as seen
        #   * `:sync`: queries the data source for new documents and stores them
        #     as plain items (not attached to an interest or subscription)
        # @param [Hash] options
        # @option options [String] :api_key an API key
        # @option options [Integer] :page a page number
        # @option options [Integer] :per_page the number of items per page
        # @return [String] an URL to query the data source for items relevant to
        #   the subscription
        #
        # @example
        #   "http://example.com/items/?q=#{CGI.escape(subscription.query['query'])}&status_id=#{subscription.data['status_id']}"
        def self.url_for(subscription, function, options = {})
          ''
        end

        # @param [String] item_id an item's unique identifier
        # @param [Hash] options
        # @return [String] a URL to get a single item from the data source
        # @note `:api_key` is the only accepted option, which is used by the
        #   "hood=up" feature only.
        #
        # @example
        #   "http://example.com/items/#{item_id}"
        def url_for_detail(item_id, options = {})
          ''
        end

        # @param [Hash] options
        # @option options [String] :since e.g. "all", "2010", "current"
        # @option options [Integer] :page a page number
        # @option options [Integer] :start a timestamp
        # @return [String] a URL to sync with a data source
        # @note Many `url_for_sync` methods accept an `:api_key` option.
        #   However, no caller uses that option.
        #
        # @example
        #   "http://example.com/items/?since=#{options[:since]}&page=#{options[:page]}"
        def url_for_sync(options = {})
          ''
        end

        # @param [Subscription] subscription used by the feed adapter only
        # @return [String] the adapter's long human name, usually plural
        def search_name(subscription = nil)
          name.demodulize.titleize
        end

        # @param [Integer] number the number of items
        # @param [Interest] interest used by no adapter
        # @return [String] the short name for an item or collection of items
        def short_name(number, interest = nil)
          name = search_name.downcase
          if number == 1
            name.singularize
          else
            name.pluralize
          end
        end

        # @param [Array,Hash] response the parsed response from an API request
        #   for multiple documents
        # @param [Symbol] function used by the federal_bills_activity adapter only
        # @param [Hash] options used by no adapter
        # @return [Array<SeenItem>] items
        def items_for(response, function, options = {})
          response.map do |document|
            item_for(document)
          end
        end

        # @param [Array,Hash] response the parsed response from an API request
        #   for a single document
        # @return [SeenItem] an item
        def item_detail_for(response)
          item_for(response)
        end

        # @param [Hash] data the arbitrary data stored on a document
        # @return [String] the document's title
        #
        # @example
        #   data['title']
        def title_for(data)
          ''
        end

        # @param [Hash] data the arbitrary data stored on a document
        # @return [String] the document's slug
        def slug_for(data)
          title_for(data)
        end

      private

        # @param [Hash] document a single document from the response to an API
        #   request to the data source
        # @return [SeenItem] an item
        # @see #items_for
        #
        # @example
        #   SeenItem.new(
        #     item_id: document['id'], # The document's unique identifier (can be a URL)
        #     date: document['issued_at'], # The date on which the document was published
        #     data: document, # Arbitrary data, usually the document itself
        #   )
        def item_for(document)
          SeenItem.new
        end
      end
    end
  end
end