@metronome/sdk 0.3.0 → 2.0.0

package/src/resources/v1/usage.ts

@@ -1,68 +1,219 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from "../../resource.js";
-import { isRequestOptions } from "../../core.js";
-import * as Core from "../../core.js";
-import * as Shared from "../shared.js";
-import { CursorPage, type CursorPageParams } from "../../pagination.js";
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { APIPromise } from '../../core/api-promise';
+import {
+  CursorPage,
+  type CursorPageParams,
+  CursorPageWithoutLimit,
+  type CursorPageWithoutLimitParams,
+  PagePromise,
+} from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
 
 export class Usage extends APIResource {
   /**
-   * Fetch aggregated usage data for multiple customers and billable-metrics, broken
-   * into intervals of the specified length.
+   * Retrieve aggregated usage data across multiple customers and billable metrics in
+   * a single query. This batch endpoint enables you to fetch usage patterns at
+   * scale, broken down by time windows, making it ideal for building analytics
+   * dashboards, generating reports, and monitoring platform-wide usage trends.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Generate platform-wide usage reports for internal teams
+   * - Monitor aggregate usage trends across your entire customer base
+   * - Create comparative usage analyses between customers or time periods
+   * - Support capacity planning with historical usage patterns
+   *
+   * ### Key response fields:
+   *
+   * An array of `UsageBatchAggregate` objects containing:
+   *
+   * - `customer_id`: The customer this usage belongs to
+   * - `billable_metric_id` and `billable_metric_name`: What was measured
+   * - `start_timestamp` and `end_timestamp`: Time window for this data point
+   * - `value`: Aggregated usage amount for the period
+   * - `groups` (optional): Usage broken down by group keys with values
+   * - `next_page`: Pagination cursor for large result sets
+   *
+   * ### Usage guidelines:
+   *
+   * - Time windows: Set `window_size` to `hour`, `day`, or `none` (entire period)
+   * - Required parameters: Must specify `starting_on`, `ending_before`, and
+   *   `window_size`
+   * - Filtering options:
+   *   - `customer_ids`: Limit to specific customers (omit for all customers)
+   *   - `billable_metrics`: Limit to specific metrics (omit for all metrics)
+   * - Pagination: Use `next_page` cursor to retrieve large datasets
+   * - Null values: Group values may be null when no usage matches that group
    *
    * @example
    * ```ts
-   * const usages = await client.v1.usage.list({
+   * // Automatically fetches more pages as needed.
+   * for await (const usageListResponse of client.v1.usage.list({
    *   ending_before: '2021-01-03T00:00:00Z',
    *   starting_on: '2021-01-01T00:00:00Z',
    *   window_size: 'day',
-   * });
+   * })) {
+   *   // ...
+   * }
    * ```
    */
-  list(params: UsageListParams, options?: Core.RequestOptions): Core.APIPromise<UsageListResponse> {
+  list(
+    params: UsageListParams,
+    options?: RequestOptions,
+  ): PagePromise<UsageListResponsesCursorPageWithoutLimit, UsageListResponse> {
     const { next_page, ...body } = params;
-    return this._client.post('/v1/usage', { query: { next_page }, body, ...options });
+    return this._client.getAPIList('/v1/usage', CursorPageWithoutLimit<UsageListResponse>, {
+      query: { next_page },
+      body,
+      method: 'post',
+      ...options,
+    });
   }
 
   /**
-   * Send usage events to Metronome. The body of this request is expected to be a
-   * JSON array of between 1 and 100 usage events. Compressed request bodies are
-   * supported with a `Content-Encoding: gzip` header. See
-   * [Getting usage into Metronome](https://docs.metronome.com/connect-metronome/) to
+   * The ingest endpoint is the primary method for sending usage events to Metronome,
+   * serving as the foundation for all billing calculations in your usage-based
+   * pricing model. This high-throughput endpoint is designed for real-time streaming
+   * ingestion, supports backdating 34 days, and is built to handle mission-critical
+   * usage data with enterprise-grade reliability. Metronome supports 100,000 events
+   * per second without requiring pre-aggregation or rollups and can scale up from
+   * there. See the [Send usage events](/guides/events/send-usage-events) guide to
    * learn more about usage events.
    *
+   * ### Use this endpoint to:
+   *
+   * Create a customer usage pipeline into Metronome that drives billable metrics,
+   * credit drawdown, and invoicing. Track customer behavior, resource consumption,
+   * and feature usage
+   *
+   * ### What happens when you send events:
+   *
+   * - Events are validated and processed in real-time
+   * - Events are matched to customers using customer IDs or customer ingest aliases
+   * - Events are matched to billable metrics and are immediately available for usage
+   *   and spend calculations
+   *
+   * ### Usage guidelines:
+   *
+   * - Historical events can be backdated up to 34 days and will immediately impact
+   *   live customer spend
+   * - Duplicate events are automatically detected and ignored (34-day deduplication
+   *   window)
+   *
+   * #### Event structure:
+   *
+   * Usage events are simple JSON objects designed for flexibility and ease of
+   * integration:
+   *
+   * ```json
+   * {
+   *   "transaction_id": "2021-01-01T00:00:00Z_cluster42",
+   *   "customer_id": "team@example.com",
+   *   "event_type": "api_request",
+   *   "timestamp": "2021-01-01T00:00:00Z",
+   *   "properties": {
+   *     "endpoint": "/v1/users",
+   *     "method": "POST",
+   *     "response_time_ms": 45,
+   *     "region": "us-west-2"
+   *   }
+   * }
+   * ```
+   *
+   * Learn more about
+   * [usage event structure definitions](/guides/events/design-usage-events).
+   *
+   * #### Transaction ID
+   *
+   * The transaction_id serves as your idempotency key, ensuring events are processed
+   * exactly once. Metronome maintains a 34-day deduplication window - significantly
+   * longer than typical 12-hour windows - enabling robust backfill scenarios without
+   * duplicate billing.
+   *
+   * - Best Practices:
+   *   - Use UUIDs for one-time events: uuid4()
+   *   - For heartbeat events, use deterministic IDs
+   *   - Include enough context to avoid collisions across different event sources
+   *
+   * #### Customer ID
+   *
+   * Identifies which customer should be billed for this usage. Supports two
+   * identification methods:
+   *
+   * - Metronome Customer ID: The UUID returned when creating a customer
+   * - Ingest Alias: Your system's identifier (email, account number, etc.)
+   *
+   * Ingest aliases enable seamless integration without requiring ID mapping, and
+   * customers can have multiple aliases for flexibility.
+   *
+   * #### Event Type:
+   *
+   * Categorizes the event type for billable metric matching. Choose descriptive
+   * names that aligns with the product surface area.
+   *
+   * #### Properties:
+   *
+   * Flexible metadata also used to match billable metrics or to be used to serve as
+   * group keys to create multiple pricing dimensions or breakdown costs by novel
+   * properties for end customers or internal finance teams measuring underlying
+   * COGs.
+   *
    * @example
    * ```ts
-   * await client.v1.usage.ingest([
-   *   {
-   *     customer_id: 'team@example.com',
-   *     event_type: 'heartbeat',
-   *     timestamp: '2021-01-01T00:00:00Z',
-   *     transaction_id: '2021-01-01T00:00:00Z_cluster42',
-   *   },
-   * ]);
+   * await client.v1.usage.ingest();
    * ```
    */
-  ingest(body?: UsageIngestParams, options?: Core.RequestOptions): Core.APIPromise<void>;
-  ingest(options?: Core.RequestOptions): Core.APIPromise<void>;
   ingest(
-    body?: UsageIngestParams | Core.RequestOptions,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<void> {
-    if (isRequestOptions(body)) {
-      return this.ingest(undefined, body);
-    }
+    params: UsageIngestParams | null | undefined = undefined,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { usage } = params ?? {};
     return this._client.post('/v1/ingest', {
-      body,
+      body: usage,
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 
   /**
-   * Fetch aggregated usage data for the specified customer, billable-metric, and
-   * optional group, broken into intervals of the specified length.
+   * Retrieve granular usage data for a specific customer and billable metric, with
+   * the ability to break down usage by custom grouping dimensions. This endpoint
+   * enables deep usage analytics by segmenting data across attributes like region,
+   * user, model type, or any custom dimension defined in your billable metrics.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Analyze usage patterns broken down by specific attributes (region, user,
+   *   department, etc.)
+   * - Build detailed usage dashboards with dimensional filtering
+   * - Identify high-usage segments for optimization opportunities
+   *
+   * ### Key response fields:
+   *
+   * An array of `PagedUsageAggregate` objects containing:
+   *
+   * - `starting_on` and `ending_before`: Time window boundaries
+   * - `group_key`: The dimension being grouped by (e.g., "region")
+   * - `group_value`: The specific value for this group (e.g., "US-East")
+   * - `value`: Aggregated usage for this group and time window
+   * - `next_page`: Pagination cursor for large datasets
+   *
+   * ### Usage guidelines:
+   *
+   * - Required parameters: Must specify `customer_id`, `billable_metric_id`, and
+   *   `window_size`
+   * - Time windows: Set `window_size` to hour, day, or none for different
+   *   granularities
+   * - Group filtering: Use `group_by` to specify:
+   *   - key: The dimension to group by (must be set on the billable metric as a
+   *     group key)
+   *   - values: Optional array to filter to specific values only
+   * - Pagination: Use limit and `next_page` for large result sets
+   * - Null handling: `group_value` may be null for unmatched data
    *
    * @example
    * ```ts
@@ -87,10 +238,10 @@ export class Usage extends APIResource {
    */
   listWithGroups(
     params: UsageListWithGroupsParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<UsageListWithGroupsResponsesCursorPage, UsageListWithGroupsResponse> {
+    options?: RequestOptions,
+  ): PagePromise<UsageListWithGroupsResponsesCursorPage, UsageListWithGroupsResponse> {
     const { limit, next_page, ...body } = params;
-    return this._client.getAPIList('/v1/usage/groups', UsageListWithGroupsResponsesCursorPage, {
+    return this._client.getAPIList('/v1/usage/groups', CursorPage<UsageListWithGroupsResponse>, {
       query: { limit, next_page },
       body,
       method: 'post',
@@ -99,10 +250,40 @@ export class Usage extends APIResource {
   }
 
   /**
-   * For a set of events, look up matched billable metrics and customers by
-   * transaction id. This endpoint looks at transactions that occurred in the last 34
-   * days, and is intended for sampling-based testing workflows. It is heavily rate
-   * limited.
+   * This endpoint retrieves events by transaction ID for events that occurred within
+   * the last 34 days. It is specifically designed for sampling-based testing
+   * workflows to detect revenue leakage. The Event Search API provides a critical
+   * observability tool that validates the integrity of your usage pipeline by
+   * allowing you to sample raw events and verify their matching against active
+   * billable metrics.
+   *
+   * Why event observability matters for revenue leakage: Silent revenue loss occurs
+   * when events are dropped, delayed, or fail to match billable metrics due to:
+   *
+   * - Upstream system failures
+   * - Event format changes
+   * - Misconfigured billable metrics
+   *
+   * ### Use this endpoint to:
+   *
+   * - Sample raw events and validate they match the expected billable metrics
+   * - Build custom leakage detection alerts to prevent silent revenue loss
+   * - Verify event processing accuracy during system changes or metric updates
+   * - Debug event matching issues in real-time
+   *
+   * ### Key response fields:
+   *
+   * - Complete event details including transaction ID, customer ID, and properties
+   * - Matched Metronome customer (if any)
+   * - Matched billable metric information (if any)
+   * - Processing status and duplicate detection flags
+   *
+   * ### Usage guidelines:
+   *
+   * ⚠️ Important: This endpoint is heavily rate limited and designed for sampling
+   * workflows only. Do not use this endpoint to check every event in your system.
+   * Instead, implement a sampling strategy to randomly validate a subset of events
+   * for observability purposes.
    *
    * @example
    * ```ts
@@ -111,39 +292,33 @@ export class Usage extends APIResource {
    * });
    * ```
    */
-  search(body: UsageSearchParams, options?: Core.RequestOptions): Core.APIPromise<UsageSearchResponse> {
+  search(body: UsageSearchParams, options?: RequestOptions): APIPromise<UsageSearchResponse> {
     return this._client.post('/v1/events/search', { body, ...options });
   }
 }
 
-export class UsageListWithGroupsResponsesCursorPage extends CursorPage<UsageListWithGroupsResponse> {}
-
-export interface UsageListResponse {
-  data: Array<UsageListResponse.Data>;
+export type UsageListResponsesCursorPageWithoutLimit = CursorPageWithoutLimit<UsageListResponse>;
 
-  next_page: string | null;
-}
+export type UsageListWithGroupsResponsesCursorPage = CursorPage<UsageListWithGroupsResponse>;
 
-export namespace UsageListResponse {
-  export interface Data {
-    billable_metric_id: string;
+export interface UsageListResponse {
+  billable_metric_id: string;
 
-    billable_metric_name: string;
+  billable_metric_name: string;
 
-    customer_id: string;
+  customer_id: string;
 
-    end_timestamp: string;
+  end_timestamp: string;
 
-    start_timestamp: string;
+  start_timestamp: string;
 
-    value: number | null;
+  value: number | null;
 
-    /**
-     * Values will be either a number or null. Null indicates that there were no
-     * matches for the group_by value.
-     */
-    groups?: { [key: string]: number | null };
-  }
+  /**
+   * Values will be either a number or null. Null indicates that there were no
+   * matches for the group_by value.
+   */
+  groups?: { [key: string]: number | null };
 }
 
 export interface UsageListWithGroupsResponse {
@@ -223,6 +398,9 @@ export namespace UsageSearchResponse {
        */
       archived_at?: string;
 
+      /**
+       * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+       */
       custom_fields?: { [key: string]: string };
 
       /**
@@ -270,7 +448,7 @@ export namespace UsageSearchResponse {
   }
 }
 
-export interface UsageListParams {
+export interface UsageListParams extends CursorPageWithoutLimitParams {
   /**
    * Body param:
    */
@@ -289,11 +467,6 @@ export interface UsageListParams {
    */
   window_size: 'HOUR' | 'DAY' | 'NONE';
 
-  /**
-   * Query param: Cursor that indicates where the next page of results should start.
-   */
-  next_page?: string;
-
   /**
    * Body param: A list of billable metrics to fetch usage for. If absent, all
    * billable metrics will be returned.
@@ -330,7 +503,9 @@ export namespace UsageListParams {
   }
 }
 
-export type UsageIngestParams = Array<UsageIngestParams.Usage>;
+export interface UsageIngestParams {
+  usage?: Array<UsageIngestParams.Usage>;
+}
 
 export namespace UsageIngestParams {
   export interface Usage {
@@ -413,14 +588,13 @@ export interface UsageSearchParams {
   transactionIds: Array<string>;
 }
 
-Usage.UsageListWithGroupsResponsesCursorPage = UsageListWithGroupsResponsesCursorPage;
-
 export declare namespace Usage {
   export {
     type UsageListResponse as UsageListResponse,
     type UsageListWithGroupsResponse as UsageListWithGroupsResponse,
     type UsageSearchResponse as UsageSearchResponse,
-    UsageListWithGroupsResponsesCursorPage as UsageListWithGroupsResponsesCursorPage,
+    type UsageListResponsesCursorPageWithoutLimit as UsageListResponsesCursorPageWithoutLimit,
+    type UsageListWithGroupsResponsesCursorPage as UsageListWithGroupsResponsesCursorPage,
     type UsageListParams as UsageListParams,
     type UsageIngestParams as UsageIngestParams,
     type UsageListWithGroupsParams as UsageListWithGroupsParams,