square.rb 30.0.0.20230720 → 32.0.0.20230925

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 148935067852283c97b96532924b8990240a8471eb1fb004af84547db7a46e6f
-  data.tar.gz: f831947407ebced9aacc23b3db7cfae06b658899b21212c2548ca00a2acce842
+  metadata.gz: 6c7adca646aa24aa7a9afa7c6acd8d49e534a854fd134f6442f315015a500d77
+  data.tar.gz: 2ea27cf68b466c3987d01685efd65c4343c7b77c3297d5b4fc113fbe39b84cf0
 SHA512:
-  metadata.gz: d7045748e5af0118787c3658002f2c43a6e4db0e044e2707b58ae2d6690abd16ce01ae360889552611c43967261c93b33fd2bcd610c305b349b687e0d8c77605
-  data.tar.gz: 65360d7cd4eebb01bddba58ad85124a51d4a60ea21c8095235ce58182a2c58f26db1353374c4b914f3f1e96fd72e774efd0c0ba19c40bc231095998e1303d544
+  metadata.gz: 550f0b2966ced843d9300cb3bb2a9fc65d033297aa1e5f04fd3777da04703641580c6f361419477ae97c32e487bf825d4480612cf52d6a88e58056bd8fc7186b
+  data.tar.gz: c4f0bdfe70c66d1853a92d3eef3d314ecd2246519035039f57b44ce44e184d6fe03f8aebdb3f4a7274d337f14f2e7d8c95590a1edecefca81f7b6411b925219c

data/README.md

@@ -77,6 +77,7 @@ rake
 
 ### Orders
 * [Orders]
+* [Order Custom Attributes]
 
 ### Subscriptions
 * [Subscriptions]
@@ -103,10 +104,13 @@ rake
 
 ### Bookings
 * [Bookings]
+* [Booking Custom Attributes]
 
 ### Business
 * [Merchants]
+* [Merchant Custom Attributes]
 * [Locations]
+* [Location Custom Attributes]
 * [Devices]
 * [Cash Drawers]
 * [Vendors]
@@ -162,9 +166,13 @@ The following Square APIs are [deprecated](https://developer.squareup.com/docs/b
 [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

data/lib/square/api/base_api.rb

@@ -4,7 +4,7 @@ module Square
     attr_accessor :config, :http_call_back
 
     def self.user_agent
-      'Square-Ruby-SDK/30.0.0.20230720 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}'
+      'Square-Ruby-SDK/32.0.0.20230925 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}'
     end
 
     def self.user_agent_parameters

data/lib/square/api/bookings_api.rb

@@ -11,6 +11,9 @@ module Square
     # @param [String] cursor Optional parameter: The pagination cursor from the
     # preceding response to return the next page of the results. Do not set this
     # when retrieving the first page of the results.
+    # @param [String] customer_id Optional parameter: The
+    # [customer](entity:Customer) for whom to retrieve bookings. If this is not
+    # set, bookings for all customers are retrieved.
     # @param [String] team_member_id Optional parameter: The team member for
     # whom to retrieve bookings. If this is not set, bookings of all members are
     # retrieved.
@@ -26,6 +29,7 @@ module Square
     # @return [ListBookingsResponse Hash] response from the API call
     def list_bookings(limit: nil,
                       cursor: nil,
+                      customer_id: nil,
                       team_member_id: nil,
                       location_id: nil,
                       start_at_min: nil,
@@ -36,6 +40,7 @@ module Square
                                      'default')
                    .query_param(new_parameter(limit, key: 'limit'))
                    .query_param(new_parameter(cursor, key: 'cursor'))
+                   .query_param(new_parameter(customer_id, key: 'customer_id'))
                    .query_param(new_parameter(team_member_id, key: 'team_member_id'))
                    .query_param(new_parameter(location_id, key: 'location_id'))
                    .query_param(new_parameter(start_at_min, key: 'start_at_min'))
@@ -110,6 +115,32 @@ module Square
         .execute
     end
 
+    # Bulk-Retrieves a list of bookings by booking IDs.
+    # To call this endpoint with buyer-level permissions, set
+    # `APPOINTMENTS_READ` for the OAuth scope.
+    # To call this endpoint with seller-level permissions, set
+    # `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
+    # @param [BulkRetrieveBookingsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [BulkRetrieveBookingsResponse Hash] response from the API call
+    def bulk_retrieve_bookings(body:)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/v2/bookings/bulk-retrieve',
+                                     'default')
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('global')))
+        .response(new_response_handler
+                   .deserializer(APIHelper.method(:json_deserialize))
+                   .is_api_response(true)
+                   .convertor(ApiResponse.method(:create)))
+        .execute
+    end
+
     # Retrieves a seller's booking profile.
     # @return [RetrieveBusinessBookingProfileResponse Hash] response from the API call
     def retrieve_business_booking_profile
