square.rb 43.0.1.20250716 → 44.0.0.0

data/lib/square/internal/types/type.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Square
+  module Internal
+    module Types
+      # @abstract
+      module Type
+        include Square::Internal::JSON::Serializable
+
+        # Coerces a value to this type
+        #
+        # @param value [unknown]
+        # @option strict [Boolean] If we should strictly coerce this value
+        def coerce(value, strict: strict?)
+          raise NotImplementedError
+        end
+
+        # Returns if strictness is on for this type, defaults to `false`
+        #
+        # @return [Boolean]
+        def strict?
+          @strict ||= false
+        end
+
+        # Enable strictness by default for this type
+        #
+        # @return [void]
+        def strict!
+          @strict = true
+          self
+        end
+      end
+    end
+  end
+end

data/lib/square/internal/types/union.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Square
+  module Internal
+    module Types
+      # Define a union between two types
+      module Union
+        include Square::Internal::Types::Type
+
+        def members
+          @members ||= []
+        end
+
+        # Add a member to this union
+        #
+        # @param type [Object]
+        # @option key [Symbol, String]
+        # @return [void]
+        def member(type, key: nil)
+          members.push([key, Utils.wrap_type(type)])
+          self
+        end
+
+        def member?(type)
+          members.any? { |_key, type_fn| type == type_fn.call }
+        end
+
+        # Set the discriminant for this union
+        #
+        # @param key [Symbol, String]
+        # @return [void]
+        def discriminant(key)
+          @discriminant = key
+        end
+
+        # @api private
+        private def discriminated?
+          !@discriminant.nil?
+        end
+
+        # Resolves the type of a value to be one of the members
+        #
+        # @param value [Object]
+        # @return [Class]
+        private def resolve_member(value)
+          if discriminated? && value.is_a?(::Hash)
+            disciminant_value = value.fetch(@discriminant, nil)
+
+            return if disciminant_value.nil?
+
+            members.to_h[disciminant_value]&.call
+          else
+            members.find do |_key, mem|
+              member_type = Utils.unwrap_type(mem)
+
+              value.is_a?(member_type)
+            end&.last&.call
+          end
+        end
+
+        def coerce(value, strict: strict?)
+          type = resolve_member(value)
+
+          unless type
+            return value unless strict
+
+            if discriminated?
+              raise Errors::TypeError,
+                    "value of type `#{value.class}` not member of union #{self}"
+            end
+
+            raise Errors::TypeError, "could not resolve to member of union #{self}"
+          end
+
+          Utils.coerce(type, value, strict: strict)
+        end
+      end
+    end
+  end
+end

