square.rb 3.20191023.0 → 3.20191120.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6869181c2882291f8cf94d596adb12e137061d21e37f1db4a5c89487fee34569
-  data.tar.gz: 5c25f08d601e4907f0b4e528d1d1ecf5e995d3ccf596a7a44dd0ace25fc03db9
+  metadata.gz: cd071af18802847ca0f4c4c2fa3578e295f341a253b464f5f43a1d3ea2822fed
+  data.tar.gz: 835014bce207c0a306b60c3ca6241534b425443052c5575f0775531821049119
 SHA512:
-  metadata.gz: 80e91e32562c8721e2d9c64a4bd338640118a26a76776b54b220d5c133b230a8a906a8fc4c75a378bf6918f3d2751d724e0e9c1e4a1adde7610483b1febbae68
-  data.tar.gz: 7e6ba403f41403e826c245fa083357170f7f312659524c2f28b1e4aa2edfc2af564be057a6386870c9da22a6482f85b9d77c37eaceccefd50d43acb6f8c68ecc
+  metadata.gz: 5aa677990bba8f49076dc13214bd597b90759feaa5438a78fae0834a1332916586d355abd49e895e5527fdf18246611790be72bbf406f92391a5214474ebdde3
+  data.tar.gz: c7a87fd601213ddbecd02d44e54a7cc56cc0fcd9c45379224327d239fd5e1a62465b8850f71f849d281e80bc2d301db1c807a2a37a03a5955e2ff323a34905a0

data/lib/square/api/apple_pay_api.rb

@@ -18,9 +18,9 @@ module Square
     # activate
     # Web Apple Pay with Square for merchants using their platform.
     # To learn more about Apple Pay on Web see the Apple Pay section in the
-    # [Embedding the Square Payment
-    # Form](https://developer.squareup.com/docs/payment-form/add-digital-wallets
-    # /apple-pay) guide.
+    # [Square Payment Form
+    # Walkthrough](https://developer.squareup.com/docs/docs/payment-form/payment
+    # -form-walkthrough).
     # @param [RegisterDomainRequest] 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/base_api.rb

@@ -13,8 +13,8 @@ module Square
       @http_call_back = http_call_back
 
       @global_headers = {
-        'user-agent' => 'Square-Ruby-SDK/3.20191023.0',
-        'Square-Version' => '2019-10-23'
+        'user-agent' => 'Square-Ruby-SDK/3.20191120.0',
+        'Square-Version' => '2019-11-20'
       }
     end
 

data/lib/square/api/catalog_api.rb

@@ -136,6 +136,89 @@ module Square
       ApiResponse.new(_response, data: decoded, errors: _errors)
     end
 
+    # Upload an image file to create a new [CatalogImage](#type-catalogimage)
+    # for an existing
+    # [CatalogObject](#type-catalogobject). Images can be uploaded and linked in
+    # this request or created independently
+    # (without an object assignment) and linked to a
+    # [CatalogObject](#type-catalogobject) at a later time.
+    # CreateCatalogImage 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. The
+    # following is an example of such an HTTP request:
+    # ```
+    # POST /v2/catalog/images
+    # Accept: application/json
+    # Content-Type: multipart/form-data;boundary="boundary"
+    # Square-Version: XXXX-XX-XX
+    # Authorization: Bearer {ACCESS_TOKEN}
+    # --boundary
+    # Content-Disposition: form-data; name="request"
+    # Content-Type: application/json
+    # {
+    # "idempotency_key":"528dea59-7bfb-43c1-bd48-4a6bba7dd61f86",
+    # "object_id": "ND6EA5AAJEO5WL3JNNIAQA32",
+    # "image":{
+    # "id":"#TEMP_ID",
+    # "type":"IMAGE",
+    # "image_data":{
+    # "caption":"A picture of a cup of coffee"
+    # }
+    # }
+    # }
+    # --boundary
+    # Content-Disposition: form-data; name="image"; filename="Coffee.jpg"
+    # Content-Type: image/jpeg
+    # {ACTUAL_IMAGE_BYTES}
+    # --boundary
+    # ```
+    # Additional information and an example cURL request can be found in the
+    # [Create a Catalog Image
+    # recipe](https://developer.squareup.com/docs/more-apis/catalog/cookbook/cre
+    # ate-catalog-images).
+    # @param [CreateCatalogImageRequest] request Optional parameter: Example:
+    # @param [File | UploadIO] image_file Optional parameter: Example:
+    # @return [CreateCatalogImageResponse Hash] response from the API call
+    def create_catalog_image(request: nil,
+                             image_file: nil)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/catalog/images'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # 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,
+          'image/jpeg'
+        )
+      }
+      _parameters = APIHelper.form_encode_parameters(_parameters)
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _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
+
     # Returns information about the Square Catalog API, such as batch size
     # limits for `BatchUpsertCatalogObjects`.
     # @return [CatalogInfoResponse Hash] response from the API call
