polarity-integration-utils 0.1.0 → 3.1.3

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

@@ -0,0 +1,1259 @@
+import Bottleneck from 'bottleneck';
+import { z } from 'zod';
+
+/**
+ * API error for REST requests
+ *
+ * @public
+ */
+export declare class ApiRequestError extends IntegrationError {
+    constructor(message: string, properties?: IntegrationErrorProperties);
+}
+
+/**
+ * Thrown by generateAccessToken method if there is a failure to fetch a token
+ *
+ * @public
+ */
+export declare class AuthRequestError extends IntegrationError {
+    constructor(message: string, properties?: IntegrationErrorProperties);
+}
+
+/**
+ * Cache operation options
+ */
+export declare interface CacheOptions {
+    /** Time-to-live in seconds. If not specified, uses default TTL */
+    ttl?: number;
+}
+
+/**
+ * @public
+ */
+export declare type Channel = z.infer<typeof ChannelSchema>;
+
+declare const ChannelSchema: z.ZodObject<{
+    channel_name: z.ZodString;
+    id: z.ZodNumber;
+}, z.core.$strip>;
+
+/**
+ * @public
+ */
+export declare type ConfigRequestProxyOptions = {
+    ca?: undefined | string;
+    cert?: undefined | string;
+    key?: undefined | string;
+    passphrase?: undefined | string;
+    rejectUnauthorized?: undefined | boolean;
+    proxy?: undefined | string;
+    json?: undefined | boolean;
+};
+
+/**
+ * @public
+ */
+export declare type DoLookupResult<TDetails = unknown> = Result<TDetails>[];
+
+/**
+ * User options object passed into the integration's `doLookup` method.
+ *
+ * @example
+ * Example of the user options object passed into `doLookup`
+ * ```js
+ * function doLookup(entities, options, cb){
+ *   // options here is of type DoLookupUserOptions
+ * }
+ * ```
+ *
+ * @example
+ * As an example, if your integration has a user option with a `key` value of
+ * `apiKey` within its `config.json`, the user options object passed into the `doLookup` method would look like:
+ * ```json
+ * {
+ *   "apiKey": "XXXXXXXXXX"
+ * }
+ * ```
+ * @public
+ */
+export declare type DoLookupUserOptions = z.infer<typeof DoLookupUserOptionsSchema>;
+
+declare const DoLookupUserOptionsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUndefined, z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+    display: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>, z.ZodArray<z.ZodObject<{
+    display: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>>]>>;
+
+/**
+ * @public
+ */
+export declare type DropdownUserOptionValue = z.infer<typeof DropdownUserOptionValueSchema>;
+
+declare const DropdownUserOptionValueSchema: z.ZodObject<{
+    display: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+
+/**
+ * Represents a Polarity Entity object which is passed to an integration's
+ * doLookup method.
+ *
+ * @public
+ */
+export declare type Entity = z.infer<typeof EntitySchema>;
+
+declare const EntitySchema: z.ZodObject<{
+    value: z.ZodString;
+    types: z.ZodArray<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"IP">, z.ZodLiteral<"IPv4">, z.ZodLiteral<"IPv4CIDR">, z.ZodLiteral<"IPv6">, z.ZodLiteral<"MAC">, z.ZodLiteral<"MD5">, z.ZodLiteral<"SHA1">, z.ZodLiteral<"SHA256">, z.ZodLiteral<"cve">, z.ZodLiteral<"domain">, z.ZodLiteral<"email">, z.ZodLiteral<"hash">, z.ZodLiteral<"string">, z.ZodLiteral<"url">]>, z.ZodLiteral<"*">, z.ZodLiteral<"custom">, z.ZodCustom<`custom.${string}`, `custom.${string}`>]>>;
+    type: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"IP">, z.ZodLiteral<"IPv4">, z.ZodLiteral<"IPv4CIDR">, z.ZodLiteral<"IPv6">, z.ZodLiteral<"MAC">, z.ZodLiteral<"MD5">, z.ZodLiteral<"SHA1">, z.ZodLiteral<"SHA256">, z.ZodLiteral<"cve">, z.ZodLiteral<"domain">, z.ZodLiteral<"email">, z.ZodLiteral<"hash">, z.ZodLiteral<"string">, z.ZodLiteral<"url">]>, z.ZodLiteral<"*">, z.ZodLiteral<"custom">, z.ZodCustom<`custom.${string}`, `custom.${string}`>]>;
+    requestContext: z.ZodObject<{
+        requestType: z.ZodLiteral<"onDemand">;
+        isUserInitiated: z.ZodBoolean;
+    }, z.core.$strip>;
+    longitude: z.ZodNumber;
+    latitude: z.ZodNumber;
+    isURL: z.ZodBoolean;
+    isSHA512: z.ZodBoolean;
+    isSHA256: z.ZodBoolean;
+    isSHA1: z.ZodBoolean;
+    isPrivateIP: z.ZodBoolean;
+    isMD5: z.ZodBoolean;
+    isIPv6: z.ZodBoolean;
+    isIPv4: z.ZodBoolean;
+    isIP: z.ZodBoolean;
+    isHex: z.ZodBoolean;
+    isHash: z.ZodBoolean;
+    isHTMLTag: z.ZodBoolean;
+    isEmail: z.ZodBoolean;
+    isDomain: z.ZodBoolean;
+    hashType: z.ZodUnion<readonly [z.ZodLiteral<"md5">, z.ZodLiteral<"sha1">, z.ZodLiteral<"sha256">, z.ZodLiteral<"sha512">, z.ZodLiteral<"">]>;
+    displayValue: z.ZodString;
+    channels: z.ZodArray<z.ZodObject<{
+        channel_name: z.ZodString;
+        id: z.ZodNumber;
+    }, z.core.$strip>>;
+    IPType: z.ZodUnion<readonly [z.ZodLiteral<"IPv4">, z.ZodLiteral<"IPv6">, z.ZodLiteral<"">]>;
+}, z.core.$strip>;
+
+/**
+ * Entity Types including custom types
+ * @public
+ */
+export declare type EntityType = z.infer<typeof EntityTypeSchema>;
+
+declare const EntityTypeSchema: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"IP">, z.ZodLiteral<"IPv4">, z.ZodLiteral<"IPv4CIDR">, z.ZodLiteral<"IPv6">, z.ZodLiteral<"MAC">, z.ZodLiteral<"MD5">, z.ZodLiteral<"SHA1">, z.ZodLiteral<"SHA256">, z.ZodLiteral<"cve">, z.ZodLiteral<"domain">, z.ZodLiteral<"email">, z.ZodLiteral<"hash">, z.ZodLiteral<"string">, z.ZodLiteral<"url">]>, z.ZodLiteral<"*">, z.ZodLiteral<"custom">, z.ZodCustom<`custom.${string}`, `custom.${string}`>]>;
+
+/**
+ * @public
+ */
+declare interface Error_2 {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: number | string;
+}
+export { Error_2 as Error }
+
+/**
+ * @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/logger');
+ *
+ * const logger = getLogger();
+ * logger.trace('this is a trace message');
+ * ```
+ *
+ * @public
+ * @returns the integration's logger object
+ */
+export declare const getLogger: () => Logger;
+
+/**
+ * Global cache operations - shared across all integrations and users
+ * Use for system-wide statistics, feature flags, or shared configuration
+ */
+export declare interface GlobalCache {
+    /**
+     * Get a value from global cache
+     * @param key - The cache key
+     * @returns Promise that resolves to the cached value or null if not found
+     * @example
+     * const totalLookups = await cache.global.get('total_lookups') || 0;
+     */
+    get(key: string): Promise<unknown>;
+    /**
+     * Set a value in global cache
+     * @param key - The cache key
+     * @param value - The value to cache (must be JSON serializable)
+     * @param options - Cache options including TTL
+     * @returns Promise that resolves when the operation completes
+     * @example
+     * await cache.global.set('total_lookups', count + 1, \{ ttl: 86400 \});
+     */
+    set(key: string, value: unknown, options?: CacheOptions): Promise<void>;
+    /**
+     * Delete a value from global cache
+     * @param key - The cache key to delete
+     * @returns Promise that resolves when the operation completes
+     * @example
+     * await cache.global.delete('feature_flags');
+     */
+    delete(key: string): Promise<void>;
+}
+
+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;
+};
+
+export declare interface Integration<TStartupResult = unknown, TDetails = unknown> {
+    startup: (logger: Logger) => Promise<TStartupResult>;
+    doLookup: (entities: Entity[], options: DoLookupUserOptions, context: IntegrationContext) => Promise<DoLookupResult<TDetails> | IntegrationError | null | void>;
+    onMessage?: (payload: unknown, options: DoLookupUserOptions, context: IntegrationContext) => Promise<unknown>;
+    onDetails?: (lookupObject: Result<TDetails>, options: DoLookupUserOptions, context: IntegrationContext) => Promise<unknown>;
+    validateOptions: (options: ValidateOptionsUserOptions, context: IntegrationContext) => IntegrationError[];
+}
+
+/**
+ * Integration-scoped cache operations - shared across all users of a specific integration
+ * Use for API responses, configuration, or data that's the same for all users
+ */
+export declare interface IntegrationCache {
+    /**
+     * Get a value from integration cache
+     * @param key - The cache key
+     * @returns Promise that resolves to the cached value or null if not found
+     * @example
+     * const config = await cache.integration.get('api_config');
+     */
+    get(key: string): Promise<unknown>;
+    /**
+     * Set a value in integration cache
+     * @param key - The cache key
+     * @param value - The value to cache (must be JSON serializable)
+     * @param options - Cache options including TTL
+     * @returns Promise that resolves when the operation completes
+     * @example
+     * await cache.integration.set('lookup_ip_1.1.1.1', result, \{ ttl: 300 \});
+     */
+    set(key: string, value: unknown, options?: CacheOptions): Promise<void>;
+    /**
+     * Delete a value from integration cache
+     * @param key - The cache key to delete
+     * @returns Promise that resolves when the operation completes
+     * @example
+     * await cache.integration.delete('expired_config');
+     */
+    delete(key: string): Promise<void>;
+}
+
+/**
+ * @public
+ */
+export declare type IntegrationConfig = z.infer<typeof IntegrationConfigSchema>;
+
+declare const IntegrationConfigSchema: z.ZodObject<{
+    polarityIntegrationUuid: z.ZodUUID;
+    name: z.ZodString;
+    acronym: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    defaultColor: z.ZodOptional<z.ZodString>;
+    entityTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dataTypes: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        type: z.ZodOptional<z.ZodLiteral<"custom">>;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+        regex: z.ZodString;
+        editable: z.ZodOptional<z.ZodBoolean>;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>]>>>;
+    customTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodLiteral<"custom">>;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+        regex: z.ZodString;
+        editable: z.ZodOptional<z.ZodBoolean>;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    supportsAdditionalCustomTypes: z.ZodOptional<z.ZodBoolean>;
+    styles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    block: z.ZodObject<{
+        component: z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strip>;
+        template: z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    summary: z.ZodOptional<z.ZodObject<{
+        component: z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strip>;
+        template: z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    onDemandOnly: z.ZodOptional<z.ZodBoolean>;
+    copyOnDemand: z.ZodOptional<z.ZodBoolean>;
+    logging: z.ZodOptional<z.ZodObject<{
+        level: z.ZodEnum<{
+            error: "error";
+            debug: "debug";
+            info: "info";
+            trace: "trace";
+            warn: "warn";
+            fatal: "fatal";
+        }>;
+    }, z.core.$strip>>;
+    request: z.ZodOptional<z.ZodObject<{
+        cert: z.ZodOptional<z.ZodString>;
+        key: z.ZodOptional<z.ZodString>;
+        passphrase: z.ZodOptional<z.ZodString>;
+        ca: z.ZodOptional<z.ZodString>;
+        proxy: z.ZodOptional<z.ZodString>;
+        rejectUnauthorized: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    options: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodEnum<{
+            text: "text";
+            password: "password";
+        }>;
+        key: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodNullable<z.ZodString>;
+        userCanEdit: z.ZodOptional<z.ZodBoolean>;
+        adminOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"boolean">;
+        key: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodNullable<z.ZodBoolean>;
+        userCanEdit: z.ZodOptional<z.ZodBoolean>;
+        adminOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"number">;
+        key: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodNullable<z.ZodNumber>;
+        userCanEdit: z.ZodOptional<z.ZodBoolean>;
+        adminOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"select">;
+        key: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+            value: z.ZodString;
+            display: z.ZodString;
+        }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            display: z.ZodString;
+        }, z.core.$strip>>, z.ZodString]>>;
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            display: z.ZodString;
+        }, z.core.$strip>>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+        userCanEdit: z.ZodBoolean;
+        adminOnly: z.ZodBoolean;
+    }, z.core.$strip>], "type">>>;
+}, z.core.$strip>;
+
+/**
+ * Integration context provided to integration functions
+ */
+export declare interface IntegrationContext {
+    /** Cache client for hierarchical caching operations */
+    cache: PolarityCache;
+    /** Integration identifier */
+    integrationId: string;
+    /** User identifier */
+    userId?: string;
+    /** Logger instance */
+    logger: Logger;
+}
+
+/**
+ * @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.
+     */
+    readonly cause: Error_2;
+    /**
+     * 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.
+     */
+    cause?: Error_2;
+    /**
+     * 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;
+}
+
+/**
+ * @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.
+     */
+    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);
+}
+
+/**
+ * @public
+ */
+declare type Logger = {
+    child?(arg: unknown): Logger;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    trace(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    fatal(...args: unknown[]): void;
+};
+export { Logger }
+export { Logger as PolarityLogger }
+
+/**
+ * @public
+ */
+export declare type MetaObject = {
+    [key: string]: unknown;
+};
+
+/**
+ * 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);
+}
+
+/**
+ * @public
+ * @param error - Error instance to parse into a plain old javascript object
+ */
+export declare const parseErrorToReadableJson: (error: Error_2) => any;
+
+/**
+ * Main cache interface providing hierarchical caching with three scopes
+ *
+ * Cache Hierarchy:
+ * - Global: System-wide data shared across all integrations
+ * - Integration: Data shared among all users of a specific integration
+ * - User: User-specific data within an integration context
+ *
+ * Best Practices:
+ * - Use appropriate TTL values to prevent stale data
+ * - Handle cache misses gracefully (operations may return null)
+ * - Wrap cache operations in try/catch blocks
+ * - Use descriptive keys that won't conflict with other data
+ *
+ * @example
+ * ```javascript
+ * // In your integration functions:
+ * async function doLookup(entities, options, context) {
+ *   const cache = context?.cache;
+ *   if (!cache) return generateFreshData();
+ *
+ *   try {
+ *     // Check integration cache first
+ *     const cached = await cache.integration.get(`lookup_${entity.value}`);
+ *     if (cached) return cached;
+ *
+ *     // Generate and cache new data
+ *     const result = await apiCall(entity);
+ *     await cache.integration.set(`lookup_${entity.value}`, result, { ttl: 300 });
+ *     return result;
+ *   } catch (error) {
+ *     console.error('Cache error:', error);
+ *     return generateFreshData(); // Fallback
+ *   }
+ * }
+ * ```
+ */
+export declare interface PolarityCache {
+    /** Global cache operations - shared across all integrations and users */
+    global: GlobalCache;
+    /** Integration-scoped cache operations - shared across all users of a specific integration */
+    integration: IntegrationCache;
+    /** User-scoped cache operations - specific to individual users */
+    user: UserCache;
+}
+
+/**
+ * A utility class for making HTTP requests
+ * @public
+ */
+export declare class PolarityRequest {
+    private bottleneckLimiter;
+    /**
+     * Instance of a Bunyan logger
+     */
+    private logger;
+    private internalThrottlingOptions;
+    /**
+     * 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;
+    /**
+     * Optional middleware method for modifying {@link HttpRequestOptions} before a request is made
+     * via the {@link PolarityRequest.run} method or {@link PolarityRequest.runInParallel} method.
+     * The returned `requestOptions` object will be used for the request.  This method is passed
+     * a copy of the original `requestOptions` object so it can be modified without side effects.
+     *
+     * This method is typically used for adding authentication (e.g., auth headers, or basic auth) to every request.
+     * It can also be used to add headers that are required on every request or conditionally add headers based
+     * on the passed in `userOptions`.
+     *
+     * This method can be set as part of the {@link PolarityRequestOptions} when creating a new instance of the
+     * {@link PolarityRequest} class or can be set after the fact.
+     *
+     * @param requestOptions - A copy of the request options used for the request.  This object can be modified
+     * without side effects.
+     * @param userOptions - The user options passed into the `doLookup` method.
+     * @returns The modified request options to use for the request.
+     */
+    preprocessRequestOptions: PreprocessRequestOptions;
+    /**
+     * Optional middleware method for modifying the {@link HttpRequestResponse} after a successful request.
+     * The passed in {@link HttpRequestResponse} object is not a copy but can be safely modified without
+     * side effects.  The returned `HttpRequestResponse` object will be used for the response.
+     *
+     * @param response - The HTTP response from the request.
+     * @param requestOptions - The request options used for the request.
+     * @param userOptions - The user options passed into the `doLookup` method.
+     */
+    postprocessRequestSuccess: PostprocessRequestSuccess;
+    /**
+     * Method that can be implemented to post-process the HTTP response after a failed request.
+     * This method is typically used to inspect the error thrown and either alter the error
+     * object (e.g., to change the error message property to something more specific), to ignore
+     * the error (by not rethrowing it), or to take a specific action based on the error (e.g.,
+     * in the case of a RetryRequestError you may want to retry the request or return a special
+     * payload to the integration front end).
+     *
+     * @param error - The error thrown during the request.
+     * @param requestOptions - The request options used for the request.
+     * @param userOptions - The user options passed into the `doLookup` method.
+     */
+    postprocessRequestFailure: PostprocessRequestFailure;
+    get throttlingOptions(): Bottleneck.ConstructorOptions;
+    set throttlingOptions(throttlingOptions: Bottleneck.ConstructorOptions);
+    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> | never;
+    /**
+     * Checks whether the HTTP response is an API error and throws an ApiRequestError if it is.
+     *
+     * @param httpResponse - The HTTP response from the Postman request.
+     * @param requestOptions - The options used for the request.
+     *
+     * @throws {@link ApiRequestError}
+         * Throws an error if the response indicates an API error.
+         */
+     private maybeThrowApiRequestError;
+     /**
+      * 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.  If the `returnErrors` property is set to `true`
+      * then the response objects will have their `error` property set to the thrown error.
+      */
+     runInParallel(options: RunInParallelOptions): Promise<HttpRequestResponse[]>;
+    }
+
+    /**
+     * @public
+     */
+    export declare interface PolarityRequestOptions {
+        defaults?: ConfigRequestProxyOptions;
+        isApiError?: IsApiErrorFunction;
+        roundedSuccessStatusCodes?: number[];
+        httpResponseErrorProperties?: string[];
+        httpResponseErrorMessageProperties?: string[];
+        requestOptionsToSanitize?: string[];
+        preprocessRequestOptions?: PreprocessRequestOptions;
+        postprocessRequestSuccess?: PostprocessRequestSuccess;
+        postprocessRequestFailure?: PostprocessRequestFailure;
+        throttlingOptions?: Bottleneck.ConstructorOptions;
+    }
+
+    /**
+     * @public
+     */
+    export declare type PossibleUserOptionValue = z.infer<typeof PossibleUserOptionValueSchema>;
+
+    declare const PossibleUserOptionValueSchema: z.ZodUnion<readonly [z.ZodUndefined, z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+        display: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+        display: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>]>;
+
+    /**
+     * @public
+     */
+    export declare type PostprocessRequestFailure = (error: Error, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<unknown> | never;
+
+    /**
+     * Optional middleware method for modifying the {@link HttpRequestResponse} after a successful request.
+     * The passed in {@link HttpRequestResponse} object is not a copy but can be safely modified without
+     * side effects.  The returned `HttpRequestResponse` object will be used for the response.
+     *
+     * @public
+     */
+    export declare type PostprocessRequestSuccess = (response: HttpRequestResponse, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<HttpRequestResponse> | never;
+
+    /**
+     * Optional middleware method for modifying {@link HttpRequestOptions} before a request is made
+     * via the {@link PolarityRequest.run} method or {@link PolarityRequest.runInParallel} method.
+     * The returned `requestOptions` object will be used for the request.  This method is passed
+     * a copy of the original `requestOptions` object so it can be modified without side effects.
+     *
+     * This method is typically used for adding authentication (e.g., auth headers, or basic auth) to every request.  It can also
+     * be used to add headers that are required on every request or conditionally add headers based
+     * on the passed in `userOptions`.
+     *
+     * @public
+     */
+    export declare type PreprocessRequestOptions = (requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<HttpRequestOptions> | never | undefined;
+
+    /**
+     * @public
+     */
+    export declare type Result<TDetails = unknown> = Omit<z.infer<typeof ResultSchema>, 'data'> & {
+        data: {
+            summary: string[];
+            details: TDetails;
+        };
+    };
+
+    declare const ResultSchema: z.ZodObject<{
+        entity: z.ZodObject<{
+            value: z.ZodString;
+            types: z.ZodArray<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"IP">, z.ZodLiteral<"IPv4">, z.ZodLiteral<"IPv4CIDR">, z.ZodLiteral<"IPv6">, z.ZodLiteral<"MAC">, z.ZodLiteral<"MD5">, z.ZodLiteral<"SHA1">, z.ZodLiteral<"SHA256">, z.ZodLiteral<"cve">, z.ZodLiteral<"domain">, z.ZodLiteral<"email">, z.ZodLiteral<"hash">, z.ZodLiteral<"string">, z.ZodLiteral<"url">]>, z.ZodLiteral<"*">, z.ZodLiteral<"custom">, z.ZodCustom<`custom.${string}`, `custom.${string}`>]>>;
+            type: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"IP">, z.ZodLiteral<"IPv4">, z.ZodLiteral<"IPv4CIDR">, z.ZodLiteral<"IPv6">, z.ZodLiteral<"MAC">, z.ZodLiteral<"MD5">, z.ZodLiteral<"SHA1">, z.ZodLiteral<"SHA256">, z.ZodLiteral<"cve">, z.ZodLiteral<"domain">, z.ZodLiteral<"email">, z.ZodLiteral<"hash">, z.ZodLiteral<"string">, z.ZodLiteral<"url">]>, z.ZodLiteral<"*">, z.ZodLiteral<"custom">, z.ZodCustom<`custom.${string}`, `custom.${string}`>]>;
+            requestContext: z.ZodObject<{
+                requestType: z.ZodLiteral<"onDemand">;
+                isUserInitiated: z.ZodBoolean;
+            }, z.core.$strip>;
+            longitude: z.ZodNumber;
+            latitude: z.ZodNumber;
+            isURL: z.ZodBoolean;
+            isSHA512: z.ZodBoolean;
+            isSHA256: z.ZodBoolean;
+            isSHA1: z.ZodBoolean;
+            isPrivateIP: z.ZodBoolean;
+            isMD5: z.ZodBoolean;
+            isIPv6: z.ZodBoolean;
+            isIPv4: z.ZodBoolean;
+            isIP: z.ZodBoolean;
+            isHex: z.ZodBoolean;
+            isHash: z.ZodBoolean;
+            isHTMLTag: z.ZodBoolean;
+            isEmail: z.ZodBoolean;
+            isDomain: z.ZodBoolean;
+            hashType: z.ZodUnion<readonly [z.ZodLiteral<"md5">, z.ZodLiteral<"sha1">, z.ZodLiteral<"sha256">, z.ZodLiteral<"sha512">, z.ZodLiteral<"">]>;
+            displayValue: z.ZodString;
+            channels: z.ZodArray<z.ZodObject<{
+                channel_name: z.ZodString;
+                id: z.ZodNumber;
+            }, z.core.$strip>>;
+            IPType: z.ZodUnion<readonly [z.ZodLiteral<"IPv4">, z.ZodLiteral<"IPv6">, z.ZodLiteral<"">]>;
+        }, z.core.$strip>;
+        displayValue: z.ZodOptional<z.ZodString>;
+        data: z.ZodObject<{
+            summary: z.ZodArray<z.ZodString>;
+            details: z.ZodUnknown;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+
+    /**
+     * 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.
+     */
+    export declare function sanitizeRequestOptions(requestOptions: HttpRequestOptions, additionalPathsToSanitize?: string[]): HttpRequestOptions;
+
+    /**
+     * @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.
+         */
+        cause?: Error_2;
+        /**
+         * 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/logger');
+     *
+     * 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;
+
+    /**
+     * List of supported entity type values
+     * @public
+     */
+    export declare type StandardEntityType = z.infer<typeof StandardEntityTypeSchema>;
+
+    declare const StandardEntityTypeSchema: z.ZodUnion<readonly [z.ZodLiteral<"IP">, z.ZodLiteral<"IPv4">, z.ZodLiteral<"IPv4CIDR">, z.ZodLiteral<"IPv6">, z.ZodLiteral<"MAC">, z.ZodLiteral<"MD5">, z.ZodLiteral<"SHA1">, z.ZodLiteral<"SHA256">, z.ZodLiteral<"cve">, z.ZodLiteral<"domain">, z.ZodLiteral<"email">, z.ZodLiteral<"hash">, z.ZodLiteral<"string">, z.ZodLiteral<"url">]>;
+
+    /**
+     * User-scoped cache operations - specific to individual users
+     * Use for user preferences, recent activity, or personalized data
+     */
+    export declare interface UserCache {
+        /**
+         * Get a value from user cache
+         * @param key - The cache key
+         * @returns Promise that resolves to the cached value or null if not found
+         * @example
+         * const preferences = await cache.user.get('preferences');
+         */
+        get(key: string): Promise<unknown>;
+        /**
+         * Set a value in user cache
+         * @param key - The cache key
+         * @param value - The value to cache (must be JSON serializable)
+         * @param options - Cache options including TTL
+         * @returns Promise that resolves when the operation completes
+         * @example
+         * await cache.user.set('recent_lookups', lookups, \{ ttl: 3600 \});
+         */
+        set(key: string, value: unknown, options?: CacheOptions): Promise<void>;
+        /**
+         * Delete a value from user cache
+         * @param key - The cache key to delete
+         * @returns Promise that resolves when the operation completes
+         * @example
+         * await cache.user.delete('preferences');
+         */
+        delete(key: string): Promise<void>;
+    }
+
+    /**
+     * @public
+     */
+    export declare type ValidateOptionsUserOption = z.infer<typeof ValidateOptionsUserOptionSchema>;
+
+    /**
+     * @public
+     */
+    export declare type ValidateOptionsUserOptions = z.infer<typeof ValidateOptionsUserOptionsSchema>;
+
+    declare const ValidateOptionsUserOptionSchema: z.ZodObject<{
+        integration_id: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodUndefined, z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+            display: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            display: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>>]>;
+        user_can_edit: z.ZodOptional<z.ZodBoolean>;
+        admin_only: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+
+    declare const ValidateOptionsUserOptionsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+        integration_id: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodUndefined, z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodObject<{
+            display: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            display: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>>]>;
+        user_can_edit: z.ZodOptional<z.ZodBoolean>;
+        admin_only: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+
+    /**
+     * @public
+     */
+    export declare type ValidationError = z.infer<typeof ValidationErrorSchema>;
+
+    declare const ValidationErrorSchema: z.ZodObject<{
+        key: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+
+    export { }