Add Reporting API polling helper + tests (FER-11257)

fern-support · fern-support · commit 225dab0f345a · 2026-06-14T09:38:55.000-04:00
The Reporting API's /reporting/v1/load endpoint is asynchronous: a
still-processing query returns HTTP 200 with {"error":"Continue wait"}
and must be re-sent until results arrive.

- ReportingHelper::loadAndWait wraps reporting-&gt;load in an exponential-
  backoff retry loop (defaults: 2s -&gt; 20s, factor 2, 20 attempts) with an
  optional shouldCancel predicate. Under PHP strict typing the sentinel
  body omits the non-nullable LoadResponse::$results, so the generated
  deserializer raises a TypeError; that is the retry signal (real API /
  transport errors propagate). Exported via src/Utils, .fernignore-protected.
- Offline unit tests (tests/Integration/ReportingHelperTest.php) exercise
  the loop through the real LoadResponse deserializer, including a probe
  proving the Continue-wait body raises TypeError.
- Live smoke test (tests/Integration/ReportingTest.php) targets production
  and is skipped unless TEST_SQUARE_REPORTING is set.
- README: hand-authored Reporting API section documenting getMetadata,
  the Continue-wait behavior, and loadAndWait options.
diff --git a/.fernignore b/.fernignore
@@ -6,6 +6,7 @@ phpstan.neon
 src/Exceptions/SquareApiException.php
 src/Legacy
 src/Utils/WebhooksHelper.php
+src/Utils/ReportingHelper.php
 tests/Integration
 .fern/replay.lock
 .fern/replay.yml