@@ -185,9 +268,8 @@ module Square
     # @param [String] types Optional parameter: An optional case-insensitive,
     # comma-separated list of object types to retrieve, for example
     # `ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.  The legal values are taken from the
-    # [CatalogObjectType](#type-catalogobjecttype) enumeration, namely `ITEM`,
-    # `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`,
-    # `MODIFIER_LIST`, or `IMAGE`.
+    # CatalogObjectType enum: `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`,
+    # `TAX`, `MODIFIER`, `MODIFIER_LIST`, or `IMAGE`.
     # @return [ListCatalogResponse Hash] response from the API call
     def list_catalog(cursor: nil,
                      types: nil)
@@ -260,11 +342,10 @@ module Square
     # are also deleted. For example, deleting a [CatalogItem](#type-catalogitem)
     # will also delete all of its
     # [CatalogItemVariation](#type-catalogitemvariation) children.
-    # @param [String] object_id Required parameter: The ID of the
-    # [CatalogObject](#type-catalogobject) to be deleted. When an object is
-    # deleted, other objects in the graph that depend on that object will be
-    # deleted as well (for example, deleting a [CatalogItem](#type-catalogitem)
-    # will delete its [CatalogItemVariation](#type-catalogitemvariation)s).
+    # @param [String] object_id Required parameter: The ID of the catalog object
+    # to be deleted. When an object is deleted, other objects in the graph that
+    # depend on that object will be deleted as well (for example, deleting a
+    # catalog item will delete its catalog item variations).
     # @return [DeleteCatalogObjectResponse Hash] response from the API call
     def delete_catalog_object(object_id:)
       # Prepare query url.
@@ -304,18 +385,16 @@ module Square
     # [CatalogModifierList](#type-catalogmodifierlist) objects, and the ids of
     # any [CatalogTax](#type-catalogtax) objects that apply to it.
     # @param [String] object_id Required parameter: The object ID of any type of
-    # [CatalogObject](#type-catalogobject)s to be retrieved.
+    # 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](#type-catalogitem), its associated
-    # [CatalogCategory](#type-catalogcategory),
-    # [CatalogTax](#type-catalogtax)es, [CatalogImage](#type-catalogimage)s and
-    # [CatalogModifierList](#type-catalogmodifierlist)s will be returned in the
+    # contains a CatalogItem, its associated CatalogCategory, CatalogTax
+    # objects, CatalogImages and CatalogModifierLists will be returned in the
     # `related_objects` field of the response. If the `object` field of the
-    # response contains a [CatalogItemVariation](#type-catalogitemvariation),
-    # its parent [CatalogItem](#type-catalogitem) will be returned in the
-    # `related_objects` field of  the response.  Default value: `false`
+    # response contains a CatalogItemVariation, its parent CatalogItem will be
+    # returned in the `related_objects` field of the response.  Default value:
+    # `false`
     # @return [RetrieveCatalogObjectResponse Hash] response from the API call
     def retrieve_catalog_object(object_id:,
                                 include_related_objects: nil)
