@metronome/sdk 0.1.0-beta.8 → 0.1.0

package/src/resources/{customers → v1/customers}/index.ts

@@ -8,14 +8,14 @@ export {
   type AlertRetrieveParams,
   type AlertListParams,
   type AlertResetParams,
-} from './alerts';
+} from "./alerts.js";
 export {
   BillingConfig,
   type BillingConfigRetrieveResponse,
   type BillingConfigCreateParams,
   type BillingConfigRetrieveParams,
   type BillingConfigDeleteParams,
-} from './billing-config';
+} from "./billing-config.js";
 export {
   Commits,
   type CommitCreateResponse,
@@ -24,7 +24,7 @@ export {
   type CommitCreateParams,
   type CommitListParams,
   type CommitUpdateEndDateParams,
-} from './commits';
+} from "./commits.js";
 export {
   Credits,
   type CreditCreateResponse,
@@ -33,7 +33,7 @@ export {
   type CreditCreateParams,
   type CreditListParams,
   type CreditUpdateEndDateParams,
-} from './credits';
+} from "./credits.js";
 export {
   CustomerDetailsCursorPage,
   CustomerListBillableMetricsResponsesCursorPage,
@@ -46,6 +46,7 @@ export {
   type CustomerArchiveResponse,
   type CustomerListBillableMetricsResponse,
   type CustomerListCostsResponse,
+  type CustomerPreviewEventsResponse,
   type CustomerSetNameResponse,
   type CustomerCreateParams,
   type CustomerRetrieveParams,
@@ -53,10 +54,11 @@ export {
   type CustomerArchiveParams,
   type CustomerListBillableMetricsParams,
   type CustomerListCostsParams,
+  type CustomerPreviewEventsParams,
   type CustomerSetIngestAliasesParams,
   type CustomerSetNameParams,
   type CustomerUpdateConfigParams,
-} from './customers';
+} from "./customers.js";
 export {
   InvoicesCursorPage,
   InvoiceListBreakdownsResponsesCursorPage,
@@ -69,13 +71,13 @@ export {
   type InvoiceListParams,
   type InvoiceAddChargeParams,
   type InvoiceListBreakdownsParams,
-} from './invoices';
+} from "./invoices.js";
 export {
   NamedSchedules,
   type NamedScheduleRetrieveResponse,
   type NamedScheduleRetrieveParams,
   type NamedScheduleUpdateParams,
-} from './named-schedules';
+} from "./named-schedules.js";
 export {
   PlanListResponsesCursorPage,
   PlanListPriceAdjustmentsResponsesCursorPage,
@@ -88,4 +90,4 @@ export {
   type PlanAddParams,
   type PlanEndParams,
   type PlanListPriceAdjustmentsParams,
-} from './plans';
+} from "./plans.js";

package/src/resources/{customers → v1/customers}/invoices.ts

