square.rb 44.0.0.20250820 → 44.0.1.20250820

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08e62d17f3f59b0448164943a0ab9e7d38dbb6b36d52d0a717c419296b7259d7'
-  data.tar.gz: 520ef4918000692ba8d62dea3dbe8125b62f246780cbb803134dddbddcec0b4a
+  metadata.gz: e5b7ba53660ef4f45bce2164d8fb018797c280503fa6c59b94f8a658c76eb912
+  data.tar.gz: 5f02ad617c72d33f32e16eb13adf4165204d1b8348b46ed91e29d7bb7616ad88
 SHA512:
-  metadata.gz: 6f500fb27612c421768e6ac83684c8ed8c73e04f3d5a0a969c50e68935d0487a1d55cd6f9a08e3d5424efcfe0248b36ded710c94a3819615553e8e7eb457d255
-  data.tar.gz: 1b28fcf5ec2e26bf6eea079a0f028b39782296168366baf3ed335dcbcbdf7ba6165cefb2580ee786d32f535fe75424d4e9e4511438a5b76d4d1b5cea43aa328b
+  metadata.gz: 35e1648199a54c20bd6d800f34f1e9988d46032d65e9f246c26b7376dda89223501295351d4ae9e64c014a13945cd518f7cdcff74e6fb7c0088513108ad65c1e
+  data.tar.gz: 8bb6b4fd497f3e7e0c30851a59ccf03d58ae3383f3db9f6faee82b92650ec6eaaa2e2fccaf87d4b3d3ba4887a0424fef2752ce0785ce83ff7c8c0a30db4f63b6

data/README.md

