@metronome/sdk 0.1.0-beta.9 → 0.2.0

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

@@ -1,13 +1,23 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../resource';
-import * as Core from '../../../core';
-import * as Shared from '../../shared';
-import { CursorPage, type CursorPageParams } from '../../../pagination';
+import { APIResource } from "../../../resource.js";
+import * as Core from "../../../core.js";
+import * as Shared from "../../shared.js";
+import { CursorPage, type CursorPageParams } from "../../../pagination.js";
 
 export class Invoices extends APIResource {
   /**
    * Fetch a specific invoice for a given customer.
+   *
+   * @example
+   * ```ts
+   * const invoice = await client.v1.customers.invoices.retrieve(
+   *   {
+   *     customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *     invoice_id: '6a37bb88-8538-48c5-b37b-a41c836328bd',
+   *   },
+   * );
+   * ```
    */
   retrieve(
     params: InvoiceRetrieveParams,
@@ -20,6 +30,16 @@ export class Invoices extends APIResource {
   /**
    * List all invoices for a given customer, optionally filtered by status, date
    * range, and/or credit type.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const invoice of client.v1.customers.invoices.list(
+   *   { customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     params: InvoiceListParams,
@@ -34,6 +54,21 @@ export class Invoices extends APIResource {
 
   /**
    * Add a one time charge to the specified invoice
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.customers.invoices.addCharge({
+   *     customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *     charge_id: '5ae4b726-1ebe-439c-9190-9831760ba195',
+   *     customer_plan_id:
+   *       'a23b3cf4-47fb-4c3f-bb3d-9e64f7704015',
+   *     description: 'One time charge',
+   *     invoice_start_timestamp: '2024-01-01T00:00:00Z',
+   *     price: 250,
+   *     quantity: 1,
+   *   });
+   * ```
    */
   addCharge(
     params: InvoiceAddChargeParams,
@@ -49,6 +84,20 @@ export class Invoices extends APIResource {
    *
    * - If we receive backdated usage after an invoice has been finalized, the
    *   backdated usage will be included in the response and usage numbers may differ.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const invoiceListBreakdownsResponse of client.v1.customers.invoices.listBreakdowns(
+   *   {
+   *     customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *     ending_before: '2019-12-27T18:11:19.117Z',
+   *     starting_on: '2019-12-27T18:11:19.117Z',
+   *   },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listBreakdowns(
     params: InvoiceListBreakdownsParams,
@@ -89,7 +138,7 @@ export interface Invoice {
    */
   billable_status?: 'billable' | 'unbillable';
 
-  contract_custom_fields?: Record<string, string>;
+  contract_custom_fields?: { [key: string]: string };
 
   contract_id?: string;
 
@@ -101,9 +150,9 @@ export interface Invoice {
    */
   created_at?: string;
 
-  custom_fields?: Record<string, unknown>;
+  custom_fields?: { [key: string]: unknown };
 
-  customer_custom_fields?: Record<string, string>;
+  customer_custom_fields?: { [key: string]: string };
 
   /**
    * End of the usage period this invoice covers (UTC)
@@ -126,14 +175,14 @@ export interface Invoice {
    */
   netsuite_sales_order_id?: string;
 
-  plan_custom_fields?: Record<string, string>;
+  plan_custom_fields?: { [key: string]: string };
 
   plan_id?: string;
 
   plan_name?: string;
 
   /**
-   * only present for beta contract invoices with reseller royalties
+   * Only present for contract invoices with reseller royalties.
    */
   reseller_royalty?: Invoice.ResellerRoyalty;
 
@@ -159,46 +208,45 @@ export namespace Invoice {
     total: number;
 
     /**
-     * only present for beta contract invoices
+     * Details about the credit or commit that was applied to this line item. Only
+     * present on line items with product of `USAGE`, `SUBSCRIPTION` or `COMPOSITE`
+     * types.
      */
     applied_commit_or_credit?: LineItem.AppliedCommitOrCredit;
 
-    /**
-     * only present for beta contract invoices
-     */
-    commit_custom_fields?: Record<string, string>;
+    commit_custom_fields?: { [key: string]: string };
 
     /**
-     * only present for beta contract invoices
+     * For line items with product of `USAGE`, `SUBSCRIPTION`, or `COMPOSITE` types,
+     * the ID of the credit or commit that was applied to this line item. For line
+     * items with product type of `FIXED`, the ID of the prepaid or postpaid commit
+     * that is being paid for.
      */
     commit_id?: string;
 
-    /**
-     * only present for beta contract invoices. This field's availability is dependent
-     * on your client's configuration.
-     */
     commit_netsuite_item_id?: string;
 
-    /**
-     * only present for beta contract invoices. This field's availability is dependent
-     * on your client's configuration.
-     */
     commit_netsuite_sales_order_id?: string;
 
-    /**
-     * only present for beta contract invoices
-     */
     commit_segment_id?: string;
 
     /**
-     * only present for beta contract invoices
+     * `PrepaidCommit` (for commit types `PREPAID` and `CREDIT`) or `PostpaidCommit`
+     * (for commit type `POSTPAID`).
      */
     commit_type?: string;
 
-    custom_fields?: Record<string, string>;
+    custom_fields?: { [key: string]: string };
+
+    discount_custom_fields?: { [key: string]: string };
+
+    /**
+     * ID of the discount applied to this line item.
+     */
+    discount_id?: string;
 
     /**
-     * only present for beta contract invoices
+     * The line item's end date (exclusive).
      */
     ending_before?: string;
 
@@ -207,12 +255,12 @@ export namespace Invoice {
     group_value?: string | null;
 
     /**
-     * only present for beta contract invoices
+     * Indicates whether the line item is prorated for `SUBSCRIPTION` type product.
      */
     is_prorated?: boolean;
 
     /**
-     * Only present for contract invoices and when the include_list_prices query
+     * Only present for contract invoices and when the `include_list_prices` query
      * parameter is set to true. This will include the list rate for the charge if
      * applicable. Only present for usage and subscription line items.
      */
@@ -230,74 +278,89 @@ export namespace Invoice {
      */
     netsuite_invoice_billing_start?: string;
 
-    /**
-     * only present for beta contract invoices. This field's availability is dependent
-     * on your client's configuration.
-     */
     netsuite_item_id?: string;
 
     /**
-     * only present for beta contract invoices
+     * Only present for line items paying for a postpaid commit true-up.
      */
     postpaid_commit?: LineItem.PostpaidCommit;
 
     /**
-     * if presentation groups are used, this will contain the values used to break down
-     * the line item
+     * Includes the presentation group values associated with this line item if
+     * presentation group keys are used.
      */
-    presentation_group_values?: Record<string, string | null>;
+    presentation_group_values?: { [key: string]: string | null };
 
     /**
-     * if pricing groups are used, this will contain the values used to calculate the
-     * price
+     * Includes the pricing group values associated with this line item if dimensional
+     * pricing is used.
      */
-    pricing_group_values?: Record<string, string>;
+    pricing_group_values?: { [key: string]: string };
 
-    product_custom_fields?: Record<string, string>;
+    product_custom_fields?: { [key: string]: string };
 
+    /**
+     * ID of the product associated with the line item.
+     */
     product_id?: string;
 
-    product_type?: string;
-
     /**
-     * only present for beta contract invoices
+     * The current product tags associated with the line item's `product_id`.
      */
-    professional_service_custom_fields?: Record<string, string>;
+    product_tags?: Array<string>;
 
     /**
-     * only present for beta contract invoices
+     * The type of the line item's product. Possible values are `FixedProductListItem`
+     * (for `FIXED` type products), `UsageProductListItem` (for `USAGE` type products),
+     * `SubscriptionProductListItem` (for `SUBSCRIPTION` type products) or
+     * `CompositeProductListItem` (for `COMPOSITE` type products). For scheduled
+     * charges, commit and credit payments, the value is `FixedProductListItem`.
      */
+    product_type?: string;
+
+    professional_service_custom_fields?: { [key: string]: string };
+
     professional_service_id?: string;
 
+    /**
+     * The quantity associated with the line item.
+     */
     quantity?: number;
 
     reseller_type?: 'AWS' | 'AWS_PRO_SERVICE' | 'GCP' | 'GCP_PRO_SERVICE';
 
-    scheduled_charge_custom_fields?: Record<string, string>;
+    scheduled_charge_custom_fields?: { [key: string]: string };
 
     /**
-     * only present for beta contract invoices
+     * ID of scheduled charge.
      */
     scheduled_charge_id?: string;
 
     /**
-     * only present for beta contract invoices
+     * The line item's start date (inclusive).
      */
     starting_at?: string;
 
     sub_line_items?: Array<LineItem.SubLineItem>;
 
+    subscription_custom_fields?: { [key: string]: string };
+
+    /**
+     * Populated if the line item has a tiered price.
+     */
     tier?: LineItem.Tier;
 
     /**
-     * only present for beta contract invoices
+     * The unit price associated with the line item.
      */
     unit_price?: number;
   }
 
   export namespace LineItem {
     /**
-     * only present for beta contract invoices
+     * Details about the credit or commit that was applied to this line item. Only
+     * present on line items with product of `USAGE`, `SUBSCRIPTION` or `COMPOSITE`
+     * types.
      */
     export interface AppliedCommitOrCredit {
       id: string;
@@ -306,14 +369,14 @@ export namespace Invoice {
     }
 
     /**
-     * only present for beta contract invoices
+     * Only present for line items paying for a postpaid commit true-up.
      */
     export interface PostpaidCommit {
       id: string;
     }
 
     export interface SubLineItem {
-      custom_fields: Record<string, string>;
+      custom_fields: { [key: string]: string };
 
       name: string;
 
@@ -373,6 +436,9 @@ export namespace Invoice {
       }
     }
 
+    /**
+     * Populated if the line item has a tiered price.
+     */
     export interface Tier {
       level: number;
 
@@ -459,13 +525,13 @@ export namespace Invoice {
 
     total: number;
 
-    credit_grant_custom_fields?: Record<string, string>;
+    credit_grant_custom_fields?: { [key: string]: string };
 
     credit_grant_id?: string;
   }
 
   /**
-   * only present for beta contract invoices with reseller royalties
+   * Only present for contract invoices with reseller royalties.
    */
   export interface ResellerRoyalty {
     fraction: string;

package/src/resources/v1/customers/named-schedules.ts

@@ -1,12 +1,22 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../resource';
-import * as Core from '../../../core';
+import { APIResource } from "../../../resource.js";
+import * as Core from "../../../core.js";
 
 export class NamedSchedules extends APIResource {
   /**
    * Get a named schedule for the given customer. This endpoint's availability is
    * dependent on your client's configuration.
+   *
+   * @example
+   * ```ts
+   * const namedSchedule =
+   *   await client.v1.customers.namedSchedules.retrieve({
+   *     customer_id: '9b85c1c1-5238-4f2a-a409-61412905e1e1',
+   *     schedule_name: 'my-schedule',
+   *     covering_date: '2022-02-15T00:00:00Z',
+   *   });
+   * ```
    */
   retrieve(
     body: NamedScheduleRetrieveParams,
@@ -18,6 +28,17 @@ export class NamedSchedules extends APIResource {
   /**
    * Update a named schedule for the given customer. This endpoint's availability is
    * dependent on your client's configuration.
+   *
+   * @example
+   * ```ts
+   * await client.v1.customers.namedSchedules.update({
+   *   customer_id: '9b85c1c1-5238-4f2a-a409-61412905e1e1',
+   *   schedule_name: 'my-schedule',
+   *   starting_at: '2022-02-01T00:00:00Z',
+   *   value: { my_key: 'my_value' },
+   *   ending_before: '2022-02-15T00:00:00Z',
+   * });
+   * ```
    */
   update(body: NamedScheduleUpdateParams, options?: Core.RequestOptions): Core.APIPromise<void> {
     return this._client.post('/v1/customers/updateNamedSchedule', {

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

@@ -1,13 +1,23 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../resource';
-import * as Core from '../../../core';
-import * as Shared from '../../shared';
-import { CursorPage, type CursorPageParams } from '../../../pagination';
+import { APIResource } from "../../../resource.js";
+import * as Core from "../../../core.js";
+import * as Shared from "../../shared.js";
+import { CursorPage, type CursorPageParams } from "../../../pagination.js";
 
 export class Plans extends APIResource {
   /**
    * List the given customer's plans in reverse-chronological order.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const planListResponse of client.v1.customers.plans.list(
+   *   { customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     params: PlanListParams,
@@ -24,6 +34,16 @@ export class Plans extends APIResource {
    * Associate an existing customer with a plan for a specified date range. See the
    * [price adjustments documentation](https://plans-docs.metronome.com/pricing/managing-plans/#price-adjustments)
    * for details on the price adjustments.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.plans.add({
+   *   customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *   plan_id: 'd2c06dae-9549-4d7d-bc04-b78dd3d241b8',
+   *   starting_on: '2021-02-01T00:00:00Z',
+   *   ending_before: '2022-02-01T00:00:00Z',
+   * });
+   * ```
    */
   add(params: PlanAddParams, options?: Core.RequestOptions): Core.APIPromise<PlanAddResponse> {
     const { customer_id, ...body } = params;
@@ -32,6 +52,15 @@ export class Plans extends APIResource {
 
   /**
    * Change the end date of a customer's plan.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.plans.end({
+   *   customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *   customer_plan_id: '7aa11640-0703-4600-8eb9-293f535a6b74',
+   *   ending_before: '2021-02-01T00:00:00Z',
+   * });
+   * ```
    */
   end(params: PlanEndParams, options?: Core.RequestOptions): Core.APIPromise<PlanEndResponse> {
     const { customer_id, customer_plan_id, ...body } = params;
@@ -45,6 +74,20 @@ export class Plans extends APIResource {
    * Lists a customer plans adjustments. See the
    * [price adjustments documentation](https://plans-docs.metronome.com/pricing/managing-plans/#price-adjustments)
    * for details.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const planListPriceAdjustmentsResponse of client.v1.customers.plans.listPriceAdjustments(
+   *   {
+   *     customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *     customer_plan_id:
+   *       '7aa11640-0703-4600-8eb9-293f535a6b74',
+   *   },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listPriceAdjustments(
     params: PlanListPriceAdjustmentsParams,
@@ -69,7 +112,7 @@ export interface PlanListResponse {
    */
   id: string;
 
-  custom_fields: Record<string, string>;
+  custom_fields: { [key: string]: string };
 
   plan_description: string;
 

package/src/resources/v1/customers.ts

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

package/src/resources/v1/dashboards.ts

@@ -1,13 +1,39 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../resource';
-import * as Core from '../../core';
+import { APIResource } from "../../resource.js";
+import * as Core from "../../core.js";
 
 export class Dashboards extends APIResource {
   /**
    * Retrieve an embeddable dashboard url for a customer. The dashboard can be
    * embedded using an iframe in a website. This will show information such as usage
    * data and customer invoices.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.dashboards.getEmbeddableURL({
+   *     customer_id: '4db51251-61de-4bfe-b9ce-495e244f3491',
+   *     dashboard: 'invoices',
+   *     bm_group_key_overrides: [
+   *       {
+   *         group_key_name: 'tenant_id',
+   *         display_name: 'Org ID',
+   *         value_display_names: {
+   *           '48ecb18f358f': 'Cluster EU',
+   *           e358f3ce242d: 'Cluster APAC',
+   *         },
+   *       },
+   *     ],
+   *     color_overrides: [
+   *       { name: 'Gray_dark', value: '#ff0000' },
+   *     ],
+   *     dashboard_options: [
+   *       { key: 'show_zero_usage_line_items', value: 'false' },
+   *       { key: 'hide_voided_invoices', value: 'true' },
+   *     ],
+   *   });
+   * ```
    */
   getEmbeddableURL(
     body: DashboardGetEmbeddableURLParams,
@@ -33,7 +59,7 @@ export interface DashboardGetEmbeddableURLParams {
   /**
    * The type of dashboard to retrieve.
    */
-  dashboard: 'invoices' | 'usage' | 'credits';
+  dashboard: 'invoices' | 'usage' | 'credits' | 'commits_and_credits';
 
   /**
    * Optional list of billable metric group key overrides
@@ -67,7 +93,7 @@ export namespace DashboardGetEmbeddableURLParams {
      * <key, value> pairs of the billable metric group key values and their display
      * names. e.g. {"a": "Asia", "b": "Euro"}
      */
-    value_display_names?: Record<string, unknown>;
+    value_display_names?: { [key: string]: unknown };
   }
 
   export interface ColorOverride {
@@ -93,7 +119,9 @@ export namespace DashboardGetEmbeddableURLParams {
       | 'UsageLine_8'
       | 'UsageLine_9'
       | 'Primary_green'
-      | 'Primary_red';
+      | 'Primary_red'
+      | 'Progress_bar'
+      | 'Progress_bar_background';
 
     /**
      * Hex value representation of the color