@metronome/sdk 0.3.0 → 2.0.0

package/src/resources/v1/customers/alerts.ts

@@ -1,13 +1,73 @@
 // 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 {
+  CursorPageWithoutLimit,
+  type CursorPageWithoutLimitParams,
+  PagePromise,
+} from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
 
 export class Alerts extends APIResource {
   /**
-   * Get the customer alert status and alert information for the specified customer
-   * and alert
+   * Retrieve the real-time evaluation status for a specific threshold
+   * notification-customer pair. This endpoint provides instant visibility into
+   * whether a customer has triggered a threshold notification condition, enabling
+   * you to monitor account health and take proactive action based on current
+   * threshold notification states.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Check if a specific customer is currently violating an threshold notification
+   *   (`in_alarm` status)
+   * - Verify threshold notification configuration details and threshold values for a
+   *   customer
+   * - Monitor the evaluation state of newly created or recently modified threshold
+   *   notification
+   * - Build dashboards or automated workflows that respond to specific threshold
+   *   notification conditions
+   * - Validate threshold notification behavior before deploying to production
+   *   customers
+   * - Integrate threshold notification status checks into customer support tools or
+   *   admin interfaces
+   *
+   * ### Key response fields:
+   *
+   * A CustomerAlert object containing:
+   *
+   * - `customer_status`: The current evaluation state
+   *
+   * - `ok` - Customer is within acceptable thresholds
+   * - `in_alarm` - Customer has breached the threshold for the notification
+   * - `evaluating` - Notification is currently being evaluated (typically during
+   *   initial setup)
+   * - `null` - Notification has been archived
+   * - `triggered_by`: Additional context about what caused the notification to
+   *   trigger (when applicable)
+   * - alert: Complete threshold notification configuration including:
+   *   - Notification ID, name, and type
+   *   - Current threshold values and credit type information
+   *   - Notification status (enabled, disabled, or archived)
+   *   - Last update timestamp
+   *   - Any applied filters (credit grant types, custom fields, group values)
+   *
+   * ### Usage guidelines:
+   *
+   * - Customer status: Returns the current evaluation state, not historical data.
+   *   For threshold notification history, use webhook notifications or event logs
+   * - Required parameters: Both customer_id and alert_id must be valid UUIDs that
+   *   exist in your organization
+   * - Archived notifications: Returns null for customer_status if the notification
+   *   has been archived, but still includes the notification configuration details
+   * - Performance considerations: This endpoint queries live evaluation state,
+   *   making it ideal for real-time monitoring but not for bulk status checks
+   * - Integration patterns: Best used for on-demand status checks in response to
+   *   user actions or as part of targeted monitoring workflows
+   * - Error handling: Returns 404 if either the customer or alert_id doesn't exist
+   *   or isn't accessible to your organization
    *
    * @example
    * ```ts
@@ -17,27 +77,96 @@ export class Alerts extends APIResource {
    * });
    * ```
    */
-  retrieve(body: AlertRetrieveParams, options?: Core.RequestOptions): Core.APIPromise<AlertRetrieveResponse> {
+  retrieve(body: AlertRetrieveParams, options?: RequestOptions): APIPromise<AlertRetrieveResponse> {
     return this._client.post('/v1/customer-alerts/get', { body, ...options });
   }
 
   /**
-   * Fetch all customer alert statuses and alert information for a customer
+   * Retrieve all threshold notification configurations and their current statuses
+   * for a specific customer in a single API call. This endpoint provides a
+   * comprehensive view of all threshold notification monitoring a customer account.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Display all active threshold notifications for a customer in dashboards or
+   *   admin panels
+   * - Quickly identify which threshold notifications a customer is currently
+   *   triggering
+   * - Audit threshold notification coverage for specific accounts
+   * - Filter threshold notifications by status (enabled, disabled, or archived)
+   *
+   * ### Key response fields:
+   *
+   * - data: Array of CustomerAlert objects, each containing:
+   *   - Current evaluation status (`ok`, `in_alarm`, `evaluating`, or `null`)
+   *   - Complete threshold notification configuration and threshold details
+   *   - Threshold notification metadata including type, name, and last update time
+   * - next_page: Pagination cursor for retrieving additional results
+   *
+   * ### Usage guidelines:
+   *
+   * - Default behavior: Returns only enabled threshold notifications unless
+   *   `alert_statuses` filter is specified
+   * - Pagination: Use the `next_page` cursor to retrieve all results for customers
+   *   with many notifications
+   * - Performance: Efficiently retrieves multiple threshold notification statuses in
+   *   a single request instead of making individual calls
+   * - Filtering: Pass the `alert_statuses` array to include disabled or archived
+   *   threshold notifications in results
    *
    * @example
    * ```ts
-   * const alerts = await client.v1.customers.alerts.list({
-   *   customer_id: '9b85c1c1-5238-4f2a-a409-61412905e1e1',
-   * });
+   * // Automatically fetches more pages as needed.
+   * for await (const customerAlert of client.v1.customers.alerts.list(
+   *   { customer_id: '9b85c1c1-5238-4f2a-a409-61412905e1e1' },
+   * )) {
+   *   // ...
+   * }
    * ```
    */
-  list(params: AlertListParams, options?: Core.RequestOptions): Core.APIPromise<AlertListResponse> {
+  list(
+    params: AlertListParams,
+    options?: RequestOptions,
+  ): PagePromise<CustomerAlertsCursorPageWithoutLimit, CustomerAlert> {
     const { next_page, ...body } = params;
-    return this._client.post('/v1/customer-alerts/list', { query: { next_page }, body, ...options });
+    return this._client.getAPIList('/v1/customer-alerts/list', CursorPageWithoutLimit<CustomerAlert>, {
+      query: { next_page },
+      body,
+      method: 'post',
+      ...options,
+    });
   }
 
   /**
-   * Reset state for an alert by customer id and force re-evaluation
+   * Force an immediate re-evaluation of a specific threshold notification for a
+   * customer, clearing any previous state and triggering a fresh assessment against
+   * current thresholds. This endpoint ensures threshold notification accuracy after
+   * configuration changes or data corrections.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Clear false positive threshold notifications after fixing data issues
+   * - Re-evaluate threshold notifications after adjusting customer balances or
+   *   credits
+   * - Test threshold notification behavior during development and debugging
+   * - Resolve stuck threshold notification that may be in an incorrect state
+   * - Trigger immediate evaluation after threshold modifications
+   *
+   * ### Key response fields:
+   *
+   * - 200 Success: Confirmation that the threshold notification has been reset and
+   *   re-evaluation initiated
+   * - No response body is returned - the operation completes asynchronously
+   *
+   * ### Usage guidelines:
+   *
+   * - Immediate effect: Triggers re-evaluation instantly, which may result in new
+   *   webhook notifications if thresholds are breached
+   * - State clearing: Removes any cached evaluation state, ensuring a fresh
+   *   assessment
+   * - Use sparingly: Intended for exceptional cases, not routine operations
+   * - Asynchronous processing: The reset completes immediately, but re-evaluation
+   *   happens in the background
    *
    * @example
    * ```ts
@@ -47,26 +176,28 @@ export class Alerts extends APIResource {
    * });
    * ```
    */
-  reset(body: AlertResetParams, options?: Core.RequestOptions): Core.APIPromise<void> {
+  reset(body: AlertResetParams, options?: RequestOptions): APIPromise<void> {
     return this._client.post('/v1/customer-alerts/reset', {
       body,
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 }
 
+export type CustomerAlertsCursorPageWithoutLimit = CursorPageWithoutLimit<CustomerAlert>;
+
 export interface CustomerAlert {
   alert: CustomerAlert.Alert;
 
   /**
-   * The status of the customer alert. If the alert is archived, null will be
-   * returned.
+   * The status of the threshold notification. If the notification is archived, null
+   * will be returned.
    */
   customer_status: 'ok' | 'in_alarm' | 'evaluating' | null;
 
   /**
-   * If present, indicates the reason the alert was triggered.
+   * If present, indicates the reason the threshold notification was triggered.
    */
   triggered_by?: string | null;
 }
@@ -74,27 +205,27 @@ export interface CustomerAlert {
 export namespace CustomerAlert {
   export interface Alert {
     /**
-     * the Metronome ID of the alert
+     * the Metronome ID of the threshold notification
      */
     id: string;
 
     /**
-     * Name of the alert
+     * Name of the threshold notification
      */
     name: string;
 
     /**
-     * Status of the alert
+     * Status of the threshold notification
      */
     status: 'enabled' | 'archived' | 'disabled';
 
     /**
-     * Threshold value of the alert policy
+     * Threshold value of the notification policy
      */
     threshold: number;
 
     /**
-     * Type of the alert
+     * Type of the threshold notification
      */
     type:
       | 'low_credit_balance_reached'
@@ -113,39 +244,41 @@ export namespace CustomerAlert {
       | 'invoice_total_reached';
 
     /**
-     * Timestamp for when the alert was last updated
+     * Timestamp for when the threshold notification was last updated
      */
     updated_at: 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>;
 
     credit_type?: Shared.CreditTypeData | null;
 
     /**
-     * A list of custom field filters for alert types that support advanced filtering
+     * A list of custom field filters for notification types that support advanced
+     * filtering
      */
     custom_field_filters?: Array<Alert.CustomFieldFilter>;
 
     /**
-     * Scopes alert evaluation to a specific presentation group key on individual line
-     * items. Only present for spend alerts.
+     * Scopes threshold notification evaluation to a specific presentation group key on
+     * individual line items. Only present for spend notifications.
      */
     group_key_filter?: Alert.GroupKeyFilter;
 
     /**
-     * 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<Alert.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>;
 
@@ -167,8 +300,8 @@ export namespace CustomerAlert {
     }
 
     /**
-     * Scopes alert evaluation to a specific presentation group key on individual line
-     * items. Only present for spend alerts.
+     * Scopes threshold notification evaluation to a specific presentation group key on
+     * individual line items. Only present for spend notifications.
      */
     export interface GroupKeyFilter {
       key: string;
@@ -179,7 +312,7 @@ export namespace CustomerAlert {
     export interface GroupValue {
       key: string;
 
-      value: string;
+      value?: string;
     }
   }
 }
@@ -188,15 +321,9 @@ export interface AlertRetrieveResponse {
   data: CustomerAlert;
 }
 
-export interface AlertListResponse {
-  data: Array<CustomerAlert>;
-
-  next_page: string | null;
-}
-
 export interface AlertRetrieveParams {
   /**
-   * The Metronome ID of the alert
+   * The Metronome ID of the threshold notification
    */
   alert_id: string;
 
@@ -206,33 +333,46 @@ export interface AlertRetrieveParams {
   customer_id: string;
 
   /**
-   * When parallel alerts are enabled during migration, this flag denotes whether to
-   * fetch alerts for plans or contracts.
+   * Only present for `spend_threshold_reached` notifications. Retrieve the
+   * notification for a specific group key-value pair.
+   */
+  group_values?: Array<AlertRetrieveParams.GroupValue>;
+
+  /**
+   * When parallel threshold notifications are enabled during migration, this flag
+   * denotes whether to fetch notifications for plans or contracts.
    */
   plans_or_contracts?: 'PLANS' | 'CONTRACTS';
 }
 
-export interface AlertListParams {
+export namespace AlertRetrieveParams {
   /**
-   * Body param: The Metronome ID of the customer
+   * Scopes threshold notification evaluation to a specific presentation group key on
+   * individual line items. Only present for spend notifications.
    */
-  customer_id: string;
+  export interface GroupValue {
+    key: string;
+
+    value: string;
+  }
+}
 
+export interface AlertListParams extends CursorPageWithoutLimitParams {
   /**
-   * Query param: Cursor that indicates where the next page of results should start.
+   * Body param: The Metronome ID of the customer
    */
-  next_page?: string;
+  customer_id: string;
 
   /**
-   * Body param: Optionally filter by alert status. If absent, only enabled alerts
-   * will be returned.
+   * Body param: Optionally filter by threshold notification status. If absent, only
+   * enabled notifications will be returned.
    */
   alert_statuses?: Array<'ENABLED' | 'DISABLED' | 'ARCHIVED'>;
 }
 
 export interface AlertResetParams {
   /**
-   * The Metronome ID of the alert
+   * The Metronome ID of the threshold notification
    */
   alert_id: string;
 
@@ -246,7 +386,7 @@ export declare namespace Alerts {
   export {
     type CustomerAlert as CustomerAlert,
     type AlertRetrieveResponse as AlertRetrieveResponse,
-    type AlertListResponse as AlertListResponse,
+    type CustomerAlertsCursorPageWithoutLimit as CustomerAlertsCursorPageWithoutLimit,
     type AlertRetrieveParams as AlertRetrieveParams,
     type AlertListParams as AlertListParams,
     type AlertResetParams as AlertResetParams,

package/src/resources/v1/customers/billing-config.ts

@@ -1,7 +1,10 @@
 // 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 { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
 
 export class BillingConfig extends APIResource {
   /**
@@ -17,12 +20,12 @@ export class BillingConfig extends APIResource {
    * });
    * ```
    */
-  create(params: BillingConfigCreateParams, options?: Core.RequestOptions): Core.APIPromise<void> {
+  create(params: BillingConfigCreateParams, options?: RequestOptions): APIPromise<void> {
     const { customer_id, billing_provider_type, ...body } = params;
-    return this._client.post(`/v1/customers/${customer_id}/billing-config/${billing_provider_type}`, {
+    return this._client.post(path`/v1/customers/${customer_id}/billing-config/${billing_provider_type}`, {
       body,
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 
@@ -40,10 +43,13 @@ export class BillingConfig extends APIResource {
    */
   retrieve(
     params: BillingConfigRetrieveParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<BillingConfigRetrieveResponse> {
+    options?: RequestOptions,
+  ): APIPromise<BillingConfigRetrieveResponse> {
     const { customer_id, billing_provider_type } = params;
-    return this._client.get(`/v1/customers/${customer_id}/billing-config/${billing_provider_type}`, options);
+    return this._client.get(
+      path`/v1/customers/${customer_id}/billing-config/${billing_provider_type}`,
+      options,
+    );
   }
 
   /**
@@ -58,11 +64,11 @@ export class BillingConfig extends APIResource {
    * });
    * ```
    */
-  delete(params: BillingConfigDeleteParams, options?: Core.RequestOptions): Core.APIPromise<void> {
+  delete(params: BillingConfigDeleteParams, options?: RequestOptions): APIPromise<void> {
     const { customer_id, billing_provider_type } = params;
-    return this._client.delete(`/v1/customers/${customer_id}/billing-config/${billing_provider_type}`, {
+    return this._client.delete(path`/v1/customers/${customer_id}/billing-config/${billing_provider_type}`, {
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 }
@@ -134,7 +140,11 @@ export namespace BillingConfigRetrieveResponse {
 
     billing_provider_customer_id?: string;
 
-    stripe_collection_method?: 'charge_automatically' | 'send_invoice';
+    stripe_collection_method?:
+      | 'charge_automatically'
+      | 'send_invoice'
+      | 'auto_charge_payment_intent'
+      | 'manually_charge_payment_intent';
   }
 }
 
@@ -201,7 +211,11 @@ export interface BillingConfigCreateParams {
   /**
    * Body param:
    */
-  stripe_collection_method?: 'charge_automatically' | 'send_invoice';
+  stripe_collection_method?:
+    | 'charge_automatically'
+    | 'send_invoice'
+    | 'auto_charge_payment_intent'
+    | 'manually_charge_payment_intent';
 }
 
 export interface BillingConfigRetrieveParams {