SDK regeneration

.fern/metadata.json

@@ -5,5 +5,5 @@
   "generatorConfig": {
     "enableWireTests": true
   },
-  "sdkVersion": "45.1.0.20260520"
+  "sdkVersion": "45.2.0.20260520"
 }

.fernignore

@@ -7,6 +7,10 @@ test/custom
 .github/workflows
 README.md
 lib/square/file_param.rb
+
+# Custom polling helper for the Reporting API (load_and_wait + Continue-wait
+# retry loop). Unit test lives under the already-ignored test/custom. FER-11257.
+lib/square/reporting_helper.rb
 Gemfile.custom
 custom.gemspec.rb
 

.github/workflows/ci.yml

@@ -19,6 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       SQUARE_SANDBOX_TOKEN: ${{ secrets.SQUARE_SANDBOX_TOKEN }}
+      TEST_SQUARE_REPORTING: ${{ secrets.TEST_SQUARE_REPORTING }}
     strategy:
       matrix:
         ruby-version: ['3.3', '3.4']

Gemfile.lock

@@ -1,85 +1,28 @@
 PATH
   remote: .
   specs:
-    square.rb (45.1.0.20260520)
-      apimatic_core (~> 0.3.11)
-      apimatic_core_interfaces (~> 0.2.1)
-      apimatic_faraday_client_adapter (~> 0.1.4)
+    square.rb (45.2.0.20260520)
 
 GEM
   remote: https://rubygems.org/
   specs:
     addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
-    apimatic_core (0.3.21)
-      apimatic_core_interfaces (~> 0.2.0)
-      certifi (~> 2018.1, >= 2018.01.18)
-      faraday-multipart (~> 1.0)
-      nokogiri (~> 1.13, >= 1.13.10)
-    apimatic_core_interfaces (0.2.3)
-    apimatic_faraday_client_adapter (0.1.6)
-      apimatic_core_interfaces (~> 0.2.0)
-      certifi (~> 2018.1, >= 2018.01.18)
-      faraday (~> 2.0, >= 2.0.1)
-      faraday-follow_redirects (~> 0.2)
-      faraday-gzip (>= 1, < 4)
-      faraday-http-cache (~> 2.2)
-      faraday-multipart (~> 1.0)
-      faraday-net_http_persistent (~> 2.0)
-      faraday-retry (~> 2.0)
     ast (2.4.3)
-    base64 (0.3.0)
     bigdecimal (4.1.2)
-    certifi (2018.01.18)
     coderay (1.1.3)
-    connection_pool (3.0.2)
     crack (1.0.1)
       bigdecimal
       rexml
-    faraday (2.14.2)
-      faraday-net_http (>= 2.0, < 3.5)
-      json
-      logger
-    faraday-follow_redirects (0.5.0)
-      faraday (>= 1, < 3)
-    faraday-gzip (3.1.0)
-      faraday (>= 2.0, < 3)
-      zlib (~> 3.0)
-    faraday-http-cache (2.7.0)
-      faraday (>= 0.8)
-    faraday-multipart (1.2.0)
-      multipart-post (~> 2.0)
-    faraday-net_http (3.4.3)
-      net-http (~> 0.5)
-    faraday-net_http_persistent (2.3.1)
-      faraday (~> 2.5)
-      net-http-persistent (>= 4.0.4, < 5)
-    faraday-retry (2.4.0)
-      faraday (~> 2.0)
     hashdiff (1.2.1)
     io-console (0.8.2)
-    json (2.19.5)
+    json (2.19.9)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    logger (1.7.0)
     method_source (1.1.0)
-    mini_portile2 (2.8.9)
     minitest (5.27.0)
-    minitest-proveit (1.0.1)
-      minitest (> 5, < 7)
     minitest-rg (5.4.0)
       minitest (>= 5.0, < 7)
-    multipart-post (2.4.1)
-    mutex_m (0.3.0)
-    net-http (0.9.1)
-      uri (>= 0.11.1)
-    net-http-persistent (4.0.8)
-      connection_pool (>= 2.2.4, < 4)
-    nokogiri (1.19.3)
-      mini_portile2 (~> 2.8.2)
-      racc (~> 1.4)
-    nokogiri (1.19.3-x86_64-linux-musl)
-      racc (~> 1.4)
     parallel (2.1.0)
     parser (3.3.11.1)
       ast (~> 2.4.1)
