@metronome/sdk 0.3.0 → 2.0.0

package/src/resources/v1/contracts/rate-cards/rate-cards.ts

@@ -1,25 +1,23 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from "../../../../resource.js";
-import { isRequestOptions } from "../../../../core.js";
-import * as Core from "../../../../core.js";
-import * as Shared from "../../../shared.js";
-import * as NamedSchedulesAPI from "./named-schedules.js";
+import { APIResource } from '../../../../core/resource';
+import * as Shared from '../../../shared';
+import * as NamedSchedulesAPI from './named-schedules';
 import {
   NamedScheduleRetrieveParams,
   NamedScheduleRetrieveResponse,
   NamedScheduleUpdateParams,
   NamedSchedules,
-} from "./named-schedules.js";
-import * as ProductOrdersAPI from "./product-orders.js";
+} from './named-schedules';
+import * as ProductOrdersAPI from './product-orders';
 import {
   ProductOrderSetParams,
   ProductOrderSetResponse,
   ProductOrderUpdateParams,
   ProductOrderUpdateResponse,
   ProductOrders,
-} from "./product-orders.js";
-import * as RatesAPI from "./rates.js";
+} from './product-orders';
+import * as RatesAPI from './rates';
 import {
   RateAddManyParams,
   RateAddManyResponse,
@@ -29,8 +27,10 @@ import {
   RateListResponse,
   RateListResponsesCursorPage,
   Rates,
-} from "./rates.js";
-import { CursorPage, type CursorPageParams } from "../../../../pagination.js";
+} from './rates';
+import { APIPromise } from '../../../../core/api-promise';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../../../core/pagination';
+import { RequestOptions } from '../../../../internal/request-options';
 
 export class RateCards extends APIResource {
   productOrders: ProductOrdersAPI.ProductOrders = new ProductOrdersAPI.ProductOrders(this._client);
@@ -38,7 +38,39 @@ export class RateCards extends APIResource {
   namedSchedules: NamedSchedulesAPI.NamedSchedules = new NamedSchedulesAPI.NamedSchedules(this._client);
 
   /**
-   * Create a new rate card
+   * In Metronome, the rate card is the central location for your pricing. Rate cards
+   * were built with new product launches and pricing changes in mind - you can
+   * update your products and pricing in one place, and that change will be
+   * automatically propagated across your customer cohorts. Most clients need only
+   * maintain one or a few rate cards within Metronome.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Create a rate card with a name and description
+   * - Define the rate card's single underlying fiat currency, and any number of
+   *   conversion rates between that fiat currency and custom pricing units. You can
+   *   then add products and associated rates in the fiat currency or custom pricing
+   *   unit for which you have defined a conversion rate.
+   * - Set aliases for the rate card. Aliases are human-readable names that you can
+   *   use in the place of the id of the rate card when provisioning a customer's
+   *   contract. By using an alias, you can easily create a contract and provision a
+   *   customer by choosing the paygo rate card, without storing the rate card id in
+   *   your internal systems. This is helpful when launching a new rate card for
+   *   paygo customers, you can update the alias for paygo to be scheduled to be
+   *   assigned to the new rate card without updating your code.
+   *
+   * ### Key response fields:
+   *
+   * - The ID of the rate card you just created
+   *
+   * ### Usage guidelines:
+   *
+   * - After creating a rate card, you can now use the addRate or addRates endpoints
+   *   to add products and their prices to it
+   * - A rate card alias can only be used by one rate card at a time. If you create a
+   *   contract with a rate card alias that is already in use by another rate card,
+   *   the original rate card's alias schedule will be updated. The alias will
+   *   reference the rate card to which it was most recently assigned.
    *
    * @example
    * ```ts
@@ -60,13 +92,14 @@ export class RateCards extends APIResource {
    * );
    * ```
    */
-  create(body: RateCardCreateParams, options?: Core.RequestOptions): Core.APIPromise<RateCardCreateResponse> {
+  create(body: RateCardCreateParams, options?: RequestOptions): APIPromise<RateCardCreateResponse> {
     return this._client.post('/v1/contract-pricing/rate-cards/create', { body, ...options });
   }
 
   /**
-   * Get a specific rate card NOTE: Use `/contract-pricing/rate-cards/getRates` to
-   * retrieve rate card rates.
+   * Return details for a specific rate card including name, description, and
+   * aliases. This endpoint does not return rates - use the dedicated getRates or
+   * getRateSchedule endpoints to understand the rates on a rate card.
    *
    * @example
    * ```ts
@@ -76,15 +109,63 @@ export class RateCards extends APIResource {
    *   });
    * ```
    */
-  retrieve(
-    body: RateCardRetrieveParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<RateCardRetrieveResponse> {
+  retrieve(body: RateCardRetrieveParams, options?: RequestOptions): APIPromise<RateCardRetrieveResponse> {
     return this._client.post('/v1/contract-pricing/rate-cards/get', { body, ...options });
   }
 
   /**
-   * Update a rate card
+   * Update the metadata properties of an existing rate card, including its name,
+   * description, and aliases. This endpoint is designed for managing rate card
+   * identity and reference aliases rather than modifying pricing rates.
+   *
+   * Modifies the descriptive properties and alias configuration of a rate card
+   * without affecting the underlying pricing rates or schedules. This allows you to
+   * update how a rate card is identified and referenced throughout your system.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Rate card renaming: Update display names or descriptions for organizational
+   *   clarity
+   * - Alias management: Add, modify, or schedule alias transitions for seamless rate
+   *   card migrations
+   * - Documentation updates: Keep rate card descriptions current with business
+   *   context
+   * - Self-serve provisioning setup: Configure aliases to enable code-free rate card
+   *   transitions
+   *
+   * #### Active contract impact:
+   *
+   * - Alias changes: Already-created contracts continue using their originally
+   *   assigned rate cards.
+   * - Other changes made using this endpoint will only impact the Metronome UI.
+   *
+   * #### Grandfathering existing PLG customer pricing:
+   *
+   * - Rate card aliases support scheduled transitions, enabling seamless rate card
+   *   migrations for new customers, allowing existing customers to be grandfathered
+   *   into their existing prices without code. Note that there are multiple
+   *   mechanisms to support grandfathering in Metronome.
+   *
+   * #### How scheduled aliases work for PLG grandfathering:
+   *
+   * Initial setup:
+   *
+   * - Add alias to current rate card: Assign a stable alias (e.g.,
+   *   "standard-pricing") to your active rate card
+   * - Reference alias during contract creation: Configure your self-serve workflow
+   *   to create contracts using `rate_card_alias` instead of direct `rate_card_id`
+   * - Automatic resolution: New contracts referencing the alias automatically
+   *   resolve to the rate card associated with the alias at the point in time of
+   *   provisioning
+   *
+   * #### Grandfathering process:
+   *
+   * - Create new rate card: Build your new rate card with updated pricing structure
+   * - Schedule alias transition: Add the same alias to the new rate card with a
+   *   `starting_at` timestamp
+   * - Automatic cutover: Starting at the scheduled time, new contracts created in
+   *   your PLG workflow using that alias will automatically reference the new rate
+   *   card
    *
    * @example
    * ```ts
@@ -97,13 +178,14 @@ export class RateCards extends APIResource {
    * );
    * ```
    */
-  update(body: RateCardUpdateParams, options?: Core.RequestOptions): Core.APIPromise<RateCardUpdateResponse> {
+  update(body: RateCardUpdateParams, options?: RequestOptions): APIPromise<RateCardUpdateResponse> {
     return this._client.post('/v1/contract-pricing/rate-cards/update', { body, ...options });
   }
 
   /**
-   * List rate cards NOTE: Use `/contract-pricing/rate-cards/getRates` to retrieve
-   * rate card rates.
+   * List all rate cards. Returns rate card IDs, names, descriptions, aliases, and
+   * other details. To view the rates associated with a given rate card, use the
+   * getRates or getRateSchedule endpoints.
    *
    * @example
    * ```ts
@@ -114,21 +196,11 @@ export class RateCards extends APIResource {
    * ```
    */
   list(
-    params?: RateCardListParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<RateCardListResponsesCursorPage, RateCardListResponse>;
-  list(
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<RateCardListResponsesCursorPage, RateCardListResponse>;
-  list(
-    params?: RateCardListParams | Core.RequestOptions,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<RateCardListResponsesCursorPage, RateCardListResponse> {
-    if (isRequestOptions(params)) {
-      return this.list(undefined, params);
-    }
+    params: RateCardListParams | null | undefined = undefined,
+    options?: RequestOptions,
+  ): PagePromise<RateCardListResponsesCursorPage, RateCardListResponse> {
     const { limit, next_page, body } = params ?? {};
-    return this._client.getAPIList('/v1/contract-pricing/rate-cards/list', RateCardListResponsesCursorPage, {
+    return this._client.getAPIList('/v1/contract-pricing/rate-cards/list', CursorPage<RateCardListResponse>, {
       query: { limit, next_page },
       body: body,
       method: 'post',
@@ -137,7 +209,11 @@ export class RateCards extends APIResource {
   }
 
   /**
-   * Archive a rate card
+   * Permanently disable a rate card by archiving it, preventing use in new contracts
+   * while preserving existing contract pricing. Use this when retiring old pricing
+   * models, consolidating rate cards, or removing outdated pricing structures.
+   * Returns the archived rate card ID and stops the rate card from appearing in
+   * contract creation workflows.
    *
    * @example
    * ```ts
@@ -147,16 +223,23 @@ export class RateCards extends APIResource {
    *   });
    * ```
    */
-  archive(
-    body: RateCardArchiveParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<RateCardArchiveResponse> {
+  archive(body: RateCardArchiveParams, options?: RequestOptions): APIPromise<RateCardArchiveResponse> {
     return this._client.post('/v1/contract-pricing/rate-cards/archive', { body, ...options });
   }
 
   /**
-   * Get all rates for a rate card from starting_at (either in perpetuity or until
-   * ending_before, if provided)
+   * A rate card defines the prices that you charge for your products. Rate cards
+   * support scheduled changes over time, to allow you to easily roll out pricing
+   * changes and new product launches across your customer base. Use this endpoint to
+   * understand the rate schedule `starting_at` a given date, optionally filtering
+   * the list of rates returned based on product id or pricing group values. For
+   * example, you may want to display a schedule of upcoming price changes for a
+   * given product in your product experience - use this endpoint to fetch that
+   * information from its source of truth in Metronome.
+   *
+   * If you want to understand the rates for a specific customer's contract,
+   * inclusive of contract-level overrides, use the `getContractRateSchedule`
+   * endpoint.
    *
    * @example
    * ```ts
@@ -178,8 +261,8 @@ export class RateCards extends APIResource {
    */
   retrieveRateSchedule(
     params: RateCardRetrieveRateScheduleParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<RateCardRetrieveRateScheduleResponse> {
+    options?: RequestOptions,
+  ): APIPromise<RateCardRetrieveRateScheduleResponse> {
     const { limit, next_page, ...body } = params;
     return this._client.post('/v1/contract-pricing/rate-cards/getRateSchedule', {
       query: { limit, next_page },
@@ -189,7 +272,7 @@ export class RateCards extends APIResource {
   }
 }
 
-export class RateCardListResponsesCursorPage extends CursorPage<RateCardListResponse> {}
+export type RateCardListResponsesCursorPage = CursorPage<RateCardListResponse>;
 
 export interface RateCardCreateResponse {
   data: Shared.ID;
@@ -213,6 +296,9 @@ export namespace RateCardRetrieveResponse {
 
     credit_type_conversions?: Array<Data.CreditTypeConversion>;
 
+    /**
+     * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+     */
     custom_fields?: { [key: string]: string };
 
     description?: string;
@@ -254,6 +340,9 @@ export interface RateCardListResponse {
 
   credit_type_conversions?: Array<RateCardListResponse.CreditTypeConversion>;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields?: { [key: string]: string };
 
   description?: string;
@@ -291,6 +380,9 @@ export namespace RateCardRetrieveRateScheduleResponse {
   export interface Data {
     entitled: boolean;
 
+    /**
+     * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+     */
     product_custom_fields: { [key: string]: string };
 
     product_id: string;
@@ -309,32 +401,12 @@ export namespace RateCardRetrieveRateScheduleResponse {
      * A distinct rate on the rate card. You can choose to use this rate rather than
      * list rate when consuming a credit or commit.
      */
-    commit_rate?: Data.CommitRate;
+    commit_rate?: Shared.CommitRate;
 
     ending_before?: string;
 
     pricing_group_values?: { [key: string]: string };
   }
-
-  export namespace Data {
-    /**
-     * A distinct rate on the rate card. You can choose to use this rate rather than
-     * list rate when consuming a credit or commit.
-     */
-    export interface CommitRate {
-      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
-
-      /**
-       * Commit rate price. For FLAT rate_type, this must be >=0.
-       */
-      price?: number;
-
-      /**
-       * Only set for TIERED rate_type.
-       */
-      tiers?: Array<Shared.Tier>;
-    }
-  }
 }
 
 export interface RateCardCreateParams {
@@ -355,6 +427,9 @@ export interface RateCardCreateParams {
    */
   credit_type_conversions?: Array<RateCardCreateParams.CreditTypeConversion>;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields?: { [key: string]: string };
 
   description?: string;
@@ -490,10 +565,8 @@ export namespace RateCardRetrieveRateScheduleParams {
   }
 }
 
-RateCards.RateCardListResponsesCursorPage = RateCardListResponsesCursorPage;
 RateCards.ProductOrders = ProductOrders;
 RateCards.Rates = Rates;
-RateCards.RateListResponsesCursorPage = RateListResponsesCursorPage;
 RateCards.NamedSchedules = NamedSchedules;
 
 export declare namespace RateCards {
@@ -504,7 +577,7 @@ export declare namespace RateCards {
     type RateCardListResponse as RateCardListResponse,
     type RateCardArchiveResponse as RateCardArchiveResponse,
     type RateCardRetrieveRateScheduleResponse as RateCardRetrieveRateScheduleResponse,
-    RateCardListResponsesCursorPage as RateCardListResponsesCursorPage,
+    type RateCardListResponsesCursorPage as RateCardListResponsesCursorPage,
     type RateCardCreateParams as RateCardCreateParams,
     type RateCardRetrieveParams as RateCardRetrieveParams,
     type RateCardUpdateParams as RateCardUpdateParams,
@@ -526,7 +599,7 @@ export declare namespace RateCards {
     type RateListResponse as RateListResponse,
     type RateAddResponse as RateAddResponse,
     type RateAddManyResponse as RateAddManyResponse,
-    RateListResponsesCursorPage as RateListResponsesCursorPage,
+    type RateListResponsesCursorPage as RateListResponsesCursorPage,
     type RateListParams as RateListParams,
     type RateAddParams as RateAddParams,
     type RateAddManyParams as RateAddManyParams,

package/src/resources/v1/contracts/rate-cards/rates.ts

@@ -1,13 +1,22 @@
 // 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 { CursorPage, type CursorPageParams } from "../../../../pagination.js";
+import { APIResource } from '../../../../core/resource';
+import * as Shared from '../../../shared';
+import { APIPromise } from '../../../../core/api-promise';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../../../core/pagination';
+import { RequestOptions } from '../../../../internal/request-options';
 
 export class Rates extends APIResource {
   /**
-   * Get all rates for a rate card at a point in time
+   * Understand the rate schedule at a given timestamp, optionally filtering the list
+   * of rates returned based on properties such as `product_id` and
+   * `pricing_group_values`. For example, you may want to display the current price
+   * for a given product in your product experience - use this endpoint to fetch that
+   * information from its source of truth in Metronome.
+   *
+   * If you want to understand the rates for a specific customer's contract,
+   * inclusive of contract-level overrides, use the `getContractRateSchedule`
+   * endpoint.
    *
    * @example
    * ```ts
@@ -33,10 +42,10 @@ export class Rates extends APIResource {
    */
   list(
     params: RateListParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<RateListResponsesCursorPage, RateListResponse> {
+    options?: RequestOptions,
+  ): PagePromise<RateListResponsesCursorPage, RateListResponse> {
     const { limit, next_page, ...body } = params;
-    return this._client.getAPIList('/v1/contract-pricing/rate-cards/getRates', RateListResponsesCursorPage, {
+    return this._client.getAPIList('/v1/contract-pricing/rate-cards/getRates', CursorPage<RateListResponse>, {
       query: { limit, next_page },
       body,
       method: 'post',
@@ -61,7 +70,7 @@ export class Rates extends APIResource {
    *   });
    * ```
    */
-  add(body: RateAddParams, options?: Core.RequestOptions): Core.APIPromise<RateAddResponse> {
+  add(body: RateAddParams, options?: RequestOptions): APIPromise<RateAddResponse> {
     return this._client.post('/v1/contract-pricing/rate-cards/addRate', { body, ...options });
   }
 
@@ -100,16 +109,19 @@ export class Rates extends APIResource {
    *   });
    * ```
    */
-  addMany(body: RateAddManyParams, options?: Core.RequestOptions): Core.APIPromise<RateAddManyResponse> {
+  addMany(body: RateAddManyParams, options?: RequestOptions): APIPromise<RateAddManyResponse> {
     return this._client.post('/v1/contract-pricing/rate-cards/addRates', { body, ...options });
   }
 }
 
-export class RateListResponsesCursorPage extends CursorPage<RateListResponse> {}
+export type RateListResponsesCursorPage = CursorPage<RateListResponse>;
 
 export interface RateListResponse {
   entitled: boolean;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   product_custom_fields: { [key: string]: string };
 
   product_id: string;
@@ -128,33 +140,13 @@ export interface RateListResponse {
    * A distinct rate on the rate card. You can choose to use this rate rather than
    * list rate when consuming a credit or commit.
    */
-  commit_rate?: RateListResponse.CommitRate;
+  commit_rate?: Shared.CommitRate;
 
   ending_before?: string;
 
   pricing_group_values?: { [key: string]: string };
 }
 
-export namespace RateListResponse {
-  /**
-   * A distinct rate on the rate card. You can choose to use this rate rather than
-   * list rate when consuming a credit or commit.
-   */
-  export interface CommitRate {
-    rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
-
-    /**
-     * Commit rate price. For FLAT rate_type, this must be >=0.
-     */
-    price?: number;
-
-    /**
-     * Only set for TIERED rate_type.
-     */
-    tiers?: Array<Shared.Tier>;
-  }
-}
-
 export interface RateAddResponse {
   data: RateAddResponse.Data;
 }
@@ -167,7 +159,7 @@ export namespace RateAddResponse {
      * A distinct rate on the rate card. You can choose to use this rate rather than
      * list rate when consuming a credit or commit.
      */
-    commit_rate?: Data.CommitRate;
+    commit_rate?: Shared.CommitRate;
 
     credit_type?: Shared.CreditTypeData;
 
@@ -212,26 +204,6 @@ export namespace RateAddResponse {
      */
     use_list_prices?: boolean;
   }
-
-  export namespace Data {
-    /**
-     * A distinct rate on the rate card. You can choose to use this rate rather than
-     * list rate when consuming a credit or commit.
-     */
-    export interface CommitRate {
-      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
-
-      /**
-       * Commit rate price. For FLAT rate_type, this must be >=0.
-       */
-      price?: number;
-
-      /**
-       * Only set for TIERED rate_type.
-       */
-      tiers?: Array<Shared.Tier>;
-    }
-  }
 }
 
 export interface RateAddManyResponse {
@@ -323,7 +295,7 @@ export interface RateAddParams {
    * A distinct rate on the rate card. You can choose to use this rate rather than
    * list rate when consuming a credit or commit.
    */
-  commit_rate?: RateAddParams.CommitRate;
+  commit_rate?: Shared.CommitRate;
 
   /**
    * The Metronome ID of the credit type to associate with price, defaults to USD
@@ -380,26 +352,6 @@ export interface RateAddParams {
   use_list_prices?: boolean;
 }
 
-export namespace RateAddParams {
-  /**
-   * A distinct rate on the rate card. You can choose to use this rate rather than
-   * list rate when consuming a credit or commit.
-   */
-  export interface CommitRate {
-    rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
-
-    /**
-     * Commit rate price. For FLAT rate_type, this must be >=0.
-     */
-    price?: number;
-
-    /**
-     * Only set for TIERED rate_type.
-     */
-    tiers?: Array<Shared.Tier>;
-  }
-}
-
 export interface RateAddManyParams {
   rate_card_id: string;
 
@@ -432,7 +384,7 @@ export namespace RateAddManyParams {
      * A distinct rate on the rate card. You can choose to use this rate rather than
      * list rate when consuming a credit or commit.
      */
-    commit_rate?: Rate.CommitRate;
+    commit_rate?: Shared.CommitRate;
 
     /**
      * "The Metronome ID of the credit type to associate with price, defaults to USD
@@ -488,36 +440,14 @@ export namespace RateAddManyParams {
      */
     use_list_prices?: boolean;
   }
-
-  export namespace Rate {
-    /**
-     * A distinct rate on the rate card. You can choose to use this rate rather than
-     * list rate when consuming a credit or commit.
-     */
-    export interface CommitRate {
-      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
-
-      /**
-       * Commit rate price. For FLAT rate_type, this must be >=0.
-       */
-      price?: number;
-
-      /**
-       * Only set for TIERED rate_type.
-       */
-      tiers?: Array<Shared.Tier>;
-    }
-  }
 }
 
-Rates.RateListResponsesCursorPage = RateListResponsesCursorPage;
-
 export declare namespace Rates {
   export {
     type RateListResponse as RateListResponse,
     type RateAddResponse as RateAddResponse,
     type RateAddManyResponse as RateAddManyResponse,
-    RateListResponsesCursorPage as RateListResponsesCursorPage,
+    type RateListResponsesCursorPage as RateListResponsesCursorPage,
     type RateListParams as RateListParams,
     type RateAddParams as RateAddParams,
     type RateAddManyParams as RateAddManyParams,

package/src/resources/v1/contracts/rate-cards.ts

@@ -1,3 +1,3 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export * from "./rate-cards/index.js";
+export * from './rate-cards/index';

package/src/resources/v1/contracts.ts

@@ -1,3 +1,3 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export * from "./contracts/index.js";
+export * from './contracts/index';