@metronome/sdk 0.3.0 → 2.0.0

package/resources/v1/customers/credits.js

@@ -2,10 +2,59 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Credits = void 0;
-const resource_1 = require("../../../resource.js");
+const resource_1 = require("../../../core/resource.js");
+const pagination_1 = require("../../../core/pagination.js");
 class Credits extends resource_1.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
@@ -31,23 +80,79 @@ class Credits extends resource_1.APIResource {
         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, options) {
-        return this._client.post('/v1/contracts/customerCredits/list', { body, ...options });
+        return this._client.getAPIList('/v1/contracts/customerCredits/list', (pagination_1.BodyCursorPage), {
+            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

package/resources/v1/customers/credits.js.map

@@ -1 +1 @@
-{"version":3,"file":"credits.js","sourceRoot":"","sources":["../../../src/resources/v1/customers/credits.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,mDAAgD;AAIhD,MAAa,OAAQ,SAAQ,sBAAW;IACtC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,IAAwB,EAAE,OAA6B;QAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sCAAsC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAsB,EAAE,OAA6B;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oCAAoC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,aAAa,CACX,IAA+B,EAC/B,OAA6B;QAE7B,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,6CAA6C,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;CACF;AAhED,0BAgEC"}
+{"version":3,"file":"credits.js","sourceRoot":"","sources":["../../../src/resources/v1/customers/credits.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,wDAAqD;AAIrD,4DAAkG;AAGlG,MAAa,OAAQ,SAAQ,sBAAW;IACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsEG;IACH,MAAM,CAAC,IAAwB,EAAE,OAAwB;QACvD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sCAAsC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2DG;IACH,IAAI,CAAC,IAAsB,EAAE,OAAwB;QACnD,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,oCAAoC,EAAE,CAAA,2BAA6B,CAAA,EAAE;YAClG,IAAI;YACJ,MAAM,EAAE,MAAM;YACd,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CACX,IAA+B,EAC/B,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,6CAA6C,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;CACF;AAxKD,0BAwKC"}

package/resources/v1/customers/credits.mjs

@@ -1,8 +1,57 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-import { APIResource } from "../../../resource.mjs";
+import { APIResource } from "../../../core/resource.mjs";
+import { BodyCursorPage } from "../../../core/pagination.mjs";
 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,23 +77,79 @@ export class Credits extends APIResource {
         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, options) {
-        return this._client.post('/v1/contracts/customerCredits/list', { body, ...options });
+        return this._client.getAPIList('/v1/contracts/customerCredits/list', (BodyCursorPage), {
+            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

package/resources/v1/customers/credits.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"credits.mjs","sourceRoot":"","sources":["../../../src/resources/v1/customers/credits.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;AAItB,MAAM,OAAO,OAAQ,SAAQ,WAAW;IACtC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,IAAwB,EAAE,OAA6B;QAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sCAAsC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAsB,EAAE,OAA6B;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oCAAoC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,aAAa,CACX,IAA+B,EAC/B,OAA6B;QAE7B,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,6CAA6C,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;CACF"}
+{"version":3,"file":"credits.mjs","sourceRoot":"","sources":["../../../src/resources/v1/customers/credits.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAIf,EAAE,cAAc,EAA0C;AAGjE,MAAM,OAAO,OAAQ,SAAQ,WAAW;IACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsEG;IACH,MAAM,CAAC,IAAwB,EAAE,OAAwB;QACvD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sCAAsC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2DG;IACH,IAAI,CAAC,IAAsB,EAAE,OAAwB;QACnD,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,oCAAoC,EAAE,CAAA,cAA6B,CAAA,EAAE;YAClG,IAAI;YACJ,MAAM,EAAE,MAAM;YACd,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CACX,IAA+B,EAC/B,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,6CAA6C,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;CACF"}