@metronome/sdk 3.0.0 → 3.5.0

package/src/client.ts

@@ -11,7 +11,7 @@ import type { APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
-import * as qs from './internal/qs';
+import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
 import * as Pagination from './core/pagination';
@@ -233,8 +233,8 @@ export class Metronome {
     return buildHeaders([{ Authorization: `Bearer ${this.bearerToken}` }]);
   }
 
-  protected stringifyQuery(query: Record<string, unknown>): string {
-    return qs.stringify(query, { arrayFormat: 'comma' });
+  protected stringifyQuery(query: object | Record<string, unknown>): string {
+    return stringifyQuery(query);
   }
 
   private getUserAgent(): string {
@@ -266,12 +266,13 @@ export class Metronome {
       : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
-    if (!isEmptyObj(defaultQuery)) {
-      query = { ...defaultQuery, ...query };
+    const pathQuery = Object.fromEntries(url.searchParams);
+    if (!isEmptyObj(defaultQuery) || !isEmptyObj(pathQuery)) {
+      query = { ...pathQuery, ...defaultQuery, ...query };
     }
 
     if (typeof query === 'object' && query && !Array.isArray(query)) {
-      url.search = this.stringifyQuery(query as Record<string, unknown>);
+      url.search = this.stringifyQuery(query);
     }
 
     return url.toString();
@@ -455,7 +456,7 @@ export class Metronome {
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
 
       const errText = await response.text().catch((err: any) => castToError(err).message);
-      const errJSON = safeJSON(errText);
+      const errJSON = safeJSON(errText) as any;
       const errMessage = errJSON ? undefined : errText;
 
       loggerFor(this).debug(
@@ -492,9 +493,14 @@ export class Metronome {
   getAPIList<Item, PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>>(
     path: string,
     Page: new (...args: any[]) => PageClass,
-    opts?: RequestOptions,
+    opts?: PromiseOrValue<RequestOptions>,
   ): Pagination.PagePromise<PageClass, Item> {
-    return this.requestAPIList(Page, { method: 'get', path, ...opts });
+    return this.requestAPIList(
+      Page,
+      opts && 'then' in opts ?
+        opts.then((opts) => ({ method: 'get', path, ...opts }))
+      : { method: 'get', path, ...opts },
+    );
   }
 
   requestAPIList<
@@ -502,7 +508,7 @@ export class Metronome {
     PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>,
   >(
     Page: new (...args: ConstructorParameters<typeof Pagination.AbstractPage>) => PageClass,
-    options: FinalRequestOptions,
+    options: PromiseOrValue<FinalRequestOptions>,
   ): Pagination.PagePromise<PageClass, Item> {
     const request = this.makeRequest(options, null, undefined);
     return new Pagination.PagePromise<PageClass, Item>(this as any as Metronome, request, Page);
@@ -515,9 +521,10 @@ export class Metronome {
     controller: AbortController,
   ): Promise<Response> {
     const { signal, method, ...options } = init || {};
-    if (signal) signal.addEventListener('abort', () => controller.abort());
+    const abort = this._makeAbort(controller);
+    if (signal) signal.addEventListener('abort', abort, { once: true });
 
-    const timeout = setTimeout(() => controller.abort(), ms);
+    const timeout = setTimeout(abort, ms);
 
     const isReadableBody =
       ((globalThis as any).ReadableStream && options.body instanceof (globalThis as any).ReadableStream) ||
@@ -594,9 +601,9 @@ export class Metronome {
       }
     }
 
-    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
-    // just do what it says, but otherwise calculate a default
-    if (!(timeoutMillis && 0 <= timeoutMillis && timeoutMillis < 60 * 1000)) {
+    // If the API asks us to wait a certain amount of time, just do what it
+    // says, but otherwise calculate a default
+    if (timeoutMillis === undefined) {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
@@ -684,6 +691,12 @@ export class Metronome {
     return headers.values;
   }
 
+  private _makeAbort(controller: AbortController) {
+    // note: we can't just inline this method inside `fetchWithTimeout()` because then the closure
+    //       would capture all request options, and cause a memory leak.
+    return () => controller.abort();
+  }
+
   private buildBody({ options: { body, headers: rawHeaders } }: { options: FinalRequestOptions }): {
     bodyHeaders: HeadersLike;
     body: BodyInit | undefined;
@@ -716,6 +729,14 @@ export class Metronome {
         (Symbol.iterator in body && 'next' in body && typeof body.next === 'function'))
     ) {
       return { bodyHeaders: undefined, body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>) };
+    } else if (
+      typeof body === 'object' &&
+      headers.values.get('content-type') === 'application/x-www-form-urlencoded'
+    ) {
+      return {
+        bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: this.stringifyQuery(body),
+      };
     } else {
       return this.#encoder({ body, headers });
     }
@@ -771,6 +792,7 @@ export declare namespace Metronome {
 
   export { V1 as V1 };
 
+  export type BalanceFilter = API.BalanceFilter;
   export type BaseThresholdCommit = API.BaseThresholdCommit;
   export type BaseUsageFilter = API.BaseUsageFilter;
   export type Commit = API.Commit;

package/src/internal/parse.ts

@@ -29,6 +29,12 @@ export async function defaultParseResponse<T>(client: Metronome, props: APIRespo
     const mediaType = contentType?.split(';')[0]?.trim();
     const isJSON = mediaType?.includes('application/json') || mediaType?.endsWith('+json');
     if (isJSON) {
+      const contentLength = response.headers.get('content-length');
+      if (contentLength === '0') {
+        // if there is no content we can't do anything
+        return undefined as T;
+      }
+
       const json = await response.json();
       return json as T;
     }

package/src/internal/utils/env.ts

@@ -9,10 +9,10 @@
  */
 export const readEnv = (env: string): string | undefined => {
   if (typeof (globalThis as any).process !== 'undefined') {
-    return (globalThis as any).process.env?.[env]?.trim() ?? undefined;
+    return (globalThis as any).process.env?.[env]?.trim() || undefined;
   }
   if (typeof (globalThis as any).Deno !== 'undefined') {
-    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+    return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined;
   }
   return undefined;
 };

package/src/internal/utils/query.ts

@@ -0,0 +1,7 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import * as qs from '../qs/stringify';
+
+export function stringifyQuery(query: object | Record<string, unknown>) {
+  return qs.stringify(query, { arrayFormat: 'comma' });
+}

package/src/internal/utils.ts

@@ -6,3 +6,4 @@ export * from './utils/env';
 export * from './utils/log';
 export * from './utils/uuid';
 export * from './utils/sleep';
+export * from './utils/query';

package/src/resources/shared.ts

@@ -3,6 +3,23 @@
 import * as Shared from './shared';
 import { BodyCursorPage } from '../core/pagination';
 
+export interface BalanceFilter {
+  /**
+   * The balance type to filter by.
+   */
+  balance_types?: Array<'PREPAID_COMMIT' | 'POSTPAID_COMMIT' | 'CREDIT'>;
+
+  /**
+   * Custom fields to compute balance across. Must match all custom fields
+   */
+  custom_fields?: { [key: string]: string };
+
+  /**
+   * Specific IDs to compute balance across.
+   */
+  ids?: Array<string>;
+}
+
 export interface BaseThresholdCommit {
   /**
    * The commit product that will be used to generate the line item for commit
@@ -17,6 +34,12 @@ export interface BaseThresholdCommit {
    * will default to the commit product name.
    */
   name?: string;
+
+  /**
+   * The priority of the commit, used to determine drawdown order. Lower priority
+   * commits are consumed first. Defaults to 100 if not specified.
+   */
+  priority?: number;
 }
 
 export interface BaseUsageFilter {
@@ -407,10 +430,12 @@ export namespace CommitHierarchyConfiguration {
  * list rate when consuming a credit or commit.
  */
 export interface CommitRate {
-  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
   /**
-   * Commit rate price. For FLAT rate_type, this must be >=0.
+   * Commit rate price. For FLAT rate_type, this must be >=0. For PERCENTAGE
+   * rate_type, this is a decimal fraction, e.g. use 0.1 for 10%; this must be >=0
+   * and <=1.
    */
   price?: number;
 
@@ -438,8 +463,16 @@ export interface CommitSpecifier {
 }
 
 export interface CommitSpecifierInput {
+  /**
+   * If provided, the specifier will apply to product usage with these set of
+   * presentation group values.
+   */
   presentation_group_values?: { [key: string]: string };
 
+  /**
+   * If provided, the specifier will apply to product usage with these set of pricing
+   * group values.
+   */
   pricing_group_values?: { [key: string]: string };
 
   /**
@@ -481,12 +514,12 @@ export interface Contract {
    */
   customer_billing_provider_configuration?: Contract.CustomerBillingProviderConfiguration;
 
-  prepaid_balance_threshold_configuration?: PrepaidBalanceThresholdConfiguration;
-
   /**
-   * Priority of the contract.
+   * ID of the package this contract was created from, if applicable.
    */
-  priority?: number;
+  package_id?: string;
+
+  prepaid_balance_threshold_configuration?: PrepaidBalanceThresholdConfiguration;
 
   /**
    * Determines which scheduled and commit charges to consolidate onto the Contract's
@@ -1054,6 +1087,8 @@ export namespace ContractV2 {
   export interface Override {
     id: string;
 
+    created_at: string;
+
     starting_at: string;
 
     applicable_product_tags?: Array<string>;
@@ -1096,12 +1131,10 @@ export namespace ContractV2 {
       product_tags?: Array<string>;
 
       recurring_commit_ids?: Array<string>;
-
-      recurring_credit_ids?: Array<string>;
     }
 
     export interface OverwriteRate {
-      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
       credit_type?: Shared.CreditTypeData;
 
@@ -1240,6 +1273,7 @@ export namespace ContractV2 {
       | Credit.CreditCreditedLedgerEntry
       | Credit.CreditManualLedgerEntry
       | Credit.CreditSeatBasedAdjustmentLedgerEntry
+      | Credit.CreditRolloverLedgerEntry
     >;
 
     name?: string;
@@ -1260,6 +1294,8 @@ export namespace ContractV2 {
      */
     recurring_credit_id?: string;
 
+    rolled_over_from?: Credit.RolledOverFrom;
+
     /**
      * This field's availability is dependent on your client's configuration.
      */
@@ -1370,6 +1406,24 @@ export namespace ContractV2 {
 
       type: 'CREDIT_SEAT_BASED_ADJUSTMENT';
     }
+
+    export interface CreditRolloverLedgerEntry {
+      amount: number;
+
+      new_contract_id: string;
+
+      segment_id: string;
+
+      timestamp: string;
+
+      type: 'CREDIT_ROLLOVER';
+    }
+
+    export interface RolledOverFrom {
+      contract_id: string;
+
+      credit_id: string;
+    }
   }
 
   /**
@@ -1433,8 +1487,8 @@ export namespace ContractV2 {
 
     export interface ParentBehavior {
       /**
-       * Account hierarchy M3 - Indicates the desired behavior of consolidated invoices
-       * generated by the parent in a customer hierarchy
+       * Indicates the desired behavior of consolidated invoices generated by the parent
+       * in a customer hierarchy
        *
        * **CONCATENATE**: Statements on the invoices of child customers will be appended
        * to the consolidated invoice
@@ -1452,15 +1506,15 @@ export namespace ContractV2 {
     parent: ChildHierarchyConfigurationV2.Parent;
 
     /**
-     * Account hierarchy M3 - Indicates which customer should pay for the child's
-     * invoice charges **SELF**: The child pays for its own invoice charges **PARENT**:
-     * The parent pays for the child's invoice charges
+     * Indicates which customer should pay for the child's invoice charges **SELF**:
+     * The child pays for its own invoice charges **PARENT**: The parent pays for the
+     * child's invoice charges
      */
     payer?: 'SELF' | 'PARENT';
 
     /**
-     * Account hierarchy M3 - Indicates the behavior of the child's invoice statements
-     * on the parent's invoices.
+     * Indicates the behavior of the child's invoice statements on the parent's
+     * invoices.
      *
      * **CONSOLIDATE**: Child's invoice statements will be added to parent's
      * consolidated invoices
@@ -2291,6 +2345,7 @@ export interface Credit {
     | Credit.CreditCreditedLedgerEntry
     | Credit.CreditManualLedgerEntry
     | Credit.CreditSeatBasedAdjustmentLedgerEntry
+    | Credit.CreditRolloverLedgerEntry
   >;
 
   name?: string;
@@ -2314,6 +2369,8 @@ export interface Credit {
    */
   recurring_credit_id?: string;
 
+  rolled_over_from?: Credit.RolledOverFrom;
+
   /**
    * This field's availability is dependent on your client's configuration.
    */
@@ -2434,6 +2491,24 @@ export namespace Credit {
     type: 'CREDIT_SEAT_BASED_ADJUSTMENT';
   }
 
+  export interface CreditRolloverLedgerEntry {
+    amount: number;
+
+    new_contract_id: string;
+
+    segment_id: string;
+
+    timestamp: string;
+
+    type: 'CREDIT_ROLLOVER';
+  }
+
+  export interface RolledOverFrom {
+    contract_id: string;
+
+    credit_id: string;
+  }
+
   /**
    * The subscription configuration for this credit, if it was generated from a
    * recurring credit with a subscription attached.
@@ -2536,8 +2611,8 @@ export namespace HierarchyConfiguration {
 
     export interface ParentBehavior {
       /**
-       * Account hierarchy M3 - Indicates the desired behavior of consolidated invoices
-       * generated by the parent in a customer hierarchy
+       * Indicates the desired behavior of consolidated invoices generated by the parent
+       * in a customer hierarchy
        *
        * **CONCATENATE**: Statements on the invoices of child customers will be appended
        * to the consolidated invoice
@@ -2555,8 +2630,7 @@ export namespace HierarchyConfiguration {
     parent: ChildHierarchyConfiguration.Parent;
 
     /**
-     * Account hierarchy M3 - Indicates which customer should pay for the child's
-     * invoice charges
+     * Indicates which customer should pay for the child's invoice charges
      *
      * **SELF**: The child pays for its own invoice charges
      *
@@ -2565,8 +2639,8 @@ export namespace HierarchyConfiguration {
     payer?: 'SELF' | 'PARENT';
 
     /**
-     * Account hierarchy M3 - Indicates the behavior of the child's invoice statements
-     * on the parent's invoices.
+     * Indicates the behavior of the child's invoice statements on the parent's
+     * invoices.
      *
      * **CONSOLIDATE**: Child's invoice statements will be added to parent's
      * consolidated invoices
@@ -2596,6 +2670,8 @@ export interface ID {
 export interface Override {
   id: string;
 
+  created_at: string;
+
   starting_at: string;
 
   applicable_product_tags?: Array<string>;
@@ -2637,7 +2713,7 @@ export interface Override {
    */
   quantity?: number;
 
-  rate_type?: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+  rate_type?: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
   target?: 'COMMIT_RATE' | 'LIST_RATE';
 
@@ -2670,8 +2746,6 @@ export namespace Override {
     product_tags?: Array<string>;
 
     recurring_commit_ids?: Array<string>;
-
-    recurring_credit_ids?: Array<string>;
   }
 
   export interface Product {
@@ -2688,7 +2762,7 @@ export interface OverrideTier {
 }
 
 export interface OverwriteRate {
-  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
   credit_type?: CreditTypeData;
 
@@ -2745,7 +2819,7 @@ export interface PaymentGateConfig {
    * 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 {
@@ -2807,7 +2881,7 @@ export interface PaymentGateConfigV2 {
    * 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 PaymentGateConfigV2 {
@@ -2873,6 +2947,8 @@ export interface PrepaidBalanceThresholdConfiguration {
    * commit amount will be in terms of this credit type instead of the fiat currency.
    */
   custom_credit_type_id?: string;
+
+  discount_configuration?: PrepaidBalanceThresholdConfiguration.DiscountConfiguration;
 }
 
 export namespace PrepaidBalanceThresholdConfiguration {
@@ -2899,6 +2975,15 @@ export namespace PrepaidBalanceThresholdConfiguration {
      */
     specifiers?: Array<Shared.CommitSpecifierInput>;
   }
+
+  export interface DiscountConfiguration {
+    /**
+     * The fraction of the original amount that the customer pays after applying the
+     * discount. For example, 0.85 means the customer pays 85% of the original amount
+     * (a 15% discount).
+     */
+    payment_fraction: number;
+  }
 }
 
 export interface PrepaidBalanceThresholdConfigurationV2 {
@@ -2929,10 +3014,12 @@ export interface PrepaidBalanceThresholdConfigurationV2 {
    * commit amount will be in terms of this credit type instead of the fiat currency.
    */
   custom_credit_type_id?: string;
+
+  discount_configuration?: PrepaidBalanceThresholdConfigurationV2.DiscountConfiguration;
 }
 
 export namespace PrepaidBalanceThresholdConfigurationV2 {
-  export interface Commit extends Shared.UpdateBaseThresholdCommit {
+  export interface Commit extends Shared.BaseThresholdCommit {
     /**
      * Which products the threshold commit applies to. If applicable_product_ids,
      * applicable_product_tags or specifiers are not provided, the commit applies to
@@ -2957,6 +3044,15 @@ export namespace PrepaidBalanceThresholdConfigurationV2 {
      */
     specifiers?: Array<Shared.CommitSpecifierInput>;
   }
+
+  export interface DiscountConfiguration {
+    /**
+     * The fraction of the original amount that the customer pays after applying the
+     * discount. For example, 0.85 means the customer pays 85% of the original amount
+     * (a 15% discount).
+     */
+    payment_fraction: number;
+  }
 }
 
 export interface PropertyFilter {
@@ -3026,7 +3122,7 @@ export interface ProService {
 }
 
 export interface Rate {
-  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'CUSTOM' | 'TIERED';
+  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'CUSTOM' | 'TIERED' | 'TIERED_PERCENTAGE';
 
   credit_type?: CreditTypeData;
 
@@ -3178,10 +3274,23 @@ export interface SpendThresholdConfiguration {
    * hits this amount, a threshold charge will be initiated.
    */
   threshold_amount: number;
+
+  discount_configuration?: SpendThresholdConfiguration.DiscountConfiguration;
+}
+
+export namespace SpendThresholdConfiguration {
+  export interface DiscountConfiguration {
+    /**
+     * The fraction of the original amount that the customer pays after applying the
+     * discount. For example, 0.85 means the customer pays 85% of the original amount
+     * (a 15% discount).
+     */
+    payment_fraction: number;
+  }
 }
 
 export interface SpendThresholdConfigurationV2 {
-  commit: UpdateBaseThresholdCommit;
+  commit: BaseThresholdCommit;
 
   /**
    * When set to false, the contract will not be evaluated against the
@@ -3197,6 +3306,19 @@ export interface SpendThresholdConfigurationV2 {
    * hits this amount, a threshold charge will be initiated.
    */
   threshold_amount: number;
+
+  discount_configuration?: SpendThresholdConfigurationV2.DiscountConfiguration;
+}
+
+export namespace SpendThresholdConfigurationV2 {
+  export interface DiscountConfiguration {
+    /**
+     * The fraction of the original amount that the customer pays after applying the
+     * discount. For example, 0.85 means the customer pays 85% of the original amount
+     * (a 15% discount).
+     */
+    payment_fraction: number;
+  }
 }
 
 export interface Subscription {
@@ -3338,6 +3460,13 @@ export interface UpdateBaseThresholdCommit {
    */
   name?: string;
 
+  /**
+   * The priority of the commit, used to determine drawdown order. Lower priority
+   * commits are consumed first. Defaults to 100 if not specified. On updates, set to
+   * null to clear a previously configured priority.
+   */
+  priority?: number | null;
+
   /**
    * The commit product that will be used to generate the line item for commit
    * payment.

package/src/resources/v1/alerts.ts

@@ -5,6 +5,9 @@ import * as Shared from '../shared';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)
+ */
 export class Alerts extends APIResource {
   /**
    * Create a new threshold notification to monitor customer spending, balances, and

package/src/resources/v1/audit-logs.ts

@@ -4,6 +4,9 @@ import { APIResource } from '../../core/resource';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Security](https://docs.metronome.com/developer-resources/security/) endpoints allow you to retrieve security-related data.
+ */
 export class AuditLogs extends APIResource {
   /**
    * Get a comprehensive audit trail of all operations performed in your Metronome

package/src/resources/v1/billable-metrics.ts

@@ -7,6 +7,9 @@ import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagin
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * [Billable metrics](https://docs.metronome.com/understanding-metronome/how-metronome-works#billable-metrics) in Metronome represent the various consumption components that Metronome meters and aggregates.
+ */
 export class BillableMetrics extends APIResource {
   /**
    * Create billable metrics programmatically with this endpoint—an essential step in