square.rb 6.3.0.20200826 → 17.1.0.20220120

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 973136d2e4f8177385869ee692c78d893fc79df5a5cb27512a57a24318027cfe
-  data.tar.gz: 8b502686044b15c7a047abc2c2a6dfa44cd7741406892b7bfb1f42e5a8af9190
+  metadata.gz: 407147246777f8a4eda2d4848cad5edb62be5801c25b6361f0dfb21d58663fd9
+  data.tar.gz: 735c7e92297b1d4a79ebd856dbe39cc304051536622f0277ddd9489811652cb6
 SHA512:
-  metadata.gz: 1138a5aeefa0e9f4a1c7fbb8d9275b7f9519bcd3092f7ee694818e00077c661893fa5c1c200d75b587bf8f6a4752b874c32f00a7f089036304302c880e5d2fc9
-  data.tar.gz: 669ef667f74ed01898f5fabcde7be3c92835878cc7a0fbded426b44906478a7c37dc72d1d3bd730c9d6b4701754592b24414cd33ca30402741664997907d403b
+  metadata.gz: 90ccb1516f8ff8998787d63a168c8c8688b9a12691d85cac3a2b6af35ce52af93bbc013e11336d5319cc252ec75ce7f790165ea5c38c69367f092e5ef62b365d
+  data.tar.gz: 05a3eb69caf678ad7f071b66a27c3ed4375ac96470ba09e51df9db6eba1401b80bd461c7fd6cb7bde91f30bb7ee5d11b9f7f293a59d40c70ab5ed52b25b9d180

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2020 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

@@ -2,12 +2,16 @@
 
 # Square Ruby SDK
 
