yext-api 0.1.1

data/lib/tasks/yext/api_tasks.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# desc "Explaining what the task does"
+# task :yext_api do
+#   # Task goes here
+# end

data/lib/yext/api.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "yext/api/engine"
+
+module Yext
+  # API interface for Yext
+  module Api
+    # Allows you to configure global settings for the Yext::Api.
+    #
+    # See Yext::Api::Utils::Configuration for details on the configuration options.
+    #
+    # Usage:
+    #
+    # Yext::Api.configure do |config|
+    #   config.account_id = "my account_id"
+    #   config.api_key    = "my api key"
+    # end
+    def self.configure
+      yield configuration if block_given?
+    end
+
+    # Gets the configuration object for configuring a single item.
+    #
+    # See Yext::Api::Utils::Configuration for details on the configuration options.
+    #
+    # Usage:
+    #
+    # Yext::Api.configuration.api_key = "my api key"
+    def self.configuration
+      Yext::Api::Utils::Configuration.instance
+    end
+  end
+end

data/lib/yext/api/administrative_api.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    # http://developer.yext.com/docs/administrative-api
+    #
+    # Yext Administrative API
+    module AdministrativeApi
+      extend Yext::Api::Concerns::RateLimits
+    end
+  end
+end

data/lib/yext/api/administrative_api/account.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module AdministrativeApi
+      # :administrative_api:
+      #   :account:
+      #     :actions:
+      #       - :action: :create
+      #         :method: :post
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/newlocationaddrequests
+      #         :path_regex: v2/accounts/\w+/newlocationaddrequests
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/createNewLocationAddRequest
+      #         :comment: Request that a new location be added and services added to it. The location is created only if the request succeeds.
+      #         :sandbox_only: false
+      #       - :action: :add_services
+      #         :method: :post
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/existinglocationaddrequests
+      #         :path_regex: v2/accounts/\w+/existinglocationaddrequests
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/createExistingLocationAddRequest
+      #         :comment: Request that one or more available services be added to an existing location.
+      #         :sandbox_only: false
+      #       - :action: :change_status
+      #         :method: :post
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/processaddrequest
+      #         :path_regex: v2/accounts/\w+/processaddrequest
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/createProcessReviewAddRequest
+      #         :comment: Request that an add request in REVIEW be processed to COMPLETE, CANCELED, or FAILED.
+      #         :sandbox_only: true
+      #       - :action: :index
+      #         :method: :get
+      #         :endpoint: https://api.yext.com/v2/accounts
+      #         :path_regex: v2/accounts
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/listAccounts
+      #         :comment: List all accounts that you have access to. Unless you are in Partner Portal mode, this will only be your own account.
+      #         :sandbox_only: false
+      #       - :action: :show
+      #         :method: :get
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}
+      #         :path_regex: v2/accounts/\w+
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/getAccount
+      #         :comment: Get details for an account.
+      #         :sandbox_only: false
+      #       - :action: :update
+      #         :method: :put
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}
+      #         :path_regex: v2/accounts/\w+
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/updateAccount
+      #         :comment: Update an account's name or ID.
+      #         :sandbox_only: false
+      class Account < Yext::Api::Utils::ApiBase
+        include Yext::Api::Concerns::AccountRelations
+      end
+    end
+  end
+end

data/lib/yext/api/administrative_api/add_request.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# TODO: Complete and test.  Untested initial framework class.
+module Yext
+  module Api
+    module AdministrativeApi
+      # :administrative_api:
+      #   :add_request:
+      #     :actions:
+      #       - :action: :index
+      #         :method: :get
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/addrequests
+      #         :path_regex: v2/accounts/[^/]+?/addrequests
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/listAddRequests
+      #         :comment: Get all of the add requests in the account. The response includes both New Location
+      #                   Add Requests and Existing Location Add Requests.
+      #         :sandbox_only: false
+      #       - :action: :show
+      #         :method: :get
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/addrequests/{addRequestId}
+      #         :path_regex: v2/accounts/[^/]+?/addrequests/[^/]+??
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/getAddRequest
+      #         :comment: Get status information about an add request previously created.
+      #         :sandbox_only: false
+      class AddRequest < Yext::Api::Utils::ApiBase
+        uri("addrequests/(:id)")
+
+        include Yext::Api::Concerns::AccountChild
+      end
+    end
+  end
+end

