@metronome/sdk 0.1.0-beta.9 → 0.2.0

package/src/resources/v1/index.ts

@@ -6,13 +6,13 @@ export {
   type AlertArchiveResponse,
   type AlertCreateParams,
   type AlertArchiveParams,
-} from './alerts';
+} from "./alerts.js";
 export {
   AuditLogListResponsesCursorPage,
   AuditLogs,
   type AuditLogListResponse,
   type AuditLogListParams,
-} from './audit-logs';
+} from "./audit-logs.js";
 export {
   BillableMetricListResponsesCursorPage,
   BillableMetrics,
@@ -24,7 +24,7 @@ export {
   type BillableMetricRetrieveParams,
   type BillableMetricListParams,
   type BillableMetricArchiveParams,
-} from './billable-metrics';
+} from "./billable-metrics.js";
 export {
   Contracts,
   type ContractCreateResponse,
@@ -35,6 +35,7 @@ export {
   type ContractCreateHistoricalInvoicesResponse,
   type ContractListBalancesResponse,
   type ContractRetrieveRateScheduleResponse,
+  type ContractRetrieveSubscriptionQuantityHistoryResponse,
   type ContractScheduleProServicesInvoiceResponse,
   type ContractUpdateEndDateResponse,
   type ContractCreateParams,
@@ -46,10 +47,11 @@ export {
   type ContractCreateHistoricalInvoicesParams,
   type ContractListBalancesParams,
   type ContractRetrieveRateScheduleParams,
+  type ContractRetrieveSubscriptionQuantityHistoryParams,
   type ContractScheduleProServicesInvoiceParams,
   type ContractSetUsageFilterParams,
   type ContractUpdateEndDateParams,
-} from './contracts/index';
+} from "./contracts/index.js";
 export {
   CreditGrantListResponsesCursorPage,
   CreditGrants,
@@ -66,7 +68,7 @@ export {
   type CreditGrantEditParams,
   type CreditGrantListEntriesParams,
   type CreditGrantVoidParams,
-} from './credit-grants';
+} from "./credit-grants.js";
 export {
   CustomFields,
   type CustomFieldListKeysResponse,
@@ -75,7 +77,7 @@ export {
   type CustomFieldListKeysParams,
   type CustomFieldRemoveKeyParams,
   type CustomFieldSetValuesParams,
-} from './custom-fields';
+} from "./custom-fields.js";
 export {
   CustomerDetailsCursorPage,
   CustomerListBillableMetricsResponsesCursorPage,
@@ -88,6 +90,7 @@ export {
   type CustomerArchiveResponse,
   type CustomerListBillableMetricsResponse,
   type CustomerListCostsResponse,
+  type CustomerPreviewEventsResponse,
   type CustomerSetNameResponse,
   type CustomerCreateParams,
   type CustomerRetrieveParams,
@@ -95,22 +98,23 @@ export {
   type CustomerArchiveParams,
   type CustomerListBillableMetricsParams,
   type CustomerListCostsParams,
+  type CustomerPreviewEventsParams,
   type CustomerSetIngestAliasesParams,
   type CustomerSetNameParams,
   type CustomerUpdateConfigParams,
-} from './customers/index';
+} from "./customers/index.js";
 export {
   Dashboards,
   type DashboardGetEmbeddableURLResponse,
   type DashboardGetEmbeddableURLParams,
-} from './dashboards';
+} from "./dashboards.js";
 export {
   Invoices,
   type InvoiceRegenerateResponse,
   type InvoiceVoidResponse,
   type InvoiceRegenerateParams,
   type InvoiceVoidParams,
-} from './invoices';
+} from "./invoices.js";
 export {
   PlanListResponsesCursorPage,
   PlanListChargesResponsesCursorPage,
@@ -125,21 +129,23 @@ export {
   type PlanGetDetailsParams,
   type PlanListChargesParams,
   type PlanListCustomersParams,
-} from './plans';
+} from "./plans.js";
 export {
   PricingUnitListResponsesCursorPage,
   PricingUnits,
   type PricingUnitListResponse,
   type PricingUnitListParams,
-} from './pricing-units';
-export { Services, type ServiceListResponse } from './services';
+} from "./pricing-units.js";
+export { Services, type ServiceListResponse } from "./services.js";
 export {
   UsageListWithGroupsResponsesCursorPage,
   Usage,
   type UsageListResponse,
   type UsageListWithGroupsResponse,
+  type UsageSearchResponse,
   type UsageListParams,
   type UsageIngestParams,
   type UsageListWithGroupsParams,
-} from './usage';
-export { V1 } from './v1';
+  type UsageSearchParams,
+} from "./usage.js";
+export { V1 } from "./v1.js";

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,
   };
 }