@metronome/sdk 0.1.0-beta.9 → 0.1.0

package/src/resources/v1/invoices.ts

@@ -1,11 +1,18 @@
 // 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 Invoices extends APIResource {
   /**
    * Regenerate a voided contract invoice
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.invoices.regenerate({
+   *   id: '6a37bb88-8538-48c5-b37b-a41c836328bd',
+   * });
+   * ```
    */
   regenerate(
     body: InvoiceRegenerateParams,
@@ -16,6 +23,13 @@ export class Invoices extends APIResource {
 
   /**
    * Void an invoice
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.invoices.void({
+   *   id: '6a37bb88-8538-48c5-b37b-a41c836328bd',
+   * });
+   * ```
    */
   void(body: InvoiceVoidParams, options?: Core.RequestOptions): Core.APIPromise<InvoiceVoidResponse> {
     return this._client.post('/v1/invoices/void', { body, ...options });

package/src/resources/v1/plans.ts

@@ -1,15 +1,23 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../resource';
-import { isRequestOptions } from '../../core';
-import * as Core from '../../core';
-import * as Shared from '../shared';
-import * as CustomersAPI from './customers/customers';
-import { CursorPage, type CursorPageParams } from '../../pagination';
+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";
 
 export class Plans extends APIResource {
   /**
    * List all available plans.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const planListResponse of client.v1.plans.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: PlanListParams,
@@ -28,6 +36,13 @@ export class Plans extends APIResource {
 
   /**
    * Fetch high level details of a specific plan.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.plans.getDetails({
+   *   plan_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   * });
+   * ```
    */
   getDetails(
     params: PlanGetDetailsParams,
@@ -39,6 +54,16 @@ export class Plans extends APIResource {
 
   /**
    * Fetches a list of charges of a specific plan.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const planListChargesResponse of client.v1.plans.listCharges(
+   *   { plan_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listCharges(
     params: PlanListChargesParams,
@@ -54,6 +79,16 @@ export class Plans extends APIResource {
   /**
    * Fetches a list of customers on a specific plan (by default, only currently
    * active plans are included)
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const planListCustomersResponse of client.v1.plans.listCustomers(
+   *   { plan_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listCustomers(
     params: PlanListCustomersParams,
@@ -77,7 +112,7 @@ export class PlanListCustomersResponsesCursorPage extends CursorPage<PlanListCus
 export interface PlanDetail {
   id: string;
 
-  custom_fields: Record<string, string>;
+  custom_fields: { [key: string]: string };
 
   name: string;
 
@@ -151,7 +186,7 @@ export interface PlanListResponse {
 
   name: string;
 
-  custom_fields?: Record<string, string>;
+  custom_fields?: { [key: string]: string };
 }
 
 export interface PlanGetDetailsResponse {
@@ -165,7 +200,7 @@ export interface PlanListChargesResponse {
 
   credit_type: Shared.CreditTypeData;
 
-  custom_fields: Record<string, string>;
+  custom_fields: { [key: string]: string };
 
   name: string;
 
@@ -238,7 +273,7 @@ export namespace PlanListCustomersResponse {
   export interface PlanDetails {
     id: string;
 
-    custom_fields: Record<string, string>;
+    custom_fields: { [key: string]: string };
 
     customer_plan_id: string;
 

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

@@ -1,13 +1,21 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../resource';
-import { isRequestOptions } from '../../core';
-import * as Core from '../../core';
-import { CursorPage, type CursorPageParams } from '../../pagination';
+import { APIResource } from "../../resource.js";
+import { isRequestOptions } from "../../core.js";
+import * as Core from "../../core.js";
+import { CursorPage, type CursorPageParams } from "../../pagination.js";
 
 export class PricingUnits extends APIResource {
   /**
    * List all pricing units (known in the API by the legacy term "credit types").
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const pricingUnitListResponse of client.v1.pricingUnits.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: PricingUnitListParams,

package/src/resources/v1/services.ts

@@ -1,7 +1,7 @@
 // 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 Services extends APIResource {
   /**
@@ -9,6 +9,11 @@ export class Services extends APIResource {
    * 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.
+   *
+   * @example
+   * ```ts
+   * const services = await client.v1.services.list();
+   * ```
    */
   list(options?: Core.RequestOptions): Core.APIPromise<ServiceListResponse> {
     return this._client.get('/v1/services', options);

package/src/resources/v1/usage.ts

@@ -1,14 +1,24 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../resource';
-import { isRequestOptions } from '../../core';
-import * as Core from '../../core';
-import { CursorPage, type CursorPageParams } from '../../pagination';
+import { APIResource } from "../../resource.js";
+import { isRequestOptions } from "../../core.js";
+import * as Core from "../../core.js";
+import * as Shared from "../shared.js";
+import { CursorPage, type CursorPageParams } from "../../pagination.js";
 
 export class Usage extends APIResource {
   /**
    * Fetch aggregated usage data for multiple customers and billable-metrics, broken
    * into intervals of the specified length.
+   *
+   * @example
+   * ```ts
+   * const usages = await client.v1.usage.list({
+   *   ending_before: '2021-01-03T00:00:00Z',
+   *   starting_on: '2021-01-01T00:00:00Z',
+   *   window_size: 'day',
+   * });
+   * ```
    */
   list(params: UsageListParams, options?: Core.RequestOptions): Core.APIPromise<UsageListResponse> {
     const { next_page, ...body } = params;
@@ -21,6 +31,18 @@ export class Usage extends APIResource {
    * supported with a `Content-Encoding: gzip` header. See
    * [Getting usage into Metronome](https://docs.metronome.com/connect-metronome/) to
    * learn more about usage events.
+   *
+   * @example
+   * ```ts
+   * await client.v1.usage.ingest([
+   *   {
+   *     customer_id: 'team@example.com',
+   *     event_type: 'heartbeat',
+   *     timestamp: '2021-01-01T00:00:00Z',
+   *     transaction_id: '2021-01-01T00:00:00Z_cluster42',
+   *   },
+   * ]);
+   * ```
    */
   ingest(body?: UsageIngestParams, options?: Core.RequestOptions): Core.APIPromise<void>;
   ingest(options?: Core.RequestOptions): Core.APIPromise<void>;
@@ -41,6 +63,27 @@ export class Usage extends APIResource {
   /**
    * Fetch aggregated usage data for the specified customer, billable-metric, and
    * optional group, broken into intervals of the specified length.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const usageListWithGroupsResponse of client.v1.usage.listWithGroups(
+   *   {
+   *     billable_metric_id:
+   *       '222796fd-d29c-429e-89b2-549fabda4ed6',
+   *     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'],
+   *     },
+   *     starting_on: '2021-01-01T00:00:00Z',
+   *   },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listWithGroups(
     params: UsageListWithGroupsParams,
@@ -54,6 +97,23 @@ export class Usage extends APIResource {
       ...options,
     });
   }
+
+  /**
+   * For a set of events, look up matched billable metrics and customers by
+   * transaction id. This endpoint looks at transactions that occurred in the last 34
+   * days, and is intended for sampling-based testing workflows. It is heavily rate
+   * limited.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.usage.search({
+   *   transactionIds: ['2021-01-01T00:00:00Z_cluster42'],
+   * });
+   * ```
+   */
+  search(body: UsageSearchParams, options?: Core.RequestOptions): Core.APIPromise<UsageSearchResponse> {
+    return this._client.post('/v1/events/search', { body, ...options });
+  }
 }
 
 export class UsageListWithGroupsResponsesCursorPage extends CursorPage<UsageListWithGroupsResponse> {}
@@ -82,7 +142,7 @@ export namespace UsageListResponse {
      * Values will be either a number or null. Null indicates that there were no
      * matches for the group_by value.
      */
-    groups?: Record<string, number | null>;
+    groups?: { [key: string]: number | null };
   }
 }
 
@@ -98,6 +158,118 @@ export interface UsageListWithGroupsResponse {
   value: number | null;
 }
 
+export type UsageSearchResponse = Array<UsageSearchResponse.UsageSearchResponseItem>;
+
+export namespace UsageSearchResponse {
+  export interface UsageSearchResponseItem {
+    id: string;
+
+    /**
+     * The ID of the customer in the ingest event body
+     */
+    customer_id: string;
+
+    event_type: string;
+
+    timestamp: string;
+
+    transaction_id: string;
+
+    is_duplicate?: boolean;
+
+    matched_billable_metrics?: Array<UsageSearchResponseItem.MatchedBillableMetric>;
+
+    /**
+     * The customer the event was matched to if a match was found
+     */
+    matched_customer?: UsageSearchResponseItem.MatchedCustomer;
+
+    processed_at?: string;
+
+    properties?: { [key: string]: unknown };
+  }
+
+  export namespace UsageSearchResponseItem {
+    export interface MatchedBillableMetric {
+      id: string;
+
+      name: string;
+
+      /**
+       * (DEPRECATED) use aggregation_type instead
+       */
+      aggregate?: string;
+
+      /**
+       * (DEPRECATED) use aggregation_key instead
+       */
+      aggregate_keys?: Array<string>;
+
+      /**
+       * A key that specifies which property of the event is used to aggregate data. This
+       * key must be one of the property filter names and is not applicable when the
+       * aggregation type is 'count'.
+       */
+      aggregation_key?: string;
+
+      /**
+       * Specifies the type of aggregation performed on matching events.
+       */
+      aggregation_type?: 'COUNT' | 'LATEST' | 'MAX' | 'SUM' | 'UNIQUE';
+
+      /**
+       * RFC 3339 timestamp indicating when the billable metric was archived. If not
+       * provided, the billable metric is not archived.
+       */
+      archived_at?: string;
+
+      custom_fields?: { [key: string]: string };
+
+      /**
+       * An optional filtering rule to match the 'event_type' property of an event.
+       */
+      event_type_filter?: Shared.EventTypeFilter;
+
+      /**
+       * (DEPRECATED) use property_filters & event_type_filter instead
+       */
+      filter?: { [key: string]: unknown };
+
+      /**
+       * (DEPRECATED) use group_keys instead
+       */
+      group_by?: Array<string>;
+
+      /**
+       * Property names that are used to group usage costs on an invoice. Each entry
+       * represents a set of properties used to slice events into distinct buckets.
+       */
+      group_keys?: Array<Array<string>>;
+
+      /**
+       * A list of filters to match events to this billable metric. Each filter defines a
+       * rule on an event property. All rules must pass for the event to match the
+       * billable metric.
+       */
+      property_filters?: Array<Shared.PropertyFilter>;
+
+      /**
+       * The SQL query associated with the billable metric
+       */
+      sql?: string;
+    }
+
+    /**
+     * The customer the event was matched to if a match was found
+     */
+    export interface MatchedCustomer {
+      id?: string;
+
+      name?: string;
+    }
+  }
+}
+
 export interface UsageListParams {
   /**
    * Body param:
@@ -173,7 +345,7 @@ export namespace UsageIngestParams {
 
     transaction_id: string;
 
-    properties?: Record<string, unknown>;
+    properties?: { [key: string]: unknown };
   }
 }
 
@@ -234,15 +406,24 @@ export namespace UsageListWithGroupsParams {
   }
 }
 
+export interface UsageSearchParams {
+  /**
+   * The transaction IDs of the events to retrieve
+   */
+  transactionIds: Array<string>;
+}
+
 Usage.UsageListWithGroupsResponsesCursorPage = UsageListWithGroupsResponsesCursorPage;
 
 export declare namespace Usage {
   export {
     type UsageListResponse as UsageListResponse,
     type UsageListWithGroupsResponse as UsageListWithGroupsResponse,
+    type UsageSearchResponse as UsageSearchResponse,
     UsageListWithGroupsResponsesCursorPage as UsageListWithGroupsResponsesCursorPage,
     type UsageListParams as UsageListParams,
     type UsageIngestParams as UsageIngestParams,
     type UsageListWithGroupsParams as UsageListWithGroupsParams,
+    type UsageSearchParams as UsageSearchParams,
   };
 }

package/src/resources/v1/v1.ts

@@ -1,22 +1,22 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../resource';
-import * as AlertsAPI from './alerts';
+import { APIResource } from "../../resource.js";
+import * as AlertsAPI from "./alerts.js";
 import {
   AlertArchiveParams,
   AlertArchiveResponse,
   AlertCreateParams,
   AlertCreateResponse,
   Alerts,
-} from './alerts';
-import * as AuditLogsAPI from './audit-logs';
+} from "./alerts.js";
+import * as AuditLogsAPI from "./audit-logs.js";
 import {
   AuditLogListParams,
   AuditLogListResponse,
   AuditLogListResponsesCursorPage,
   AuditLogs,
-} from './audit-logs';
-import * as BillableMetricsAPI from './billable-metrics';
+} from "./audit-logs.js";
+import * as BillableMetricsAPI from "./billable-metrics.js";
 import {
   BillableMetricArchiveParams,
   BillableMetricArchiveResponse,
@@ -28,8 +28,8 @@ import {
   BillableMetricRetrieveParams,
   BillableMetricRetrieveResponse,
   BillableMetrics,
-} from './billable-metrics';
-import * as CreditGrantsAPI from './credit-grants';
+} from "./billable-metrics.js";
+import * as CreditGrantsAPI from "./credit-grants.js";
 import {
   CreditGrantCreateParams,
   CreditGrantCreateResponse,
@@ -46,8 +46,8 @@ import {
   CreditLedgerEntry,
   RolloverAmountMaxAmount,
   RolloverAmountMaxPercentage,
-} from './credit-grants';
-import * as CustomFieldsAPI from './custom-fields';
+} from "./credit-grants.js";
+import * as CustomFieldsAPI from "./custom-fields.js";
 import {
   CustomFieldAddKeyParams,
   CustomFieldDeleteValuesParams,
@@ -56,18 +56,18 @@ import {
   CustomFieldRemoveKeyParams,
   CustomFieldSetValuesParams,
   CustomFields,
-} from './custom-fields';
-import * as DashboardsAPI from './dashboards';
-import { DashboardGetEmbeddableURLParams, DashboardGetEmbeddableURLResponse, Dashboards } from './dashboards';
-import * as InvoicesAPI from './invoices';
+} from "./custom-fields.js";
+import * as DashboardsAPI from "./dashboards.js";
+import { DashboardGetEmbeddableURLParams, DashboardGetEmbeddableURLResponse, Dashboards } from "./dashboards.js";
+import * as InvoicesAPI from "./invoices.js";
 import {
   InvoiceRegenerateParams,
   InvoiceRegenerateResponse,
   InvoiceVoidParams,
   InvoiceVoidResponse,
   Invoices,
-} from './invoices';
-import * as PlansAPI from './plans';
+} from "./invoices.js";
+import * as PlansAPI from "./plans.js";
 import {
   PlanDetail,
   PlanGetDetailsParams,
@@ -82,17 +82,17 @@ import {
   PlanListResponse,
   PlanListResponsesCursorPage,
   Plans,
-} from './plans';
-import * as PricingUnitsAPI from './pricing-units';
+} from "./plans.js";
+import * as PricingUnitsAPI from "./pricing-units.js";
 import {
   PricingUnitListParams,
   PricingUnitListResponse,
   PricingUnitListResponsesCursorPage,
   PricingUnits,
-} from './pricing-units';
-import * as ServicesAPI from './services';
-import { ServiceListResponse, Services } from './services';
-import * as UsageAPI from './usage';
+} from "./pricing-units.js";
+import * as ServicesAPI from "./services.js";
+import { ServiceListResponse, Services } from "./services.js";
+import * as UsageAPI from "./usage.js";
 import {
   Usage,
   UsageIngestParams,
@@ -101,8 +101,10 @@ import {
   UsageListWithGroupsParams,
   UsageListWithGroupsResponse,
   UsageListWithGroupsResponsesCursorPage,
-} from './usage';
-import * as ContractsAPI from './contracts/contracts';
+  UsageSearchParams,
+  UsageSearchResponse,
+} from "./usage.js";
+import * as ContractsAPI from "./contracts/contracts.js";
 import {
   ContractAddManualBalanceEntryParams,
   ContractAmendParams,
@@ -121,14 +123,16 @@ import {
   ContractRetrieveRateScheduleParams,
   ContractRetrieveRateScheduleResponse,
   ContractRetrieveResponse,
+  ContractRetrieveSubscriptionQuantityHistoryParams,
+  ContractRetrieveSubscriptionQuantityHistoryResponse,
   ContractScheduleProServicesInvoiceParams,
   ContractScheduleProServicesInvoiceResponse,
   ContractSetUsageFilterParams,
   ContractUpdateEndDateParams,
   ContractUpdateEndDateResponse,
   Contracts,
-} from './contracts/contracts';
-import * as CustomersAPI from './customers/customers';
+} from "./contracts/contracts.js";
+import * as CustomersAPI from "./customers/customers.js";
 import {
   Customer,
   CustomerArchiveParams,
@@ -144,6 +148,8 @@ import {
   CustomerListCostsResponse,
   CustomerListCostsResponsesCursorPage,
   CustomerListParams,
+  CustomerPreviewEventsParams,
+  CustomerPreviewEventsResponse,
   CustomerRetrieveParams,
   CustomerRetrieveResponse,
   CustomerSetIngestAliasesParams,
@@ -151,7 +157,7 @@ import {
   CustomerSetNameResponse,
   CustomerUpdateConfigParams,
   Customers,
-} from './customers/customers';
+} from "./customers/customers.js";
 
 export class V1 extends APIResource {
   alerts: AlertsAPI.Alerts = new AlertsAPI.Alerts(this._client);
@@ -253,6 +259,7 @@ export declare namespace V1 {
     type CustomerArchiveResponse as CustomerArchiveResponse,
     type CustomerListBillableMetricsResponse as CustomerListBillableMetricsResponse,
     type CustomerListCostsResponse as CustomerListCostsResponse,
+    type CustomerPreviewEventsResponse as CustomerPreviewEventsResponse,
     type CustomerSetNameResponse as CustomerSetNameResponse,
     CustomerDetailsCursorPage as CustomerDetailsCursorPage,
     CustomerListBillableMetricsResponsesCursorPage as CustomerListBillableMetricsResponsesCursorPage,
@@ -263,6 +270,7 @@ export declare namespace V1 {
     type CustomerArchiveParams as CustomerArchiveParams,
     type CustomerListBillableMetricsParams as CustomerListBillableMetricsParams,
     type CustomerListCostsParams as CustomerListCostsParams,
+    type CustomerPreviewEventsParams as CustomerPreviewEventsParams,
     type CustomerSetIngestAliasesParams as CustomerSetIngestAliasesParams,
     type CustomerSetNameParams as CustomerSetNameParams,
     type CustomerUpdateConfigParams as CustomerUpdateConfigParams,
@@ -278,10 +286,12 @@ export declare namespace V1 {
     Usage as Usage,
     type UsageListResponse as UsageListResponse,
     type UsageListWithGroupsResponse as UsageListWithGroupsResponse,
+    type UsageSearchResponse as UsageSearchResponse,
     UsageListWithGroupsResponsesCursorPage as UsageListWithGroupsResponsesCursorPage,
     type UsageListParams as UsageListParams,
     type UsageIngestParams as UsageIngestParams,
     type UsageListWithGroupsParams as UsageListWithGroupsParams,
+    type UsageSearchParams as UsageSearchParams,
   };
 
   export {
@@ -334,6 +344,7 @@ export declare namespace V1 {
     type ContractCreateHistoricalInvoicesResponse as ContractCreateHistoricalInvoicesResponse,
     type ContractListBalancesResponse as ContractListBalancesResponse,
     type ContractRetrieveRateScheduleResponse as ContractRetrieveRateScheduleResponse,
+    type ContractRetrieveSubscriptionQuantityHistoryResponse as ContractRetrieveSubscriptionQuantityHistoryResponse,
     type ContractScheduleProServicesInvoiceResponse as ContractScheduleProServicesInvoiceResponse,
     type ContractUpdateEndDateResponse as ContractUpdateEndDateResponse,
     type ContractCreateParams as ContractCreateParams,
@@ -345,6 +356,7 @@ export declare namespace V1 {
     type ContractCreateHistoricalInvoicesParams as ContractCreateHistoricalInvoicesParams,
     type ContractListBalancesParams as ContractListBalancesParams,
     type ContractRetrieveRateScheduleParams as ContractRetrieveRateScheduleParams,
+    type ContractRetrieveSubscriptionQuantityHistoryParams as ContractRetrieveSubscriptionQuantityHistoryParams,
     type ContractScheduleProServicesInvoiceParams as ContractScheduleProServicesInvoiceParams,
     type ContractSetUsageFilterParams as ContractSetUsageFilterParams,
     type ContractUpdateEndDateParams as ContractUpdateEndDateParams,

package/src/resources/v1.ts

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