@metronome/sdk 0.3.0 → 2.0.0

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
@@ -42,30 +106,87 @@ export class Commits extends APIResource {
    * });
    * ```
    */
-  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
@@ -80,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 });
   }
 }
@@ -90,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;
 }
@@ -143,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 };
 
   /**
@@ -188,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
@@ -331,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;
@@ -387,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
    */
@@ -431,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 };

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

@@ -1,12 +1,63 @@
 // 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 { CreditsBodyCursorPage } from '../../shared';
+import { APIPromise } from '../../../core/api-promise';
+import { BodyCursorPage, type BodyCursorPageParams, PagePromise } from '../../../core/pagination';
+import { RequestOptions } from '../../../internal/request-options';
 
 export class Credits extends APIResource {
   /**
-   * Create a new credit at the customer level.
+   * Creates customer-level credits that provide spending allowances or free credit
+   * balances for customers across their Metronome usage. Note: In most cases, you
+   * should add credits directly to customer contracts using the contract/create or
+   * contract/edit APIs.
+   *
+   * ### Use this endpoint to:
+   *
+   * Use this endpoint when you need to provision credits directly at the customer
+   * level that can be applied across multiple contracts or scoped to specific
+   * contracts. Customer-level credits are ideal for:
+   *
+   * - Customer onboarding incentives that apply globally
+   * - Flexible spending allowances that aren't tied to a single contract
+   * - Migration scenarios where you need to preserve existing customer balances
+   *
+   * #### Scoping flexibility:
+   *
+   * Customer-level credits can be configured in two ways:
+   *
+   * - Contract-specific: Use the applicable_contract_ids field to limit the credit
+   *   to specific contracts
+   * - Cross-contract: Leave applicable_contract_ids empty to allow the credit to be
+   *   used across all of the customer's contracts
+   *
+   * #### Product Targeting:
+   *
+   * Credits can be scoped to specific products using `applicable_product_ids` or
+   * `applicable_product_tags`, or left unrestricted to apply to all products.
+   *
+   * #### Priority considerations:
+   *
+   * When multiple credits 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 credits are applied in the desired order.
+   *
+   * #### Access Schedule Required:
+   *
+   * You must provide an `access_schedule` that defines when and how much credit
+   * becomes available to the customer over time. This usually is aligned to the
+   * contract schedule or starts immediately and is set to expire in the future.
+   *
+   * ### Usage Guidelines:
+   *
+   * ⚠️ Preferred Alternative: In most cases, you should add credits directly to
+   * contracts using the contract/create or contract/edit APIs instead of creating
+   * customer-level credits. Contract-level credits provide better organization, and
+   * are easier for finance teams to recognize revenue, and are the recommended
+   * approach for most use cases.
    *
    * @example
    * ```ts
@@ -28,29 +79,85 @@ export class Credits extends APIResource {
    * });
    * ```
    */
-  create(body: CreditCreateParams, options?: Core.RequestOptions): Core.APIPromise<CreditCreateResponse> {
+  create(body: CreditCreateParams, options?: RequestOptions): APIPromise<CreditCreateResponse> {
     return this._client.post('/v1/contracts/customerCredits/create', { body, ...options });
   }
 
   /**
-   * List credits.
+   * Retrieve a detailed list of all credits available to a customer, including
+   * promotional credits and contract-specific credits. This endpoint provides
+   * comprehensive visibility into credit balances, access schedules, and usage
+   * rules, enabling you to build credit management interfaces and track available
+   * funding.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Display all available credits in customer billing dashboards
+   * - Show credit balances and expiration dates
+   * - Track credit usage history with optional ledger details
+   * - Build credit management and reporting tools
+   * - Monitor promotional credit utilization • Support customer inquiries about
+   *   available credits
+   *
+   * ### Key response fields:
+   *
+   * An array of Credit objects containing:
+   *
+   * - Credit details: Name, priority, and which applicable products/tags it applies
+   *   to
+   * - Product ID: The `product_id` of the credit. This is for external mapping into
+   *   your quote-to-cash stack, not the product it applies to.
+   * - Access schedule: When credits become available and expire
+   * - Optional ledger entries: Transaction history (if `include_ledgers=true`)
+   * - Balance information: Current available amount (if `include_balance=true`)
+   * - Metadata: Custom fields and usage specifiers
+   *
+   * ### Usage guidelines:
+   *
+   * - Pagination: Results limited to 25 commits per page; use next_page for more
+   * - Date filtering options:
+   *   - `covering_date`: Credits active on a specific date
+   *   - `starting_at`: Credits with access on/after a date
+   *   - `effective_before`: Credits with access before a date (exclusive)
+   * - Scope options:
+   *   - `include_contract_credits`: Include contract-level credits (not just
+   *     customer-level)
+   *   - `include_archived`: Include archived credits and credits from archived
+   *     contracts
+   * - Performance considerations:
+   *   - `include_ledgers`: Adds detailed transaction history (slower)
+   *   - `include_balance`: Adds current balance calculation (slower)
+   * - Optional filtering: Use credit_id to retrieve a specific commit
    *
    * @example
    * ```ts
