square.rb 16.0.0.20211117 → 18.0.0.20220216

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25ab6d01177792b1eb326af1a782a12ab26eff2678b44666aac14954907740e2
-  data.tar.gz: 1ba81bfd71af7fd3124015de59166e33401f0e230301d4ea45e6c70438380741
+  metadata.gz: d63ad56661f521ead949670191ddb004cf944daedf7836047c9281e8e6600ecf
+  data.tar.gz: 548171c3a90103f2a2492166e6b69f9c0dd7855f1c20d656e4c7c1f922053e86
 SHA512:
-  metadata.gz: c0fa97ef6d70db8247d6a14cb946a942f9327faa37e881ce8628cd8f68e38bb6c91238cf10419dc915597701b69c73ecb0f1813d45be4d6f37eaa837c1646364
-  data.tar.gz: a9337cd596b733099e84765048134f4edc183f548ac6638da50257bfb0d3b0529271d17c509a1f9b34342abe9e7184d56ec4fe1f292ea1fa2ad36036228384d1
+  metadata.gz: 4d5f5cdb0c4992a16eca7327a67642d9fcb807ae040b7c3426d5635ac3ef9f40ab9d144fe011b60c5ad996b81b098e49a3e4cf8a3e6aa3dd4742fab08fd6e1b3
+  data.tar.gz: 56b7b2f269877ec3b2f867d608e0a803a066e74bc958d2e0f60e156a034360e872d0c7eccefa5d552a35b700f2c9cb83b364a942e96968a713ab33013069dea5

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

@@ -10,7 +10,7 @@ Use this gem to integrate Square payments into your app and grow your business w
 
 ## Requirements
 
-We support Ruby 2.5.x, 2.6.x, and 2.7.x.
+We support Ruby 2.6 through 3.1.
 
 ## Installation
 

data/lib/square/api/base_api.rb

@@ -1,3 +1,4 @@
+require 'erb'
 module Square
   # BaseApi.
   class BaseApi
@@ -8,7 +9,7 @@ module Square
       @http_call_back = http_call_back
 
       @global_headers = {
-        'user-agent' => 'Square-Ruby-SDK/16.0.0.20211117',
+        'user-agent' => get_user_agent,
         'Square-Version' => config.square_version
       }
     end
@@ -35,5 +36,19 @@ module Square
 
       response
     end
+
+    def get_user_agent
+      user_agent = 'Square-Ruby-SDK/18.0.0.20220216 ({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
 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/catalog_api.rb

@@ -136,10 +136,10 @@ module Square
     end
 
     # Uploads an image file to be represented by a
-    # [CatalogImage]($m/CatalogImage) object linked to an existing
-    # [CatalogObject]($m/CatalogObject) instance. A call to this endpoint can
-    # upload an image, link an image to
-    # a catalog object, or do both.
+    # [CatalogImage]($m/CatalogImage) object that can be linked to an existing
+    # [CatalogObject]($m/CatalogObject) instance. The resulting `CatalogImage`
+    # is unattached to any `CatalogObject` if the `object_id`
+    # is not specified.
     # This `CreateCatalogImage` endpoint accepts HTTP multipart/form-data
     # requests with a JSON part and an image file part in
     # JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.
@@ -196,6 +196,71 @@ module Square
       )
     end
 