-[![Travis status](https://travis-ci.org/square/square-ruby-sdk.svg?branch=master)](https://travis-ci.org/square/square-ruby-sdk)
+[![Build](https://github.com/square/square-ruby-sdk/actions/workflows/ruby.yml/badge.svg)](https://github.com/square/square-ruby-sdk/actions/workflows/ruby.yml)
 [![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.
 
+## Requirements
+
+We support Ruby 2.5.x, 2.6.x, 2.7.x, and 3.0.x.
+
 ## Installation
 
 Install the gem from the command line:
@@ -33,6 +37,9 @@ gem 'square.rb'
 * [Disputes]
 * [Checkout]
 * [Apple Pay]
+* [Cards]
+
+### Terminal
 * [Terminal]
 
 ### Orders
@@ -56,26 +63,36 @@ gem 'square.rb'
 ### Loyalty
 * [Loyalty]
 
+### Gift Cards
+* [Gift Cards]
+* [Gift Card Activities]
+
+### Bookings
+* [Bookings]
+
 ### Business
 * [Merchants]
 * [Locations]
 * [Devices]
+* [Cash Drawers]
 
 ### Team
 * [Team]
-* [Employees]
 * [Labor]
-* [Cash Drawers]
 
 ### Financials
 * [Bank Accounts]
 
+### Online
+* [Sites]
+* [Snippets]
+
 ### Authorization APIs
 * [Mobile Authorization]
-* [O Auth]
+* [OAuth]
 
 ### Deprecated APIs
-* [V1 Locations]
+* [Employees]
 * [V1 Employees]
 * [V1 Transactions]
 * [V1 Items]
@@ -98,8 +115,8 @@ require 'square'
 # for the Square account whose assets you want to manage.
 
 client = Square::Client.new(
-    access_token: 'YOUR SANDBOX ACCESS TOKEN HERE',
-    environment: 'sandbox'
+  access_token: 'YOUR SANDBOX ACCESS TOKEN HERE',
+  environment: 'sandbox'
 )
 
 # Call list_locations method to get all locations in this Square account
@@ -107,10 +124,10 @@ result = client.locations.list_locations
 
 # Call the #success? method to see if the call succeeded
 if result.success?
-	# The #data Struct contains a list of locations
+  # The #data Struct contains a list of locations
   locations = result.data.locations
 
-	# Iterate over the list
+  # Iterate over the list
   locations.each do |location|
     # Each location is represented as a Hash
     location.each do |key, value|
@@ -159,6 +176,7 @@ This error was returned when an invalid token was used to call the API.
 After you’ve tried out the Square APIs and tested your application using sandbox, you will want to switch to your production credentials so that you can manage real Square resources. Don't forget to switch your access token from sandbox to production for real data.
 
 ## SDK patterns
+
 If you know a few patterns, you’ll be able to call any API in the SDK. Here are some important ones:
 
 ### Get an access token
@@ -179,21 +197,31 @@ To use the Square API, you import the Client class, instantiate a Client object,
 
 - Instantiate a `Square::Client` object with the access token for the Square account whose resources you want to manage. To access sandbox resources, initialize the `Square::Client` with environment set to sandbox:
 
-```ruby
-client = Square::Client.new(
+  ```ruby
+  client = Square::Client.new(
     access_token: 'SANDBOX ACCESS TOKEN HERE',
     environment: 'sandbox'
-)
-```
+  )
+  ```
 
 - To access production resources, set environment to production:
 
-```ruby
-client = Square::Client.new(
+  ```ruby
+  client = Square::Client.new(
     access_token: 'ACCESS TOKEN HERE',
     environment: 'production'
-)
-```
+  )
+  ```
+
+- To set a custom environment provide a `custom_url`, and set environment to `custom`:
+
+  ```ruby
+  client = Square::Client.new(
+    access_token:'ACCESS TOKEN HERE',
+    environment: 'custom',
+    custom_url: 'https://your.customdomain.com'
+  )
+  ```
  
 ### Get an Instance of an API object and call its methods
 
@@ -201,9 +229,9 @@ Each API is implemented as a class. The Client object instantiates every API cla
 
 - Work with an API by calling the methods on the API object. For example, you would call list_customers to get a list of all customers in the Square account:
 
-```ruby
-result = client.customers.list_customers
-```
+  ```ruby
+  result = client.customers.list_customers
+  ```
 
 See the SDK documentation for the list of methods for each API class.
 
@@ -224,6 +252,7 @@ result = client.customers.create_customer(request_body)
 ```
 
 If your call succeeds, you’ll see a response that looks like this:
+
 ```
 {'customer': {'created_at': '2019-06-28T21:23:05.126Z', 'creation_source': 'THIRD_PARTY', 'family_name': 'Earhardt', 'given_name': 'Amelia', 'id': 'CBASEDwl3El91nohQ2FLEk4aBfcgAQ', 'preferences': {'email_unsubscribed': False}, 'updated_at': '2019-06-28T21:23:05.126Z'}}
 ```
@@ -248,7 +277,7 @@ end
 
 ## Tests
 
-First, clone the gem locally and `cd` into the directory.
+First, clone the repo locally and `cd` into the directory.
 
 ```sh
 git clone https://github.com/square/square-ruby-sdk.git
@@ -280,38 +309,44 @@ The Square Platform is built on the [Square API]. Square has a number of other S
 
 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
 [Developer Dashboard]: https://developer.squareup.com/apps
 [Square API]: https://squareup.com/developers
 [sign up for a developer account]: https://squareup.com/signup?v=developers
 [Client]: doc/client.md
-[Devices]: doc/devices.md
-[Disputes]: doc/disputes.md
-[Terminal]: doc/terminal.md
-[Team]: doc/team.md
-[Cash Drawers]: doc/cash-drawers.md
-[Customer Groups]: doc/customer-groups.md
-[Customer Segments]: doc/customer-segments.md
-[Bank Accounts]: doc/bank-accounts
-[Payments]: doc/payments.md
-[Checkout]: doc/checkout.md
-[Catalog]: doc/catalog.md
-[Customers]: doc/customers.md
-[Employees]: doc/employees.md
-[Inventory]: doc/inventory.md
-[Labor]: doc/labor.md
-[Loyalty]: doc/loyalty.md
-[Locations]: doc/locations.md
-[Merchants]: doc/merchants.md
-[Orders]: doc/orders.md
-[Invoices]: doc/invoices.md
-[Apple Pay]: doc/apple-pay.md
-[Refunds]: doc/refunds.md
-[Mobile Authorization]: doc/mobile-authorization.md
-[O Auth]: doc/o-auth.md
-[V1 Locations]: doc/v1-locations.md
-[V1 Employees]: doc/v1-employees.md
-[V1 Transactions]: doc/v1-transactions.md
-[V1 Items]: doc/v1-items.md
-[Transactions]: doc/transactions.md
-[Subscriptions]: doc/subscriptions.md
+[Devices]: doc/api/devices.md
+[Disputes]: doc/api/disputes.md
+[Terminal]: doc/api/terminal.md
+[Team]: doc/api/team.md
+[Cash Drawers]: doc/api/cash-drawers.md
+[Customer Groups]: doc/api/customer-groups.md
+[Customer Segments]: doc/api/customer-segments.md
+[Bank Accounts]: doc/api/bank-accounts.md
+[Payments]: doc/api/payments.md
+[Checkout]: doc/api/checkout.md
+[Catalog]: doc/api/catalog.md
+[Customers]: doc/api/customers.md
+[Employees]: doc/api/employees.md
+[Inventory]: doc/api/inventory.md
+[Labor]: doc/api/labor.md
+[Loyalty]: doc/api/loyalty.md
+[Bookings]: doc/api/bookings.md
+[Locations]: doc/api/locations.md
+[Merchants]: doc/api/merchants.md
+[Orders]: doc/api/orders.md
+[Invoices]: doc/api/invoices.md
+[Apple Pay]: doc/api/apple-pay.md
+[Refunds]: doc/api/refunds.md
+[Subscriptions]: doc/api/subscriptions.md
+[Mobile Authorization]: doc/api/mobile-authorization.md
+[OAuth]: doc/api/o-auth.md
+[V1 Employees]: doc/api/v1-employees.md
+[V1 Transactions]: doc/api/v1-transactions.md
+[V1 Items]: doc/api/v1-items.md
+[Transactions]: doc/api/transactions.md
+[Sites]: doc/api/sites.md
+[Snippets]: doc/api/snippets.md
+[Cards]: doc/api/cards.md
+[Gift Cards]: doc/api/gift-cards.md
+[Gift Card Activities]: doc/api/gift-card-activities.md

data/lib/square/api/apple_pay_api.rb

@@ -5,17 +5,18 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Activates a domain for use with Web Apple Pay and Square. A validation
-    # will be performed on this domain by Apple to ensure is it properly set up
+    # Activates a domain for use with Apple Pay on the Web and Square. A
+    # validation
+    # is performed on this domain by Apple to ensure that it is properly set up
     # as
     # an Apple Pay enabled domain.
     # This endpoint provides an easy way for platform developers to bulk
     # 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
-    # [Square Payment Form
-    # Walkthrough](https://developer.squareup.com/docs/docs/payment-form/payment
-    # -form-walkthrough).
+    # Apple Pay on the Web with Square for merchants using their platform.
+    # To learn more about Web Apple Pay, see
+    # [Add the Apple Pay on the Web
+    # Button](https://developer.squareup.com/docs/payment-form/add-digital-walle
+    # ts/apple-pay).
     # @param [RegisterDomainRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -29,7 +30,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -44,7 +45,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
   end
 end

data/lib/square/api/bank_accounts_api.rb

@@ -5,16 +5,13 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Returns a list of [BankAccount](#type-bankaccount) objects linked to a
-    # Square account.
-    # For more information, see
-    # [Bank Accounts
-    # API](https://developer.squareup.com/docs/docs/bank-accounts-api).
+    # Returns a list of [BankAccount]($m/BankAccount) objects linked to a Square
+    # account.
     # @param [String] cursor Optional parameter: The pagination cursor returned
     # by a previous call to this endpoint. Use it in the next `ListBankAccounts`
     # request to retrieve the next set  of results.  See the
-    # [Pagination](https://developer.squareup.com/docs/docs/working-with-apis/pa
-    # gination) guide for more information.
+    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
+    # ion) guide for more information.
     # @param [Integer] limit Optional parameter: Upper limit on the number of
     # bank accounts to return in the response.  Currently, 1000 is the largest
     # supported limit. You can specify a limit  of up to 1000 bank accounts.
@@ -53,20 +50,18 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
-    # Returns details of a [BankAccount](#type-bankaccount) identified by V1
-    # bank account ID.
-    # For more information, see
-    # [Retrieve a bank account by using an ID issued by V1 Bank Accounts
-    # API](https://developer.squareup.com/docs/docs/bank-accounts-api#retrieve-a
-    # -bank-account-by-using-an-id-issued-by-the-v1-bank-accounts-api).
+    # Returns details of a [BankAccount]($m/BankAccount) identified by V1 bank
+    # account ID.
     # @param [String] v1_bank_account_id Required parameter: Connect V1 ID of
     # the desired `BankAccount`. For more information, see  [Retrieve a bank
     # account by using an ID issued by V1 Bank Accounts
-    # API](https://developer.squareup.com/docs/docs/bank-accounts-api#retrieve-a
-    # -bank-account-by-using-an-id-issued-by-v1-bank-accounts-api).
+    # API](https://developer.squareup.com/docs/bank-accounts-api#retrieve-a-bank
+    # -account-by-using-an-id-issued-by-v1-bank-accounts-api).
     # @return [GetBankAccountByV1IdResponse Hash] response from the API call
     def get_bank_account_by_v1_id(v1_bank_account_id:)
       # Prepare query url.
@@ -74,7 +69,7 @@ module Square
       _query_builder << '/v2/bank-accounts/by-v1-id/{v1_bank_account_id}'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'v1_bank_account_id' => v1_bank_account_id
+        'v1_bank_account_id' => { 'value' => v1_bank_account_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -94,13 +89,13 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
-    # Returns details of a [BankAccount](#type-bankaccount)
-    # linked to a Square account. For more information, see
-    # [Bank Accounts
-    # API](https://developer.squareup.com/docs/docs/bank-accounts-api).
+    # Returns details of a [BankAccount]($m/BankAccount)
+    # linked to a Square account.
     # @param [String] bank_account_id Required parameter: Square-issued ID of
     # the desired `BankAccount`.
     # @return [GetBankAccountResponse Hash] response from the API call
@@ -110,7 +105,7 @@ module Square
       _query_builder << '/v2/bank-accounts/{bank_account_id}'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'bank_account_id' => bank_account_id
+        'bank_account_id' => { 'value' => bank_account_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -130,7 +125,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
   end
 end

data/lib/square/api/base_api.rb

@@ -1,3 +1,4 @@
+require 'erb'
 module Square
   # BaseApi.
   class BaseApi
@@ -8,36 +9,46 @@ module Square
       @http_call_back = http_call_back
 
       @global_headers = {
-        'user-agent' => 'Square-Ruby-SDK/6.3.0.20200826',
+        'user-agent' => get_user_agent,
         'Square-Version' => config.square_version
       }
     end
 
     def validate_parameters(args)
       args.each do |_name, value|
-        if value.nil?
-          raise ArgumentError, "Required parameter #{_name} cannot be nil."
-        end
+        raise ArgumentError, "Required parameter #{_name} cannot be nil." if value.nil?
       end
     end
 
     def execute_request(request, binary: false)
-      @http_call_back.on_before_request(request) if @http_call_back
+      @http_call_back&.on_before_request(request)
 
       APIHelper.clean_hash(request.headers)
       request.headers.merge!(@global_headers)
-      unless config.additional_headers.nil?
-        request.headers.merge!(config.additional_headers)
-      end
+      request.headers.merge!(config.additional_headers) unless config.additional_headers.nil?
 
       response = if binary
                    config.http_client.execute_as_binary(request)
                  else
                    config.http_client.execute_as_string(request)
                  end
-      @http_call_back.on_after_response(response) if @http_call_back
+      @http_call_back&.on_after_response(response)
 
       response
     end
+
+    def get_user_agent
+      user_agent = 'Square-Ruby-SDK/17.1.0.20220120 ({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