@metronome/sdk 0.2.0 → 1.0.0

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 };