square.rb 13.0.0.20210721 → 16.0.0.20211117

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f0db97e9e88ea1a9f5f7f9db716b8f2ce36473400c34f57ec01622e2b0b584b
-  data.tar.gz: 999b75d8c4ded30c3895d6cecf97d18883a6018ec9b79a53b85f1bed20f56de4
+  metadata.gz: 25ab6d01177792b1eb326af1a782a12ab26eff2678b44666aac14954907740e2
+  data.tar.gz: 1ba81bfd71af7fd3124015de59166e33401f0e230301d4ea45e6c70438380741
 SHA512:
-  metadata.gz: 2a74a9814e8d3d9edb5f9a36439c85f41c593f91941a3938c869b602b8fa65f2cf1ce6b115f43ed65c6a76ec6d36c8e237a5f855e3d12dbe90f6c906c9c7390d
-  data.tar.gz: a9d2ecd07e5616d2341b095519414007ab0e4bfc5159a90e3fb7e4b9d6337add73859641da52ccda4ee4bffb8ea39a59a37f487638c931f75c0ab1c77bb4dbce
+  metadata.gz: c0fa97ef6d70db8247d6a14cb946a942f9327faa37e881ce8628cd8f68e38bb6c91238cf10419dc915597701b69c73ecb0f1813d45be4d6f37eaa837c1646364
+  data.tar.gz: a9337cd596b733099e84765048134f4edc183f548ac6638da50257bfb0d3b0529271d17c509a1f9b34342abe9e7184d56ec4fe1f292ea1fa2ad36036228384d1

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2121 Square, Inc.
+Copyright 2021 Square, Inc.
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

data/README.md

@@ -8,6 +8,10 @@
 
 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:
@@ -33,6 +37,9 @@ gem 'square.rb'
 * [Disputes]
 * [Checkout]
 * [Apple Pay]
+* [Cards]
+
+### Terminal
 * [Terminal]
 
 ### Orders
@@ -56,6 +63,10 @@ gem 'square.rb'
 ### Loyalty
 * [Loyalty]
 
+### Gift Cards
+* [Gift Cards]
+* [Gift Card Activities]
+
 ### Bookings
 * [Bookings]
 
@@ -63,12 +74,11 @@ gem 'square.rb'
 * [Merchants]
 * [Locations]
 * [Devices]
+* [Cash Drawers]
 
 ### Team
 * [Team]
-* [Employees]
 * [Labor]
-* [Cash Drawers]
 
 ### Financials
 * [Bank Accounts]
@@ -82,6 +92,7 @@ gem 'square.rb'
 * [OAuth]
 
 ### Deprecated APIs
+* [Employees]
 * [V1 Employees]
 * [V1 Transactions]
 * [V1 Items]
@@ -104,8 +115,8 @@ require 'square'
 # for the Square account whose assets you want to manage.
 
 client = Square::Client.new(
-    access_token: 'YOUR SANDBOX ACCESS TOKEN HERE',
-    environment: 'sandbox'
+  access_token: 'YOUR SANDBOX ACCESS TOKEN HERE',
+  environment: 'sandbox'
 )
 
 # Call list_locations method to get all locations in this Square account
@@ -113,10 +124,10 @@ result = client.locations.list_locations
 
 # Call the #success? method to see if the call succeeded
 if result.success?
-	# The #data Struct contains a list of locations
+  # The #data Struct contains a list of locations
   locations = result.data.locations
 
-	# Iterate over the list
+  # Iterate over the list
   locations.each do |location|
     # Each location is represented as a Hash
     location.each do |key, value|
@@ -165,6 +176,7 @@ This error was returned when an invalid token was used to call the API.
 After you’ve tried out the Square APIs and tested your application using sandbox, you will want to switch to your production credentials so that you can manage real Square resources. Don't forget to switch your access token from sandbox to production for real data.
 
 ## SDK patterns
+
 If you know a few patterns, you’ll be able to call any API in the SDK. Here are some important ones:
 
 ### Get an access token
@@ -185,30 +197,31 @@ To use the Square API, you import the Client class, instantiate a Client object,
 
 - Instantiate a `Square::Client` object with the access token for the Square account whose resources you want to manage. To access sandbox resources, initialize the `Square::Client` with environment set to sandbox:
 
-```ruby
-client = Square::Client.new(
+  ```ruby
+  client = Square::Client.new(
     access_token: 'SANDBOX ACCESS TOKEN HERE',
     environment: 'sandbox'
-)
-```
+  )
+  ```
 
 - To access production resources, set environment to production:
 
-```ruby
-client = Square::Client.new(
+  ```ruby
+  client = Square::Client.new(
     access_token: 'ACCESS TOKEN HERE',
     environment: 'production'
-)
-```
+  )
+  ```
 
 - To set a custom environment provide a `custom_url`, and set environment to `custom`:
 
-```ruby
-client = Square::Client.new(
+  ```ruby
+  client = Square::Client.new(
     access_token:'ACCESS TOKEN HERE',
     environment: 'custom',
     custom_url: 'https://your.customdomain.com'
-)
+  )
+  ```
  
 ### Get an Instance of an API object and call its methods
 
@@ -216,9 +229,9 @@ Each API is implemented as a class. The Client object instantiates every API cla
 
 - Work with an API by calling the methods on the API object. For example, you would call list_customers to get a list of all customers in the Square account:
 
-```ruby
-result = client.customers.list_customers
-```
+  ```ruby
+  result = client.customers.list_customers
+  ```
 
 See the SDK documentation for the list of methods for each API class.
 
@@ -239,6 +252,7 @@ result = client.customers.create_customer(request_body)
 ```
 
 If your call succeeds, you’ll see a response that looks like this:
