@metronome/sdk 0.1.0-beta.9 → 0.2.0

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

@@ -1,10 +1,10 @@
 // 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 AlertsAPI from './alerts';
+import { APIResource } from "../../../resource.js";
+import { isRequestOptions } from "../../../core.js";
+import * as Core from "../../../core.js";
+import * as Shared from "../../shared.js";
+import * as AlertsAPI from "./alerts.js";
 import {
   AlertListParams,
   AlertListResponse,
@@ -13,16 +13,16 @@ import {
   AlertRetrieveResponse,
   Alerts,
   CustomerAlert,
-} from './alerts';
-import * as BillingConfigAPI from './billing-config';
+} from "./alerts.js";
+import * as BillingConfigAPI from "./billing-config.js";
 import {
   BillingConfig as BillingConfigAPIBillingConfig,
   BillingConfigCreateParams,
   BillingConfigDeleteParams,
   BillingConfigRetrieveParams,
   BillingConfigRetrieveResponse,
-} from './billing-config';
-import * as CommitsAPI from './commits';
+} from "./billing-config.js";
+import * as CommitsAPI from "./commits.js";
 import {
   CommitCreateParams,
   CommitCreateResponse,
@@ -31,8 +31,8 @@ import {
   CommitUpdateEndDateParams,
   CommitUpdateEndDateResponse,
   Commits,
-} from './commits';
-import * as CreditsAPI from './credits';
+} from "./commits.js";
+import * as CreditsAPI from "./credits.js";
 import {
   CreditCreateParams,
   CreditCreateResponse,
@@ -41,8 +41,8 @@ import {
   CreditUpdateEndDateParams,
   CreditUpdateEndDateResponse,
   Credits,
-} from './credits';
-import * as InvoicesAPI from './invoices';
+} from "./credits.js";
+import * as InvoicesAPI from "./invoices.js";
 import {
   Invoice,
   InvoiceAddChargeParams,
@@ -55,15 +55,15 @@ import {
   InvoiceRetrieveResponse,
   Invoices,
   InvoicesCursorPage,
-} from './invoices';
-import * as NamedSchedulesAPI from './named-schedules';
+} from "./invoices.js";
+import * as NamedSchedulesAPI from "./named-schedules.js";
 import {
   NamedScheduleRetrieveParams,
   NamedScheduleRetrieveResponse,
   NamedScheduleUpdateParams,
   NamedSchedules,
-} from './named-schedules';
-import * as PlansAPI from './plans';
+} from "./named-schedules.js";
+import * as PlansAPI from "./plans.js";
 import {
   PlanAddParams,
   PlanAddResponse,
@@ -76,8 +76,8 @@ import {
   PlanListResponse,
   PlanListResponsesCursorPage,
   Plans,
-} from './plans';
-import { CursorPage, type CursorPageParams } from '../../../pagination';
+} from "./plans.js";
+import { CursorPage, type CursorPageParams } from "../../../pagination.js";
 
 export class Customers extends APIResource {
   alerts: AlertsAPI.Alerts = new AlertsAPI.Alerts(this._client);
@@ -90,6 +90,24 @@ export class Customers extends APIResource {
 
   /**
    * Create a new customer
+   *
+   * @example
+   * ```ts
+   * const customer = await client.v1.customers.create({
+   *   name: 'Example, Inc.',
+   *   customer_billing_provider_configurations: [
+   *     {
+   *       billing_provider: 'stripe',
+   *       delivery_method: 'direct_to_billing_provider',
+   *       configuration: {
+   *         stripe_customer_id: 'cus_123',
+   *         stripe_collection_method: 'charge_automatically',
+   *       },
+   *     },
+   *   ],
+   *   ingest_aliases: ['team@example.com'],
+   * });
+   * ```
    */
   create(body: CustomerCreateParams, options?: Core.RequestOptions): Core.APIPromise<CustomerCreateResponse> {
     return this._client.post('/v1/customers', { body, ...options });
@@ -97,6 +115,13 @@ export class Customers extends APIResource {
 
   /**
    * Get a customer by Metronome ID.
+   *
+   * @example
+   * ```ts
+   * const customer = await client.v1.customers.retrieve({
+   *   customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   * });
+   * ```
    */
   retrieve(
     params: CustomerRetrieveParams,
@@ -108,6 +133,14 @@ export class Customers extends APIResource {
 
   /**
    * List all customers.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const customerDetail of client.v1.customers.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: CustomerListParams,
@@ -125,7 +158,15 @@ export class Customers extends APIResource {
   }
 
   /**
-   * Archive a customer
+   * Archive a customer Note: any alerts associated with the customer will not be
+   * triggered.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.archive({
+   *   id: '8deed800-1b7a-495d-a207-6c52bac54dc9',
+   * });
+   * ```
    */
   archive(
     body: CustomerArchiveParams,
@@ -136,6 +177,16 @@ export class Customers extends APIResource {
 
   /**
    * Get all billable metrics for a given customer.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const customerListBillableMetricsResponse of client.v1.customers.listBillableMetrics(
+   *   { customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listBillableMetrics(
     params: CustomerListBillableMetricsParams,
@@ -153,6 +204,20 @@ export class Customers extends APIResource {
    * Fetch daily pending costs for the specified customer, broken down by credit type
    * and line items. Note: this is not supported for customers whose plan includes a
    * UNIQUE-type billable metric.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const customerListCostsResponse of client.v1.customers.listCosts(
+   *   {
+   *     customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *     ending_before: '2019-12-27T18:11:19.117Z',
+   *     starting_on: '2019-12-27T18:11:19.117Z',
+   *   },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listCosts(
     params: CustomerListCostsParams,
@@ -166,10 +231,46 @@ export class Customers extends APIResource {
     );
   }
 
+  /**
+   * Preview how a set of events will affect a customer's invoice. Generates a draft
+   * invoice for a customer using their current contract configuration and the
+   * provided events. This is useful for testing how new events will affect the
+   * customer's invoice before they are actually processed.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.previewEvents({
+   *   customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *   events: [
+   *     {
+   *       event_type: 'heartbeat',
+   *       timestamp: '2021-01-01T00:00:00Z',
+   *       properties: { cpu_hours: 100, memory_gb_hours: 200 },
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  previewEvents(
+    params: CustomerPreviewEventsParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<CustomerPreviewEventsResponse> {
+    const { customer_id, ...body } = params;
+    return this._client.post(`/v1/customers/${customer_id}/previewEvents`, { body, ...options });
+  }
+
   /**
    * Sets the ingest aliases for a customer. Ingest aliases can be used in the
    * `customer_id` field when sending usage events to Metronome. This call is
    * idempotent. It fully replaces the set of ingest aliases for the given customer.
+   *
+   * @example
+   * ```ts
+   * await client.v1.customers.setIngestAliases({
+   *   customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *   ingest_aliases: ['team@example.com'],
+   * });
+   * ```
    */
   setIngestAliases(
     params: CustomerSetIngestAliasesParams,
@@ -185,6 +286,14 @@ export class Customers extends APIResource {
 
   /**
    * Updates the specified customer's name.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.setName({
+   *   customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *   name: 'Example, Inc.',
+   * });
+   * ```
    */
   setName(
     params: CustomerSetNameParams,
@@ -196,6 +305,14 @@ export class Customers extends APIResource {
 
   /**
    * Updates the specified customer's config.
+   *
+   * @example
+   * ```ts
+   * await client.v1.customers.updateConfig({
+   *   customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *   salesforce_account_id: '0015500001WO1ZiABL',
+   * });
+   * ```
    */
   updateConfig(params: CustomerUpdateConfigParams, options?: Core.RequestOptions): Core.APIPromise<void> {
     const { customer_id, ...body } = params;
@@ -233,7 +350,7 @@ export interface Customer {
 
   name: string;
 
-  custom_fields?: Record<string, string>;
+  custom_fields?: { [key: string]: string };
 }
 
 export interface CustomerDetail {
@@ -242,7 +359,12 @@ export interface CustomerDetail {
    */
   id: string;
 
-  custom_fields: Record<string, string>;
+  /**
+   * RFC 3339 timestamp indicating when the customer was created.
+   */
+  created_at: string;
+
+  custom_fields: { [key: string]: string };
 
   customer_config: CustomerDetail.CustomerConfig;
 
@@ -335,7 +457,7 @@ export interface CustomerListBillableMetricsResponse {
    */
   archived_at?: string;
 
-  custom_fields?: Record<string, string>;
+  custom_fields?: { [key: string]: string };
 
   /**
    * An optional filtering rule to match the 'event_type' property of an event.
@@ -345,7 +467,7 @@ export interface CustomerListBillableMetricsResponse {
   /**
    * (DEPRECATED) use property_filters & event_type_filter instead
    */
-  filter?: Record<string, unknown>;
+  filter?: { [key: string]: unknown };
 
   /**
    * (DEPRECATED) use group_keys instead
@@ -372,7 +494,7 @@ export interface CustomerListBillableMetricsResponse {
 }
 
 export interface CustomerListCostsResponse {
-  credit_types: Record<string, CustomerListCostsResponse.CreditTypes>;
+  credit_types: { [key: string]: CustomerListCostsResponse.CreditTypes };
 
   end_timestamp: string;
 
@@ -401,6 +523,10 @@ export namespace CustomerListCostsResponse {
   }
 }
 
+export interface CustomerPreviewEventsResponse {
+  data: InvoicesAPI.Invoice;
+}
+
 export interface CustomerSetNameResponse {
   data: Customer;
 }
@@ -413,7 +539,7 @@ export interface CustomerCreateParams {
 
   billing_config?: CustomerCreateParams.BillingConfig;
 
-  custom_fields?: Record<string, string>;
+  custom_fields?: { [key: string]: string };
 
   customer_billing_provider_configurations?: Array<CustomerCreateParams.CustomerBillingProviderConfiguration>;
 
@@ -492,7 +618,7 @@ export namespace CustomerCreateParams {
      * object, however, for most billing provider + delivery method combinations, it
      * will not be a valid configuration.
      */
-    configuration?: Record<string, unknown>;
+    configuration?: { [key: string]: unknown };
 
     /**
      * The method to use for delivering invoices to this customer. If not provided, the
@@ -575,6 +701,59 @@ export interface CustomerListCostsParams extends CursorPageParams {
   starting_on: string;
 }
 
+export interface CustomerPreviewEventsParams {
+  /**
+   * Path param:
+   */
+  customer_id: string;
+
+  /**
+   * Body param:
+   */
+  events: Array<CustomerPreviewEventsParams.Event>;
+
+  /**
+   * Body param: If set to "replace", the preview will be generated as if those were
+   * the only events for the specified customer. If set to "merge", the events will
+   * be merged with any existing events for the specified customer. Defaults to
+   * "replace".
+   */
+  mode?: 'replace' | 'merge';
+
+  /**
+   * Body param: If set, all zero quantity line items will be filtered out of the
+   * response.
+   */
+  skip_zero_qty_line_items?: boolean;
+}
+
+export namespace CustomerPreviewEventsParams {
+  export interface Event {
+    event_type: string;
+
+    /**
+     * This has no effect for preview events, but may be set for consistency with Event
+     * objects. They will be processed even if they do not match the customer's ID or
+     * ingest aliases.
+     */
+    customer_id?: string;
+
+    properties?: { [key: string]: unknown };
+
+    /**
+     * RFC 3339 formatted. If not provided, the current time will be used.
+     */
+    timestamp?: string;
+
+    /**
+     * This has no effect for preview events, but may be set for consistency with Event
+     * objects. Duplicate transaction_ids are NOT filtered out, even within the same
+     * request.
+     */
+    transaction_id?: string;
+  }
+}
+
 export interface CustomerSetIngestAliasesParams {
   /**
    * Path param:
@@ -642,6 +821,7 @@ export declare namespace Customers {
     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,
@@ -652,6 +832,7 @@ export declare namespace Customers {
     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,

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

@@ -8,14 +8,14 @@ export {
   type AlertRetrieveParams,
   type AlertListParams,
   type AlertResetParams,
-} from './alerts';
+} from "./alerts.js";
 export {
   BillingConfig,
   type BillingConfigRetrieveResponse,
   type BillingConfigCreateParams,
   type BillingConfigRetrieveParams,
   type BillingConfigDeleteParams,
-} from './billing-config';
+} from "./billing-config.js";
 export {
   Commits,
   type CommitCreateResponse,
@@ -24,7 +24,7 @@ export {
   type CommitCreateParams,
   type CommitListParams,
   type CommitUpdateEndDateParams,
-} from './commits';
+} from "./commits.js";
 export {
   Credits,
   type CreditCreateResponse,
@@ -33,7 +33,7 @@ export {
   type CreditCreateParams,
   type CreditListParams,
   type CreditUpdateEndDateParams,
-} from './credits';
+} from "./credits.js";
 export {
   CustomerDetailsCursorPage,
   CustomerListBillableMetricsResponsesCursorPage,
@@ -46,6 +46,7 @@ export {
   type CustomerArchiveResponse,
   type CustomerListBillableMetricsResponse,
   type CustomerListCostsResponse,
+  type CustomerPreviewEventsResponse,
   type CustomerSetNameResponse,
   type CustomerCreateParams,
   type CustomerRetrieveParams,
@@ -53,10 +54,11 @@ export {
   type CustomerArchiveParams,
   type CustomerListBillableMetricsParams,
   type CustomerListCostsParams,
+  type CustomerPreviewEventsParams,
   type CustomerSetIngestAliasesParams,
   type CustomerSetNameParams,
   type CustomerUpdateConfigParams,
-} from './customers';
+} from "./customers.js";
 export {
   InvoicesCursorPage,
   InvoiceListBreakdownsResponsesCursorPage,
@@ -69,13 +71,13 @@ export {
   type InvoiceListParams,
   type InvoiceAddChargeParams,
   type InvoiceListBreakdownsParams,
-} from './invoices';
+} from "./invoices.js";
 export {
   NamedSchedules,
   type NamedScheduleRetrieveResponse,
   type NamedScheduleRetrieveParams,
   type NamedScheduleUpdateParams,
-} from './named-schedules';
+} from "./named-schedules.js";
 export {
   PlanListResponsesCursorPage,
   PlanListPriceAdjustmentsResponsesCursorPage,
@@ -88,4 +90,4 @@ export {
   type PlanAddParams,
   type PlanEndParams,
   type PlanListPriceAdjustmentsParams,
-} from './plans';
+} from "./plans.js";