@@ -1,32 +1,52 @@
 // 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,
     options?: Core.RequestOptions,
   ): Core.APIPromise<InvoiceRetrieveResponse> {
     const { customer_id, invoice_id, ...query } = params;
-    return this._client.get(`/customers/${customer_id}/invoices/${invoice_id}`, { query, ...options });
+    return this._client.get(`/v1/customers/${customer_id}/invoices/${invoice_id}`, { query, ...options });
   }
 
   /**
    * 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,
     options?: Core.RequestOptions,
   ): Core.PagePromise<InvoicesCursorPage, Invoice> {
     const { customer_id, ...query } = params;
-    return this._client.getAPIList(`/customers/${customer_id}/invoices`, InvoicesCursorPage, {
+    return this._client.getAPIList(`/v1/customers/${customer_id}/invoices`, InvoicesCursorPage, {
       query,
       ...options,
     });
@@ -34,18 +54,50 @@ 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,
     options?: Core.RequestOptions,
   ): Core.APIPromise<InvoiceAddChargeResponse> {
     const { customer_id, ...body } = params;
-    return this._client.post(`/customers/${customer_id}/addCharge`, { body, ...options });
+    return this._client.post(`/v1/customers/${customer_id}/addCharge`, { body, ...options });
   }
 
   /**
    * List daily or hourly invoice breakdowns for a given customer, optionally
-   * filtered by status, date range, and/or credit type.
+   * filtered by status, date range, and/or credit type. Important considerations:
+   *
+   * - 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,
@@ -53,7 +105,7 @@ export class Invoices extends APIResource {
   ): Core.PagePromise<InvoiceListBreakdownsResponsesCursorPage, InvoiceListBreakdownsResponse> {
     const { customer_id, ...query } = params;
     return this._client.getAPIList(
-      `/customers/${customer_id}/invoices/breakdowns`,
+      `/v1/customers/${customer_id}/invoices/breakdowns`,
       InvoiceListBreakdownsResponsesCursorPage,
       { query, ...options },
     );
@@ -86,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;
 
@@ -98,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)
@@ -123,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;
 
@@ -156,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 };
 
     /**
-     * only present for beta contract invoices
+     * ID of the discount applied to this line item.
+     */
+    discount_id?: string;
+
+    /**
+     * The line item's end date (exclusive).
      */
     ending_before?: string;
 
@@ -204,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.
      */
@@ -227,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;
@@ -303,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;
 
@@ -370,6 +436,9 @@ export namespace Invoice {
       }
     }
 
+    /**
+     * Populated if the line item has a tiered price.
+     */
     export interface Tier {
       level: number;
 
@@ -456,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/{customers → v1/customers}/named-schedules.ts

@@ -1,26 +1,47 @@
 // 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,
     options?: Core.RequestOptions,
   ): Core.APIPromise<NamedScheduleRetrieveResponse> {
-    return this._client.post('/customers/getNamedSchedule', { body, ...options });
+    return this._client.post('/v1/customers/getNamedSchedule', { body, ...options });
   }
 
   /**
    * 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('/customers/updateNamedSchedule', {
+    return this._client.post('/v1/customers/updateNamedSchedule', {
       body,
       ...options,
       headers: { Accept: '*/*', ...options?.headers },

package/src/resources/{customers → v1/customers}/plans.ts

@@ -1,20 +1,30 @@
 // 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,
     options?: Core.RequestOptions,
   ): Core.PagePromise<PlanListResponsesCursorPage, PlanListResponse> {
     const { customer_id, ...query } = params;
-    return this._client.getAPIList(`/customers/${customer_id}/plans`, PlanListResponsesCursorPage, {
+    return this._client.getAPIList(`/v1/customers/${customer_id}/plans`, PlanListResponsesCursorPage, {
       query,
       ...options,
     });
@@ -24,24 +34,60 @@ 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;
-    return this._client.post(`/customers/${customer_id}/plans/add`, { body, ...options });
+    return this._client.post(`/v1/customers/${customer_id}/plans/add`, { body, ...options });
   }
 
   /**
    * 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;
-    return this._client.post(`/customers/${customer_id}/plans/${customer_plan_id}/end`, { body, ...options });
+    return this._client.post(`/v1/customers/${customer_id}/plans/${customer_plan_id}/end`, {
+      body,
+      ...options,
+    });
   }
 
   /**
    * 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,
@@ -49,7 +95,7 @@ export class Plans extends APIResource {
   ): Core.PagePromise<PlanListPriceAdjustmentsResponsesCursorPage, PlanListPriceAdjustmentsResponse> {
     const { customer_id, customer_plan_id, ...query } = params;
     return this._client.getAPIList(
-      `/customers/${customer_id}/plans/${customer_plan_id}/priceAdjustments`,
+      `/v1/customers/${customer_id}/plans/${customer_plan_id}/priceAdjustments`,
       PlanListPriceAdjustmentsResponsesCursorPage,
       { query, ...options },
     );
@@ -66,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

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