@metronome/sdk 0.3.0 → 2.0.0

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

@@ -1,9 +1,38 @@
-import { APIResource } from "../../resource.js";
-import * as Core from "../../core.js";
+import { APIResource } from "../../core/resource.js";
+import { APIPromise } from "../../core/api-promise.js";
+import { CursorPageWithoutLimit, type CursorPageWithoutLimitParams, PagePromise } from "../../core/pagination.js";
+import { RequestOptions } from "../../internal/request-options.js";
 export declare 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
@@ -14,9 +43,12 @@ export declare class CustomFields extends APIResource {
      * });
      * ```
      */
-    addKey(body: CustomFieldAddKeyParams, options?: Core.RequestOptions): Core.APIPromise<void>;
+    addKey(body: CustomFieldAddKeyParams, options?: RequestOptions): APIPromise<void>;
     /**
-     * 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
@@ -27,21 +59,29 @@ export declare class CustomFields extends APIResource {
      * });
      * ```
      */
-    deleteValues(body: CustomFieldDeleteValuesParams, options?: Core.RequestOptions): Core.APIPromise<void>;
+    deleteValues(body: CustomFieldDeleteValuesParams, options?: RequestOptions): APIPromise<void>;
     /**
-     * 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 | null | undefined, options?: RequestOptions): PagePromise<CustomFieldListKeysResponsesCursorPageWithoutLimit, CustomFieldListKeysResponse>;
     /**
-     * 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
@@ -51,15 +91,12 @@ export declare class CustomFields extends APIResource {
      * });
      * ```
      */
-    removeKey(body: CustomFieldRemoveKeyParams, options?: Core.RequestOptions): Core.APIPromise<void>;
+    removeKey(body: CustomFieldRemoveKeyParams, options?: RequestOptions): APIPromise<void>;
     /**
-     * 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
@@ -70,18 +107,13 @@ export declare class CustomFields extends APIResource {
      * });
      * ```
      */
-    setValues(body: CustomFieldSetValuesParams, options?: Core.RequestOptions): Core.APIPromise<void>;
+    setValues(body: CustomFieldSetValuesParams, options?: RequestOptions): APIPromise<void>;
 }
