swiftype-app-search 0.1.0

data/lib/swiftype-app-search.rb

@@ -0,0 +1,4 @@
+require 'swiftype-app-search/client'
+
+module SwiftypeAppSearch
+end

data/lib/swiftype-app-search/client.rb

@@ -0,0 +1,62 @@
+require 'set'
+require 'swiftype-app-search/request'
+require 'swiftype-app-search/utils'
+require 'jwt'
+
+module SwiftypeAppSearch
+  # API client for the {Swiftype App Search API}[https://swiftype.com/app-search].
+  class Client
+    autoload :Documents, 'swiftype-app-search/client/documents'
+    autoload :Engines, 'swiftype-app-search/client/engines'
+    autoload :Search, 'swiftype-app-search/client/search'
+
+    DEFAULT_TIMEOUT = 15
+
+    include SwiftypeAppSearch::Request
+
+    attr_reader :api_key, :open_timeout, :overall_timeout, :api_endpoint
+
+    # Create a new SwiftypeAppSearch::Client client
+    #
+    # @param options [Hash] a hash of configuration options that will override what is set on the SwiftypeAppSearch class.
+    # @option options [String] :account_host_key an Account Host Key to use for this client
+    # @option options [String] :api_key an Api Key to use for this client
+    # @option options [Numeric] :overall_timeout overall timeout for requests in seconds (default: 15s)
+    # @option options [Numeric] :open_timeout the number of seconds Net::HTTP (default: 15s)
+    #   will wait while opening a connection before raising a Timeout::Error
+    def initialize(options = {})
+      @api_endpoint = options.fetch(:api_endpoint) { "https://#{options.fetch(:account_host_key)}.api.swiftype.com/api/as/v1/" }
+      @api_key = options.fetch(:api_key)
+      @open_timeout = options.fetch(:open_timeout, DEFAULT_TIMEOUT).to_f
+      @overall_timeout = options.fetch(:overall_timeout, DEFAULT_TIMEOUT).to_f
+    end
+
+    module SignedSearchOptions
+      ALGORITHM = 'HS256'.freeze
+
+      module ClassMethods
+        # Build a JWT for authentication
+        #
+        # @param [String] api_key the API Key to sign the request with
+        # @param [String] api_key_id the unique API Key identifier
+        # @option options see the {App Search API}[https://swiftype.com/documentation/app-search/] for supported search options.
+        #
+        # @return [String] the JWT to use for authentication
+        def create_signed_search_key(api_key, api_key_id, options = {})
+          raise 'Must create signed search key with an API Key, cannot use a Search Key' unless api_key.start_with?('api')
+          payload = Utils.symbolize_keys(options).merge(:api_key_id => api_key_id)
+          JWT.encode(payload, api_key, ALGORITHM)
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    include SwiftypeAppSearch::Client::Documents
+    include SwiftypeAppSearch::Client::Engines
+    include SwiftypeAppSearch::Client::Search
+    include SwiftypeAppSearch::Client::SignedSearchOptions
+  end
+end

data/lib/swiftype-app-search/client/documents.rb

@@ -0,0 +1,56 @@
+# Documents have fields that can be searched or filtered.
+#
+# For more information on indexing documents, see the {App Search documentation}[https://swiftype.com/documentation/app-search/].
+module SwiftypeAppSearch
+  class Client
+    module Documents
+      REQUIRED_TOP_LEVEL_KEYS = [
+        'id'
+      ].map!(&:freeze).to_set.freeze
+
+      # Retrieve Documents from the API by IDs for the {App Search API}[https://swiftype.com/documentation/app-search/]
+      #
+      # @param [String] engine_name the unique Engine name
+      # @param [Array<String>] ids an Array of Document IDs
+      #
+      # @return [Array<Hash>] an Array of Documents
+
+      def get_documents(engine_name, ids)
+        get("engines/#{engine_name}/documents", ids)
+      end
+
+      # Index a batch of documents using the {App Search API}[https://swiftype.com/documentation/app-search/].
+      #
+      # @param [String] engine_name the unique Engine name
+      # @param [Array] documents an Array of Document Hashes
+      #
+      # @return [Array<Hash>] an Array of processed Document Status hashes
+      #
+      # @raise [SwiftypeAppSearch::InvalidDocument] when a single document is missing required fields or contains unsupported fields
+      # @raise [Timeout::Error] when timeout expires waiting for statuses
+      def index_documents(engine_name, documents)
+        documents.map! { |document| validate_and_normalize_document(document) }
+        post("engines/#{engine_name}/documents", documents)
+      end
+
+      # Destroy a batch of documents given a list of IDs
+      #
+      # @param [Array<String>] ids an Array of Document IDs
+      #
+      # @return [Array<Hash>] an Array of Document destroy result hashes
+      def destroy_documents(engine_name, ids)
+        delete("engines/#{engine_name}/documents", ids)
+      end
+
+      private
+      def validate_and_normalize_document(document)
+        document = Utils.stringify_keys(document)
+        document_keys = document.keys.to_set
+        missing_keys = REQUIRED_TOP_LEVEL_KEYS - document_keys
+        raise InvalidDocument.new("missing required fields (#{missing_keys.to_a.join(', ')})") if missing_keys.any?
+
+        document
+      end
+    end
+  end
+end

