@paid-ai/paid-node 1.8.0 → 2.0.0

package/dist/cjs/api/resources/signals/client/Client.js

@@ -231,7 +231,80 @@ class Signals {
         });
     }
     /**
-     * Create multiple signals (usage events) in a single request. Each signal must include a customer attribution (either customerId or externalCustomerId) and a product attribution (either productId or externalProductId).
+     * Fetch up to 500 ingested signals (usage events) by ID in one request, each with the data payload submitted at ingest. Use it to resolve the `signalId` values on a page of credit transactions, or the signals behind one run or ticket, instead of calling `GET /api/v2/signals/{id}` once per signal. Signals are returned in request order; IDs that match nothing in your organization are listed under `notFound` rather than failing the request. This is a read-only operation: it requires the `read:usage` scope and is not available to customer API keys.
+     *
+     * @param {Paid.SignalLookupRequest} request
+     * @param {Signals.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.TooManyRequestsError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.signals.getSignalsByIds({
+     *         ids: ["6890b0e2a6f2c30012f0a1b3", "6890b0e2a6f2c30012f0a1b4"]
+     *     })
+     */
+    getSignalsByIds(request, requestOptions) {
+        return core.HttpResponsePromise.fromPromise(this.__getSignalsByIds(request, requestOptions));
+    }
+    __getSignalsByIds(request, requestOptions) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g, _h;
+            const _headers = (0, headers_js_1.mergeHeaders)((_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, (0, headers_js_1.mergeOnlyDefinedHeaders)({ Authorization: yield this._getAuthorizationHeader() }), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
+            const _response = yield core.fetcher({
+                url: core.url.join((_c = (_b = (yield core.Supplier.get(this._options.baseUrl))) !== null && _b !== void 0 ? _b : (yield core.Supplier.get(this._options.environment))) !== null && _c !== void 0 ? _c : environments.PaidEnvironment.Default, "signals/lookup"),
+                method: "POST",
+                headers: _headers,
+                contentType: "application/json",
+                queryParameters: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams,
+                requestType: "json",
+                body: request,
+                timeoutMs: ((_f = (_d = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _d !== void 0 ? _d : (_e = this._options) === null || _e === void 0 ? void 0 : _e.timeoutInSeconds) !== null && _f !== void 0 ? _f : 60) * 1000,
+                maxRetries: (_g = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _g !== void 0 ? _g : (_h = this._options) === null || _h === void 0 ? void 0 : _h.maxRetries,
+                abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
+            });
+            if (_response.ok) {
+                return { data: _response.body, rawResponse: _response.rawResponse };
+            }
+            if (_response.error.reason === "status-code") {
+                switch (_response.error.statusCode) {
+                    case 400:
+                        throw new Paid.BadRequestError(_response.error.body, _response.rawResponse);
+                    case 403:
+                        throw new Paid.ForbiddenError(_response.error.body, _response.rawResponse);
+                    case 429:
+                        throw new Paid.TooManyRequestsError(_response.error.body, _response.rawResponse);
+                    case 500:
+                        throw new Paid.InternalServerError(_response.error.body, _response.rawResponse);
+                    default:
+                        throw new errors.PaidError({
+                            statusCode: _response.error.statusCode,
+                            body: _response.error.body,
+                            rawResponse: _response.rawResponse,
+                        });
+                }
+            }
+            switch (_response.error.reason) {
+                case "non-json":
+                    throw new errors.PaidError({
+                        statusCode: _response.error.statusCode,
+                        body: _response.error.rawBody,
+                        rawResponse: _response.rawResponse,
+                    });
+                case "timeout":
+                    throw new errors.PaidTimeoutError("Timeout exceeded when calling POST /signals/lookup.");
+                case "unknown":
+                    throw new errors.PaidError({
+                        message: _response.error.errorMessage,
+                        rawResponse: _response.rawResponse,
+                    });
+            }
+        });
+    }
+    /**
+     * Create multiple signals (usage events) in a single request. Each signal names its customer (`customerId` or `externalCustomerId`; an alias of the customer resolves too), its customer unit (`externalCustomerUnitId`: the unit's key, or an alias that points at a unit), or both, plus an optional product attribution (`productId` or `externalProductId`). A unit alone derives the customer from the unit. A unit sent with a customer must belong to it, else the batch is refused with `400 CUSTOMER_UNIT_MISMATCH`. A unit is never named by Paid's unit id. A key or alias that matches nothing is stored without a customer, keeping the id, so it can be pointed at a unit later. An identifier is matched as a unit key first, then a customer external id, then an alias. Unit attribution is enabled per organization: where it is not, a `customerUnit` sent next to a `customer` is accepted and ignored rather than checked, as before, while a unit named alone still derives its customer. Authenticate with your organization API key, or with a customer API key (prefixed `paid_ck_live_` or `paid_ck_test_`, created with `POST /api/v2/customers/{id}/api-keys`) so a customer's own runtime can report its usage without holding your organization key. A customer API key can call this endpoint only, and only for its own customer: if any signal names another customer, or one Paid does not know, the whole batch is refused with `403` `CUSTOMER_MISMATCH` and nothing is stored. Its idempotency keys are scoped to that customer. See [Send signals with a customer API key](/documentation/signals/send-signals-with-a-customer-api-key).
      *
      * @param {Paid.BulkSignalsRequest} request
      * @param {Signals.RequestOptions} requestOptions - Request-specific configuration.
@@ -244,10 +317,24 @@ class Signals {
      * @example
      *     await client.signals.createSignals({
      *         signals: [{
-     *                 eventName: "eventName",
+     *                 eventName: "email_sent",
      *                 customer: {
-     *                     customerId: "customerId"
-     *                 }
+     *                     externalCustomerId: "acme-corp"
+     *                 },
+     *                 attribution: {
+     *                     externalProductId: "email-agent"
+     *                 },
+     *                 timestamp: "2026-01-31T23:00:00Z",
+     *                 data: {
+     *                     "recipients": 3
+     *                 },
+     *                 idempotencyKey: "email_sent_msg_8f3a2c"
+     *             }, {
+     *                 eventName: "email_sent",
+     *                 customerUnit: {
+     *                     externalCustomerUnitId: "acme-marketing"
+     *                 },
+     *                 idempotencyKey: "email_sent_msg_9b41d7"
      *             }]
      *     })
      */
@@ -308,6 +395,304 @@ class Signals {
             }
         });
     }
