square.rb 17.0.0.20211215 → 18.1.0.20220316

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28048e0ca738b0ca2de7579b8dc077c0307266afa1ff42c1ee6808eb64c79f43
-  data.tar.gz: 7ba3afdb67a42eb41864d5fe5839b8b74f525eebac2b6348e51aee92c9399328
+  metadata.gz: bbb5aeea53c32ac7828ffb52501c522f8e4811bb81aa4f0deb453802dcc9147e
+  data.tar.gz: 2526651aefdbeb8e605d35ef011de1c21f241e860c9d3fde2853b3c9e8912932
 SHA512:
-  metadata.gz: 2bf8bcf75bf6558596e20c1f9d3c82d579aa20f4964047c94bc43592b2e1b0f28445d1f788ba30e1272095380a07a5350fc4c2f8082097b12ef29eb424b33bfd
-  data.tar.gz: 4b09ca82e2b15e60b7ae1a7c217bf445cfb8dd0f6ceb60d6e835d08a5ef08657054d15cc58124d85a1be2f30a8d67630a55caaf58c0942cb92de81ec426cfe6d
+  metadata.gz: 500aa37342e9b95690d2541bc0f55d4b2ba2797290439a9da44bb1056b3aaf20d741a30b853afdaf9a81be4720b1b2284062974ac5c31908b17e0bc858725fa8
+  data.tar.gz: 83e45f18a23572b205a30ac3aad83529a6f94e0ae2a340ce28d3a06b243ace51e315114ca5e24cfa8676420d705dd7d80aec69053306eb63f799578c9a499f97

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2021 Square, Inc.
+Copyright 2022 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

