@metronome/sdk 0.3.0 → 2.0.0

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

@@ -1,9 +1,11 @@
 // 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';
+import { path } from '../../../internal/utils/path';
 
 export class Plans extends APIResource {
   /**
@@ -21,10 +23,10 @@ export class Plans extends APIResource {
    */
   list(
     params: PlanListParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<PlanListResponsesCursorPage, PlanListResponse> {
+    options?: RequestOptions,
+  ): PagePromise<PlanListResponsesCursorPage, PlanListResponse> {
     const { customer_id, ...query } = params;
-    return this._client.getAPIList(`/v1/customers/${customer_id}/plans`, PlanListResponsesCursorPage, {
+    return this._client.getAPIList(path`/v1/customers/${customer_id}/plans`, CursorPage<PlanListResponse>, {
       query,
       ...options,
     });
@@ -45,9 +47,9 @@ export class Plans extends APIResource {
    * });
    * ```
    */
-  add(params: PlanAddParams, options?: Core.RequestOptions): Core.APIPromise<PlanAddResponse> {
+  add(params: PlanAddParams, options?: RequestOptions): APIPromise<PlanAddResponse> {
     const { customer_id, ...body } = params;
-    return this._client.post(`/v1/customers/${customer_id}/plans/add`, { body, ...options });
+    return this._client.post(path`/v1/customers/${customer_id}/plans/add`, { body, ...options });
   }
 
   /**
@@ -62,9 +64,9 @@ export class Plans extends APIResource {
    * });
    * ```
    */
-  end(params: PlanEndParams, options?: Core.RequestOptions): Core.APIPromise<PlanEndResponse> {
+  end(params: PlanEndParams, options?: RequestOptions): APIPromise<PlanEndResponse> {
     const { customer_id, customer_plan_id, ...body } = params;
-    return this._client.post(`/v1/customers/${customer_id}/plans/${customer_plan_id}/end`, {
+    return this._client.post(path`/v1/customers/${customer_id}/plans/${customer_plan_id}/end`, {
       body,
       ...options,
     });
@@ -91,20 +93,20 @@ export class Plans extends APIResource {
    */
   listPriceAdjustments(
     params: PlanListPriceAdjustmentsParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<PlanListPriceAdjustmentsResponsesCursorPage, PlanListPriceAdjustmentsResponse> {
+    options?: RequestOptions,
+  ): PagePromise<PlanListPriceAdjustmentsResponsesCursorPage, PlanListPriceAdjustmentsResponse> {
     const { customer_id, customer_plan_id, ...query } = params;
     return this._client.getAPIList(
-      `/v1/customers/${customer_id}/plans/${customer_plan_id}/priceAdjustments`,
-      PlanListPriceAdjustmentsResponsesCursorPage,
+      path`/v1/customers/${customer_id}/plans/${customer_plan_id}/priceAdjustments`,
+      CursorPage<PlanListPriceAdjustmentsResponse>,
       { query, ...options },
     );
   }
 }
 
-export class PlanListResponsesCursorPage extends CursorPage<PlanListResponse> {}
+export type PlanListResponsesCursorPage = CursorPage<PlanListResponse>;
 
-export class PlanListPriceAdjustmentsResponsesCursorPage extends CursorPage<PlanListPriceAdjustmentsResponse> {}
+export type PlanListPriceAdjustmentsResponsesCursorPage = CursorPage<PlanListPriceAdjustmentsResponse>;
 
 export interface PlanListResponse {
   /**
@@ -112,6 +114,9 @@ export interface PlanListResponse {
    */
   id: string;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields: { [key: string]: string };
 
   plan_description: string;
@@ -358,17 +363,14 @@ export interface PlanListPriceAdjustmentsParams extends CursorPageParams {
   customer_plan_id: string;
 }
 
-Plans.PlanListResponsesCursorPage = PlanListResponsesCursorPage;
-Plans.PlanListPriceAdjustmentsResponsesCursorPage = PlanListPriceAdjustmentsResponsesCursorPage;
-
 export declare namespace Plans {
   export {
     type PlanListResponse as PlanListResponse,
     type PlanAddResponse as PlanAddResponse,
     type PlanEndResponse as PlanEndResponse,
     type PlanListPriceAdjustmentsResponse as PlanListPriceAdjustmentsResponse,
-    PlanListResponsesCursorPage as PlanListResponsesCursorPage,
-    PlanListPriceAdjustmentsResponsesCursorPage as PlanListPriceAdjustmentsResponsesCursorPage,
+    type PlanListResponsesCursorPage as PlanListResponsesCursorPage,
+    type PlanListPriceAdjustmentsResponsesCursorPage as PlanListPriceAdjustmentsResponsesCursorPage,
     type PlanListParams as PlanListParams,
     type PlanAddParams as PlanAddParams,
     type PlanEndParams as PlanEndParams,

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.js";
+export * from './customers/index';

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,39 @@ 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 {
+  Payments,
+  type Payment,
+  type PaymentStatus,
+  type PaymentAttemptResponse,
+  type PaymentCancelResponse,
+  type PaymentListParams,
+  type PaymentAttemptParams,
+  type PaymentCancelParams,
+  type PaymentsBodyCursorPage,
+} from './payments';
 export {
-  PlanListResponsesCursorPage,
-  PlanListChargesResponsesCursorPage,
-  PlanListCustomersResponsesCursorPage,
   Plans,
   type PlanDetail,
   type PlanListResponse,
@@ -129,16 +143,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 +163,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/payments.ts

@@ -0,0 +1,170 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { APIPromise } from '../../core/api-promise';
+import { BodyCursorPage, type BodyCursorPageParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+
+export class Payments extends APIResource {
+  /**
+   * Fetch all payment attempts for the given invoice.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const payment of client.v1.payments.list({
+   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   invoice_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   *   statuses: ['pending', 'requires_intervention'],
+   * })) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(body: PaymentListParams, options?: RequestOptions): PagePromise<PaymentsBodyCursorPage, Payment> {
+    return this._client.getAPIList('/v1/payments/list', BodyCursorPage<Payment>, {
+      body,
+      method: 'post',
+      ...options,
+    });
+  }
+
+  /**
+   * Trigger a new attempt by canceling any existing attempts for this invoice and
+   * creating a new Payment. This will trigger another attempt to charge the
+   * Customer's configured Payment Gateway. Payment can only be attempted if all of
+   * the following are true:
+   *
+   * - The Metronome Invoice is finalized
+   * - PLG Invoicing is configured for the Customer
+   * - You cannot attempt payments for invoices that have already been `paid` or
+   *   `voided`.
+   *
+   * Attempting to payment on an ineligible Invoice or Customer will result in a
+   * `400` response.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.payments.attempt({
+   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   invoice_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   * });
+   * ```
+   */
+  attempt(body: PaymentAttemptParams, options?: RequestOptions): APIPromise<PaymentAttemptResponse> {
+    return this._client.post('/v1/payments/attempt', { body, ...options });
+  }
+
+  /**
+   * Cancel an existing payment attempt for an invoice.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.payments.cancel({
+   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   invoice_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   * });
+   * ```
+   */
+  cancel(body: PaymentCancelParams, options?: RequestOptions): APIPromise<PaymentCancelResponse> {
+    return this._client.post('/v1/payments/cancel', { body, ...options });
+  }
+}
+
+export type PaymentsBodyCursorPage = BodyCursorPage<Payment>;
+
+export interface Payment {
+  id: string;
+
+  amount?: number;
+
+  amount_paid?: number;
+
+  contract_id?: string;
+
+  created_at?: string;
+
+  customer_id?: string;
+
+  error_message?: string;
+
+  fiat_credit_type?: Shared.CreditTypeData;
+
+  invoice_id?: string;
+
+  payment_gateway?: Payment.PaymentGateway;
+
+  status?: PaymentStatus;
+
+  updated_at?: string;
+}
+
+export namespace Payment {
+  export interface PaymentGateway {
+    stripe: PaymentGateway.Stripe;
+
+    type: 'stripe';
+  }
+
+  export namespace PaymentGateway {
+    export interface Stripe {
+      payment_intent_id: string;
+
+      error?: Stripe.Error;
+    }
+
+    export namespace Stripe {
+      export interface Error {
+        code?: string;
+
+        decline_code?: string;
+
+        type?: string;
+      }
+    }
+  }
+}
+
+export type PaymentStatus = 'pending' | 'requires_intervention' | 'paid' | 'canceled';
+
+export interface PaymentAttemptResponse {
+  data: Payment;
+}
+
+export interface PaymentCancelResponse {
+  data: Payment;
+}
+
+export interface PaymentListParams extends BodyCursorPageParams {
+  customer_id: string;
+
+  invoice_id: string;
+
+  statuses?: Array<PaymentStatus>;
+}
+
+export interface PaymentAttemptParams {
+  customer_id: string;
+
+  invoice_id: string;
+}
+
+export interface PaymentCancelParams {
+  customer_id: string;
+
+  invoice_id: string;
+}
+
+export declare namespace Payments {
+  export {
+    type Payment as Payment,
+    type PaymentStatus as PaymentStatus,
+    type PaymentAttemptResponse as PaymentAttemptResponse,
+    type PaymentCancelResponse as PaymentCancelResponse,
+    type PaymentsBodyCursorPage as PaymentsBodyCursorPage,
+    type PaymentListParams as PaymentListParams,
+    type PaymentAttemptParams as PaymentAttemptParams,
+    type PaymentCancelParams as PaymentCancelParams,
+  };
+}