@@ -160,6 +191,28 @@ module Square
         .execute
     end
 
+    # Retrieves one or more team members' booking profiles.
+    # @param [BulkRetrieveTeamMemberBookingProfilesRequest] body Required
+    # parameter: An object containing the fields to POST for the request.  See
+    # the corresponding object definition for field details.
+    # @return [BulkRetrieveTeamMemberBookingProfilesResponse Hash] response from the API call
+    def bulk_retrieve_team_member_booking_profiles(body:)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/v2/bookings/team-member-booking-profiles/bulk-retrieve',
+                                     'default')
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('global')))
+        .response(new_response_handler
+                   .deserializer(APIHelper.method(:json_deserialize))
+                   .is_api_response(true)
+                   .convertor(ApiResponse.method(:create)))
+        .execute
+    end
+
     # Retrieves a team member's booking profile.
     # @param [String] team_member_id Required parameter: The ID of the team
     # member to retrieve.

data/lib/square/api/checkout_api.rb

@@ -8,9 +8,6 @@ module Square
     # For more information, see [Checkout API
     # highlights](https://developer.squareup.com/docs/checkout-api#checkout-api-
     # highlights).
-    # We recommend that you use the
-    # new [CreatePaymentLink](api-endpoint:Checkout-CreatePaymentLink)
-    # endpoint in place of this previously released endpoint.
     # @param [String] location_id Required parameter: The ID of the business
     # location to associate the checkout with.
     # @param [CreateCheckoutRequest] body Required parameter: An object

data/lib/square/api/devices_api.rb

@@ -1,6 +1,42 @@
 module Square
   # DevicesApi
   class DevicesApi < BaseApi
+    # List devices associated with the merchant. Currently, only Terminal API
+    # devices are supported.
+    # @param [String] cursor Optional parameter: A pagination cursor returned by
+    # a previous call to this endpoint. Provide this cursor to retrieve the next
+    # set of results for the original query. See
+    # [Pagination](https://developer.squareup.com/docs/build-basics/common-api-p
+    # atterns/pagination) for more information.
+    # @param [SortOrder] sort_order Optional parameter: The order in which
+    # results are listed. - `ASC` - Oldest to newest. - `DESC` - Newest to
+    # oldest (default).
+    # @param [Integer] limit Optional parameter: The number of results to return
+    # in a single page.
+    # @param [String] location_id Optional parameter: If present, only returns
+    # devices at the target location.
+    # @return [ListDevicesResponse Hash] response from the API call
+    def list_devices(cursor: nil,
+                     sort_order: nil,
+                     limit: nil,
+                     location_id: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/v2/devices',
+                                     'default')
+                   .query_param(new_parameter(cursor, key: 'cursor'))
+                   .query_param(new_parameter(sort_order, key: 'sort_order'))
+                   .query_param(new_parameter(limit, key: 'limit'))
+                   .query_param(new_parameter(location_id, key: 'location_id'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('global')))
+        .response(new_response_handler
+                   .deserializer(APIHelper.method(:json_deserialize))
+                   .is_api_response(true)
+                   .convertor(ApiResponse.method(:create)))
+        .execute
+    end
+
     # Lists all DeviceCodes associated with the merchant.
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint. Provide this to retrieve the next set of
@@ -81,5 +117,25 @@ module Square
                    .convertor(ApiResponse.method(:create)))
         .execute
     end
+
+    # Retrieves Device with the associated `device_id`.
+    # @param [String] device_id Required parameter: The unique ID for the
+    # desired `Device`.
+    # @return [GetDeviceResponse Hash] response from the API call
+    def get_device(device_id:)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/v2/devices/{device_id}',
+                                     'default')
+                   .template_param(new_parameter(device_id, key: 'device_id')
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('global')))
+        .response(new_response_handler
+                   .deserializer(APIHelper.method(:json_deserialize))
+                   .is_api_response(true)
+                   .convertor(ApiResponse.method(:create)))
+        .execute
+    end
   end
 end

data/lib/square/api/gift_cards_api.rb

@@ -13,7 +13,7 @@ module Square
     # cards of all states.
     # @param [Integer] limit Optional parameter: If a limit is provided, the
     # endpoint returns only the specified number of results per page. The
-    # maximum value is 50. The default value is 30. For more information, see
+    # maximum value is 200. The default value is 30. For more information, see
     # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
     # ion).
     # @param [String] cursor Optional parameter: A pagination cursor returned by