+
 ```
 {'customer': {'created_at': '2019-06-28T21:23:05.126Z', 'creation_source': 'THIRD_PARTY', 'family_name': 'Earhardt', 'given_name': 'Amelia', 'id': 'CBASEDwl3El91nohQ2FLEk4aBfcgAQ', 'preferences': {'email_unsubscribed': False}, 'updated_at': '2019-06-28T21:23:05.126Z'}}
 ```
@@ -263,7 +277,7 @@ end
 
 ## Tests
 
-First, clone the gem locally and `cd` into the directory.
+First, clone the repo locally and `cd` into the directory.
 
 ```sh
 git clone https://github.com/square/square-ruby-sdk.git
@@ -333,3 +347,6 @@ You can also use the Square API to create applications or services that work wit
 [Transactions]: doc/api/transactions.md
 [Sites]: doc/api/sites.md
 [Snippets]: doc/api/snippets.md
+[Cards]: doc/api/cards.md
+[Gift Cards]: doc/api/gift-cards.md
+[Gift Card Activities]: doc/api/gift-card-activities.md

data/lib/square/api/apple_pay_api.rb

@@ -30,7 +30,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

data/lib/square/api/base_api.rb

@@ -8,34 +8,30 @@ module Square
       @http_call_back = http_call_back
 
       @global_headers = {
-        'user-agent' => 'Square-Ruby-SDK/13.0.0.20210721',
+        'user-agent' => 'Square-Ruby-SDK/16.0.0.20211117',
         '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)
-      unless config.additional_headers.nil?
-        request.headers.merge!(config.additional_headers)
-      end
+      request.headers.merge!(config.additional_headers) unless config.additional_headers.nil?
 
       response = if binary
                    config.http_client.execute_as_binary(request)
                  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/bookings_api.rb

@@ -5,6 +5,66 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
+    # Retrieve a collection of bookings.
+    # @param [Integer] limit Optional parameter: The maximum number of results
+    # per page to return in a paged response.
+    # @param [String] cursor Optional parameter: The pagination cursor from the
+    # preceding response to return the next page of the results. Do not set this
+    # when retrieving the first page of the results.
+    # @param [String] team_member_id Optional parameter: The team member for
+    # whom to retrieve bookings. If this is not set, bookings of all members are
+    # retrieved.
+    # @param [String] location_id Optional parameter: The location for which to
+    # retrieve bookings. If this is not set, all locations' bookings are
+    # retrieved.
+    # @param [String] start_at_min Optional parameter: The RFC 3339 timestamp
+    # specifying the earliest of the start time. If this is not set, the current
+    # time is used.
+    # @param [String] start_at_max Optional parameter: The RFC 3339 timestamp
+    # specifying the latest of the start time. If this is not set, the time of
+    # 31 days after `start_at_min` is used.
+    # @return [ListBookingsResponse Hash] response from the API call
+    def list_bookings(limit: nil,
+                      cursor: nil,
+                      team_member_id: nil,
+                      location_id: nil,
+                      start_at_min: nil,
+                      start_at_max: nil)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/bookings'
+      _query_builder = APIHelper.append_url_with_query_parameters(
+        _query_builder,
+        'limit' => limit,
+        'cursor' => cursor,
+        'team_member_id' => team_member_id,
+        'location_id' => location_id,
+        'start_at_min' => start_at_min,
+        'start_at_max' => start_at_max
+      )
+      _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
+
     # Creates a booking.
     # @param [CreateBookingRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
@@ -19,7 +79,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -53,7 +113,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -242,7 +302,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -283,7 +343,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

data/lib/square/api/cards_api.rb

@@ -76,7 +76,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

data/lib/square/api/catalog_api.rb

@@ -29,7 +29,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -68,7 +68,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -115,7 +115,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -307,7 +307,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -435,7 +435,7 @@ module Square
     # Searches for [CatalogObject]($m/CatalogObject) of any type by matching
     # supported search attribute values,
     # excluding custom attribute values on items or item variations, against one
-    # or more of the specified query expressions.
+    # or more of the specified query filters.
     # This (`SearchCatalogObjects`) endpoint differs from the
     # [SearchCatalogItems]($e/Catalog/SearchCatalogItems)
     # endpoint in the following aspects:
@@ -462,7 +462,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -485,7 +485,7 @@ module Square
     # Searches for catalog items or item variations by matching supported search
     # attribute values, including
     # custom attribute values, against one or more of the specified query
-    # expressions.
+    # filters.
     # This (`SearchCatalogItems`) endpoint differs from the
     # [SearchCatalogObjects]($e/Catalog/SearchCatalogObjects)
     # endpoint in the following aspects:
@@ -512,7 +512,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -548,7 +548,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -584,7 +584,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

data/lib/square/api/checkout_api.rb

@@ -28,7 +28,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

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
 
@@ -58,7 +66,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -169,7 +177,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

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
       )
@@ -80,7 +88,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -124,7 +132,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -156,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
@@ -266,7 +274,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -312,7 +320,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

data/lib/square/api/devices_api.rb

@@ -74,7 +74,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

data/lib/square/api/disputes_api.rb

@@ -259,7 +259,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.