@metronome/sdk 0.3.0 → 2.0.0

package/src/resources/v1/credit-grants.ts

@@ -1,11 +1,17 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from "../../resource.js";
-import { isRequestOptions } from "../../core.js";
-import * as Core from "../../core.js";
-import * as CreditGrantsAPI from "./credit-grants.js";
-import * as Shared from "../shared.js";
-import { CursorPage, type CursorPageParams } from "../../pagination.js";
+import { APIResource } from '../../core/resource';
+import * as CreditGrantsAPI from './credit-grants';
+import * as Shared from '../shared';
+import { APIPromise } from '../../core/api-promise';
+import {
+  CursorPage,
+  type CursorPageParams,
+  CursorPageWithoutLimit,
+  type CursorPageWithoutLimitParams,
+  PagePromise,
+} from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
 
 export class CreditGrants extends APIResource {
   /**
@@ -32,10 +38,7 @@ export class CreditGrants extends APIResource {
    * });
    * ```
    */
-  create(
-    body: CreditGrantCreateParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<CreditGrantCreateResponse> {
+  create(body: CreditGrantCreateParams, options?: RequestOptions): APIPromise<CreditGrantCreateResponse> {
     return this._client.post('/v1/credits/createGrant', { body, ...options });
   }
 
@@ -63,21 +66,11 @@ export class CreditGrants extends APIResource {
    * ```
    */
   list(
-    params?: CreditGrantListParams,
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<CreditGrantListResponsesCursorPage, CreditGrantListResponse>;
-  list(
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<CreditGrantListResponsesCursorPage, CreditGrantListResponse>;
-  list(
-    params: CreditGrantListParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.PagePromise<CreditGrantListResponsesCursorPage, CreditGrantListResponse> {
-    if (isRequestOptions(params)) {
-      return this.list({}, params);
-    }
-    const { limit, next_page, ...body } = params;
-    return this._client.getAPIList('/v1/credits/listGrants', CreditGrantListResponsesCursorPage, {
+    params: CreditGrantListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CreditGrantListResponsesCursorPage, CreditGrantListResponse> {
+    const { limit, next_page, ...body } = params ?? {};
+    return this._client.getAPIList('/v1/credits/listGrants', CursorPage<CreditGrantListResponse>, {
       query: { limit, next_page },
       body,
       method: 'post',
@@ -97,7 +90,7 @@ export class CreditGrants extends APIResource {
    * });
    * ```
    */
-  edit(body: CreditGrantEditParams, options?: Core.RequestOptions): Core.APIPromise<CreditGrantEditResponse> {
+  edit(body: CreditGrantEditParams, options?: RequestOptions): APIPromise<CreditGrantEditResponse> {
     return this._client.post('/v1/credits/editGrant', { body, ...options });
   }
 
@@ -108,28 +101,31 @@ export class CreditGrants extends APIResource {
    *
    * @example
    * ```ts
-   * const response = await client.v1.creditGrants.listEntries({
-   *   credit_type_ids: ['2714e483-4ff1-48e4-9e25-ac732e8f24f2'],
-   *   customer_ids: ['6a37bb88-8538-48c5-b37b-a41c836328bd'],
-   *   ending_before: '2021-02-01T00:00:00Z',
-   *   starting_on: '2021-01-01T00:00:00Z',
-   * });
+   * // Automatically fetches more pages as needed.
+   * for await (const creditGrantListEntriesResponse of client.v1.creditGrants.listEntries(
+   *   {
+   *     credit_type_ids: [
+   *       '2714e483-4ff1-48e4-9e25-ac732e8f24f2',
+   *     ],
+   *     customer_ids: ['6a37bb88-8538-48c5-b37b-a41c836328bd'],
+   *     ending_before: '2021-02-01T00:00:00Z',
+   *     starting_on: '2021-01-01T00:00:00Z',
+   *   },
+   * )) {
+   *   // ...
+   * }
    * ```
    */
   listEntries(
-    params?: CreditGrantListEntriesParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<CreditGrantListEntriesResponse>;
-  listEntries(options?: Core.RequestOptions): Core.APIPromise<CreditGrantListEntriesResponse>;
-  listEntries(
-    params: CreditGrantListEntriesParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<CreditGrantListEntriesResponse> {
-    if (isRequestOptions(params)) {
-      return this.listEntries({}, params);
-    }
-    const { next_page, sort, ...body } = params;
-    return this._client.post('/v1/credits/listEntries', { query: { next_page, sort }, body, ...options });
+    params: CreditGrantListEntriesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CreditGrantListEntriesResponsesCursorPageWithoutLimit, CreditGrantListEntriesResponse> {
+    const { next_page, sort, ...body } = params ?? {};
+    return this._client.getAPIList(
+      '/v1/credits/listEntries',
+      CursorPageWithoutLimit<CreditGrantListEntriesResponse>,
+      { query: { next_page, sort }, body, method: 'post', ...options },
+    );
   }
 
   /**
@@ -142,12 +138,15 @@ export class CreditGrants extends APIResource {
    * });
    * ```
    */
-  void(body: CreditGrantVoidParams, options?: Core.RequestOptions): Core.APIPromise<CreditGrantVoidResponse> {
+  void(body: CreditGrantVoidParams, options?: RequestOptions): APIPromise<CreditGrantVoidResponse> {
     return this._client.post('/v1/credits/voidGrant', { body, ...options });
   }
 }
 
-export class CreditGrantListResponsesCursorPage extends CursorPage<CreditGrantListResponse> {}
+export type CreditGrantListResponsesCursorPage = CursorPage<CreditGrantListResponse>;
+
+export type CreditGrantListEntriesResponsesCursorPageWithoutLimit =
+  CursorPageWithoutLimit<CreditGrantListEntriesResponse>;
 
 export interface CreditLedgerEntry {
   /**
@@ -221,6 +220,9 @@ export interface CreditGrantListResponse {
    */
   balance: CreditGrantListResponse.Balance;
 
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields: { [key: string]: string };
 
   /**
@@ -336,78 +338,70 @@ export interface CreditGrantEditResponse {
 }
 
 export interface CreditGrantListEntriesResponse {
-  data: Array<CreditGrantListEntriesResponse.Data>;
+  customer_id: string;
 
-  next_page: string | null;
+  ledgers: Array<CreditGrantListEntriesResponse.Ledger>;
 }
 
 export namespace CreditGrantListEntriesResponse {
-  export interface Data {
-    customer_id: string;
+  export interface Ledger {
+    credit_type: Shared.CreditTypeData;
 
-    ledgers: Array<Data.Ledger>;
+    /**
+     * the effective balances at the end of the specified time window
+     */
+    ending_balance: Ledger.EndingBalance;
+
+    entries: Array<CreditGrantsAPI.CreditLedgerEntry>;
+
+    pending_entries: Array<CreditGrantsAPI.CreditLedgerEntry>;
+
+    starting_balance: Ledger.StartingBalance;
   }
 
-  export namespace Data {
-    export interface Ledger {
-      credit_type: Shared.CreditTypeData;
+  export namespace Ledger {
+    /**
+     * the effective balances at the end of the specified time window
+     */
+    export interface EndingBalance {
+      /**
+       * the ending_before request parameter (if supplied) or the current billing
+       * period's end date
+       */
+      effective_at: string;
 
       /**
-       * the effective balances at the end of the specified time window
+       * the ending balance, including the balance of all grants that have not expired
+       * before the effective_at date and deductions that happened before the
+       * effective_at date
        */
-      ending_balance: Ledger.EndingBalance;
+      excluding_pending: number;
 
-      entries: Array<CreditGrantsAPI.CreditLedgerEntry>;
+      /**
+       * the excluding_pending balance plus any pending invoice deductions and
+       * expirations that will happen by the effective_at date
+       */
+      including_pending: number;
+    }
 
-      pending_entries: Array<CreditGrantsAPI.CreditLedgerEntry>;
+    export interface StartingBalance {
+      /**
+       * the starting_on request parameter (if supplied) or the first credit grant's
+       * effective_at date
+       */
+      effective_at: string;
 
-      starting_balance: Ledger.StartingBalance;
-    }
+      /**
+       * the starting balance, including all posted grants, deductions, and expirations
+       * that happened at or before the effective_at timestamp
+       */
+      excluding_pending: number;
 
-    export namespace Ledger {
       /**
-       * the effective balances at the end of the specified time window
+       * the excluding_pending balance plus any pending activity that has not been posted
+       * at the time of the query
        */
-      export interface EndingBalance {
-        /**
-         * the ending_before request parameter (if supplied) or the current billing
-         * period's end date
-         */
-        effective_at: string;
-
-        /**
-         * the ending balance, including the balance of all grants that have not expired
-         * before the effective_at date and deductions that happened before the
-         * effective_at date
-         */
-        excluding_pending: number;
-
-        /**
-         * the excluding_pending balance plus any pending invoice deductions and
-         * expirations that will happen by the effective_at date
-         */
-        including_pending: number;
-      }
-
-      export interface StartingBalance {
-        /**
-         * the starting_on request parameter (if supplied) or the first credit grant's
-         * effective_at date
-         */
-        effective_at: string;
-
-        /**
-         * the starting balance, including all posted grants, deductions, and expirations
-         * that happened at or before the effective_at timestamp
-         */
-        excluding_pending: number;
-
-        /**
-         * the excluding_pending balance plus any pending activity that has not been posted
-         * at the time of the query
-         */
-        including_pending: number;
-      }
+      including_pending: number;
     }
   }
 }
@@ -589,12 +583,7 @@ export interface CreditGrantEditParams {
   name?: string;
 }
 
-export interface CreditGrantListEntriesParams {
-  /**
-   * Query param: Cursor that indicates where the next page of results should start.
-   */
-  next_page?: string;
-
+export interface CreditGrantListEntriesParams extends CursorPageWithoutLimitParams {
   /**
    * Query param: Ledgers sort order by date, asc or desc. Defaults to asc.
    */
@@ -641,8 +630,6 @@ export interface CreditGrantVoidParams {
   void_credit_purchase_invoice?: boolean;
 }
 
-CreditGrants.CreditGrantListResponsesCursorPage = CreditGrantListResponsesCursorPage;
-
 export declare namespace CreditGrants {
   export {
     type CreditLedgerEntry as CreditLedgerEntry,
@@ -653,7 +640,8 @@ export declare namespace CreditGrants {
     type CreditGrantEditResponse as CreditGrantEditResponse,
     type CreditGrantListEntriesResponse as CreditGrantListEntriesResponse,
     type CreditGrantVoidResponse as CreditGrantVoidResponse,
-    CreditGrantListResponsesCursorPage as CreditGrantListResponsesCursorPage,
+    type CreditGrantListResponsesCursorPage as CreditGrantListResponsesCursorPage,
+    type CreditGrantListEntriesResponsesCursorPageWithoutLimit as CreditGrantListEntriesResponsesCursorPageWithoutLimit,
     type CreditGrantCreateParams as CreditGrantCreateParams,
     type CreditGrantListParams as CreditGrantListParams,
     type CreditGrantEditParams as CreditGrantEditParams,

package/src/resources/v1/custom-fields.ts

@@ -1,13 +1,46 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from "../../resource.js";
-import { isRequestOptions } from "../../core.js";
-import * as Core from "../../core.js";
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import {
+  CursorPageWithoutLimit,
+  type CursorPageWithoutLimitParams,
+  PagePromise,
+} from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
 
 export class CustomFields extends APIResource {
   /**
-   * Add a key to the allow list for a given entity. There is a 100 character limit
-   * on custom field keys.
+   * Creates a new custom field key for a given entity (e.g. billable metric,
+   * contract, alert).
+   *
+   * Custom fields are properties that you can add to Metronome objects to store
+   * metadata like foreign keys or other descriptors. This metadata can get
+   * transferred to or accessed by other systems to contextualize Metronome data and
+   * power business processes. For example, to service workflows like revenue
+   * recognition, reconciliation, and invoicing, custom fields help Metronome know
+   * the relationship between entities in the platform and third-party systems.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Create a new custom field key for Customer objects in Metronome. You can then
+   *   use the Set Custom Field Values endpoint to set the value of this key for a
+   *   specific customer.
+   * - Specify whether the key should enforce uniqueness. If the key is set to
+   *   enforce uniqueness and you attempt to set a custom field value for the key
+   *   that already exists, it will fail.
+   *
+   * ### Usage guidelines:
+   *
+   * - Custom fields set on commits, credits, and contracts can be used to scope
+   *   alert evaluation. For example, you can create a spend threshold alert that
+   *   only considers spend associated with contracts with custom field key
+   *   `contract_type` and value `paygo`
+   * - Custom fields set on products can be used in the Stripe integration to set
+   *   metadata on invoices.
+   * - Custom fields for customers, contracts, invoices, products, commits, scheduled
+   *   charges, and subscriptions are passed down to the invoice.
    *
    * @example
    * ```ts
@@ -18,16 +51,19 @@ export class CustomFields extends APIResource {
    * });
    * ```
    */
-  addKey(body: CustomFieldAddKeyParams, options?: Core.RequestOptions): Core.APIPromise<void> {
+  addKey(body: CustomFieldAddKeyParams, options?: RequestOptions): APIPromise<void> {
     return this._client.post('/v1/customFields/addKey', {
       body,
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 
   /**
-   * Deletes one or more custom fields on an instance of a Metronome entity.
+   * Remove specific custom field values from a Metronome entity instance by
+   * specifying the field keys to delete. Use this endpoint to clean up unwanted
+   * custom field data while preserving other fields on the same entity. Requires the
+   * entity type, entity ID, and array of keys to remove.
    *
    * @example
    * ```ts
@@ -38,42 +74,47 @@ export class CustomFields extends APIResource {
    * });
    * ```
    */
-  deleteValues(body: CustomFieldDeleteValuesParams, options?: Core.RequestOptions): Core.APIPromise<void> {
+  deleteValues(body: CustomFieldDeleteValuesParams, options?: RequestOptions): APIPromise<void> {
     return this._client.post('/v1/customFields/deleteValues', {
       body,
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 
   /**
-   * List all active custom field keys, optionally filtered by entity type.
+   * Retrieve all your active custom field keys, with optional filtering by entity
+   * type (customer, contract, product, etc.). Use this endpoint to discover what
+   * custom field keys are available before setting values on entities or to audit
+   * your custom field configuration across different entity types.
    *
    * @example
    * ```ts
-   * const response = await client.v1.customFields.listKeys({
-   *   entities: ['customer'],
-   * });
+   * // Automatically fetches more pages as needed.
+   * for await (const customFieldListKeysResponse of client.v1.customFields.listKeys(
+   *   { entities: ['customer'] },
+   * )) {
+   *   // ...
+   * }
    * ```
    */
   listKeys(
-    params?: CustomFieldListKeysParams,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<CustomFieldListKeysResponse>;
-  listKeys(options?: Core.RequestOptions): Core.APIPromise<CustomFieldListKeysResponse>;
-  listKeys(
-    params: CustomFieldListKeysParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<CustomFieldListKeysResponse> {
-    if (isRequestOptions(params)) {
-      return this.listKeys({}, params);
-    }
-    const { next_page, ...body } = params;
-    return this._client.post('/v1/customFields/listKeys', { query: { next_page }, body, ...options });
+    params: CustomFieldListKeysParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CustomFieldListKeysResponsesCursorPageWithoutLimit, CustomFieldListKeysResponse> {
+    const { next_page, ...body } = params ?? {};
+    return this._client.getAPIList(
+      '/v1/customFields/listKeys',
+      CursorPageWithoutLimit<CustomFieldListKeysResponse>,
+      { query: { next_page }, body, method: 'post', ...options },
+    );
   }
 
   /**
-   * Remove a key from the allow list for a given entity.
+   * Removes a custom field key from the allowlist for a specific entity type,
+   * preventing future use of that key across all instances of the entity. Existing
+   * values for this key on entity instances will no longer be accessible once the
+   * key is removed.
    *
    * @example
    * ```ts
@@ -83,22 +124,19 @@ export class CustomFields extends APIResource {
    * });
    * ```
    */
-  removeKey(body: CustomFieldRemoveKeyParams, options?: Core.RequestOptions): Core.APIPromise<void> {
+  removeKey(body: CustomFieldRemoveKeyParams, options?: RequestOptions): APIPromise<void> {
     return this._client.post('/v1/customFields/removeKey', {
       body,
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 
   /**
-   * Sets one or more custom fields on an instance of a Metronome entity. If a
-   * key/value pair passed in this request matches one already set on the entity, its
-   * value will be overwritten. Any key/value pairs that exist on the entity that do
-   * not match those passed in this request will remain untouched. This endpoint is
-   * transactional and will update all key/value pairs or no key/value pairs. Partial
-   * updates are not supported. There is a 200 character limit on custom field
-   * values.
+   * Sets custom field values on a specific Metronome entity instance. Overwrites
+   * existing values for matching keys while preserving other fields. All updates are
+   * transactional—either all values are set or none are. Custom field values are
+   * limited to 200 characters each.
    *
    * @example
    * ```ts
@@ -109,47 +147,42 @@ export class CustomFields extends APIResource {
    * });
    * ```
    */
-  setValues(body: CustomFieldSetValuesParams, options?: Core.RequestOptions): Core.APIPromise<void> {
+  setValues(body: CustomFieldSetValuesParams, options?: RequestOptions): APIPromise<void> {
     return this._client.post('/v1/customFields/setValues', {
       body,
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 }
 
-export interface CustomFieldListKeysResponse {
-  data: Array<CustomFieldListKeysResponse.Data>;
-
-  next_page: string | null;
-}
+export type CustomFieldListKeysResponsesCursorPageWithoutLimit =
+  CursorPageWithoutLimit<CustomFieldListKeysResponse>;
 
-export namespace CustomFieldListKeysResponse {
-  export interface Data {
-    enforce_uniqueness: boolean;
+export interface CustomFieldListKeysResponse {
+  enforce_uniqueness: boolean;
 
-    entity:
-      | 'alert'
-      | 'billable_metric'
-      | 'charge'
-      | 'commit'
-      | 'contract_credit'
-      | 'contract_product'
-      | 'contract'
-      | 'credit_grant'
-      | 'customer_plan'
-      | 'customer'
-      | 'discount'
-      | 'invoice'
-      | 'plan'
-      | 'professional_service'
-      | 'product'
-      | 'rate_card'
-      | 'scheduled_charge'
-      | 'subscription';
+  entity:
+    | 'alert'
+    | 'billable_metric'
+    | 'charge'
+    | 'commit'
+    | 'contract_credit'
+    | 'contract_product'
+    | 'contract'
+    | 'credit_grant'
+    | 'customer_plan'
+    | 'customer'
+    | 'discount'
+    | 'invoice'
+    | 'plan'
+    | 'professional_service'
+    | 'product'
+    | 'rate_card'
+    | 'scheduled_charge'
+    | 'subscription';
 
-    key: string;
-  }
+  key: string;
 }
 
 export interface CustomFieldAddKeyParams {
@@ -204,12 +237,7 @@ export interface CustomFieldDeleteValuesParams {
   keys: Array<string>;
 }
 
-export interface CustomFieldListKeysParams {
-  /**
-   * Query param: Cursor that indicates where the next page of results should start.
-   */
-  next_page?: string;
-
+export interface CustomFieldListKeysParams extends CursorPageWithoutLimitParams {
   /**
    * Body param: Optional list of entity types to return keys for
    */
@@ -260,6 +288,9 @@ export interface CustomFieldRemoveKeyParams {
 }
 
 export interface CustomFieldSetValuesParams {
+  /**
+   * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+   */
   custom_fields: { [key: string]: string };
 
   entity:
@@ -288,6 +319,7 @@ export interface CustomFieldSetValuesParams {
 export declare namespace CustomFields {
   export {
     type CustomFieldListKeysResponse as CustomFieldListKeysResponse,
+    type CustomFieldListKeysResponsesCursorPageWithoutLimit as CustomFieldListKeysResponsesCursorPageWithoutLimit,
     type CustomFieldAddKeyParams as CustomFieldAddKeyParams,
     type CustomFieldDeleteValuesParams as CustomFieldDeleteValuesParams,
     type CustomFieldListKeysParams as CustomFieldListKeysParams,