@metronome/sdk 0.2.0 → 1.0.0

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

@@ -1,13 +1,61 @@
 // 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 alert-customer pair.
+   * This endpoint provides instant visibility into whether a customer has triggered
+   * an alert condition, enabling you to monitor account health and take proactive
+   * action based on current alert states.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Check if a specific customer is currently violating an alert threshold
+   *   (`in_alarm` status)
+   * - Verify alert configuration details and threshold values for a customer
+   * - Integrate alert 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 alert threshold
+   * - `evaluating` - Alert has yet to be evaluated (typically due to a customer or
+   *   alert having just been created)
+   * - `null` - Alert has been archived
+   * - `triggered_by`: Additional context about what caused the alert to trigger
+   *   (when applicable)
+   * - alert: Complete alert configuration including:
+   *   - Alert ID, name, and type
+   *   - Current threshold values and credit type information
+   *   - Alert 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 alert history, use webhook notifications or event logs
+   * - Archived alerts: Returns null for customer_status if the alert has been
+   *   archived, but still includes the alert configuration details
+   * - Integration patterns: This endpoint can be used to check a customer's alert
+   *   status, but shouldn't be scraped. You should instead rely on the webhook
+   *   notification to understand when customers are moved to IN_ALARM.
+   * - 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 +65,89 @@ 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 alert configurations and their current statuses for a specific
+   * customer in a single API call. This endpoint provides a comprehensive view of
+   * all alerts monitoring a customer account.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Display all active alerts for a customer in dashboards or admin panels
+   * - Quickly identify which alerts a customer is currently triggering
+   * - Audit alert coverage for specific accounts
+   * - Filter alerts 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 alert configuration and threshold details
+   *   - Alert metadata including type, name, and last update time
+   * - `next_page`: Pagination cursor for retrieving additional results
+   *
+   * ### Usage guidelines:
+   *
+   * - Default behavior: Returns only enabled alerts unless alert_statuses filter is
+   *   specified
+   * - Pagination: Use the `next_page` cursor to retrieve all results for customers
+   *   with many alerts
    *
    * @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 alert for a customer, clearing
+   * any previous state and triggering a fresh assessment against current thresholds.
+   * This endpoint ensures alert accuracy after configuration changes or data
+   * corrections.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Clear false positive alerts after fixing data issues
+   * - Re-evaluate alerts after adjusting customer balances or credits
+   * - Test alert behavior during development and debugging
+   * - Resolve stuck alerts that may be in an incorrect state
+   * - Trigger immediate evaluation after threshold modifications
+   *
+   * ### Key response fields:
+   *
+   * - 200 Success: Confirmation that the alert 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,15 +157,17 @@ 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;
 
@@ -179,7 +291,7 @@ export namespace CustomerAlert {
     export interface GroupValue {
       key: string;
 
-      value: string;
+      value?: string;
     }
   }
 }
@@ -188,12 +300,6 @@ export interface AlertRetrieveResponse {
   data: CustomerAlert;
 }
 
