polarity-integration-utils 3.1.7 → 4.0.0

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

@@ -1,5 +1,19 @@
-import Bottleneck from 'bottleneck';
-import { z } from 'zod';
+import type { DoLookupUserOptions } from '@polarityio/integration-types';
+import type { Entity } from '@polarityio/integration-types';
+import type { EntityType } from '@polarityio/integration-types';
+import type { IntegrationContext } from '@polarityio/integration-types';
+import type { Logger } from '@polarityio/integration-types';
+
+/**
+ * Hook that runs after a successful HTTP response. Each hook receives the output
+ * of the previous hook, allowing the response to be modified in a chain.
+ *
+ * Typically used to extract specific fields from the response body or to
+ * transform the response into a more useful shape.
+ *
+ * @public
+ */
+export declare type AfterResponseHook = (response: HttpRequestResponse, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<HttpRequestResponse>;
 
 /**
  * API error for REST requests
@@ -20,22 +34,15 @@ export declare class AuthRequestError extends IntegrationError {
 }
 
 /**
- * Cache operation options
- */
-export declare interface CacheOptions {
-    /** Time-to-live in seconds. If not specified, uses default TTL */
-    ttl?: number;
-}
-
-/**
+ * Hook that runs before an HTTP request is made. Each hook receives the output
+ * of the previous hook, allowing request options to be modified in a chain.
+ *
+ * Typically used for adding authentication headers or conditionally modifying
+ * request options based on user options.
+ *
  * @public
  */
-export declare type Channel = z.infer<typeof ChannelSchema>;
-
-declare const ChannelSchema: z.ZodObject<{
-    channel_name: z.ZodString;
-    id: z.ZodNumber;
-}, z.core.$strip>;
+export declare type BeforeRequestHook = (requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<HttpRequestOptions>;
 
 /**
  * @public
@@ -51,110 +58,60 @@ export declare type ConfigRequestProxyOptions = {
 };
 
 /**
- * @public
- */
-export declare type DoLookupResult<TDetails = unknown> = Result<TDetails>[];
-
-/**
- * User options object passed into the integration's `doLookup` method.
+ * Creates a mock `Entity` for use in tests.
  *
- * @example
- * Example of the user options object passed into `doLookup`
- * ```js
- * function doLookup(entities, options, cb){
- *   // options here is of type DoLookupUserOptions
- * }
- * ```
+ * 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
- * 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"
- * }
+ * ```typescript
+ * const ip = createEntity('IPv4', '8.8.8.8');
+ * const domain = createEntity('domain', 'example.com');
  * ```
- * @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>>]>>;
+export declare const createEntity: (type: EntityType, value: string) => Entity;
 
 /**
- * @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.
+ * Creates a mock `IntegrationContext`
+ * with stubbed logger, cache, and polling methods.
  *
- * @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
+ * 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 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}`>]>;
+export declare const createMockIntegrationContext: (createMockFn?: MockFnFactory) => IntegrationContext;
 
 /**
+ * Custom entity type definition for config.json
  * @public
  */
-declare interface Error_2 {
-    name: string;
-    message: string;
-    stack?: string;
-    code?: number | string;
+export declare interface CustomType {
+    type?: 'custom';
+    name?: string;
+    description?: string;
+    key: string;
+    regex: string;
+    editable?: boolean;
+    enabled?: boolean;
 }
-export { Error_2 as Error }
 
 /**
  * @public
@@ -180,39 +137,6 @@ export declare type ErrorMeta = {
  */
 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';
 
 /**
@@ -346,176 +270,37 @@ export declare type HttpRequestResponse = {
     [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>;
-}
-
 /**
+ * Integration config.json type
  * @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;
+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[];
 }
 
 /**
@@ -535,26 +320,26 @@ export declare class IntegrationError extends Error {
     /**
      * a meta object containing non-standard meta-information about the error.
      */
-    readonly meta: ErrorMeta;
+    readonly meta?: ErrorMeta;
     /**
      * The HTTP status code applicable to this error, expressed as a string value.
      */
-    readonly status: string;
+    readonly status?: string;
     /**
      *  an application-specific error code, expressed as a string value.
      */
-    readonly code: string;
+    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.
+     * this property is used to pass through a related Error instance but can be any value.
      */
-    readonly cause: Error_2;
+    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;
+    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
@@ -594,9 +379,9 @@ export declare interface IntegrationErrorProperties {
     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.
+     * this property is used to pass through a related Error instance but can be any value.
      */
-    cause?: Error_2;
+    cause?: unknown;
     /**
      * The HTTP status code applicable to this error, expressed as a string value.
      */
@@ -631,6 +416,46 @@ export declare interface IntegrationErrorProperties {
     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
  */
@@ -664,19 +489,14 @@ export declare class LibraryUsageError extends IntegrationError {
 }
 
 /**
+ * Minimal interface for a rate limiter compatible with PolarityRequest.
+ * The Polarity server provides a Bottleneck instance that satisfies this interface.
+ *
  * @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 }
+export declare interface Limiter {
+    schedule<T>(fn: (...args: unknown[]) => PromiseLike<T>, ...args: unknown[]): Promise<T>;
+}
 
 /**
  * @public
@@ -685,6 +505,25 @@ 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
@@ -696,68 +535,43 @@ export declare class NetworkError extends IntegrationError {
 }
 
 /**
+ * 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
- * @param error - Error instance to parse into a plain old javascript object
  */
-export declare const parseErrorToReadableJson: (error: Error_2) => any;
+export declare type OnApiErrorHook = (error: ApiRequestError, response: HttpRequestResponse, requestOptions: HttpRequestOptions, userOptions: DoLookupUserOptions) => Promise<void>;
 
 /**
- * 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
+ * Hook that runs when a network error or rate-limiting error occurs during a request.
  *
- * 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
+ * If all registered hooks return without throwing, the error is suppressed.
+ * To propagate or replace the error, throw from within the hook.
  *
- * @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
- *   }
- * }
- * ```
+ * @public
  */
-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;
-}
+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;
 
 /**
  * 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
@@ -807,49 +621,20 @@ export declare class PolarityRequest {
     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.
+     * 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.
      */
-    postprocessRequestSuccess: PostprocessRequestSuccess;
+    limiter: Limiter | null;
     /**
-     * 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).
+     * 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.
      *
-     * @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.
+     * @see {@link PolarityRequestHooks} for hook type details.
      */
-    postprocessRequestFailure: PostprocessRequestFailure;
-    get throttlingOptions(): Bottleneck.ConstructorOptions;
-    set throttlingOptions(throttlingOptions: Bottleneck.ConstructorOptions);
+    readonly hooks: Required<PolarityRequestHooks>;
     constructor(options?: PolarityRequestOptions);
     private configFieldIsValid;
     /**
@@ -858,17 +643,18 @@ export declare class PolarityRequest {
      * @param requestOptions - request options used to make the HTTP request
      * @returns The HTTP response
      */
-    run(requestOptions: HttpRequestOptions): Promise<HttpRequestResponse> | never;
+    run(requestOptions: HttpRequestOptions): Promise<HttpRequestResponse | undefined> | never;
     /**
-     * Checks whether the HTTP response is an API error and throws an ApiRequestError if it is.
+     * 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 ApiRequestError}
-         * Throws an error if the response indicates an API error.
+     * @throws {@link LibraryUsageError}
+         * Throws if the `isApiError` function returns an invalid result.
          */
-     private maybeThrowApiRequestError;
+     private detectApiError;
      /**
       * Returns true if the `httpStatusCode` is not one of the rounded HTTP status codes
       * specified in the PolarityRequest `roundedSuccessStatusCodes` property.
@@ -924,10 +710,44 @@ export declare class PolarityRequest {
       * `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.
+      * @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[]>;
+     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[];
     }
 
     /**
@@ -940,102 +760,19 @@ export declare class PolarityRequest {
         httpResponseErrorProperties?: string[];
         httpResponseErrorMessageProperties?: string[];
         requestOptionsToSanitize?: string[];
-        preprocessRequestOptions?: PreprocessRequestOptions;
-        postprocessRequestSuccess?: PostprocessRequestSuccess;
-        postprocessRequestFailure?: PostprocessRequestFailure;
-        throttlingOptions?: Bottleneck.ConstructorOptions;
+        hooks?: PolarityRequestHooks;
+        limiter?: Limiter;
     }
 
     /**
      * @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>;
+    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
@@ -1091,6 +828,15 @@ export declare class PolarityRequest {
      */
     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
      */
@@ -1132,9 +878,9 @@ export declare class PolarityRequest {
         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.
+         * this property is used to pass through a related Error instance but can be any value.
          */
-        cause?: Error_2;
+        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
@@ -1168,92 +914,16 @@ export declare class PolarityRequest {
     export declare const setLogger: (logger: Logger) => void;
 
     /**
-     * List of supported entity type values
+     * View component reference in config.json
      * @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>;
+    export declare interface ViewComponent {
+        component: {
+            file: string;
+        };
+        template: {
+            file: string;
+        };
     }
 
-    /**
-     * @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 { }