@metronome/sdk 0.1.0-beta.8 → 0.1.0

package/src/resources/{customers → v1/customers}/credits.ts

@@ -1,32 +1,72 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../resource';
-import * as Core from '../../core';
-import * as Shared from '../shared';
+import { APIResource } from "../../../resource.js";
+import * as Core from "../../../core.js";
+import * as Shared from "../../shared.js";
 
 export class Credits extends APIResource {
   /**
    * Create a new credit at the customer level.
+   *
+   * @example
+   * ```ts
+   * const credit = await client.v1.customers.credits.create({
+   *   access_schedule: {
+   *     credit_type_id: '2714e483-4ff1-48e4-9e25-ac732e8f24f2',
+   *     schedule_items: [
+   *       {
+   *         amount: 1000,
+   *         starting_at: '2020-01-01T00:00:00.000Z',
+   *         ending_before: '2020-02-01T00:00:00.000Z',
+   *       },
+   *     ],
+   *   },
+   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   priority: 100,
+   *   product_id: 'f14d6729-6a44-4b13-9908-9387f1918790',
+   *   name: 'My Credit',
+   * });
+   * ```
    */
   create(body: CreditCreateParams, options?: Core.RequestOptions): Core.APIPromise<CreditCreateResponse> {
-    return this._client.post('/contracts/customerCredits/create', { body, ...options });
+    return this._client.post('/v1/contracts/customerCredits/create', { body, ...options });
   }
 
   /**
    * List credits.
+   *
+   * @example
+   * ```ts
+   * const credits = await client.v1.customers.credits.list({
+   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   credit_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   *   include_ledgers: true,
+   * });
+   * ```
    */
   list(body: CreditListParams, options?: Core.RequestOptions): Core.APIPromise<CreditListResponse> {
-    return this._client.post('/contracts/customerCredits/list', { body, ...options });
+    return this._client.post('/v1/contracts/customerCredits/list', { body, ...options });
   }
 
   /**
-   * Update the end date of a credit
+   * Pull forward the end date of a credit. Use the "edit a credit" endpoint to
+   * extend the end date of a credit, or to make other edits to the credit.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.customers.credits.updateEndDate({
+   *     access_ending_before: '2020-01-01T00:00:00.000Z',
+   *     credit_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   *     customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   });
+   * ```
    */
   updateEndDate(
     body: CreditUpdateEndDateParams,
     options?: Core.RequestOptions,
   ): Core.APIPromise<CreditUpdateEndDateResponse> {
-    return this._client.post('/contracts/customerCredits/updateEndDate', { body, ...options });
+    return this._client.post('/v1/contracts/customerCredits/updateEndDate', { body, ...options });
   }
 }
 