diff --git a/README.md b/README.md
@@ -210,6 +210,77 @@ $isValid = WebhooksHelper.verifySignature(
 )
 ```
 
+## Reporting API
+
+The [Square Reporting API](https://developer.squareup.com/docs/reporting-api/overview) lets you
+query aggregated business data. Start by calling `getMetadata` to discover the schema — the cubes,
+views, measures, dimensions, and segments you can reference — then run a query with `load`:
+
+```php
+$metadata = $client->reporting->getMetadata();
+
+$response = $client->reporting->load(new Square\Reporting\Requests\LoadRequest([
+    'query' => new Square\Types\Query([
+        'measures' => ['Orders.count'],
+    ]),
+]));
+```
+
+### Polling for long-running queries
+
+The `load` endpoint is asynchronous. While a query is still being computed, the API responds with
+an HTTP `200` whose body is `{ "error": "Continue wait" }` instead of results, and the client is
+expected to re-send the identical request until the results are ready. The SDK provides
+`ReportingHelper::loadAndWait`, which owns that retry loop with exponential backoff:
+
+```php
+use Square\Utils\ReportingHelper;
+use Square\Reporting\Requests\LoadRequest;
+use Square\Types\Query;
+
+$response = ReportingHelper::loadAndWait(
+    $client,
+    new LoadRequest([
+        'query' => new Query([
+            'measures' => ['Orders.count'],
+        ]),
+    ]),
+);
+
+foreach ($response->getResults() as $result) {
+    // ...
+}
+```
+
+`loadAndWait` accepts an options array to tune the polling behavior:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `maxAttempts` | `20` | Maximum poll attempts before giving up. |
+| `initialDelayMs` | `2000` | Delay before the first retry, in milliseconds. |
+| `maxDelayMs` | `20000` | Upper bound on the backoff delay, in milliseconds. |
+| `backoffFactor` | `2` | Multiplier applied to the delay after each attempt. |
+| `shouldCancel` | `null` | A `callable(): bool` polled before each attempt (and during the wait); aborts the loop when it returns `true`. |
+| `requestOptions` | `null` | Per-request options forwarded to each underlying `reporting->load` call. |
+
+```php
+$response = ReportingHelper::loadAndWait(
+    $client,
+    new LoadRequest([/* ... */]),
+    [
+        'maxAttempts' => 30,
+        'initialDelayMs' => 1000,
+        'shouldCancel' => fn (): bool => /* e.g. a deadline check */ false,
+    ],
+);
+```
+
+If the query does not resolve within `maxAttempts`, or if `shouldCancel` aborts it, a
+`Square\Exceptions\SquareException` is thrown.
+
+> **Note:** The Reporting API is available in **production only** and requires a
+> reporting-provisioned access token; it is not available in the sandbox environment.
+
 ## 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.
diff --git a/src/Utils/ReportingHelper.php b/src/Utils/ReportingHelper.php
@@ -0,0 +1,149 @@
+<?php
+
+namespace Square\Utils;
+
+use Square\SquareClient;
+use Square\Reporting\Requests\LoadRequest;
+use Square\Types\LoadResponse;
+use Square\Exceptions\SquareException;
+use TypeError;
+
+/**
+ * Utility to help with the Square Reporting API.
+ * See https://developer.squareup.com/docs/reporting-api/overview for more details.
+ *
+ * The `/reporting/v1/load` endpoint is asynchronous: a query that is still being
+ * computed comes back as an HTTP 200 whose body is `{ "error": "Continue wait" }`
+ * rather than the results. Clients are expected to re-send the identical request,
+ * with backoff, until real results arrive. {@see ReportingHelper::loadAndWait()}
+ * owns that retry loop.
+ *
+ * Detecting the sentinel under PHP's strict typing: a "Continue wait" body omits
+ * the `LoadResponse::$results` field (which is non-nullable), so the generated
+ * `reporting->load()` raises a `TypeError` while deserializing it rather than
+ * returning a populated object. That `TypeError` — distinct from the
+ * `SquareApiException` / `SquareException` raised for real API and transport
+ * failures, which are allowed to propagate — is the retry signal. (Should the
+ * `LoadResponse` schema ever make `results` optional, the sentinel would instead
+ * survive as an unmapped `error` property; the helper checks for that case too.)
+ */
+class ReportingHelper
+{
+    /**
+     * Sentinel value returned by the Reporting API on an HTTP 200 while a
+     * `/reporting/v1/load` query is still processing. It is NOT an error — the
+     * request should be retried.
+     */
+    private const CONTINUE_WAIT = 'Continue wait';
+
+    /**
+     * Runs a reporting query and transparently polls until it resolves, returning
+     * the final {@see LoadResponse}. Re-sends the identical request with exponential
+     * backoff while the API answers "Continue wait".
+     *
+     * @param SquareClient $client The configured Square client.
+     * @param LoadRequest $request The reporting query (same shape as `reporting->load`).
+     * @param ?array{
+     *   maxAttempts?: int,
+     *   initialDelayMs?: int,
+     *   maxDelayMs?: int,
+     *   backoffFactor?: float,
+     *   shouldCancel?: callable(): bool,
+     *   requestOptions?: array{
+     *     baseUrl?: string,
+     *     maxRetries?: int,
+     *     timeout?: float,
+     *     headers?: array<string, string>,
+     *     queryParameters?: array<string, mixed>,
+     *     bodyProperties?: array<string, mixed>,
+     *   },
+     * } $options Polling/backoff configuration:
+     *   - `maxAttempts`    Maximum poll attempts before giving up. Default 20.
+     *   - `initialDelayMs` Delay before the first retry, in ms. Default 2000.
+     *   - `maxDelayMs`     Upper bound on the backoff delay, in ms. Default 20000.
+     *   - `backoffFactor`  Multiplier applied to the delay after each attempt. Default 2.
+     *   - `shouldCancel`   Predicate polled before each attempt and during the
+     *                      backoff wait; aborts the loop when it returns `true`.
+     *   - `requestOptions` Forwarded to each underlying `reporting->load` call.
+     * @return LoadResponse The resolved response (never the "Continue wait" sentinel).
+     * @throws SquareException If the query does not resolve within `maxAttempts`, or if cancelled.
+     */
+    public static function loadAndWait(
+        SquareClient $client,
+        LoadRequest $request = new LoadRequest(),
+        ?array $options = null,
+    ): LoadResponse {
+        $options ??= [];
+        $maxAttempts = $options['maxAttempts'] ?? 20;
+        $initialDelayMs = $options['initialDelayMs'] ?? 2000;
+        $maxDelayMs = $options['maxDelayMs'] ?? 20000;
+        $backoffFactor = $options['backoffFactor'] ?? 2;
+        $shouldCancel = $options['shouldCancel'] ?? null;
+        $requestOptions = $options['requestOptions'] ?? null;
+
+        $delayMs = $initialDelayMs;
+        for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
+            if ($shouldCancel !== null && $shouldCancel()) {
+                throw new SquareException(message: 'Reporting query polling was cancelled.');
+            }
+
+            try {
+                $response = $client->reporting->load($request, $requestOptions);
+                if (!self::isContinueWait($response)) {
+                    return $response;
+                }
+            } catch (TypeError) {
+                // The still-processing "Continue wait" body omits the required
+                // `results` field, so the generated deserializer raises a TypeError.
+                // Real API/transport failures raise SquareApiException/SquareException
+                // and are intentionally left to propagate.
+            }
+
+            if ($attempt === $maxAttempts) {
+                break;
+            }
+            self::sleep($delayMs, $shouldCancel);
+            $delayMs = (int) min($delayMs * $backoffFactor, $maxDelayMs);
+        }
+
+        throw new SquareException(
+            message: sprintf(
+                'Reporting query did not complete after %d attempts ("%s").',
+                $maxAttempts,
+                self::CONTINUE_WAIT,
+            ),
+        );
+    }
+
+    /**
+     * Forward-compatible sentinel check: if the generated `LoadResponse` ever makes
+     * `results` optional, a "Continue wait" body would deserialize successfully with
+     * the unmapped `error` field preserved as an additional property. Treat that as
+     * a retry signal rather than a result.
+     */
+    private static function isContinueWait(LoadResponse $response): bool
+    {
+        return ($response->getAdditionalProperties()['error'] ?? null) === self::CONTINUE_WAIT;
+    }
+
+    /**
+     * Sleeps for the given number of milliseconds, polling `$shouldCancel` in small
+     * slices so cancellation stays responsive during a long backoff wait.
+     *
+     * @param ?callable(): bool $shouldCancel
+     * @throws SquareException If cancelled mid-wait.
+     */
+    private static function sleep(int $ms, ?callable $shouldCancel): void
+    {
+        $sliceMs = 100;
+        $remaining = $ms;
+        while ($remaining > 0) {
+            if ($shouldCancel !== null && $shouldCancel()) {
+                throw new SquareException(message: 'Reporting query polling was cancelled.');
+            }
+            $chunk = min($sliceMs, $remaining);
+            usleep($chunk * 1000);
+            $remaining -= $chunk;
+        }
+    }
+}
diff --git a/tests/Integration/ReportingHelperTest.php b/tests/Integration/ReportingHelperTest.php
@@ -0,0 +1,163 @@
+<?php
+
+namespace Square\Tests\Integration;
+
+use PHPUnit\Framework\TestCase;
+use Square\Reporting\ReportingClient;
+use Square\Reporting\Requests\LoadRequest;
+use Square\Exceptions\SquareException;
+use Square\SquareClient;
+use Square\Types\LoadResponse;
+use Square\Types\LoadResult;
+use Square\Types\LoadResultAnnotation;
+use Square\Utils\ReportingHelper;
+use TypeError;
+
+/**
+ * The Reporting API answers a still-processing `/reporting/v1/load` query with an
+ * HTTP 200 whose body is `{ "error": "Continue wait" }`. `ReportingHelper::loadAndWait`
+ * owns the retry loop around that sentinel.
+ *
+ * These tests run fully offline: the `reporting` client is replaced with a stub
+ * that pops a scripted sequence of responses. A "Continue wait" entry is fed as the
+ * raw JSON body and deserialized through the *real* generated `LoadResponse::fromJson`,
+ * so the sentinel is detected by exactly the same mechanism as in production — the
+ * deserializer raising a `TypeError` on the missing, non-nullable `results` field —
+ * rather than a hand-faked exception. Resolved entries are real `LoadResponse` objects.
+ */
+class ReportingHelperTest extends TestCase
+{
+    private const CONTINUE_WAIT_BODY = '{"error":"Continue wait"}';
+
+    /** Builds a minimal, fully-valid resolved `LoadResponse` with one result row. */
+    private static function resolvedResponse(): LoadResponse
+    {
+        return new LoadResponse([
+            'results' => [
+                new LoadResult([
+                    'annotation' => new LoadResultAnnotation([
+                        'measures' => [],
+                        'dimensions' => [],
+                        'segments' => [],
+                        'timeDimensions' => [],
+                    ]),
+                    'data' => [['Orders.count' => '128']],
+                ]),
+            ],
+        ]);
+    }
+
+    /**
+     * Builds a SquareClient whose `reporting->load` returns the next scripted entry
+     * (the last entry repeats once exhausted), recording the call count. A string
+     * entry is deserialized via the real `LoadResponse::fromJson`; a `LoadResponse`
+     * entry is returned as-is.
+     *
+     * @param array<string|LoadResponse> $sequence One entry per expected `load` call.
+     * @param int &$callCount Receives the number of `load` invocations.
+     */
+    private function clientReturning(array $sequence, int &$callCount): SquareClient
+    {
+        $callCount = 0;
+        $reporting = $this->getMockBuilder(ReportingClient::class)
+            ->disableOriginalConstructor()
+            ->onlyMethods(['load'])
+            ->getMock();
+        $reporting->method('load')->willReturnCallback(
+            function () use ($sequence, &$callCount): LoadResponse {
+                $entry = $sequence[min($callCount, count($sequence) - 1)];
+                $callCount++;
+                // Real deserialization for the sentinel: a "Continue wait" body raises
+                // a TypeError here, exactly as the generated client does in production.
+                return is_string($entry) ? LoadResponse::fromJson($entry) : $entry;
+            }
+        );
+
+        $client = new SquareClient('test-token');
+        $client->reporting = $reporting;
+        return $client;
+    }
+
+    public function testPollsPastContinueWaitAndReturnsResolvedResult(): void
+    {
+        $callCount = 0;
+        $client = $this->clientReturning(
+            [self::CONTINUE_WAIT_BODY, self::CONTINUE_WAIT_BODY, self::resolvedResponse()],
+            $callCount,
+        );
+
+        $response = ReportingHelper::loadAndWait(
+            $client,
+            new LoadRequest(),
+            ['initialDelayMs' => 1, 'maxDelayMs' => 1, 'maxAttempts' => 5],
+        );
+
+        $this->assertCount(1, $response->getResults());
+        $this->assertArrayNotHasKey('error', $response->getAdditionalProperties());
+        $this->assertSame(3, $callCount);
+    }
+
+    public function testReturnsImmediatelyWhenFirstResponseHasResults(): void
+    {
+        $callCount = 0;
+        $client = $this->clientReturning([self::resolvedResponse()], $callCount);
+
+        $response = ReportingHelper::loadAndWait($client, new LoadRequest(), ['initialDelayMs' => 1]);
+
+        $this->assertCount(1, $response->getResults());
+        $this->assertSame(1, $callCount);
+    }
+
+    public function testThrowsOnceMaxAttemptsExhausted(): void
+    {
+        $callCount = 0;
+        $client = $this->clientReturning([self::CONTINUE_WAIT_BODY], $callCount); // never resolves
+
+        try {
+            ReportingHelper::loadAndWait(
+                $client,
+                new LoadRequest(),
+                ['initialDelayMs' => 1, 'maxDelayMs' => 1, 'maxAttempts' => 3],
+            );
+            $this->fail('Expected SquareException was not thrown.');
+        } catch (SquareException $e) {
+            $this->assertStringContainsString('did not complete after 3 attempts', $e->getMessage());
+        }
+        $this->assertSame(3, $callCount);
+    }
+
+    public function testCancellationAbortsPolling(): void
+    {
+        $callCount = 0;
+        $client = $this->clientReturning([self::CONTINUE_WAIT_BODY], $callCount); // would otherwise poll
+
+        $this->expectException(SquareException::class);
+        $this->expectExceptionMessage('cancelled');
+
+        ReportingHelper::loadAndWait(
+            $client,
+            new LoadRequest(),
+            ['maxAttempts' => 10, 'shouldCancel' => fn (): bool => true],
+        );
+    }
+
+    /**
+     * The crux of the design: the generated `reporting->load` deserializes the
+     * "Continue wait" body into a TypeError (the non-nullable `results` is absent).
+     * That raised TypeError is how `loadAndWait` recognizes the sentinel; if it ever
+     * stops throwing, the helper would mistake "Continue wait" for a result.
+     */
+    public function testContinueWaitBodyRaisesTypeErrorOnDeserialization(): void
+    {
+        $this->expectException(TypeError::class);
+        LoadResponse::fromJson(self::CONTINUE_WAIT_BODY);
+    }
+
+    /** A real (here, empty) result body deserializes cleanly, with no sentinel. */
+    public function testResolvedBodyDeserializesCleanly(): void
+    {
+        $resolved = LoadResponse::fromJson('{"results":[]}');
+        $this->assertSame([], $resolved->getResults());
+        $this->assertArrayNotHasKey('error', $resolved->getAdditionalProperties());
+    }
+}
diff --git a/tests/Integration/ReportingTest.php b/tests/Integration/ReportingTest.php
