square.rb 8.0.0.20201216 → 26.1.0.20230119

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50abb148c3dd6d03e86147fc8f95f3f58eeafeabb22d81c65a5c58b87b0b1060
-  data.tar.gz: 26371d6cdfa25de275bfef471b8145e43eaeccc7dc661d0abac57f9b643645aa
+  metadata.gz: ac8d00e1d947c816019d207e36e19a85ef2f8d66e3b5c4295e3e19f6cfcd5af6
+  data.tar.gz: ba91ef39e6e11e16af9a859abe126cd8f25e0d0751a65a101e63dfb0bbbf4718
 SHA512:
-  metadata.gz: a404bd6129da3f1ed2cdeaa8080d05c4ec75fe2ae93913c9c6e01de706f8dfc8487fb8696d431072a87511d9036fa6fa7cc797e6765f326c382d45ba0658d719
-  data.tar.gz: 8000f93f083e58f8c6c820520f535cdf5015f1184ac0bd2febfb3a4448e0850a9ea168e997f7a42f54435255a3beba8a2c74615fd2a155e05fe8cb8bcd7c1652
+  metadata.gz: 23f2218d4d9757a648c69c5d6d21eb764f121695c6a11ac80607f24bb86301745f410b1103937ad49a157f150784ea1d396ea57393d0743c0742848b8beba0fa
+  data.tar.gz: fc4af83a8b04a151839c45f6f0c632f2b6b5b65abfcde66027d89714ac8566770b5f70407d021337d7cae3daa67957b06ca373eaf4b3b6791aef13ae1029ca87

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2020 Square, Inc.
+Copyright 2023 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,30 +2,66 @@
 
 # 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.