data/lib/square/api/o_auth_api.rb

@@ -56,10 +56,7 @@ module Square
     # Revokes an access token generated with the OAuth flow.
     # If an account has more than one OAuth access token for your application,
     # this
-    # endpoint revokes all of them, regardless of which token you specify. When
-    # an
-    # OAuth access token is revoked, all of the active subscriptions associated
-    # with that OAuth token are canceled immediately.
+    # endpoint revokes all of them, regardless of which token you specify.
     # __Important:__ The `Authorization` header for this endpoint must have the
     # following format:
     # ```

data/lib/square/client.rb

@@ -4,7 +4,7 @@ module Square
     attr_reader :config, :auth_managers
 
     def sdk_version
-      '30.0.0.20230720'
+      '32.0.0.20230925'
     end
 
     def square_version
@@ -267,7 +267,7 @@ module Square
                    retry_methods: %i[get put], http_callback: nil,
                    environment: 'production',
                    custom_url: 'https://connect.squareup.com', access_token: '',
-                   square_version: '2023-07-20', user_agent_detail: '',
+                   square_version: '2023-09-25', user_agent_detail: '',
                    additional_headers: {}, config: nil)
       @config = if config.nil?
                   Configuration.new(connection: connection, adapter: adapter,

data/lib/square/configuration.rb

@@ -19,7 +19,7 @@ module Square
                    retry_methods: %i[get put], http_callback: nil,
                    environment: 'production',
                    custom_url: 'https://connect.squareup.com', access_token: '',
-                   square_version: '2023-07-20', user_agent_detail: '',
+                   square_version: '2023-09-25', user_agent_detail: '',
                    additional_headers: {})
 
       super connection: connection, adapter: adapter, timeout: timeout,

data/lib/square/utilities/webhooks_helper.rb

@@ -0,0 +1,23 @@
+require 'openssl'
+require 'base64'
+
+module Square
+  class WebhooksHelper
+    def self.is_valid_webhook_event_signature(request_body, signature_header, signature_key, notification_url)
+      return false if request_body.nil?
+      raise 'signature_key is null or empty' if signature_key.nil? || signature_key.empty?
+      raise 'notification_url is null or empty' if notification_url.nil? || notification_url.empty?
+
+      # Perform UTF-8 encoding to bytes
+      payload_bytes = "#{notification_url}#{request_body}".force_encoding('utf-8')
+      signature_key_bytes = signature_key.force_encoding('utf-8')
+
+      # Compute the hash value
+      hmac = OpenSSL::HMAC.digest('sha256', signature_key_bytes, payload_bytes)
+
+      # Compare the computed hash vs the value in the signature header
+      hash_base64 = Base64.strict_encode64(hmac)
+      hash_base64 == signature_header
+    end
+  end
+end

data/lib/square.rb

@@ -72,3 +72,4 @@ require_relative 'square/api/team_api'
 require_relative 'square/api/terminal_api'
 require_relative 'square/api/vendors_api'
 require_relative 'square/api/webhook_subscriptions_api'
+require_relative 'square/utilities/webhooks_helper'

data/test/webhooks/test_webhooks_helper.rb