+    # Uploads a new image file to replace the existing one in the specified
+    # [CatalogImage]($m/CatalogImage) object.
+    # This `UpdateCatalogImage` endpoint accepts HTTP multipart/form-data
+    # requests with a JSON part and an image file part in
+    # JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.
+    # @param [String] image_id Required parameter: The ID of the `CatalogImage`
+    # object to update the encapsulated image file.
+    # @param [UpdateCatalogImageRequest] request Optional parameter: Example:
+    # @param [File | UploadIO] image_file Optional parameter: Example:
+    # @return [UpdateCatalogImageResponse Hash] response from the API call
+    def update_catalog_image(image_id:,
+                             request: nil,
+                             image_file: nil)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/catalog/images/{image_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'image_id' => { 'value' => image_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      if image_file.is_a? FileWrapper
+        image_file_wrapper = image_file.file
+        image_file_content_type = image_file.content_type
+      else
+        image_file_wrapper = image_file
+        image_file_content_type = 'image/jpeg'
+      end
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare form parameters.
+      _parameters = {
+        'request' => Faraday::UploadIO.new(
+          StringIO.new(request.to_json),
+          'application/json'
+        ),
+        'image_file' => Faraday::UploadIO.new(
+          image_file_wrapper,
+          image_file_content_type
+        )
+      }
+      _parameters = APIHelper.form_encode_parameters(_parameters)
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.put(
+        _query_url,
+        headers: _headers,
+        parameters: _parameters
+      )
+      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 information about the Square Catalog API, such as batch size
     # limits that can be used by the `BatchUpsertCatalogObjects` endpoint.
     # @return [CatalogInfoResponse Hash] response from the API call
@@ -226,15 +291,12 @@ module Square
       )
     end
 
-    # Returns a list of [CatalogObject]($m/CatalogObject)s that includes
-    # all objects of a set of desired types (for example, all
-    # [CatalogItem]($m/CatalogItem)
-    # and [CatalogTax]($m/CatalogTax) objects) in the catalog. The `types`
-    # parameter
-    # is specified as a comma-separated list of valid
-    # [CatalogObject]($m/CatalogObject) types:
-    # `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`,
-    # `DISCOUNT`, `TAX`, `IMAGE`.
+    # Returns a list of all [CatalogObject]($m/CatalogObject)s of the specified
+    # types in the catalog.
+    # The `types` parameter is specified as a comma-separated list of the
+    # [CatalogObjectType]($m/CatalogObjectType) values,
+    # for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`,
+    # `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`".
     # __Important:__ ListCatalog does not return deleted catalog items. To
     # retrieve
     # deleted catalog items, use
@@ -247,16 +309,22 @@ module Square
     # for more information.
     # @param [String] types Optional parameter: An optional case-insensitive,
     # 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.
+    # defined in the [CatalogObjectType]($m/CatalogObjectType) enum, for
+    # example, `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
+    # `MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.  If this is unspecified, the
+    # operation returns objects of all the top level types at the version of the
+    # Square API used to make the request. Object types that are nested onto
+    # other object types are not included in the defaults.  At the current API
+    # version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT,
+    # MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, SERVICE_CHARGE, PRICING_RULE,
+    # PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN,
+    # ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS.
     # @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
     # matched against the [CatalogObject]($m/CatalogObject)s' `version`
-    # attribute.
+    # attribute.  If not included, results will be from the current version of
+    # the catalog.
     # @return [ListCatalogResponse Hash] response from the API call
     def list_catalog(cursor: nil,
                      types: nil,
@@ -382,17 +450,24 @@ module Square
     # catalog objects to be retrieved.
     # @param [Boolean] include_related_objects Optional parameter: If `true`,
     # the response will include additional objects that are related to the
-    # requested object, as follows:  If the `object` field of the response
-    # contains a `CatalogItem`, its associated `CatalogCategory`, `CatalogTax`,
-    # `CatalogImage` and `CatalogModifierList` objects will be returned in the
-    # `related_objects` field of the response. If the `object` field of the
-    # response contains a `CatalogItemVariation`, its parent `CatalogItem` will
-    # be returned in the `related_objects` field of the response.  Default
-    # value: `false`
+    # requested objects. Related objects are defined as any objects referenced
+    # by ID by the results in the `objects` field of the response. These objects
+    # are put in the `related_objects` field. Setting this to `true` is helpful
+    # when the objects are needed for immediate display to a user. This process
+    # only goes one level deep. Objects referenced by the related objects will
+    # not be included. For example,  if the `objects` field of the response
+    # contains a CatalogItem, its associated CatalogCategory objects, CatalogTax
+    # objects, CatalogImage objects and CatalogModifierLists will be returned in
+    # the `related_objects` field of the response. If the `objects` field of the
+    # response contains a CatalogItemVariation, its parent CatalogItem will be
+    # returned in the `related_objects` field of the response.  Default value:
+    # `false`
     # @param [Long] catalog_version Optional parameter: Requests objects as of a
     # specific version of the catalog. This allows you to retrieve historical
     # versions of objects. The value to retrieve a specific version of an object
     # can be found in the version field of [CatalogObject]($m/CatalogObject)s.
+    # If not included, results will be from the current version of the
+    # catalog.
     # @return [RetrieveCatalogObjectResponse Hash] response from the API call
     def retrieve_catalog_object(object_id:,
                                 include_related_objects: false,

data/lib/square/api/locations_api.rb

@@ -5,10 +5,9 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Provides information of all locations of a business.
-    # Many Square API endpoints require a `location_id` parameter.
-    # The `id` field of the [`Location`]($m/Location) objects returned by this
-    # endpoint correspond to that `location_id` parameter.
+    # 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
       # Prepare query url.
@@ -37,7 +36,17 @@ module Square
       )
     end
 
-    # Creates a location.
+    # Creates a [location](https://developer.squareup.com/docs/locations-api).
+    # Creating new locations allows for separate configuration of receipt
+    # layouts, item prices,
+    # and sales reports. Developers can use locations to separate sales activity
+    # via applications
+    # that integrate with Square from sales activity elsewhere in a seller's
+    # account.
+    # Locations created programmatically with the Locations API will last
+    # forever and
+    # are visible to the seller for their own management, so ensure that
+    # each location has a sensible and unique name.
     # @param [CreateLocationRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -71,12 +80,12 @@ module Square
       )
     end
 
-    # Retrieves details of a location. You can specify "main"
-    # as the location ID to retrieve details of the
-    # main location.
+    # Retrieves details of a single location. Specify "main"
+    # as the location ID to retrieve details of the [main
+    # location](https://developer.squareup.com/docs/locations-api#about-the-main
+    # -location).
     # @param [String] location_id Required parameter: The ID of the location to
-    # retrieve. If you specify the string "main", then the endpoint returns the
-    # main location.
+    # retrieve. Specify the string "main" to return the main location.
     # @return [RetrieveLocationResponse Hash] response from the API call
     def retrieve_location(location_id:)
       # Prepare query url.
@@ -109,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.

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/mobile_authorization_api.rb

@@ -6,9 +6,9 @@ module Square
     end
 
     # Generates code to authorize a mobile application to connect to a Square
-    # card reader
-    # Authorization codes are one-time-use and expire __60 minutes__ after being
-    # issued.
+    # card reader.
+    # Authorization codes are one-time-use codes and expire 60 minutes after
+    # being issued.
     # __Important:__ The `Authorization` header you provide to this endpoint
     # must have the following format:
     # ```

data/lib/square/api/o_auth_api.rb

@@ -12,11 +12,11 @@ module Square
     # okens).
     # Renews an OAuth access token before it expires.
     # OAuth access tokens besides your application's personal access token
-    # expire after __30 days__.
-    # You can also renew expired tokens within __15 days__ of their expiration.
+    # expire after 30 days.
+    # You can also renew expired tokens within 15 days of their expiration.
     # You cannot renew an access token that has been expired for more than 15
     # days.
-    # Instead, the associated user must re-complete the OAuth flow from the
+    # Instead, the associated user must recomplete the OAuth flow from the
     # beginning.
     # __Important:__ The `Authorization` header for this endpoint must have the
     # following format:
@@ -25,10 +25,10 @@ module Square
     # ```
     # Replace `APPLICATION_SECRET` with the application secret on the
     # Credentials
-    # page in the [developer dashboard](https://developer.squareup.com/apps).
-    # @param [String] client_id Required parameter: Your application ID,
-    # available from the OAuth page for your  application on the Developer
-    # Dashboard.
+    # page in the [Developer Dashboard](https://developer.squareup.com/apps).
+    # @param [String] client_id Required parameter: Your application ID, which
+    # is available in the OAuth page in the [Developer
+    # Dashboard](https://developer.squareup.com/apps).
     # @param [RenewTokenRequest] body Required parameter: An object containing
     # the fields to POST for the request.  See the corresponding object
     # definition for field details.

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_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,13 +4,17 @@ module Square
     attr_reader :config
 
     def sdk_version
-      '16.0.0.20211117'
+      '18.0.0.20220216'
     end
 
     def square_version
       config.square_version
     end
 
+    def user_agent_detail
+      config.user_agent_detail
+    end
+
     # Access to mobile_authorization controller.
     # @return [MobileAuthorizationApi] Returns the controller instance.
     def mobile_authorization
@@ -209,16 +213,16 @@ module Square
       @terminal ||= TerminalApi.new config
     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-11-17', access_token: '',
-                   additional_headers: {}, config: nil)
+                   square_version: '2022-02-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,
@@ -227,6 +231,7 @@ module Square
                                     custom_url: custom_url,
                                     square_version: square_version,
                                     access_token: access_token,
