square.rb 16.0.1.20211117 → 17.0.0.20211215

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaa278b9bc1f61b0e659dbe860cfc070db0e2e0f6d281def02b9f27bc42da721
-  data.tar.gz: 11e335e2982f650a5af6b7ee93e70c6574652f70e6154d71b484d0e7ad7415f9
+  metadata.gz: 28048e0ca738b0ca2de7579b8dc077c0307266afa1ff42c1ee6808eb64c79f43
+  data.tar.gz: 7ba3afdb67a42eb41864d5fe5839b8b74f525eebac2b6348e51aee92c9399328
 SHA512:
-  metadata.gz: 7e54deb4e4f35f0796c9cd65b191282d95cf088812c2b23a072cdc37212283c739ec98848488c046403df8b2ff146146459c1232ab40f9ef29edcc9f7d107597
-  data.tar.gz: 1984f4566d0e0c03258ad3b230a4a25a12113fb5f7a02412bb512ae0d47684c4449ab314d83f4cfb1084b882a11a8dceec83d414e7cace41ed454914857a75ba
+  metadata.gz: 2bf8bcf75bf6558596e20c1f9d3c82d579aa20f4964047c94bc43592b2e1b0f28445d1f788ba30e1272095380a07a5350fc4c2f8082097b12ef29eb424b33bfd
+  data.tar.gz: 4b09ca82e2b15e60b7ae1a7c217bf445cfb8dd0f6ceb60d6e835d08a5ef08657054d15cc58124d85a1be2f30a8d67630a55caaf58c0942cb92de81ec426cfe6d

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.1.20211117',
+        'user-agent' => get_user_agent,
         'Square-Version' => config.square_version
       }
     end
@@ -35,5 +36,10 @@ module Square
 
       response
     end
+
+    def get_user_agent
+      user_agent = 'Square-Ruby-SDK/17.0.0.20211215'
+      user_agent
+    end
   end
 end

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,8 @@ 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,
+    # including those with an inactive status.
     # @return [ListLocationsResponse Hash] response from the API call
     def list_locations
       # Prepare query url.
@@ -37,7 +35,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 +79,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.

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

@@ -4,13 +4,17 @@ module Square
     attr_reader :config
 
     def sdk_version
-      '16.0.1.20211117'
+      '17.0.0.20211215'
     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
@@ -214,8 +218,8 @@ module Square
                    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: '2021-12-15', 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,
@@ -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

@@ -5,7 +5,7 @@ module Square
     # 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
+                :square_version, :access_token, :user_agent_detail
 
     def additional_headers
       @additional_headers.clone
@@ -20,8 +20,8 @@ module Square
                    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: {})
+                   square_version: '2021-12-15', access_token: '',
+                   user_agent_detail: '', additional_headers: {})
       # The Http Client passed from the sdk user for making requests
       @http_client_instance = http_client_instance
 
@@ -67,7 +67,7 @@ module Square
                    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)
+                   user_agent_detail: nil, additional_headers: nil)
       http_client_instance ||= self.http_client_instance
       timeout ||= self.timeout
       max_retries ||= self.max_retries
@@ -79,6 +79,7 @@ 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,
@@ -89,6 +90,7 @@ module Square
                         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
 

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,
+  #including those with an inactive status.
   def test_list_locations()
 
     # Perform the API call through the SDK function

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: square.rb
 version: !ruby/object:Gem::Version
-  version: 16.0.1.20211117
+  version: 17.0.0.20211215
 platform: ruby
 authors:
 - Square Developer Platform
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-11-29 00:00:00.000000000 Z
+date: 2021-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logging