@metronome/sdk 0.2.0 → 1.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 alert to monitor customer spending, balances, and billing metrics
+   * in real-time. Metronome's alert system provides industry-leading speed with
+   * immediate evaluation capabilities, enabling you to proactively manage customer
+   * accounts and prevent revenue leakage.
+   *
+   * This endpoint creates configurable alerts that continuously monitor various
+   * billing thresholds including spend limits, credit balances, commitment
+   * utilization, and invoice totals. Alerts can be configured globally for all
+   * customers or targeted to specific customer accounts. Custom fields can be used
+   * on certain alert types to further target alerts to groups of customers.
+   *
+   * ### 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 alert configuration with its unique ID and current status
+   * - The customer's evaluation status (ok, in_alarm, or evaluating)
+   * - Alert 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 alert must have a unique `uniqueness_key` within
+   *   your organization. Use `release_uniqueness_key` : `true` when archiving to
+   *   reuse keys
+   * - Alert type requirements: Different alert types require specific fields (e.g.,
+   *   `billable_metric_id` for usage alerts, `credit_type_id` for credit-based
+   *   alerts)
+   * - Webhook delivery: Alerts trigger webhook notifications for real-time
+   *   integration with your systems. Configure webhook endpoints before creating
+   *   alerts
+   * - Performance at scale: Metronome's event-driven architecture processes alert
+   *   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,38 @@ 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 an alert and remove it from active monitoring across all
+   * customers. Archived alerts stop evaluating immediately and can optionally
+   * release their uniqueness key for reuse in future alert configurations.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Decommission alerts that are no longer needed
+   * - Clean up test or deprecated alert configurations
+   * - Free up uniqueness keys for reuse with new alerts
+   * - Stop alert evaluations without losing historical configuration data
+   * - Disable outdated monitoring rules during pricing model transitions
+   *
+   * ### Key response fields:
+   *
+   * - data: Object containing the archived alert's ID
+   * - Alert evaluation stops immediately for all affected customers
+   * - Historical alert data and configurations remain accessible for audit purposes
+   *
+   * ### Usage guidelines:
+   *
+   * - Irreversible for evaluation: Archived alerts cannot be re-enabled; create a
+   *   new alert to resume monitoring
+   * - Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the
+   *   key in future alerts
+   * - Immediate effect: Alert evaluation stops instantly across all customers
+   * - Historical preservation: Archive operation maintains alert history and
+   *   configuration for compliance and auditing
    *
    * @example
    * ```ts
@@ -34,7 +105,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 });
   }
 }
@@ -155,7 +226,7 @@ export namespace AlertCreateParams {
   export interface GroupValue {
     key: string;
 
-    value: string;
+    value?: string;
   }
 }
 

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,