data/lib/yext/api/administrative_api/service.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module AdministrativeApi
+      # :administrative_api:
+      #   :service:
+      #     :actions:
+      #       - :action: :available
+      #         :method: :get
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/availableservices
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/listAvailableServices
+      #         :comment: Return list of services available to you under your agreements.
+      #         :sandbox_only: false
+      #       - :action: :index
+      #         :method: :get
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/services
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/listServices
+      #         :comment: Retrieve a list of all services provisioned through this account.
+      #         :sandbox_only: false
+      #       - :action: :destroy
+      #         :method: :post
+      #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/cancelservices
+      #         :default_version: 20161012
+      #         :documentation: http://developer.yext.com/docs/administrative-api/#operation/cancelServices
+      #         :comment: Cancel one or more active services.
+      #         :sandbox_only: false
+      class Service < Yext::Api::Utils::ApiBase
+        include Yext::Api::Concerns::AccountChild
+
+        scope :available, -> { with(Yext::Api::Concerns::AccountChild.with_account_path("availableservices")) }
+        scope :cancel_services, -> { with(Yext::Api::Concerns::AccountChild.with_account_path("cancelservices")) }
+      end
+    end
+  end
+end

data/lib/yext/api/concerns/account_child.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Concerns
+      # This concern prepends the `accounts/:account_id/` path to the URI for classes which require it.
+      #
+      # The account_id can be set in the following ways:
+      #   * Global configuration:
+      #     * Yext::Api.configuration.account_id = new_account_id
+      #   * For an individual call:
+      #     * SpykeClass.with_account(new_account_id)
+      #     * SpykeClass.where(account_id: new_account_id)
+      #
+      # NOTE:  This will not work if the DefaultParameters middleware is not being used.
+      #
+      # If the class that this is included in uses a custom URI, the `uri` call must be made before this
+      # module is included.
+      module AccountChild
+        extend ActiveSupport::Concern
+
+        class << self
+          def with_account_path(path)
+            File.join("accounts/:account_id", path)
+          end
+
+          def ensure_relation(klass)
+            [Yext::Api::KnowledgeApi::AccountSettings::Account, Yext::Api::AdministrativeApi::Account].each do |account_class|
+              next if account_class.instance_methods.include?("#{klass.model_name.element}_ids".to_sym)
+
+              klass_uri = klass.instance_variable_get(:@uri)
+              helper_warnings(account_class, klass, klass_uri)
+              klass_uri ||= klass.send(:default_uri)
+
+              add_has_many_relation(account_class, klass, klass_uri)
+            end
+          end
+
+          private
+
+          def add_has_many_relation(account_class, klass, klass_uri)
+            account_class.class_eval do
+              has_many klass.model_name.element.pluralize.to_sym,
+                       class_name: klass.name,
+                       uri:        Yext::Api::Concerns::AccountChild.with_account_path(klass_uri)
+            end
+          end
+
+          def helper_warnings(account_class, klass, klass_uri)
+            klass_name    = klass.name
+            relation_name = klass.model_name.element.pluralize
+
+            puts "WARNING! #{account_class.name} does not include the relationship for #{klass_name}"
+            puts " Add the following line to Yext::Api::Concerns::AccountRelations:"
+
+            if klass_uri && klass_uri != klass.send(:default_uri)
+              puts "   has_many :#{relation_name}, class_name: \"#{klass_name}\", " \
+                       "uri: Yext::Api::Concerns::AccountChild.with_account_path(\"#{klass_uri}\")"
+            else
+              puts "   has_many :#{relation_name}, class_name: \"#{klass_name}\""
+            end
+          end
+        end
+
+        included do
+          scope(:with_account, lambda do |account_or_id|
+            if account_or_id.is_a?(Yext::Api::KnowledgeApi::AccountSettings::Account) ||
+                account_or_id.is_a?(Yext::Api::AdministrativeApi::Account)
+              account_or_id
+            else
+              Yext::Api::KnowledgeApi::AccountSettings::Account.new(id: account_or_id)
+            end.public_send(model_name.element.pluralize)
+          end)
+
+          Yext::Api::Concerns::AccountChild.ensure_relation(self)
+        end
+
+        class_methods do
+          def all
+            if current_scope.nil?
+              Yext::Api::KnowledgeApi::AccountSettings::Account.
+                  new(id: Yext::Api.configuration.account_id || "me").
+                  public_send(model_name.element.pluralize)
+            else
+              current_scope
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/concerns/account_relations.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Concerns
+      # Because the Account is listed in the API documentation in two locations, there are two
+      # different but somewhat identical Account objects.
+      #
+      # This module includes the shared code between the two.
+      module AccountRelations
+        extend ActiveSupport::Concern
+
+        # The module AccountChild will add these relations if they are missing, but if they are
+        # listed explicitly it is more efficient.
+        included do
+          has_many :add_requests,
+                   class_name: "Yext::Api::AdministrativeApi::AddRequest",
+                   uri:        Yext::Api::Concerns::AccountChild.with_account_path("addrequests/(:id)")
+          has_many :locations, class_name: "Yext::Api::KnowledgeApi::KnowledgeManager::Location"
+          has_many :services, class_name: "Yext::Api::AdministrativeApi::Service"
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/concerns/api_finder.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Concerns
+      # This module add the `find_api` method to a class to allow the searching of the base
+      # api category module for a particular route.
+      module ApiFinder
+        def find_api(url, method)
+          return if url.nil? || method.nil?
+          return Yext::Api::LiveApi if url.host.include?("liveapi")
+
+          hash = YAML.load_file(Yext::Api::Engine.root.join("lib/config/api.yml"))
+
+          hash.each_key do |hash_key|
+            guess_api = api_from_key(hash_key)
+
+            next if guess_api.blank?
+
+            return guess_api if found_route?(hash[hash_key], url.path, method.to_s)
+          end
+
+          nil
+        end
+
+        private
+
+        def found_route?(hash, path, method)
+          hash.each do |key_name, sub_hash|
+            if sub_hash.is_a?(Hash)
+              return true if found_route?(sub_hash, path, method)
+            elsif key_name == :actions
+              return true if found_action?(sub_hash, path, method)
+            end
+          end
+
+          false
+        end
+
+        def found_action?(actions, path, method)
+          actions.each do |action|
+            next if action[:path_regex].blank?
+            next if action[:method].to_s != method
+
+            return true if Regexp.new("#{action[:path_regex]}$").match(path)
+          end
+
+          false
+        end
+
+        def api_from_key(hash_key)
+          "Yext::Api::#{hash_key.to_s.classify}".constantize
+        rescue NameError
+          # :nocov:
+          nil
+          # :nocov:
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/concerns/default_scopes.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Concerns
+      # This module adds default scopes that will specify configurations to be overridden for a
+      # particular call.
+      #
+      # If these scopes are used, the values passed in will be used in the API call, if the scope
+      # is not used, then the DefaultParameters middleware will insert the default values.
+      module DefaultScopes
+        extend ActiveSupport::Concern
+
+        included do
+          scope(:with_version, ->(version) { where(v: version) })
+          scope(:with_application, ->(app_id) { where(api_key: app_id) })
+          scope(:yext_username, ->(username) { where(yext_username: username) })
+          scope(:yext_user_id, ->(user_id) { where(yext_user_id: user_id) })
+
+          scope(:validate, lambda do |validation = Yext::Api::Enumerations::Validation::STRICT|
+            if validation.is_a?(String)
+              validation = Yext::Api::Enumerations::Validation::STRICT unless Yext::Api::Enumerations::Validation.all.include?(validation)
+            else
+              validation = if validation
+                             Yext::Api::Enumerations::Validation::STRICT
+                           else
+                             Yext::Api::Enumerations::Validation::LENIENT
+                           end
+            end
+
+            where(validation: validation)
+          end)
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/concerns/enum_all.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Concerns
+      # This concern adds an `all` method to an enumeration class to list all constants in that class.
+      module EnumAll
+        extend ActiveSupport::Concern
+
+        class_methods do
+          def all
+            (constants - %i[ClassMethods]).map { |c| const_get(c) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/concerns/faraday_connection.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Concerns
+      # This module defines methods that set the connection for a Spyke class.
+      #
+      # The default connection is to the sandbox or the API based on the value of the configuration
+      # sandbox setting.
+      #
+      # A class function live_api is provided to allow LiveApi module classes to use the live endpoint.
+      module FaradayConnection
+        extend ActiveSupport::Concern
+
+        included do
+          url = if Yext::Api.configuration.sandbox
+                  "https://sandbox.yext.com/v2"
+                else
+                  "https://api.yext.com/v2"
+                end
+
+          self.connection = Yext::Api::Concerns::FaradayConnection.faraday_connection(url)
+        end
+
+        class_methods do
+          def live_api
+            self.connection = Yext::Api::Concerns::FaradayConnection.faraday_connection("https://live.yext.com/v2")
+          end
+        end
+
+        def self.faraday_connection(url)
+          Faraday.new(url: url) do |c|
+            c.request :json
+
+            c.use Yext::Api::Utils::ResponseParser
+            c.use Yext::Api::Utils::DefaultParameters
+            c.use Yext::Api::Utils::ApiRateLimits
+
+            c.adapter Faraday.default_adapter
+          end
+        end
+      end
+    end
+  end
+end