@metronome/sdk 0.2.0 → 1.0.0

package/src/resources/v1/dashboards.ts

@@ -1,13 +1,40 @@
 // 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 { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
 
 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.
+   * Generate secure, embeddable dashboard URLs that allow you to seamlessly
+   * integrate Metronome's billing visualizations directly into your application.
+   * This endpoint creates authenticated iframe-ready URLs for customer-specific
+   * dashboards, providing a white-labeled billing experience without building custom
+   * UI.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Embed billing dashboards directly in your customer portal or admin interface
+   * - Provide self-service access to invoices, usage data, and credit balances
+   * - Build white-labeled billing experiences with minimal development effort
+   *
+   * ### Key response fields:
+   *
+   * - A secure, time-limited URL that can be embedded in an iframe
+   * - The URL includes authentication tokens and configuration parameters
+   * - URLs are customer-specific and respect your security settings
+   *
+   * ### Usage guidelines:
+   *
+   * - Dashboard types: Choose from `invoices`, `usage`, or `commits_and_credits`
+   * - Customization options:
+   *   - `dashboard_options`: Configure whether you want invoices to show zero usage
+   *     line items
+   *   - `color_overrides`: Match your brand's color palette
+   *   - `bm_group_key_overrides`: Customize how dimensions are displayed (for the
+   *     usage embeddable dashboard)
+   * - Iframe implementation: Embed the returned URL directly in an iframe element
+   * - Responsive design: Dashboards automatically adapt to container dimensions
    *
    * @example
    * ```ts
@@ -37,8 +64,8 @@ export class Dashboards extends APIResource {
    */
   getEmbeddableURL(
     body: DashboardGetEmbeddableURLParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<DashboardGetEmbeddableURLResponse> {
+    options?: RequestOptions,
+  ): APIPromise<DashboardGetEmbeddableURLResponse> {
     return this._client.post('/v1/dashboards/getEmbeddableUrl', { body, ...options });
   }
 }

package/src/resources/v1/index.ts

@@ -6,15 +6,14 @@ export {
   type AlertArchiveResponse,
   type AlertCreateParams,
   type AlertArchiveParams,
-} from "./alerts.js";
+} from './alerts';
 export {
-  AuditLogListResponsesCursorPage,
   AuditLogs,
   type AuditLogListResponse,
   type AuditLogListParams,
-} from "./audit-logs.js";
+  type AuditLogListResponsesCursorPage,
+} from './audit-logs';
 export {
-  BillableMetricListResponsesCursorPage,
   BillableMetrics,
   type BillableMetricCreateResponse,
   type BillableMetricRetrieveResponse,
@@ -24,7 +23,8 @@ export {
   type BillableMetricRetrieveParams,
   type BillableMetricListParams,
   type BillableMetricArchiveParams,
-} from "./billable-metrics.js";
+  type BillableMetricListResponsesCursorPage,
+} from './billable-metrics';
 export {
   Contracts,
   type ContractCreateResponse,
@@ -51,9 +51,9 @@ export {
   type ContractScheduleProServicesInvoiceParams,
   type ContractSetUsageFilterParams,
   type ContractUpdateEndDateParams,
-} from "./contracts/index.js";
+  type ContractListBalancesResponsesBodyCursorPage,
+} from './contracts/index';
 export {
-  CreditGrantListResponsesCursorPage,
   CreditGrants,
   type CreditLedgerEntry,
   type RolloverAmountMaxAmount,
@@ -68,7 +68,9 @@ export {
   type CreditGrantEditParams,
   type CreditGrantListEntriesParams,
   type CreditGrantVoidParams,
-} from "./credit-grants.js";
+  type CreditGrantListResponsesCursorPage,
+  type CreditGrantListEntriesResponsesCursorPageWithoutLimit,
+} from './credit-grants';
 export {
   CustomFields,
   type CustomFieldListKeysResponse,
@@ -77,11 +79,9 @@ export {
   type CustomFieldListKeysParams,
   type CustomFieldRemoveKeyParams,
   type CustomFieldSetValuesParams,
-} from "./custom-fields.js";
+  type CustomFieldListKeysResponsesCursorPageWithoutLimit,
+} from './custom-fields';
 export {
-  CustomerDetailsCursorPage,
-  CustomerListBillableMetricsResponsesCursorPage,
-  CustomerListCostsResponsesCursorPage,
   Customers,
   type Customer,
   type CustomerDetail,
@@ -91,6 +91,7 @@ export {
   type CustomerListBillableMetricsResponse,
   type CustomerListCostsResponse,
   type CustomerPreviewEventsResponse,
+  type CustomerRetrieveBillingConfigurationsResponse,
   type CustomerSetNameResponse,
   type CustomerCreateParams,
   type CustomerRetrieveParams,
@@ -99,26 +100,28 @@ export {
   type CustomerListBillableMetricsParams,
   type CustomerListCostsParams,
   type CustomerPreviewEventsParams,
+  type CustomerRetrieveBillingConfigurationsParams,
+  type CustomerSetBillingConfigurationsParams,
   type CustomerSetIngestAliasesParams,
   type CustomerSetNameParams,
   type CustomerUpdateConfigParams,
-} from "./customers/index.js";
+  type CustomerDetailsCursorPage,
+  type CustomerListBillableMetricsResponsesCursorPage,
+  type CustomerListCostsResponsesCursorPage,
+} from './customers/index';
 export {
   Dashboards,
   type DashboardGetEmbeddableURLResponse,
   type DashboardGetEmbeddableURLParams,
-} from "./dashboards.js";
+} from './dashboards';
 export {
   Invoices,
   type InvoiceRegenerateResponse,
   type InvoiceVoidResponse,
   type InvoiceRegenerateParams,
   type InvoiceVoidParams,
-} from "./invoices.js";
+} from './invoices';
 export {
-  PlanListResponsesCursorPage,
-  PlanListChargesResponsesCursorPage,
-  PlanListCustomersResponsesCursorPage,
   Plans,
   type PlanDetail,
   type PlanListResponse,
@@ -129,16 +132,18 @@ export {
   type PlanGetDetailsParams,
   type PlanListChargesParams,
   type PlanListCustomersParams,
-} from "./plans.js";
+  type PlanListResponsesCursorPage,
+  type PlanListChargesResponsesCursorPage,
+  type PlanListCustomersResponsesCursorPage,
+} from './plans';
 export {
-  PricingUnitListResponsesCursorPage,
   PricingUnits,
   type PricingUnitListResponse,
   type PricingUnitListParams,
-} from "./pricing-units.js";
-export { Services, type ServiceListResponse } from "./services.js";
+  type PricingUnitListResponsesCursorPage,
+} from './pricing-units';
+export { Services, type ServiceListResponse } from './services';
 export {
-  UsageListWithGroupsResponsesCursorPage,
   Usage,
   type UsageListResponse,
   type UsageListWithGroupsResponse,
@@ -147,5 +152,7 @@ export {
   type UsageIngestParams,
   type UsageListWithGroupsParams,
   type UsageSearchParams,
-} from "./usage.js";
-export { V1 } from "./v1.js";
+  type UsageListResponsesCursorPageWithoutLimit,
+  type UsageListWithGroupsResponsesCursorPage,
+} from './usage';
+export { V1 } from './v1';

package/src/resources/v1/invoices.ts

@@ -1,11 +1,29 @@
 // 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 { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
 
 export class Invoices extends APIResource {
   /**
-   * Regenerate a voided contract invoice
+   * This endpoint regenerates a voided invoice and recalculates the invoice based on
+   * up-to-date rates, available balances, and other fees regardless of the billing
+   * period.
+   *
+   * ### Use this endpoint to:
+   *
+   * Recalculate an invoice with updated rate terms, available balance, and fees to
+   * correct billing disputes or discrepancies
+   *
+   * ### Key response fields:
+   *
+   * The regenerated invoice id, which is distinct from the previously voided
+   * invoice.
+   *
+   * ### Usage guidelines:
+   *
+   * If an invoice is attached to a contract with a billing provider on it, the
+   * regenerated invoice will be distributed based on the configuration.
    *
    * @example
    * ```ts