@@ -359,6 +438,16 @@ module Square
     # [CatalogQueryItemsForTax](#type-catalogqueryitemsfortax), and
     # [CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierlist)
     # .
+    # --
+    # --
+    # Future end of the above comment:
+    # [CatalogQueryItemsForTax](#type-catalogqueryitemsfortax),
+    # [CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierlist)
+    # ,
+    # [CatalogQueryItemsForItemOptions](#type-catalogqueryitemsforitemoptions),
+    # and
+    # [CatalogQueryItemVariationsForItemOptionValues](#type-catalogqueryitemvari
+    # ationsforitemoptionvalues).
     # @param [SearchCatalogObjectsRequest] 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/customers_api.rb

@@ -13,14 +13,14 @@ module Square
     # Lists a business's customers.
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this to retrieve the next set of
-    # results for your original query.  See
-    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
+    # results for your original query.  See the [Pagination
+    # guide](https://developer.squareup.com/docs/working-with-apis/pagination)
     # for more information.
     # @param [CustomerSortField] sort_field Optional parameter: Indicates how
-    # Customers should be sorted. Default: `DEFAULT`.
+    # Customers should be sorted.  Default: `DEFAULT`.
     # @param [SortOrder] sort_order Optional parameter: Indicates whether
     # Customers should be sorted in ascending (`ASC`) or descending (`DESC`)