+Use this library to integrate Square payments into your app and grow your business with Square APIs including Catalog, Customers, Employees, Inventory, Labor, Locations, and Orders.
+
+* [Requirements](#requirements)
+* [Installation](#installation)
+* [Quickstart](#quickstart)
+* [Usage](#usage)
+* [Tests](#tests)
+* [SDK Reference](#sdk-reference)
+* [Deprecated APIs](#deprecated-apis)
+
+## Requirements
+
+Use of the Square Ruby SDK requires:
+
+* Ruby 2.6 through 3.1
 
 ## Installation
 
-Install the gem from the command line:
+For more information, see [Set Up Your Square SDK for a Ruby Project](https://developer.squareup.com/docs/sdks/ruby/setup-project).
+
+## Quickstart
+
+For more information, see [Square Ruby SDK Quickstart](https://developer.squareup.com/docs/sdks/ruby/quick-start).
+
+## Usage
+For more information, see [Using the Square Ruby SDK](https://developer.squareup.com/docs/sdks/ruby/using-ruby-sdk).
+
+## Tests
+
+First, clone the repo locally and `cd` into the directory.
+
+```sh
+git clone https://github.com/square/square-ruby-sdk.git
+cd square-ruby-sdk
+```
+
+Next, make sure Bundler is installed and install the development dependencies.
 
-```ruby
-gem install square.rb
+```sh
+gem install bundler
+bundle
 ```
 
-Or add the gem to your Gemfile and `bundle`:
+Before running the tests, find a sandbox token in your [Developer Dashboard] and set a `SQUARE_SANDBOX_TOKEN` environment variable.
 
-```ruby
-gem 'square.rb'
+```sh
+export SQUARE_SANDBOX_TOKEN="YOUR SANDBOX TOKEN HERE"
 ```
 
-### API Client
-* [Client]
+And run the tests.
 
-## API documentation
+```sh
+rake
+```
+
+## SDK Reference
 
 ### Payments
 * [Payments]
@@ -33,6 +69,10 @@ gem 'square.rb'
 * [Disputes]
 * [Checkout]
 * [Apple Pay]
+* [Cards]
+* [Payouts]
+
+### Terminal
 * [Terminal]
 
 ### Orders
@@ -50,12 +90,17 @@ gem 'square.rb'
 
 ### Customers
 * [Customers]
+* [Customer Custom Attributes]
 * [Customer Groups]
 * [Customer Segments]
 
 ### Loyalty
 * [Loyalty]
 
+### Gift Cards
+* [Gift Cards]
+* [Gift Card Activities]
+
 ### Bookings
 * [Bookings]
 
@@ -63,225 +108,33 @@ gem 'square.rb'
 * [Merchants]
 * [Locations]
 * [Devices]
+* [Cash Drawers]
+* [Vendors]
 
 ### Team
 * [Team]
-* [Employees]
 * [Labor]
-* [Cash Drawers]
 
 ### Financials
 * [Bank Accounts]
 
-### Authorization APIs
-* [Mobile Authorization]
-* [O Auth]
-
-### Deprecated APIs
-* [V1 Employees]
-* [V1 Transactions]
-* [V1 Items]
-* [Transactions]
-
-## Usage
-
-First time using Square? Here’s how to get started:
-
-1. **Create a Square account.** If you don’t have one already, [sign up for a developer account].
-1. **Create an application.** Go to your [Developer Dashboard] and create your first application. All you need to do is give it a name. When you’re doing this for your production application, enter the name as you would want a customer to see it.
-1. **Make your first API call.** Almost all Square API calls require a location ID. You’ll make your first call to #list_locations, which happens to be one of the API calls that don’t require a location ID. For more information about locations, see the [Locations] API documentation.
-
-Now let’s call your first Square API. Open your favorite text editor, create a new file called `locations.rb`, and copy the following code into that file:
-
-```ruby
-require 'square'
- 
-# Create an instance of the API Client and initialize it with the credentials 
-# for the Square account whose assets you want to manage.
-
-client = Square::Client.new(
-    access_token: 'YOUR SANDBOX ACCESS TOKEN HERE',
-    environment: 'sandbox'
-)
-
-# Call list_locations method to get all locations in this Square account
-result = client.locations.list_locations
-
-# Call the #success? method to see if the call succeeded
-if result.success?
-	# The #data Struct contains a list of locations
-  locations = result.data.locations
-
-	# Iterate over the list
-  locations.each do |location|
-    # Each location is represented as a Hash
-    location.each do |key, value|
-      puts "#{key}: #{value}"
-    end
-  end
-else
-  # Handle the case that the result is an error.
-  warn 'Error calling LocationsApi.listlocations ...'
-
-  # The #errors method returns an Array of error Hashes
-  result.errors.each do |key, value|
-    warn "#{key}: #{value}"
-  end
-end
-```
-
-Next, get an access token and reference it in your code. Go back to your application in the Developer Dashboard, in the Sandbox section click Show in the Sandbox Access Token box, copy that access token, and replace `'YOUR SANDBOX ACCESS TOKEN HERE'` with that token.
-
-**Important** When you eventually switch from trying things out on sandbox to actually working with your real production resources, you should not embed the access token in your code. Make sure you store and access your production access tokens securely.
-
-Now save `locations.rb` and run it:
-
-```sh
-ruby locations.rb
-```
-
-If your call is successful, you’ll get a response that looks like this:
-
-```
-address : {'address_line_1': '1455 Market Street', 'administrative_district_level_1': 'CA', 'country': 'US', 'locality': 'San Francisco', 'postal_code': '94103'}
-# ...
-```
-
-Yay! You successfully made your first call. If you didn’t, you would see an error message that looks something like this:
-
-```
-Error calling LocationsApi.listlocations
-category : AUTHENTICATION_ERROR
-code : UNAUTHORIZED
-detail : This request could not be authorized.
-```
-
-This error was returned when an invalid token was used to call the API.
-
-After you’ve tried out the Square APIs and tested your application using sandbox, you will want to switch to your production credentials so that you can manage real Square resources. Don't forget to switch your access token from sandbox to production for real data.
-
-## SDK patterns
-If you know a few patterns, you’ll be able to call any API in the SDK. Here are some important ones:
-
-### Get an access token
-
-To use the Square API to manage the resources (such as payments, orders, customers, etc.) of a Square account, you need to create an application (or use an existing one) in the Developer Dashboard and get an access token.
-
-When you call a Square API, you call it using an access key. An access key has specific permissions to resources in a specific Square account that can be accessed by a specific application in a specific developer account.
-Use an access token that is appropriate for your use case. There are two options:
+### Online
+* [Sites]
+* [Snippets]
 
-- To manage the resources for your own Square account, use the Personal Access Token for the application created in your Square account.
-- To manage resources for other Square accounts, use OAuth to ask owners of the accounts you want to manage so that you can work on their behalf. When you implement OAuth, you ask the Square account holder for permission to manage resources in their account (you can define the specific resources to access) and get an OAuth access token and refresh token for their account.
-
-**Important** For both use cases, make sure you store and access the tokens securely.
-
-### Import and Instantiate the Client Class
-
-To use the Square API, you import the Client class, instantiate a Client object, and initialize it with the appropriate access token. Here’s how:
-
-- Instantiate a `Square::Client` object with the access token for the Square account whose resources you want to manage. To access sandbox resources, initialize the `Square::Client` with environment set to sandbox:
-
-```ruby
-client = Square::Client.new(
-    access_token: 'SANDBOX ACCESS TOKEN HERE',
-    environment: 'sandbox'
-)
-```
-
-- To access production resources, set environment to production:
-
-```ruby
-client = Square::Client.new(
-    access_token: 'ACCESS TOKEN HERE',
-    environment: 'production'
-)
-```
- 
-### Get an Instance of an API object and call its methods
-
-Each API is implemented as a class. The Client object instantiates every API class and exposes them as properties so you can easily start using any Square API. You work with an API by calling methods on an instance of an API class. Here’s how:
-
-- Work with an API by calling the methods on the API object. For example, you would call list_customers to get a list of all customers in the Square account:
-
-```ruby
-result = client.customers.list_customers
-```
-
-See the SDK documentation for the list of methods for each API class.
-
-Pass complex parameters (such as create, update, search, etc.) as a Hash. For example, you would pass a Hash containing the values used to create a new customer using create_customer:
-
-```ruby
-# Create a unique key for this creation operation so you don't accidentally
-# create the customer multiple times if you need to retry this operation.
-require 'securerandom'
-
-idempotency_key = SecureRandom.uuid
-
-# To create a customer, you'll need to specify at least a few required fields.
-request_body = {idempotency_key: idempotency_key, given_name: 'Amelia', family_name: 'Earhardt'}
-
-# Call create_customer method to create a new customer in this Square account
-result = client.customers.create_customer(request_body)
-```
-
-If your call succeeds, you’ll see a response that looks like this:
-```
-{'customer': {'created_at': '2019-06-28T21:23:05.126Z', 'creation_source': 'THIRD_PARTY', 'family_name': 'Earhardt', 'given_name': 'Amelia', 'id': 'CBASEDwl3El91nohQ2FLEk4aBfcgAQ', 'preferences': {'email_unsubscribed': False}, 'updated_at': '2019-06-28T21:23:05.126Z'}}
-```
-
-- Use idempotency for create, update, or other calls that you want to avoid calling twice. To make an idempotent API call, you add the idempotency_key with a unique value in the Hash for the API call’s request.
-- Specify a location ID for APIs such as Transactions, Orders, and Checkout that deal with payments. When a payment or order is created in Square, it is always associated with a location.
-
-### Handle the response
-
-API calls return a response object that contains properties that describe both the request (headers and request) and the response (status_code, reason_phrase, text, errors, body, and cursor). The response also has #success? and #error? helper methods so you can easily determine the success or failure of a call:
-
-```ruby
-if result.success?
-  p result.data
-elsif result.error?
-  warn result.errors.inspect
-end
-```
-
-- Read the response payload. The response payload is returned as a Struct from the #data method. For retrieve calls, a Struct containing a single item is returned with a key name that is the name of the object (for example, customer). For list calls, a Struct containing a Array of objects is returned with a key name that is the plural of the object name (for example, customers).
-- Make sure you get all items returned in a list call by checking the cursor value returned in the API response. When you call a list API the first time, set the cursor to an empty String or omit it from the API request. If the API response contains a cursor with a value, you call the API again to get the next page of items and continue to call that API again until the cursor is an empty String.
-
-## Tests
-
-First, clone the gem locally and `cd` into the directory.
-
-```sh
-git clone https://github.com/square/square-ruby-sdk.git
-cd square-ruby-sdk
-```
-
-Next, make sure Bundler is installed and install the development dependencies.
-
-```sh
-gem install bundler
-bundle
-```
-
-Before running the tests, find a sandbox token in your [Developer Dashboard] and set a `SQUARE_SANDBOX_TOKEN` environment variable.
-
-```sh
-export SQUARE_SANDBOX_TOKEN="YOUR SANDBOX TOKEN HERE"
-```
-
-And run the tests.
+### Authorization
+* [Mobile Authorization]
+* [OAuth]
 
-```sh
-rake
-```
+## Deprecated APIs
 
-## Learn more
+The following Square APIs are [deprecated](https://developer.squareup.com/docs/build-basics/api-lifecycle):
 
-The Square Platform is built on the [Square API]. Square has a number of other SDKs that enable you to securely handle credit card information on both mobile and web so that you can process payments via the Square API. 
+* [Employees] - replaced by the [Team] API. For more information, see [Migrate from the Employees API](https://developer.squareup.com/docs/team/migrate-from-v2-employees).
 
-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).
+* [Transactions] - replaced by the [Orders] and [Payments] APIs.  For more information, see [Migrate from the Transactions API](https://developer.squareup.com/docs/payments-api/migrate-from-transactions-api).
 
+  
 [//]: # "Link anchor definitions"
 [Square Logo]: https://docs.connect.squareup.com/images/github/github-square-logo.svg
 [Developer Dashboard]: https://developer.squareup.com/apps
@@ -293,6 +146,7 @@ You can also use the Square API to create applications or services that work wit
 [Terminal]: doc/api/terminal.md
 [Team]: doc/api/team.md
 [Cash Drawers]: doc/api/cash-drawers.md
+[Vendors]: doc/api/vendors.md
 [Customer Groups]: doc/api/customer-groups.md
 [Customer Segments]: doc/api/customer-segments.md
 [Bank Accounts]: doc/api/bank-accounts.md
@@ -300,7 +154,7 @@ You can also use the Square API to create applications or services that work wit
 [Checkout]: doc/api/checkout.md
 [Catalog]: doc/api/catalog.md
 [Customers]: doc/api/customers.md
-[Employees]: doc/api/employees.md
+[Customer Custom Attributes]: doc/api/customer-custom-attributes.md
 [Inventory]: doc/api/inventory.md
 [Labor]: doc/api/labor.md
 [Loyalty]: doc/api/loyalty.md
@@ -313,8 +167,12 @@ You can also use the Square API to create applications or services that work wit
 [Refunds]: doc/api/refunds.md
 [Subscriptions]: doc/api/subscriptions.md
 [Mobile Authorization]: doc/api/mobile-authorization.md
-[O Auth]: 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
+[OAuth]: doc/api/o-auth.md
+[Sites]: doc/api/sites.md
+[Snippets]: doc/api/snippets.md
+[Cards]: doc/api/cards.md
+[Payouts]: doc/api/payouts.md
+[Gift Cards]: doc/api/gift-cards.md
+[Gift Card Activities]: doc/api/gift-card-activities.md
+[Employees]: doc/api/employees.md
 [Transactions]: doc/api/transactions.md

data/lib/square/api/apple_pay_api.rb

@@ -5,17 +5,24 @@ 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/payment-form/payment-form
-    # -walkthrough).
+    # Apple Pay on the Web with Square for merchants using their platform.
+    # Note: The SqPaymentForm library is deprecated as of May 13, 2021, and will
+    # only receive critical security updates until it is retired on October 31,
+    # 2022.
+    # You must migrate your payment form code to the Web Payments SDK to
+    # continue using your domain for Apple Pay. For more information on
+    # migrating to the Web Payments SDK, see [Migrate to the Web Payments
+    # SDK](https://developer.squareup.com/docs/web-payments/migrate).
+    # To learn more about the Web Payments SDK and how to add Apple Pay, see
+    # [Take an Apple Pay
+    # Payment](https://developer.squareup.com/docs/web-payments/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 +36,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

data/lib/square/api/bank_accounts_api.rb

@@ -5,8 +5,8 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Returns a list of [BankAccount](#type-bankaccount) objects linked to a
-    # Square account.
+    # 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
@@ -55,8 +55,8 @@ module Square
       )
     end
 
-    # Returns details of a [BankAccount](#type-bankaccount) identified by V1
-    # bank account ID.
+    # 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
@@ -94,7 +94,7 @@ module Square
       )
     end
 
-    # Returns details of a [BankAccount](#type-bankaccount)
+    # 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`.

data/lib/square/api/base_api.rb

@@ -1,3 +1,4 @@
+require 'erb'
 module Square
   # BaseApi.
   class BaseApi
@@ -8,36 +9,53 @@ module Square
       @http_call_back = http_call_back
 
       @global_headers = {
-        'user-agent' => 'Square-Ruby-SDK/8.0.0.20201216',
+        '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 validate_parameters_types(args)
+      args.each do |_name, type|
+        key, val = type.first
+        APIHelper.validate_types(key, val) unless key.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/26.1.0.20230119 ({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