@@ -6,30 +6,54 @@
 [![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.
+Use this library 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, 2.7.x, and 3.0.x.
+Use of the Square Ruby SDK requires:
+
+* Ruby 2.6 through 3.1
 
 ## Installation
 
-Install the gem from the command line:
+For more information, see [Set Up Your Square SDK for a Ruby Project](https://developer.squareup.com/docs/sdks/ruby/setup-project).
+
+## Quickstart
+
+For more information, see [Square Ruby SDK Quickstart](https://developer.squareup.com/docs/sdks/ruby/quick-start).
+
+## Usage
+For more information, see [Using the Square Ruby SDK](https://developer.squareup.com/docs/sdks/ruby/using-ruby-sdk).
+
+## Tests
+
+First, clone the repo locally and `cd` into the directory.
+
+```sh
+git clone https://github.com/square/square-ruby-sdk.git
+cd square-ruby-sdk
+```
+
+Next, make sure Bundler is installed and install the development dependencies.
 
-```ruby
-gem install square.rb
+```sh
+gem install bundler
+bundle
 ```
 
-Or add the gem to your Gemfile and `bundle`:
+Before running the tests, find a sandbox token in your [Developer Dashboard] and set a `SQUARE_SANDBOX_TOKEN` environment variable.
 
-```ruby
-gem 'square.rb'
+```sh
+export SQUARE_SANDBOX_TOKEN="YOUR SANDBOX TOKEN HERE"
 ```
 
-### API Client
-* [Client]
+And run the tests.
 
-## API documentation
+```sh
+rake
+```
+
+## SDK Reference
 
 ### Payments
 * [Payments]
@@ -98,216 +122,6 @@ gem 'square.rb'
 * [V1 Items]
 * [Transactions]
 
-## Usage
-
-First time using Square? Here’s how to get started:
-
-1. **Create a Square account.** If you don’t have one already, [sign up for a developer account].
-1. **Create an application.** Go to your [Developer Dashboard] and create your first application. All you need to do is give it a name. When you’re doing this for your production application, enter the name as you would want a customer to see it.
-1. **Make your first API call.** Almost all Square API calls require a location ID. You’ll make your first call to #list_locations, which happens to be one of the API calls that don’t require a location ID. For more information about locations, see the [Locations] API documentation.
-
-Now let’s call your first Square API. Open your favorite text editor, create a new file called `locations.rb`, and copy the following code into that file:
-
-```ruby
-require 'square'
- 
-# Create an instance of the API Client and initialize it with the credentials 
-# for the Square account whose assets you want to manage.
-
-client = Square::Client.new(
-  access_token: 'YOUR SANDBOX ACCESS TOKEN HERE',
-  environment: 'sandbox'
-)
-
-# Call list_locations method to get all locations in this Square account
-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
-  locations = result.data.locations
-
-  # Iterate over the list
-  locations.each do |location|
-    # Each location is represented as a Hash
-    location.each do |key, value|
-      puts "#{key}: #{value}"
-    end
-  end
-else
-  # Handle the case that the result is an error.
-  warn 'Error calling LocationsApi.listlocations ...'
-
-  # The #errors method returns an Array of error Hashes
-  result.errors.each do |key, value|
-    warn "#{key}: #{value}"
-  end
-end
-```
-
-Next, get an access token and reference it in your code. Go back to your application in the Developer Dashboard, in the Sandbox section click Show in the Sandbox Access Token box, copy that access token, and replace `'YOUR SANDBOX ACCESS TOKEN HERE'` with that token.
-
-**Important** When you eventually switch from trying things out on sandbox to actually working with your real production resources, you should not embed the access token in your code. Make sure you store and access your production access tokens securely.
-
-Now save `locations.rb` and run it:
-
-```sh
-ruby locations.rb
-```
-
-If your call is successful, you’ll get a response that looks like this:
-
-```
-address : {'address_line_1': '1455 Market Street', 'administrative_district_level_1': 'CA', 'country': 'US', 'locality': 'San Francisco', 'postal_code': '94103'}
-# ...
-```
-
-Yay! You successfully made your first call. If you didn’t, you would see an error message that looks something like this:
-
-```
-Error calling LocationsApi.listlocations
-category : AUTHENTICATION_ERROR
-code : UNAUTHORIZED
-detail : This request could not be authorized.
-```
-
-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
-
-To use the Square API to manage the resources (such as payments, orders, customers, etc.) of a Square account, you need to create an application (or use an existing one) in the Developer Dashboard and get an access token.
-
-When you call a Square API, you call it using an access key. An access key has specific permissions to resources in a specific Square account that can be accessed by a specific application in a specific developer account.
-Use an access token that is appropriate for your use case. There are two options:
-
-- To manage the resources for your own Square account, use the Personal Access Token for the application created in your Square account.
-- To manage resources for other Square accounts, use OAuth to ask owners of the accounts you want to manage so that you can work on their behalf. When you implement OAuth, you ask the Square account holder for permission to manage resources in their account (you can define the specific resources to access) and get an OAuth access token and refresh token for their account.
-
-**Important** For both use cases, make sure you store and access the tokens securely.
-
-### Import and Instantiate the Client Class
-
-To use the Square API, you import the Client class, instantiate a Client object, and initialize it with the appropriate access token. Here’s how:
-
-- 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(
-    access_token: 'SANDBOX ACCESS TOKEN HERE',
-    environment: 'sandbox'
-  )
-  ```
-
-- To access production resources, set environment to production:
-
-  ```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(
-    access_token:'ACCESS TOKEN HERE',
-    environment: 'custom',
-    custom_url: 'https://your.customdomain.com'
-  )
-  ```
- 
-### Get an Instance of an API object and call its methods
-
-Each API is implemented as a class. The Client object instantiates every API class and exposes them as properties so you can easily start using any Square API. You work with an API by calling methods on an instance of an API class. Here’s how:
-
-- 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
-  ```
-
-See the SDK documentation for the list of methods for each API class.
-
-Pass complex parameters (such as create, update, search, etc.) as a Hash. For example, you would pass a Hash containing the values used to create a new customer using create_customer:
-
-```ruby
-# Create a unique key for this creation operation so you don't accidentally
-# create the customer multiple times if you need to retry this operation.
-require 'securerandom'
-
-idempotency_key = SecureRandom.uuid
-
-# To create a customer, you'll need to specify at least a few required fields.
-request_body = {idempotency_key: idempotency_key, given_name: 'Amelia', family_name: 'Earhardt'}
-
-# Call create_customer method to create a new customer in this Square account
-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'}}
-```
-
-- Use idempotency for create, update, or other calls that you want to avoid calling twice. To make an idempotent API call, you add the idempotency_key with a unique value in the Hash for the API call’s request.
-- Specify a location ID for APIs such as Transactions, Orders, and Checkout that deal with payments. When a payment or order is created in Square, it is always associated with a location.
-
-### Handle the response
-
-API calls return a response object that contains properties that describe both the request (headers and request) and the response (status_code, reason_phrase, text, errors, body, and cursor). The response also has #success? and #error? helper methods so you can easily determine the success or failure of a call:
-
-```ruby
-if result.success?
-  p result.data
-elsif result.error?
-  warn result.errors.inspect
-end
-```
-
-- Read the response payload. The response payload is returned as a Struct from the #data method. For retrieve calls, a Struct containing a single item is returned with a key name that is the name of the object (for example, customer). For list calls, a Struct containing a Array of objects is returned with a key name that is the plural of the object name (for example, customers).
-- Make sure you get all items returned in a list call by checking the cursor value returned in the API response. When you call a list API the first time, set the cursor to an empty String or omit it from the API request. If the API response contains a cursor with a value, you call the API again to get the next page of items and continue to call that API again until the cursor is an empty String.
-
-## Tests
-
-First, clone the repo locally and `cd` into the directory.
-
-```sh
-git clone https://github.com/square/square-ruby-sdk.git
-cd square-ruby-sdk
-```
-
-Next, make sure Bundler is installed and install the development dependencies.
-
-```sh
-gem install bundler
-bundle
-```
-
-Before running the tests, find a sandbox token in your [Developer Dashboard] and set a `SQUARE_SANDBOX_TOKEN` environment variable.
-
-```sh
-export SQUARE_SANDBOX_TOKEN="YOUR SANDBOX TOKEN HERE"
-```
-
-And run the tests.
-
-```sh
-rake
-```
-
-## Learn more
-
-The Square Platform is built on the [Square API]. Square has a number of other SDKs that enable you to securely handle credit card information on both mobile and web so that you can process payments via the Square API. 
-
-You can also use the Square API to create applications or services that work with payments, orders, inventory, etc. that have been created and managed in Square’s in-person hardware products (Square Point of Sale and Square Register).
 
 [//]: # "Link anchor definitions"
 [Square Logo]: https://docs.connect.squareup.com/images/github/github-square-logo.svg

data/lib/square/api/base_api.rb

@@ -38,7 +38,16 @@ module Square
     end
 
     def get_user_agent
-      user_agent = 'Square-Ruby-SDK/17.0.0.20211215'
+      user_agent = 'Square-Ruby-SDK/18.1.0.20220316 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}'
+      user_agent['{engine}'] = RUBY_ENGINE
+      user_agent['{engine-version}'] = RUBY_ENGINE_VERSION
+      user_agent['{os-info}'] = RUBY_PLATFORM
+      user_agent['{api-version}'] = config.square_version
+      if config.user_agent_detail.nil? || config.user_agent_detail.empty?
+        user_agent = user_agent.gsub('{detail}', '')
+      else
+        user_agent['{detail}'] = ERB::Util.url_encode(config.user_agent_detail.to_s)
+      end
       user_agent
     end
   end

data/lib/square/api/bookings_api.rb

@@ -6,6 +6,10 @@ module Square
     end
 
     # Retrieve a collection of bookings.
+    # To call this endpoint with buyer-level permissions, set
+    # `APPOINTMENTS_READ` for the OAuth scope.
+    # To call this endpoint with seller-level permissions, set
+    # `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
     # @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
@@ -66,6 +70,10 @@ module Square
     end
 
     # Creates a booking.
+    # To call this endpoint with buyer-level permissions, set
+    # `APPOINTMENTS_WRITE` for the OAuth scope.
+    # To call this endpoint with seller-level permissions, set
+    # `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.
     # @param [CreateBookingRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -100,6 +108,10 @@ module Square
     end
 
     # Searches for availabilities for booking.
+    # To call this endpoint with buyer-level permissions, set
+    # `APPOINTMENTS_READ` for the OAuth scope.
+    # To call this endpoint with seller-level permissions, set
+    # `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
     # @param [SearchAvailabilityRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -167,9 +179,10 @@ module Square
     # include only bookable team members in the returned result (`true`) or not
     # (`false`).
     # @param [Integer] limit Optional parameter: The maximum number of results
-    # to return.
-    # @param [String] cursor Optional parameter: The cursor for paginating
-    # through the results.
+    # 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] location_id Optional parameter: Indicates whether to
     # include only team members enabled at the given location in the returned
     # result.
@@ -247,6 +260,10 @@ module Square
     end
 
     # Retrieves a booking.
+    # To call this endpoint with buyer-level permissions, set
+    # `APPOINTMENTS_READ` for the OAuth scope.
+    # To call this endpoint with seller-level permissions, set
+    # `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
     # @param [String] booking_id Required parameter: The ID of the
     # [Booking]($m/Booking) object representing the to-be-retrieved booking.
     # @return [RetrieveBookingResponse Hash] response from the API call
@@ -282,6 +299,10 @@ module Square
     end
 
     # Updates a booking.
+    # To call this endpoint with buyer-level permissions, set
+    # `APPOINTMENTS_WRITE` for the OAuth scope.
+    # To call this endpoint with seller-level permissions, set
+    # `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.
     # @param [String] booking_id Required parameter: The ID of the
     # [Booking]($m/Booking) object representing the to-be-updated booking.
     # @param [UpdateBookingRequest] body Required parameter: An object
@@ -323,6 +344,10 @@ module Square
     end
 
     # Cancels an existing booking.
+    # To call this endpoint with buyer-level permissions, set
+    # `APPOINTMENTS_WRITE` for the OAuth scope.
+    # To call this endpoint with seller-level permissions, set
+    # `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.
     # @param [String] booking_id Required parameter: The ID of the
     # [Booking]($m/Booking) object representing the to-be-cancelled booking.
     # @param [CancelBookingRequest] body Required parameter: An object

data/lib/square/api/customer_groups_api.rb

@@ -9,14 +9,15 @@ module Square
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this cursor to retrieve the next
     # set of results for your original query.  For more information, see
-    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
-    # ion).
+    # [Pagination](https://developer.squareup.com/docs/build-basics/common-api-p
+    # atterns/pagination).
     # @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).
+    # contain more or fewer results. If the limit is less than 1 or greater than
+    # 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error.
+    # The default value is 50.  For more information, see
+    # [Pagination](https://developer.squareup.com/docs/build-basics/common-api-p
+    # atterns/pagination).
     # @return [ListCustomerGroupsResponse Hash] response from the API call
     def list_customer_groups(cursor: nil,
                              limit: nil)

data/lib/square/api/customer_segments_api.rb

@@ -9,14 +9,15 @@ module Square
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # previous calls to `ListCustomerSegments`. This cursor is used to retrieve
     # the next set of query results.  For more information, see
-    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
-    # ion).
+    # [Pagination](https://developer.squareup.com/docs/build-basics/common-api-p
+    # atterns/pagination).
     # @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).
+    # contain more or fewer results. If the specified limit is less than 1 or
+    # greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400
+    # VALUE_TOO_HIGH` error. The default value is 50.  For more information, see
+    # [Pagination](https://developer.squareup.com/docs/build-basics/common-api-p
+    # atterns/pagination).
     # @return [ListCustomerSegmentsResponse Hash] response from the API call
     def list_customer_segments(cursor: nil,
                                limit: nil)

data/lib/square/api/customers_api.rb

@@ -15,14 +15,16 @@ module Square
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this cursor to retrieve the next
     # set of results for your original query.  For more information, see
-    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
-    # ion).
+    # [Pagination](https://developer.squareup.com/docs/build-basics/common-api-p
+    # atterns/pagination).
     # @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).
+    # contain more or fewer results. If the specified limit is less than 1 or
+    # greater than 100, Square returns a `400 VALUE_TOO_LOW` or `400
+    # VALUE_TOO_HIGH` error. The default value is 100.  For more information,
+    # see
+    # [Pagination](https://developer.squareup.com/docs/build-basics/common-api-p
+    # atterns/pagination).
     # @param [CustomerSortField] sort_field Optional parameter: Indicates how
     # customers should be sorted.  The default value is `DEFAULT`.
     # @param [SortOrder] sort_order Optional parameter: Indicates whether
@@ -166,8 +168,9 @@ module Square
     # @param [Long] version Optional parameter: The current version of the
     # 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
+    # concurrency](https://developer.squareup.com/docs/build-basics/common-api-p
+    # atterns/optimistic-concurrency) control.  For more information, see
+    # [Delete a customer
     # profile](https://developer.squareup.com/docs/customers-api/use-the-api/kee
     # p-records#delete-customer-profile).
     # @return [DeleteCustomerResponse Hash] response from the API call

data/lib/square/api/locations_api.rb

@@ -5,7 +5,8 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Provides details about all of the seller's locations,
+    # Provides details about all of the seller's
+    # [locations](https://developer.squareup.com/docs/locations-api),
     # including those with an inactive status.
     # @return [ListLocationsResponse Hash] response from the API call
     def list_locations
@@ -117,7 +118,7 @@ module Square
       )
     end
 
-    # Updates a location.
+    # Updates a [location](https://developer.squareup.com/docs/locations-api).
     # @param [String] location_id Required parameter: The ID of the location to
     # update.
     # @param [UpdateLocationRequest] body Required parameter: An object

data/lib/square/api/loyalty_api.rb

@@ -124,12 +124,6 @@ module Square
     # [CalculateLoyaltyPoints]($e/Loyalty/CalculateLoyaltyPoints) to compute the
     # points
     # that you provide to this endpoint.
-    # __Note:__ The country of the seller's Square account determines whether
-    # tax is included in the purchase amount when accruing points for
-    # spend-based and visit-based programs.
-    # For more information, see [Availability of Square
-    # Loyalty](https://developer.squareup.com/docs/loyalty-api/overview#loyalty-
-    # market-availability).
     # @param [String] account_id Required parameter: The [loyalty
     # account]($m/LoyaltyAccount) ID to which to add the points.
     # @param [AccumulateLoyaltyPointsRequest] body Required parameter: An object
@@ -336,8 +330,8 @@ module Square
     end
 
     # Calculates the points a purchase earns.
-    # - If you are using the Orders API to manage orders, you provide `order_id`
-    # in the request. The
+    # - If you are using the Orders API to manage orders, you provide the
+    # `order_id` in the request. The
     # endpoint calculates the points by reading the order.
     # - If you are not using the Orders API to manage orders, you provide the
     # purchase amount in
@@ -345,12 +339,9 @@ module Square
     # An application might call this endpoint to show the points that a buyer
     # can earn with the
     # specific purchase.
-    # __Note:__ The country of the seller's Square account determines whether
-    # tax is included in the purchase amount when accruing points for
-    # spend-based and visit-based programs.
-    # For more information, see [Availability of Square
-    # Loyalty](https://developer.squareup.com/docs/loyalty-api/overview#loyalty-
-    # market-availability).
+    # For spend-based and visit-based programs, the `tax_mode` setting of the
+    # accrual rule indicates how taxes should be treated for loyalty points
+    # accrual.
     # @param [String] program_id Required parameter: The [loyalty
     # program]($m/LoyaltyProgram) ID, which defines the rules for accruing
     # points.
@@ -433,9 +424,10 @@ module Square
       )
     end
 
-    # Searches for loyalty rewards in a loyalty account.
-    # In the current implementation, the endpoint supports search by the reward
-    # `status`.
+    # Searches for loyalty rewards. This endpoint accepts a request with no
+    # query filters and returns results for all loyalty accounts.
+    # If you include a `query` object, `loyalty_account_id` is required and
+    # `status` is  optional.
     # If you know a reward ID, use the
     # [RetrieveLoyaltyReward]($e/Loyalty/RetrieveLoyaltyReward) endpoint.
     # Search results are sorted by `updated_at` in descending order.

data/lib/square/api/merchants_api.rb

@@ -5,15 +5,17 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Returns `Merchant` information for a given access token.
-    # If you don't know a `Merchant` ID, you can use this endpoint to retrieve
-    # the merchant ID for an access token.
-    # You can specify your personal access token to get your own merchant
-    # information or specify an OAuth token
-    # to get the information for the  merchant that granted you access.
+    # Provides details about the merchant associated with a given access token.
+    # The access token used to connect your application to a Square seller is
+    # associated
+    # with a single merchant. That means that `ListMerchants` returns a list
+    # with a single `Merchant` object. You can specify your personal access
+    # token
+    # to get your own merchant information or specify an OAuth token to get the
+    # information for the merchant that granted your application access.
     # If you know the merchant ID, you can also use the
     # [RetrieveMerchant]($e/Merchants/RetrieveMerchant)
-    # endpoint to get the merchant information.
+    # endpoint to retrieve the merchant information.
     # @param [Integer] cursor Optional parameter: The cursor generated by the
     # previous response.
     # @return [ListMerchantsResponse Hash] response from the API call
@@ -48,7 +50,7 @@ module Square
       )
     end
 
-    # Retrieve a `Merchant` object for the given `merchant_id`.
+    # Retrieves the `Merchant` object for the given `merchant_id`.
     # @param [String] merchant_id Required parameter: The ID of the merchant to
     # retrieve. If the string "me" is supplied as the ID, then retrieve the
     # merchant that is currently accessible to this call.

data/lib/square/api/refunds_api.rb

@@ -31,10 +31,13 @@ module Square
     # the given status are returned. For a list of refund status values, see
     # [PaymentRefund]($m/PaymentRefund).  Default: If omitted, refunds are
     # returned regardless of their status.
-    # @param [String] source_type Optional parameter: If provided, only refunds
-    # with the given source type are returned. - `CARD` - List refunds only for
-    # payments where `CARD` was specified as the payment source.  Default: If
-    # omitted, refunds are returned regardless of the source type.
+    # @param [String] source_type Optional parameter: If provided, only returns
+    # refunds whose payments have the indicated source type. Current values
+    # include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`. For
+    # information about these payment source types, see [Take
+    # Payments](https://developer.squareup.com/docs/payments-api/take-payments).
+    #  Default: If omitted, refunds are returned regardless of the source
+    # type.
     # @param [Integer] limit Optional parameter: The maximum number of results
     # to be returned in a single page.  It is possible to receive fewer results
     # than the specified limit on a given page.  If the supplied value is

data/lib/square/api/vendors_api.rb

@@ -0,0 +1,257 @@
+module Square
+  # VendorsApi
+  class VendorsApi < BaseApi
+    def initialize(config, http_call_back: nil)
+      super(config, http_call_back: http_call_back)
+    end
+
+    # Creates one or more [Vendor]($m/Vendor) objects to represent suppliers to
+    # a seller.
+    # @param [BulkCreateVendorsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [BulkCreateVendorsResponse Hash] response from the API call
+    def bulk_create_vendors(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/bulk-create'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+
+      # 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 one or more vendors of specified [Vendor]($m/Vendor) IDs.
+    # @param [BulkRetrieveVendorsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [BulkRetrieveVendorsResponse Hash] response from the API call
+    def bulk_retrieve_vendors(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/bulk-retrieve'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+
+      # 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
+
+    # Updates one or more of existing [Vendor]($m/Vendor) objects as suppliers
+    # to a seller.
+    # @param [BulkUpdateVendorsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [BulkUpdateVendorsResponse Hash] response from the API call
+    def bulk_update_vendors(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/bulk-update'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.put(
+        _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
+
+    # Creates a single [Vendor]($m/Vendor) object to represent a supplier to a
+    # seller.
+    # @param [CreateVendorRequest] body Required parameter: An object containing
+    # the fields to POST for the request.  See the corresponding object
+    # definition for field details.
+    # @return [CreateVendorResponse Hash] response from the API call
+    def create_vendor(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/create'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+
+      # 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
+
+    # Searches for vendors using a filter against supported [Vendor]($m/Vendor)
+    # properties and a supported sorter.
+    # @param [SearchVendorsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [SearchVendorsResponse Hash] response from the API call
+    def search_vendors(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/search'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+
+      # 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 the vendor of a specified [Vendor]($m/Vendor) ID.
+    # @param [String] vendor_id Required parameter: ID of the
+    # [Vendor]($m/Vendor) to retrieve.
+    # @return [RetrieveVendorResponse Hash] response from the API call
+    def retrieve_vendor(vendor_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/{vendor_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'vendor_id' => { 'value' => vendor_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
+
+    # Updates an existing [Vendor]($m/Vendor) object as a supplier to a seller.
+    # @param [UpdateVendorRequest] body Required parameter: An object containing
+    # the fields to POST for the request.  See the corresponding object
+    # definition for field details.
+    # @param [String] vendor_id Required parameter: Example:
+    # @return [UpdateVendorResponse Hash] response from the API call
+    def update_vendor(body:,
+                      vendor_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/{vendor_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'vendor_id' => { 'value' => vendor_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.put(
+        _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
+  end
+end

data/lib/square/api_helper.rb

@@ -8,18 +8,16 @@ module Square
     def self.serialize_array(key, array, formatting: 'indexed')
       tuples = []
 
-      case formatting
-      when 'unindexed'
-        tuples += array.map { |element| ["#{key}[]", element] }
-      when 'indexed'
-        tuples += array.map.with_index do |element, index|
-          ["#{key}[#{index}]", element]
-        end
-      when 'plain'
-        tuples += array.map { |element| [key, element] }
-      else
-        raise ArgumentError, 'Invalid format provided.'
-      end
+      tuples += case formatting
+                when 'csv'
+                  [[key, array.map { |element| CGI.escape(element.to_s) }.join(',')]]
+                when 'psv'
+                  [[key, array.map { |element| CGI.escape(element.to_s) }.join('|')]]
+                when 'tsv'
+                  [[key, array.map { |element| CGI.escape(element.to_s) }.join("\t")]]
+                else
+                  array.map { |element| [key, element] }
+                end
       tuples
     end
 
@@ -75,31 +73,19 @@ module Square
       return query_builder if parameters.nil?
 
       array_serialization = 'indexed'
+      parameters = process_complex_types_parameters(parameters, array_serialization)
 
       parameters.each do |key, value|
         seperator = query_builder.include?('?') ? '&' : '?'
         unless value.nil?
           if value.instance_of? Array
             value.compact!
-            query_builder += case array_serialization
-                             when 'csv'
-                               "#{seperator}#{key}=#{value.map do |element|
-                                 CGI.escape(element.to_s)
-                               end.join(',')}"
-                             when 'psv'
-                               "#{seperator}#{key}=#{value.map do |element|
-                                 CGI.escape(element.to_s)
-                               end.join('|')}"
-                             when 'tsv'
-                               "#{seperator}#{key}=#{value.map do |element|
-                                 CGI.escape(element.to_s)
-                               end.join("\t")}"
-                             else
-                               "#{seperator}#{APIHelper.serialize_array(
-                                 key, value, formatting: array_serialization
-                               ).map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }
-                               .join('&')}"
-                             end
+            APIHelper.serialize_array(
+              key, value, formatting: array_serialization
+            ).each do |element|
+              seperator = query_builder.include?('?') ? '&' : '?'
+              query_builder += "#{seperator}#{element[0]}=#{element[1]}"
+            end
           else
             query_builder += "#{seperator}#{key}=#{CGI.escape(value.to_s)}"
           end
@@ -163,6 +149,18 @@ module Square
       encoded
     end
 
+    # Process complex types in query_params.
+    # @param [Hash] The hash of query parameters.
+    # @return [Hash] A hash with the processed query parameters.
+    def self.process_complex_types_parameters(query_parameters, array_serialization)
+      processed_params = {}
+      query_parameters.each do |key, value|
+        processed_params.merge!(APIHelper.form_encode(value, key, formatting:
+          array_serialization))
+      end
+      processed_params
+    end
+
     def self.custom_merge(a, b)
       x = {}
       a.each do |key, value_a|

data/lib/square/client.rb

@@ -4,7 +4,7 @@ module Square
     attr_reader :config
 
     def sdk_version
-      '17.0.0.20211215'
+      '18.1.0.20220316'
     end
 
     def square_version
@@ -213,16 +213,22 @@ module Square
       @terminal ||= TerminalApi.new config
     end
 
-    def initialize(http_client_instance: nil, timeout: 60, max_retries: 0,
+    # Access to vendors controller.
+    # @return [VendorsApi] Returns the controller instance.
+    def vendors
+      @vendors ||= VendorsApi.new config
+    end
+
+    def initialize(connection: nil, timeout: 60, max_retries: 0,
                    retry_interval: 1, backoff_factor: 2,
                    retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
                    retry_methods: %i[get put], environment: 'production',
                    custom_url: 'https://connect.squareup.com',
-                   square_version: '2021-12-15', access_token: '',
+                   square_version: '2022-03-16', access_token: '',
                    user_agent_detail: '', additional_headers: {}, config: nil)
       @config = if config.nil?
-                  Configuration.new(http_client_instance: http_client_instance,
-                                    timeout: timeout, max_retries: max_retries,
+                  Configuration.new(connection: connection, timeout: timeout,
+                                    max_retries: max_retries,
                                     retry_interval: retry_interval,
                                     backoff_factor: backoff_factor,
                                     retry_statuses: retry_statuses,

data/lib/square/configuration.rb

@@ -3,9 +3,9 @@ module Square
   # are configured in this class.
   class Configuration
     # The attribute readers for properties.
-    attr_reader :http_client, :http_client_instance, :timeout, :max_retries, :retry_interval,
-                :backoff_factor, :retry_statuses, :retry_methods, :environment, :custom_url,
-                :square_version, :access_token, :user_agent_detail
+    attr_reader :http_client, :connection, :timeout, :max_retries, :retry_interval, :backoff_factor,
+                :retry_statuses, :retry_methods, :environment, :custom_url, :square_version,
+                :access_token, :user_agent_detail
 
     def additional_headers
       @additional_headers.clone
@@ -15,15 +15,15 @@ module Square
       attr_reader :environments
     end
 
-    def initialize(http_client_instance: nil, timeout: 60, max_retries: 0,
+    def initialize(connection: nil, timeout: 60, max_retries: 0,
                    retry_interval: 1, backoff_factor: 2,
                    retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
                    retry_methods: %i[get put], environment: 'production',
                    custom_url: 'https://connect.squareup.com',
-                   square_version: '2021-12-15', access_token: '',
+                   square_version: '2022-03-16', access_token: '',
                    user_agent_detail: '', additional_headers: {})
-      # The Http Client passed from the sdk user for making requests
-      @http_client_instance = http_client_instance
+      # The Faraday connection object passed by the SDK user for making requests
+      @connection = connection
 
       # The value to use for connection timeout
       @timeout = timeout
@@ -61,14 +61,17 @@ module Square
 
       # The Http Client to use for making requests.
       @http_client = create_http_client
+
+      # User agent detail, to be appended with user-agent header.
+      @user_agent_detail = get_user_agent(user_agent_detail)
     end
 
-    def clone_with(http_client_instance: nil, timeout: nil, max_retries: nil,
+    def clone_with(connection: nil, timeout: nil, max_retries: nil,
                    retry_interval: nil, backoff_factor: nil,
                    retry_statuses: nil, retry_methods: nil, environment: nil,
                    custom_url: nil, square_version: nil, access_token: nil,
                    user_agent_detail: nil, additional_headers: nil)
-      http_client_instance ||= self.http_client_instance
+      connection ||= self.connection
       timeout ||= self.timeout
       max_retries ||= self.max_retries
       retry_interval ||= self.retry_interval
@@ -82,8 +85,8 @@ module Square
       user_agent_detail ||= self.user_agent_detail
       additional_headers ||= self.additional_headers
 
-      Configuration.new(http_client_instance: http_client_instance,
-                        timeout: timeout, max_retries: max_retries,
+      Configuration.new(connection: connection, timeout: timeout,
+                        max_retries: max_retries,
                         retry_interval: retry_interval,
                         backoff_factor: backoff_factor,
                         retry_statuses: retry_statuses,
@@ -99,8 +102,13 @@ module Square
                         retry_interval: retry_interval,
                         backoff_factor: backoff_factor,
                         retry_statuses: retry_statuses,
-                        retry_methods: retry_methods,
-                        http_client_instance: http_client_instance)
+                        retry_methods: retry_methods, connection: connection)
+    end
+
+    def get_user_agent(user_agent_detail)
+      raise ArgumentError, 'The length of user-agent detail should not exceed 128 characters.' unless user_agent_detail.length < 128
+
+      user_agent_detail
     end
 
     # All the environments the SDK can run in.

data/lib/square/http/faraday_client.rb

@@ -4,29 +4,28 @@ require 'faraday_middleware'
 module Square
   # An implementation of HttpClient.
   class FaradayClient < HttpClient
+    # The attribute readers for properties.
+    attr_reader :connection
+
     # The constructor.
     def initialize(timeout:, max_retries:, retry_interval:,
                    backoff_factor:, retry_statuses:, retry_methods:,
-                   http_client_instance: nil, cache: false, verify: true)
-      if http_client_instance.nil?
-        create_connection(timeout: timeout, max_retries: max_retries,
-                          retry_interval: retry_interval, backoff_factor: backoff_factor,
-                          retry_statuses: retry_statuses, retry_methods: retry_methods,
-                          cache: cache, verify: verify)
-      else
-        if http_client_instance.instance_variable_get('@connection').nil?
-          raise ArgumentError,
-                "`connection` cannot be nil in `#{self.class}`. Please specify a valid value."
-        end
-        @connection = http_client_instance.instance_variable_get('@connection')
-      end
+                   connection: nil, cache: false, verify: true)
+      @connection = if connection.nil?
+                      create_connection(timeout: timeout, max_retries: max_retries,
+                                        retry_interval: retry_interval, backoff_factor: backoff_factor,
+                                        retry_statuses: retry_statuses, retry_methods: retry_methods,
+                                        cache: cache, verify: verify)
+                    else
+                      connection
+                    end
     end
 
     # Method to initialize connection.
     def create_connection(timeout:, max_retries:, retry_interval:,
                           backoff_factor:, retry_statuses:, retry_methods:,
                           cache: false, verify: true)
-      @connection = Faraday.new do |faraday|
+      Faraday.new do |faraday|
         faraday.use Faraday::HttpCache, serializer: Marshal if cache
         faraday.use FaradayMiddleware::FollowRedirects
         faraday.use :gzip
@@ -42,7 +41,6 @@ module Square
         faraday.options[:params_encoder] = Faraday::FlatParamsEncoder
         faraday.options[:timeout] = timeout if timeout.positive?
       end
-      @connection
     end
 
     # Method overridden from HttpClient.

data/lib/square.rb

@@ -63,3 +63,4 @@ require_relative 'square/api/snippets_api'
 require_relative 'square/api/subscriptions_api'
 require_relative 'square/api/team_api'
 require_relative 'square/api/terminal_api'
+require_relative 'square/api/vendors_api'

data/test/api/test_locations_api.rb

@@ -7,7 +7,7 @@ class LocationsApiTests < ApiTestBase
     @controller = LocationsApi.new CONFIG, http_call_back: @response_catcher
   end
 
-  # Provides details about all of the seller's locations,
+  # Provides details about all of the seller's [locations](https://developer.squareup.com/docs/locations-api),
   #including those with an inactive status.
   def test_list_locations()
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: square.rb
 version: !ruby/object:Gem::Version
-  version: 17.0.0.20211215
+  version: 18.1.0.20220316
 platform: ruby
 authors:
 - Square Developer Platform
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-15 00:00:00.000000000 Z
+date: 2022-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logging
@@ -170,6 +170,7 @@ files:
 - lib/square/api/terminal_api.rb
 - lib/square/api/transactions_api.rb
 - lib/square/api/v1_transactions_api.rb
+- lib/square/api/vendors_api.rb
 - lib/square/api_helper.rb
 - lib/square/client.rb
 - lib/square/configuration.rb