+                                    user_agent_detail: user_agent_detail,
                                     additional_headers: additional_headers)
                 else
                   config

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
+    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-11-17', access_token: '',
-                   additional_headers: {})
-      # The Http Client passed from the sdk user for making requests
-      @http_client_instance = http_client_instance
+                   square_version: '2022-02-16', access_token: '',
+                   user_agent_detail: '', additional_headers: {})
+      # 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,
-                   additional_headers: nil)
-      http_client_instance ||= self.http_client_instance
+                   user_agent_detail: nil, additional_headers: nil)
+      connection ||= self.connection
       timeout ||= self.timeout
       max_retries ||= self.max_retries
       retry_interval ||= self.retry_interval
@@ -79,16 +82,18 @@ module Square
       custom_url ||= self.custom_url
       square_version ||= self.square_version
       access_token ||= self.access_token
+      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,
                         retry_methods: retry_methods, environment: environment,
                         custom_url: custom_url, square_version: square_version,
                         access_token: access_token,
+                        user_agent_detail: user_agent_detail,
                         additional_headers: additional_headers)
     end
 
@@ -97,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/test/api/test_locations_api.rb

@@ -7,11 +7,8 @@ class LocationsApiTests < ApiTestBase
     @controller = LocationsApi.new CONFIG, http_call_back: @response_catcher
   end
 
-  # Provides information of all locations of a business.
-  #
-  #Many Square API endpoints require a `location_id` parameter.
-  #The `id` field of the [`Location`]($m/Location) objects returned by this
-  #endpoint correspond to that `location_id` parameter.
+  # 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()
 
     # Perform the API call through the SDK function

data/test/test_helper.rb

@@ -82,7 +82,7 @@ class TestHelper
     unless @cache.keys.include? url  
       @cache[url] = Tempfile.new('APIMatic')
       @cache[url].binmode
-      @cache[url].write(open(url, {ssl_ca_cert: Certifi.where}).read)
+      @cache[url].write(URI.open(url, {ssl_ca_cert: Certifi.where}).read)
     end
     return @cache[url].path
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: square.rb
 version: !ruby/object:Gem::Version
-  version: 16.0.0.20211117
+  version: 18.0.0.20220216
 platform: ruby
 authors:
 - Square Developer Platform
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-11-17 00:00:00.000000000 Z
+date: 2022-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logging
@@ -209,9 +209,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ">="
     - !ruby/object:Gem::Version
       version: '2.5'
-  - - "<"
-    - !ruby/object:Gem::Version
-      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="