@metronome/sdk 2.2.0 → 3.4.1

package/src/resources/v1/payments.ts

@@ -95,6 +95,8 @@ export interface Payment {
 
   payment_gateway?: Payment.PaymentGateway;
 
+  revenue_system_payments?: Array<Payment.RevenueSystemPayment>;
+
   status?: PaymentStatus;
 
   updated_at?: string;
@@ -126,6 +128,19 @@ export namespace Payment {
       }
     }
   }
+
+  export interface RevenueSystemPayment {
+    revenue_system_provider: string;
+
+    sync_status: string;
+
+    /**
+     * The error message from the revenue system, if available.
+     */
+    error_message?: string;
+
+    revenue_system_external_payment_id?: string;
+  }
 }
 
 export type PaymentStatus = 'pending' | 'requires_intervention' | 'paid' | 'canceled';

package/src/resources/v1/plans.ts

@@ -8,6 +8,9 @@ import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagin
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * [Plans](https://docs.metronome.com/pricing-and-packaging/create-plans/) determine the base pricing for a customer. Use these endpoints to add a plan to a customer, end a customer plan, retrieve plans, and retrieve plan details. Create plans in the [Metronome app](https://app.metronome.com/plans).
+ */
 export class Plans extends APIResource {
   /**
    * List all available plans. This is a Plans (deprecated) endpoint. New clients
@@ -306,14 +309,14 @@ export interface PlanGetDetailsParams {
 
 export interface PlanListChargesParams extends CursorPageParams {
   /**
-   * Path param:
+   * Path param
    */
   plan_id: string;
 }
 
 export interface PlanListCustomersParams extends CursorPageParams {
   /**
-   * Path param:
+   * Path param
    */
   plan_id: string;
 

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

@@ -4,6 +4,9 @@ import { APIResource } from '../../core/resource';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * Use these endpoints to configure a billing API key, a webhook secret, or invoice finalization behavior.
+ */
 export class PricingUnits extends APIResource {
   /**
    * List all pricing units. All fiat currency types (for example, USD or GBP) will

package/src/resources/v1/services.ts

@@ -4,6 +4,9 @@ import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Security](https://docs.metronome.com/developer-resources/security/) endpoints allow you to retrieve security-related data.
+ */
 export class Services extends APIResource {
   /**
    * Gets Metronome's service registry with associated IP addresses for security

package/src/resources/v1/settings/billing-providers.ts

@@ -4,6 +4,9 @@ import { APIResource } from '../../../core/resource';
 import { APIPromise } from '../../../core/api-promise';
 import { RequestOptions } from '../../../internal/request-options';
 
+/**
+ * Use these endpoints to configure a billing API key, a webhook secret, or invoice finalization behavior.
+ */
 export class BillingProviders extends APIResource {
   /**
    * Set up account-level configuration for a billing provider. Once configured,

package/src/resources/v1/settings/settings.ts

@@ -12,6 +12,9 @@ import {
 import { APIPromise } from '../../../core/api-promise';
 import { RequestOptions } from '../../../internal/request-options';
 
+/**
+ * Use these endpoints to configure a billing API key, a webhook secret, or invoice finalization behavior.
+ */
 export class Settings extends APIResource {
   billingProviders: BillingProvidersAPI.BillingProviders = new BillingProvidersAPI.BillingProviders(
     this._client,

package/src/resources/v1/usage.ts

@@ -13,6 +13,9 @@ import {
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Usage events](https://docs.metronome.com/connecting-metronome/send-usage-data/) are the basis for billable metrics. Use these endpoints to send usage events to Metronome and retrieve aggregated event data.
+ */
 export class Usage extends APIResource {
   /**
    * Retrieve aggregated usage data across multiple customers and billable metrics in
@@ -192,13 +195,37 @@ export class Usage extends APIResource {
    * - Build detailed usage dashboards with dimensional filtering
    * - Identify high-usage segments for optimization opportunities
    *
+   * ### Request parameters
+   *
+   * Use [`group_key`](#body-group-key) and [`group_filters`](#body-group-filters) to
+   * group by one or more dimensions. This is required for compound group keys and
+   * recommended for all new integrations:
+   *
+   * ```json
+   * {
+   *   "group_key": ["region", "team"],
+   *   "group_filters": {
+   *     "region": ["US-East", "US-West"]
+   *   }
+   * }
+   * ```
+   *
+   * Important: For compound group keys, you must pass the complete set of keys that
+   * make up the compound key. Partial key combinations are not supported. For
+   * example, if your billable metric has a compound group key [region, team,
+   * environment], you must pass all three keys in group_key—you cannot pass just
+   * `[region]` or `[region, team]`.
+   *
    * ### Key response fields:
    *
    * An array of `PagedUsageAggregate` objects containing:
    *
    * - `starting_on` and `ending_before`: Time window boundaries
-   * - `group_key`: The dimension being grouped by (e.g., "region")
-   * - `group_value`: The specific value for this group (e.g., "US-East")
+   * - `group`: Object mapping group keys to their values
+   *   - For simple groups, this will be a map with a single key-value pair (e.g.,
+   *     `{"region": "US-East"}`)
+   *   - For compound groups, this will be a map with multiple key-value pairs (e.g.,
+   *     `{"region": "US-East", "team": "engineering"}`)
    * - `value`: Aggregated usage for this group and time window
    * - `next_page`: Pagination cursor for large datasets
    *
@@ -208,12 +235,13 @@ export class Usage extends APIResource {
    *   `window_size`
    * - Time windows: Set `window_size` to hour, day, or none for different
    *   granularities
-   * - Group filtering: Use `group_by` to specify:
-   *   - key: The dimension to group by (must be set on the billable metric as a
-   *     group key)
-   *   - values: Optional array to filter to specific values only
+   * - Group filtering: Use `group_key` and `group_filters` to specify groups and
+   *   group filters
+   * - Limits: When using compound group keys (2+ keys in `group_key`), the default
+   *   and max limit is 100
    * - Pagination: Use limit and `next_page` for large result sets
-   * - Null handling: `group_value` may be null for unmatched data
+   * - Null handling: Group values may be null for events missing the group key
+   *   property
    *
    * @example
    * ```ts
@@ -225,10 +253,8 @@ export class Usage extends APIResource {
    *     customer_id: '04ca7e72-4229-4a6e-ab11-9f7376fccbcb',
    *     window_size: 'day',
    *     ending_before: '2021-01-03T00:00:00Z',
-   *     group_by: {
-   *       key: 'region',
-   *       values: ['US-East', 'US-West', 'EU-Central'],
-   *     },
+   *     group_filters: { region: ['us-east1', 'us-west1'] },
+   *     group_key: ['region'],
    *     starting_on: '2021-01-01T00:00:00Z',
    *   },
    * )) {
@@ -324,13 +350,27 @@ export interface UsageListResponse {
 export interface UsageListWithGroupsResponse {
   ending_before: string;
 
+  /**
+   * @deprecated Use `group` instead. The group key for single-key grouping.
+   */
   group_key: string | null;
 
+  /**
+   * @deprecated Use `group` instead. The group value for single-key grouping.
+   */
   group_value: string | null;
 
   starting_on: string;
 
   value: number | null;
+
+  /**
+   * Map of group key to their value for this usage aggregate. For simple group keys,
+   * this should be a single key e.g. `{"region": "US-East"}` For compound group
+   * keys, this should contain the values of each group key that forms the compound
+   * e.g. `{"region": "US-East", "team": "engineering"}`
+   */
+  group?: { [key: string]: string };
 }
 
 export type UsageSearchResponse = Array<UsageSearchResponse.UsageSearchResponseItem>;
@@ -451,12 +491,12 @@ export namespace UsageSearchResponse {
 
 export interface UsageListParams extends CursorPageWithoutLimitParams {
   /**
-   * Body param:
+   * Body param
    */
   ending_before: string;
 
   /**
-   * Body param:
+   * Body param
    */
   starting_on: string;
 
@@ -527,12 +567,12 @@ export namespace UsageIngestParams {
 
 export interface UsageListWithGroupsParams extends CursorPageParams {
   /**
-   * Body param:
+   * Body param
    */
   billable_metric_id: string;
 
   /**
-   * Body param:
+   * Body param
    */
   customer_id: string;
 
@@ -552,22 +592,50 @@ export interface UsageListWithGroupsParams extends CursorPageParams {
   current_period?: boolean;
 
   /**
-   * Body param:
+   * Body param
    */
   ending_before?: string;
 
   /**
-   * Body param:
+   * @deprecated Body param: Use group_key and group_filters instead. Use a single
+   * group key to group by. Compound group keys are not supported.
    */
   group_by?: UsageListWithGroupsParams.GroupBy;
 
   /**
-   * Body param:
+   * Body param: Object mapping group keys to arrays of values to filter on. Only
+   * usage matching these filter values will be returned. Keys must be present in
+   * group_key. Omit a key or use an empty array to include all values for that
+   * dimension.
+   */
+  group_filters?: { [key: string]: Array<string> };
+
+  /**
+   * Body param: Group key to group usage by. Supports both simple (single key) and
+   * compound (multiple keys) group keys.
+   *
+   * For simple group keys, provide a single key e.g. `["region"]`. For compound
+   * group keys, provide multiple keys e.g. `["region", "team"]`.
+   *
+   * For streaming metrics, the keys must be defined as a simple or compound group
+   * key on the billable metric. For compound group keys, all keys must match an
+   * exact compound group key definition — partial matches are not allowed.
+   *
+   * Cannot be used together with `group_by`.
+   */
+  group_key?: Array<string>;
+
+  /**
+   * Body param
    */
   starting_on?: string;
 }
 
 export namespace UsageListWithGroupsParams {
+  /**
+   * @deprecated Use group_key and group_filters instead. Use a single group key to
+   * group by. Compound group keys are not supported.
+   */
   export interface GroupBy {
     /**
      * The name of the group_by key to use

package/src/resources/v1/v1.ts

@@ -69,6 +69,22 @@ import {
   InvoiceVoidResponse,
   Invoices,
 } from './invoices';
+import * as PackagesAPI from './packages';
+import {
+  PackageArchiveParams,
+  PackageArchiveResponse,
+  PackageCreateParams,
+  PackageCreateResponse,
+  PackageListContractsOnPackageParams,
+  PackageListContractsOnPackageResponse,
+  PackageListContractsOnPackageResponsesCursorPage,
+  PackageListParams,
+  PackageListResponse,
+  PackageListResponsesCursorPage,
+  PackageRetrieveParams,
+  PackageRetrieveResponse,
+  Packages,
+} from './packages';
 import * as PaymentsAPI from './payments';
 import {
   Payment,
@@ -130,6 +146,8 @@ import {
   ContractCreateHistoricalInvoicesResponse,
   ContractCreateParams,
   ContractCreateResponse,
+  ContractGetNetBalanceParams,
+  ContractGetNetBalanceResponse,
   ContractListBalancesParams,
   ContractListBalancesResponse,
   ContractListBalancesResponsesBodyCursorPage,
@@ -151,6 +169,8 @@ import {
 import * as CustomersAPI from './customers/customers';
 import {
   Customer,
+  CustomerArchiveBillingConfigurationsParams,
+  CustomerArchiveBillingConfigurationsResponse,
   CustomerArchiveParams,
   CustomerArchiveResponse,
   CustomerCreateParams,
@@ -199,6 +219,7 @@ export class V1 extends APIResource {
   services: ServicesAPI.Services = new ServicesAPI.Services(this._client);
   invoices: InvoicesAPI.Invoices = new InvoicesAPI.Invoices(this._client);
   contracts: ContractsAPI.Contracts = new ContractsAPI.Contracts(this._client);
+  packages: PackagesAPI.Packages = new PackagesAPI.Packages(this._client);
   payments: PaymentsAPI.Payments = new PaymentsAPI.Payments(this._client);
   settings: SettingsAPI.Settings = new SettingsAPI.Settings(this._client);
 }
@@ -216,6 +237,7 @@ V1.BillableMetrics = BillableMetrics;
 V1.Services = Services;
 V1.Invoices = Invoices;
 V1.Contracts = Contracts;
+V1.Packages = Packages;
 V1.Payments = Payments;
 V1.Settings = Settings;
 
@@ -277,6 +299,7 @@ export declare namespace V1 {
     type CustomerCreateResponse as CustomerCreateResponse,
     type CustomerRetrieveResponse as CustomerRetrieveResponse,
     type CustomerArchiveResponse as CustomerArchiveResponse,
+    type CustomerArchiveBillingConfigurationsResponse as CustomerArchiveBillingConfigurationsResponse,
     type CustomerListBillableMetricsResponse as CustomerListBillableMetricsResponse,
     type CustomerListCostsResponse as CustomerListCostsResponse,
     type CustomerPreviewEventsResponse as CustomerPreviewEventsResponse,
@@ -290,6 +313,7 @@ export declare namespace V1 {
     type CustomerRetrieveParams as CustomerRetrieveParams,
     type CustomerListParams as CustomerListParams,
     type CustomerArchiveParams as CustomerArchiveParams,
+    type CustomerArchiveBillingConfigurationsParams as CustomerArchiveBillingConfigurationsParams,
     type CustomerListBillableMetricsParams as CustomerListBillableMetricsParams,
     type CustomerListCostsParams as CustomerListCostsParams,
     type CustomerPreviewEventsParams as CustomerPreviewEventsParams,
@@ -368,6 +392,7 @@ export declare namespace V1 {
     type ContractAmendResponse as ContractAmendResponse,
     type ContractArchiveResponse as ContractArchiveResponse,
     type ContractCreateHistoricalInvoicesResponse as ContractCreateHistoricalInvoicesResponse,
+    type ContractGetNetBalanceResponse as ContractGetNetBalanceResponse,
     type ContractListBalancesResponse as ContractListBalancesResponse,
     type ContractRetrieveRateScheduleResponse as ContractRetrieveRateScheduleResponse,
     type ContractRetrieveSubscriptionQuantityHistoryResponse as ContractRetrieveSubscriptionQuantityHistoryResponse,
@@ -381,6 +406,7 @@ export declare namespace V1 {
     type ContractAmendParams as ContractAmendParams,
     type ContractArchiveParams as ContractArchiveParams,
     type ContractCreateHistoricalInvoicesParams as ContractCreateHistoricalInvoicesParams,
+    type ContractGetNetBalanceParams as ContractGetNetBalanceParams,
     type ContractListBalancesParams as ContractListBalancesParams,
     type ContractRetrieveRateScheduleParams as ContractRetrieveRateScheduleParams,
     type ContractRetrieveSubscriptionQuantityHistoryParams as ContractRetrieveSubscriptionQuantityHistoryParams,
@@ -389,6 +415,22 @@ export declare namespace V1 {
     type ContractUpdateEndDateParams as ContractUpdateEndDateParams,
   };
 
+  export {
+    Packages as Packages,
+    type PackageCreateResponse as PackageCreateResponse,
+    type PackageRetrieveResponse as PackageRetrieveResponse,
+    type PackageListResponse as PackageListResponse,
+    type PackageArchiveResponse as PackageArchiveResponse,
+    type PackageListContractsOnPackageResponse as PackageListContractsOnPackageResponse,
+    type PackageListResponsesCursorPage as PackageListResponsesCursorPage,
+    type PackageListContractsOnPackageResponsesCursorPage as PackageListContractsOnPackageResponsesCursorPage,
+    type PackageCreateParams as PackageCreateParams,
+    type PackageRetrieveParams as PackageRetrieveParams,
+    type PackageListParams as PackageListParams,
+    type PackageArchiveParams as PackageArchiveParams,
+    type PackageListContractsOnPackageParams as PackageListContractsOnPackageParams,
+  };
+
   export {
     Payments as Payments,
     type Payment as Payment,

package/src/resources/v2/contracts.ts

@@ -76,10 +76,7 @@ export class Contracts extends APIResource {
    *
    * ### Key response fields:
    *
-   * - The `id` of the edit
-   * - Complete edit details. For example, if you edited the contract to add new
-   *   overrides and credits, you will receive the IDs of those overrides and credits
-   *   in the response.
+   * - The `id` of the contract that was edited
    *
    * ### Usage guidelines:
    *
@@ -556,7 +553,7 @@ export namespace ContractGetEditHistoryResponse {
       }
 
       export interface OverwriteRate {
-        rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+        rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
         credit_type?: Shared.CreditTypeData;
 
@@ -1677,6 +1674,13 @@ export interface ContractEditParams {
 
   add_reseller_royalties?: Array<ContractEditParams.AddResellerRoyalty>;
 
+  /**
+   * Update the revenue system configuration on the contract. Currently only supports
+   * adding a revenue system configuration to a contract that does not already have
+   * one.
+   */
+  add_revenue_system_configuration_update?: ContractEditParams.AddRevenueSystemConfigurationUpdate;
+
   add_scheduled_charges?: Array<ContractEditParams.AddScheduledCharge>;
 
   add_spend_threshold_configuration?: Shared.SpendThresholdConfigurationV2;
@@ -1736,6 +1740,12 @@ export interface ContractEditParams {
 
   update_credits?: Array<ContractEditParams.UpdateCredit>;
 
+  /**
+   * Number of days after issuance of invoice after which the invoice is due (e.g.
+   * Net 30).
+   */
+  update_net_payment_terms_days?: number | null;
+
   update_prepaid_balance_threshold_configuration?: ContractEditParams.UpdatePrepaidBalanceThresholdConfiguration;
 
   /**
@@ -2065,7 +2075,7 @@ export namespace ContractEditParams {
        * not wish Metronome to calculate tax on your behalf. Leaving this field blank
        * will default to NONE.
        */
-      tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'AVALARA' | 'PRECALCULATED';
+      tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'PRECALCULATED';
     }
 
     export namespace PaymentGateConfig {
@@ -2169,6 +2179,11 @@ export namespace ContractEditParams {
 
     rate_type?: 'COMMIT_RATE' | 'LIST_RATE';
 
+    /**
+     * Fraction of unused segments that will be rolled over. Must be between 0 and 1.
+     */
+    rollover_fraction?: number;
+
     /**
      * List of filters that determine what kind of customer usage draws down a commit
      * or credit. A customer's usage needs to meet the condition of at least one of the
@@ -2461,7 +2476,7 @@ export namespace ContractEditParams {
      * Required for OVERWRITE type.
      */
     export interface OverwriteRate {
-      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
       credit_type_id?: string;
 
@@ -2925,6 +2940,37 @@ export namespace ContractEditParams {
     }
   }
 
+  /**
+   * Update the revenue system configuration on the contract. Currently only supports
+   * adding a revenue system configuration to a contract that does not already have
+   * one.
+   */
+  export interface AddRevenueSystemConfigurationUpdate {
+    revenue_system_configuration: AddRevenueSystemConfigurationUpdate.RevenueSystemConfiguration;
+
+    schedule: AddRevenueSystemConfigurationUpdate.Schedule;
+  }
+
+  export namespace AddRevenueSystemConfigurationUpdate {
+    export interface RevenueSystemConfiguration {
+      delivery_method?: 'direct_to_billing_provider' | 'aws_sqs' | 'tackle' | 'aws_sns';
+
+      /**
+       * The revenue system provider type.
+       */
+      provider?: 'netsuite';
+
+      revenue_system_configuration_id?: string;
+    }
+
+    export interface Schedule {
+      /**
+       * When the revenue system configuration update will take effect.
+       */
+      effective_at: 'START_OF_CURRENT_PERIOD';
+    }
+  }
+
   export interface AddScheduledCharge {
     product_id: string;
 
@@ -3332,6 +3378,8 @@ export namespace ContractEditParams {
      * regenerated to reflect the rate type change.
      */
     rate_type?: 'LIST_RATE' | 'COMMIT_RATE';
+
+    rollover_fraction?: number | null;
   }
 
   export namespace UpdateCredit {

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '2.2.0'; // x-release-please-version
+export const VERSION = '3.4.1'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.2.0";
+export declare const VERSION = "3.4.1";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.2.0";
+export declare const VERSION = "3.4.1";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '2.2.0'; // x-release-please-version
+exports.VERSION = '3.4.1'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '2.2.0'; // x-release-please-version
+export const VERSION = '3.4.1'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map