square.rb 10.0.0.202104217 → 13.1.0.20210818

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1c9c3a6b13fa697e2fffc362d766cb1b7ded51f360ad7fcf342039d2623911d
-  data.tar.gz: 11954b03a0f85edec268ef6d4f7bb020386dfba4134f28a720c5b6c39b3c2315
+  metadata.gz: a624808dd5bb0375fef64adf65cbe8203c6b582bd38e34afb69b4b0c0f4fd8a4
+  data.tar.gz: 849966858b71f5a2b2f4abb9811561156172b591cf2a3c93886bee88c5ecff83
 SHA512:
-  metadata.gz: cc03189601f3985171af4af574f987b31d4c3132ffb96b7d4ada0996056309183a50d1f02a8af602a9a63543f0737903f336185a7e4284db324df74ff114f6e5
-  data.tar.gz: 042712b0f44ce7a117e7b1cd7f9286d4ada8c033d54b9e347e62a4dc491463fa984f5f0590c9a6d29ef0f3bade77199ee76eab60f4c7960c12a6e95d551acc15
+  metadata.gz: bcb9330214a8a813a1d6bf405db19dcd2264f70f1745b793c9cf7c844f340dc056cf7a141a0e12ca65187ee02d1c856ee59621ab2143f18e518bdc734bc9f35c
+  data.tar.gz: 5a93c48a1751fae253c1819fd0c4925b47e3998be01ad9af2acae45cbac6c4a6d9979bf4e0e36baa9475bd54c396135c5d136981fc4b87ec0c04d507cf259698

data/README.md

@@ -2,12 +2,16 @@
 
 # Square Ruby SDK
 