data/lib/swiftype-app-search/client/engines.rb

@@ -0,0 +1,23 @@
+# Engines are the core concept representing indexes in App Search.
+#
+module SwiftypeAppSearch
+  class Client
+    module Engines
+      def list_engines
+        get("engines")
+      end
+
+      def get_engine(engine_name)
+        get("engines/#{engine_name}")
+      end
+
+      def create_engine(engine_name)
+        post("engines", :name => engine_name)
+      end
+
+      def destroy_engine(engine_name)
+        delete("engines/#{engine_name}")
+      end
+    end
+  end
+end

data/lib/swiftype-app-search/client/search.rb

@@ -0,0 +1,17 @@
+module SwiftypeAppSearch
+  class Client
+    module Search
+      # Search for documents
+      #
+      # @param [String] engine_name the unique Engine name
+      # @param [String] query the search query
+      # @option options see the {App Search API}[https://swiftype.com/documentation/app-search/] for supported search options.
+      #
+      # @return [Array<Hash>] an Array of Document destroy result hashes
+      def search(engine_name, query, options = {})
+        params = Utils.symbolize_keys(options).merge(:query => query)
+        request(:post, "engines/#{engine_name}/search", params)
+      end
+    end
+  end
+end

data/lib/swiftype-app-search/exceptions.rb

@@ -0,0 +1,24 @@
+module SwiftypeAppSearch
+  class ClientException < StandardError
+    attr_reader :errors
+
+    def initialize(response)
+      @errors = response['errors'] || [ response ]
+      message = (errors.count == 1) ? "Error: #{errors.first}" : "Errors: #{errors.inspect}"
+      super(message)
+    end
+  end
+
+  class NonExistentRecord < ClientException; end
+  class InvalidCredentials < ClientException; end
+  class BadRequest < ClientException; end
+  class Forbidden < ClientException; end
+  class InvalidDocument < ClientException; end
+
+  class UnexpectedHTTPException < ClientException
+    def initialize(http_response)
+      @errors = []
+      super("HTTP #{http_response.code}: #{http_response.body}")
+    end
+  end
+end

data/lib/swiftype-app-search/request.rb

@@ -0,0 +1,111 @@
+require 'net/https'
+require 'json'
+require 'swiftype-app-search/exceptions'
+require 'swiftype-app-search/version'
+require 'openssl'
+
+module SwiftypeAppSearch
+  DEFAULT_USER_AGENT = "swiftype-app-search-ruby/#{SwiftypeAppSearch::VERSION}"
+
+  module Request
+    attr_accessor :last_request
+
+    def get(path, params={})
+      request(:get, path, params)
+    end
+
+    def post(path, params={})
+      request(:post, path, params)
+    end
+
+    def put(path, params={})
+      request(:put, path, params)
+    end
+
+    def patch(path, params={})
+      request(:patch, path, params)
+    end
+
+    def delete(path, params={})
+      request(:delete, path, params)
+    end
+
+    # Construct and send a request to the API.
+    #
+    # @raise [Timeout::Error] when the timeout expires
+    def request(method, path, params = {})
+      Timeout.timeout(overall_timeout) do
+        uri = URI.parse("#{api_endpoint}#{path}")
+
+        request = build_request(method, uri, params)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.open_timeout = open_timeout
+        http.read_timeout = overall_timeout
+
+        http.set_debug_output(STDERR) if debug?
+
+        if uri.scheme == 'https'
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.ca_file = File.join(File.dirname(__FILE__), '..', 'data', 'ca-bundle.crt')
+          http.ssl_timeout = open_timeout
+        end
+
+        @last_request = request
+
+        response = http.request(request)
+        response_json = parse_response(response)
+
+        case response
+        when Net::HTTPSuccess
+          return response_json
+        when Net::HTTPBadRequest
+          raise SwiftypeAppSearch::BadRequest, response_json
+        when Net::HTTPUnauthorized
+          raise SwiftypeAppSearch::InvalidCredentials, response_json
+        when Net::HTTPNotFound
+          raise SwiftypeAppSearch::NonExistentRecord, response_json
+        when Net::HTTPForbidden
+          raise SwiftypeAppSearch::Forbidden, response_json
+        else
+          raise SwiftypeAppSearch::UnexpectedHTTPException, response
+        end
+      end
+    end
+
+    private
+
+    def parse_response(response)
+      body = response.body.to_s.strip
+      body == '' ? {} : JSON.parse(body)
+    end
+
+    def debug?
+      @debug ||= (ENV['AS_DEBUG'] == 'true')
+    end
+
+    def build_request(method, uri, params)
+      klass = case method
+              when :get
+                Net::HTTP::Get
+              when :post
+                Net::HTTP::Post
+              when :put
+                Net::HTTP::Put
+              when :patch
+                Net::HTTP::Patch
+              when :delete
+                Net::HTTP::Delete
+              end
+
+      req = klass.new(uri.request_uri)
+      req.body = JSON.generate(params) unless params.length == 0
+
+      req['User-Agent'] = DEFAULT_USER_AGENT
+      req['Content-Type'] = 'application/json'
+      req['Authorization'] = "Bearer #{api_key}"
+
+      req
+    end
+  end
+end