+export type CustomFieldListKeysResponsesCursorPageWithoutLimit = CursorPageWithoutLimit<CustomFieldListKeysResponse>;
 export interface CustomFieldListKeysResponse {
-    data: Array<CustomFieldListKeysResponse.Data>;
-    next_page: string | null;
-}
-export declare namespace CustomFieldListKeysResponse {
-    interface Data {
-        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';
-        key: string;
-    }
+    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';
+    key: string;
 }
 export interface CustomFieldAddKeyParams {
     enforce_uniqueness: boolean;
@@ -93,11 +125,7 @@ export interface CustomFieldDeleteValuesParams {
     entity_id: string;
     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
      */
@@ -108,6 +136,9 @@ export interface CustomFieldRemoveKeyParams {
     key: string;
 }
 export interface CustomFieldSetValuesParams {
+    /**
+     * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+     */
     custom_fields: {
         [key: string]: string;
     };
@@ -115,6 +146,6 @@ export interface CustomFieldSetValuesParams {
     entity_id: string;
 }
 export declare namespace CustomFields {
-    export { type CustomFieldListKeysResponse as CustomFieldListKeysResponse, type CustomFieldAddKeyParams as CustomFieldAddKeyParams, type CustomFieldDeleteValuesParams as CustomFieldDeleteValuesParams, type CustomFieldListKeysParams as CustomFieldListKeysParams, type CustomFieldRemoveKeyParams as CustomFieldRemoveKeyParams, type CustomFieldSetValuesParams as CustomFieldSetValuesParams, };
+    export { type CustomFieldListKeysResponse as CustomFieldListKeysResponse, type CustomFieldListKeysResponsesCursorPageWithoutLimit as CustomFieldListKeysResponsesCursorPageWithoutLimit, type CustomFieldAddKeyParams as CustomFieldAddKeyParams, type CustomFieldDeleteValuesParams as CustomFieldDeleteValuesParams, type CustomFieldListKeysParams as CustomFieldListKeysParams, type CustomFieldRemoveKeyParams as CustomFieldRemoveKeyParams, type CustomFieldSetValuesParams as CustomFieldSetValuesParams, };
 }
 //# sourceMappingURL=custom-fields.d.ts.map

package/resources/v1/custom-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"custom-fields.d.ts","sourceRoot":"","sources":["../../src/resources/v1/custom-fields.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"custom-fields.d.ts","sourceRoot":"","sources":["../../src/resources/v1/custom-fields.ts"],"names":[],"mappings":"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"}

package/resources/v1/custom-fields.js

@@ -2,12 +2,40 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CustomFields = void 0;
-const resource_1 = require("../../resource.js");
-const core_1 = require("../../core.js");
+const resource_1 = require("../../core/resource.js");
+const pagination_1 = require("../../core/pagination.js");
+const headers_1 = require("../../internal/headers.js");
 class CustomFields extends resource_1.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
@@ -22,11 +50,14 @@ class CustomFields extends resource_1.APIResource {
         return this._client.post('/v1/customFields/addKey', {
             body,
             ...options,
-            headers: { Accept: '*/*', ...options?.headers },
+            headers: (0, headers_1.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
@@ -41,18 +72,34 @@ class CustomFields extends resource_1.APIResource {
         return this._client.post('/v1/customFields/deleteValues', {
             body,
             ...options,
-            headers: { Accept: '*/*', ...options?.headers },
+            headers: (0, headers_1.buildHeaders)([{ Accept: '*/*' }, options?.headers]),
         });
     }
+    /**
+     * 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
+     * // Automatically fetches more pages as needed.
+     * for await (const customFieldListKeysResponse of client.v1.customFields.listKeys(
+     *   { entities: ['customer'] },
+     * )) {
+     *   // ...
+     * }
+     * ```
+     */
     listKeys(params = {}, options) {
-        if ((0, core_1.isRequestOptions)(params)) {
-            return this.listKeys({}, params);
-        }
-        const { next_page, ...body } = params;
-        return this._client.post('/v1/customFields/listKeys', { query: { next_page }, body, ...options });
+        const { next_page, ...body } = params ?? {};
+        return this._client.getAPIList('/v1/customFields/listKeys', (pagination_1.CursorPageWithoutLimit), { 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
@@ -66,17 +113,14 @@ class CustomFields extends resource_1.APIResource {
         return this._client.post('/v1/customFields/removeKey', {
             body,
             ...options,
-            headers: { Accept: '*/*', ...options?.headers },
+            headers: (0, headers_1.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
@@ -91,7 +135,7 @@ class CustomFields extends resource_1.APIResource {
         return this._client.post('/v1/customFields/setValues', {
             body,
             ...options,
-            headers: { Accept: '*/*', ...options?.headers },
+            headers: (0, headers_1.buildHeaders)([{ Accept: '*/*' }, options?.headers]),
         });
     }
 }

package/resources/v1/custom-fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"custom-fields.js","sourceRoot":"","sources":["../../src/resources/v1/custom-fields.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,gDAA6C;AAC7C,wCAA8C;AAG9C,MAAa,YAAa,SAAQ,sBAAW;IAC3C;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,IAA6B,EAAE,OAA6B;QACjE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE;YAClD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,IAAmC,EAAE,OAA6B;QAC7E,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE;YACxD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;IAiBD,QAAQ,CACN,SAA0D,EAAE,EAC5D,OAA6B;QAE7B,IAAI,IAAA,uBAAgB,EAAC,MAAM,CAAC,EAAE;YAC5B,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;SAClC;QACD,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACtC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACpG,CAAC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAgC,EAAE,OAA6B;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE;YACrD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,IAAgC,EAAE,OAA6B;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE;YACrD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;CACF;AAhHD,oCAgHC"}
+{"version":3,"file":"custom-fields.js","sourceRoot":"","sources":["../../src/resources/v1/custom-fields.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAElD,yDAI+B;AAC/B,uDAAsD;AAGtD,MAAa,YAAa,SAAQ,sBAAW;IAC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,MAAM,CAAC,IAA6B,EAAE,OAAwB;QAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE;YAClD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,IAAmC,EAAE,OAAwB;QACxE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE;YACxD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CACN,SAAuD,EAAE,EACzD,OAAwB;QAExB,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,IAAI,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAC5B,2BAA2B,EAC3B,CAAA,mCAAmD,CAAA,EACnD,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAC3D,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,IAAgC,EAAE,OAAwB;QAClE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE;YACrD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,IAAgC,EAAE,OAAwB;QAClE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE;YACrD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AAhJD,oCAgJC"}

package/resources/v1/custom-fields.mjs

@@ -1,10 +1,38 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-import { APIResource } from "../../resource.mjs";
-import { isRequestOptions } from "../../core.mjs";
+import { APIResource } from "../../core/resource.mjs";
+import { CursorPageWithoutLimit, } from "../../core/pagination.mjs";
+import { buildHeaders } from "../../internal/headers.mjs";
 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
@@ -19,11 +47,14 @@ export class CustomFields extends APIResource {
         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,18 +69,34 @@ export class CustomFields extends APIResource {
         return this._client.post('/v1/customFields/deleteValues', {
             body,
             ...options,
-            headers: { Accept: '*/*', ...options?.headers },
+            headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
         });
     }
+    /**
+     * 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
+     * // Automatically fetches more pages as needed.
+     * for await (const customFieldListKeysResponse of client.v1.customFields.listKeys(
+     *   { entities: ['customer'] },
+     * )) {
+     *   // ...
+     * }
+     * ```
+     */
     listKeys(params = {}, options) {
-        if (isRequestOptions(params)) {
-            return this.listKeys({}, params);
-        }
-        const { next_page, ...body } = params;
-        return this._client.post('/v1/customFields/listKeys', { query: { next_page }, body, ...options });
+        const { next_page, ...body } = params ?? {};
+        return this._client.getAPIList('/v1/customFields/listKeys', (CursorPageWithoutLimit), { 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
@@ -63,17 +110,14 @@ export class CustomFields extends APIResource {
         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
@@ -88,7 +132,7 @@ export class CustomFields extends APIResource {
         return this._client.post('/v1/customFields/setValues', {
             body,
             ...options,
-            headers: { Accept: '*/*', ...options?.headers },
+            headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
         });
     }
 }

package/resources/v1/custom-fields.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"custom-fields.mjs","sourceRoot":"","sources":["../../src/resources/v1/custom-fields.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OACf,EAAE,gBAAgB,EAAE;AAG3B,MAAM,OAAO,YAAa,SAAQ,WAAW;IAC3C;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,IAA6B,EAAE,OAA6B;QACjE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE;YAClD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,IAAmC,EAAE,OAA6B;QAC7E,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE;YACxD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;IAiBD,QAAQ,CACN,SAA0D,EAAE,EAC5D,OAA6B;QAE7B,IAAI,gBAAgB,CAAC,MAAM,CAAC,EAAE;YAC5B,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;SAClC;QACD,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACtC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACpG,CAAC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAgC,EAAE,OAA6B;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE;YACrD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,IAAgC,EAAE,OAA6B;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE;YACrD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"custom-fields.mjs","sourceRoot":"","sources":["../../src/resources/v1/custom-fields.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAEf,EACL,sBAAsB,GAGvB;OACM,EAAE,YAAY,EAAE;AAGvB,MAAM,OAAO,YAAa,SAAQ,WAAW;IAC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,MAAM,CAAC,IAA6B,EAAE,OAAwB;QAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE;YAClD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,IAAmC,EAAE,OAAwB;QACxE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE;YACxD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CACN,SAAuD,EAAE,EACzD,OAAwB;QAExB,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,IAAI,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAC5B,2BAA2B,EAC3B,CAAA,sBAAmD,CAAA,EACnD,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAC3D,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,IAAgC,EAAE,OAAwB;QAClE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE;YACrD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,IAAgC,EAAE,OAAwB;QAClE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE;YACrD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF"}