yext-api 0.1.1 → 0.1.3

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

@@ -6,37 +6,12 @@ module Yext
       # :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
@@ -44,7 +19,6 @@ module Yext
       #         :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
@@ -52,10 +26,46 @@ module Yext
       #         :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
+
+        after_save :save_account_id
+
+        # The save action only allows the saving of the account_id and the accountName
+        #
+        # Furthermore, the account_id cannot be changed by the partner, but only by the customer
+        # themselves.
+        def save
+          return unless accountId?
+
+          updates             = { account_id: account_id, accountName: accountName }
+          updates[:accountId] = accountId if accountId != account_id
+
+          scope.with(Yext::Api::Concerns::AccountChild.with_account_path("")).
+              where(updates).
+              put
+
+          save_account_id
+        end
+
+        # rubocop:disable Naming/MethodName
+
+        # Yext field names don't match the Ruby naming standard, this is the field name they use.
+        # Because I use `account_id` in the route, I need that attribute defined.  Because
+        # Yext uses accountId, when it is set, I need to set `account_id` so they will match.
+        def accountId=(value)
+          super
+          attributes[:account_id] ||= value
+        end
+
+        # rubocop:enable Naming/MethodName
+
+        private
+
+        def save_account_id
+          attributes[:account_id] = accountId
+        end
       end
     end
   end

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

@@ -13,8 +13,6 @@ module Yext
       #         :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
@@ -22,12 +20,98 @@ module Yext
       #         :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
+      #       - :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
+      #         :sandbox_only: false
+      #       - :action: :update
+      #         :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
+      #         :sandbox_only: true
+      #       - :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
       #         :sandbox_only: false
       class AddRequest < Yext::Api::Utils::ApiBase
         uri("addrequests/(:id)")
 
         include Yext::Api::Concerns::AccountChild
+
+        # This is a helper method to try to simplify changing the status of an AddRequest if you
+        # don't have an AddRequest object.
+        #
+        # Some examples of ways to change a status:
+        #   Yext::Api::AdministrativeApi::AddRequest.change_status!(request_id, Yext::Api::Enumerations::AddRequestStatus::COMPLETE)
+        #   Yext::Api::AdministrativeApi::AddRequest.new(id: request_id, status: Yext::Api::Enumerations::AddRequestStatus::COMPLETE).save
+        #   add_request = Yext::Api::AdministrativeApi::AddRequest.find(request_id)
+        #     add_request.status = Yext::Api::Enumerations::AddRequestStatus::COMPLETE)
+        #     add_request.save
+        def self.change_status!(request_id, new_status)
+          raise InvalidArgument "invalid status" unless Yext::Api::Enumerations::AddRequestStatus.all.include?(new_status)
+
+          new(id: request_id, status: new_status).save
+        end
+
+        # A method as scope to add services to an AddRequest.  This feature is here because it is documented
+        # in the AdministrativeApi as basically a method on the AddRequest concept.
+        #
+        # The Location contains an instance method to do this without having to pass in the
+        # arguments hash:
+        #
+        # Some examples of ways to add services:
+        #   Yext::Api::AdministrativeApi::AddRequest.add_services! existingLocationId:        location_id
+        #                                                          existingLocationAccountId: child_account_id,
+        #                                                          skus:                      [sku]
+        #
+        #   location = Yext::KnowledgeApi::KnowledgeManager::Location.account(child_account_id).find(location_id)
+        #     location.add_services! skus: [sku]
+        #
+        #   location = Yext::KnowledgeApi::KnowledgeManager::Location.new(account_id: child_account_id, id: location_id)
+        #     location.add_services! skus: [sku]
+        scope(:add_services!, lambda do |location_update_hash = {}|
+          args = scope_args(true)
+
+          args.merge!(location_update_hash)
+
+          Yext::Api::AdministrativeApi::Account.
+              where(args).
+              with(:existinglocationaddrequests).
+              post
+        end)
+
+        def save
+          if persisted?
+            change_status
+          else
+            create_new_location
+          end
+        end
+
+        private
+
+        def create_new_location
+          scope.
+              with(Yext::Api::Concerns::AccountChild.with_account_path("newlocationaddrequests")).
+              where(attributes.reverse_merge(account_id: Yext::Api.configuration.param_account_id)).
+              post
+        end
+
+        def change_status
+          scope.
+              with(Yext::Api::Concerns::AccountChild.with_account_path("processaddrequest")).
+              where(addRequestId: id, status: status).
+              post
+        end
       end
     end
   end

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

@@ -11,27 +11,49 @@ module Yext
       #         :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")) }
+
+        # A method as scope to cancel services for a location.  This feature is here because it is documented
+        # in the AdministrativeApi as basically a method on the Service concept.
+        #
+        # The Location contains an instance method to do this without having to pass in the
+        # arguments hash:
+        #
+        # Some examples of ways to add services:
+        #   Yext::Api::AdministrativeApi::Service.cancel_services! locationId: location_id
+        #                                                          skus:       [sku]
+        #
+        #   location = Yext::KnowledgeApi::KnowledgeManager::Location.account(child_account_id).find(location_id)
+        #     location.cancel_services! skus: [sku]
+        #
+        #   location = Yext::KnowledgeApi::KnowledgeManager::Location.new(id: location_id)
+        #     location.cancel_services! skus: [sku]
+        scope(:cancel_services!, lambda do |cancel_hash|
+          args = scope_args(true)
+
+          args.merge!(cancel_hash)
+
+          Yext::Api::AdministrativeApi::Account.
+              where(args).
+              with(:cancelservices).
+              post
+        end)
       end
     end
   end

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

@@ -9,7 +9,7 @@ module Yext
       #   * Global configuration:
       #     * Yext::Api.configuration.account_id = new_account_id
       #   * For an individual call:
-      #     * SpykeClass.with_account(new_account_id)
+      #     * SpykeClass.account(new_account_id)
       #     * SpykeClass.where(account_id: new_account_id)
       #
       # NOTE:  This will not work if the DefaultParameters middleware is not being used.
@@ -26,7 +26,7 @@ module Yext
 
           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)
+              next if account_class.association?(klass)
 
               klass_uri = klass.instance_variable_get(:@uri)
               helper_warnings(account_class, klass, klass_uri)
@@ -36,11 +36,17 @@ module Yext
             end
           end
 
+          def association_name(klass)
+            association_name = klass.parents.include?(Yext::Api::LiveApi) ? "live_" : ""
+
+            association_name + klass.model_name.element.pluralize
+          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,
+              has_many Yext::Api::Concerns::AccountChild.association_name(klass).to_sym,
                        class_name: klass.name,
                        uri:        Yext::Api::Concerns::AccountChild.with_account_path(klass_uri)
             end
@@ -48,7 +54,7 @@ module Yext
 
           def helper_warnings(account_class, klass, klass_uri)
             klass_name    = klass.name
-            relation_name = klass.model_name.element.pluralize
+            relation_name = Yext::Api::Concerns::AccountChild.association_name(klass)
 
             puts "WARNING! #{account_class.name} does not include the relationship for #{klass_name}"
             puts " Add the following line to Yext::Api::Concerns::AccountRelations:"
@@ -63,13 +69,13 @@ module Yext
         end
 
         included do
-          scope(:with_account, lambda do |account_or_id|
+          scope(: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.public_send(Yext::Api::Concerns::AccountChild.association_name(self))
           end)
 
           Yext::Api::Concerns::AccountChild.ensure_relation(self)
@@ -79,12 +85,35 @@ module Yext
           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)
+                  new(id: Yext::Api.configuration.param_account_id).
+                  public_send(Yext::Api::Concerns::AccountChild.association_name(self))
             else
               current_scope
             end
           end
+
+          def reset_uri
+            [Yext::Api::KnowledgeApi::AccountSettings::Account, Yext::Api::AdministrativeApi::Account].each do |account_class|
+              next unless account_class.association?(self)
+
+              klass_uri = instance_variable_get(:@uri) || default_uri
+
+              account_class.
+                  new.
+                  send(Yext::Api::Concerns::AccountChild.association_name(self)).
+                  with(Yext::Api::Concerns::AccountChild.with_account_path(klass_uri))
+            end
+          end
+
+          def scope_args(account_scope = false)
+            args = current_scope&.params&.dup || {}
+
+            args[:account_id] ||= Yext::Api.configuration.param_account_id
+
+            args[:id] = args.delete(:account_id) if account_scope
+
+            args
+          end
         end
       end
     end

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

@@ -13,11 +13,26 @@ module Yext
         # The module AccountChild will add these relations if they are missing, but if they are
         # listed explicitly it is more efficient.
         included do
+          # AdministrativeApi
           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"
+
+          # KnowledgeApi::KnowledgeManager
+          has_many :locations, class_name: "Yext::Api::KnowledgeApi::KnowledgeManager::Location"
+
+          # KnowledgeApi::AccountSettings
+          has_many :users, class_name: "Yext::Api::KnowledgeApi::AccountSettings::User"
+
+          # LiveApi
+          has_many :live_locations, class_name: "Yext::Api::LiveApi::Location"
+        end
+
+        class_methods do
+          def association?(klass)
+            associations.key?(Yext::Api::Concerns::AccountChild.association_name(klass).to_sym)
+          end
         end
       end
     end

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

@@ -12,8 +12,8 @@ module Yext
         extend ActiveSupport::Concern
 
         included do
-          scope(:with_version, ->(version) { where(v: version) })
-          scope(:with_application, ->(app_id) { where(api_key: app_id) })
+          scope(:version, ->(version) { where(v: version) })
+          scope(: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) })
 
@@ -31,6 +31,12 @@ module Yext
             where(validation: validation)
           end)
         end
+
+        class_methods do
+          def reset_uri
+            # do nothing.
+          end
+        end
       end
     end
   end

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

@@ -28,15 +28,29 @@ module Yext
           end
         end
 
-        def self.faraday_connection(url)
-          Faraday.new(url: url) do |c|
-            c.request :json
+        class << self
+          def faraday_connection(url)
+            Faraday.new(url: url) do |c|
+              c.request :json
+              c.request :retry,
+                        max:                 2,
+                        interval:            0.05,
+                        interval_randomness: 0.5,
+                        backoff_factor:      2
 
-            c.use Yext::Api::Utils::ResponseParser
-            c.use Yext::Api::Utils::DefaultParameters
-            c.use Yext::Api::Utils::ApiRateLimits
+              add_middleware(c)
 
-            c.adapter Faraday.default_adapter
+              c.adapter Faraday.default_adapter
+            end
+          end
+
+          private
+
+          def add_middleware(c)
+            c.use Yext::Api::Utils::Middleware::ResponseParser
+            c.use Yext::Api::Utils::Middleware::DefaultParameters
+            c.use Yext::Api::Utils::Middleware::ApiRateLimits
+            c.use Yext::Api::Utils::Middleware::UriCleanup
           end
         end
       end

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

@@ -10,7 +10,14 @@ module Yext
                     :rate_limit_limit,
                     :rate_limit_reset_at,
                     :last_status,
-                    :last_meta
+                    :last_meta,
+                    :last_data
+
+        private
+
+        def last_data=(last_data)
+          @last_data = last_data
+        end
 
         def last_status=(last_status)
           @last_status = last_status