From 88c4fda4ed0cb1f820311dac199024193508ea6c Mon Sep 17 00:00:00 2001 From: fern-api <115122769+fern-api[bot]@users.noreply.github.com> Date: Fri, 12 Jun 2026 23:53:31 +0000 Subject: [PATCH 1/6] [fern-generated] Update SDK Generated by Fern CLI Version: unknown Generators: - fernapi/fern-typescript-sdk: 3.43.8 --- .fern/metadata.json | 2 +- package.json | 2 +- reference.md | 119 +++++++++++++ src/BaseClient.ts | 4 +- src/Client.ts | 6 + src/api/resources/index.ts | 2 + src/api/resources/reporting/client/Client.ts | 162 +++++++++++++++++ src/api/resources/reporting/client/index.ts | 1 + .../reporting/client/requests/LoadRequest.ts | 13 ++ .../reporting/client/requests/index.ts | 1 + src/api/resources/reporting/index.ts | 1 + src/api/types/CacheMode.ts | 10 ++ src/api/types/Cube.ts | 18 ++ src/api/types/CubeJoin.ts | 6 + src/api/types/CubeType.ts | 8 + src/api/types/CustomNumericFormat.ts | 13 ++ src/api/types/CustomTimeFormat.ts | 11 ++ src/api/types/Dimension.ts | 22 +++ src/api/types/DimensionGranularity.ts | 10 ++ src/api/types/DimensionOrder.ts | 7 + src/api/types/Folder.ts | 6 + src/api/types/Format.ts | 8 + src/api/types/FormatDescription.ts | 13 ++ src/api/types/Hierarchy.ts | 9 + src/api/types/JoinHint.ts | 3 + src/api/types/JoinSubquery.ts | 8 + src/api/types/LinkFormat.ts | 11 ++ src/api/types/LoadResponse.ts | 10 ++ src/api/types/LoadResult.ts | 11 ++ src/api/types/LoadResultAnnotation.ts | 8 + src/api/types/LoadResultData.ts | 8 + src/api/types/LoadResultDataColumnar.ts | 11 ++ src/api/types/LoadResultDataCompact.ts | 11 ++ src/api/types/LoadResultDataRow.ts | 6 + src/api/types/Measure.ts | 19 ++ src/api/types/MetadataResponse.ts | 8 + src/api/types/NestedFolder.ts | 6 + src/api/types/Query.ts | 19 ++ src/api/types/QueryFilter.ts | 5 + src/api/types/QueryFilterAnd.ts | 5 + src/api/types/QueryFilterCondition.ts | 7 + src/api/types/QueryFilterOr.ts | 5 + src/api/types/ReportingError.ts | 8 + src/api/types/ResponseFormat.ts | 9 + src/api/types/Segment.ts | 9 + src/api/types/SimpleFormat.ts | 12 ++ src/api/types/TimeDimension.ts | 7 + src/api/types/index.ts | 36 ++++ src/serialization/resources/index.ts | 2 + .../resources/reporting/client/index.ts | 1 + .../reporting/client/requests/LoadRequest.ts | 22 +++ .../reporting/client/requests/index.ts | 1 + .../resources/reporting/index.ts | 1 + src/serialization/types/CacheMode.ts | 12 ++ src/serialization/types/Cube.ts | 45 +++++ src/serialization/types/CubeJoin.ts | 18 ++ src/serialization/types/CubeType.ts | 14 ++ .../types/CustomNumericFormat.ts | 22 +++ src/serialization/types/CustomTimeFormat.ts | 20 +++ src/serialization/types/Dimension.ts | 44 +++++ .../types/DimensionGranularity.ts | 28 +++ src/serialization/types/DimensionOrder.ts | 12 ++ src/serialization/types/Folder.ts | 19 ++ src/serialization/types/Format.ts | 16 ++ src/serialization/types/FormatDescription.ts | 22 +++ src/serialization/types/Hierarchy.ts | 22 +++ src/serialization/types/JoinHint.ts | 13 ++ src/serialization/types/JoinSubquery.ts | 22 +++ src/serialization/types/LinkFormat.ts | 18 ++ src/serialization/types/LoadResponse.ts | 23 +++ src/serialization/types/LoadResult.ts | 28 +++ .../types/LoadResultAnnotation.ts | 24 +++ src/serialization/types/LoadResultData.ts | 15 ++ .../types/LoadResultDataColumnar.ts | 20 +++ .../types/LoadResultDataCompact.ts | 20 +++ src/serialization/types/LoadResultDataRow.ts | 12 ++ src/serialization/types/Measure.ts | 38 ++++ src/serialization/types/MetadataResponse.ts | 21 +++ src/serialization/types/NestedFolder.ts | 18 ++ src/serialization/types/Query.ts | 44 +++++ src/serialization/types/QueryFilter.ts | 15 ++ src/serialization/types/QueryFilterAnd.ts | 18 ++ .../types/QueryFilterCondition.ts | 22 +++ src/serialization/types/QueryFilterOr.ts | 18 ++ src/serialization/types/ReportingError.ts | 16 ++ src/serialization/types/ResponseFormat.ts | 12 ++ src/serialization/types/Segment.ts | 24 +++ src/serialization/types/SimpleFormat.ts | 12 ++ src/serialization/types/TimeDimension.ts | 20 +++ src/serialization/types/index.ts | 36 ++++ src/version.ts | 2 +- tests/wire/reporting.test.ts | 163 ++++++++++++++++++ yarn.lock | 6 +- 93 files changed, 1689 insertions(+), 8 deletions(-) create mode 100644 src/api/resources/reporting/client/Client.ts create mode 100644 src/api/resources/reporting/client/index.ts create mode 100644 src/api/resources/reporting/client/requests/LoadRequest.ts create mode 100644 src/api/resources/reporting/client/requests/index.ts create mode 100644 src/api/resources/reporting/index.ts create mode 100644 src/api/types/CacheMode.ts create mode 100644 src/api/types/Cube.ts create mode 100644 src/api/types/CubeJoin.ts create mode 100644 src/api/types/CubeType.ts create mode 100644 src/api/types/CustomNumericFormat.ts create mode 100644 src/api/types/CustomTimeFormat.ts create mode 100644 src/api/types/Dimension.ts create mode 100644 src/api/types/DimensionGranularity.ts create mode 100644 src/api/types/DimensionOrder.ts create mode 100644 src/api/types/Folder.ts create mode 100644 src/api/types/Format.ts create mode 100644 src/api/types/FormatDescription.ts create mode 100644 src/api/types/Hierarchy.ts create mode 100644 src/api/types/JoinHint.ts create mode 100644 src/api/types/JoinSubquery.ts create mode 100644 src/api/types/LinkFormat.ts create mode 100644 src/api/types/LoadResponse.ts create mode 100644 src/api/types/LoadResult.ts create mode 100644 src/api/types/LoadResultAnnotation.ts create mode 100644 src/api/types/LoadResultData.ts create mode 100644 src/api/types/LoadResultDataColumnar.ts create mode 100644 src/api/types/LoadResultDataCompact.ts create mode 100644 src/api/types/LoadResultDataRow.ts create mode 100644 src/api/types/Measure.ts create mode 100644 src/api/types/MetadataResponse.ts create mode 100644 src/api/types/NestedFolder.ts create mode 100644 src/api/types/Query.ts create mode 100644 src/api/types/QueryFilter.ts create mode 100644 src/api/types/QueryFilterAnd.ts create mode 100644 src/api/types/QueryFilterCondition.ts create mode 100644 src/api/types/QueryFilterOr.ts create mode 100644 src/api/types/ReportingError.ts create mode 100644 src/api/types/ResponseFormat.ts create mode 100644 src/api/types/Segment.ts create mode 100644 src/api/types/SimpleFormat.ts create mode 100644 src/api/types/TimeDimension.ts create mode 100644 src/serialization/resources/reporting/client/index.ts create mode 100644 src/serialization/resources/reporting/client/requests/LoadRequest.ts create mode 100644 src/serialization/resources/reporting/client/requests/index.ts create mode 100644 src/serialization/resources/reporting/index.ts create mode 100644 src/serialization/types/CacheMode.ts create mode 100644 src/serialization/types/Cube.ts create mode 100644 src/serialization/types/CubeJoin.ts create mode 100644 src/serialization/types/CubeType.ts create mode 100644 src/serialization/types/CustomNumericFormat.ts create mode 100644 src/serialization/types/CustomTimeFormat.ts create mode 100644 src/serialization/types/Dimension.ts create mode 100644 src/serialization/types/DimensionGranularity.ts create mode 100644 src/serialization/types/DimensionOrder.ts create mode 100644 src/serialization/types/Folder.ts create mode 100644 src/serialization/types/Format.ts create mode 100644 src/serialization/types/FormatDescription.ts create mode 100644 src/serialization/types/Hierarchy.ts create mode 100644 src/serialization/types/JoinHint.ts create mode 100644 src/serialization/types/JoinSubquery.ts create mode 100644 src/serialization/types/LinkFormat.ts create mode 100644 src/serialization/types/LoadResponse.ts create mode 100644 src/serialization/types/LoadResult.ts create mode 100644 src/serialization/types/LoadResultAnnotation.ts create mode 100644 src/serialization/types/LoadResultData.ts create mode 100644 src/serialization/types/LoadResultDataColumnar.ts create mode 100644 src/serialization/types/LoadResultDataCompact.ts create mode 100644 src/serialization/types/LoadResultDataRow.ts create mode 100644 src/serialization/types/Measure.ts create mode 100644 src/serialization/types/MetadataResponse.ts create mode 100644 src/serialization/types/NestedFolder.ts create mode 100644 src/serialization/types/Query.ts create mode 100644 src/serialization/types/QueryFilter.ts create mode 100644 src/serialization/types/QueryFilterAnd.ts create mode 100644 src/serialization/types/QueryFilterCondition.ts create mode 100644 src/serialization/types/QueryFilterOr.ts create mode 100644 src/serialization/types/ReportingError.ts create mode 100644 src/serialization/types/ResponseFormat.ts create mode 100644 src/serialization/types/Segment.ts create mode 100644 src/serialization/types/SimpleFormat.ts create mode 100644 src/serialization/types/TimeDimension.ts create mode 100644 tests/wire/reporting.test.ts diff --git a/.fern/metadata.json b/.fern/metadata.json index e860c4655..151030e32 100644 --- a/.fern/metadata.json +++ b/.fern/metadata.json @@ -54,5 +54,5 @@ } } }, - "sdkVersion": "44.1.0" + "sdkVersion": "44.2.0" } diff --git a/package.json b/package.json index 483ff3dc4..86d985bbc 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "square", - "version": "44.1.0", + "version": "44.2.0", "private": false, "repository": { "type": "git", diff --git a/reference.md b/reference.md index 73556c03a..baa667ffa 100644 --- a/reference.md +++ b/reference.md @@ -13705,6 +13705,125 @@ await client.vendors.update({ + + + + +## Reporting +
client.reporting.getMetadata() -> Square.MetadataResponse +
+
+ +#### 📝 Description + +
+
+ +
+
+ +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`. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```typescript +await client.reporting.getMetadata(); + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**requestOptions:** `ReportingClient.RequestOptions` + +
+
+
+
+ + +
+
+
+ +
client.reporting.load({ ...params }) -> Square.LoadResponse +
+
+ +#### 📝 Description + +
+
+ +
+
+ +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. +
+
+
+
+ +#### 🔌 Usage + +
+
+ +
+
+ +```typescript +await client.reporting.load(); + +``` +
+
+
+
+ +#### ⚙️ Parameters + +
+
+ +
+
+ +**request:** `Square.LoadRequest` + +
+
+ +
+
+ +**requestOptions:** `ReportingClient.RequestOptions` + +
+
+
+
+ +
diff --git a/src/BaseClient.ts b/src/BaseClient.ts index 549b355ac..7df2da7bd 100644 --- a/src/BaseClient.ts +++ b/src/BaseClient.ts @@ -56,8 +56,8 @@ export function normalizeClientOptions; + + constructor(options: ReportingClient.Options = {}) { + this._options = normalizeClientOptionsWithAuth(options); + } + + /** + * 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 {ReportingClient.RequestOptions} requestOptions - Request-specific configuration. + * + * @example + * await client.reporting.getMetadata() + */ + public getMetadata( + requestOptions?: ReportingClient.RequestOptions, + ): core.HttpResponsePromise { + return core.HttpResponsePromise.fromPromise(this.__getMetadata(requestOptions)); + } + + private async __getMetadata( + requestOptions?: ReportingClient.RequestOptions, + ): Promise> { + const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest(); + const _headers: core.Fetcher.Args["headers"] = mergeHeaders( + _authRequest.headers, + this._options?.headers, + mergeOnlyDefinedHeaders({ "Square-Version": requestOptions?.version ?? "2026-05-20" }), + requestOptions?.headers, + ); + const _response = await (this._options.fetcher ?? core.fetcher)({ + url: core.url.join( + (await core.Supplier.get(this._options.baseUrl)) ?? + (await core.Supplier.get(this._options.environment)) ?? + environments.SquareEnvironment.Production, + "reporting/v1/meta", + ), + method: "GET", + headers: _headers, + queryParameters: requestOptions?.queryParams, + timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000, + maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries, + abortSignal: requestOptions?.abortSignal, + fetchFn: this._options?.fetch, + logging: this._options.logging, + }); + if (_response.ok) { + return { + data: serializers.MetadataResponse.parseOrThrow(_response.body, { + unrecognizedObjectKeys: "passthrough", + allowUnrecognizedUnionMembers: true, + allowUnrecognizedEnumValues: true, + skipValidation: true, + breadcrumbsPrefix: ["response"], + }), + rawResponse: _response.rawResponse, + }; + } + + if (_response.error.reason === "status-code") { + throw new errors.SquareError({ + statusCode: _response.error.statusCode, + body: _response.error.body, + rawResponse: _response.rawResponse, + }); + } + + return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/reporting/v1/meta"); + } + + /** + * 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 {Square.LoadRequest} request + * @param {ReportingClient.RequestOptions} requestOptions - Request-specific configuration. + * + * @example + * await client.reporting.load() + */ + public load( + request: Square.LoadRequest = {}, + requestOptions?: ReportingClient.RequestOptions, + ): core.HttpResponsePromise { + return core.HttpResponsePromise.fromPromise(this.__load(request, requestOptions)); + } + + private async __load( + request: Square.LoadRequest = {}, + requestOptions?: ReportingClient.RequestOptions, + ): Promise> { + const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest(); + const _headers: core.Fetcher.Args["headers"] = mergeHeaders( + _authRequest.headers, + this._options?.headers, + mergeOnlyDefinedHeaders({ "Square-Version": requestOptions?.version ?? "2026-05-20" }), + requestOptions?.headers, + ); + const _response = await (this._options.fetcher ?? core.fetcher)({ + url: core.url.join( + (await core.Supplier.get(this._options.baseUrl)) ?? + (await core.Supplier.get(this._options.environment)) ?? + environments.SquareEnvironment.Production, + "reporting/v1/load", + ), + method: "POST", + headers: _headers, + contentType: "application/json", + queryParameters: requestOptions?.queryParams, + requestType: "json", + body: serializers.LoadRequest.jsonOrThrow(request, { + unrecognizedObjectKeys: "strip", + omitUndefined: true, + }), + timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000, + maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries, + abortSignal: requestOptions?.abortSignal, + fetchFn: this._options?.fetch, + logging: this._options.logging, + }); + if (_response.ok) { + return { + data: serializers.LoadResponse.parseOrThrow(_response.body, { + unrecognizedObjectKeys: "passthrough", + allowUnrecognizedUnionMembers: true, + allowUnrecognizedEnumValues: true, + skipValidation: true, + breadcrumbsPrefix: ["response"], + }), + rawResponse: _response.rawResponse, + }; + } + + if (_response.error.reason === "status-code") { + throw new errors.SquareError({ + statusCode: _response.error.statusCode, + body: _response.error.body, + rawResponse: _response.rawResponse, + }); + } + + return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/reporting/v1/load"); + } +} diff --git a/src/api/resources/reporting/client/index.ts b/src/api/resources/reporting/client/index.ts new file mode 100644 index 000000000..415726b7f --- /dev/null +++ b/src/api/resources/reporting/client/index.ts @@ -0,0 +1 @@ +export * from "./requests"; diff --git a/src/api/resources/reporting/client/requests/LoadRequest.ts b/src/api/resources/reporting/client/requests/LoadRequest.ts new file mode 100644 index 000000000..9a0dff5ad --- /dev/null +++ b/src/api/resources/reporting/client/requests/LoadRequest.ts @@ -0,0 +1,13 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../../../index"; + +/** + * @example + * {} + */ +export interface LoadRequest { + queryType?: string; + cache?: Square.CacheMode; + query?: Square.Query; +} diff --git a/src/api/resources/reporting/client/requests/index.ts b/src/api/resources/reporting/client/requests/index.ts new file mode 100644 index 000000000..d0f272edf --- /dev/null +++ b/src/api/resources/reporting/client/requests/index.ts @@ -0,0 +1 @@ +export type { LoadRequest } from "./LoadRequest"; diff --git a/src/api/resources/reporting/index.ts b/src/api/resources/reporting/index.ts new file mode 100644 index 000000000..5ec76921e --- /dev/null +++ b/src/api/resources/reporting/index.ts @@ -0,0 +1 @@ +export * from "./client"; diff --git a/src/api/types/CacheMode.ts b/src/api/types/CacheMode.ts new file mode 100644 index 000000000..f46a305fc --- /dev/null +++ b/src/api/types/CacheMode.ts @@ -0,0 +1,10 @@ +// This file was auto-generated by Fern from our API Definition. + +/** Cache strategy for a reporting query. */ +export const CacheMode = { + StaleIfSlow: "stale-if-slow", + StaleWhileRevalidate: "stale-while-revalidate", + MustRevalidate: "must-revalidate", + NoCache: "no-cache", +} as const; +export type CacheMode = (typeof CacheMode)[keyof typeof CacheMode]; diff --git a/src/api/types/Cube.ts b/src/api/types/Cube.ts new file mode 100644 index 000000000..33e01e3bf --- /dev/null +++ b/src/api/types/Cube.ts @@ -0,0 +1,18 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +export interface Cube { + name: string; + title?: string; + type: Square.CubeType; + meta?: Record; + description?: string; + measures: Square.Measure[]; + dimensions: Square.Dimension[]; + segments: Square.Segment[]; + joins?: Square.CubeJoin[]; + folders?: Square.Folder[]; + nestedFolders?: Square.NestedFolder[]; + hierarchies?: Square.Hierarchy[]; +} diff --git a/src/api/types/CubeJoin.ts b/src/api/types/CubeJoin.ts new file mode 100644 index 000000000..5deb96dc7 --- /dev/null +++ b/src/api/types/CubeJoin.ts @@ -0,0 +1,6 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface CubeJoin { + name: string; + relationship: string; +} diff --git a/src/api/types/CubeType.ts b/src/api/types/CubeType.ts new file mode 100644 index 000000000..13680e8f0 --- /dev/null +++ b/src/api/types/CubeType.ts @@ -0,0 +1,8 @@ +// This file was auto-generated by Fern from our API Definition. + +/** Type of cube */ +export const CubeType = { + Cube: "cube", + View: "view", +} as const; +export type CubeType = (typeof CubeType)[keyof typeof CubeType]; diff --git a/src/api/types/CustomNumericFormat.ts b/src/api/types/CustomNumericFormat.ts new file mode 100644 index 000000000..a53b8b01c --- /dev/null +++ b/src/api/types/CustomNumericFormat.ts @@ -0,0 +1,13 @@ +// This file was auto-generated by Fern from our API Definition. + +/** + * Custom numeric format for numeric measures and dimensions + */ +export interface CustomNumericFormat { + /** Type of the format (must be 'custom-numeric') */ + type: "custom-numeric"; + /** d3-format specifier string (e.g., '.2f', ',.0f', '$,.2f', '.0%', '.2s'). See https://d3js.org/d3-format */ + value: string; + /** Name of the predefined format (e.g., 'percent_2', 'currency_1'). Present only when a named format was used. */ + alias?: string; +} diff --git a/src/api/types/CustomTimeFormat.ts b/src/api/types/CustomTimeFormat.ts new file mode 100644 index 000000000..6c59fa959 --- /dev/null +++ b/src/api/types/CustomTimeFormat.ts @@ -0,0 +1,11 @@ +// This file was auto-generated by Fern from our API Definition. + +/** + * Custom time format for time dimensions + */ +export interface CustomTimeFormat { + /** Type of the format (must be 'custom-time') */ + type: "custom-time"; + /** POSIX strftime format string (IEEE Std 1003.1 / POSIX.1) with d3-time-format extensions (e.g., '%Y-%m-%d', '%d/%m/%Y %H:%M:%S'). See https://pubs.opengroup.org/onlinepubs/009695399/functions/strptime.html and https://d3js.org/d3-time-format */ + value: string; +} diff --git a/src/api/types/Dimension.ts b/src/api/types/Dimension.ts new file mode 100644 index 000000000..6feb85327 --- /dev/null +++ b/src/api/types/Dimension.ts @@ -0,0 +1,22 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +export interface Dimension { + name: string; + title?: string; + shortTitle?: string; + description?: string; + type: string; + /** When dimension is defined in View, it keeps the original path: Cube.dimension */ + aliasMember?: string; + granularities?: Square.DimensionGranularity[]; + meta?: Record; + format?: Square.Format; + formatDescription?: Square.FormatDescription; + /** ISO 4217 currency code in uppercase (3 characters, e.g. USD, EUR) */ + currency?: string; + order?: Square.DimensionOrder; + /** Key reference for the dimension */ + key?: string; +} diff --git a/src/api/types/DimensionGranularity.ts b/src/api/types/DimensionGranularity.ts new file mode 100644 index 000000000..727f482dc --- /dev/null +++ b/src/api/types/DimensionGranularity.ts @@ -0,0 +1,10 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface DimensionGranularity { + name: string; + title: string; + interval?: string; + sql?: string; + offset?: string; + origin?: string; +} diff --git a/src/api/types/DimensionOrder.ts b/src/api/types/DimensionOrder.ts new file mode 100644 index 000000000..e21e3762d --- /dev/null +++ b/src/api/types/DimensionOrder.ts @@ -0,0 +1,7 @@ +// This file was auto-generated by Fern from our API Definition. + +export const DimensionOrder = { + Asc: "asc", + Desc: "desc", +} as const; +export type DimensionOrder = (typeof DimensionOrder)[keyof typeof DimensionOrder]; diff --git a/src/api/types/Folder.ts b/src/api/types/Folder.ts new file mode 100644 index 000000000..093f4ffd2 --- /dev/null +++ b/src/api/types/Folder.ts @@ -0,0 +1,6 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface Folder { + name: string; + members: string[]; +} diff --git a/src/api/types/Format.ts b/src/api/types/Format.ts new file mode 100644 index 000000000..d76c05456 --- /dev/null +++ b/src/api/types/Format.ts @@ -0,0 +1,8 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +/** + * Format of measure or dimension - can be a simple string format, a link configuration, a custom time format, or a custom numeric format + */ +export type Format = Square.SimpleFormat | Square.LinkFormat | Square.CustomTimeFormat | Square.CustomNumericFormat; diff --git a/src/api/types/FormatDescription.ts b/src/api/types/FormatDescription.ts new file mode 100644 index 000000000..af1632091 --- /dev/null +++ b/src/api/types/FormatDescription.ts @@ -0,0 +1,13 @@ +// This file was auto-generated by Fern from our API Definition. + +/** + * Resolved format description with the predefined name and d3-format specifier + */ +export interface FormatDescription { + /** Predefined format name (e.g., 'percent_2', 'currency_1') or a base name like 'number', or 'custom' for ad-hoc specifiers */ + name: string; + /** d3-format specifier string (e.g., '.2f', ',.0f', '$,.2f'). See https://d3js.org/d3-format */ + specifier: string; + /** ISO 4217 currency code in uppercase (e.g. USD, EUR). Present when a currency format is used. */ + currency?: string; +} diff --git a/src/api/types/Hierarchy.ts b/src/api/types/Hierarchy.ts new file mode 100644 index 000000000..9a919a396 --- /dev/null +++ b/src/api/types/Hierarchy.ts @@ -0,0 +1,9 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface Hierarchy { + name: string; + /** When hierarchy is defined in Cube, it keeps the original path: Cube.hierarchy */ + aliasMember?: string; + title?: string; + levels: string[]; +} diff --git a/src/api/types/JoinHint.ts b/src/api/types/JoinHint.ts new file mode 100644 index 000000000..41f293adc --- /dev/null +++ b/src/api/types/JoinHint.ts @@ -0,0 +1,3 @@ +// This file was auto-generated by Fern from our API Definition. + +export type JoinHint = string[]; diff --git a/src/api/types/JoinSubquery.ts b/src/api/types/JoinSubquery.ts new file mode 100644 index 000000000..2d3d19fee --- /dev/null +++ b/src/api/types/JoinSubquery.ts @@ -0,0 +1,8 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface JoinSubquery { + sql: string; + on: string; + joinType: string; + alias: string; +} diff --git a/src/api/types/LinkFormat.ts b/src/api/types/LinkFormat.ts new file mode 100644 index 000000000..1a1981d1f --- /dev/null +++ b/src/api/types/LinkFormat.ts @@ -0,0 +1,11 @@ +// This file was auto-generated by Fern from our API Definition. + +/** + * Link format with label and type + */ +export interface LinkFormat { + /** Label for the link */ + label: string; + /** Type of the format (must be 'link') */ + type: "link"; +} diff --git a/src/api/types/LoadResponse.ts b/src/api/types/LoadResponse.ts new file mode 100644 index 000000000..eed22522a --- /dev/null +++ b/src/api/types/LoadResponse.ts @@ -0,0 +1,10 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +export interface LoadResponse { + pivotQuery?: Record; + slowQuery?: boolean; + queryType?: string; + results: Square.LoadResult[]; +} diff --git a/src/api/types/LoadResult.ts b/src/api/types/LoadResult.ts new file mode 100644 index 000000000..30c972163 --- /dev/null +++ b/src/api/types/LoadResult.ts @@ -0,0 +1,11 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +export interface LoadResult { + dataSource?: string; + annotation: Square.LoadResultAnnotation; + data: Square.LoadResultData; + refreshKeyValues?: Record[]; + lastRefreshTime?: string; +} diff --git a/src/api/types/LoadResultAnnotation.ts b/src/api/types/LoadResultAnnotation.ts new file mode 100644 index 000000000..935835d11 --- /dev/null +++ b/src/api/types/LoadResultAnnotation.ts @@ -0,0 +1,8 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface LoadResultAnnotation { + measures: Record; + dimensions: Record; + segments: Record; + timeDimensions: Record; +} diff --git a/src/api/types/LoadResultData.ts b/src/api/types/LoadResultData.ts new file mode 100644 index 000000000..b12c98716 --- /dev/null +++ b/src/api/types/LoadResultData.ts @@ -0,0 +1,8 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +/** + * Result `data` payload. Either an array of objects keyed by member name (default); a compact `{ members, dataset }` object when `responseFormat=compact`; or a columnar `{ members, columns }` object when `responseFormat=columnar`. + */ +export type LoadResultData = Square.LoadResultDataRow | Square.LoadResultDataCompact | Square.LoadResultDataColumnar; diff --git a/src/api/types/LoadResultDataColumnar.ts b/src/api/types/LoadResultDataColumnar.ts new file mode 100644 index 000000000..1251aae95 --- /dev/null +++ b/src/api/types/LoadResultDataColumnar.ts @@ -0,0 +1,11 @@ +// This file was auto-generated by Fern from our API Definition. + +/** + * Columnar data format - members list paired with one primitive array per column. Returned when `responseFormat=columnar` is requested. + */ +export interface LoadResultDataColumnar { + /** Ordered list of member names. Element `i` of `columns` holds the values for `members[i]` across all rows. */ + members: string[]; + /** One array per member, in the same order as `members`. Each inner array contains the primitive value of that member for every row (null, boolean, number, string). */ + columns: unknown[][]; +} diff --git a/src/api/types/LoadResultDataCompact.ts b/src/api/types/LoadResultDataCompact.ts new file mode 100644 index 000000000..458052a01 --- /dev/null +++ b/src/api/types/LoadResultDataCompact.ts @@ -0,0 +1,11 @@ +// This file was auto-generated by Fern from our API Definition. + +/** + * Compact data format - a single object with the members list and a dataset of primitive arrays. Returned when `responseFormat=compact` is requested. + */ +export interface LoadResultDataCompact { + /** Ordered list of member names that correspond to each cell position in `dataset` rows. */ + members: string[]; + /** Array of rows, where each row is an array of primitive values (null, boolean, number, string) aligned with `members`. */ + dataset: unknown[][]; +} diff --git a/src/api/types/LoadResultDataRow.ts b/src/api/types/LoadResultDataRow.ts new file mode 100644 index 000000000..e71a80084 --- /dev/null +++ b/src/api/types/LoadResultDataRow.ts @@ -0,0 +1,6 @@ +// This file was auto-generated by Fern from our API Definition. + +/** + * Row-oriented (default) data format - an array of rows, each row is an object keyed by member name. + */ +export type LoadResultDataRow = Record[]; diff --git a/src/api/types/Measure.ts b/src/api/types/Measure.ts new file mode 100644 index 000000000..8973d67f9 --- /dev/null +++ b/src/api/types/Measure.ts @@ -0,0 +1,19 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +export interface Measure { + name: string; + title?: string; + shortTitle?: string; + description?: string; + type: string; + aggType?: string; + meta?: Record; + format?: Square.Format; + formatDescription?: Square.FormatDescription; + /** ISO 4217 currency code in uppercase (3 characters, e.g. USD, EUR) */ + currency?: string; + /** When measure is defined in View, it keeps the original path: Cube.measure */ + aliasMember?: string; +} diff --git a/src/api/types/MetadataResponse.ts b/src/api/types/MetadataResponse.ts new file mode 100644 index 000000000..6cf87790e --- /dev/null +++ b/src/api/types/MetadataResponse.ts @@ -0,0 +1,8 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +export interface MetadataResponse { + cubes?: Square.Cube[]; + compilerId?: string; +} diff --git a/src/api/types/NestedFolder.ts b/src/api/types/NestedFolder.ts new file mode 100644 index 000000000..851964fc5 --- /dev/null +++ b/src/api/types/NestedFolder.ts @@ -0,0 +1,6 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface NestedFolder { + name: string; + members: string[]; +} diff --git a/src/api/types/Query.ts b/src/api/types/Query.ts new file mode 100644 index 000000000..1897b2a89 --- /dev/null +++ b/src/api/types/Query.ts @@ -0,0 +1,19 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +export interface Query { + measures?: string[]; + dimensions?: string[]; + segments?: string[]; + timeDimensions?: Square.TimeDimension[]; + order?: string[][]; + limit?: number; + offset?: number; + filters?: Square.QueryFilter[]; + ungrouped?: boolean; + subqueryJoins?: Square.JoinSubquery[]; + joinHints?: Square.JoinHint[]; + timezone?: string; + responseFormat?: Square.ResponseFormat; +} diff --git a/src/api/types/QueryFilter.ts b/src/api/types/QueryFilter.ts new file mode 100644 index 000000000..c81475be4 --- /dev/null +++ b/src/api/types/QueryFilter.ts @@ -0,0 +1,5 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../index"; + +export type QueryFilter = Square.QueryFilterCondition | Square.QueryFilterOr | Square.QueryFilterAnd; diff --git a/src/api/types/QueryFilterAnd.ts b/src/api/types/QueryFilterAnd.ts new file mode 100644 index 000000000..e0013f700 --- /dev/null +++ b/src/api/types/QueryFilterAnd.ts @@ -0,0 +1,5 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface QueryFilterAnd { + and?: Record[]; +} diff --git a/src/api/types/QueryFilterCondition.ts b/src/api/types/QueryFilterCondition.ts new file mode 100644 index 000000000..b1b7eb10e --- /dev/null +++ b/src/api/types/QueryFilterCondition.ts @@ -0,0 +1,7 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface QueryFilterCondition { + member?: string; + operator?: string; + values?: string[]; +} diff --git a/src/api/types/QueryFilterOr.ts b/src/api/types/QueryFilterOr.ts new file mode 100644 index 000000000..fad6096ba --- /dev/null +++ b/src/api/types/QueryFilterOr.ts @@ -0,0 +1,5 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface QueryFilterOr { + or?: Record[]; +} diff --git a/src/api/types/ReportingError.ts b/src/api/types/ReportingError.ts new file mode 100644 index 000000000..6a4a4ebaf --- /dev/null +++ b/src/api/types/ReportingError.ts @@ -0,0 +1,8 @@ +// This file was auto-generated by Fern from our API Definition. + +/** + * Error envelope returned by the Reporting API. Note: a 200 response whose body is `{ "error": "Continue wait" }` is not a failure — it signals that a long-running query is still processing and the request should be retried. + */ +export interface ReportingError { + error: string; +} diff --git a/src/api/types/ResponseFormat.ts b/src/api/types/ResponseFormat.ts new file mode 100644 index 000000000..5783d563a --- /dev/null +++ b/src/api/types/ResponseFormat.ts @@ -0,0 +1,9 @@ +// This file was auto-generated by Fern from our API Definition. + +/** Output format of the result `data` payload. `default` returns row-oriented data (`LoadResultDataRow`); `compact` returns a `{ members, dataset }` object with rows of primitive arrays (`LoadResultDataCompact`); `columnar` returns a `{ members, columns }` object with one primitive array per member (`LoadResultDataColumnar`). */ +export const ResponseFormat = { + Default: "default", + Compact: "compact", + Columnar: "columnar", +} as const; +export type ResponseFormat = (typeof ResponseFormat)[keyof typeof ResponseFormat]; diff --git a/src/api/types/Segment.ts b/src/api/types/Segment.ts new file mode 100644 index 000000000..0e8e637a8 --- /dev/null +++ b/src/api/types/Segment.ts @@ -0,0 +1,9 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface Segment { + name: string; + title: string; + description?: string; + shortTitle: string; + meta?: Record; +} diff --git a/src/api/types/SimpleFormat.ts b/src/api/types/SimpleFormat.ts new file mode 100644 index 000000000..e2e682fc8 --- /dev/null +++ b/src/api/types/SimpleFormat.ts @@ -0,0 +1,12 @@ +// This file was auto-generated by Fern from our API Definition. + +/** Simple format */ +export const SimpleFormat = { + Percent: "percent", + Currency: "currency", + Number: "number", + ImageUrl: "imageUrl", + Id: "id", + Link: "link", +} as const; +export type SimpleFormat = (typeof SimpleFormat)[keyof typeof SimpleFormat]; diff --git a/src/api/types/TimeDimension.ts b/src/api/types/TimeDimension.ts new file mode 100644 index 000000000..d5e46cc81 --- /dev/null +++ b/src/api/types/TimeDimension.ts @@ -0,0 +1,7 @@ +// This file was auto-generated by Fern from our API Definition. + +export interface TimeDimension { + dimension: string; + granularity?: string; + dateRange?: Record; +} diff --git a/src/api/types/index.ts b/src/api/types/index.ts index 1626e884f..8cb2912c3 100644 --- a/src/api/types/index.ts +++ b/src/api/types/index.ts @@ -115,6 +115,7 @@ export * from "./BusinessBookingProfileCustomerTimezoneChoice"; export * from "./BusinessHours"; export * from "./BusinessHoursPeriod"; export * from "./BuyNowPayLaterDetails"; +export * from "./CacheMode"; export * from "./CalculateLoyaltyPointsResponse"; export * from "./CalculateOrderResponse"; export * from "./CancelBookingResponse"; @@ -332,6 +333,9 @@ export * from "./CreateTransferOrderLineData"; export * from "./CreateTransferOrderResponse"; export * from "./CreateVendorResponse"; export * from "./CreateWebhookSubscriptionResponse"; +export * from "./Cube"; +export * from "./CubeJoin"; +export * from "./CubeType"; export * from "./Currency"; export * from "./CustomAttribute"; export * from "./CustomAttributeDefinition"; @@ -393,6 +397,8 @@ export * from "./CustomerUpdatedEvent"; export * from "./CustomerUpdatedEventData"; export * from "./CustomerUpdatedEventObject"; export * from "./CustomField"; +export * from "./CustomNumericFormat"; +export * from "./CustomTimeFormat"; export * from "./DataCollectionOptions"; export * from "./DataCollectionOptionsInputType"; export * from "./DateRange"; @@ -453,6 +459,9 @@ export * from "./DeviceMetadata"; export * from "./DeviceStatus"; export * from "./DeviceStatusCategory"; export * from "./DigitalWalletDetails"; +export * from "./Dimension"; +export * from "./DimensionGranularity"; +export * from "./DimensionOrder"; export * from "./DisableBankAccountResponse"; export * from "./DisableCardResponse"; export * from "./DisableEventsResponse"; @@ -506,6 +515,9 @@ export * from "./FelicaDetails"; export * from "./FelicaDetailsFelicaBrand"; export * from "./FilterValue"; export * from "./FloatNumberRange"; +export * from "./Folder"; +export * from "./Format"; +export * from "./FormatDescription"; export * from "./Fulfillment"; export * from "./FulfillmentDeliveryDetails"; export * from "./FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType"; @@ -644,6 +656,7 @@ export * from "./GiftCardType"; export * from "./GiftCardUpdatedEvent"; export * from "./GiftCardUpdatedEventData"; export * from "./GiftCardUpdatedEventObject"; +export * from "./Hierarchy"; export * from "./InventoryAdjustment"; export * from "./InventoryAdjustmentGroup"; export * from "./InventoryAlertType"; @@ -708,6 +721,8 @@ export * from "./JobCreatedEventObject"; export * from "./JobUpdatedEvent"; export * from "./JobUpdatedEventData"; export * from "./JobUpdatedEventObject"; +export * from "./JoinHint"; +export * from "./JoinSubquery"; export * from "./LaborScheduledShiftCreatedEvent"; export * from "./LaborScheduledShiftCreatedEventData"; export * from "./LaborScheduledShiftCreatedEventObject"; @@ -737,6 +752,7 @@ export * from "./LaborTimecardUpdatedEventData"; export * from "./LaborTimecardUpdatedEventObject"; export * from "./LightningDetails"; export * from "./LinkCustomerToGiftCardResponse"; +export * from "./LinkFormat"; export * from "./ListBankAccountsResponse"; export * from "./ListBookingCustomAttributeDefinitionsResponse"; export * from "./ListBookingCustomAttributesResponse"; @@ -790,6 +806,13 @@ export * from "./ListTransactionsResponse"; export * from "./ListWebhookEventTypesResponse"; export * from "./ListWebhookSubscriptionsResponse"; export * from "./ListWorkweekConfigsResponse"; +export * from "./LoadResponse"; +export * from "./LoadResult"; +export * from "./LoadResultAnnotation"; +export * from "./LoadResultData"; +export * from "./LoadResultDataColumnar"; +export * from "./LoadResultDataCompact"; +export * from "./LoadResultDataRow"; export * from "./Location"; export * from "./LocationBookingProfile"; export * from "./LocationCapability"; @@ -881,6 +904,7 @@ export * from "./LoyaltyPromotionUpdatedEventData"; export * from "./LoyaltyPromotionUpdatedEventObject"; export * from "./LoyaltyReward"; export * from "./LoyaltyRewardStatus"; +export * from "./Measure"; export * from "./MeasurementUnit"; export * from "./MeasurementUnitArea"; export * from "./MeasurementUnitCustom"; @@ -905,8 +929,10 @@ export * from "./MerchantSettingsUpdatedEvent"; export * from "./MerchantSettingsUpdatedEventData"; export * from "./MerchantSettingsUpdatedEventObject"; export * from "./MerchantStatus"; +export * from "./MetadataResponse"; export * from "./ModifierLocationOverrides"; export * from "./Money"; +export * from "./NestedFolder"; export * from "./OauthAuthorizationRevokedEvent"; export * from "./OauthAuthorizationRevokedEventData"; export * from "./OauthAuthorizationRevokedEventObject"; @@ -1043,6 +1069,11 @@ export * from "./ProductType"; export * from "./PublishInvoiceResponse"; export * from "./PublishScheduledShiftResponse"; export * from "./QrCodeOptions"; +export * from "./Query"; +export * from "./QueryFilter"; +export * from "./QueryFilterAnd"; +export * from "./QueryFilterCondition"; +export * from "./QueryFilterOr"; export * from "./QuickPay"; export * from "./Range"; export * from "./ReceiptOptions"; @@ -1062,6 +1093,8 @@ export * from "./RefundUpdatedEventObject"; export * from "./RegisterDomainResponse"; export * from "./RegisterDomainResponseStatus"; export * from "./RemoveGroupFromCustomerResponse"; +export * from "./ReportingError"; +export * from "./ResponseFormat"; export * from "./ResumeSubscriptionResponse"; export * from "./RetrieveBookingCustomAttributeDefinitionResponse"; export * from "./RetrieveBookingCustomAttributeResponse"; @@ -1140,6 +1173,7 @@ export * from "./SearchVendorsRequestFilter"; export * from "./SearchVendorsRequestSort"; export * from "./SearchVendorsRequestSortField"; export * from "./SearchVendorsResponse"; +export * from "./Segment"; export * from "./SegmentFilter"; export * from "./SelectOption"; export * from "./SelectOptions"; @@ -1156,6 +1190,7 @@ export * from "./ShiftWorkdayMatcher"; export * from "./ShippingFee"; export * from "./SignatureImage"; export * from "./SignatureOptions"; +export * from "./SimpleFormat"; export * from "./Site"; export * from "./Snippet"; export * from "./SortOrder"; @@ -1260,6 +1295,7 @@ export * from "./TimecardStatus"; export * from "./TimecardWage"; export * from "./TimecardWorkday"; export * from "./TimecardWorkdayMatcher"; +export * from "./TimeDimension"; export * from "./TimeRange"; export * from "./TipSettings"; export * from "./Transaction"; diff --git a/src/serialization/resources/index.ts b/src/serialization/resources/index.ts index ecbcb65e8..fd5b35663 100644 --- a/src/serialization/resources/index.ts +++ b/src/serialization/resources/index.ts @@ -38,6 +38,8 @@ export * as payments from "./payments"; export * from "./payments/client/requests"; export * as refunds from "./refunds"; export * from "./refunds/client/requests"; +export * as reporting from "./reporting"; +export * from "./reporting/client/requests"; export * as snippets from "./snippets"; export * from "./snippets/client/requests"; export * as subscriptions from "./subscriptions"; diff --git a/src/serialization/resources/reporting/client/index.ts b/src/serialization/resources/reporting/client/index.ts new file mode 100644 index 000000000..415726b7f --- /dev/null +++ b/src/serialization/resources/reporting/client/index.ts @@ -0,0 +1 @@ +export * from "./requests"; diff --git a/src/serialization/resources/reporting/client/requests/LoadRequest.ts b/src/serialization/resources/reporting/client/requests/LoadRequest.ts new file mode 100644 index 000000000..21f456e06 --- /dev/null +++ b/src/serialization/resources/reporting/client/requests/LoadRequest.ts @@ -0,0 +1,22 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../../../../api/index"; +import * as core from "../../../../../core"; +import type * as serializers from "../../../../index"; +import { CacheMode } from "../../../../types/CacheMode"; +import { Query } from "../../../../types/Query"; + +export const LoadRequest: core.serialization.Schema = + core.serialization.object({ + queryType: core.serialization.string().optional(), + cache: CacheMode.optional(), + query: Query.optional(), + }); + +export declare namespace LoadRequest { + export interface Raw { + queryType?: string | null; + cache?: CacheMode.Raw | null; + query?: Query.Raw | null; + } +} diff --git a/src/serialization/resources/reporting/client/requests/index.ts b/src/serialization/resources/reporting/client/requests/index.ts new file mode 100644 index 000000000..ec6eb0118 --- /dev/null +++ b/src/serialization/resources/reporting/client/requests/index.ts @@ -0,0 +1 @@ +export { LoadRequest } from "./LoadRequest"; diff --git a/src/serialization/resources/reporting/index.ts b/src/serialization/resources/reporting/index.ts new file mode 100644 index 000000000..5ec76921e --- /dev/null +++ b/src/serialization/resources/reporting/index.ts @@ -0,0 +1 @@ +export * from "./client"; diff --git a/src/serialization/types/CacheMode.ts b/src/serialization/types/CacheMode.ts new file mode 100644 index 000000000..f7fbb9b2c --- /dev/null +++ b/src/serialization/types/CacheMode.ts @@ -0,0 +1,12 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const CacheMode: core.serialization.Schema = + core.serialization.enum_(["stale-if-slow", "stale-while-revalidate", "must-revalidate", "no-cache"]); + +export declare namespace CacheMode { + export type Raw = "stale-if-slow" | "stale-while-revalidate" | "must-revalidate" | "no-cache"; +} diff --git a/src/serialization/types/Cube.ts b/src/serialization/types/Cube.ts new file mode 100644 index 000000000..267764de9 --- /dev/null +++ b/src/serialization/types/Cube.ts @@ -0,0 +1,45 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { CubeJoin } from "./CubeJoin"; +import { CubeType } from "./CubeType"; +import { Dimension } from "./Dimension"; +import { Folder } from "./Folder"; +import { Hierarchy } from "./Hierarchy"; +import { Measure } from "./Measure"; +import { NestedFolder } from "./NestedFolder"; +import { Segment } from "./Segment"; + +export const Cube: core.serialization.ObjectSchema = core.serialization.object({ + name: core.serialization.string(), + title: core.serialization.string().optional(), + type: CubeType, + meta: core.serialization.record(core.serialization.string(), core.serialization.unknown()).optional(), + description: core.serialization.string().optional(), + measures: core.serialization.list(Measure), + dimensions: core.serialization.list(Dimension), + segments: core.serialization.list(Segment), + joins: core.serialization.list(CubeJoin).optional(), + folders: core.serialization.list(Folder).optional(), + nestedFolders: core.serialization.list(NestedFolder).optional(), + hierarchies: core.serialization.list(Hierarchy).optional(), +}); + +export declare namespace Cube { + export interface Raw { + name: string; + title?: string | null; + type: CubeType.Raw; + meta?: Record | null; + description?: string | null; + measures: Measure.Raw[]; + dimensions: Dimension.Raw[]; + segments: Segment.Raw[]; + joins?: CubeJoin.Raw[] | null; + folders?: Folder.Raw[] | null; + nestedFolders?: NestedFolder.Raw[] | null; + hierarchies?: Hierarchy.Raw[] | null; + } +} diff --git a/src/serialization/types/CubeJoin.ts b/src/serialization/types/CubeJoin.ts new file mode 100644 index 000000000..741d09338 --- /dev/null +++ b/src/serialization/types/CubeJoin.ts @@ -0,0 +1,18 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const CubeJoin: core.serialization.ObjectSchema = + core.serialization.object({ + name: core.serialization.string(), + relationship: core.serialization.string(), + }); + +export declare namespace CubeJoin { + export interface Raw { + name: string; + relationship: string; + } +} diff --git a/src/serialization/types/CubeType.ts b/src/serialization/types/CubeType.ts new file mode 100644 index 000000000..5472da5ab --- /dev/null +++ b/src/serialization/types/CubeType.ts @@ -0,0 +1,14 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const CubeType: core.serialization.Schema = core.serialization.enum_([ + "cube", + "view", +]); + +export declare namespace CubeType { + export type Raw = "cube" | "view"; +} diff --git a/src/serialization/types/CustomNumericFormat.ts b/src/serialization/types/CustomNumericFormat.ts new file mode 100644 index 000000000..bd3b8bdf4 --- /dev/null +++ b/src/serialization/types/CustomNumericFormat.ts @@ -0,0 +1,22 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const CustomNumericFormat: core.serialization.ObjectSchema< + serializers.CustomNumericFormat.Raw, + Square.CustomNumericFormat +> = core.serialization.object({ + type: core.serialization.stringLiteral("custom-numeric"), + value: core.serialization.string(), + alias: core.serialization.string().optional(), +}); + +export declare namespace CustomNumericFormat { + export interface Raw { + type: "custom-numeric"; + value: string; + alias?: string | null; + } +} diff --git a/src/serialization/types/CustomTimeFormat.ts b/src/serialization/types/CustomTimeFormat.ts new file mode 100644 index 000000000..c851637c6 --- /dev/null +++ b/src/serialization/types/CustomTimeFormat.ts @@ -0,0 +1,20 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const CustomTimeFormat: core.serialization.ObjectSchema< + serializers.CustomTimeFormat.Raw, + Square.CustomTimeFormat +> = core.serialization.object({ + type: core.serialization.stringLiteral("custom-time"), + value: core.serialization.string(), +}); + +export declare namespace CustomTimeFormat { + export interface Raw { + type: "custom-time"; + value: string; + } +} diff --git a/src/serialization/types/Dimension.ts b/src/serialization/types/Dimension.ts new file mode 100644 index 000000000..29abe545e --- /dev/null +++ b/src/serialization/types/Dimension.ts @@ -0,0 +1,44 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { DimensionGranularity } from "./DimensionGranularity"; +import { DimensionOrder } from "./DimensionOrder"; +import { Format } from "./Format"; +import { FormatDescription } from "./FormatDescription"; + +export const Dimension: core.serialization.ObjectSchema = + core.serialization.object({ + name: core.serialization.string(), + title: core.serialization.string().optional(), + shortTitle: core.serialization.string().optional(), + description: core.serialization.string().optional(), + type: core.serialization.string(), + aliasMember: core.serialization.string().optional(), + granularities: core.serialization.list(DimensionGranularity).optional(), + meta: core.serialization.record(core.serialization.string(), core.serialization.unknown()).optional(), + format: Format.optional(), + formatDescription: FormatDescription.optional(), + currency: core.serialization.string().optional(), + order: DimensionOrder.optional(), + key: core.serialization.string().optional(), + }); + +export declare namespace Dimension { + export interface Raw { + name: string; + title?: string | null; + shortTitle?: string | null; + description?: string | null; + type: string; + aliasMember?: string | null; + granularities?: DimensionGranularity.Raw[] | null; + meta?: Record | null; + format?: Format.Raw | null; + formatDescription?: FormatDescription.Raw | null; + currency?: string | null; + order?: DimensionOrder.Raw | null; + key?: string | null; + } +} diff --git a/src/serialization/types/DimensionGranularity.ts b/src/serialization/types/DimensionGranularity.ts new file mode 100644 index 000000000..17279cc55 --- /dev/null +++ b/src/serialization/types/DimensionGranularity.ts @@ -0,0 +1,28 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const DimensionGranularity: core.serialization.ObjectSchema< + serializers.DimensionGranularity.Raw, + Square.DimensionGranularity +> = core.serialization.object({ + name: core.serialization.string(), + title: core.serialization.string(), + interval: core.serialization.string().optional(), + sql: core.serialization.string().optional(), + offset: core.serialization.string().optional(), + origin: core.serialization.string().optional(), +}); + +export declare namespace DimensionGranularity { + export interface Raw { + name: string; + title: string; + interval?: string | null; + sql?: string | null; + offset?: string | null; + origin?: string | null; + } +} diff --git a/src/serialization/types/DimensionOrder.ts b/src/serialization/types/DimensionOrder.ts new file mode 100644 index 000000000..5c3dafee9 --- /dev/null +++ b/src/serialization/types/DimensionOrder.ts @@ -0,0 +1,12 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const DimensionOrder: core.serialization.Schema = + core.serialization.enum_(["asc", "desc"]); + +export declare namespace DimensionOrder { + export type Raw = "asc" | "desc"; +} diff --git a/src/serialization/types/Folder.ts b/src/serialization/types/Folder.ts new file mode 100644 index 000000000..273418d56 --- /dev/null +++ b/src/serialization/types/Folder.ts @@ -0,0 +1,19 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const Folder: core.serialization.ObjectSchema = core.serialization.object( + { + name: core.serialization.string(), + members: core.serialization.list(core.serialization.string()), + }, +); + +export declare namespace Folder { + export interface Raw { + name: string; + members: string[]; + } +} diff --git a/src/serialization/types/Format.ts b/src/serialization/types/Format.ts new file mode 100644 index 000000000..70742a34b --- /dev/null +++ b/src/serialization/types/Format.ts @@ -0,0 +1,16 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { CustomNumericFormat } from "./CustomNumericFormat"; +import { CustomTimeFormat } from "./CustomTimeFormat"; +import { LinkFormat } from "./LinkFormat"; +import { SimpleFormat } from "./SimpleFormat"; + +export const Format: core.serialization.Schema = + core.serialization.undiscriminatedUnion([SimpleFormat, LinkFormat, CustomTimeFormat, CustomNumericFormat]); + +export declare namespace Format { + export type Raw = SimpleFormat.Raw | LinkFormat.Raw | CustomTimeFormat.Raw | CustomNumericFormat.Raw; +} diff --git a/src/serialization/types/FormatDescription.ts b/src/serialization/types/FormatDescription.ts new file mode 100644 index 000000000..49b24b82d --- /dev/null +++ b/src/serialization/types/FormatDescription.ts @@ -0,0 +1,22 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const FormatDescription: core.serialization.ObjectSchema< + serializers.FormatDescription.Raw, + Square.FormatDescription +> = core.serialization.object({ + name: core.serialization.string(), + specifier: core.serialization.string(), + currency: core.serialization.string().optional(), +}); + +export declare namespace FormatDescription { + export interface Raw { + name: string; + specifier: string; + currency?: string | null; + } +} diff --git a/src/serialization/types/Hierarchy.ts b/src/serialization/types/Hierarchy.ts new file mode 100644 index 000000000..3073b5460 --- /dev/null +++ b/src/serialization/types/Hierarchy.ts @@ -0,0 +1,22 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const Hierarchy: core.serialization.ObjectSchema = + core.serialization.object({ + name: core.serialization.string(), + aliasMember: core.serialization.string().optional(), + title: core.serialization.string().optional(), + levels: core.serialization.list(core.serialization.string()), + }); + +export declare namespace Hierarchy { + export interface Raw { + name: string; + aliasMember?: string | null; + title?: string | null; + levels: string[]; + } +} diff --git a/src/serialization/types/JoinHint.ts b/src/serialization/types/JoinHint.ts new file mode 100644 index 000000000..8d0283416 --- /dev/null +++ b/src/serialization/types/JoinHint.ts @@ -0,0 +1,13 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const JoinHint: core.serialization.Schema = core.serialization.list( + core.serialization.string(), +); + +export declare namespace JoinHint { + export type Raw = string[]; +} diff --git a/src/serialization/types/JoinSubquery.ts b/src/serialization/types/JoinSubquery.ts new file mode 100644 index 000000000..dbe48db85 --- /dev/null +++ b/src/serialization/types/JoinSubquery.ts @@ -0,0 +1,22 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const JoinSubquery: core.serialization.ObjectSchema = + core.serialization.object({ + sql: core.serialization.string(), + on: core.serialization.string(), + joinType: core.serialization.string(), + alias: core.serialization.string(), + }); + +export declare namespace JoinSubquery { + export interface Raw { + sql: string; + on: string; + joinType: string; + alias: string; + } +} diff --git a/src/serialization/types/LinkFormat.ts b/src/serialization/types/LinkFormat.ts new file mode 100644 index 000000000..2d40b6de1 --- /dev/null +++ b/src/serialization/types/LinkFormat.ts @@ -0,0 +1,18 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const LinkFormat: core.serialization.ObjectSchema = + core.serialization.object({ + label: core.serialization.string(), + type: core.serialization.stringLiteral("link"), + }); + +export declare namespace LinkFormat { + export interface Raw { + label: string; + type: "link"; + } +} diff --git a/src/serialization/types/LoadResponse.ts b/src/serialization/types/LoadResponse.ts new file mode 100644 index 000000000..7cbe8dbcc --- /dev/null +++ b/src/serialization/types/LoadResponse.ts @@ -0,0 +1,23 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { LoadResult } from "./LoadResult"; + +export const LoadResponse: core.serialization.ObjectSchema = + core.serialization.object({ + pivotQuery: core.serialization.record(core.serialization.string(), core.serialization.unknown()).optional(), + slowQuery: core.serialization.boolean().optional(), + queryType: core.serialization.string().optional(), + results: core.serialization.list(LoadResult), + }); + +export declare namespace LoadResponse { + export interface Raw { + pivotQuery?: Record | null; + slowQuery?: boolean | null; + queryType?: string | null; + results: LoadResult.Raw[]; + } +} diff --git a/src/serialization/types/LoadResult.ts b/src/serialization/types/LoadResult.ts new file mode 100644 index 000000000..1e3249532 --- /dev/null +++ b/src/serialization/types/LoadResult.ts @@ -0,0 +1,28 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { LoadResultAnnotation } from "./LoadResultAnnotation"; +import { LoadResultData } from "./LoadResultData"; + +export const LoadResult: core.serialization.ObjectSchema = + core.serialization.object({ + dataSource: core.serialization.string().optional(), + annotation: LoadResultAnnotation, + data: LoadResultData, + refreshKeyValues: core.serialization + .list(core.serialization.record(core.serialization.string(), core.serialization.unknown())) + .optional(), + lastRefreshTime: core.serialization.string().optional(), + }); + +export declare namespace LoadResult { + export interface Raw { + dataSource?: string | null; + annotation: LoadResultAnnotation.Raw; + data: LoadResultData.Raw; + refreshKeyValues?: Record[] | null; + lastRefreshTime?: string | null; + } +} diff --git a/src/serialization/types/LoadResultAnnotation.ts b/src/serialization/types/LoadResultAnnotation.ts new file mode 100644 index 000000000..b01bbc53e --- /dev/null +++ b/src/serialization/types/LoadResultAnnotation.ts @@ -0,0 +1,24 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const LoadResultAnnotation: core.serialization.ObjectSchema< + serializers.LoadResultAnnotation.Raw, + Square.LoadResultAnnotation +> = core.serialization.object({ + measures: core.serialization.record(core.serialization.string(), core.serialization.unknown()), + dimensions: core.serialization.record(core.serialization.string(), core.serialization.unknown()), + segments: core.serialization.record(core.serialization.string(), core.serialization.unknown()), + timeDimensions: core.serialization.record(core.serialization.string(), core.serialization.unknown()), +}); + +export declare namespace LoadResultAnnotation { + export interface Raw { + measures: Record; + dimensions: Record; + segments: Record; + timeDimensions: Record; + } +} diff --git a/src/serialization/types/LoadResultData.ts b/src/serialization/types/LoadResultData.ts new file mode 100644 index 000000000..673acd859 --- /dev/null +++ b/src/serialization/types/LoadResultData.ts @@ -0,0 +1,15 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { LoadResultDataColumnar } from "./LoadResultDataColumnar"; +import { LoadResultDataCompact } from "./LoadResultDataCompact"; +import { LoadResultDataRow } from "./LoadResultDataRow"; + +export const LoadResultData: core.serialization.Schema = + core.serialization.undiscriminatedUnion([LoadResultDataRow, LoadResultDataCompact, LoadResultDataColumnar]); + +export declare namespace LoadResultData { + export type Raw = LoadResultDataRow.Raw | LoadResultDataCompact.Raw | LoadResultDataColumnar.Raw; +} diff --git a/src/serialization/types/LoadResultDataColumnar.ts b/src/serialization/types/LoadResultDataColumnar.ts new file mode 100644 index 000000000..546a738b3 --- /dev/null +++ b/src/serialization/types/LoadResultDataColumnar.ts @@ -0,0 +1,20 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const LoadResultDataColumnar: core.serialization.ObjectSchema< + serializers.LoadResultDataColumnar.Raw, + Square.LoadResultDataColumnar +> = core.serialization.object({ + members: core.serialization.list(core.serialization.string()), + columns: core.serialization.list(core.serialization.list(core.serialization.unknown())), +}); + +export declare namespace LoadResultDataColumnar { + export interface Raw { + members: string[]; + columns: unknown[][]; + } +} diff --git a/src/serialization/types/LoadResultDataCompact.ts b/src/serialization/types/LoadResultDataCompact.ts new file mode 100644 index 000000000..09137ca61 --- /dev/null +++ b/src/serialization/types/LoadResultDataCompact.ts @@ -0,0 +1,20 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const LoadResultDataCompact: core.serialization.ObjectSchema< + serializers.LoadResultDataCompact.Raw, + Square.LoadResultDataCompact +> = core.serialization.object({ + members: core.serialization.list(core.serialization.string()), + dataset: core.serialization.list(core.serialization.list(core.serialization.unknown())), +}); + +export declare namespace LoadResultDataCompact { + export interface Raw { + members: string[]; + dataset: unknown[][]; + } +} diff --git a/src/serialization/types/LoadResultDataRow.ts b/src/serialization/types/LoadResultDataRow.ts new file mode 100644 index 000000000..49b20d720 --- /dev/null +++ b/src/serialization/types/LoadResultDataRow.ts @@ -0,0 +1,12 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const LoadResultDataRow: core.serialization.Schema = + core.serialization.list(core.serialization.record(core.serialization.string(), core.serialization.unknown())); + +export declare namespace LoadResultDataRow { + export type Raw = Record[]; +} diff --git a/src/serialization/types/Measure.ts b/src/serialization/types/Measure.ts new file mode 100644 index 000000000..1ba203e9e --- /dev/null +++ b/src/serialization/types/Measure.ts @@ -0,0 +1,38 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { Format } from "./Format"; +import { FormatDescription } from "./FormatDescription"; + +export const Measure: core.serialization.ObjectSchema = + core.serialization.object({ + name: core.serialization.string(), + title: core.serialization.string().optional(), + shortTitle: core.serialization.string().optional(), + description: core.serialization.string().optional(), + type: core.serialization.string(), + aggType: core.serialization.string().optional(), + meta: core.serialization.record(core.serialization.string(), core.serialization.unknown()).optional(), + format: Format.optional(), + formatDescription: FormatDescription.optional(), + currency: core.serialization.string().optional(), + aliasMember: core.serialization.string().optional(), + }); + +export declare namespace Measure { + export interface Raw { + name: string; + title?: string | null; + shortTitle?: string | null; + description?: string | null; + type: string; + aggType?: string | null; + meta?: Record | null; + format?: Format.Raw | null; + formatDescription?: FormatDescription.Raw | null; + currency?: string | null; + aliasMember?: string | null; + } +} diff --git a/src/serialization/types/MetadataResponse.ts b/src/serialization/types/MetadataResponse.ts new file mode 100644 index 000000000..696e26971 --- /dev/null +++ b/src/serialization/types/MetadataResponse.ts @@ -0,0 +1,21 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { Cube } from "./Cube"; + +export const MetadataResponse: core.serialization.ObjectSchema< + serializers.MetadataResponse.Raw, + Square.MetadataResponse +> = core.serialization.object({ + cubes: core.serialization.list(Cube).optional(), + compilerId: core.serialization.string().optional(), +}); + +export declare namespace MetadataResponse { + export interface Raw { + cubes?: Cube.Raw[] | null; + compilerId?: string | null; + } +} diff --git a/src/serialization/types/NestedFolder.ts b/src/serialization/types/NestedFolder.ts new file mode 100644 index 000000000..5d082eb12 --- /dev/null +++ b/src/serialization/types/NestedFolder.ts @@ -0,0 +1,18 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const NestedFolder: core.serialization.ObjectSchema = + core.serialization.object({ + name: core.serialization.string(), + members: core.serialization.list(core.serialization.string()), + }); + +export declare namespace NestedFolder { + export interface Raw { + name: string; + members: string[]; + } +} diff --git a/src/serialization/types/Query.ts b/src/serialization/types/Query.ts new file mode 100644 index 000000000..ab93352fe --- /dev/null +++ b/src/serialization/types/Query.ts @@ -0,0 +1,44 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { JoinHint } from "./JoinHint"; +import { JoinSubquery } from "./JoinSubquery"; +import { QueryFilter } from "./QueryFilter"; +import { ResponseFormat } from "./ResponseFormat"; +import { TimeDimension } from "./TimeDimension"; + +export const Query: core.serialization.ObjectSchema = core.serialization.object({ + measures: core.serialization.list(core.serialization.string()).optional(), + dimensions: core.serialization.list(core.serialization.string()).optional(), + segments: core.serialization.list(core.serialization.string()).optional(), + timeDimensions: core.serialization.list(TimeDimension).optional(), + order: core.serialization.list(core.serialization.list(core.serialization.string())).optional(), + limit: core.serialization.number().optional(), + offset: core.serialization.number().optional(), + filters: core.serialization.list(QueryFilter).optional(), + ungrouped: core.serialization.boolean().optional(), + subqueryJoins: core.serialization.list(JoinSubquery).optional(), + joinHints: core.serialization.list(JoinHint).optional(), + timezone: core.serialization.string().optional(), + responseFormat: ResponseFormat.optional(), +}); + +export declare namespace Query { + export interface Raw { + measures?: string[] | null; + dimensions?: string[] | null; + segments?: string[] | null; + timeDimensions?: TimeDimension.Raw[] | null; + order?: string[][] | null; + limit?: number | null; + offset?: number | null; + filters?: QueryFilter.Raw[] | null; + ungrouped?: boolean | null; + subqueryJoins?: JoinSubquery.Raw[] | null; + joinHints?: JoinHint.Raw[] | null; + timezone?: string | null; + responseFormat?: ResponseFormat.Raw | null; + } +} diff --git a/src/serialization/types/QueryFilter.ts b/src/serialization/types/QueryFilter.ts new file mode 100644 index 000000000..0562089b7 --- /dev/null +++ b/src/serialization/types/QueryFilter.ts @@ -0,0 +1,15 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; +import { QueryFilterAnd } from "./QueryFilterAnd"; +import { QueryFilterCondition } from "./QueryFilterCondition"; +import { QueryFilterOr } from "./QueryFilterOr"; + +export const QueryFilter: core.serialization.Schema = + core.serialization.undiscriminatedUnion([QueryFilterCondition, QueryFilterOr, QueryFilterAnd]); + +export declare namespace QueryFilter { + export type Raw = QueryFilterCondition.Raw | QueryFilterOr.Raw | QueryFilterAnd.Raw; +} diff --git a/src/serialization/types/QueryFilterAnd.ts b/src/serialization/types/QueryFilterAnd.ts new file mode 100644 index 000000000..49824c09d --- /dev/null +++ b/src/serialization/types/QueryFilterAnd.ts @@ -0,0 +1,18 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const QueryFilterAnd: core.serialization.ObjectSchema = + core.serialization.object({ + and: core.serialization + .list(core.serialization.record(core.serialization.string(), core.serialization.unknown())) + .optional(), + }); + +export declare namespace QueryFilterAnd { + export interface Raw { + and?: Record[] | null; + } +} diff --git a/src/serialization/types/QueryFilterCondition.ts b/src/serialization/types/QueryFilterCondition.ts new file mode 100644 index 000000000..0abebfac5 --- /dev/null +++ b/src/serialization/types/QueryFilterCondition.ts @@ -0,0 +1,22 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const QueryFilterCondition: core.serialization.ObjectSchema< + serializers.QueryFilterCondition.Raw, + Square.QueryFilterCondition +> = core.serialization.object({ + member: core.serialization.string().optional(), + operator: core.serialization.string().optional(), + values: core.serialization.list(core.serialization.string()).optional(), +}); + +export declare namespace QueryFilterCondition { + export interface Raw { + member?: string | null; + operator?: string | null; + values?: string[] | null; + } +} diff --git a/src/serialization/types/QueryFilterOr.ts b/src/serialization/types/QueryFilterOr.ts new file mode 100644 index 000000000..1910f75a3 --- /dev/null +++ b/src/serialization/types/QueryFilterOr.ts @@ -0,0 +1,18 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const QueryFilterOr: core.serialization.ObjectSchema = + core.serialization.object({ + or: core.serialization + .list(core.serialization.record(core.serialization.string(), core.serialization.unknown())) + .optional(), + }); + +export declare namespace QueryFilterOr { + export interface Raw { + or?: Record[] | null; + } +} diff --git a/src/serialization/types/ReportingError.ts b/src/serialization/types/ReportingError.ts new file mode 100644 index 000000000..065a1ec1f --- /dev/null +++ b/src/serialization/types/ReportingError.ts @@ -0,0 +1,16 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const ReportingError: core.serialization.ObjectSchema = + core.serialization.object({ + error: core.serialization.string(), + }); + +export declare namespace ReportingError { + export interface Raw { + error: string; + } +} diff --git a/src/serialization/types/ResponseFormat.ts b/src/serialization/types/ResponseFormat.ts new file mode 100644 index 000000000..f582eabf9 --- /dev/null +++ b/src/serialization/types/ResponseFormat.ts @@ -0,0 +1,12 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const ResponseFormat: core.serialization.Schema = + core.serialization.enum_(["default", "compact", "columnar"]); + +export declare namespace ResponseFormat { + export type Raw = "default" | "compact" | "columnar"; +} diff --git a/src/serialization/types/Segment.ts b/src/serialization/types/Segment.ts new file mode 100644 index 000000000..b41e516e7 --- /dev/null +++ b/src/serialization/types/Segment.ts @@ -0,0 +1,24 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const Segment: core.serialization.ObjectSchema = + core.serialization.object({ + name: core.serialization.string(), + title: core.serialization.string(), + description: core.serialization.string().optional(), + shortTitle: core.serialization.string(), + meta: core.serialization.record(core.serialization.string(), core.serialization.unknown()).optional(), + }); + +export declare namespace Segment { + export interface Raw { + name: string; + title: string; + description?: string | null; + shortTitle: string; + meta?: Record | null; + } +} diff --git a/src/serialization/types/SimpleFormat.ts b/src/serialization/types/SimpleFormat.ts new file mode 100644 index 000000000..38457c153 --- /dev/null +++ b/src/serialization/types/SimpleFormat.ts @@ -0,0 +1,12 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const SimpleFormat: core.serialization.Schema = + core.serialization.enum_(["percent", "currency", "number", "imageUrl", "id", "link"]); + +export declare namespace SimpleFormat { + export type Raw = "percent" | "currency" | "number" | "imageUrl" | "id" | "link"; +} diff --git a/src/serialization/types/TimeDimension.ts b/src/serialization/types/TimeDimension.ts new file mode 100644 index 000000000..1fec6bb3f --- /dev/null +++ b/src/serialization/types/TimeDimension.ts @@ -0,0 +1,20 @@ +// This file was auto-generated by Fern from our API Definition. + +import type * as Square from "../../api/index"; +import * as core from "../../core"; +import type * as serializers from "../index"; + +export const TimeDimension: core.serialization.ObjectSchema = + core.serialization.object({ + dimension: core.serialization.string(), + granularity: core.serialization.string().optional(), + dateRange: core.serialization.record(core.serialization.string(), core.serialization.unknown()).optional(), + }); + +export declare namespace TimeDimension { + export interface Raw { + dimension: string; + granularity?: string | null; + dateRange?: Record | null; + } +} diff --git a/src/serialization/types/index.ts b/src/serialization/types/index.ts index 1626e884f..8cb2912c3 100644 --- a/src/serialization/types/index.ts +++ b/src/serialization/types/index.ts @@ -115,6 +115,7 @@ export * from "./BusinessBookingProfileCustomerTimezoneChoice"; export * from "./BusinessHours"; export * from "./BusinessHoursPeriod"; export * from "./BuyNowPayLaterDetails"; +export * from "./CacheMode"; export * from "./CalculateLoyaltyPointsResponse"; export * from "./CalculateOrderResponse"; export * from "./CancelBookingResponse"; @@ -332,6 +333,9 @@ export * from "./CreateTransferOrderLineData"; export * from "./CreateTransferOrderResponse"; export * from "./CreateVendorResponse"; export * from "./CreateWebhookSubscriptionResponse"; +export * from "./Cube"; +export * from "./CubeJoin"; +export * from "./CubeType"; export * from "./Currency"; export * from "./CustomAttribute"; export * from "./CustomAttributeDefinition"; @@ -393,6 +397,8 @@ export * from "./CustomerUpdatedEvent"; export * from "./CustomerUpdatedEventData"; export * from "./CustomerUpdatedEventObject"; export * from "./CustomField"; +export * from "./CustomNumericFormat"; +export * from "./CustomTimeFormat"; export * from "./DataCollectionOptions"; export * from "./DataCollectionOptionsInputType"; export * from "./DateRange"; @@ -453,6 +459,9 @@ export * from "./DeviceMetadata"; export * from "./DeviceStatus"; export * from "./DeviceStatusCategory"; export * from "./DigitalWalletDetails"; +export * from "./Dimension"; +export * from "./DimensionGranularity"; +export * from "./DimensionOrder"; export * from "./DisableBankAccountResponse"; export * from "./DisableCardResponse"; export * from "./DisableEventsResponse"; @@ -506,6 +515,9 @@ export * from "./FelicaDetails"; export * from "./FelicaDetailsFelicaBrand"; export * from "./FilterValue"; export * from "./FloatNumberRange"; +export * from "./Folder"; +export * from "./Format"; +export * from "./FormatDescription"; export * from "./Fulfillment"; export * from "./FulfillmentDeliveryDetails"; export * from "./FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType"; @@ -644,6 +656,7 @@ export * from "./GiftCardType"; export * from "./GiftCardUpdatedEvent"; export * from "./GiftCardUpdatedEventData"; export * from "./GiftCardUpdatedEventObject"; +export * from "./Hierarchy"; export * from "./InventoryAdjustment"; export * from "./InventoryAdjustmentGroup"; export * from "./InventoryAlertType"; @@ -708,6 +721,8 @@ export * from "./JobCreatedEventObject"; export * from "./JobUpdatedEvent"; export * from "./JobUpdatedEventData"; export * from "./JobUpdatedEventObject"; +export * from "./JoinHint"; +export * from "./JoinSubquery"; export * from "./LaborScheduledShiftCreatedEvent"; export * from "./LaborScheduledShiftCreatedEventData"; export * from "./LaborScheduledShiftCreatedEventObject"; @@ -737,6 +752,7 @@ export * from "./LaborTimecardUpdatedEventData"; export * from "./LaborTimecardUpdatedEventObject"; export * from "./LightningDetails"; export * from "./LinkCustomerToGiftCardResponse"; +export * from "./LinkFormat"; export * from "./ListBankAccountsResponse"; export * from "./ListBookingCustomAttributeDefinitionsResponse"; export * from "./ListBookingCustomAttributesResponse"; @@ -790,6 +806,13 @@ export * from "./ListTransactionsResponse"; export * from "./ListWebhookEventTypesResponse"; export * from "./ListWebhookSubscriptionsResponse"; export * from "./ListWorkweekConfigsResponse"; +export * from "./LoadResponse"; +export * from "./LoadResult"; +export * from "./LoadResultAnnotation"; +export * from "./LoadResultData"; +export * from "./LoadResultDataColumnar"; +export * from "./LoadResultDataCompact"; +export * from "./LoadResultDataRow"; export * from "./Location"; export * from "./LocationBookingProfile"; export * from "./LocationCapability"; @@ -881,6 +904,7 @@ export * from "./LoyaltyPromotionUpdatedEventData"; export * from "./LoyaltyPromotionUpdatedEventObject"; export * from "./LoyaltyReward"; export * from "./LoyaltyRewardStatus"; +export * from "./Measure"; export * from "./MeasurementUnit"; export * from "./MeasurementUnitArea"; export * from "./MeasurementUnitCustom"; @@ -905,8 +929,10 @@ export * from "./MerchantSettingsUpdatedEvent"; export * from "./MerchantSettingsUpdatedEventData"; export * from "./MerchantSettingsUpdatedEventObject"; export * from "./MerchantStatus"; +export * from "./MetadataResponse"; export * from "./ModifierLocationOverrides"; export * from "./Money"; +export * from "./NestedFolder"; export * from "./OauthAuthorizationRevokedEvent"; export * from "./OauthAuthorizationRevokedEventData"; export * from "./OauthAuthorizationRevokedEventObject"; @@ -1043,6 +1069,11 @@ export * from "./ProductType"; export * from "./PublishInvoiceResponse"; export * from "./PublishScheduledShiftResponse"; export * from "./QrCodeOptions"; +export * from "./Query"; +export * from "./QueryFilter"; +export * from "./QueryFilterAnd"; +export * from "./QueryFilterCondition"; +export * from "./QueryFilterOr"; export * from "./QuickPay"; export * from "./Range"; export * from "./ReceiptOptions"; @@ -1062,6 +1093,8 @@ export * from "./RefundUpdatedEventObject"; export * from "./RegisterDomainResponse"; export * from "./RegisterDomainResponseStatus"; export * from "./RemoveGroupFromCustomerResponse"; +export * from "./ReportingError"; +export * from "./ResponseFormat"; export * from "./ResumeSubscriptionResponse"; export * from "./RetrieveBookingCustomAttributeDefinitionResponse"; export * from "./RetrieveBookingCustomAttributeResponse"; @@ -1140,6 +1173,7 @@ export * from "./SearchVendorsRequestFilter"; export * from "./SearchVendorsRequestSort"; export * from "./SearchVendorsRequestSortField"; export * from "./SearchVendorsResponse"; +export * from "./Segment"; export * from "./SegmentFilter"; export * from "./SelectOption"; export * from "./SelectOptions"; @@ -1156,6 +1190,7 @@ export * from "./ShiftWorkdayMatcher"; export * from "./ShippingFee"; export * from "./SignatureImage"; export * from "./SignatureOptions"; +export * from "./SimpleFormat"; export * from "./Site"; export * from "./Snippet"; export * from "./SortOrder"; @@ -1260,6 +1295,7 @@ export * from "./TimecardStatus"; export * from "./TimecardWage"; export * from "./TimecardWorkday"; export * from "./TimecardWorkdayMatcher"; +export * from "./TimeDimension"; export * from "./TimeRange"; export * from "./TipSettings"; export * from "./Transaction"; diff --git a/src/version.ts b/src/version.ts index 46c381128..32c9f109a 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const SDK_VERSION = "44.1.0"; +export const SDK_VERSION = "44.2.0"; diff --git a/tests/wire/reporting.test.ts b/tests/wire/reporting.test.ts new file mode 100644 index 000000000..ea23752c5 --- /dev/null +++ b/tests/wire/reporting.test.ts @@ -0,0 +1,163 @@ +// This file was auto-generated by Fern from our API Definition. + +import { SquareClient } from "../../src/Client"; +import { mockServerPool } from "../mock-server/MockServerPool"; + +describe("ReportingClient", () => { + test("getMetadata", async () => { + const server = mockServerPool.createServer(); + const client = new SquareClient({ maxRetries: 0, token: "test", environment: server.baseUrl }); + + const rawResponseBody = { + cubes: [ + { + name: "name", + title: "title", + type: "cube", + meta: { key: "value" }, + description: "description", + measures: [{ name: "name", type: "type" }], + dimensions: [{ name: "name", type: "type" }], + segments: [{ name: "name", title: "title", shortTitle: "shortTitle" }], + joins: [{ name: "name", relationship: "relationship" }], + folders: [{ name: "name", members: ["members"] }], + nestedFolders: [{ name: "name", members: ["members"] }], + hierarchies: [{ name: "name", levels: ["levels"] }], + }, + ], + compilerId: "compilerId", + }; + server.mockEndpoint().get("/reporting/v1/meta").respondWith().statusCode(200).jsonBody(rawResponseBody).build(); + + const response = await client.reporting.getMetadata(); + expect(response).toEqual({ + cubes: [ + { + name: "name", + title: "title", + type: "cube", + meta: { + key: "value", + }, + description: "description", + measures: [ + { + name: "name", + type: "type", + }, + ], + dimensions: [ + { + name: "name", + type: "type", + }, + ], + segments: [ + { + name: "name", + title: "title", + shortTitle: "shortTitle", + }, + ], + joins: [ + { + name: "name", + relationship: "relationship", + }, + ], + folders: [ + { + name: "name", + members: ["members"], + }, + ], + nestedFolders: [ + { + name: "name", + members: ["members"], + }, + ], + hierarchies: [ + { + name: "name", + levels: ["levels"], + }, + ], + }, + ], + compilerId: "compilerId", + }); + }); + + test("load", async () => { + const server = mockServerPool.createServer(); + const client = new SquareClient({ maxRetries: 0, token: "test", environment: server.baseUrl }); + const rawRequestBody = {}; + const rawResponseBody = { + pivotQuery: { key: "value" }, + slowQuery: true, + queryType: "queryType", + results: [ + { + dataSource: "dataSource", + annotation: { + measures: { key: "value" }, + dimensions: { key: "value" }, + segments: { key: "value" }, + timeDimensions: { key: "value" }, + }, + data: [{ key: "value" }], + refreshKeyValues: [{ key: "value" }], + lastRefreshTime: "lastRefreshTime", + }, + ], + }; + server + .mockEndpoint() + .post("/reporting/v1/load") + .jsonBody(rawRequestBody) + .respondWith() + .statusCode(200) + .jsonBody(rawResponseBody) + .build(); + + const response = await client.reporting.load(); + expect(response).toEqual({ + pivotQuery: { + key: "value", + }, + slowQuery: true, + queryType: "queryType", + results: [ + { + dataSource: "dataSource", + annotation: { + measures: { + key: "value", + }, + dimensions: { + key: "value", + }, + segments: { + key: "value", + }, + timeDimensions: { + key: "value", + }, + }, + data: [ + { + key: "value", + }, + ], + refreshKeyValues: [ + { + key: "value", + }, + ], + lastRefreshTime: "lastRefreshTime", + }, + ], + }); + }); +}); diff --git a/yarn.lock b/yarn.lock index d5a98fc68..1a064180f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1205,9 +1205,9 @@ asynckit@^0.4.0: integrity sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q== axios@^1.8.4: - version "1.16.1" - resolved "https://registry.yarnpkg.com/axios/-/axios-1.16.1.tgz#517e29291d19d6e8cf919ff264f4fe157261ba12" - integrity sha512-caYkukvroVPO8KrzuJEb50Hm07KwfBZPEC3VeFHTsqWHvKTsy54hjJz9BS/cdaypROE2rH6xvm9mHX4fgWkr3A== + version "1.17.0" + resolved "https://registry.yarnpkg.com/axios/-/axios-1.17.0.tgz#ae5a1164a4f719942cd73c67e6a3f62d3ccb8f2b" + integrity sha512-J8SwNxprqqpbfenehxWYXE7CW+wM1BB4w3+N+g+/Wx40xM4rsLrfPmHHxSWIxJLYDgSY/HqlFPIYb2/S3rxafw== dependencies: follow-redirects "^1.16.0" form-data "^4.0.5" From b2286d5664fbeab0eea0d27abf592b9bc73dc8a6 Mon Sep 17 00:00:00 2001 From: jsklan Date: Sat, 13 Jun 2026 09:35:51 -0400 Subject: [PATCH 2/6] Add Reporting API polling wrapper + tests (FER-11257) ReportingHelper.loadAndWait wraps reporting.load with an exponential-backoff retry loop around the "Continue wait" sentinel the async /v1/load endpoint returns (HTTP 200) while a query is still computing. Exported from the package root and protected via .fernignore so regeneration won't clobber it. Tests: - tests/unit/reporting.test.ts (protected): polling logic, maxAttempts timeout, abort, and a real-serializer check that the "Continue wait" body survives deserialization as a detectable sentinel. Runnable without a live account. - tests/integration/reporting.test.ts: live smoke test. Reporting is served only from production (connect.squareup.com/reporting; sandbox 404s), so this suite targets production by default and needs a production-capable TEST_SQUARE_TOKEN. Read-only endpoints (schema discovery + queries). --- .fernignore | 1 + src/index.ts | 1 + src/wrapper/ReportingHelper.ts | 107 ++++++++++++++++++++++++++++ tests/integration/reporting.test.ts | 88 +++++++++++++++++++++++ tests/unit/reporting.test.ts | 104 +++++++++++++++++++++++++++ 5 files changed, 301 insertions(+) create mode 100644 src/wrapper/ReportingHelper.ts create mode 100644 tests/integration/reporting.test.ts create mode 100644 tests/unit/reporting.test.ts diff --git a/.fernignore b/.fernignore index 58de1ace7..d954dd95a 100644 --- a/.fernignore +++ b/.fernignore @@ -9,6 +9,7 @@ src/core/index.ts src/core/crypto tests/unit/error.test.ts tests/unit/fetcher/stream-wrappers/webpack.test.ts +tests/unit/reporting.test.ts tests/integration legacy jest.config.mjs diff --git a/src/index.ts b/src/index.ts index d972a1c40..2a3211a92 100644 --- a/src/index.ts +++ b/src/index.ts @@ -7,3 +7,4 @@ export { SquareError, SquareTimeoutError } from "./errors/index.js"; export * from "./exports.js"; export * as serialization from "./serialization/index.js"; export { WebhooksHelper } from "./wrapper/WebhooksHelper"; +export { ReportingHelper, type LoadAndWaitOptions } from "./wrapper/ReportingHelper"; diff --git a/src/wrapper/ReportingHelper.ts b/src/wrapper/ReportingHelper.ts new file mode 100644 index 000000000..28d71ae7b --- /dev/null +++ b/src/wrapper/ReportingHelper.ts @@ -0,0 +1,107 @@ +import type * as Square from "../api"; +import type { ReportingClient } from "../api/resources/reporting/client/Client"; +import type { SquareClient } from "../Client"; +import { SquareError } from "../errors"; + +/** + * Sentinel returned by the Reporting API on an HTTP 200 while a `/v1/load` + * query is still processing. It is NOT an error — the request should be retried. + * See the {@link https://developer.squareup.com/docs/reporting-api/overview Reporting API docs}. + */ +const CONTINUE_WAIT = "Continue wait"; + +export interface LoadAndWaitOptions { + /** Maximum poll attempts before giving up. Default 20. */ + maxAttempts?: number; + /** Delay before the first retry, in ms. Default 2000. */ + initialDelayMs?: number; + /** Upper bound on the backoff delay, in ms. Default 20000. */ + maxDelayMs?: number; + /** Multiplier applied to the delay after each attempt. Default 2. */ + backoffFactor?: number; + /** Aborts the poll loop (and the in-flight wait) when signalled. */ + signal?: AbortSignal; + /** Forwarded to each underlying `client.reporting.load` call. */ + requestOptions?: ReportingClient.RequestOptions; +} + +/** + * Utility to help with the {@link https://developer.squareup.com/docs/reporting-api/overview Square Reporting API}. + * + * The `/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. This helper owns that retry loop. + */ +export class ReportingHelper { + /** + * Runs a reporting query and transparently polls until it resolves, returning + * the final {@link Square.LoadResponse}. Re-sends the identical request with + * exponential backoff while the API answers "Continue wait". + * + * @param client A configured {@link SquareClient}. + * @param request The reporting query (same shape as `client.reporting.load`). + * @param options Polling/backoff configuration. + * @returns The resolved `LoadResponse` (never the "Continue wait" sentinel). + * @throws {@link SquareError} if the query does not resolve within `maxAttempts`. + */ + static async loadAndWait( + client: SquareClient, + request: Square.LoadRequest = {}, + options: LoadAndWaitOptions = {}, + ): Promise { + const { + maxAttempts = 20, + initialDelayMs = 2_000, + maxDelayMs = 20_000, + backoffFactor = 2, + signal, + requestOptions, + } = options; + + let delayMs = initialDelayMs; + for (let attempt = 1; attempt <= maxAttempts; attempt++) { + if (signal?.aborted) { + throw new SquareError({ message: "Reporting query polling was aborted." }); + } + const response = await client.reporting.load(request, requestOptions); + if (!ReportingHelper.isContinueWait(response)) { + return response; + } + if (attempt === maxAttempts) { + break; + } + await ReportingHelper.sleep(delayMs, signal); + delayMs = Math.min(delayMs * backoffFactor, maxDelayMs); + } + throw new SquareError({ + message: `Reporting query did not complete after ${maxAttempts} attempts ("${CONTINUE_WAIT}").`, + }); + } + + /** + * A "Continue wait" body parses into a `LoadResponse` (validation is skipped) + * with the `error` field preserved and `results` absent. That's the signal to retry. + */ + private static isContinueWait(response: Square.LoadResponse): boolean { + return (response as unknown as Square.ReportingError).error === CONTINUE_WAIT; + } + + private static sleep(ms: number, signal?: AbortSignal): Promise { + return new Promise((resolve, reject) => { + if (signal?.aborted) { + reject(new SquareError({ message: "Reporting query polling was aborted." })); + return; + } + const timer = setTimeout(() => { + signal?.removeEventListener("abort", onAbort); + resolve(); + }, ms); + const onAbort = () => { + clearTimeout(timer); + reject(new SquareError({ message: "Reporting query polling was aborted." })); + }; + signal?.addEventListener("abort", onAbort, { once: true }); + }); + } +} diff --git a/tests/integration/reporting.test.ts b/tests/integration/reporting.test.ts new file mode 100644 index 000000000..2c5791c89 --- /dev/null +++ b/tests/integration/reporting.test.ts @@ -0,0 +1,88 @@ +import { ReportingHelper, SquareClient, SquareEnvironment } from "../../src"; +import type * as Square from "../../src/api"; + +// The Reporting API is a beta, bespoke offering served ONLY from production +// (connect.squareup.com/reporting) — it is not routed on sandbox (returns 404 there). +// So, unlike the other integration suites (which target sandbox), this one targets +// production by default and needs a production-capable TEST_SQUARE_TOKEN. The endpoints +// are read-only (schema discovery + queries), so running them against prod is safe. +// The polling *logic* is covered without a live account in tests/unit/reporting.test.ts. +// +// Run it: +// TEST_SQUARE_TOKEN= yarn test:integration --testPathPattern reporting +// # override the host with TEST_SQUARE_BASE_URL= if reporting moves. + +function createReportingClient(): SquareClient { + const token = process.env.TEST_SQUARE_TOKEN; + if (!token) { + throw new Error("TEST_SQUARE_TOKEN must be set to run the reporting integration suite."); + } + // Reporting only exists on production; allow overriding the host via TEST_SQUARE_BASE_URL. + const baseUrl = process.env.TEST_SQUARE_BASE_URL ?? SquareEnvironment.Production; + // Make the live target unambiguous in the test output (useful when triaging CI). + console.log(`[reporting] base URL: ${baseUrl} -> ${baseUrl}/reporting/v1/{meta,load}`); + return new SquareClient({ token, baseUrl }); +} + +describe("Reporting API (live)", () => { + let client: SquareClient; + beforeAll(() => { + client = createReportingClient(); + }); + + // Resolves the first queryable measure from the live schema, e.g. "Orders.count". + async function firstMeasureName(): Promise { + const metadata = await client.reporting.getMetadata(); + const measure = metadata.cubes?.[0]?.measures?.[0]?.name; + if (!measure) { + throw new Error("No cubes/measures are available on the reporting schema for this account."); + } + return measure; + } + + it("getMetadata() returns the queryable schema (cubes + measures)", async () => { + const metadata = await client.reporting.getMetadata(); + + expect(metadata.cubes).toBeDefined(); + expect(metadata.cubes?.length ?? 0).toBeGreaterThan(0); + + // Surface the live schema so a developer can see what is queryable. + const summary = (metadata.cubes ?? []).slice(0, 5).map((cube) => ({ + cube: cube.name, + measures: (cube.measures ?? []).slice(0, 5).map((measure) => measure.name), + })); + console.log("Reporting schema (first 5 cubes):", JSON.stringify(summary, null, 2)); + }); + + it("load() returns either results or the 'Continue wait' sentinel for an in-flight query", async () => { + const measure = await firstMeasureName(); + const response = await client.reporting.load({ query: { measures: [measure] } }); + + const sentinel = (response as unknown as { error?: string }).error; + if (sentinel) { + // Documented async behavior: a still-processing query comes back as HTTP 200 + // with { "error": "Continue wait" } instead of results. + expect(sentinel).toBe("Continue wait"); + } else { + expect(response.results).toBeDefined(); + } + }); + + it( + "loadAndWait() resolves a query end-to-end without surfacing 'Continue wait'", + async () => { + const measure = await firstMeasureName(); + + const response: Square.LoadResponse = await ReportingHelper.loadAndWait( + client, + { query: { measures: [measure] } }, + { maxAttempts: 20, initialDelayMs: 2_000, maxDelayMs: 20_000 }, + ); + + // The polling helper must never hand back the raw "Continue wait" sentinel. + expect((response as unknown as { error?: string }).error).toBeUndefined(); + expect(response.results).toBeDefined(); + }, + 5 * 60_000, // polling can take minutes; override jest's default 5s timeout + ); +}); diff --git a/tests/unit/reporting.test.ts b/tests/unit/reporting.test.ts new file mode 100644 index 000000000..9a780880b --- /dev/null +++ b/tests/unit/reporting.test.ts @@ -0,0 +1,104 @@ +import type { SquareClient } from "../../src"; +import { ReportingHelper } from "../../src"; +import type * as Square from "../../src/api"; +import * as serializers from "../../src/serialization"; + +/** + * The Reporting API answers a still-processing `/v1/load` query with an HTTP 200 + * whose body is `{ "error": "Continue wait" }`. `ReportingHelper.loadAndWait` owns + * the retry loop around that sentinel. These tests exercise that loop without a + * network by scripting `client.reporting.load`, plus one test that proves the + * sentinel actually survives the generated client's deserialization. + */ + +const CONTINUE_WAIT = "Continue wait"; + +/** A `SquareClient` stub whose `reporting.load` returns a scripted sequence of responses. */ +function fakeClient(sequence: Square.LoadResponse[]): { client: SquareClient; callCount: () => number } { + let i = 0; + const client = { + reporting: { + load: async (): Promise => { + const response = sequence[Math.min(i, sequence.length - 1)]; + i += 1; + return response; + }, + }, + } as unknown as SquareClient; + return { client, callCount: () => i }; +} + +const continueWait = { error: CONTINUE_WAIT } as unknown as Square.LoadResponse; +const resolved = { results: [{ data: { "Orders.count": "128" } }] } as unknown as Square.LoadResponse; + +describe("ReportingHelper.loadAndWait", () => { + it("polls past 'Continue wait' responses and returns the resolved result", async () => { + const { client, callCount } = fakeClient([continueWait, continueWait, resolved]); + + const response = await ReportingHelper.loadAndWait( + client, + { query: { measures: ["Orders.count"] } }, + { initialDelayMs: 1, maxDelayMs: 1, maxAttempts: 5 }, + ); + + // The helper must never hand back the raw sentinel. + expect((response as unknown as { error?: string }).error).toBeUndefined(); + expect(response.results).toBeDefined(); + expect(callCount()).toBe(3); + }); + + it("returns immediately when the first response already has results", async () => { + const { client, callCount } = fakeClient([resolved]); + + const response = await ReportingHelper.loadAndWait(client, {}, { initialDelayMs: 1 }); + + expect(response.results).toBeDefined(); + expect(callCount()).toBe(1); + }); + + it("throws once maxAttempts is exhausted while still 'Continue wait'", async () => { + const { client, callCount } = fakeClient([continueWait]); // never resolves + + await expect( + ReportingHelper.loadAndWait(client, {}, { initialDelayMs: 1, maxDelayMs: 1, maxAttempts: 3 }), + ).rejects.toThrow(/did not complete after 3 attempts/); + expect(callCount()).toBe(3); + }); + + it("rejects promptly when the abort signal fires mid-poll", async () => { + const { client } = fakeClient([continueWait]); // would otherwise poll forever + const controller = new AbortController(); + + const pending = ReportingHelper.loadAndWait( + client, + {}, + { + initialDelayMs: 1_000, + maxAttempts: 10, + signal: controller.signal, + }, + ); + controller.abort(); + + await expect(pending).rejects.toThrow(/aborted/); + }); + + it("treats a real-serializer 'Continue wait' body as a retry signal, not a result", async () => { + // The crux of the design: the generated `reporting.load` parses the body with + // skipValidation + passthrough, so the `error` sentinel survives onto a + // LoadResponse-shaped object (and `results` stays absent). If this ever stops + // being true, loadAndWait would mistake "Continue wait" for a real result. + const parsed = serializers.LoadResponse.parseOrThrow( + { error: CONTINUE_WAIT }, + { + unrecognizedObjectKeys: "passthrough", + allowUnrecognizedUnionMembers: true, + allowUnrecognizedEnumValues: true, + skipValidation: true, + }, + ) as unknown as { error?: string; results?: unknown }; + + expect(parsed.error).toBe(CONTINUE_WAIT); + expect(parsed.results).toBeUndefined(); + }); +}); From 9565fd5be01dbf0c4754d8bb6c561932049bdbbf Mon Sep 17 00:00:00 2001 From: jsklan Date: Sat, 13 Jun 2026 10:22:25 -0400 Subject: [PATCH 3/6] Gate reporting integration suite behind TEST_SQUARE_REPORTING (FER-11257) Reporting is served only from production and needs a prod, reporting-provisioned token; CI's token is sandbox-only and 401s against prod, turning the integration job red. Gate the live suite behind TEST_SQUARE_REPORTING so it skips by default (CI green) while staying runnable on demand against a real prod account. Default target stays production. Polling logic remains covered by tests/unit/reporting.test.ts. --- tests/integration/reporting.test.ts | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/tests/integration/reporting.test.ts b/tests/integration/reporting.test.ts index 2c5791c89..91ba31549 100644 --- a/tests/integration/reporting.test.ts +++ b/tests/integration/reporting.test.ts @@ -3,14 +3,17 @@ import type * as Square from "../../src/api"; // The Reporting API is a beta, bespoke offering served ONLY from production // (connect.squareup.com/reporting) — it is not routed on sandbox (returns 404 there). -// So, unlike the other integration suites (which target sandbox), this one targets -// production by default and needs a production-capable TEST_SQUARE_TOKEN. The endpoints -// are read-only (schema discovery + queries), so running them against prod is safe. -// The polling *logic* is covered without a live account in tests/unit/reporting.test.ts. +// Validating it live therefore needs a production, reporting-provisioned TEST_SQUARE_TOKEN. +// CI's token is sandbox-only (it 401s against prod), so this suite is gated behind +// TEST_SQUARE_REPORTING and skips by default — keeping CI green. The endpoints are +// read-only (schema discovery + queries). The polling *logic* is covered without a live +// account in tests/unit/reporting.test.ts. // -// Run it: -// TEST_SQUARE_TOKEN= yarn test:integration --testPathPattern reporting +// Run it against a real prod account: +// TEST_SQUARE_REPORTING=1 TEST_SQUARE_TOKEN= \ +// yarn test:integration --testPathPattern reporting // # override the host with TEST_SQUARE_BASE_URL= if reporting moves. +const describeReporting = process.env.TEST_SQUARE_REPORTING ? describe : describe.skip; function createReportingClient(): SquareClient { const token = process.env.TEST_SQUARE_TOKEN; @@ -24,7 +27,7 @@ function createReportingClient(): SquareClient { return new SquareClient({ token, baseUrl }); } -describe("Reporting API (live)", () => { +describeReporting("Reporting API (live)", () => { let client: SquareClient; beforeAll(() => { client = createReportingClient(); From cfdd483338a4d01f0470b1af661aa6ff46b5ab64 Mon Sep 17 00:00:00 2001 From: jsklan Date: Sat, 13 Jun 2026 10:28:05 -0400 Subject: [PATCH 4/6] Raise integration test timeout to 30s to absorb slow sandbox calls (FER-11257) The customers 'add to group' integration test intermittently exceeds jest's 5s default under CI load, turning the integration job red. Bump the integration project's testTimeout to 30s (jest.config.mjs is .fernignore-protected). --- jest.config.mjs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/jest.config.mjs b/jest.config.mjs index 9cb402935..056266f51 100644 --- a/jest.config.mjs +++ b/jest.config.mjs @@ -42,6 +42,9 @@ export default { displayName: "integration", preset: "ts-jest", testEnvironment: "node", + // Integration tests hit the live sandbox; multi-step flows (e.g. customers + // "add to group") can exceed jest's 5s default under CI load. Give them headroom. + testTimeout: 30000, moduleNameMapper: { "^(\.{1,2}/.*)\.js$": "$1", }, From 58701a17556d91bd6399942319e3b411848e53e6 Mon Sep 17 00:00:00 2001 From: jsklan Date: Sat, 13 Jun 2026 10:34:13 -0400 Subject: [PATCH 5/6] Document Reporting API + loadAndWait polling helper in README (FER-11257) Add a '## Reporting API' section (preserved by the README generator) covering getMetadata schema discovery, the async 'Continue wait' polling behavior, and the ReportingHelper.loadAndWait helper, linking to Square's Reporting API docs. Also add a Table of Contents entry. --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/README.md b/README.md index ae4ec5b2a..762712015 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ The Square TypeScript library provides convenient access to the Square APIs from - [File Uploads](#file-uploads) - [Pagination](#pagination) - [Webhook Signature Verification](#webhook-signature-verification) +- [Reporting API](#reporting-api) - [Advanced](#advanced) - [Additional Headers](#additional-headers) - [Additional Query String Parameters](#additional-query-string-parameters) @@ -270,6 +271,63 @@ const isValid = WebhooksHelper.verifySignature({ }); ``` +## Reporting API + +The [Reporting API](https://developer.squareup.com/docs/reporting-api/overview) lets you query +aggregated reporting data. Call `reporting.getMetadata` first to discover the available cubes, +measures, and dimensions, then run a query with `reporting.load`. + +```ts +import { SquareClient } from "square"; + +const client = new SquareClient({ token: "YOUR_TOKEN" }); + +// Discover what you can query. +const metadata = await client.reporting.getMetadata(); + +// Run a query against the discovered schema. +const response = await client.reporting.load({ + query: { measures: ["Orders.count"] }, +}); +``` + +`load` is asynchronous: while a query is still being computed, the API returns an HTTP `200` whose +body is `{ "error": "Continue wait" }` instead of results, and the client is expected to re-send the +identical request — with backoff — until the results are ready. The `ReportingHelper.loadAndWait` +utility owns that polling loop for you and returns the resolved results (never the `"Continue wait"` +sentinel): + +```ts +import { ReportingHelper, SquareClient } from "square"; + +const client = new SquareClient({ token: "YOUR_TOKEN" }); + +const response = await ReportingHelper.loadAndWait(client, { + query: { measures: ["Orders.count"] }, +}); + +console.log(response.results); +``` + +By default it polls up to 20 times with exponential backoff (2s → 20s). Tune the behavior — and +pass an `AbortSignal` to cancel — via the options argument: + +```ts +const controller = new AbortController(); + +const response = await ReportingHelper.loadAndWait( + client, + { query: { measures: ["Orders.count"] } }, + { + maxAttempts: 10, // default 20 + initialDelayMs: 1000, // default 2000 + maxDelayMs: 20000, // default 20000 + backoffFactor: 2, // default 2 + signal: controller.signal, + }, +); +``` + ## Advanced ### Additional Headers From 13e04ff561c34522be2fd394626d5b978168aad8 Mon Sep 17 00:00:00 2001 From: Fern Support <126544928+fern-support@users.noreply.github.com> Date: Mon, 15 Jun 2026 19:49:46 -0400 Subject: [PATCH 6/6] test(reporting): source live token from TEST_SQUARE_REPORTING (prod) --- .github/workflows/integration.yml | 1 + tests/integration/reporting.test.ts | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.yml index b0a3673a1..bd8f2ba65 100644 --- a/.github/workflows/integration.yml +++ b/.github/workflows/integration.yml @@ -6,6 +6,7 @@ jobs: integration: env: TEST_SQUARE_TOKEN: ${{ secrets.TEST_SQUARE_TOKEN }} + TEST_SQUARE_REPORTING: ${{ secrets.TEST_SQUARE_REPORTING }} runs-on: ubuntu-latest steps: - name: Checkout repo diff --git a/tests/integration/reporting.test.ts b/tests/integration/reporting.test.ts index 91ba31549..87a0be62d 100644 --- a/tests/integration/reporting.test.ts +++ b/tests/integration/reporting.test.ts @@ -3,22 +3,22 @@ import type * as Square from "../../src/api"; // The Reporting API is a beta, bespoke offering served ONLY from production // (connect.squareup.com/reporting) — it is not routed on sandbox (returns 404 there). -// Validating it live therefore needs a production, reporting-provisioned TEST_SQUARE_TOKEN. -// CI's token is sandbox-only (it 401s against prod), so this suite is gated behind +// Validating it live therefore needs a production, reporting-provisioned access token. +// CI's sandbox token is unrelated (it 401s against prod), so this suite is gated behind // TEST_SQUARE_REPORTING and skips by default — keeping CI green. The endpoints are // read-only (schema discovery + queries). The polling *logic* is covered without a live // account in tests/unit/reporting.test.ts. // // Run it against a real prod account: -// TEST_SQUARE_REPORTING=1 TEST_SQUARE_TOKEN= \ +// TEST_SQUARE_REPORTING= \ // yarn test:integration --testPathPattern reporting // # override the host with TEST_SQUARE_BASE_URL= if reporting moves. const describeReporting = process.env.TEST_SQUARE_REPORTING ? describe : describe.skip; function createReportingClient(): SquareClient { - const token = process.env.TEST_SQUARE_TOKEN; + const token = process.env.TEST_SQUARE_REPORTING; if (!token) { - throw new Error("TEST_SQUARE_TOKEN must be set to run the reporting integration suite."); + throw new Error("TEST_SQUARE_REPORTING must be set to run the reporting integration suite."); } // Reporting only exists on production; allow overriding the host via TEST_SQUARE_BASE_URL. const baseUrl = process.env.TEST_SQUARE_BASE_URL ?? SquareEnvironment.Production;