data/lib/square/internal/types/unknown.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Square
+  module Internal
+    module Types
+      module Unknown
+        include Square::Internal::Types::Type
+
+        def coerce(value)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/square/internal/types/utils.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Square
+  module Internal
+    module Types
+      # Utilities for dealing with and checking types
+      module Utils
+        # Wraps a type into a type function
+        #
+        # @param type [Proc, Object]
+        # @return [Proc]
+        def self.wrap_type(type)
+          case type
+          when Proc
+            type
+          else
+            -> { type }
+          end
+        end
+
+        # Resolves a type or type function into a type
+        #
+        # @param type [Proc, Object]
+        # @return [Object]
+        def self.unwrap_type(type)
+          type.is_a?(Proc) ? type.call : type
+        end
+
+        def self.coerce(target, value, strict: false) # rubocop:disable Metrics/CyclomaticComplexity
+          type = unwrap_type(target)
+
+          case type
+          in Array
+            case value
+            when ::Array
+              return type.coerce(value, strict: strict)
+            when Set, ::Hash
+              return coerce(type, value.to_a)
+            end
+          in Hash
+            case value
+            when ::Hash
+              return type.coerce(value, strict: strict)
+            when ::Array
+              return coerce(type, value.to_h)
+            end
+          in ->(t) { t <= NilClass }
+            return nil
+          in ->(t) { t <= String }
+            case value
+            when String, Symbol, Numeric, TrueClass, FalseClass
+              return value.to_s
+            end
+          in ->(t) { t <= Symbol }
+            case value
+            when Symbol, String
+              return value.to_sym
+            end
+          in ->(t) { t <= Integer }
+            case value
+            when Numeric, String, Time
+              return value.to_i
+            end
+          in ->(t) { t <= Float }
+            case value
+            when Numeric, Time, String
+              return value.to_f
+            end
+          in ->(t) { t <= Model }
+            case value
+            when type
+              return value
+            when ::Hash
+              return type.coerce(value, strict: strict)
+            end
+          in Module
+            case type
+            in ->(t) { t.singleton_class.included_modules.include?(Enum) }
+              return type.coerce(value, strict: strict)
+            in ->(t) { t.singleton_class.included_modules.include?(Union) }
+              return type.coerce(value, strict: strict)
+            else
+              value
+            end
+          else
+            value
+          end
+
+          raise Errors::TypeError, "cannot coerce value of type `#{value.class}` to `#{target}`" if strict
+
+          value
+        end
+
+        def self.symbolize_keys(hash)
+          hash.transform_keys(&:to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/square/inventory/client.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Square
+  module Inventory
+    class Client
+      # @return [Square::Inventory::Client]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Deprecated version of [RetrieveInventoryAdjustment](api-endpoint:Inventory-RetrieveInventoryAdjustment) after the endpoint URL
+      # is updated to conform to the standard convention.
+      #
+      # @return [Square::Types::GetInventoryAdjustmentResponse]
+      def deprecated_get_adjustment(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/inventory/adjustment/#{params[:adjustment_id]}"
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::GetInventoryAdjustmentResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Returns the [InventoryAdjustment](entity:InventoryAdjustment) object
+      # with the provided `adjustment_id`.
+      #
+      # @return [Square::Types::GetInventoryAdjustmentResponse]
+      def get_adjustment(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/inventory/adjustments/#{params[:adjustment_id]}"
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::GetInventoryAdjustmentResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Deprecated version of [BatchChangeInventory](api-endpoint:Inventory-BatchChangeInventory) after the endpoint URL
+      # is updated to conform to the standard convention.
+      #
+      # @return [Square::Types::BatchChangeInventoryResponse]
+      def deprecated_batch_change(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "POST",
+          path: "v2/inventory/batch-change",
+          body: Square::Types::BatchChangeInventoryRequest.new(params).to_h
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::BatchChangeInventoryResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Deprecated version of [BatchRetrieveInventoryChanges](api-endpoint:Inventory-BatchRetrieveInventoryChanges) after the endpoint URL
+      # is updated to conform to the standard convention.
+      #
+      # @return [Square::Types::BatchGetInventoryChangesResponse]
+      def deprecated_batch_get_changes(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "POST",
+          path: "v2/inventory/batch-retrieve-changes",
+          body: Square::Types::BatchRetrieveInventoryChangesRequest.new(params).to_h
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::BatchGetInventoryChangesResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Deprecated version of [BatchRetrieveInventoryCounts](api-endpoint:Inventory-BatchRetrieveInventoryCounts) after the endpoint URL
+      # is updated to conform to the standard convention.
+      #
+      # @return [Square::Types::BatchGetInventoryCountsResponse]
+      def deprecated_batch_get_counts(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "POST",
+          path: "v2/inventory/batch-retrieve-counts",
+          body: Square::Types::BatchGetInventoryCountsRequest.new(params).to_h
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::BatchGetInventoryCountsResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Applies adjustments and counts to the provided item quantities.
+      #
+      # On success: returns the current calculated counts for all objects
+      # referenced in the request.
+      # On failure: returns a list of related errors.
+      #
+      # @return [Square::Types::BatchChangeInventoryResponse]
+      def batch_create_changes(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "POST",
+          path: "v2/inventory/changes/batch-create",
+          body: Square::Types::BatchChangeInventoryRequest.new(params).to_h
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::BatchChangeInventoryResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Returns historical physical counts and adjustments based on the
+      # provided filter criteria.
+      #
+      # Results are paginated and sorted in ascending order according their
+      # `occurred_at` timestamp (oldest first).
+      #
+      # BatchRetrieveInventoryChanges is a catch-all query endpoint for queries
+      # that cannot be handled by other, simpler endpoints.
+      #
+      # @return [Square::Types::BatchGetInventoryChangesResponse]
+      def batch_get_changes(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "POST",
+          path: "v2/inventory/changes/batch-retrieve",
+          body: Square::Types::BatchRetrieveInventoryChangesRequest.new(params).to_h
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::BatchGetInventoryChangesResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Returns current counts for the provided
+      # [CatalogObject](entity:CatalogObject)s at the requested
+      # [Location](entity:Location)s.
+      #
+      # Results are paginated and sorted in descending order according to their
+      # `calculated_at` timestamp (newest first).
+      #
+      # When `updated_after` is specified, only counts that have changed since that
+      # time (based on the server timestamp for the most recent change) are
+      # returned. This allows clients to perform a "sync" operation, for example
+      # in response to receiving a Webhook notification.
+      #
+      # @return [Square::Types::BatchGetInventoryCountsResponse]
+      def batch_get_counts(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "POST",
+          path: "v2/inventory/counts/batch-retrieve",
+          body: Square::Types::BatchGetInventoryCountsRequest.new(params).to_h
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::BatchGetInventoryCountsResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Deprecated version of [RetrieveInventoryPhysicalCount](api-endpoint:Inventory-RetrieveInventoryPhysicalCount) after the endpoint URL
+      # is updated to conform to the standard convention.
+      #
+      # @return [Square::Types::GetInventoryPhysicalCountResponse]
+      def deprecated_get_physical_count(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/inventory/physical-count/#{params[:physical_count_id]}"
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::GetInventoryPhysicalCountResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Returns the [InventoryPhysicalCount](entity:InventoryPhysicalCount)
+      # object with the provided `physical_count_id`.
+      #
+      # @return [Square::Types::GetInventoryPhysicalCountResponse]
+      def get_physical_count(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/inventory/physical-counts/#{params[:physical_count_id]}"
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::GetInventoryPhysicalCountResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Returns the [InventoryTransfer](entity:InventoryTransfer) object
+      # with the provided `transfer_id`.
+      #
+      # @return [Square::Types::GetInventoryTransferResponse]
+      def get_transfer(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/inventory/transfers/#{params[:transfer_id]}"
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::GetInventoryTransferResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Retrieves the current calculated stock count for a given
+      # [CatalogObject](entity:CatalogObject) at a given set of
+      # [Location](entity:Location)s. Responses are paginated and unsorted.
+      # For more sophisticated queries, use a batch endpoint.
+      #
+      # @return [Square::Types::GetInventoryCountResponse]
+      def get(request_options: {}, **params)
+        _query_param_names = %w[location_ids cursor]
+        _query = params.slice(*_query_param_names)
+        params = params.except(*_query_param_names)
+
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/inventory/#{params[:catalog_object_id]}",
+          query: _query
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::GetInventoryCountResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Returns a set of physical counts and inventory adjustments for the
+      # provided [CatalogObject](entity:CatalogObject) at the requested
+      # [Location](entity:Location)s.
+      #
+      # You can achieve the same result by calling [BatchRetrieveInventoryChanges](api-endpoint:Inventory-BatchRetrieveInventoryChanges)
+      # and having the `catalog_object_ids` list contain a single element of the `CatalogObject` ID.
+      #
+      # Results are paginated and sorted in descending order according to their
+      # `occurred_at` timestamp (newest first).
+      #
+      # There are no limits on how far back the caller can page. This endpoint can be
+      # used to display recent changes for a specific item. For more
+      # sophisticated queries, use a batch endpoint.
+      #
+      # @return [Square::Types::GetInventoryChangesResponse]
+      def changes(request_options: {}, **params)
+        _query_param_names = %w[location_ids cursor]
+        _query = params.slice(*_query_param_names)
+        params = params.except(*_query_param_names)
+
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/inventory/#{params[:catalog_object_id]}/changes",
+          query: _query
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::GetInventoryChangesResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+    end
+  end
+end

data/lib/square/inventory/types/changes_inventory_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Square
+  module Inventory
+    module Types
+      class ChangesInventoryRequest < Internal::Types::Model
+        field :catalog_object_id, -> { String }, optional: false, nullable: false
+        field :location_ids, -> { String }, optional: true, nullable: false
+        field :cursor, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/square/inventory/types/deprecated_get_adjustment_inventory_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Square
+  module Inventory
+    module Types
+      class DeprecatedGetAdjustmentInventoryRequest < Internal::Types::Model
+        field :adjustment_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/square/inventory/types/deprecated_get_physical_count_inventory_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Square
+  module Inventory
+    module Types
+      class DeprecatedGetPhysicalCountInventoryRequest < Internal::Types::Model
+        field :physical_count_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/square/inventory/types/get_adjustment_inventory_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Square
+  module Inventory
+    module Types
+      class GetAdjustmentInventoryRequest < Internal::Types::Model
+        field :adjustment_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/square/inventory/types/get_inventory_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Square
+  module Inventory
+    module Types
+      class GetInventoryRequest < Internal::Types::Model
+        field :catalog_object_id, -> { String }, optional: false, nullable: false
+        field :location_ids, -> { String }, optional: true, nullable: false
+        field :cursor, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/square/inventory/types/get_physical_count_inventory_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Square
+  module Inventory
+    module Types
+      class GetPhysicalCountInventoryRequest < Internal::Types::Model
+        field :physical_count_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/square/inventory/types/get_transfer_inventory_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Square
+  module Inventory
+    module Types
+      class GetTransferInventoryRequest < Internal::Types::Model
+        field :transfer_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end