@@ -28,6 +28,28 @@ gem 'square.rb', '~> 44.0.0'
 
 For more information, see [Using the Square Ruby SDK](https://developer.squareup.com/docs/sdks/ruby/using-ruby-sdk).
 
+```ruby
+require "square"
+
+square = Square::Client.new(
+  token: 'YOUR_API_KEY'
+)
+
+image_file = Square::FileParam.from_filepath(
+  filepath: fixture_path("small.png"),
+  content_type: "image/png"
+)
+
+response = square.invoices.create_invoice_attachment(
+  invoice_id: "inv:0-ChA4-3sU9GPd-uOC3HgvFjMWEL4N",
+  request: {
+    idempotency_key: SecureRandom.uuid,
+    description: "A test invoice attachment"
+  },
+  image_file: image_file
+)
+```
+
 ## 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.
@@ -83,6 +105,28 @@ client = SquareLegacy::Client.new(
 ```
 4. Gradually migrate over to the new SDK by importing it from the `'square'` import.
 
+## Environments
+
+This SDK allows you to configure different environments or custom URLs for API requests. You can either use the predefined environments or specify your own custom URL.
+
+### Environments
+```ruby
+require "square"
+
+client = Square::Client.new(
+    base_url: Square::Environment::PRODUCTION
+)
+```
+
+### Custom URL
+```ruby
+require "square"
+
+client = Square::Client.new(
+    base_url: "https://custom-staging.com"
+)
+```
+
 ## Request And Response Types
 
 The SDK exports all request and response types as Ruby classes. Simply require them with the
@@ -97,20 +141,29 @@ request = Square::CreateMobileAuthorizationCodeRequest.new(
 )
 ```
 
-## Exception Handling
+## Errors
 
-When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
-will be raised.
+Failed API calls will raise errors that can be rescued from granularly.
 
 ```ruby
-require 'square'
+require "square"
+
+client = Square::Client.new(
+  base_url: Square::Environment::PRODUCTION
+)
 
 begin
-  response = client.payments.create(...)
-rescue Square::ApiError => e
-  puts "Status Code: #{e.status_code}"
-  puts "Message: #{e.message}"
-  puts "Body: #{e.body}"
+    result = client.payments.create
+rescue Square::Errors::TimeoutError
+    puts "API didn't respond before our timeout elapsed"
+rescue Square::Errors::ServiceUnavailableError
+    puts "API returned status 503, is probably overloaded, try again later"
+rescue Square::Errors::ServerError
+    puts "API returned some other 5xx status, this is probably a bug"
+rescue Square::Errors::ResponseError => e
+    puts "API returned an unexpected status other than 5xx: #{e.code} {e.message}"
+rescue Square::Errors::ApiError => e
+    puts "Some other error occurred when calling the API: {e.message}"
 end
 ```
 

data/lib/square/apple_pay/client.rb

@@ -26,17 +26,23 @@ module Square
       # @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,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           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)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::RegisterDomainResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
     end
   end

data/lib/square/bank_accounts/client.rb

@@ -12,22 +12,31 @@ module Square
       #
       # @return [Square::Types::ListBankAccountsResponse]
       def list(request_options: {}, **params)
-        _query_param_names = %w[cursor limit location_id]
+        _query_param_names = [
+          %w[cursor limit location_id],
+          %i[cursor limit location_id]
+        ].flatten
         _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,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           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)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::ListBankAccountsResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Returns details of a [BankAccount](entity:BankAccount) identified by V1 bank account ID.
@@ -35,16 +44,22 @@ module Square
       # @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,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           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)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::GetBankAccountByV1IdResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Returns details of a [BankAccount](entity:BankAccount)
@@ -53,16 +68,22 @@ module Square
       # @return [Square::Types::GetBankAccountResponse]
       def get(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           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)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::GetBankAccountResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
     end
   end

data/lib/square/bookings/client.rb

@@ -15,23 +15,31 @@ module Square
       #
       # @return [Square::Types::ListBookingsResponse]
       def list(request_options: {}, **params)
-        _query_param_names = %w[limit cursor customer_id team_member_id location_id start_at_min
-                                start_at_max]
+        _query_param_names = [
+          %w[limit cursor customer_id team_member_id location_id start_at_min start_at_max],
+          %i[limit cursor customer_id team_member_id location_id start_at_min start_at_max]
+        ].flatten
         _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,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "GET",
           path: "v2/bookings",
           query: _query
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::ListBookingsResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::ListBookingsResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Creates a booking.
@@ -52,17 +60,23 @@ module Square
       # @return [Square::Types::CreateBookingResponse]
       def create(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "POST",
           path: "v2/bookings",
           body: params
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::CreateBookingResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::CreateBookingResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Searches for availabilities for booking.
@@ -73,17 +87,23 @@ module Square
       # @return [Square::Types::SearchAvailabilityResponse]
       def search_availability(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "POST",
           path: "v2/bookings/availability/search",
           body: params
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::SearchAvailabilityResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::SearchAvailabilityResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Bulk-Retrieves a list of bookings by booking IDs.
@@ -94,17 +114,23 @@ module Square
       # @return [Square::Types::BulkRetrieveBookingsResponse]
       def bulk_retrieve_bookings(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "POST",
           path: "v2/bookings/bulk-retrieve",
           body: params
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::BulkRetrieveBookingsResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::BulkRetrieveBookingsResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Retrieves a seller's booking profile.
@@ -112,16 +138,22 @@ module Square
       # @return [Square::Types::GetBusinessBookingProfileResponse]
       def get_business_profile(request_options: {}, **_params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "GET",
           path: "v2/bookings/business-booking-profile"
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::GetBusinessBookingProfileResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::GetBusinessBookingProfileResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Retrieves a seller's location booking profile.
@@ -129,16 +161,22 @@ module Square
       # @return [Square::Types::RetrieveLocationBookingProfileResponse]
       def retrieve_location_booking_profile(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "GET",
           path: "v2/bookings/location-booking-profiles/#{params[:location_id]}"
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::RetrieveLocationBookingProfileResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::RetrieveLocationBookingProfileResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Retrieves one or more team members' booking profiles.
@@ -146,17 +184,23 @@ module Square
       # @return [Square::Types::BulkRetrieveTeamMemberBookingProfilesResponse]
       def bulk_retrieve_team_member_booking_profiles(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "POST",
           path: "v2/bookings/team-member-booking-profiles/bulk-retrieve",
           body: params
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::BulkRetrieveTeamMemberBookingProfilesResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::BulkRetrieveTeamMemberBookingProfilesResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Retrieves a booking.
@@ -167,16 +211,22 @@ module Square
       # @return [Square::Types::GetBookingResponse]
       def get(request_options: {}, **params)
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "GET",
           path: "v2/bookings/#{params[:booking_id]}"
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::GetBookingResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::GetBookingResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Updates a booking.
@@ -192,17 +242,23 @@ module Square
         _path_param_names = ["booking_id"]
 
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "PUT",
           path: "v2/bookings/#{params[:booking_id]}",
           body: params.except(*_path_param_names)
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::UpdateBookingResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::UpdateBookingResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # Cancels an existing booking.
@@ -218,17 +274,23 @@ module Square
         _path_param_names = ["booking_id"]
 
         _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::SANDBOX,
+          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
           method: "POST",
           path: "v2/bookings/#{params[:booking_id]}/cancel",
           body: params.except(*_path_param_names)
         )
-        _response = @client.send(_request)
-        if _response.code >= "200" && _response.code < "300"
-          return Square::Types::CancelBookingResponse.load(_response.body)
+        begin
+          _response = @client.send(_request)
+        rescue Net::HTTPRequestTimeout
+          raise Square::Errors::TimeoutError
+        end
+        code = _response.code.to_i
+        if code.between?(200, 299)
+          Square::Types::CancelBookingResponse.load(_response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(_response.body, code: code)
         end
-
-        raise _response.body
       end
 
       # @return [Square::CustomAttributeDefinitions::Client]