+    /**
+     * Produces a usage summary file: one row per customer per month, with columns broken down by the signal payload fields you name. Choose `format` to get JSON or a wide CSV; JSON is the default. The export runs in the background, so this returns immediately with a pending export and the file appears on it once it succeeds. Give `spec` to describe the columns, or `copyFrom` with an earlier export's id to reuse that export's columns over a new window. The spec is stored on the export, so an old file can always be explained by the export that produced it. Signals are bucketed by month in UTC on their effective timestamp, the same basis billing uses, so the totals reconcile with invoices. One export runs per organization at a time.
+     *
+     * @param {Paid.CreateSignalSummaryExportRequest} request
+     * @param {Signals.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.ConflictError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.signals.createSignalSummaryExport({
+     *         spec: {
+     *             name: "Monthly workflow usage",
+     *             signalNames: [{
+     *                     name: "workflow_run",
+     *                     group: "Workflow runs",
+     *                     slug: "runs"
+     *                 }],
+     *             dimensions: [{
+     *                     kind: "bands",
+     *                     path: "steps",
+     *                     appliesTo: ["workflow_run"],
+     *                     brackets: [{
+     *                             from: 1,
+     *                             upTo: 10,
+     *                             slug: "1_10_steps",
+     *                             group: "1-10 steps"
+     *                         }, {
+     *                             upTo: null,
+     *                             slug: "11_plus_steps",
+     *                             group: "11+ steps"
+     *                         }]
+     *                 }],
+     *             measures: [{
+     *                     fn: "count"
+     *                 }]
+     *         },
+     *         from: "2026-01-01",
+     *         to: "2026-04-01",
+     *         format: "csv"
+     *     })
+     */
+    createSignalSummaryExport(request, requestOptions) {
+        return core.HttpResponsePromise.fromPromise(this.__createSignalSummaryExport(request, requestOptions));
+    }
+    __createSignalSummaryExport(request, requestOptions) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g, _h;
+            const _headers = (0, headers_js_1.mergeHeaders)((_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, (0, headers_js_1.mergeOnlyDefinedHeaders)({ Authorization: yield this._getAuthorizationHeader() }), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
+            const _response = yield core.fetcher({
+                url: core.url.join((_c = (_b = (yield core.Supplier.get(this._options.baseUrl))) !== null && _b !== void 0 ? _b : (yield core.Supplier.get(this._options.environment))) !== null && _c !== void 0 ? _c : environments.PaidEnvironment.Default, "signals/summary/batch/"),
+                method: "POST",
+                headers: _headers,
+                contentType: "application/json",
+                queryParameters: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams,
+                requestType: "json",
+                body: request,
+                timeoutMs: ((_f = (_d = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _d !== void 0 ? _d : (_e = this._options) === null || _e === void 0 ? void 0 : _e.timeoutInSeconds) !== null && _f !== void 0 ? _f : 60) * 1000,
+                maxRetries: (_g = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _g !== void 0 ? _g : (_h = this._options) === null || _h === void 0 ? void 0 : _h.maxRetries,
+                abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
+            });
+            if (_response.ok) {
+                return { data: _response.body, rawResponse: _response.rawResponse };
+            }
+            if (_response.error.reason === "status-code") {
+                switch (_response.error.statusCode) {
+                    case 400:
+                        throw new Paid.BadRequestError(_response.error.body, _response.rawResponse);
+                    case 403:
+                        throw new Paid.ForbiddenError(_response.error.body, _response.rawResponse);
+                    case 404:
+                        throw new Paid.NotFoundError(_response.error.body, _response.rawResponse);
+                    case 409:
+                        throw new Paid.ConflictError(_response.error.body, _response.rawResponse);
+                    case 500:
+                        throw new Paid.InternalServerError(_response.error.body, _response.rawResponse);
+                    default:
+                        throw new errors.PaidError({
+                            statusCode: _response.error.statusCode,
+                            body: _response.error.body,
+                            rawResponse: _response.rawResponse,
+                        });
+                }
+            }
+            switch (_response.error.reason) {
+                case "non-json":
+                    throw new errors.PaidError({
+                        statusCode: _response.error.statusCode,
+                        body: _response.error.rawBody,
+                        rawResponse: _response.rawResponse,
+                    });
+                case "timeout":
+                    throw new errors.PaidTimeoutError("Timeout exceeded when calling POST /signals/summary/batch/.");
+                case "unknown":
+                    throw new errors.PaidError({
+                        message: _response.error.errorMessage,
+                        rawResponse: _response.rawResponse,
+                    });
+            }
+        });
+    }
+    /**
+     * Returns one export with its status and the shape it ran. While it is succeeded and unexpired, each read issues a fresh short-lived download link.
+     *
+     * @param {Paid.GetSignalSummaryExportRequest} request
+     * @param {Signals.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.signals.getSignalSummaryExport({
+     *         id: "sse_5pZa1Kd8Nqx"
+     *     })
+     */
+    getSignalSummaryExport(request, requestOptions) {
+        return core.HttpResponsePromise.fromPromise(this.__getSignalSummaryExport(request, requestOptions));
+    }
+    __getSignalSummaryExport(request, requestOptions) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g, _h;
+            const { id } = request;
+            const _headers = (0, headers_js_1.mergeHeaders)((_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, (0, headers_js_1.mergeOnlyDefinedHeaders)({ Authorization: yield this._getAuthorizationHeader() }), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
+            const _response = yield core.fetcher({
+                url: core.url.join((_c = (_b = (yield core.Supplier.get(this._options.baseUrl))) !== null && _b !== void 0 ? _b : (yield core.Supplier.get(this._options.environment))) !== null && _c !== void 0 ? _c : environments.PaidEnvironment.Default, `signals/summary/batch/${core.url.encodePathParam(id)}`),
+                method: "GET",
+                headers: _headers,
+                queryParameters: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams,
+                timeoutMs: ((_f = (_d = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _d !== void 0 ? _d : (_e = this._options) === null || _e === void 0 ? void 0 : _e.timeoutInSeconds) !== null && _f !== void 0 ? _f : 60) * 1000,
+                maxRetries: (_g = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _g !== void 0 ? _g : (_h = this._options) === null || _h === void 0 ? void 0 : _h.maxRetries,
+                abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
+            });
+            if (_response.ok) {
+                return { data: _response.body, rawResponse: _response.rawResponse };
+            }
+            if (_response.error.reason === "status-code") {
+                switch (_response.error.statusCode) {
+                    case 400:
+                        throw new Paid.BadRequestError(_response.error.body, _response.rawResponse);
+                    case 403:
+                        throw new Paid.ForbiddenError(_response.error.body, _response.rawResponse);
+                    case 404:
+                        throw new Paid.NotFoundError(_response.error.body, _response.rawResponse);
+                    case 500:
+                        throw new Paid.InternalServerError(_response.error.body, _response.rawResponse);
+                    default:
+                        throw new errors.PaidError({
+                            statusCode: _response.error.statusCode,
+                            body: _response.error.body,
+                            rawResponse: _response.rawResponse,
+                        });
+                }
+            }
+            switch (_response.error.reason) {
+                case "non-json":
+                    throw new errors.PaidError({
+                        statusCode: _response.error.statusCode,
+                        body: _response.error.rawBody,
+                        rawResponse: _response.rawResponse,
+                    });
+                case "timeout":
+                    throw new errors.PaidTimeoutError("Timeout exceeded when calling GET /signals/summary/batch/{id}.");
+                case "unknown":
+                    throw new errors.PaidError({
+                        message: _response.error.errorMessage,
+                        rawResponse: _response.rawResponse,
+                    });
+            }
+        });
+    }
+    /**
+     * Counts signals into period buckets. Use it to chart signal volume over time, split by signal name or by a signal-payload key such as team_id.
+     *
+     * Signals count against their effective timestamp in UTC. This is the same basis billing uses, so these figures reconcile with an invoice.
+     *
+     * The endpoint reads a pre-aggregated hourly rollup, not the raw signals. An hour is therefore the finest interval. One request may span at most 250 periods.
+     *
+     * A grouped request keeps the 100 groups with the most signals. It sums the rest under the key "other". Each period total stays complete, but a group inside "other" loses its own figure. Read groups.truncated to learn how many groups lost it. Zero means every group kept its own figure.
+     *
+     * Results are paged with limit and cursor. A page is never truncated in silence.
+     *
+     * To download the series as a file, call this endpoint over HTTP with format=csv. It returns the same points as a text/csv table with a single header row. A CSV cannot carry a cursor, so a result that does not fit one page returns 400 rather than a file that is missing rows.
+     *
+     * For a wide per-customer spreadsheet over arbitrary payload fields, use the batch export at /signals/summary/batch instead.
+     *
+     * @param {Paid.GetSignalSummaryRequest} request
+     * @param {Signals.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.RequestTimeoutError}
+     * @throws {@link Paid.TooManyRequestsError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.signals.getSignalSummary({
+     *         startDate: "2026-08-01",
+     *         endDate: "2026-08-31",
+     *         interval: "day",
+     *         groupBy: "signalName",
+     *         limit: 1000
+     *     })
+     */
+    getSignalSummary(request, requestOptions) {
+        return core.HttpResponsePromise.fromPromise(this.__getSignalSummary(request, requestOptions));
+    }
+    __getSignalSummary(request, requestOptions) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g, _h;
+            const { startDate, endDate, interval, customerId, externalCustomerId, signalNames, groupBy, dimensionKey, limit, cursor, } = request;
+            const _queryParams = {};
+            _queryParams.startDate = startDate;
+            _queryParams.endDate = endDate;
+            _queryParams.interval = interval;
+            if (customerId != null) {
+                _queryParams.customerId = customerId;
+            }
+            if (externalCustomerId != null) {
+                _queryParams.externalCustomerId = externalCustomerId;
+            }
+            if (signalNames != null) {
+                if (Array.isArray(signalNames)) {
+                    _queryParams.signalNames = signalNames.map((item) => item);
+                }
+                else {
+                    _queryParams.signalNames = signalNames;
+                }
+            }
+            if (groupBy != null) {
+                _queryParams.groupBy = groupBy;
+            }
+            if (dimensionKey != null) {
+                _queryParams.dimensionKey = dimensionKey;
+            }
+            if (limit != null) {
+                _queryParams.limit = limit.toString();
+            }
+            if (cursor != null) {
+                _queryParams.cursor = cursor;
+            }
+            const _headers = (0, headers_js_1.mergeHeaders)((_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, (0, headers_js_1.mergeOnlyDefinedHeaders)({ Authorization: yield this._getAuthorizationHeader() }), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
+            const _response = yield core.fetcher({
+                url: core.url.join((_c = (_b = (yield core.Supplier.get(this._options.baseUrl))) !== null && _b !== void 0 ? _b : (yield core.Supplier.get(this._options.environment))) !== null && _c !== void 0 ? _c : environments.PaidEnvironment.Default, "signals/summary/"),
+                method: "GET",
+                headers: _headers,
+                queryParameters: Object.assign(Object.assign({}, _queryParams), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams),
+                timeoutMs: ((_f = (_d = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _d !== void 0 ? _d : (_e = this._options) === null || _e === void 0 ? void 0 : _e.timeoutInSeconds) !== null && _f !== void 0 ? _f : 60) * 1000,
+                maxRetries: (_g = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _g !== void 0 ? _g : (_h = this._options) === null || _h === void 0 ? void 0 : _h.maxRetries,
+                abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
+            });
+            if (_response.ok) {
+                return { data: _response.body, rawResponse: _response.rawResponse };
+            }
+            if (_response.error.reason === "status-code") {
+                switch (_response.error.statusCode) {
+                    case 400:
+                        throw new Paid.BadRequestError(_response.error.body, _response.rawResponse);
+                    case 403:
+                        throw new Paid.ForbiddenError(_response.error.body, _response.rawResponse);
+                    case 404:
+                        throw new Paid.NotFoundError(_response.error.body, _response.rawResponse);
+                    case 408:
+                        throw new Paid.RequestTimeoutError(_response.error.body, _response.rawResponse);
+                    case 429:
+                        throw new Paid.TooManyRequestsError(_response.error.body, _response.rawResponse);
+                    case 500:
+                        throw new Paid.InternalServerError(_response.error.body, _response.rawResponse);
+                    default:
+                        throw new errors.PaidError({
+                            statusCode: _response.error.statusCode,
+                            body: _response.error.body,
+                            rawResponse: _response.rawResponse,
+                        });
+                }
+            }
+            switch (_response.error.reason) {
+                case "non-json":
+                    throw new errors.PaidError({
+                        statusCode: _response.error.statusCode,
+                        body: _response.error.rawBody,
+                        rawResponse: _response.rawResponse,
+                    });
+                case "timeout":
+                    throw new errors.PaidTimeoutError("Timeout exceeded when calling GET /signals/summary/.");
+                case "unknown":
+                    throw new errors.PaidError({
+                        message: _response.error.errorMessage,
+                        rawResponse: _response.rawResponse,
+                    });
+            }
+        });
+    }
     _getAuthorizationHeader() {
         return __awaiter(this, void 0, void 0, function* () {
             return `Bearer ${yield core.Supplier.get(this._options.token)}`;

package/dist/cjs/api/resources/signals/client/requests/BulkSignalsRequest.d.ts

@@ -3,10 +3,24 @@ import type * as Paid from "../../../../index.js";
  * @example
  *     {
  *         signals: [{
- *                 eventName: "eventName",
+ *                 eventName: "email_sent",
  *                 customer: {
- *                     customerId: "customerId"
- *                 }
+ *                     externalCustomerId: "acme-corp"
+ *                 },
+ *                 attribution: {
+ *                     externalProductId: "email-agent"
+ *                 },
+ *                 timestamp: "2026-01-31T23:00:00Z",
+ *                 data: {
+ *                     "recipients": 3
+ *                 },
+ *                 idempotencyKey: "email_sent_msg_8f3a2c"
+ *             }, {
+ *                 eventName: "email_sent",
+ *                 customerUnit: {
+ *                     externalCustomerUnitId: "acme-marketing"
+ *                 },
+ *                 idempotencyKey: "email_sent_msg_9b41d7"
  *             }]
  *     }
  */

package/dist/cjs/api/resources/signals/client/requests/CreateSignalSummaryExportRequest.d.ts

@@ -0,0 +1,56 @@
+import type * as Paid from "../../../../index.js";
+/**
+ * @example
+ *     {
+ *         spec: {
+ *             name: "Monthly workflow usage",
+ *             signalNames: [{
+ *                     name: "workflow_run",
+ *                     group: "Workflow runs",
+ *                     slug: "runs"
+ *                 }],
+ *             dimensions: [{
+ *                     kind: "bands",
+ *                     path: "steps",
+ *                     appliesTo: ["workflow_run"],
+ *                     brackets: [{
+ *                             from: 1,
+ *                             upTo: 10,
+ *                             slug: "1_10_steps",
+ *                             group: "1-10 steps"
+ *                         }, {
+ *                             upTo: null,
+ *                             slug: "11_plus_steps",
+ *                             group: "11+ steps"
+ *                         }]
+ *                 }],
+ *             measures: [{
+ *                     fn: "count"
+ *                 }]
+ *         },
+ *         from: "2026-01-01",
+ *         to: "2026-04-01",
+ *         format: "csv"
+ *     }
+ */
+export interface CreateSignalSummaryExportRequest {
+    spec?: Paid.SignalSummarySpecInput;
+    /** Reuse the shape of an earlier export, so a monthly run produces the same columns without restating them. Give this or spec, not both. */
+    copyFrom?: string;
+    /** Start of the window, inclusive, snapped down to a period start. Cannot be earlier than 2025-09-01. */
+    from: string;
+    /** End of the window, exclusive, snapped down to a period start. */
+    to: string;
+    /** Restrict the file to these customers. Accepts Paid IDs, UUIDs, or your external IDs. Omit for every customer. */
+    customerIds?: string[];
+    /** Format of the produced file. `json` gives the columns and one object per customer per month; `csv` gives the wide spreadsheet with three header rows. */
+    format?: CreateSignalSummaryExportRequest.Format;
+}
+export declare namespace CreateSignalSummaryExportRequest {
+    /** Format of the produced file. `json` gives the columns and one object per customer per month; `csv` gives the wide spreadsheet with three header rows. */
+    const Format: {
+        readonly Json: "json";
+        readonly Csv: "csv";
+    };
+    type Format = (typeof Format)[keyof typeof Format];
+}

package/dist/cjs/api/resources/signals/client/requests/CreateSignalSummaryExportRequest.js

@@ -0,0 +1,12 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateSignalSummaryExportRequest = void 0;
+var CreateSignalSummaryExportRequest;
+(function (CreateSignalSummaryExportRequest) {
+    /** Format of the produced file. `json` gives the columns and one object per customer per month; `csv` gives the wide spreadsheet with three header rows. */
+    CreateSignalSummaryExportRequest.Format = {
+        Json: "json",
+        Csv: "csv",
+    };
+})(CreateSignalSummaryExportRequest || (exports.CreateSignalSummaryExportRequest = CreateSignalSummaryExportRequest = {}));

package/dist/cjs/api/resources/signals/client/requests/GetSignalSummaryExportRequest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @example
+ *     {
+ *         id: "sse_5pZa1Kd8Nqx"
+ *     }
+ */
+export interface GetSignalSummaryExportRequest {
+    id: string;
+}

package/dist/cjs/api/resources/signals/client/requests/GetSignalSummaryExportRequest.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/resources/signals/client/requests/GetSignalSummaryRequest.d.ts

@@ -0,0 +1,45 @@
+import type * as Paid from "../../../../index.js";
+/**
+ * @example
+ *     {
+ *         startDate: "2026-08-01",
+ *         endDate: "2026-08-31",
+ *         interval: "day",
+ *         groupBy: "signalName",
+ *         limit: 1000
+ *     }
+ */
+export interface GetSignalSummaryRequest {
+    /** Window start, inclusive. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters. */
+    startDate: string;
+    /** Window end, inclusive — a date-only value means through the end of that UTC day. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters. */
+    endDate: string;
+    /**
+     * Period size. Buckets align to UTC hours, calendar days, ISO weeks that start on Monday, or calendar months. An hour is the finest period available.
+     *
+     * The first and last bucket report bounds clipped to your window.
+     *
+     * A request may span at most 250 periods. That is about 10 days at hour, 8 months at day, and 20 years at month. A longer window returns 400 WINDOW_TOO_LARGE.
+     */
+    interval: Paid.GetSignalSummaryRequestInterval;
+    /** Narrow the summary to one customer. Accepts a Paid customer ID or, as a fallback, your external customer ID. Mutually exclusive with externalCustomerId. Omit both to summarize every customer. */
+    customerId?: string;
+    /** Your external customer ID. Mutually exclusive with customerId. */
+    externalCustomerId?: string;
+    /** Narrow the summary to these signal names. Repeat the parameter for more than one. Omit to count every signal. */
+    signalNames?: string | string[];
+    /**
+     * Split each period into one series per group. signalName groups by the signal's name. dimension groups by a signal-payload key named in dimensionKey — signals per team, for example. Omit for one total per period.
+     *
+     * A grouped request keeps the 100 groups with the most signals. It sums the rest under the key "other".
+     *
+     * Each period total stays complete, but a group inside "other" loses its own figure. Read groups.truncated to learn how many groups lost it. To name every group, narrow the request with signalNames, customerId, or a shorter window.
+     */
+    groupBy?: Paid.GetSignalSummaryRequestGroupBy;
+    /** The signal-payload key to group by. Required when groupBy is dimension; rejected otherwise. The key must be one your organization has declared for grouping — an undeclared key is refused rather than answered by a full scan. A signal whose payload lacks the key, or holds it empty, groups under an empty groupKey. */
+    dimensionKey?: string;
+    /** Maximum points to return in this page. The response is never silently truncated: when more points exist, hasMore is true and nextCursor is set. */
+    limit?: number;
+    /** Continue from a previous response's nextCursor. Every other parameter must be unchanged. */
+    cursor?: string;
+}

package/dist/cjs/api/resources/signals/client/requests/GetSignalSummaryRequest.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/resources/signals/client/requests/SignalLookupRequest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @example
+ *     {
+ *         ids: ["6890b0e2a6f2c30012f0a1b3", "6890b0e2a6f2c30012f0a1b4"]
+ *     }
+ */
+export interface SignalLookupRequest {
+    /** Signal IDs to fetch, up to 500 per request. Duplicates are collapsed. For example the `signalId` values from a page of `GET /api/v2/credits/transactions`. */
+    ids: string[];
+}

package/dist/cjs/api/resources/signals/client/requests/SignalLookupRequest.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/resources/signals/client/requests/index.d.ts

@@ -1,3 +1,7 @@
 export type { BulkSignalsRequest } from "./BulkSignalsRequest.js";
+export type { CreateSignalSummaryExportRequest } from "./CreateSignalSummaryExportRequest.js";
 export type { GetSignalByIdRequest } from "./GetSignalByIdRequest.js";
+export type { GetSignalSummaryExportRequest } from "./GetSignalSummaryExportRequest.js";
+export type { GetSignalSummaryRequest } from "./GetSignalSummaryRequest.js";
 export type { ListSignalsRequest } from "./ListSignalsRequest.js";
+export type { SignalLookupRequest } from "./SignalLookupRequest.js";

package/dist/cjs/api/resources/signals/index.d.ts

@@ -1 +1,2 @@
 export * from "./client/index.js";
+export * from "./types/index.js";

package/dist/cjs/api/resources/signals/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./client/index.js"), exports);
+__exportStar(require("./types/index.js"), exports);

package/dist/cjs/api/resources/signals/types/GetSignalSummaryRequestGroupBy.d.ts

@@ -0,0 +1,5 @@
+export declare const GetSignalSummaryRequestGroupBy: {
+    readonly SignalName: "signalName";
+    readonly Dimension: "dimension";
+};
+export type GetSignalSummaryRequestGroupBy = (typeof GetSignalSummaryRequestGroupBy)[keyof typeof GetSignalSummaryRequestGroupBy];

package/dist/cjs/api/resources/signals/types/GetSignalSummaryRequestGroupBy.js

@@ -0,0 +1,8 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetSignalSummaryRequestGroupBy = void 0;
+exports.GetSignalSummaryRequestGroupBy = {
+    SignalName: "signalName",
+    Dimension: "dimension",
+};

package/dist/cjs/api/resources/signals/types/GetSignalSummaryRequestInterval.d.ts

@@ -0,0 +1,7 @@
+export declare const GetSignalSummaryRequestInterval: {
+    readonly Hour: "hour";
+    readonly Day: "day";
+    readonly Week: "week";
+    readonly Month: "month";
+};
+export type GetSignalSummaryRequestInterval = (typeof GetSignalSummaryRequestInterval)[keyof typeof GetSignalSummaryRequestInterval];