@@ -0,0 +1,136 @@
+require_relative '../../lib/square/utilities/webhooks_helper.rb'
+require 'minitest/autorun'
+require 'minitest/hell'
+require 'minitest/pride'
+require 'minitest/proveit'
+require 'logger'
+
+class WebhooksHelperTest < Minitest::Test
+  # Called only once for the class before any test has executed
+  def setup
+    @logger = Logger.new(STDOUT) # Create a Logger instance for logging
+    @logger.level = Logger::INFO # Set the log level to INFO or any desired level
+    @request_body = '{"merchant_id":"MLEFBHHSJGVHD","type":"webhooks.test_notification","event_id":"ac3ac95b-f97d-458c-a6e6-18981597e05f","created_at":"2022-07-13T20:30:59.037339943Z","data":{"type":"webhooks","id":"bc368e64-01aa-407e-b46e-3231809b1129"}}'
+    @signature_header = 'GF4YkrJgGBDZ9NIYbNXBnMzqb2HoL4RW/S6vkZ9/2N4='
+    @signature_key = 'Ibxx_5AKakO-3qeNVR61Dw'
+    @notification_url = 'https://webhook.site/679a4f3a-dcfa-49ee-bac5-9d0edad886b9'
+  end
+
+  def test_signature_validation_pass
+    @logger.info('Running test_signature_validation_pass') # Log a message
+    is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature(
+      @request_body,
+      @signature_header,
+      @signature_key,
+      @notification_url
+    )
+    assert_equal true, is_valid
+  end
+
+  def test_signature_validation_fails_on_notification_url_mismatch
+    @logger.info('Running test_signature_validation_fails_on_notification_url_mismatch') # Log a message
+    is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature(
+      @request_body,
+      @signature_header,
+      @signature_key,
+      'https://webhook.site/79a4f3a-dcfa-49ee-bac5-9d0edad886b9'
+    )
+    assert_equal false, is_valid
+  end
+
+  def test_signature_validation_fails_on_invalid_signature_key
+    @logger.info('Running test_signature_validation_fails_on_invalid_signature_key') # Log a message
+    is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature(
+      @request_body,
+      @signature_header,
+      'MCmhFRxGX82xMwg5FsaoQA',
+      @notification_url
+    )
+    assert_equal false, is_valid
+  end
+
+  def test_signature_validation_fails_on_invalid_signature_header
+    is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature(
+      @request_body,
+      '1z2n3DEJJiUPKcPzQo1ftvbxGdw=',
+      @signature_key,
+      @notification_url
+    )
+    assert_equal false, is_valid
+  end
+
+  def test_signature_validation_fails_on_request_body_mismatch
+    request_body = '{"merchant_id":"MLEFBHHSJGVHD","type":"webhooks.test_notification","event_id":"ac3ac95b-f97d-458c-a6e6-18981597e05f","created_at":"2022-06-13T20:30:59.037339943Z","data":{"type":"webhooks","id":"bc368e64-01aa-407e-b46e-3231809b1129"}}'
+    is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature(
+      request_body,
+      @signature_header,
+      @signature_key,
+      @notification_url
+    )
+    assert_equal false, is_valid
+  end
+
+  def test_signature_validation_fails_on_request_body_formatted
+    request_body = '{
+            "merchant_id": "MLEFBHHSJGVHD",
+            "type": "webhooks.test_notification",
+            "event_id": "ac3ac95b-f97d-458c-a6e6-18981597e05f",
+            "created_at": "2022-07-13T20:30:59.037339943Z",
+            "data": {
+                "type": "webhooks",
+                "id": "bc368e64-01aa-407e-b46e-3231809b1129"
+            }
+        }'
+    is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature(
+      request_body,
+      @signature_header,
+      @signature_key,
+      @notification_url
+    )
+    assert_equal false, is_valid
+  end
+
+  def test_throws_error_on_empty_signature_key
+    assert_raises(RuntimeError, 'signature_key is null or empty') do
+      Square::WebhooksHelper.is_valid_webhook_event_signature(
+        @request_body,
+        @signature_header,
+        '',
+        @notification_url
+      )
+    end
+  end
+
+  def test_throws_error_on_signature_key_not_configured
+    assert_raises(RuntimeError) do
+      Square::WebhooksHelper.is_valid_webhook_event_signature(
+        @request_body,
+        @signature_header,
+        nil,
+        @notification_url
+      )
+    end
+  end
+
+  def test_throws_error_on_empty_notification_url
+    assert_raises(RuntimeError, 'notification_url is null or empty') do
+      Square::WebhooksHelper.is_valid_webhook_event_signature(
+        @request_body,
+        @signature_header,
+        @signature_key,
+        ''
+      )
+    end
+  end
+
+  def test_throws_error_on_notification_url_not_configured
+    assert_raises(RuntimeError) do
+      Square::WebhooksHelper.is_valid_webhook_event_signature(
+        @request_body,
+        @signature_header,
+        @signature_key,
+        nil
+      )
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: square.rb
 version: !ruby/object:Gem::Version
-  version: 30.0.0.20230720
+  version: 32.0.0.20230925
 platform: ruby
 authors:
 - Square Developer Platform
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-19 00:00:00.000000000 Z
+date: 2023-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: apimatic_core_interfaces
@@ -150,6 +150,7 @@ files:
 - lib/square/http/http_response.rb
 - lib/square/utilities/date_time_helper.rb
 - lib/square/utilities/file_wrapper.rb
+- lib/square/utilities/webhooks_helper.rb
 - spec/user_journey_spec.rb
 - test/api/api_test_base.rb
 - test/api/test_catalog_api.rb
@@ -161,6 +162,7 @@ files:
 - test/api/test_payments_api.rb
 - test/api/test_refunds_api.rb
 - test/http_response_catcher.rb
+- test/webhooks/test_webhooks_helper.rb
 homepage: ''
 licenses:
 - Apache-2.0