square.rb 43.0.0.20250618 → 44.0.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 433e68ae77cf868e2f282dc01f60dba1e0f1fb411eed39b039f51ff886789c26
-  data.tar.gz: d1b18f16e5118406bec362303d25e5e3a7908172619b93973ea41e3f7b889fe2
+  metadata.gz: ceb59d3c6e7dacec682ddd6c1a982c27fdc0b931c85f058e73352c903e505fb2
+  data.tar.gz: 4b7dd19c83e735c80b601d0d979f3d39aa61e78d867607e7ac4a52d2878dd7e1
 SHA512:
-  metadata.gz: 66e9394620fa19a4e1f9787aa63d6ccbc6d77b43028d3271fe86853e0d487e116b7311f95f936056629cc071142c3466ea5fd0065fdfcbae535373997fbe4219
-  data.tar.gz: ace44f21ce02c5ab13c64c9109b67e9be2f0fd894cc2d373637d2b3153166fb304f224f22e118c12ead5dfc289e8dc83e0d6fcc49af2551188a39e9a4b03abac
+  metadata.gz: bb3b8ec7d65372cc6f36490bd1518ffd6da6e46d96aee440b387ecd6d48b3c9e5b4754d3bccbcc375f69c6221395c55dc921506fea37efb4dbc2456ac233fa80
+  data.tar.gz: 31ec2f0b38264a2d9ecb5c81e18777362409af54bad95d5dafc87beb49c15c843a3b9c41c358f5b9a8afb6d6bcb7e8d77d8689d6751dc95e517bc0443b9e6626

data/LICENSE

@@ -1,10 +1,21 @@
-Copyright 2024 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
-   https://www.apache.org/licenses/LICENSE-2.0
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+MIT License
+
+Copyright (c) 2025 Square.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,190 +1,209 @@
-![Square logo]
+# Square Ruby Library
 