@@ -78,7 +118,7 @@ export interface CreditCreateParams {
    */
   applicable_product_tags?: Array<string>;
 
-  custom_fields?: Record<string, string>;
+  custom_fields?: { [key: string]: string };
 
   /**
    * Used only in UI/API. It is not exposed to end customers.
@@ -102,6 +142,14 @@ export interface CreditCreateParams {
    */
   salesforce_opportunity_id?: string;
 
+  /**
+   * 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
+   * specifiers to contribute to a commit's or credit's drawdown. This field cannot
+   * be used together with `applicable_product_ids` or `applicable_product_tags`.
+   */
+  specifiers?: Array<CreditCreateParams.Specifier>;
+
   /**
    * Prevents the creation of duplicates. If a request to create a commit or credit
    * is made with a uniqueness key that was previously used to create a commit or
@@ -139,6 +187,23 @@ export namespace CreditCreateParams {
       starting_at: string;
     }
   }
+
+  export interface Specifier {
+    presentation_group_values?: { [key: string]: string };
+
+    pricing_group_values?: { [key: string]: string };
+
+    /**
+     * If provided, the specifier will only apply to the product with the specified ID.
+     */
+    product_id?: string;
+
+    /**
+     * If provided, the specifier will only apply to products with all the specified
+     * tags.
+     */
+    product_tags?: Array<string>;
+  }
 }
 
 export interface CreditListParams {
@@ -157,7 +222,7 @@ export interface CreditListParams {
   effective_before?: string;
 
   /**
-   * Include credits from archived contracts.
+   * Include archived credits and credits from archived contracts.
    */
   include_archived?: boolean;
 
@@ -178,6 +243,11 @@ export interface CreditListParams {
    */
   include_ledgers?: boolean;
 
+  /**
+   * The maximum number of commits to return. Defaults to 25.
+   */
+  limit?: number;
+
   /**
    * The next page token from a previous response.
    */

package/src/resources/{customers → 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,24 +90,57 @@ 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('/customers', { body, ...options });
+    return this._client.post('/v1/customers', { body, ...options });
   }
 
   /**
    * 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,
     options?: Core.RequestOptions,
   ): Core.APIPromise<CustomerRetrieveResponse> {
     const { customer_id } = params;
-    return this._client.get(`/customers/${customer_id}`, options);
+    return this._client.get(`/v1/customers/${customer_id}`, options);
   }
 
   /**
    * List all customers.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const customerDetail of client.v1.customers.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: CustomerListParams,
@@ -121,21 +154,39 @@ export class Customers extends APIResource {
     if (isRequestOptions(query)) {
       return this.list({}, query);
     }
-    return this._client.getAPIList('/customers', CustomerDetailsCursorPage, { query, ...options });
+    return this._client.getAPIList('/v1/customers', CustomerDetailsCursorPage, { query, ...options });
   }
 
   /**
-   * 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,
     options?: Core.RequestOptions,
   ): Core.APIPromise<CustomerArchiveResponse> {
-    return this._client.post('/customers/archive', { body, ...options });
+    return this._client.post('/v1/customers/archive', { body, ...options });
   }
 
   /**
    * 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,
@@ -143,7 +194,7 @@ export class Customers extends APIResource {
   ): Core.PagePromise<CustomerListBillableMetricsResponsesCursorPage, CustomerListBillableMetricsResponse> {
     const { customer_id, ...query } = params;
     return this._client.getAPIList(
-      `/customers/${customer_id}/billable-metrics`,
+      `/v1/customers/${customer_id}/billable-metrics`,
       CustomerListBillableMetricsResponsesCursorPage,
       { query, ...options },
     );
@@ -153,29 +204,80 @@ 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,
     options?: Core.RequestOptions,
   ): Core.PagePromise<CustomerListCostsResponsesCursorPage, CustomerListCostsResponse> {
     const { customer_id, ...query } = params;
-    return this._client.getAPIList(`/customers/${customer_id}/costs`, CustomerListCostsResponsesCursorPage, {
-      query,
-      ...options,
-    });
+    return this._client.getAPIList(
+      `/v1/customers/${customer_id}/costs`,
+      CustomerListCostsResponsesCursorPage,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * 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,
     options?: Core.RequestOptions,
   ): Core.APIPromise<void> {
     const { customer_id, ...body } = params;
-    return this._client.post(`/customers/${customer_id}/setIngestAliases`, {
+    return this._client.post(`/v1/customers/${customer_id}/setIngestAliases`, {
       body,
       ...options,
       headers: { Accept: '*/*', ...options?.headers },
@@ -184,21 +286,37 @@ 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,
     options?: Core.RequestOptions,
   ): Core.APIPromise<CustomerSetNameResponse> {
     const { customer_id, ...body } = params;
-    return this._client.post(`/customers/${customer_id}/setName`, { body, ...options });
+    return this._client.post(`/v1/customers/${customer_id}/setName`, { body, ...options });
   }
 
   /**
    * 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;
-    return this._client.post(`/customers/${customer_id}/updateConfig`, {
+    return this._client.post(`/v1/customers/${customer_id}/updateConfig`, {
       body,
       ...options,
       headers: { Accept: '*/*', ...options?.headers },
@@ -232,7 +350,7 @@ export interface Customer {
 
   name: string;
 
-  custom_fields?: Record<string, string>;
+  custom_fields?: { [key: string]: string };
 }
 
 export interface CustomerDetail {
@@ -241,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;
 
@@ -259,6 +382,12 @@ export interface CustomerDetail {
 
   name: string;
 
+  /**
+   * RFC 3339 timestamp indicating when the customer was archived. Null if the
+   * customer is active.
+   */
+  archived_at?: string | null;
+
   /**
    * This field's availability is dependent on your client's configuration.
    */
@@ -328,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.
@@ -338,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
@@ -365,7 +494,7 @@ export interface CustomerListBillableMetricsResponse {
 }
 
 export interface CustomerListCostsResponse {
-  credit_types: Record<string, CustomerListCostsResponse.CreditTypes>;
+  credit_types: { [key: string]: CustomerListCostsResponse.CreditTypes };
 
   end_timestamp: string;
 
@@ -394,6 +523,10 @@ export namespace CustomerListCostsResponse {
   }
 }
 
+export interface CustomerPreviewEventsResponse {
+  data: InvoicesAPI.Invoice;
+}
+
 export interface CustomerSetNameResponse {
   data: Customer;
 }
@@ -406,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>;
 
@@ -485,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
@@ -517,7 +650,8 @@ export interface CustomerListParams extends CursorPageParams {
   ingest_alias?: string;
 
   /**
-   * Filter the customer list by only archived customers.
+   * Filter the customer list to only return archived customers. By default, only
+   * active customers are returned.
    */
   only_archived?: boolean;
 
@@ -567,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:
@@ -634,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,
@@ -644,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,