-export interface AlertListResponse {
-  data: Array<CustomerAlert>;
-
-  next_page: string | null;
-}
-
 export interface AlertRetrieveParams {
   /**
    * The Metronome ID of the alert
@@ -205,6 +311,12 @@ export interface AlertRetrieveParams {
    */
   customer_id: string;
 
+  /**
+   * Only present for `spend_threshold_reached` alerts. Retrieve the alert for a
+   * specific group key-value pair.
+   */
+  group_values?: Array<AlertRetrieveParams.GroupValue>;
+
   /**
    * When parallel alerts are enabled during migration, this flag denotes whether to
    * fetch alerts for plans or contracts.
@@ -212,16 +324,23 @@ export interface AlertRetrieveParams {
   plans_or_contracts?: 'PLANS' | 'CONTRACTS';
 }
 
-export interface AlertListParams {
+export namespace AlertRetrieveParams {
   /**
-   * Body param: The Metronome ID of the customer
+   * Scopes alert evaluation to a specific presentation group key on individual line
+   * items. Only present for spend alerts.
    */
-  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
@@ -246,7 +365,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 {

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

@@ -1,12 +1,76 @@
 // 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 { CommitsBodyCursorPage } from '../../shared';
+import { APIPromise } from '../../../core/api-promise';
+import { BodyCursorPage, type BodyCursorPageParams, PagePromise } from '../../../core/pagination';
+import { RequestOptions } from '../../../internal/request-options';
 
 export class Commits extends APIResource {
   /**
-   * Create a new commit at the customer level.
+   * Creates customer-level commits that establish spending commitments for customers
+   * across their Metronome usage. Commits represent contracted spending obligations
+   * that can be either prepaid (paid upfront) or postpaid (billed later).
+   *
+   * Note: In most cases, you should add commitments directly to customer contracts
+   * using the contract/create or contract/edit APIs.
+   *
+   * ### Use this endpoint to:
+   *
+   * Use this endpoint when you need to establish customer-level spending commitments
+   * that can be applied across multiple contracts or scoped to specific contracts.
+   * Customer-level commits are ideal for:
+   *
+   * - Enterprise-wide minimum spending agreements that span multiple contracts
+   * - Multi-contract volume commitments with shared spending pools
+   * - Cross-contract discount tiers based on aggregate usage
+   *
+   * #### Commit type Requirements:
+   *
+   * - You must specify either "prepaid" or "postpaid" as the commit type:
+   * - Prepaid commits: Customer pays upfront; invoice_schedule is optional (if
+   *   omitted, creates a commit without an invoice)
+   * - Postpaid commits: Customer pays when the commitment expires (the end of the
+   *   access_schedule); invoice_schedule is required and must match access_schedule
+   *   totals.
+   *
+   * #### Billing configuration:
+   *
+   * - invoice_contract_id is required for postpaid commits and for prepaid commits
+   *   with billing (only optional for free prepaid commits)
+   * - For postpaid commits: access_schedule and invoice_schedule must have matching
+   *   amounts
+   * - For postpaid commits: only one schedule item is allowed in both schedules.
+   *
+   * #### Scoping flexibility:
+   *
+   * Customer-level commits can be configured in a few ways:
+   *
+   * - Contract-specific: Use the `applicable_contract_ids` field to limit the commit
+   *   to specific contracts
+   * - Cross-contract: Leave `applicable_contract_ids` empty to allow the commit to
+   *   be used across all of the customer's contracts
+   *
+   * #### Product targeting:
+   *
+   * Commits can be scoped to specific products using applicable_product_ids,
+   * applicable_product_tags, or specifiers, or left unrestricted to apply to all
+   * products.
+   *
+   * #### Priority considerations:
+   *
+   * When multiple commits are applicable, the one with the lower priority value will
+   * be consumed first. If there is a tie, contract level commits and credits will be
+   * applied before customer level commits and credits. Plan your priority scheme
+   * carefully to ensure commits are applied in the desired order.
+   *
+   * ### Usage guidelines:
+   *
+   * ⚠️ Preferred Alternative: In most cases, you should add commits directly to
+   * contracts using the create contract or edit contract APIs instead of creating
+   * customer-level commits. Contract-level commits provide better organization and
+   * are the recommended approach for standard use cases.
    *
    * @example
    * ```ts
@@ -36,35 +100,93 @@ export class Commits extends APIResource {
    *         timestamp: '2020-03-01T00:00:00.000Z',
    *       },
    *     ],
+   *     do_not_invoice: false,
    *   },
    *   name: 'My Commit',
    * });
    * ```
    */
-  create(body: CommitCreateParams, options?: Core.RequestOptions): Core.APIPromise<CommitCreateResponse> {
+  create(body: CommitCreateParams, options?: RequestOptions): APIPromise<CommitCreateResponse> {
     return this._client.post('/v1/contracts/customerCommits/create', { body, ...options });
   }
 
   /**
-   * List commits.
+   * Retrieve all commit agreements for a customer, including both prepaid and
+   * postpaid commitments. This endpoint provides comprehensive visibility into
+   * contractual spending obligations, enabling you to track commitment utilization
+   * and manage customer contracts effectively.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Display commitment balances and utilization in customer dashboards
+   * - Track prepaid commitment drawdown and remaining balances
+   * - Monitor postpaid commitment progress toward minimum thresholds
+   * - Build commitment tracking and forecasting tools
+   * - Show commitment history with optional ledger details
+   * - Manage rollover balances between contract periods
+   *
+   * ### Key response fields:
+   *
+   * An array of Commit objects containing:
+   *
+   * - Commit type: PREPAID (pay upfront) or POSTPAID (pay at true-up)
+   * - Rate type: COMMIT_RATE (discounted) or LIST_RATE (standard pricing)
+   * - Access schedule: When commitment funds become available
+   * - Invoice schedule: When the customer is billed
+   * - Product targeting: Which product(s) usage is eligible to draw from this commit
+   * - Optional ledger entries: Transaction history (if `include_ledgers=true`)
+   * - Balance information: Current available amount (if `include_balance=true`)
+   * - Rollover settings: Fraction of unused amount that carries forward
+   *
+   * ### Usage guidelines:
+   *
+   * - Pagination: Results limited to 25 commits per page; use 'next_page' for more
+   * - Date filtering options:
+   *   - `covering_date`: Commits active on a specific date
+   *   - `starting_at`: Commits with access on/after a date
+   *   - `effective_before`: Commits with access before a date (exclusive)
+   * - Scope options:
+   *   - `include_contract_commits`: Include contract-level commits (not just
+   *     customer-level)
+   *   - `include_archived`: Include archived commits and commits from archived
+   *     contracts
+   * - Performance considerations:
+   *   - include_ledgers: Adds detailed transaction history (slower)
+   *   - include_balance: Adds current balance calculation (slower)
+   * - Optional filtering: Use commit_id to retrieve a specific commit
    *
    * @example
    * ```ts
-   * const commits = await client.v1.customers.commits.list({
-   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
-   *   commit_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
-   *   include_ledgers: true,
-   * });
+   * // Automatically fetches more pages as needed.
+   * for await (const commit of client.v1.customers.commits.list(
+   *   {
+   *     customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *     commit_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   *     include_ledgers: true,
+   *   },
+   * )) {
+   *   // ...
+   * }
    * ```
    */
-  list(body: CommitListParams, options?: Core.RequestOptions): Core.APIPromise<CommitListResponse> {
-    return this._client.post('/v1/contracts/customerCommits/list', { body, ...options });
+  list(body: CommitListParams, options?: RequestOptions): PagePromise<CommitsBodyCursorPage, Shared.Commit> {
+    return this._client.getAPIList('/v1/contracts/customerCommits/list', BodyCursorPage<Shared.Commit>, {
+      body,
+      method: 'post',
+      ...options,
+    });
   }
 
   /**
-   * Pull forward the end date of a prepaid commit. Use the "edit a commit" endpoint
-   * to extend the end date of a prepaid commit, or to make other edits to the
-   * commit.
+   * Shortens the end date of a prepaid commit to terminate it earlier than
+   * originally scheduled. Use this endpoint when you need to cancel or reduce the
+   * duration of an existing prepaid commit. Only works with prepaid commit types and
+   * can only move the end date forward (earlier), not extend it.
+   *
+   * ### Usage guidelines:
+   *
+   * To extend commit end dates or make other comprehensive edits, use the 'edit
+   * commit' endpoint instead.
    *
    * @example
    * ```ts
@@ -79,8 +201,8 @@ export class Commits extends APIResource {
    */
   updateEndDate(
     body: CommitUpdateEndDateParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<CommitUpdateEndDateResponse> {
+    options?: RequestOptions,
+  ): APIPromise<CommitUpdateEndDateResponse> {
     return this._client.post('/v1/contracts/customerCommits/updateEndDate', { body, ...options });
   }
 }
@@ -89,12 +211,6 @@ export interface CommitCreateResponse {
   data: Shared.ID;
 }
 
-export interface CommitListResponse {
-  data: Array<Shared.Commit>;
-
-  next_page: string | null;
-}
-
 export interface CommitUpdateEndDateResponse {
   data: Shared.ID;
 }
@@ -142,6 +258,9 @@ export interface CommitCreateParams {
    */
   applicable_product_tags?: Array<string>;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields?: { [key: string]: string };
 
   /**
@@ -187,7 +306,7 @@ export interface CommitCreateParams {
    * specifiers to contribute to a commit's or credit's drawdown. This field cannot
    * be used together with `applicable_product_ids` or `applicable_product_tags`.
    */
-  specifiers?: Array<CommitCreateParams.Specifier>;
+  specifiers?: Array<Shared.CommitSpecifierInput>;
 
   /**
    * Prevents the creation of duplicates. If a request to create a commit or credit
@@ -240,6 +359,12 @@ export namespace CommitCreateParams {
      */
     credit_type_id?: string;
 
+    /**
+     * This field is only applicable to commit invoice schedules. If true, this
+     * schedule will not generate an invoice.
+     */
+    do_not_invoice?: boolean;
+
     /**
      * Enter the unit price and quantity for the charge or instead only send the
      * amount. If amount is sent, the unit price is assumed to be the amount and
@@ -324,26 +449,9 @@ export namespace CommitCreateParams {
       unit_price?: number;
     }
   }
-
-  export interface Specifier {
-    presentation_group_values?: { [key: string]: string };
-
-    pricing_group_values?: { [key: string]: string };
-
-    /**
-     * If provided, the specifier will only apply to the product with the specified ID.
-     */
-    product_id?: string;
-
-    /**
-     * If provided, the specifier will only apply to products with all the specified
-     * tags.
-     */
-    product_tags?: Array<string>;
-  }
 }
 
-export interface CommitListParams {
+export interface CommitListParams extends BodyCursorPageParams {
   customer_id: string;
 
   commit_id?: string;
@@ -380,16 +488,6 @@ export interface CommitListParams {
    */
   include_ledgers?: boolean;
 
-  /**
-   * The maximum number of commits to return. Defaults to 25.
-   */
-  limit?: number;
-
-  /**
-   * The next page token from a previous response.
-   */
-  next_page?: string;
-
   /**
    * Include only commits that have any access on or after the provided date
    */
@@ -424,10 +522,11 @@ export interface CommitUpdateEndDateParams {
 export declare namespace Commits {
   export {
     type CommitCreateResponse as CommitCreateResponse,
-    type CommitListResponse as CommitListResponse,
     type CommitUpdateEndDateResponse as CommitUpdateEndDateResponse,
     type CommitCreateParams as CommitCreateParams,
     type CommitListParams as CommitListParams,
     type CommitUpdateEndDateParams as CommitUpdateEndDateParams,
   };
 }
+
+export { type CommitsBodyCursorPage };