-    # order. Default: `ASC`.
+    # order.  Default: `ASC`.
     # @return [ListCustomersResponse Hash] response from the API call
     def list_customers(cursor: nil,
                        sort_field: nil,
@@ -208,10 +208,9 @@ module Square
     # You cannot edit a customer's cards on file with this endpoint. To make
     # changes
     # to a card on file, you must delete the existing card on file with the
-    # [DeleteCustomerCard](#endpoint-customers-deletecustomercard) endpoint,
-    # then
-    # create a new one with the
-    # [CreateCustomerCard](#endpoint-customers-createcustomercard) endpoint.
+    # [DeleteCustomerCard](#endpoint-deletecustomercard) endpoint, then create a
+    # new one with the
+    # [CreateCustomerCard](#endpoint-createcustomercard) endpoint.
     # @param [String] customer_id Required parameter: The ID of the customer to
     # update.
     # @param [UpdateCustomerRequest] body Required parameter: An object
@@ -255,8 +254,6 @@ module Square
     # calls with the same card nonce return the same card record that was
     # created
     # with the provided nonce during the _first_ call.
-    # Cards on file are automatically updated on a monthly basis to confirm they
-    # are still valid and can be charged.
     # @param [String] customer_id Required parameter: The Square ID of the
     # customer profile the card is linked to.
     # @param [CreateCustomerCardRequest] body Required parameter: An object

data/lib/square/api/employees_api.rb

@@ -10,7 +10,7 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Gets a list of `Employee` objects for a business.
+    # ListEmployees
     # @param [String] location_id Optional parameter: Filter employees returned
     # to only those that are associated with the specified location.
     # @param [EmployeeStatus] status Optional parameter: Specifies the
@@ -55,7 +55,7 @@ module Square
       ApiResponse.new(_response, data: decoded, errors: _errors)
     end
 
-    # Gets an `Employee` by Square-assigned employee `ID` (UUID)
+    # RetrieveEmployee
     # @param [String] id Required parameter: UUID for the employee that was
     # requested.
     # @return [RetrieveEmployeeResponse Hash] response from the API call

data/lib/square/api/inventory_api.rb

@@ -202,9 +202,9 @@ module Square
     # empty list queries all locations.
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this to retrieve the next set of
-    # results for the original query.  See
-    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
-    # for more information.
+    # results for the original query.  See the
+    # [Pagination](https://developer.squareup.com/docs/docs/working-with-apis/pa
+    # gination) guide for more information.
     # @return [RetrieveInventoryCountResponse Hash] response from the API call
     def retrieve_inventory_count(catalog_object_id:,
                                  location_ids: nil,
@@ -257,9 +257,9 @@ module Square
     # empty list queries all locations.
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this to retrieve the next set of
-    # results for the original query.  See
-    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
-    # for more information.
+    # results for the original query.  See the
+    # [Pagination](https://developer.squareup.com/docs/docs/working-with-apis/pa
+    # gination) guide for more information.
     # @return [RetrieveInventoryChangesResponse Hash] response from the API call
     def retrieve_inventory_changes(catalog_object_id:,
                                    location_ids: nil,

data/lib/square/api/locations_api.rb

@@ -10,7 +10,7 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Provides the details for all of a business's locations.
+    # Provides information of all locations of a business.
     # Most other Connect API endpoints have a required `location_id` path
     # parameter.
     # The `id` field of the [`Location`](#type-location) objects returned by
@@ -42,6 +42,40 @@ module Square
       ApiResponse.new(_response, data: decoded, errors: _errors)
     end
 
+    # Creates a location.
+    # For more information about locations, see [Locations API
+    # Overview](https://developer.squareup.com/docs/locations-api).
+    # @param [CreateLocationRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [CreateLocationResponse Hash] response from the API call
+    def create_location(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/locations'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'content-type' => 'application/json; charset=utf-8'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _query_url,
+        headers: _headers,
+        parameters: body.to_json
+      )
+      OAuth2.apply(config, _request)
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(_response, data: decoded, errors: _errors)
+    end
+
     # Retrieves details of a location.
     # @param [String] location_id Required parameter: The ID of the location to
     # retrieve.
@@ -75,7 +109,7 @@ module Square
       ApiResponse.new(_response, data: decoded, errors: _errors)
     end
 
-    # Updates the `Location` specified by the given ID.
+    # Updates a location.
     # @param [String] location_id Required parameter: The ID of the location to
     # update.
     # @param [UpdateLocationRequest] body Required parameter: An object

data/lib/square/api/mobile_authorization_api.rb

@@ -19,9 +19,10 @@ module Square
     # ```
     # Authorization: Bearer ACCESS_TOKEN
     # ```
-    # Replace `ACCESS_TOKEN` with a [valid production authorization
-    # credential](https://developer.squareup.com/docs/get-started#step-4-underst
-    # and-the-different-application-credentials).
+    # Replace `ACCESS_TOKEN` with a
+    # [valid production authorization
+    # credential](https://developer.squareup.com/docs/docs/build-basics/access-t
+    # okens).
     # @param [CreateMobileAuthorizationCodeRequest] 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/o_auth_api.rb

@@ -31,7 +31,7 @@ module Square
     # Replace `APPLICATION_SECRET` with the application secret on the
     # Credentials
     # page in the [application dashboard](https://connect.squareup.com/apps).
-    # @param [String] client_id Required parameter: Your application's ID,
+    # @param [String] client_id Required parameter: Your application ID,
     # available from the [application
     # dashboard](https://connect.squareup.com/apps).
     # @param [RenewTokenRequest] body Required parameter: An object containing

data/lib/square/api/refunds_api.rb

@@ -29,12 +29,12 @@ module Square
     # @param [String] location_id Optional parameter: ID of location associated
     # with payment.
     # @param [String] status Optional parameter: If provided, only refunds with
-    # the given status are returned.  For a list of refund status values, see
+    # the given status are returned. For a list of refund status values, see
     # [PaymentRefund](#type-paymentrefund).  Default: If omitted refunds are
     # returned regardless of 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 payment  source.  Default: If omitted
+    # with the given source type are returned. - `CARD` - List refunds only for
+    # payments where card was specified as payment source.  Default: If omitted
     # refunds are returned regardless of source type.
     # @return [ListPaymentRefundsResponse Hash] response from the API call
     def list_payment_refunds(begin_time: nil,

data/lib/square/api/reporting_api.rb

@@ -30,9 +30,8 @@ module Square
     # newest first).  Default value: `DESC`
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this to retrieve the next set of
-    # results for your original query.  See
-    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
-    # for more information.
+    # results for your original query.  See [Paginating
+    # results](#paginatingresults) for more information.
     # @return [ListAdditionalRecipientReceivableRefundsResponse Hash] response from the API call
     def list_additional_recipient_receivable_refunds(location_id:,
                                                      begin_time: nil,
@@ -96,9 +95,8 @@ module Square
     # newest first).  Default value: `DESC`
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this to retrieve the next set of
-    # results for your original query.  See
-    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
-    # for more information.
+    # results for your original query.  See [Paginating
+    # results](#paginatingresults) for more information.
     # @return [ListAdditionalRecipientReceivablesResponse Hash] response from the API call
     def list_additional_recipient_receivables(location_id:,
                                               begin_time: nil,

data/lib/square/api/transactions_api.rb

@@ -34,9 +34,8 @@ module Square
     # newest first).  Default value: `DESC`
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this to retrieve the next set of
-    # results for your original query.  See
-    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
-    # for more information.
+    # results for your original query.  See [Paginating
+    # results](#paginatingresults) for more information.
     # @return [ListRefundsResponse Hash] response from the API call
     def list_refunds(location_id:,
                      begin_time: nil,
@@ -100,9 +99,8 @@ module Square
     # newest first).  Default value: `DESC`
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this to retrieve the next set of
-    # results for your original query.  See
-    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
-    # for more information.
+    # results for your original query.  See [Paginating
+    # results](#paginatingresults) for more information.
     # @return [ListTransactionsResponse Hash] response from the API call
     def list_transactions(location_id:,
                           begin_time: nil,
@@ -154,10 +152,16 @@ module Square
     # - Values for the `customer_card_id` and `customer_id` parameters (to
     # charge
     # a customer's card on file)
+    # In order for an eCommerce payment to potentially qualify for
+    # [Square chargeback protection](https://squareup.com/help/article/5394),
+    # you
+    # _must_ provide values for the following parameters in your request:
+    # - `buyer_email_address`
+    # - At least one of `billing_address` or `shipping_address`
     # When this response is returned, the amount of Square's processing fee
     # might not yet be
     # calculated. To obtain the processing fee, wait about ten seconds and call
-    # [RetrieveTransaction](#endpoint-transactions-retrievetransaction). See the
+    # [RetrieveTransaction](#endpoint-retrievetransaction). See the
     # `processing_fee_money`
     # field of each [Tender included](#type-tender) in the transaction.
     # @param [String] location_id Required parameter: The ID of the location to
@@ -240,12 +244,12 @@ module Square
     end
 
     # Captures a transaction that was created with the
-    # [Charge](#endpoint-transactions-charge)
+    # [Charge](#endpoint-charge)
     # endpoint with a `delay_capture` value of `true`.
-    # See the [Delay Capture of
-    # Funds](https://developer.squareup.com/docs/transactions-api/cookbook/delay
-    # -capture)
-    # recipe for more information.
+    # See [Delayed capture
+    # transactions](https://developer.squareup.com/docs/payments/transactions/ov
+    # erview#delayed-capture)
+    # for more information.
     # @param [String] location_id Required parameter: Example:
     # @param [String] transaction_id Required parameter: Example:
     # @return [CaptureTransactionResponse Hash] response from the API call
@@ -334,13 +338,12 @@ module Square
       ApiResponse.new(_response, data: decoded, errors: _errors)
     end
 
-    # Cancels a transaction that was created with the
-    # [Charge](#endpoint-transactions-charge)
+    # Cancels a transaction that was created with the [Charge](#endpoint-charge)
     # endpoint with a `delay_capture` value of `true`.
-    # See the [Delay Capture of
-    # Funds](https://developer.squareup.com/docs/transactions-api/cookbook/delay
-    # -capture)
-    # recipe for more information.
+    # See [Delayed capture
+    # transactions](https://developer.squareup.com/docs/payments/transactions/ov
+    # erview#delayed-capture)
+    # for more information.
     # @param [String] location_id Required parameter: Example:
     # @param [String] transaction_id Required parameter: Example:
     # @return [VoidTransactionResponse Hash] response from the API call