@metronome/sdk 0.3.0 → 2.0.0

package/src/resources/v1/alerts.ts

@@ -1,12 +1,57 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from "../../resource.js";
-import * as Core from "../../core.js";
-import * as Shared from "../shared.js";
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
 
 export class Alerts extends APIResource {
   /**
-   * Create a new alert
+   * Create a new threshold notification to monitor customer spending, balances, and
+   * billing metrics in real-time. Metronome's notification system provides
+   * industry-leading speed with immediate evaluation capabilities, enabling you to
+   * proactively manage customer accounts and prevent revenue leakage.
+   *
+   * This endpoint creates configurable threshold notifications that continuously
+   * monitor various billing thresholds including spend limits, credit balances,
+   * commitment utilization, and invoice totals. Threshold notifications can be
+   * configured globally for all customers or targeted to specific customer accounts.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Proactively monitor customer spending patterns to prevent unexpected overages
+   *   or credit exhaustion
+   * - Automate notifications when customers approach commitment limits or credit
+   *   thresholds
+   * - Enable real-time intervention for accounts at risk of churn or payment issues
+   * - Scale billing operations by automating threshold-based workflows and
+   *   notifications
+   *
+   * ### Key response fields:
+   *
+   * A successful response returns a CustomerAlert object containing:
+   *
+   * - The threshold notification configuration with its unique ID and current status
+   * - The customer's evaluation status (ok, in_alarm, or evaluating)
+   * - Threshold notification metadata including type, threshold values, and update
+   *   timestamps
+   *
+   * ### Usage guidelines:
+   *
+   * - Immediate evaluation: Set `evaluate_on_create` : `true` (default) for instant
+   *   evaluation against existing customers
+   * - Uniqueness constraints: Each threshold notification must have a unique
+   *   `uniqueness_key` within your organization. Use `release_uniqueness_key` :
+   *   `true` when archiving to reuse keys
+   * - Notification type requirements: Different threshold notification types require
+   *   specific fields (e.g., `billable_metric_id` for usage notifications,
+   *   `credit_type_id` for credit-based threshold notifications)
+   * - Webhook delivery: Threshold notifications trigger webhook notifications for
+   *   real-time integration with your systems. Configure webhook endpoints before
+   *   creating threshold notifications
+   * - Performance at scale: Metronome's event-driven architecture processes
+   *   threshold notification evaluations in real-time as usage events stream in,
+   *   unlike competitors who rely on periodic polling or batch evaluation cycles
    *
    * @example
    * ```ts
@@ -20,12 +65,39 @@ export class Alerts extends APIResource {
    * });
    * ```
    */
-  create(body: AlertCreateParams, options?: Core.RequestOptions): Core.APIPromise<AlertCreateResponse> {
+  create(body: AlertCreateParams, options?: RequestOptions): APIPromise<AlertCreateResponse> {
     return this._client.post('/v1/alerts/create', { body, ...options });
   }
 
   /**
-   * Archive an existing alert
+   * Permanently disable a threshold notification and remove it from active
+   * monitoring across all customers. Archived threshold notifications stop
+   * evaluating immediately and can optionally release their uniqueness key for reuse
+   * in future threshold notification configurations.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Decommission threshold notifications that are no longer needed
+   * - Clean up test or deprecated threshold notification configurations
+   * - Free up uniqueness keys for reuse with new threshold notifications
+   * - Stop threshold notification evaluations without losing historical
+   *   configuration data
+   * - Disable outdated monitoring rules during pricing model transitions
+   *
+   * ### Key response fields:
+   *
+   * - data: Object containing the archived threshold notification's ID
+   *
+   * ### Usage guidelines:
+   *
+   * - Irreversible for evaluation: Archived threshold notifications cannot be
+   *   re-enabled; create a new threshold notification to resume monitoring
+   * - Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the
+   *   key in future threshold notifications
+   * - Immediate effect: Threshold notification evaluation stops instantly across all
+   *   customers
+   * - Historical preservation: Archive operation maintains threshold notification
+   *   history and configuration for compliance and auditing
    *
    * @example
    * ```ts
@@ -34,7 +106,7 @@ export class Alerts extends APIResource {
    * });
    * ```
    */
-  archive(body: AlertArchiveParams, options?: Core.RequestOptions): Core.APIPromise<AlertArchiveResponse> {
+  archive(body: AlertArchiveParams, options?: RequestOptions): APIPromise<AlertArchiveResponse> {
     return this._client.post('/v1/alerts/archive', { body, ...options });
   }
 }
@@ -49,7 +121,7 @@ export interface AlertArchiveResponse {
 
 export interface AlertCreateParams {
   /**
-   * Type of the alert
+   * Type of the threshold notification
    */
   alert_type:
     | 'low_credit_balance_reached'
@@ -68,70 +140,72 @@ export interface AlertCreateParams {
     | 'invoice_total_reached';
 
   /**
-   * Name of the alert
+   * Name of the threshold notification
    */
   name: string;
 
   /**
-   * Threshold value of the alert policy. Depending upon the alert type, this number
-   * may represent a financial amount, the days remaining, or a percentage reached.
+   * Threshold value of the notification policy. Depending upon the notification
+   * type, this number may represent a financial amount, the days remaining, or a
+   * percentage reached.
    */
   threshold: number;
 
   /**
-   * For alerts of type `usage_threshold_reached`, specifies which billable metric to
-   * track the usage for.
+   * For threshold notifications of type `usage_threshold_reached`, specifies which
+   * billable metric to track the usage for.
    */
   billable_metric_id?: string;
 
   /**
-   * An array of strings, representing a way to filter the credit grant this alert
-   * applies to, by looking at the credit_grant_type field on the credit grant. This
-   * field is only defined for CreditPercentage and CreditBalance alerts
+   * An array of strings, representing a way to filter the credit grant this
+   * threshold notification applies to, by looking at the credit_grant_type field on
+   * the credit grant. This field is only defined for CreditPercentage and
+   * CreditBalance notifications
    */
   credit_grant_type_filters?: Array<string>;
 
   /**
-   * ID of the credit's currency, defaults to USD. If the specific alert type
+   * ID of the credit's currency, defaults to USD. If the specific notification type
    * requires a pricing unit/currency, find the ID in the
    * [Metronome app](https://app.metronome.com/offering/pricing-units).
    */
   credit_type_id?: string;
 
   /**
-   * A list of custom field filters for alert types that support advanced filtering.
-   * Only present for contract invoices.
+   * A list of custom field filters for threshold notification types that support
+   * advanced filtering. Only present for contract invoices.
    */
   custom_field_filters?: Array<AlertCreateParams.CustomFieldFilter>;
 
   /**
-   * If provided, will create this alert for this specific customer. To create an
-   * alert for all customers, do not specify a `customer_id`.
+   * If provided, will create this threshold notification for this specific customer.
+   * To create a notification for all customers, do not specify a `customer_id`.
    */
   customer_id?: string;
 
   /**
-   * If true, the alert will evaluate immediately on customers that already meet the
-   * alert threshold. If false, it will only evaluate on future customers that
-   * trigger the alert threshold. Defaults to true.
+   * If true, the threshold notification will evaluate immediately on customers that
+   * already meet the notification threshold. If false, it will only evaluate on
+   * future customers that trigger the threshold. Defaults to true.
    */
   evaluate_on_create?: boolean;
 
   /**
-   * Only present for `spend_threshold_reached` alerts. Scope alert to a specific
-   * group key on individual line items.
+   * Only present for `spend_threshold_reached` notifications. Scope notification to
+   * a specific group key on individual line items.
    */
   group_values?: Array<AlertCreateParams.GroupValue>;
 
   /**
-   * Only supported for invoice_total_reached alerts. A list of invoice types to
-   * evaluate.
+   * Only supported for invoice_total_reached threshold notifications. A list of
+   * invoice types to evaluate.
    */
   invoice_types_filter?: Array<string>;
 
   /**
-   * If provided, will create this alert for this specific plan. To create an alert
-   * for all customers, do not specify a `plan_id`.
+   * If provided, will create this threshold notification for this specific plan. To
+   * create a notification for all customers, do not specify a `plan_id`.
    */
   plan_id?: string;
 
@@ -155,18 +229,19 @@ export namespace AlertCreateParams {
   export interface GroupValue {
     key: string;
 
-    value: string;
+    value?: string;
   }
 }
 
 export interface AlertArchiveParams {
   /**
-   * The Metronome ID of the alert
+   * The Metronome ID of the threshold notification
    */
   id: string;
 
   /**
-   * If true, resets the uniqueness key on this alert so it can be re-used
+   * If true, resets the uniqueness key on this threshold notification so it can be
+   * re-used
    */
   release_uniqueness_key?: boolean;
 }

package/src/resources/v1/audit-logs.ts

@@ -1,16 +1,50 @@
 // 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 { CursorPage, type CursorPageParams } from "../../pagination.js";
+import { APIResource } from '../../core/resource';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
 
 export class AuditLogs extends APIResource {
   /**
-   * Retrieves a range of audit logs. If no further audit logs are currently
-   * available, the data array will be empty. As new audit logs are created,
-   * subsequent requests using the same next_page value will be in the returned data
-   * array, ensuring a continuous and uninterrupted reading of audit logs.
+   * Get a comprehensive audit trail of all operations performed in your Metronome
+   * account, whether initiated through the API, web interface, or automated
+   * processes. This endpoint provides detailed logs of who did what and when,
+   * enabling compliance reporting, security monitoring, and operational
+   * troubleshooting across all interaction channels.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Monitor all account activity for security and compliance purposes
+   * - Track configuration changes regardless of source (API, UI, or system)
+   * - Investigate issues by reviewing historical operations
+   *
+   * ### Key response fields:
+   *
+   * An array of AuditLog objects containing:
+   *
+   * - id: Unique identifier for the audit log entry
+   * - timestamp: When the action occurred (RFC 3339 format)
+   * - actor: Information about who performed the action
+   * - request: Details including request ID, IP address, and user agent
+   * - `resource_type`: The type of resource affected (e.g., customer, contract,
+   *   invoice)
+   * - `resource_id`: The specific resource identifier
+   * - `action`: The operation performed
+   * - `next_page`: Cursor for continuous log retrieval
+   *
+   * ### Usage guidelines:
+   *
+   * - Continuous retrieval: The next_page token enables uninterrupted log
+   *   streaming—save it between requests to ensure no logs are missed
+   * - Empty responses: An empty data array means no new logs yet; continue polling
+   *   with the same next_page token
+   * - Date filtering:
+   *   - `starting_on`: Earliest logs to return (inclusive)
+   *   - `ending_before`: Latest logs to return (exclusive)
+   *   - Cannot be used with `next_page`
+   * - Resource filtering: Must specify both `resource_type` and `resource_id`
+   *   together
+   * - Sort order: Default is `date_asc`; use `date_desc` for newest first
    *
    * @example
    * ```ts
@@ -21,24 +55,14 @@ export class AuditLogs extends APIResource {
    * ```
    */
   list(
-    query?: AuditLogListParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<AuditLogListResponsesCursorPage, AuditLogListResponse>;
-  list(
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<AuditLogListResponsesCursorPage, AuditLogListResponse>;
-  list(
-    query: AuditLogListParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<AuditLogListResponsesCursorPage, AuditLogListResponse> {
-    if (isRequestOptions(query)) {
-      return this.list({}, query);
-    }
-    return this._client.getAPIList('/v1/auditLogs', AuditLogListResponsesCursorPage, { query, ...options });
+    query: AuditLogListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AuditLogListResponsesCursorPage, AuditLogListResponse> {
+    return this._client.getAPIList('/v1/auditLogs', CursorPage<AuditLogListResponse>, { query, ...options });
   }
 }
 
-export class AuditLogListResponsesCursorPage extends CursorPage<AuditLogListResponse> {}
+export type AuditLogListResponsesCursorPage = CursorPage<AuditLogListResponse>;
 
 export interface AuditLogListResponse {
   id: string;
@@ -108,12 +132,10 @@ export interface AuditLogListParams extends CursorPageParams {
   starting_on?: string;
 }
 
-AuditLogs.AuditLogListResponsesCursorPage = AuditLogListResponsesCursorPage;
-
 export declare namespace AuditLogs {
   export {
     type AuditLogListResponse as AuditLogListResponse,
-    AuditLogListResponsesCursorPage as AuditLogListResponsesCursorPage,
+    type AuditLogListResponsesCursorPage as AuditLogListResponsesCursorPage,
     type AuditLogListParams as AuditLogListParams,
   };
 }

package/src/resources/v1/billable-metrics.ts

@@ -1,14 +1,43 @@
 // 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, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
 
 export class BillableMetrics extends APIResource {
   /**
-   * Creates a new Billable Metric.
+   * Create billable metrics programmatically with this endpoint—an essential step in
+   * configuring your pricing and packaging in Metronome.
+   *
+   * A billable metric is a customizable query that filters and aggregates events
+   * from your event stream. These metrics are continuously tracked as usage data
+   * enters Metronome through the ingestion pipeline. The ingestion process
+   * transforms raw usage data into actionable pricing metrics, enabling accurate
+   * metering and billing for your products.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Create individual or multiple billable metrics as part of a setup workflow.
+   * - Automate the entire pricing configuration process, from metric creation to
+   *   customer contract setup.
+   * - Define metrics using either standard filtering/aggregation or a custom SQL
+   *   query.
+   *
+   * ### Key response fields:
+   *
+   * - The ID of the billable metric that was created
+   * - The created billable metric will be available to be used in Products, usage
+   *   endpoints, and alerts.
+   *
+   * ### Usage guidelines:
+   *
+   * - Metrics defined using standard filtering and aggregation are Streaming
+   *   billable metrics, which have been optimized for ultra low latency and high
+   *   throughput workflows.
+   * - Use SQL billable metrics if you require more flexible aggregation options.
    *
    * @example
    * ```ts
@@ -37,13 +66,23 @@ export class BillableMetrics extends APIResource {
    */
   create(
     body: BillableMetricCreateParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<BillableMetricCreateResponse> {
+    options?: RequestOptions,
+  ): APIPromise<BillableMetricCreateResponse> {
     return this._client.post('/v1/billable-metrics/create', { body, ...options });
   }
 
   /**
-   * Get a billable metric.
+   * Retrieves the complete configuration for a specific billable metric by its ID.
+   * Use this to review billable metric setup before associating it with products.
+   * Returns the metric's `name`, `event_type_filter`, `property_filters`,
+   * `aggregation_type`, `aggregation_key`, `group_keys`, `custom fields`, and
+   * `SQL query` (if it's a SQL billable metric).
+   *
+   * Important:
+   *
+   * - Archived billable metrics will include an `archived_at` timestamp; they no
+   *   longer process new usage events but remain accessible for historical
+   *   reference.
    *
    * @example
    * ```ts
@@ -56,14 +95,18 @@ export class BillableMetrics extends APIResource {
    */
   retrieve(
     params: BillableMetricRetrieveParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<BillableMetricRetrieveResponse> {
+    options?: RequestOptions,
+  ): APIPromise<BillableMetricRetrieveResponse> {
     const { billable_metric_id } = params;
-    return this._client.get(`/v1/billable-metrics/${billable_metric_id}`, options);
+    return this._client.get(path`/v1/billable-metrics/${billable_metric_id}`, options);
   }
 
   /**
-   * List all billable metrics.
+   * Retrieves all billable metrics with their complete configurations. Use this for
+   * programmatic discovery and management of billable metrics, such as associating
+   * metrics to products and auditing for orphaned or archived metrics. Important:
+   * Archived metrics are excluded by default; use `include_archived`=`true`
+   * parameter to include them.
    *
    * @example
    * ```ts
@@ -74,27 +117,25 @@ export class BillableMetrics extends APIResource {
    * ```
    */
   list(
-    query?: BillableMetricListParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<BillableMetricListResponsesCursorPage, BillableMetricListResponse>;
-  list(
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<BillableMetricListResponsesCursorPage, BillableMetricListResponse>;
-  list(
-    query: BillableMetricListParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<BillableMetricListResponsesCursorPage, BillableMetricListResponse> {
-    if (isRequestOptions(query)) {
-      return this.list({}, query);
-    }
-    return this._client.getAPIList('/v1/billable-metrics', BillableMetricListResponsesCursorPage, {
+    query: BillableMetricListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<BillableMetricListResponsesCursorPage, BillableMetricListResponse> {
+    return this._client.getAPIList('/v1/billable-metrics', CursorPage<BillableMetricListResponse>, {
       query,
       ...options,
     });
   }
 
   /**
-   * Archive an existing billable metric.
+   * Use this endpoint to retire billable metrics that are no longer used. After a
+   * billable metric is archived, that billable metric can no longer be used in any
+   * new Products to define how that product should be metered. If you archive a
+   * billable metric that is already associated with a Product, the Product will
+   * continue to function as usual, metering based on the definition of the archived
+   * billable metric.
+   *
+   * Archived billable metrics will be returned on the `getBillableMetric` and
+   * `listBillableMetrics` endpoints with a populated `archived_at` field.
    *
    * @example
    * ```ts
@@ -105,13 +146,13 @@ export class BillableMetrics extends APIResource {
    */
   archive(
     body: BillableMetricArchiveParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<BillableMetricArchiveResponse> {
+    options?: RequestOptions,
+  ): APIPromise<BillableMetricArchiveResponse> {
     return this._client.post('/v1/billable-metrics/archive', { body, ...options });
   }
 }
 
-export class BillableMetricListResponsesCursorPage extends CursorPage<BillableMetricListResponse> {}
+export type BillableMetricListResponsesCursorPage = CursorPage<BillableMetricListResponse>;
 
 export interface BillableMetricCreateResponse {
   data: Shared.ID;
@@ -151,6 +192,9 @@ export namespace BillableMetricRetrieveResponse {
      */
     archived_at?: string;
 
+    /**
+     * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+     */
     custom_fields?: { [key: string]: string };
 
     /**
@@ -207,6 +251,9 @@ export interface BillableMetricListResponse {
    */
   archived_at?: string;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields?: { [key: string]: string };
 
   /**
@@ -301,15 +348,13 @@ export interface BillableMetricArchiveParams {
   id: string;
 }
 
-BillableMetrics.BillableMetricListResponsesCursorPage = BillableMetricListResponsesCursorPage;
-
 export declare namespace BillableMetrics {
   export {
     type BillableMetricCreateResponse as BillableMetricCreateResponse,
     type BillableMetricRetrieveResponse as BillableMetricRetrieveResponse,
     type BillableMetricListResponse as BillableMetricListResponse,
     type BillableMetricArchiveResponse as BillableMetricArchiveResponse,
-    BillableMetricListResponsesCursorPage as BillableMetricListResponsesCursorPage,
+    type BillableMetricListResponsesCursorPage as BillableMetricListResponsesCursorPage,
     type BillableMetricCreateParams as BillableMetricCreateParams,
     type BillableMetricRetrieveParams as BillableMetricRetrieveParams,
     type BillableMetricListParams as BillableMetricListParams,