Merge pull request #143 from square/eden/update-list-payment-refunds

Add additional `updatedAtBeginTime`, `updatedAtEndTime`, and `sortField` query parameters to `listPaymentRefunds` endpoint.

Author: mikekono

doc/api/refunds.md

@@ -32,7 +32,10 @@ def list_payment_refunds(begin_time: nil,
                          location_id: nil,
                          status: nil,
                          source_type: nil,
-                         limit: nil)
+                         limit: nil,
+                         updated_at_begin_time: nil,
+                         updated_at_end_time: nil,
+                         sort_field: nil)
 ```
 
 ## Parameters
@@ -47,6 +50,9 @@ def list_payment_refunds(begin_time: nil,
 | `status` | `String` | Query, Optional | If provided, only refunds with the given status are returned.<br>For a list of refund status values, see [PaymentRefund](entity:PaymentRefund).<br><br>Default: If omitted, refunds are returned regardless of their status. |
 | `source_type` | `String` | Query, Optional | If provided, only returns refunds whose payments have the indicated source type.<br>Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`.<br>For information about these payment source types, see<br>[Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).<br><br>Default: If omitted, refunds are returned regardless of the source type. |
 | `limit` | `Integer` | Query, Optional | The maximum number of results to be returned in a single page.<br><br>It is possible to receive fewer results than the specified limit on a given page.<br><br>If the supplied value is greater than 100, no more than 100 results are returned.<br><br>Default: 100 |
+| `updated_at_begin_time` | `string` | Query, Optional | Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339<br>format.  The range is determined using the `updated_at` field for each `PaymentRefund`.<br><br>Default: if omitted, the time range starts at `begin_time`. |
+| `updated_at_end_time` | `string` | Query, Optional | Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339<br>format.  The range is determined using the `updated_at` field for each `PaymentRefund`.<br><br>Default: The current time. |
+| `sort_field` | `string` | Query, Optional | The field used to sort results by. The default is `CREATED_AT`.<br>Current values include `CREATED_AT` and `UPDATED_AT`.<br> |
 
 ## Response Type
 

doc/client.md