-   * const credits = await client.v1.customers.credits.list({
-   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
-   *   credit_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
-   *   include_ledgers: true,
-   * });
+   * // Automatically fetches more pages as needed.
+   * for await (const credit of client.v1.customers.credits.list(
+   *   {
+   *     customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *     credit_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   *     include_ledgers: true,
+   *   },
+   * )) {
+   *   // ...
+   * }
    * ```
    */
-  list(body: CreditListParams, options?: Core.RequestOptions): Core.APIPromise<CreditListResponse> {
-    return this._client.post('/v1/contracts/customerCredits/list', { body, ...options });
+  list(body: CreditListParams, options?: RequestOptions): PagePromise<CreditsBodyCursorPage, Shared.Credit> {
+    return this._client.getAPIList('/v1/contracts/customerCredits/list', BodyCursorPage<Shared.Credit>, {
+      body,
+      method: 'post',
+      ...options,
+    });
   }
 
   /**
-   * Pull forward the end date of a credit. Use the "edit a credit" endpoint to
-   * extend the end date of a credit, or to make other edits to the credit.
+   * Shortens the end date of an existing customer credit to terminate it earlier
+   * than originally scheduled. Only allows moving end dates forward (earlier), not
+   * extending them.
+   *
+   * Note: To extend credit end dates or make comprehensive edits, use the 'edit
+   * credit' endpoint instead.
    *
    * @example
    * ```ts
@@ -64,8 +171,8 @@ export class Credits extends APIResource {
    */
   updateEndDate(
     body: CreditUpdateEndDateParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<CreditUpdateEndDateResponse> {
+    options?: RequestOptions,
+  ): APIPromise<CreditUpdateEndDateResponse> {
     return this._client.post('/v1/contracts/customerCredits/updateEndDate', { body, ...options });
   }
 }
@@ -74,12 +181,6 @@ export interface CreditCreateResponse {
   data: Shared.ID;
 }
 
-export interface CreditListResponse {
-  data: Array<Shared.Credit>;
-
-  next_page: string | null;
-}
-
 export interface CreditUpdateEndDateResponse {
   data: Shared.ID;
 }
@@ -118,6 +219,9 @@ export interface CreditCreateParams {
    */
   applicable_product_tags?: Array<string>;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields?: { [key: string]: string };
 
   /**
@@ -148,7 +252,7 @@ export interface CreditCreateParams {
    * 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<CreditCreateParams.Specifier>;
+  specifiers?: Array<Shared.CommitSpecifierInput>;
 
   /**
    * Prevents the creation of duplicates. If a request to create a commit or credit
@@ -187,26 +291,9 @@ export namespace CreditCreateParams {
       starting_at: string;
     }
   }
-
-  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 CreditListParams {
+export interface CreditListParams extends BodyCursorPageParams {
   customer_id: string;
 
   /**
@@ -243,16 +330,6 @@ export interface CreditListParams {
    */
   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 credits that have any access on or after the provided date
    */
@@ -280,10 +357,11 @@ export interface CreditUpdateEndDateParams {
 export declare namespace Credits {
   export {
     type CreditCreateResponse as CreditCreateResponse,
-    type CreditListResponse as CreditListResponse,
     type CreditUpdateEndDateResponse as CreditUpdateEndDateResponse,
     type CreditCreateParams as CreditCreateParams,
     type CreditListParams as CreditListParams,
     type CreditUpdateEndDateParams as CreditUpdateEndDateParams,
   };
 }
+
+export { type CreditsBodyCursorPage };