-# 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)
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Fsquare%2Fsquare-ruby-sdk)
 [![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 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)
+The Square Ruby library provides convenient access to the Square API from Ruby.
 
 ## Requirements
 
 Use of the Square Ruby SDK requires:
 
-* Ruby 2.6 through 3.1
+* Ruby 3.2+
 
 ## Installation
 
-For more information, see [Set Up Your Square SDK for a Ruby Project](https://developer.squareup.com/docs/sdks/ruby/setup-project).
+The Square Ruby SDK version is managed through the gem version. To use a specific version:
 
-## Quickstart
+```bash
+gem install square.rb
+```
 
-For more information, see [Square Ruby SDK Quickstart](https://developer.squareup.com/docs/sdks/ruby/quick-start).
+Or in your Gemfile:
+```ruby
+gem 'square.rb', '~> 44.0.0'
+```
 
 ## Usage
+
 For more information, see [Using the Square Ruby SDK](https://developer.squareup.com/docs/sdks/ruby/using-ruby-sdk).
 
-## Tests
+## Legacy SDK
+
+While the new SDK has a lot of improvements, we at Square understand that it takes time to upgrade when there are breaking changes.
+To make the migration easier, the new SDK also exports the legacy SDK as `square_legacy`. Here's an example of how you can use the
+legacy SDK alongside the new SDK inside a single file:
+
+```ruby
+# Load both SDKs
+require 'square'
+require 'square_legacy'
+
+# Initialize new SDK client
+new_client = Square::Client.new(
+  access_token: 'YOUR_SQUARE_ACCESS_TOKEN'
+)
+
+# Initialize legacy SDK client
+legacy_client = SquareLegacy::Client.new(
+  bearer_auth_credentials: {
+    access_token: 'YOUR_SQUARE_ACCESS_TOKEN'
+  }
+)
+
+# Use new SDK for newer features
+locations = new_client.locations.get_locations.data.locations
+
+# Use legacy SDK for specific legacy functionality
+legacy_payment = legacy_client.payments_api.create_payment(
+  body: {
+    source_id: 'example_1234567890',
+    idempotency_key: SecureRandom.uuid,
+    amount_money: {
+      amount: 100,
+      currency: 'USD'
+    }
+  }
+)
+```
 
-First, clone the repo locally and `cd` into the directory.
+We recommend migrating to the new SDK using the following steps:
 
-```sh
-git clone https://github.com/square/square-ruby-sdk.git
-cd square-ruby-sdk
+1. Update your square.rb: `gem update square.rb`
+2. Search and replace all requires from `'square'` to `'square_legacy'`
+3. Update all client initializations from 
+```ruby 
+client = Square::Client.new(access_token: 'token')
 ```
+to 
+```ruby
+client = SquareLegacy::Client.new(
+  bearer_auth_credentials: { access_token: 'token' }
+)
+```
+4. Gradually migrate over to the new SDK by importing it from the `'square'` import.
+
+## Request And Response Types
+
+The SDK exports all request and response types as Ruby classes. Simply require them with the
+following namespace:
 
-Next, make sure Bundler is installed and install the development dependencies.
+```ruby
+require 'square'
 
-```sh
-gem install bundler
-bundle
+# Create a request object
+request = Square::CreateMobileAuthorizationCodeRequest.new(
+  location_id: 'YOUR_LOCATION_ID'
+)
 ```
 
-Before running the tests, find a sandbox token in your [Developer Dashboard] and set a `SQUARE_SANDBOX_TOKEN` environment variable.
+## Exception Handling
+
+When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
+will be raised.
+
+```ruby
+require 'square'
 
-```sh
-export SQUARE_SANDBOX_TOKEN="YOUR SANDBOX TOKEN HERE"
+begin
+  response = client.payments.create(...)
+rescue Square::ApiError => e
+  puts "Status Code: #{e.status_code}"
+  puts "Message: #{e.message}"
+  puts "Body: #{e.body}"
+end
 ```
 
-And run the tests.
+## Pagination
 
-```sh
-rake
+List endpoints are paginated. The SDK provides methods to handle pagination:
+
+```ruby
+require 'square'
+
+client = Square::Client.new(access_token: "YOUR_TOKEN")
+
+# Get all items using pagination
+response = client.bank_accounts.list
+all_bank_accounts = []
+
+while response.data.bank_accounts.any?
+  all_bank_accounts.concat(response.data.bank_accounts)
+  
+  # Check if there are more pages
+  if response.cursor
+    response = client.bank_accounts.list(cursor: response.cursor)
+  else
+    break
+  end
+end
+
+puts "Total bank accounts: #{all_bank_accounts.length}"
 ```
 
-## SDK Reference
+## Advanced
 
-### Payments
-* [Payments]
-* [Refunds]
-* [Disputes]
-* [Checkout]
-* [Apple Pay]
-* [Cards]
-* [Payouts]
+### Additional Headers
 
-### Terminal
-* [Terminal]
+If you would like to send additional headers as part of the request, use the `headers` request option.
 
-### Orders
-* [Orders]
-* [Order Custom Attributes]
+```ruby
+response = client.payments.create(..., {
+  headers: {
+    'X-Custom-Header' => 'custom value'
+  }
+})
+```
 
-### Subscriptions
-* [Subscriptions]
+### Receive Extra Properties
 
-### Invoices
-* [Invoices]
+Every response includes any extra properties in the JSON response that were not specified in the type.
+This can be useful for API features not present in the SDK yet.
 
-### Items
-* [Catalog]
-* [Inventory]
+You can receive and interact with the extra properties by accessing the raw response data:
 
-### Customers
-* [Customers]
-* [Customer Custom Attributes]
-* [Customer Groups]
-* [Customer Segments]
+```ruby
+response = client.locations.create(...)
 
-### Loyalty
-* [Loyalty]
+# Access the raw response data
+location_data = response.data.to_h
 
-### Gift Cards
-* [Gift Cards]
-* [Gift Card Activities]
+# Then access the extra property by its name
+undocumented_property = location_data['undocumentedProperty']
+```
 
-### Bookings
-* [Bookings]
-* [Booking Custom Attributes]
+### Retries
 
-### Business
-* [Merchants]
-* [Merchant Custom Attributes]
-* [Locations]
-* [Location Custom Attributes]
-* [Devices]
-* [Cash Drawers]
-* [Vendors]
+The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
+as the request is deemed retriable and the number of retry attempts has not grown larger than the configured
+retry limit (default: 2).
 
-### Team
-* [Team]
-* [Labor]
+A request is deemed retriable when any of the following HTTP status codes is returned:
 
-### Financials
-* [Bank Accounts]
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
 
-### Online
-* [Sites]
-* [Snippets]
+Use the `max_retries` request option to configure this behavior.
 
-### Authorization
-* [Mobile Authorization]
-* [OAuth]
+```ruby
+response = client.payments.create(..., {
+  max_retries: 0 # override max_retries at the request level
+})
+```
 
-### Webhook Subscriptions
-* [Webhook Subscriptions]
+### Timeouts
 
-## Deprecated APIs
+The SDK defaults to a 60 second timeout. Use the `timeout_in_seconds` option to configure this behavior.
 
-The following Square APIs are [deprecated](https://developer.squareup.com/docs/build-basics/api-lifecycle):
+```ruby
+response = client.payments.create(..., {
+  timeout_in_seconds: 30 # override timeout to 30s
+})
+```
 
-* [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).
+## Contributing
 
-* [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).
+While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!
 
-  
-[//]: # "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/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
-[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
-[Payments]: doc/api/payments.md
-[Checkout]: doc/api/checkout.md
-[Catalog]: doc/api/catalog.md
-[Customers]: doc/api/customers.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
-[Bookings]: doc/api/bookings.md
-[Booking Custom Attributes]: doc/api/booking-custom-attributes.md
-[Locations]: doc/api/locations.md
-[Location Custom Attributes]: doc/api/location-custom-attributes.md
-[Merchants]: doc/api/merchants.md
-[Merchant Custom Attributes]: doc/api/merchant-custom-attributes.md
-[Orders]: doc/api/orders.md
-[Order Custom Attributes]: doc/api/order-custom-attributes.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
-[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
-[Webhook Subscriptions]: doc/api/webhook-subscriptions.md
+On the other hand, contributions to the README are always very welcome!

data/lib/square/apple_pay/client.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Square
+  module ApplePay
+    class Client
+      # @return [Square::ApplePay::Client]
+      def initialize(client:)
+        @client = client
+      end
+
+      # 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
+      # Apple Pay on the Web with Square for merchants using their platform.
+      #
+      # Note: You will need to host a valid domain verification file on your domain to support Apple Pay.  The
+      # current version of this file is always available at https://app.squareup.com/digital-wallets/apple-pay/apple-developer-merchantid-domain-association,
+      # and should be hosted at `.well_known/apple-developer-merchantid-domain-association` on your
+      # domain.  This file is subject to change; we strongly recommend checking for updates regularly and avoiding
+      # long-lived caches that might not keep in sync with the correct file version.
+      #
+      # 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).
+      #
+      # @return [Square::Types::RegisterDomainResponse]
+      def register_domain(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "POST",
+          path: "v2/apple-pay/domains",
+          body: params
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::RegisterDomainResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+    end
+  end
+end

data/lib/square/apple_pay/types/register_domain_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Square
+  module ApplePay
+    module Types
+      class RegisterDomainRequest < Internal::Types::Model
+        field :domain_name, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/square/bank_accounts/client.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Square
+  module BankAccounts
+    class Client
+      # @return [Square::BankAccounts::Client]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Returns a list of [BankAccount](entity:BankAccount) objects linked to a Square account.
+      #
+      # @return [Square::Types::ListBankAccountsResponse]
+      def list(request_options: {}, **params)
+        _query_param_names = %w[cursor limit location_id]
+        _query = params.slice(*_query_param_names)
+        params.except(*_query_param_names)
+
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/bank-accounts",
+          query: _query
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::ListBankAccountsResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Returns details of a [BankAccount](entity:BankAccount) identified by V1 bank account ID.
+      #
+      # @return [Square::Types::GetBankAccountByV1IdResponse]
+      def get_by_v_1_id(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/bank-accounts/by-v1-id/#{params[:v1_bank_account_id]}"
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::GetBankAccountByV1IdResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+
+      # Returns details of a [BankAccount](entity:BankAccount)
+      # linked to a Square account.
+      #
+      # @return [Square::Types::GetBankAccountResponse]
+      def get(request_options: {}, **params)
+        _request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          method: "GET",
+          path: "v2/bank-accounts/#{params[:bank_account_id]}"
+        )
+        _response = @client.send(_request)
+        if _response.code >= "200" && _response.code < "300"
+          return Square::Types::GetBankAccountResponse.load(_response.body)
+        end
+
+        raise _response.body
+      end
+    end
+  end
+end

data/lib/square/bank_accounts/types/get_bank_accounts_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Square
+  module BankAccounts
+    module Types
+      class GetBankAccountsRequest < Internal::Types::Model
+        field :bank_account_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/square/bank_accounts/types/get_by_v_1_id_bank_accounts_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Square
+  module BankAccounts
+    module Types
+      class GetByV1IdBankAccountsRequest < Internal::Types::Model
+        field :v_1_bank_account_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/square/bank_accounts/types/list_bank_accounts_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Square
+  module BankAccounts
+    module Types
+      class ListBankAccountsRequest < Internal::Types::Model
+        field :cursor, -> { String }, optional: true, nullable: false
+        field :limit, -> { Integer }, optional: true, nullable: false
+        field :location_id, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end