-[![Travis status](https://travis-ci.org/square/square-ruby-sdk.svg?branch=master)](https://travis-ci.org/square/square-ruby-sdk)
+[![Build](https://github.com/square/square-ruby-sdk/actions/workflows/ruby.yml/badge.svg)](https://github.com/square/square-ruby-sdk/actions/workflows/ruby.yml)
 [![Gem version](https://badge.fury.io/rb/square.rb.svg?new)](https://badge.fury.io/rb/square.rb)
 [![Apache-2 license](https://img.shields.io/badge/license-Apache2-brightgreen.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
 Use this gem to integrate Square payments into your app and grow your business with Square APIs including Catalog, Customers, Employees, Inventory, Labor, Locations, and Orders.
 
+## Requirements
+
+We support Ruby 2.5.x, 2.6.x, and 2.7.x.
+
 ## Installation
 
 Install the gem from the command line:
@@ -73,9 +77,13 @@ gem 'square.rb'
 ### Financials
 * [Bank Accounts]
 
+### Online
+* [Sites]
+* [Snippets]
+
 ### Authorization APIs
 * [Mobile Authorization]
-* [O Auth]
+* [OAuth]
 
 ### Deprecated APIs
 * [V1 Employees]
@@ -322,8 +330,10 @@ You can also use the Square API to create applications or services that work wit
 [Refunds]: doc/api/refunds.md
 [Subscriptions]: doc/api/subscriptions.md
 [Mobile Authorization]: doc/api/mobile-authorization.md
-[O Auth]: doc/api/o-auth.md
+[OAuth]: doc/api/o-auth.md
 [V1 Employees]: doc/api/v1-employees.md
 [V1 Transactions]: doc/api/v1-transactions.md
 [V1 Items]: doc/api/v1-items.md
 [Transactions]: doc/api/transactions.md
+[Sites]: doc/api/sites.md
+[Snippets]: doc/api/snippets.md

data/lib/square.rb

@@ -9,6 +9,7 @@ require_relative 'square/client.rb'
 
 # Utilities
 require_relative 'square/utilities/file_wrapper.rb'
+require_relative 'square/utilities/date_time_helper.rb'
 
 # Http
 require_relative 'square/http/api_response.rb'
@@ -36,6 +37,7 @@ require_relative 'square/api/v1_transactions_api.rb'
 require_relative 'square/api/apple_pay_api.rb'
 require_relative 'square/api/bank_accounts_api.rb'
 require_relative 'square/api/bookings_api.rb'
+require_relative 'square/api/cards_api.rb'
 require_relative 'square/api/cash_drawers_api.rb'
 require_relative 'square/api/catalog_api.rb'
 require_relative 'square/api/customers_api.rb'
@@ -44,6 +46,8 @@ require_relative 'square/api/customer_segments_api.rb'
 require_relative 'square/api/devices_api.rb'
 require_relative 'square/api/disputes_api.rb'
 require_relative 'square/api/employees_api.rb'
+require_relative 'square/api/gift_cards_api.rb'
+require_relative 'square/api/gift_card_activities_api.rb'
 require_relative 'square/api/inventory_api.rb'
 require_relative 'square/api/invoices_api.rb'
 require_relative 'square/api/labor_api.rb'
@@ -55,6 +59,8 @@ require_relative 'square/api/merchants_api.rb'
 require_relative 'square/api/orders_api.rb'
 require_relative 'square/api/payments_api.rb'
 require_relative 'square/api/refunds_api.rb'
+require_relative 'square/api/sites_api.rb'
+require_relative 'square/api/snippets_api.rb'
 require_relative 'square/api/subscriptions_api.rb'
 require_relative 'square/api/team_api.rb'
 require_relative 'square/api/terminal_api.rb'

data/lib/square/api/base_api.rb

@@ -8,21 +8,19 @@ module Square
       @http_call_back = http_call_back
 
       @global_headers = {
-        'user-agent' => 'Square-Ruby-SDK/10.0.0.202104217',
+        'user-agent' => 'Square-Ruby-SDK/13.1.0.20210818',
         'Square-Version' => config.square_version
       }
     end
 
     def validate_parameters(args)
       args.each do |_name, value|
-        if value.nil?
-          raise ArgumentError, "Required parameter #{_name} cannot be nil."
-        end
+        raise ArgumentError, "Required parameter #{_name} cannot be nil." if value.nil?
       end
     end
 
     def execute_request(request, binary: false)
-      @http_call_back.on_before_request(request) if @http_call_back
+      @http_call_back&.on_before_request(request)
 
       APIHelper.clean_hash(request.headers)
       request.headers.merge!(@global_headers)
@@ -35,7 +33,7 @@ module Square
                  else
                    config.http_client.execute_as_string(request)
                  end
-      @http_call_back.on_after_response(response) if @http_call_back
+      @http_call_back&.on_after_response(response)
 
       response
     end

data/lib/square/api/cards_api.rb

@@ -0,0 +1,170 @@
+module Square
+  # CardsApi
+  class CardsApi < BaseApi
+    def initialize(config, http_call_back: nil)
+      super(config, http_call_back: http_call_back)
+    end
+
+    # Retrieves a list of cards owned by the account making the request.
+    # A max of 25 cards will be returned.
+    # @param [String] cursor Optional parameter: A pagination cursor returned by
+    # a previous call to this endpoint. Provide this to retrieve the next set of
+    # results for your original query.  See
+    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
+    # for more information.
+    # @param [String] customer_id Optional parameter: Limit results to cards
+    # associated with the customer supplied. By default, all cards owned by the
+    # merchant are returned.
+    # @param [Boolean] include_disabled Optional parameter: Includes disabled
+    # cards. By default, all enabled cards owned by the merchant are returned.
+    # @param [String] reference_id Optional parameter: Limit results to cards
+    # associated with the reference_id supplied.
+    # @param [SortOrder] sort_order Optional parameter: Sorts the returned list
+    # by when the card was created with the specified order. This field defaults
+    # to ASC.
+    # @return [ListCardsResponse Hash] response from the API call
+    def list_cards(cursor: nil,
+                   customer_id: nil,
+                   include_disabled: false,
+                   reference_id: nil,
+                   sort_order: nil)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/cards'
+      _query_builder = APIHelper.append_url_with_query_parameters(
+        _query_builder,
+        'cursor' => cursor,
+        'customer_id' => customer_id,
+        'include_disabled' => include_disabled,
+        'reference_id' => reference_id,
+        'sort_order' => sort_order
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.get(
+        _query_url,
+        headers: _headers
+      )
+      OAuth2.apply(config, _request)
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    end
+
+    # Adds a card on file to an existing merchant.
+    # @param [CreateCardRequest] body Required parameter: An object containing
+    # the fields to POST for the request.  See the corresponding object
+    # definition for field details.
+    # @return [CreateCardResponse Hash] response from the API call
+    def create_card(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/cards'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'content-type' => 'application/json; charset=utf-8'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _query_url,
+        headers: _headers,
+        parameters: body.to_json
+      )
+      OAuth2.apply(config, _request)
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    end
+
+    # Retrieves details for a specific Card.
+    # @param [String] card_id Required parameter: Unique ID for the desired
+    # Card.
+    # @return [RetrieveCardResponse Hash] response from the API call
+    def retrieve_card(card_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/cards/{card_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'card_id' => { 'value' => card_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.get(
+        _query_url,
+        headers: _headers
+      )
+      OAuth2.apply(config, _request)
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    end
+
+    # Disables the card, preventing any further updates or charges.
+    # Disabling an already disabled card is allowed but has no effect.
+    # @param [String] card_id Required parameter: Unique ID for the desired
+    # Card.
+    # @return [DisableCardResponse Hash] response from the API call
+    def disable_card(card_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/cards/{card_id}/disable'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'card_id' => { 'value' => card_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _query_url,
+        headers: _headers
+      )
+      OAuth2.apply(config, _request)
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    end
+  end
+end

data/lib/square/api/catalog_api.rb

@@ -241,14 +241,17 @@ module Square
     # [SearchCatalogObjects]($e/Catalog/SearchCatalogObjects)
     # and set the `include_deleted_objects` attribute value to `true`.
     # @param [String] cursor Optional parameter: The pagination cursor returned
-    # in the previous response. Leave unset for an initial request. See
+    # in the previous response. Leave unset for an initial request. The page
+    # size is currently set to be 100. See
     # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
     # for more information.
     # @param [String] types Optional parameter: An optional case-insensitive,
-    # comma-separated list of object types to retrieve, for example
-    # `ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.  The legal values are taken from the
-    # CatalogObjectType enum: `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`,
-    # `TAX`, `MODIFIER`, `MODIFIER_LIST`, or `IMAGE`.
+    # comma-separated list of object types to retrieve.  The valid values are
+    # defined in the [CatalogObjectType]($m/CatalogObjectType) enum, including
+    # `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`,
+    # `MODIFIER_LIST`, or `IMAGE`.  If this is unspecified, the operation
+    # returns objects of all the types at the version of the Square API used to
+    # make the request.
     # @param [Long] catalog_version Optional parameter: The specific version of
     # the catalog objects to be included in the response.  This allows you to
     # retrieve historical versions of objects. The specified version value is

data/lib/square/api/customer_groups_api.rb

@@ -11,14 +11,22 @@ module Square
     # set of results for your original query.  For more information, see
     # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
     # ion).
+    # @param [Integer] limit Optional parameter: The maximum number of results
+    # to return in a single page. This limit is advisory. The response might
+    # contain more or fewer results.  The limit is ignored if it is less than 1
+    # or greater than 50. The default value is 50.  For more information, see
+    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
+    # ion).
     # @return [ListCustomerGroupsResponse Hash] response from the API call
-    def list_customer_groups(cursor: nil)
+    def list_customer_groups(cursor: nil,
+                             limit: nil)
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/customers/groups'
       _query_builder = APIHelper.append_url_with_query_parameters(
         _query_builder,
-        'cursor' => cursor
+        'cursor' => cursor,
+        'limit' => limit
       )
       _query_url = APIHelper.clean_url _query_builder
 

data/lib/square/api/customer_segments_api.rb

@@ -11,14 +11,22 @@ module Square
     # the next set of query results.  For more information, see
     # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
     # ion).
+    # @param [Integer] limit Optional parameter: The maximum number of results
+    # to return in a single page. This limit is advisory. The response might
+    # contain more or fewer results.  The limit is ignored if it is less than 1
+    # or greater than 50. The default value is 50.  For more information, see
+    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
+    # ion).
     # @return [ListCustomerSegmentsResponse Hash] response from the API call
-    def list_customer_segments(cursor: nil)
+    def list_customer_segments(cursor: nil,
+                               limit: nil)
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/customers/segments'
       _query_builder = APIHelper.append_url_with_query_parameters(
         _query_builder,
-        'cursor' => cursor
+        'cursor' => cursor,
+        'limit' => limit
       )
       _query_url = APIHelper.clean_url _query_builder
 

data/lib/square/api/customers_api.rb

@@ -17,13 +17,20 @@ module Square
     # set of results for your original query.  For more information, see
     # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
     # ion).
+    # @param [Integer] limit Optional parameter: The maximum number of results
+    # to return in a single page. This limit is advisory. The response might
+    # contain more or fewer results.  The limit is ignored if it is less than 1
+    # or greater than 100. The default value is 100.  For more information, see
+    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
+    # ion).
     # @param [CustomerSortField] sort_field Optional parameter: Indicates how
-    # customers should be sorted.  Default: `DEFAULT`.
+    # customers should be sorted.  The default value is `DEFAULT`.
     # @param [SortOrder] sort_order Optional parameter: Indicates whether
     # customers should be sorted in ascending (`ASC`) or descending (`DESC`)
-    # order.  Default: `ASC`.
+    # order.  The default value is `ASC`.
     # @return [ListCustomersResponse Hash] response from the API call
     def list_customers(cursor: nil,
+                       limit: nil,
                        sort_field: nil,
                        sort_order: nil)
       # Prepare query url.
@@ -32,6 +39,7 @@ module Square
       _query_builder = APIHelper.append_url_with_query_parameters(
         _query_builder,
         'cursor' => cursor,
+        'limit' => limit,
         'sort_field' => sort_field,
         'sort_order' => sort_order
       )
@@ -58,8 +66,7 @@ module Square
       )
     end
 
-    # Creates a new customer for a business, which can have associated cards on
-    # file.
+    # Creates a new customer for a business.
     # You must provide at least one of the following values in your request to
     # this
     # endpoint:
@@ -145,8 +152,8 @@ module Square
       )
     end
 
-    # Deletes a customer profile from a business, including any linked cards on
-    # file.
+    # Deletes a customer profile from a business. This operation also unlinks
+    # any associated cards on file.
     # As a best practice, you should include the `version` field in the request
     # to enable [optimistic
     # concurrency](https://developer.squareup.com/docs/working-with-apis/optimis
@@ -157,7 +164,7 @@ module Square
     # @param [String] customer_id Required parameter: The ID of the customer to
     # delete.
     # @param [Long] version Optional parameter: The current version of the
-    # customer profile.   As a best practice, you should include this parameter
+    # customer profile.  As a best practice, you should include this parameter
     # to enable [optimistic
     # concurrency](https://developer.squareup.com/docs/working-with-apis/optimis
     # tic-concurrency) control.  For more information, see [Delete a customer
@@ -245,11 +252,8 @@ module Square
     # the customer profile.
     # To update a customer profile that was created by merging existing
     # profiles, you must use the ID of the newly created profile.
-    # You cannot use this endpoint to change cards on file. To change a card on
-    # file, call [DeleteCustomerCard]($e/Customers/DeleteCustomerCard) to delete
-    # the existing card and then call
-    # [CreateCustomerCard]($e/Customers/CreateCustomerCard) to create a new
-    # card.
+    # You cannot use this endpoint to change cards on file. To make changes, use
+    # the [Cards API]($e/Cards) or [Gift Cards API]($e/GiftCards).
     # @param [String] customer_id Required parameter: The ID of the customer to
     # update.
     # @param [UpdateCustomerRequest] body Required parameter: An object
@@ -303,6 +307,7 @@ module Square
     # @return [CreateCustomerCardResponse Hash] response from the API call
     def create_customer_card(customer_id:,
                              body:)
+      warn 'Endpoint create_customer_card in CustomersApi is deprecated'
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/customers/{customer_id}/cards'
@@ -343,6 +348,7 @@ module Square
     # @return [DeleteCustomerCardResponse Hash] response from the API call
     def delete_customer_card(customer_id:,
                              card_id:)
+      warn 'Endpoint delete_customer_card in CustomersApi is deprecated'
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/customers/{customer_id}/cards/{card_id}'