@@ -97,7 +40,7 @@ GEM
     reline (0.6.3)
       io-console (~> 0.5)
     rexml (3.4.4)
-    rubocop (1.86.2)
+    rubocop (1.87.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -119,23 +62,18 @@ GEM
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
-    uri (1.1.1)
     webmock (3.26.2)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    zlib (3.2.3)
 
 PLATFORMS
   ruby
-  x86_64-linux-musl
+  x86_64-linux
 
 DEPENDENCIES
-  base64
   minitest (~> 5.16)
-  minitest-proveit (~> 1.0)
   minitest-rg
-  mutex_m
   pry
   rake (~> 13.0)
   rubocop (~> 1.21)

README.md

@@ -255,6 +255,60 @@ response = client.payments.create(..., {
 })
 ```
 
+## Reporting API
+
+The [Reporting API](https://developer.squareup.com/docs/reporting-api/overview) exposes two
+polling endpoints under `client.reporting`:
+
+- `get_metadata` — describes the data you can query (cubes, measures, dimensions, segments).
+  Call it first to discover the schema.
+- `load` — runs a reporting query and returns the aggregated results.
+
+`load` is asynchronous: while a query is still being computed it returns an HTTP 200 whose body
+is `{ "error": "Continue wait" }` rather than the results. Callers are expected to re-send the
+identical request, with backoff, until real results arrive.
+
+The SDK ships a `.fernignore`-protected helper that owns that retry loop. Require it explicitly
+to add `load_and_wait` to `client.reporting`:
+
+```ruby
+require "square"
+require "square/reporting_helper"
+
+client = Square::Client.new(token: ENV.fetch("SQUARE_TOKEN"))
+
+# 1. Discover the schema.
+metadata = client.reporting.get_metadata
+
+# 2. Run a query and transparently poll until it resolves.
+response = client.reporting.load_and_wait(
+  query: {
+    measures: ["orders.count"],
+    time_dimensions: [{ dimension: "orders.created_at", granularity: "day" }]
+  }
+)
+
+response.results.each { |result| puts result.to_h }
+```
+
+`load_and_wait` accepts optional polling parameters (defaults shown): `max_attempts: 20`,
+`initial_delay: 2.0`, `max_delay: 20.0`, `backoff_factor: 2.0` (seconds). It raises
+`Square::Reporting::ContinueWaitTimeoutError` if the query has not resolved within
+`max_attempts`. Pass a `should_cancel` predicate to abort the loop early (the Ruby idiom for an
+abort signal); it raises `Square::Reporting::PollingCancelledError` when the predicate returns a
+truthy value:
+
+```ruby
+deadline = Time.now + 60
+response = client.reporting.load_and_wait(
+  query: { measures: ["orders.count"] },
+  should_cancel: -> { Time.now > deadline }
+)
+```
+
+> **Note:** The Reporting API is production-only — sandbox requests return 404, and a sandbox
+> token against production returns 401. Use a production, reporting-provisioned token.
+
 ## Contributing
 
 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!

lib/square.rb

@@ -1392,6 +1392,42 @@
 require_relative "square/types/get_team_member_request"
 require_relative "square/types/get_wage_setting_request"
 require_relative "square/types/get_webhook_subscription_request"
+require_relative "square/types/cube_join"
+require_relative "square/types/segment"
+require_relative "square/types/dimension_granularity"
+require_relative "square/types/dimension_order"
+require_relative "square/types/simple_format"
+require_relative "square/types/link_format"
+require_relative "square/types/custom_time_format"
+require_relative "square/types/custom_numeric_format"
+require_relative "square/types/format"
+require_relative "square/types/format_description"
+require_relative "square/types/dimension"
+require_relative "square/types/measure"
+require_relative "square/types/folder"
+require_relative "square/types/nested_folder"
+require_relative "square/types/hierarchy"
+require_relative "square/types/cube_type"
+require_relative "square/types/cube"
+require_relative "square/types/metadata_response"
+require_relative "square/types/load_result_annotation"
+require_relative "square/types/load_result_data_row"
+require_relative "square/types/load_result_data_compact"
+require_relative "square/types/load_result_data_columnar"
+require_relative "square/types/load_result_data"
+require_relative "square/types/load_result"
+require_relative "square/types/reporting_error"
+require_relative "square/types/load_response"
+require_relative "square/types/query_filter_and"
+require_relative "square/types/query_filter_or"
+require_relative "square/types/query_filter_condition"
+require_relative "square/types/time_dimension"
+require_relative "square/types/query_filter"
+require_relative "square/types/join_subquery"
+require_relative "square/types/join_hint"
+require_relative "square/types/response_format"
+require_relative "square/types/query"
+require_relative "square/types/cache_mode"
 require_relative "square/client"
 require_relative "square/o_auth/client"
 require_relative "square/o_auth/types/revoke_token_request"
@@ -1590,6 +1626,8 @@
 require_relative "square/vendors/types/search_vendors_request"
 require_relative "square/vendors/types/get_vendors_request"
 require_relative "square/vendors/types/update_vendors_request"
+require_relative "square/reporting/client"
+require_relative "square/reporting/types/load_request"
 require_relative "square/bookings/custom_attribute_definitions/client"
 require_relative "square/bookings/custom_attribute_definitions/types/list_custom_attribute_definitions_request"
 require_relative "square/bookings/custom_attribute_definitions/types/create_booking_custom_attribute_definition_request"

lib/square/client.rb

@@ -10,7 +10,7 @@ def initialize(base_url: nil, token: ENV.fetch("SQUARE_TOKEN", nil))
       @raw_client = Square::Internal::Http::RawClient.new(
         base_url: base_url || Square::Environment::PRODUCTION,
         headers: {
-          "User-Agent" => "square.rb/45.1.0.20260520",
+          "User-Agent" => "square.rb/45.2.0.20260520",
           "X-Fern-Language" => "Ruby",
           Authorization: "Bearer #{token}"
         }
@@ -182,6 +182,11 @@ def vendors
       @vendors ||= Square::Vendors::Client.new(client: @raw_client)
     end
 
+    # @return [Square::Reporting::Client]
+    def reporting
+      @reporting ||= Square::Reporting::Client.new(client: @raw_client)
+    end
+
     # @return [Square::CashDrawers::Client]
     def cash_drawers
       @cash_drawers ||= Square::CashDrawers::Client.new(client: @raw_client)

lib/square/reporting/client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Square
+  module Reporting
+    class Client
+      # @param client [Square::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Describes the data available to query: the cubes, views, measures, dimensions, and segments you can reference in
+      # a reporting query. Call this first to discover the schema, then pass the members you need to `load`.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Square::Types::MetadataResponse]
+      def get_metadata(request_options: {}, **params)
+        Square::Internal::Types::Utils.normalize_keys(params)
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "reporting/v1/meta",
+          request_options: request_options
+        )
+        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::MetadataResponse.load(response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Runs a reporting query against the discovered schema and returns the aggregated results. Long-running queries
+      # may return a "Continue wait" response while processing — retry the same request until results are ready.
+      #
+      # @param request_options [Hash]
+      # @param params [Square::Reporting::Types::LoadRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Square::Types::LoadResponse]
+      def load(request_options: {}, **params)
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "reporting/v1/load",
+          body: Square::Reporting::Types::LoadRequest.new(params).to_h,
+          request_options: request_options
+        )
+        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::LoadResponse.load(response.body)
+        else
+          error_class = Square::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

lib/square/reporting/types/load_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Square
+  module Reporting
+    module Types
+      class LoadRequest < Internal::Types::Model
+        field :query_type, -> { String }, optional: true, nullable: false, api_name: "queryType"
+        field :cache, -> { Square::Types::CacheMode }, optional: true, nullable: false
+        field :query, -> { Square::Types::Query }, optional: true, nullable: false
+      end
+    end
+  end
+end