@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 |  --- | --- | --- |
-| `square_version` | `String` | Square Connect API versions<br>*Default*: `'2025-01-23'` |
+| `square_version` | `String` | Square Connect API versions<br>*Default*: `'2025-02-20'` |
 | `custom_url` | `String` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`<br>*Default*: `'https://connect.squareup.com'` |
 | `environment` | `string` | The API environment. <br> **Default: `production`** |
 | `connection` | `Faraday::Connection` | The Faraday connection object passed by the SDK user for making requests |
@@ -25,7 +25,7 @@ The API client can be initialized as follows:
 
 ```ruby
 client = Square::Client.new(
-  square_version: '2025-01-23',
+  square_version: '2025-02-20',
   bearer_auth_credentials: BearerAuthCredentials.new(
     access_token: 'AccessToken'
   ),
@@ -55,7 +55,7 @@ require 'square'
 include Square
 
 client = Square::Client.new(
-  square_version: '2025-01-23',
+  square_version: '2025-02-20',
   bearer_auth_credentials: BearerAuthCredentials.new(
     access_token: 'AccessToken'
   ),

doc/models/list-payment-refunds-request.md

@@ -22,6 +22,9 @@ The maximum results per page is 100.
 | `status` | `String` | Optional | If provided, only refunds with the given status are returned.<br>For a list of refund status values, see [PaymentRefund](entity:PaymentRefund).<br><br>Default: If omitted, refunds are returned regardless of their status. |
 | `source_type` | `String` | Optional | If provided, only returns refunds whose payments have the indicated source type.<br>Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`.<br>For information about these payment source types, see<br>[Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).<br><br>Default: If omitted, refunds are returned regardless of the source type. |
 | `limit` | `Integer` | Optional | The maximum number of results to be returned in a single page.<br><br>It is possible to receive fewer results than the specified limit on a given page.<br><br>If the supplied value is greater than 100, no more than 100 results are returned.<br><br>Default: 100 |
+| `updated_at_begin_time` | `String` | Optional | Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339<br>format.  The range is determined using the `updated_at` field for each `PaymentRefund`.<br><br>Default: if omitted, the time range starts at `begin_time`. |
+| `updated_at_end_time` | `String` | Optional | Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339<br>format.  The range is determined using the `updated_at` field for each `PaymentRefund`.<br><br>Default: The current time. |
+| `sort_field` | `String` | Optional | The field used to sort results by. The default is `CREATED_AT`.<br>Current values include `CREATED_AT` and `UPDATED_AT`.<br> |
 
 ## Example (as JSON)
 

lib/square/api/base_api.rb

@@ -5,7 +5,7 @@ class BaseApi
     attr_accessor :config, :http_call_back
 
     def self.user_agent
-      'Square-Ruby-SDK/41.0.0.20250123 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}'
+      'Square-Ruby-SDK/41.1.0.20250220 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}'
     end
 
     def self.user_agent_parameters

lib/square/api/refunds_api.rb

@@ -40,6 +40,18 @@ class RefundsApi < BaseApi
     # to be returned in a single page.  It is possible to receive fewer results
     # than the specified limit on a given page.  If the supplied value is
     # greater than 100, no more than 100 results are returned.  Default: 100
+    # @param [String] updated_at_begin_time Optional parameter: Indicates the
+    # start of the time range to retrieve each `PaymentRefund` for, in RFC 3339
+    # format.  The range is determined using the `updated_at` field for each
+    # `PaymentRefund`.  Default: if omitted, the time range starts at
+    # `begin_time`.
+    # @param [String] updated_at_end_time Optional parameter: Indicates the end
+    # of the time range to retrieve each `PaymentRefund` for, in RFC 3339
+    # format.  The range is determined using the `updated_at` field for each
+    # `PaymentRefund`.  Default: The current time.
+    # @param [String] sort_field Optional parameter: The field used to sort
+    # results by. The default is `CREATED_AT`. Current values include
+    # `CREATED_AT` and `UPDATED_AT`.
     # @return [ApiResponse]  the complete http response with raw body and status code.
     def list_payment_refunds(begin_time: nil,
                              end_time: nil,
@@ -48,7 +60,10 @@ def list_payment_refunds(begin_time: nil,
                              location_id: nil,
                              status: nil,
                              source_type: nil,
-                             limit: nil)
+                             limit: nil,
+                             updated_at_begin_time: nil,
+                             updated_at_end_time: nil,
+                             sort_field: nil)
       new_api_call_builder
         .request(new_request_builder(HttpMethodEnum::GET,
                                      '/v2/refunds',
@@ -61,6 +76,9 @@ def list_payment_refunds(begin_time: nil,
                    .query_param(new_parameter(status, key: 'status'))
                    .query_param(new_parameter(source_type, key: 'source_type'))
                    .query_param(new_parameter(limit, key: 'limit'))
+                   .query_param(new_parameter(updated_at_begin_time, key: 'updated_at_begin_time'))
+                   .query_param(new_parameter(updated_at_end_time, key: 'updated_at_end_time'))
+                   .query_param(new_parameter(sort_field, key: 'sort_field'))
                    .header_param(new_parameter('application/json', key: 'accept'))
                    .auth(Single.new('global')))
         .response(new_response_handler

lib/square/client.rb

@@ -5,7 +5,7 @@ class Client
     attr_reader :config, :auth_managers
 
     def sdk_version
-      '41.0.0.20250123'
+      '41.1.0.20250220'
     end
 
     def square_version
@@ -274,7 +274,7 @@ def initialize(
       retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
       retry_methods: %i[get put], http_callback: nil, environment: 'production',
       custom_url: 'https://connect.squareup.com', access_token: nil,
-      bearer_auth_credentials: nil, square_version: '2025-01-23',
+      bearer_auth_credentials: nil, square_version: '2025-02-20',
       user_agent_detail: '', additional_headers: {}, config: nil
     )
       @config = if config.nil?

lib/square/configuration.rb

@@ -24,7 +24,7 @@ def initialize(
       retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
       retry_methods: %i[get put], http_callback: nil, environment: 'production',
       custom_url: 'https://connect.squareup.com', access_token: nil,
-      bearer_auth_credentials: nil, square_version: '2025-01-23',
+      bearer_auth_credentials: nil, square_version: '2025-02-20',
       user_agent_detail: '', additional_headers: {}
     )
 

square.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'square.rb'
-  s.version = '41.0.0.20250123'
+  s.version = '41.1.0.20250220'
   s.summary = 'square'
   s.description = ''
   s.authors = ['Square Developer Platform']

test/api/test_refunds_api.rb

@@ -22,9 +22,12 @@ def test_test_list_payment_refunds()
     location_id = nil
     status = nil
     source_type = nil
+    updated_at_begin_time = nil
+    updated_at_end_time = nil
+    sort_field = nil
 
     # Perform the API call through the SDK function
-    result = @controller.list_payment_refunds(begin_time: begin_time, end_time: end_time, sort_order: sort_order, cursor: cursor, location_id: location_id, status: status, source_type: source_type)
+    result = @controller.list_payment_refunds(begin_time: begin_time, end_time: end_time, sort_order: sort_order, cursor: cursor, location_id: location_id, status: status, source_type: source_type, updated_at_begin_time: updated_at_begin_time, updated_at_end_time: updated_at_end_time, sort_field: sort_field)
 
     # Test response code
     assert_equal(200, @response_catcher.response.status_code)