data/lib/swiftype-app-search/utils.rb

@@ -0,0 +1,18 @@
+module SwiftypeAppSearch
+  module Utils
+    extend self
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) do |(key, value), out|
+        out[key.to_s] = value
+      end
+    end
+
+    def symbolize_keys(hash)
+      hash.each_with_object({}) do |(key, value), out|
+        new_key = key.respond_to?(:to_sym) ? key.to_sym : key
+        out[new_key] = value
+      end
+    end
+  end
+end

data/lib/swiftype-app-search/version.rb

@@ -0,0 +1,3 @@
+module SwiftypeAppSearch
+  VERSION = '0.1.0'
+end

data/script/console

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path('../../lib', __FILE__)
+
+require 'swiftype-app-search'
+require 'irb'
+require 'irb/completion'
+
+IRB.start

data/spec/client_spec.rb

@@ -0,0 +1,89 @@
+describe SwiftypeAppSearch::Client do
+  let(:engine_name) { "ruby-client-test-#{Time.now.to_i}" }
+
+  include_context "App Search Credentials"
+  let(:client) { SwiftypeAppSearch::Client.new(:account_host_key => as_account_host_key, :api_key => as_api_key) }
+
+  context 'Documents' do
+    %i[index_documents].each do |method|
+      context "##{method}" do
+        it 'should validate required document fields' do
+          documents = [{'url' => 'http://www.youtube.com/watch?v=v1uyQZNg2vE'}]
+          expect do
+            client.public_send(method, engine_name, documents)
+          end.to raise_error(SwiftypeAppSearch::InvalidDocument, 'Error: missing required fields (id)')
+        end
+      end
+    end
+  end
+
+  context 'Engines' do
+    after do
+      # Clean up the test engine from our account
+      begin
+        client.destroy_engine(engine_name)
+      rescue SwiftypeAppSearch::NonExistentRecord
+      end
+    end
+
+    context '#create_engine' do
+      it 'should create an engine when given a right set of parameters' do
+        expect { client.get_engine(engine_name) }.to raise_error(SwiftypeAppSearch::NonExistentRecord)
+        client.create_engine(engine_name)
+        expect { client.get_engine(engine_name) }.to_not raise_error
+      end
+
+      it 'should return an engine object' do
+        engine = client.create_engine(engine_name)
+        expect(engine).to be_kind_of(Hash)
+        expect(engine['name']).to eq(engine_name)
+      end
+
+      it 'should return an error when the engine name has already been taken' do
+        client.create_engine(engine_name)
+        expect { client.create_engine(engine_name) }.to raise_error do |e|
+          expect(e).to be_a(SwiftypeAppSearch::BadRequest)
+          expect(e.errors).to eq(['Name is already taken'])
+        end
+      end
+    end
+
+    context '#list_engines' do
+      it 'should return an array with a list of engines' do
+        expect(client.list_engines).to be_an(Array)
+      end
+
+      it 'should include the engine name in listed objects' do
+        # Create an engine
+        client.create_engine(engine_name)
+
+        # Get the list
+        engines = client.list_engines
+        expect(engines.find { |e| e['name'] == engine_name }).to_not be_nil
+      end
+    end
+
+    context '#destroy_engine' do
+      it 'should destroy the engine if it exists' do
+        client.create_engine(engine_name)
+        expect { client.get_engine(engine_name) }.to_not raise_error
+
+        client.destroy_engine(engine_name)
+        expect { client.get_engine(engine_name) }.to raise_error(SwiftypeAppSearch::NonExistentRecord)
+      end
+
+      it 'should raise an error if the engine does not exist' do
+        expect { client.destroy_engine(engine_name) }.to raise_error(SwiftypeAppSearch::NonExistentRecord)
+      end
+    end
+  end
+
+  context 'Configuration' do
+    context 'account_host_key' do
+      it 'sets the base url correctly' do
+        client = SwiftypeAppSearch::Client.new(:account_host_key => 'host-asdf', :api_key => 'foo')
+        expect(client.api_endpoint).to eq('https://host-asdf.api.swiftype.com/api/as/v1/')
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+require 'bundler/setup'
+require 'rspec'
+require 'webmock'
+require 'awesome_print'
+require 'swiftype-app-search'
+
+RSpec.shared_context "App Search Credentials" do
+  let(:as_api_key) { ENV.fetch('AS_API_KEY', 'API_KEY') }
+  let(:as_account_host_key) { ENV.fetch('AS_ACCOUNT_HOST_KEY', 'ACCOUNT_HOST_KEY') }
+end
+
+RSpec.configure do |config|
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = "random"
+end