@@ -14,15 +32,16 @@ export class Invoices extends APIResource {
    * });
    * ```
    */
-  regenerate(
-    body: InvoiceRegenerateParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<InvoiceRegenerateResponse> {
+  regenerate(body: InvoiceRegenerateParams, options?: RequestOptions): APIPromise<InvoiceRegenerateResponse> {
     return this._client.post('/v1/invoices/regenerate', { body, ...options });
   }
 
   /**
-   * Void an invoice
+   * Permanently cancels an invoice by setting its status to voided, preventing
+   * collection and removing it from customer billing. Use this to correct billing
+   * errors, cancel incorrect charges, or handle disputed invoices that should not be
+   * collected. Returns the voided invoice ID with the status change applied
+   * immediately to stop any payment processing.
    *
    * @example
    * ```ts
@@ -31,7 +50,7 @@ export class Invoices extends APIResource {
    * });
    * ```
    */
-  void(body: InvoiceVoidParams, options?: Core.RequestOptions): Core.APIPromise<InvoiceVoidResponse> {
+  void(body: InvoiceVoidParams, options?: RequestOptions): APIPromise<InvoiceVoidResponse> {
     return this._client.post('/v1/invoices/void', { body, ...options });
   }
 }

package/src/resources/v1/plans.ts

@@ -1,11 +1,12 @@
 // 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 CustomersAPI from "./customers/customers.js";
-import { CursorPage, type CursorPageParams } from "../../pagination.js";
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import * as CustomersAPI from './customers/customers';
+import { APIPromise } from '../../core/api-promise';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
 
 export class Plans extends APIResource {
   /**
@@ -20,18 +21,10 @@ export class Plans extends APIResource {
    * ```
    */
   list(
-    query?: PlanListParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<PlanListResponsesCursorPage, PlanListResponse>;
-  list(options?: Core.RequestOptions): Core.PagePromise<PlanListResponsesCursorPage, PlanListResponse>;
-  list(
-    query: PlanListParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<PlanListResponsesCursorPage, PlanListResponse> {
-    if (isRequestOptions(query)) {
-      return this.list({}, query);
-    }
-    return this._client.getAPIList('/v1/plans', PlanListResponsesCursorPage, { query, ...options });
+    query: PlanListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<PlanListResponsesCursorPage, PlanListResponse> {
+    return this._client.getAPIList('/v1/plans', CursorPage<PlanListResponse>, { query, ...options });
   }
 
   /**
@@ -44,12 +37,9 @@ export class Plans extends APIResource {
    * });
    * ```
    */
-  getDetails(
-    params: PlanGetDetailsParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<PlanGetDetailsResponse> {
+  getDetails(params: PlanGetDetailsParams, options?: RequestOptions): APIPromise<PlanGetDetailsResponse> {
     const { plan_id } = params;
-    return this._client.get(`/v1/planDetails/${plan_id}`, options);
+    return this._client.get(path`/v1/planDetails/${plan_id}`, options);
   }
 
   /**
@@ -67,13 +57,14 @@ export class Plans extends APIResource {
    */
   listCharges(
     params: PlanListChargesParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<PlanListChargesResponsesCursorPage, PlanListChargesResponse> {
+    options?: RequestOptions,
+  ): PagePromise<PlanListChargesResponsesCursorPage, PlanListChargesResponse> {
     const { plan_id, ...query } = params;
-    return this._client.getAPIList(`/v1/planDetails/${plan_id}/charges`, PlanListChargesResponsesCursorPage, {
-      query,
-      ...options,
-    });
+    return this._client.getAPIList(
+      path`/v1/planDetails/${plan_id}/charges`,
+      CursorPage<PlanListChargesResponse>,
+      { query, ...options },
+    );
   }
 
   /**
@@ -92,26 +83,29 @@ export class Plans extends APIResource {
    */
   listCustomers(
     params: PlanListCustomersParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<PlanListCustomersResponsesCursorPage, PlanListCustomersResponse> {
+    options?: RequestOptions,
+  ): PagePromise<PlanListCustomersResponsesCursorPage, PlanListCustomersResponse> {
     const { plan_id, ...query } = params;
     return this._client.getAPIList(
-      `/v1/planDetails/${plan_id}/customers`,
-      PlanListCustomersResponsesCursorPage,
+      path`/v1/planDetails/${plan_id}/customers`,
+      CursorPage<PlanListCustomersResponse>,
       { query, ...options },
     );
   }
 }
 
-export class PlanListResponsesCursorPage extends CursorPage<PlanListResponse> {}
+export type PlanListResponsesCursorPage = CursorPage<PlanListResponse>;
 
-export class PlanListChargesResponsesCursorPage extends CursorPage<PlanListChargesResponse> {}
+export type PlanListChargesResponsesCursorPage = CursorPage<PlanListChargesResponse>;
 
-export class PlanListCustomersResponsesCursorPage extends CursorPage<PlanListCustomersResponse> {}
+export type PlanListCustomersResponsesCursorPage = CursorPage<PlanListCustomersResponse>;
 
 export interface PlanDetail {
   id: string;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields: { [key: string]: string };
 
   name: string;
@@ -186,6 +180,9 @@ export interface PlanListResponse {
 
   name: string;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields?: { [key: string]: string };
 }
 
@@ -200,6 +197,9 @@ export interface PlanListChargesResponse {
 
   credit_type: Shared.CreditTypeData;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields: { [key: string]: string };
 
   name: string;
@@ -273,6 +273,9 @@ export namespace PlanListCustomersResponse {
   export interface PlanDetails {
     id: string;
 
+    /**
+     * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+     */
     custom_fields: { [key: string]: string };
 
     customer_plan_id: string;
@@ -324,10 +327,6 @@ export interface PlanListCustomersParams extends CursorPageParams {
   status?: 'all' | 'active' | 'ended' | 'upcoming';
 }
 
-Plans.PlanListResponsesCursorPage = PlanListResponsesCursorPage;
-Plans.PlanListChargesResponsesCursorPage = PlanListChargesResponsesCursorPage;
-Plans.PlanListCustomersResponsesCursorPage = PlanListCustomersResponsesCursorPage;
-
 export declare namespace Plans {
   export {
     type PlanDetail as PlanDetail,
@@ -335,9 +334,9 @@ export declare namespace Plans {
     type PlanGetDetailsResponse as PlanGetDetailsResponse,
     type PlanListChargesResponse as PlanListChargesResponse,
     type PlanListCustomersResponse as PlanListCustomersResponse,
-    PlanListResponsesCursorPage as PlanListResponsesCursorPage,
-    PlanListChargesResponsesCursorPage as PlanListChargesResponsesCursorPage,
-    PlanListCustomersResponsesCursorPage as PlanListCustomersResponsesCursorPage,
+    type PlanListResponsesCursorPage as PlanListResponsesCursorPage,
+    type PlanListChargesResponsesCursorPage as PlanListChargesResponsesCursorPage,
+    type PlanListCustomersResponsesCursorPage as PlanListCustomersResponsesCursorPage,
     type PlanListParams as PlanListParams,
     type PlanGetDetailsParams as PlanGetDetailsParams,
     type PlanListChargesParams as PlanListChargesParams,

package/src/resources/v1/pricing-units.ts

@@ -1,13 +1,17 @@
 // 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 { CursorPage, type CursorPageParams } from "../../pagination.js";
+import { APIResource } from '../../core/resource';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
 
 export class PricingUnits extends APIResource {
   /**
-   * List all pricing units (known in the API by the legacy term "credit types").
+   * List all pricing units. All fiat currency types (for example, USD or GBP) will
+   * be included, as well as any custom pricing units that were configured. Custom
+   * pricing units can be used to charge for usage in a non-fiat pricing unit, for
+   * example AI credits.
+   *
+   * Note: The USD (cents) pricing unit is 2714e483-4ff1-48e4-9e25-ac732e8f24f2.
    *
    * @example
    * ```ts
@@ -18,27 +22,17 @@ export class PricingUnits extends APIResource {
    * ```
    */
   list(
-    query?: PricingUnitListParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<PricingUnitListResponsesCursorPage, PricingUnitListResponse>;
-  list(
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<PricingUnitListResponsesCursorPage, PricingUnitListResponse>;
-  list(
-    query: PricingUnitListParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<PricingUnitListResponsesCursorPage, PricingUnitListResponse> {
-    if (isRequestOptions(query)) {
-      return this.list({}, query);
-    }
-    return this._client.getAPIList('/v1/credit-types/list', PricingUnitListResponsesCursorPage, {
+    query: PricingUnitListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<PricingUnitListResponsesCursorPage, PricingUnitListResponse> {
+    return this._client.getAPIList('/v1/credit-types/list', CursorPage<PricingUnitListResponse>, {
       query,
       ...options,
     });
   }
 }
 
-export class PricingUnitListResponsesCursorPage extends CursorPage<PricingUnitListResponse> {}
+export type PricingUnitListResponsesCursorPage = CursorPage<PricingUnitListResponse>;
 
 export interface PricingUnitListResponse {
   id?: string;
@@ -50,12 +44,10 @@ export interface PricingUnitListResponse {
 
 export interface PricingUnitListParams extends CursorPageParams {}
 
-PricingUnits.PricingUnitListResponsesCursorPage = PricingUnitListResponsesCursorPage;
-
 export declare namespace PricingUnits {
   export {
     type PricingUnitListResponse as PricingUnitListResponse,
-    PricingUnitListResponsesCursorPage as PricingUnitListResponsesCursorPage,
+    type PricingUnitListResponsesCursorPage as PricingUnitListResponsesCursorPage,
     type PricingUnitListParams as PricingUnitListParams,
   };
 }

package/src/resources/v1/services.ts

@@ -1,21 +1,24 @@
 // 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 { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
 
 export class Services extends APIResource {
   /**
-   * Fetches a list of services used by Metronome and the associated IP addresses. IP
-   * addresses are not necessarily unique between services. In most cases, IP
-   * addresses will appear in the list at least 30 days before they are used for the
-   * first time.
+   * Gets Metronome's service registry with associated IP addresses for security
+   * allowlisting and firewall configuration. Use this endpoint to maintain an
+   * up-to-date list of IPs that your systems should trust for Metronome
+   * communications. Returns service names and their current IP ranges, with new IPs
+   * typically appearing 30+ days before first use to ensure smooth allowlist
+   * updates.
    *
    * @example
    * ```ts
    * const services = await client.v1.services.list();
    * ```
    */
-  list(options?: Core.RequestOptions): Core.APIPromise<ServiceListResponse> {
+  list(options?: RequestOptions): APIPromise<ServiceListResponse> {
     return this._client.get('/v1/services', options);
   }
 }