polarity-integration-utils 4.1.1 → 4.2.0

package/dist/polarity-integration-utils.d.ts

@@ -58,872 +58,910 @@ export declare type ConfigRequestProxyOptions = {
 };
 
 /**
- * Creates a mock `Entity` for use in tests.
+ * Creates a cache-safe key by hashing the input values with SHA-256 and
+ * prepending a descriptive prefix.
  *
- * Automatically detects whether the value is a domain or IPv4 address and sets
- * the corresponding boolean flags. All other flags default to `false`.
+ * Use this to derive cache keys from dynamic or sensitive data (entity values,
+ * credentials, etc.) that may contain characters outside the allowed set.
  *
- * @param type - An `EntityType` string (e.g., `'IPv4'`, `'domain'`, `'MD5'`)
- * @param value - The entity value string
- * @returns A fully populated `Entity` object
+ * @param prefix - A short descriptive label using only letters, digits, dots,
+ *   underscores, and hyphens (must match `/^[a-zA-Z0-9._-]+$/`).
+ * @param value - First value to hash (required).
+ * @param values - Additional values to hash (e.g., further credentials or identifiers).
+ * @returns A key in the form `prefix_<64-char hex hash>`.
  *
- * @example
- * ```typescript
- * const ip = createEntity('IPv4', '8.8.8.8');
- * const domain = createEntity('domain', 'example.com');
- * ```
- */
-export declare const createEntity: (type: EntityType, value: string) => Entity;
-
-/**
- * Creates a mock `IntegrationContext`
- * with stubbed logger, cache, and polling methods.
- *
- * Pass your testing framework's mock function factory to enable spy capabilities
- * (e.g., `toHaveBeenCalledWith()`). When omitted, plain no-op stubs are used.
- *
- * @param createMockFn - A factory that creates mock functions (e.g., `vi.fn` or `jest.fn`)
- * @returns A fully populated `IntegrationContext` with stubbed methods
- *
- * @example
- * ```typescript
- * // Vitest
- * const ctx = createMockIntegrationContext(vi.fn);
- *
- * // Jest
- * const ctx = createMockIntegrationContext(jest.fn);
- *
- * // No framework — plain no-ops
- * const ctx = createMockIntegrationContext();
- * ```
- */
-export declare const createMockIntegrationContext: (createMockFn?: MockFnFactory) => IntegrationContext;
-
-/**
- * Custom entity type definition for config.json
- * @public
- */
-export declare interface CustomType {
-    type?: 'custom';
-    name?: string;
-    description?: string;
-    key: string;
-    regex: string;
-    editable?: boolean;
-    enabled?: boolean;
-}
-
-/**
- * @public
- */
-export declare type ErrorMeta = {
-    [otherMetadata: string]: unknown;
-};
-
-/**
- * return the logger object set via the {@link setLogger} method.
- *
- * @example
- * Example of using the integration's logging object:
- * ```js
- * const { getLogger } = require('polarity-integration-utils');
- *
- * const logger = getLogger();
- * logger.trace('this is a trace message');
- * ```
- *
- * @public
- * @returns the integration's logger object
- */
-export declare const getLogger: () => Logger;
-
-export declare type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
-
-/**
- * @public
- */
-export declare type HttpRequestOptions = {
-    /**
-     * The URL to make the request to.
-     */
-    url?: string;
-    /**
-     * The HTTP method to use for the request.
-     *
-     * @defaultValue 'GET'
-     */
-    method?: HttpMethod;
-    /**
-     *  If true, sets body to JSON representation of value and adds Content-type: application/json header.
-     *  Additionally, parses the response body as JSON.
+ * @throws {@link LibraryUsageError}
+     * If `prefix` or `value` is not a string, if `prefix` is empty or contains
+     * invalid characters, if any additional value is not a string, or if the
+     * resulting key would exceed 250 characters.
      *
-     *  @defaultValue true
-     */
-    json?: boolean;
-    /**
-     * An object containing the headers to include in the request.
-     * @example
-     * Here is an example of setting the "X-Api-Key" `headers` property:
-     * ```
-     * {
-     *   headers: {
-     *     'X-Api-Key': '1234567890'
-     *   }
-     * }
-     * ```
-     */
-    headers?: object;
-    /**
-     * An object containing querystring parameters to include in the request.
-     * @example
-     * Here is an example of setting the `qs` property:
-     * ```
-     * {
-     *   qs: {
-     *     search: 'foo'
-     *   }
-     * }
-     * ```
-     */
-    qs?: object;
-    /**
-     * When passed an object or a querystring, this sets body to a querystring representation of value,
-     * and adds Content-type: application/x-www-form-urlencoded header.
-     */
-    form?: object;
-    /**
-     * The body of the request.
-     */
-    body?: object;
-    /**
-     * The authentication options to use for the request
-     */
-    auth?: {
-        username: string;
-        password: string;
-        sendImmediately?: boolean;
-    } | {
-        bearer: string;
-        sendImmediately?: boolean;
-    };
-    [key: string]: unknown;
-} & ({
-    entity: Entity;
-    entities?: never;
-    requestId?: never;
-} | {
-    entities: Entity[];
-    entity?: never;
-    requestId?: never;
-} | {
-    requestId: string | unknown;
-    entity?: never;
-    entities?: never;
-} | {
-    entity?: never;
-    entities?: never;
-    requestId?: never;
-});
-
-/**
- * @public
- */
-export declare type HttpRequestResponse = {
-    /**
-     * The HTTP status code of the response.
-     */
-    statusCode: number;
-    request: {
-        uri: unknown;
-        method: string;
-        headers: unknown;
-        [key: string]: unknown;
-    };
-    /**
-     * The body of the response.
-     */
-    body: unknown;
-    /**
-     * The response headers
-     */
-    headers: unknown;
-    /**
-     * The error object if an error occurred during the request.
-     */
-    error?: ApiRequestError | NetworkError | RetryRequestError;
-    /**
-     * The entity that the request was made for. The `entity` property matches the
-     * `entity` property set on the {@link HttpRequestOptions} object associated with this HttpRequestResponse.
-     */
-    entity?: Entity;
-    /**
-     * An array of entities that the request was made for.  The `entities` property
-     * matches the `entities` property set on the {@link HttpRequestOptions} object associated
-     * with this HttpRequestResponse.
-     */
-    entities?: Entity[];
-    /**
-     * A custom request id that can be used to identify the request.  The `requestId` matches
-     * the `requestId` property set on the {@link HttpRequestOptions} object.
-     */
-    requestId?: string | unknown;
-    [key: string]: unknown;
-};
-
-/**
- * Integration config.json type
- * @public
- */
-export declare interface IntegrationConfig {
-    polarityIntegrationUuid: string;
-    name: string;
-    acronym: string;
-    description?: string;
-    defaultColor?: string;
-    entityTypes?: string[];
-    dataTypes?: (string | CustomType)[];
-    customTypes?: CustomType[];
-    supportsAdditionalCustomTypes?: boolean;
-    styles?: string[];
-    block: ViewComponent;
-    summary?: ViewComponent;
-    onDemandOnly?: boolean;
-    copyOnDemand?: boolean;
-    logging?: {
-        level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-    };
-    request?: {
-        cert?: string;
-        key?: string;
-        passphrase?: string;
-        ca?: string;
-        proxy?: string;
-        rejectUnauthorized?: boolean;
-    };
-    options?: IntegrationOption[];
-}
-
-/**
- * @public
- */
-export declare class IntegrationError extends Error {
-    /**
-     *  a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of
-     *  the problem except for purposes of localization.
-     */
-    readonly title: string;
-    /**
-     * a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be
-     * localized
-     */
-    readonly detail: string;
-    /**
-     * a meta object containing non-standard meta-information about the error.
-     */
-    readonly meta?: ErrorMeta;
-    /**
-     * The HTTP status code applicable to this error, expressed as a string value.
-     */
-    readonly status?: string;
-    /**
-     *  an application-specific error code, expressed as a string value.
-     */
-    readonly code?: string;
-    /**
-     * The `cause` property is used to specify the `cause` of the error.  Typically,
-     * this property is used to pass through a related Error instance but can be any value.
-     */
-    readonly cause?: unknown;
-    /**
-     * Additional details related to the error that may help the user troubleshoot the issue.  If set by the user
-     * via the Error constructor, the user provided value will override any automated help message set by the
-     * Error class.
-     */
-    readonly help?: string;
-    /**
-     * Relevant for integration errors involving a network call, the `requestOptions` property
-     * details the request options that resulted in the specified error.  The `requestOptions` property will automatically
-     * have sensitive authentication headers stripped.
-     */
-    readonly requestOptions?: HttpRequestOptions;
-    /**
-     * Construct a new IntegrationError object.
-     * @param message - A string description of the error which is used as the `detail` property on the
-     * serialized error.
-     * @param properties - Optional properties for the error.
-     */
-    constructor(message: string, properties?: IntegrationErrorProperties);
-    /**
-     * Serializes the error's properties into a POJO.  The order of the
-     * properties is preserved when serialized.
-     * @returns JSON representation of the error
-     */
-    toJSON(): SerializedIntegrationError;
-}
-
-/**
- * @public
- */
-export declare interface IntegrationErrorProperties {
-    /**
-     *  a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of
-     *  the problem except for purposes of localization.  If omitted, the title will default to the type
-     *  of error (e.g., IntegrationError, or ApiRequestError)
-     */
-    title?: string;
-    /**
-     * Additional details related to the error that may help the user troubleshoot the issue.  If set by the user
-     * via the Error constructor, the user provided value will override any automated help message set by the
-     * Error class.
-     */
-    help?: string;
-    /**
-     * The `cause` property is used to specify the `cause` of the error.  Typically,
-     * this property is used to pass through a related Error instance but can be any value.
-     */
-    cause?: unknown;
-    /**
-     * The HTTP status code applicable to this error, expressed as a string value.
-     */
-    status?: string;
-    /**
-     *  an application-specific error code, expressed as a string value.
-     */
-    code?: string;
-    /**
-     * Relevant for integration errors involving a network call, the `requestOptions` property
-     * details the request options that resulted in the specified error.  The `requestOptions` property will automatically
-     * have sensitive authentication headers stripped.
-     * By default, the following paths are sanitized:
-     *
-     * - auth.password
-     * - auth.bearer
-     * - body.password
-     * - form.client_secret
-     * - headers.authorization
-     * - headers.x-api-key
-     *
-     * Additional paths can be sanitized by using the `requestOptionsToSanitize` property.
-     */
-    requestOptions?: HttpRequestOptions;
-    /**
-     * List of paths in JSON dot notation to sanitize in the requestOptions object
-     */
-    requestOptionsToSanitize?: string[];
-    /**
-     * Any additional properties which will be appended to the Error's meta property
-     */
-    meta?: MetaObject;
-}
-
-/**
- * Integration option definition for config.json
- * @public
- */
-export declare type IntegrationOption = {
-    type: 'text' | 'password';
-    key: string;
-    name: string;
-    description?: string;
-    default: string | null;
-    userCanEdit?: boolean;
-    adminOnly?: boolean;
-} | {
-    type: 'boolean';
-    key: string;
-    name: string;
-    description?: string;
-    default: boolean | null;
-    userCanEdit?: boolean;
-    adminOnly?: boolean;
-} | {
-    type: 'number';
-    key: string;
-    name: string;
-    description?: string;
-    default: number | null;
-    userCanEdit?: boolean;
-    adminOnly?: boolean;
-} | {
-    type: 'select';
-    key: string;
-    name: string;
-    description?: string;
-    default: SelectOptionItem | SelectOptionItem[] | string | null;
-    options: SelectOptionItem[];
-    multiple?: boolean;
-    userCanEdit: boolean;
-    adminOnly: boolean;
-};
-
-/**
- * @public
- */
-export declare type IsApiErrorFunction = (response: HttpRequestResponse, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => IsApiErrorResult;
-
-/**
- * @public
- */
-export declare type IsApiErrorResult = {
-    /**
-     * Indicates whether the response is an API error.
-     */
-    isApiError: boolean;
-    /**
-     * Optional message providing additional information about the API error.  The
-     * returned `message` will be used as the `message` property on the {@link ApiRequestError} object
-     * thrown by the request.
+     * @group Utilities
+     * @public
      */
-    message?: string;
-};
-
-/**
- * Thrown when the polarity-integration-utils library is used incorrectly.  For example,
- * if a method is called with incorrect or missing parameters, or a required initialization
- * method is not called.  This Error class should not be used directly by integrations.
- *
- * @public
- */
-export declare class LibraryUsageError extends IntegrationError {
-    constructor(message: string, properties?: IntegrationErrorProperties);
-}
-
-/**
- * Minimal interface for a rate limiter compatible with PolarityRequest.
- * The Polarity server provides a Bottleneck instance that satisfies this interface.
- *
- * @public
- */
-export declare interface Limiter {
-    schedule<T>(fn: (...args: unknown[]) => PromiseLike<T>, ...args: unknown[]): Promise<T>;
-}
-
-/**
- * @public
- */
-export declare type MetaObject = {
-    [key: string]: unknown;
-};
-
-/**
- * Factory function that creates mock functions. Pass `vi.fn` (Vitest)
- * or `jest.fn` (Jest) to get spy capabilities. When omitted, plain
- * no-op functions are used.
- *
- * @example
- * ```typescript
- * // Vitest — enables toHaveBeenCalledWith() assertions
- * const ctx = createMockIntegrationContext(vi.fn);
- *
- * // Jest
- * const ctx = createMockIntegrationContext(jest.fn);
- *
- * // No framework — plain no-ops
- * const ctx = createMockIntegrationContext();
- * ```
- */
-export declare type MockFnFactory = () => (...args: any[]) => any;
-
-/**
- * Generic network error for REST requests.
- * https://betterstack.com/community/guides/scaling-nodejs/nodejs-errors/#4-econnrefused
- *
- * @public
- */
-export declare class NetworkError extends IntegrationError {
-    constructor(message: string, properties?: IntegrationErrorProperties);
-}
-
-/**
- * Hook that runs when an API error is detected (non-success status code or error
- * properties found in the response body). Receives the full HTTP response so the
- * hook can inspect status codes, headers, and body.
- *
- * If all registered hooks return without throwing, the error is suppressed and
- * the HTTP response is returned to the caller. To propagate or replace the error,
- * throw from within the hook.
- *
- * @public
- */
-export declare type OnApiErrorHook = (error: ApiRequestError, response: HttpRequestResponse, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<void>;
-
-/**
- * Hook that runs when a network error or rate-limiting error occurs during a request.
- *
- * If all registered hooks return without throwing, the error is suppressed.
- * To propagate or replace the error, throw from within the hook.
- *
- * @public
- */
-export declare type OnNetworkErrorHook = (error: NetworkError | RetryRequestError, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<void>;
-
-/**
- * @public
- * @param error - Error instance to parse into a plain old javascript object
- */
-export declare const parseErrorToReadableJson: (error: ResponseError) => any;
+ export declare function createCacheKey(prefix: string, value: string, ...values: string[]): string;
+
+ /**
+  * Creates a mock `Entity` for use in tests.
+  *
+  * Automatically detects whether the value is a domain or IPv4 address and sets
+  * the corresponding boolean flags. All other flags default to `false`.
+  *
+  * @param type - An `EntityType` string (e.g., `'IPv4'`, `'domain'`, `'MD5'`)
+  * @param value - The entity value string
+  * @returns A fully populated `Entity` object
+  *
+  * @example
+  * ```typescript
+  * const ip = createEntity('IPv4', '8.8.8.8');
+  * const domain = createEntity('domain', 'example.com');
+  * ```
+  *
+  * @group Testing
+  * @public
+  */
+ export declare const createEntity: (type: EntityType, value: string) => Entity;
+
+ /**
+  * Creates a mock `IntegrationContext`
+  * with stubbed logger, cache, and polling methods.
+  *
+  * Pass your testing framework's mock function factory to enable spy capabilities
+  * (e.g., `toHaveBeenCalledWith()`). When omitted, plain no-op stubs are used.
+  *
+  * @param createMockFn - A factory that creates mock functions (e.g., `vi.fn` or `jest.fn`)
+  * @returns A fully populated `IntegrationContext` with stubbed methods
+  *
+  * @group Testing
+  * @public
+  *
+  * @example
+  * ```typescript
+  * // Vitest
+  * const ctx = createMockIntegrationContext(vi.fn);
+  *
+  * // Jest
+  * const ctx = createMockIntegrationContext(jest.fn);
+  *
+  * // No framework — plain no-ops
+  * const ctx = createMockIntegrationContext();
+  * ```
+  */
+ export declare const createMockIntegrationContext: (createMockFn?: MockFnFactory) => IntegrationContext;
+
+ /**
+  * Custom entity type definition for config.json
+  * @public
+  */
+ export declare interface CustomType {
+     type?: 'custom';
+     name?: string;
+     description?: string;
+     key: string;
+     regex: string;
+     editable?: boolean;
+     enabled?: boolean;
+ }
+
+ /**
+  * @public
+  */
+ export declare type ErrorMeta = {
+     [otherMetadata: string]: unknown;
+ };
+
+ /**
+  * return the logger object set via the {@link setLogger} method.
+  *
+  * @example
+  * Example of using the integration's logging object:
+  * ```js
+  * const { getLogger } = require('polarity-integration-utils');
+  *
+  * const logger = getLogger();
+  * logger.trace('this is a trace message');
+  * ```
+  *
+  * @group Logging
+  * @public
+  * @returns the integration's logger object
+  */
+ export declare const getLogger: () => Logger;
+
+ export declare type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+
+ /**
+  * @public
+  */
+ export declare type HttpRequestOptions = {
+     /**
+      * The URL to make the request to.
+      */
+     url?: string;
+     /**
+      * The HTTP method to use for the request.
+      *
+      * @defaultValue 'GET'
+      */
+     method?: HttpMethod;
+     /**
+      *  If true, sets body to JSON representation of value and adds Content-type: application/json header.
+      *  Additionally, parses the response body as JSON.
+      *
+      *  @defaultValue true
+      */
+     json?: boolean;
+     /**
+      * An object containing the headers to include in the request.
+      * @example
+      * Here is an example of setting the "X-Api-Key" `headers` property:
+      * ```
+      * {
+      *   headers: {
+      *     'X-Api-Key': '1234567890'
+      *   }
+      * }
+      * ```
+      */
+     headers?: object;
+     /**
+      * An object containing querystring parameters to include in the request.
+      * @example
+      * Here is an example of setting the `qs` property:
+      * ```
+      * {
+      *   qs: {
+      *     search: 'foo'
+      *   }
+      * }
+      * ```
+      */
+     qs?: object;
+     /**
+      * When passed an object or a querystring, this sets body to a querystring representation of value,
+      * and adds Content-type: application/x-www-form-urlencoded header.
+      */
+     form?: object;
+     /**
+      * The body of the request.
+      */
+     body?: object;
+     /**
+      * The authentication options to use for the request
+      */
+     auth?: {
+         username: string;
+         password: string;
+         sendImmediately?: boolean;
+     } | {
+         bearer: string;
+         sendImmediately?: boolean;
+     };
+     [key: string]: unknown;
+ } & ({
+     entity: Entity;
+     entities?: never;
+     requestId?: never;
+ } | {
+     entities: Entity[];
+     entity?: never;
+     requestId?: never;
+ } | {
+     requestId: string | unknown;
+     entity?: never;
+     entities?: never;
+ } | {
+     entity?: never;
+     entities?: never;
+     requestId?: never;
+ });
+
+ /**
+  * @public
+  */
+ export declare type HttpRequestResponse = {
+     /**
+      * The HTTP status code of the response.
+      */
+     statusCode: number;
+     request: {
+         uri: unknown;
+         method: string;
+         headers: unknown;
+         [key: string]: unknown;
+     };
+     /**
+      * The body of the response.
+      */
+     body: unknown;
+     /**
+      * The response headers
+      */
+     headers: unknown;
+     /**
+      * The error object if an error occurred during the request.
+      */
+     error?: ApiRequestError | NetworkError | RetryRequestError;
+     /**
+      * The entity that the request was made for. The `entity` property matches the
+      * `entity` property set on the {@link HttpRequestOptions} object associated with this HttpRequestResponse.
+      */
+     entity?: Entity;
+     /**
+      * An array of entities that the request was made for.  The `entities` property
+      * matches the `entities` property set on the {@link HttpRequestOptions} object associated
+      * with this HttpRequestResponse.
+      */
+     entities?: Entity[];
+     /**
+      * A custom request id that can be used to identify the request.  The `requestId` matches
+      * the `requestId` property set on the {@link HttpRequestOptions} object.
+      */
+     requestId?: string | unknown;
+     [key: string]: unknown;
+ };
+
+ /**
+  * Integration config.json type
+  * @public
+  */
+ export declare interface IntegrationConfig {
+     polarityIntegrationUuid: string;
+     name: string;
+     acronym: string;
+     description?: string;
+     defaultColor?: string;
+     entityTypes?: string[];
+     dataTypes?: (string | CustomType)[];
+     customTypes?: CustomType[];
+     supportsAdditionalCustomTypes?: boolean;
+     styles?: string[];
+     block: ViewComponent;
+     summary?: ViewComponent;
+     onDemandOnly?: boolean;
+     copyOnDemand?: boolean;
+     logging?: {
+         level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+     };
+     request?: {
+         cert?: string;
+         key?: string;
+         passphrase?: string;
+         ca?: string;
+         proxy?: string;
+         rejectUnauthorized?: boolean;
+     };
+     options?: IntegrationOption[];
+ }
+
+ /**
+  * @public
+  */
+ export declare class IntegrationError extends Error {
+     /**
+      *  a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of
+      *  the problem except for purposes of localization.
+      */
+     readonly title: string;
+     /**
+      * a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be
+      * localized
+      */
+     readonly detail: string;
+     /**
+      * a meta object containing non-standard meta-information about the error.
+      */
+     readonly meta?: ErrorMeta;
+     /**
+      * The HTTP status code applicable to this error, expressed as a string value.
+      */
+     readonly status?: string;
+     /**
+      *  an application-specific error code, expressed as a string value.
+      */
+     readonly code?: string;
+     /**
+      * The `cause` property is used to specify the `cause` of the error.  Typically,
+      * this property is used to pass through a related Error instance but can be any value.
+      */
+     readonly cause?: unknown;
+     /**
+      * Additional details related to the error that may help the user troubleshoot the issue.  If set by the user
+      * via the Error constructor, the user provided value will override any automated help message set by the
+      * Error class.
+      */
+     readonly help?: string;
+     /**
+      * Relevant for integration errors involving a network call, the `requestOptions` property
+      * details the request options that resulted in the specified error.  The `requestOptions` property will automatically
+      * have sensitive authentication headers stripped.
+      */
+     readonly requestOptions?: HttpRequestOptions;
+     /**
+      * Construct a new IntegrationError object.
+      * @param message - A string description of the error which is used as the `detail` property on the
+      * serialized error.
+      * @param properties - Optional properties for the error.
+      */
+     constructor(message: string, properties?: IntegrationErrorProperties);
+     /**
+      * Serializes the error's properties into a POJO.  The order of the
+      * properties is preserved when serialized.
+      * @returns JSON representation of the error
+      */
+     toJSON(): SerializedIntegrationError;
+ }
 
-/**
- * A utility class for making HTTP requests
- * @public
- */
-export declare class PolarityRequest {
-    /**
-     * Instance of a Bunyan logger
-     */
-    private logger;
-    /**
-     * postman-request library request object with default values set.  Used internally for
-     * making HTTP requests directly via the postman-request library
-     */
-    private readonly requestWithDefaults;
-    readonly roundedSuccessStatusCodes: number[];
-    /**
-     * One or more HTTP response properties specified using JSON dot notation.  If the
-     * specified path exists within the `body` property of the HTTP Response, an
-     * ApiRequestError will be thrown.
-     *
-     * By default, this value is an empty array and response properties are not used to
-     * detect errors.
-     * @defaultValue []
-     */
-    readonly httpResponseErrorProperties: string[];
-    /**
-     * One or more HTTP response properties specified using JSON dot notation that
-     * point to an error message that should be displayed to the user in the event
-     * of an API error.
-     *
-     * The property should be a string value.  If the property does not exist or is not
-     * a string value, a default error message will be used instead.
-     */
-    readonly httpResponseErrorMessageProperties: string[];
-    /**
-     * Optional method that can be implemented to determine if an API error
-     * was encountered after an HTTP request is made.
-     *
-     * If the `isApiError` method is implemented
-     * the property `roundedSuccessStatusCodes` and `httpResponseErrorProperties` are not
-     * used to determine API errors.
-     *
-     * @returns An object indicating whether an API error was encountered and an optional message.
-     */
-    readonly isApiError: IsApiErrorFunction;
-    /**
-     * An array of JSON dot notation paths to omit from the request options when logging.
-     *
-     * This property can be used to sanitize sensitive request properties that should not
-     * appear in logging.
-     *
-     * Note that the `requestOptions` object is automatically sanitized to remove properties that
-     * typically contain sensitive API key and passwords.  For a list of properties that are
-     * automatically sanitized, see the {@link sanitizeRequestOptions} method.
-     */
-    readonly requestOptionsToSanitize: string[];
-    userOptions: DoLookupUserOptions;
-    /**
-     * An optional rate limiter instance used to throttle HTTP requests.
-     * When set, all requests made via {@link PolarityRequest.run} are scheduled
-     * through this limiter. Typically provided by the Polarity server via the
-     * integration context.
-     */
-    limiter: Limiter | null;
-    /**
-     * Lifecycle hooks for customizing request behavior. Hooks are configured via the
-     * {@link PolarityRequestOptions.hooks} property when creating a new instance of the
-     * {@link PolarityRequest} class.
-     *
-     * @see {@link PolarityRequestHooks} for hook type details.
-     */
-    readonly hooks: Required<PolarityRequestHooks>;
-    constructor(options?: PolarityRequestOptions);
-    private configFieldIsValid;
-    /**
-     * Makes a single HTTP request and returns the response or throws an error
-     *
-     * @param requestOptions - request options used to make the HTTP request
-     * @returns The HTTP response
-     */
-    run(requestOptions: HttpRequestOptions): Promise<HttpRequestResponse | undefined> | never;
-    /**
-     * Checks whether the HTTP response is an API error and returns an ApiRequestError if it is.
-     *
-     * @param httpResponse - The HTTP response from the Postman request.
-     * @param requestOptions - The options used for the request.
-     * @returns An ApiRequestError if the response indicates an API error, undefined otherwise.
-     *
-     * @throws {@link LibraryUsageError}
-         * Throws if the `isApiError` function returns an invalid result.
-         */
-     private detectApiError;
+ /**
+  * @public
+  */
+ export declare interface IntegrationErrorProperties {
+     /**
+      *  a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of
+      *  the problem except for purposes of localization.  If omitted, the title will default to the type
+      *  of error (e.g., IntegrationError, or ApiRequestError)
+      */
+     title?: string;
+     /**
+      * Additional details related to the error that may help the user troubleshoot the issue.  If set by the user
+      * via the Error constructor, the user provided value will override any automated help message set by the
+      * Error class.
+      */
+     help?: string;
+     /**
+      * The `cause` property is used to specify the `cause` of the error.  Typically,
+      * this property is used to pass through a related Error instance but can be any value.
+      */
+     cause?: unknown;
+     /**
+      * The HTTP status code applicable to this error, expressed as a string value.
+      */
+     status?: string;
+     /**
+      *  an application-specific error code, expressed as a string value.
+      */
+     code?: string;
      /**
-      * Returns true if the `httpStatusCode` is not one of the rounded HTTP status codes
-      * specified in the PolarityRequest `roundedSuccessStatusCodes` property.
+      * Relevant for integration errors involving a network call, the `requestOptions` property
+      * details the request options that resulted in the specified error.  The `requestOptions` property will automatically
+      * have sensitive authentication headers stripped.
+      * By default, the following paths are sanitized:
       *
-      * @param httpStatusCode - A numeric HTTP Status Code
-      * @returns true if the provided `httpStatusCode` is an error code
+      * - auth.password
+      * - auth.bearer
+      * - body.password
+      * - form.client_secret
+      * - headers.authorization
+      * - headers.x-api-key
+      *
+      * Additional paths can be sanitized by using the `requestOptionsToSanitize` property.
+      */
+     requestOptions?: HttpRequestOptions;
+     /**
+      * List of paths in JSON dot notation to sanitize in the requestOptions object
+      */
+     requestOptionsToSanitize?: string[];
+     /**
+      * Any additional properties which will be appended to the Error's meta property
+      */
+     meta?: MetaObject;
+ }
+
+ /**
+  * Integration option definition for config.json
+  * @public
+  */
+ export declare type IntegrationOption = {
+     type: 'text' | 'password';
+     key: string;
+     name: string;
+     description?: string;
+     default: string | null;
+     userCanEdit?: boolean;
+     adminOnly?: boolean;
+ } | {
+     type: 'boolean';
+     key: string;
+     name: string;
+     description?: string;
+     default: boolean | null;
+     userCanEdit?: boolean;
+     adminOnly?: boolean;
+ } | {
+     type: 'number';
+     key: string;
+     name: string;
+     description?: string;
+     default: number | null;
+     userCanEdit?: boolean;
+     adminOnly?: boolean;
+ } | {
+     type: 'select';
+     key: string;
+     name: string;
+     description?: string;
+     default: SelectOptionItem | SelectOptionItem[] | string | null;
+     options: SelectOptionItem[];
+     multiple?: boolean;
+     userCanEdit: boolean;
+     adminOnly: boolean;
+ };
+
+ /**
+  * @public
+  */
+ export declare type IsApiErrorFunction = (response: HttpRequestResponse, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => IsApiErrorResult;
+
+ /**
+  * @public
+  */
+ export declare type IsApiErrorResult = {
+     /**
+      * Indicates whether the response is an API error.
       */
-     private isHttpStatusCodeError;
+     isApiError: boolean;
      /**
-      * Returns true indicating that the API returned an error  if the `httpBody` contains
-      * one of the paths specified by the PolarityRequest `httpResponseErrorProperties`
-      * property.
+      * Optional message providing additional information about the API error.  The
+      * returned `message` will be used as the `message` property on the {@link ApiRequestError} object
+      * thrown by the request.
+      */
+     message?: string;
+ };
+
+ /**
+  * Thrown when the polarity-integration-utils library is used incorrectly.  For example,
+  * if a method is called with incorrect or missing parameters, or a required initialization
+  * method is not called.  This Error class should not be used directly by integrations.
+  *
+  * @public
+  */
+ export declare class LibraryUsageError extends IntegrationError {
+     constructor(message: string, properties?: IntegrationErrorProperties);
+ }
+
+ /**
+  * Minimal interface for a rate limiter compatible with PolarityRequest.
+  * The Polarity server provides a Bottleneck instance that satisfies this interface.
+  *
+  * @public
+  */
+ export declare interface Limiter {
+     schedule<T>(fn: (...args: unknown[]) => PromiseLike<T>, ...args: unknown[]): Promise<T>;
+ }
+
+ /**
+  * @public
+  */
+ export declare type MetaObject = {
+     [key: string]: unknown;
+ };
+
+ /**
+  * Factory function that creates mock functions. Pass `vi.fn` (Vitest)
+  * or `jest.fn` (Jest) to get spy capabilities. When omitted, plain
+  * no-op functions are used.
+  *
+  * @example
+  * ```typescript
+  * // Vitest — enables toHaveBeenCalledWith() assertions
+  * const ctx = createMockIntegrationContext(vi.fn);
+  *
+  * // Jest
+  * const ctx = createMockIntegrationContext(jest.fn);
+  *
+  * // No framework — plain no-ops
+  * const ctx = createMockIntegrationContext();
+  * ```
+  * @public
+  */
+ export declare type MockFnFactory = () => (...args: any[]) => any;
+
+ /**
+  * Generic network error for REST requests.
+  * https://betterstack.com/community/guides/scaling-nodejs/nodejs-errors/#4-econnrefused
+  *
+  * @public
+  */
+ export declare class NetworkError extends IntegrationError {
+     constructor(message: string, properties?: IntegrationErrorProperties);
+ }
+
+ /**
+  * Hook that runs when an API error is detected (non-success status code or error
+  * properties found in the response body). Receives the full HTTP response so the
+  * hook can inspect status codes, headers, and body.
+  *
+  * If all registered hooks return without throwing, the error is suppressed and
+  * the HTTP response is returned to the caller. To propagate or replace the error,
+  * throw from within the hook.
+  *
+  * @public
+  */
+ export declare type OnApiErrorHook = (error: ApiRequestError, response: HttpRequestResponse, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<void>;
+
+ /**
+  * Hook that runs when a network error or rate-limiting error occurs during a request.
+  *
+  * If all registered hooks return without throwing, the error is suppressed.
+  * To propagate or replace the error, throw from within the hook.
+  *
+  * @public
+  */
+ export declare type OnNetworkErrorHook = (error: NetworkError | RetryRequestError, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<void>;
+
+ /**
+  * @deprecated Do not use in v2 integrations.
+  * @group Utilities
+  * @public
+  * @param error - Error instance to parse into a plain old javascript object
+  */
+ export declare const parseErrorToReadableJson: (error: ResponseError) => any;
+
+ /**
+  * A utility class for making HTTP requests
+  * @group Requests
+  * @public
+  */
+ export declare class PolarityRequest {
+     /**
+      * Instance of a Bunyan logger
+      */
+     private logger;
+     /**
+      * postman-request library request object with default values set.  Used internally for
+      * making HTTP requests directly via the postman-request library
+      */
+     private readonly requestWithDefaults;
+     readonly roundedSuccessStatusCodes: number[];
+     /**
+      * One or more HTTP response properties specified using JSON dot notation.  If the
+      * specified path exists within the `body` property of the HTTP Response, an
+      * ApiRequestError will be thrown.
       *
-      * @param httpBody - body property from the HttpRequestResponse
-      * @returns `true` if the httpBody property contains properties specified in `httpResponseErrorProperties`
+      * By default, this value is an empty array and response properties are not used to
+      * detect errors.
+      * @defaultValue []
       */
-     private hasHttpResponseErrorProperty;
+     readonly httpResponseErrorProperties: string[];
      /**
-      * Returns an error message based on the `httpResponseErrorMessageProperties` first.  If no
-      * message is found, it then uses the `httpResponseErrorProperties` to attempt to find
-      * a suitable error message.  If no message is still found, the `defaultMessage` is returned.
+      * One or more HTTP response properties specified using JSON dot notation that
+      * point to an error message that should be displayed to the user in the event
+      * of an API error.
       *
-      * @param httpBody - JSON Object returned by an HTTP Request
-      * @param defaultMessage - A default error message to use if no specific error messages are found
-      * @returns An error message
+      * The property should be a string value.  If the property does not exist or is not
+      * a string value, a default error message will be used instead.
       */
-     private getErrorMessageFromHttpResponse;
+     readonly httpResponseErrorMessageProperties: string[];
      /**
-      * Given a list of `properties` which are strings representing JSON dot notation, this
-      * method returns the first string property found at the given JSON path
-      * in the given `object`.
+      * Optional method that can be implemented to determine if an API error
+      * was encountered after an HTTP request is made.
+      *
+      * If the `isApiError` method is implemented
+      * the property `roundedSuccessStatusCodes` and `httpResponseErrorProperties` are not
+      * used to determine API errors.
       *
-      * @param object - An object to find properties in
-      * @param properties - a list of JSON dot notation properties to look for within `object`
-      * @returns A string value of the property found within the given object or undefined if no value is found
+      * @returns An object indicating whether an API error was encountered and an optional message.
       */
-     private maybeGetStringPropertyValue;
+     readonly isApiError: IsApiErrorFunction;
      /**
-      * Runs multiple requests in parallel with a limit on the maximum number of concurrent requests.
+      * An array of JSON dot notation paths to omit from the request options when logging.
       *
-      * When running multiple request at once it is often useful to be able to tie a specific request
-      * back to the entity the request is for.  To support this, the `HttpRequestOptions` object accepts
-      * an optional `entity` property which can be assigned to the Entity the request is being made for.
-      * The `HttpRequestResponse` object returned by this method will include the same `entity` property
-      * making it easy to match the response to the entity.
+      * This property can be used to sanitize sensitive request properties that should not
+      * appear in logging.
       *
-      * Alternatively, for requests that are made for multiple entities at once (e.g., a query that can
-      * search multiple entities at a time), the `HttpRequestOptions` object also has an `entities`
-      * property which accept an array of entity objects.  Similar to the `entity`, the
-      * `entities` property will be set on the `HttpRequestResponse` object.
+      * Note that the `requestOptions` object is automatically sanitized to remove properties that
+      * typically contain sensitive API key and passwords.  For a list of properties that are
+      * automatically sanitized, see the {@link sanitizeRequestOptions} method.
+      */
+     readonly requestOptionsToSanitize: string[];
+     userOptions: DoLookupUserOptions;
+     /**
+      * An optional rate limiter instance used to throttle HTTP requests.
+      * When set, all requests made via {@link PolarityRequest.run} are scheduled
+      * through this limiter. Typically provided by the Polarity server via the
+      * integration context.
+      */
+     limiter: Limiter | null;
+     /**
+      * Lifecycle hooks for customizing request behavior. Hooks are configured via the
+      * {@link PolarityRequestOptions.hooks} property when creating a new instance of the
+      * {@link PolarityRequest} class.
       *
-      * Finally, if you are looking to pass through a custom request id you can do that using the
-      * `requestId` property.
+      * @see {@link PolarityRequestHooks} for hook type details.
+      */
+     readonly hooks: Required<PolarityRequestHooks>;
+     constructor(options?: PolarityRequestOptions);
+     private configFieldIsValid;
+     /**
+      * Makes a single HTTP request and returns the response or throws an error
       *
-      * @param options - An array of request options for running requests in parallel.
-      * @returns A promise that resolves to an array of responses in the same order as the input
-      * request options. If the `returnErrors` property is set to `true`, the response objects will
-      * have their `error` property set to the thrown error. If `onNetworkError` hooks are configured
-      * and suppress an error (return without throwing), the corresponding entry will be `undefined`.
-      */
-     runInParallel(options: RunInParallelOptions): Promise<(HttpRequestResponse | undefined)[]>;
-    }
-
-    /**
-     * Hooks for customizing the {@link PolarityRequest} lifecycle. All hook arrays
-     * execute in order. `beforeRequest` and `afterResponse` hooks chain their output,
-     * while error hooks run sequentially and can suppress errors by returning without
-     * throwing.
-     *
-     * @public
-     */
-    export declare interface PolarityRequestHooks {
-        /**
-         * Hooks that run before each HTTP request. Each hook receives a copy of the request
-         * options and the return value is passed to the next hook (or used for the request).
-         */
-        beforeRequest?: BeforeRequestHook[];
-        /**
-         * Hooks that run after a successful HTTP response. Each hook receives the response
-         * from the previous hook and the return value is passed to the next hook (or returned
-         * to the caller).
-         */
-        afterResponse?: AfterResponseHook[];
-        /**
-         * Hooks that run when an API error is detected. Each hook receives the error and the
-         * full HTTP response. If all hooks return without throwing, the error is suppressed.
-         */
-        onApiError?: OnApiErrorHook[];
-        /**
-         * Hooks that run when a network or rate-limiting error occurs. If all hooks return
-         * without throwing, the error is suppressed.
-         */
-        onNetworkError?: OnNetworkErrorHook[];
-    }
-
-    /**
-     * @public
-     */
-    export declare interface PolarityRequestOptions {
-        defaults?: ConfigRequestProxyOptions;
-        isApiError?: IsApiErrorFunction;
-        roundedSuccessStatusCodes?: number[];
-        httpResponseErrorProperties?: string[];
-        httpResponseErrorMessageProperties?: string[];
-        requestOptionsToSanitize?: string[];
-        hooks?: PolarityRequestHooks;
-        limiter?: Limiter;
-    }
-
-    /**
-     * @public
-     */
-    export declare interface ResponseError {
-        name: string;
-        message: string;
-        stack?: string;
-        code?: number | string;
-    }
-
-    /**
-     * Thrown by authenticated request method for any HTTP status codes where we want to allow
-     * the user to retry their lookup.
-     *
-     * @public
-     */
-    export declare class RetryRequestError extends IntegrationError {
-        constructor(message: string, properties?: IntegrationErrorProperties);
-    }
+      * @param requestOptions - request options used to make the HTTP request
+      * @returns The HTTP response
+      */
+     run(requestOptions: HttpRequestOptions): Promise<HttpRequestResponse | undefined> | never;
+     /**
+      * Checks whether the HTTP response is an API error and returns an ApiRequestError if it is.
+      *
+      * @param httpResponse - The HTTP response from the Postman request.
+      * @param requestOptions - The options used for the request.
+      * @returns An ApiRequestError if the response indicates an API error, undefined otherwise.
+      *
+      * @throws {@link LibraryUsageError}
+          * Throws if the `isApiError` function returns an invalid result.
+          */
+      private detectApiError;
+      /**
+       * Returns true if the `httpStatusCode` is not one of the rounded HTTP status codes
+       * specified in the PolarityRequest `roundedSuccessStatusCodes` property.
+       *
+       * @param httpStatusCode - A numeric HTTP Status Code
+       * @returns true if the provided `httpStatusCode` is an error code
+       */
+      private isHttpStatusCodeError;
+      /**
+       * Returns true indicating that the API returned an error  if the `httpBody` contains
+       * one of the paths specified by the PolarityRequest `httpResponseErrorProperties`
+       * property.
+       *
+       * @param httpBody - body property from the HttpRequestResponse
+       * @returns `true` if the httpBody property contains properties specified in `httpResponseErrorProperties`
+       */
+      private hasHttpResponseErrorProperty;
+      /**
+       * Returns an error message based on the `httpResponseErrorMessageProperties` first.  If no
+       * message is found, it then uses the `httpResponseErrorProperties` to attempt to find
+       * a suitable error message.  If no message is still found, the `defaultMessage` is returned.
+       *
+       * @param httpBody - JSON Object returned by an HTTP Request
+       * @param defaultMessage - A default error message to use if no specific error messages are found
+       * @returns An error message
+       */
+      private getErrorMessageFromHttpResponse;
+      /**
+       * Given a list of `properties` which are strings representing JSON dot notation, this
+       * method returns the first string property found at the given JSON path
+       * in the given `object`.
+       *
+       * @param object - An object to find properties in
+       * @param properties - a list of JSON dot notation properties to look for within `object`
+       * @returns A string value of the property found within the given object or undefined if no value is found
+       */
+      private maybeGetStringPropertyValue;
+      /**
+       * Runs multiple requests in parallel with a limit on the maximum number of concurrent requests.
+       *
+       * When running multiple request at once it is often useful to be able to tie a specific request
+       * back to the entity the request is for.  To support this, the `HttpRequestOptions` object accepts
+       * an optional `entity` property which can be assigned to the Entity the request is being made for.
+       * The `HttpRequestResponse` object returned by this method will include the same `entity` property
+       * making it easy to match the response to the entity.
+       *
+       * Alternatively, for requests that are made for multiple entities at once (e.g., a query that can
+       * search multiple entities at a time), the `HttpRequestOptions` object also has an `entities`
+       * property which accept an array of entity objects.  Similar to the `entity`, the
+       * `entities` property will be set on the `HttpRequestResponse` object.
+       *
+       * Finally, if you are looking to pass through a custom request id you can do that using the
+       * `requestId` property.
+       *
+       * @param options - An array of request options for running requests in parallel.
+       * @returns A promise that resolves to an array of responses in the same order as the input
+       * request options. If the `returnErrors` property is set to `true`, the response objects will
+       * have their `error` property set to the thrown error. If `onNetworkError` hooks are configured
+       * and suppress an error (return without throwing), the corresponding entry will be `undefined`.
+       */
+      runInParallel(options: RunInParallelOptions): Promise<(HttpRequestResponse | undefined)[]>;
+     }
 
-    /**
-     * @public
-     */
-    export declare type RunInParallelOptions = {
-        /**
-         * Array of HttpRequestOptions that will be run in parallel as specified by
-         * the `maxConcurrentRequests` property.
-         */
-        allRequestOptions: HttpRequestOptions[];
-        /**
-         * Maximum number of requests to run in parallel
-         *
-         * @defaultValue 5
-         */
-        maxConcurrentRequests?: number;
-        /**
-         * If true, any errors thrown during the request will be returned in the response object on the `error` property
-         * of the returned `HttpRequestResponse` object.  If false, any errors thrown will be thrown and should be handled by
-         *
-         *
-         * @defaultValue false
-         */
-        returnErrors?: boolean;
-    };
-
-    /**
-     * Sanitizes the request options by removing sensitive information
-     * from the provided request options object.
-     *
-     * Default sanitized paths are:
-     *
-     * - auth.password
-     * - auth.bearer
-     * - body.password
-     * - form.client_secret
-     * - headers.authorization
-     * - headers.x-api-key
-     *
-     * @param requestOptions - request options to sanitize
-     * @param additionalPathsToSanitize - array of additional paths to sanitize in addition to the
-     * default paths.
-     */
-    export declare function sanitizeRequestOptions(requestOptions: HttpRequestOptions, additionalPathsToSanitize?: string[]): HttpRequestOptions;
+     /**
+      * Hooks for customizing the {@link PolarityRequest} lifecycle. All hook arrays
+      * execute in order. `beforeRequest` and `afterResponse` hooks chain their output,
+      * while error hooks run sequentially and can suppress errors by returning without
+      * throwing.
+      *
+      * @public
+      */
+     export declare interface PolarityRequestHooks {
+         /**
+          * Hooks that run before each HTTP request. Each hook receives a copy of the request
+          * options and the return value is passed to the next hook (or used for the request).
+          */
+         beforeRequest?: BeforeRequestHook[];
+         /**
+          * Hooks that run after a successful HTTP response. Each hook receives the response
+          * from the previous hook and the return value is passed to the next hook (or returned
+          * to the caller).
+          */
+         afterResponse?: AfterResponseHook[];
+         /**
+          * Hooks that run when an API error is detected. Each hook receives the error and the
+          * full HTTP response. If all hooks return without throwing, the error is suppressed.
+          */
+         onApiError?: OnApiErrorHook[];
+         /**
+          * Hooks that run when a network or rate-limiting error occurs. If all hooks return
+          * without throwing, the error is suppressed.
+          */
+         onNetworkError?: OnNetworkErrorHook[];
+     }
 
-    /**
-     * A select option item with display label and value
-     * @public
-     */
-    export declare interface SelectOptionItem {
-        value: string;
-        display: string;
-    }
+     /**
+      * @public
+      */
+     export declare interface PolarityRequestOptions {
+         defaults?: ConfigRequestProxyOptions;
+         isApiError?: IsApiErrorFunction;
+         roundedSuccessStatusCodes?: number[];
+         httpResponseErrorProperties?: string[];
+         httpResponseErrorMessageProperties?: string[];
+         requestOptionsToSanitize?: string[];
+         hooks?: PolarityRequestHooks;
+         limiter?: Limiter;
+     }
 
-    /**
-     * @public
-     */
-    export declare interface SerializedIntegrationError {
-        /**
-         *  a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of
-         *  the problem except for purposes of localization.  If omitted, the title will default to the type
-         *  of error (e.g., IntegrationError, or ApiRequestError)
-         */
-        title: string;
-        /**
-         * The name data property of IntegrationError.prototype is shared by all Error instances.
-         * It represents the name for the type of error. For IntegrationError.prototype.name,
-         * the initial value is "IntegrationError".
-         */
-        name: string;
-        /**
-         * a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be
-         * localized
-         */
-        detail: string;
-        /**
-         * An optional HTTP status code applicable to this error, expressed as a string value.
-         */
-        status?: string;
-        /**
-         * Additional details related to the error that may help the user troubleshoot the issue.  If set by the user
-         * via the Error constructor, the user provided value will override any automated help message set by the
-         * Error class.
-         */
-        help?: string;
-        /**
-         * An optional StackTrace of the error
-         */
-        stack?: string;
-        /**
-         *  An optional application-specific error code, expressed as a string value.
-         */
-        code?: number | string;
-        /**
-         * The `cause` property is used to specify the `cause` of the error.  Typically,
-         * this property is used to pass through a related Error instance but can be any value.
-         */
-        cause?: unknown;
-        /**
-         * Relevant for integration errors involving a network call, the `requestOptions` property
-         * details the request options that resulted in the specified error.  The `requestOptions` property will automatically
-         * have sensitive authentication headers stripped.
-         */
-        requestOptions?: HttpRequestOptions;
-        /**
-         * an optional  meta object containing non-standard meta-information about the error.
-         */
-        meta?: ErrorMeta;
-    }
-
-    /**
-     * Set the logger object used by the integration.
-     *
-     * @example
-     * Example of setting the logger within the integration's startup method:
-     * ```js
-     * const { setLogger } = require('polarity-integration-utils');
-     *
-     * function startup(logger){
-     *   setLogger(logger);
-     * }
-     * ```
-     *
-     * You can now use {@link getLogger} to get the logger object anywhere within your integration codebase.
-     *
-     * @public
-     * @param logger - the integration logger object passed into the `startup` method
-     */
-    export declare const setLogger: (logger: Logger) => void;
+     /**
+      * @deprecated Do not use in v2 integrations.
+      * @public
+      */
+     export declare interface ResponseError {
+         name: string;
+         message: string;
+         stack?: string;
+         code?: number | string;
+     }
 
-    /**
-     * View component reference in config.json
-     * @public
-     */
-    export declare interface ViewComponent {
-        component: {
-            file: string;
-        };
-        template: {
-            file: string;
-        };
-    }
-
-    export { }
+     /**
+      * Thrown by authenticated request method for any HTTP status codes where we want to allow
+      * the user to retry their lookup.
+      *
+      * @public
+      */
+     export declare class RetryRequestError extends IntegrationError {
+         constructor(message: string, properties?: IntegrationErrorProperties);
+     }
+
+     /**
+      * @public
+      */
+     export declare type RunInParallelOptions = {
+         /**
+          * Array of HttpRequestOptions that will be run in parallel as specified by
+          * the `maxConcurrentRequests` property.
+          */
+         allRequestOptions: HttpRequestOptions[];
+         /**
+          * Maximum number of requests to run in parallel
+          *
+          * @defaultValue 5
+          */
+         maxConcurrentRequests?: number;
+         /**
+          * If true, any errors thrown during the request will be returned in the response object on the `error` property
+          * of the returned `HttpRequestResponse` object.  If false, any errors thrown will be thrown and should be handled by
+          *
+          *
+          * @defaultValue false
+          */
+         returnErrors?: boolean;
+     };
+
+     /**
+      * Sanitizes the request options by removing sensitive information
+      * from the provided request options object.
+      *
+      * Default sanitized paths are:
+      *
+      * - auth.password
+      * - auth.bearer
+      * - body.password
+      * - form.client_secret
+      * - headers.authorization
+      * - headers.x-api-key
+      *
+      * @param requestOptions - request options to sanitize
+      * @param additionalPathsToSanitize - array of additional paths to sanitize in addition to the
+      * default paths.
+      * @group Requests
+      * @public
+      */
+     export declare function sanitizeRequestOptions(requestOptions: HttpRequestOptions, additionalPathsToSanitize?: string[]): HttpRequestOptions;
+
+     /**
+      * A select option item with display label and value
+      * @public
+      */
+     export declare interface SelectOptionItem {
+         value: string;
+         display: string;
+     }
+
+     /**
+      * @public
+      */
+     export declare interface SerializedIntegrationError {
+         /**
+          *  a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of
+          *  the problem except for purposes of localization.  If omitted, the title will default to the type
+          *  of error (e.g., IntegrationError, or ApiRequestError)
+          */
+         title: string;
+         /**
+          * The name data property of IntegrationError.prototype is shared by all Error instances.
+          * It represents the name for the type of error. For IntegrationError.prototype.name,
+          * the initial value is "IntegrationError".
+          */
+         name: string;
+         /**
+          * a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be
+          * localized
+          */
+         detail: string;
+         /**
+          * An optional HTTP status code applicable to this error, expressed as a string value.
+          */
+         status?: string;
+         /**
+          * Additional details related to the error that may help the user troubleshoot the issue.  If set by the user
+          * via the Error constructor, the user provided value will override any automated help message set by the
+          * Error class.
+          */
+         help?: string;
+         /**
+          * An optional StackTrace of the error
+          */
+         stack?: string;
+         /**
+          *  An optional application-specific error code, expressed as a string value.
+          */
+         code?: number | string;
+         /**
+          * The `cause` property is used to specify the `cause` of the error.  Typically,
+          * this property is used to pass through a related Error instance but can be any value.
+          */
+         cause?: unknown;
+         /**
+          * Relevant for integration errors involving a network call, the `requestOptions` property
+          * details the request options that resulted in the specified error.  The `requestOptions` property will automatically
+          * have sensitive authentication headers stripped.
+          */
+         requestOptions?: HttpRequestOptions;
+         /**
+          * an optional  meta object containing non-standard meta-information about the error.
+          */
+         meta?: ErrorMeta;
+     }
+
+     /**
+      * Set the logger object used by the integration.
+      *
+      * @example
+      * Example of setting the logger within the integration's startup method:
+      * ```js
+      * const { setLogger } = require('polarity-integration-utils');
+      *
+      * function startup(logger){
+      *   setLogger(logger);
+      * }
+      * ```
+      *
+      * You can now use {@link getLogger} to get the logger object anywhere within your integration codebase.
+      *
+      * @group Logging
+      * @public
+      * @param logger - the integration logger object passed into the `startup` method
+      */
+     export declare const setLogger: (logger: Logger) => void;
+
+     /**
+      * View component reference in config.json
+      * @public
+      */
+     export declare interface ViewComponent {
+         component: {
+             file: string;
+         };
+         template: {
+             file: string;
+         };
+     }
+
+     export { }