polarity-integration-utils 2.0.8 → 3.1.3

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

@@ -1,4 +1,5 @@
 import Bottleneck from 'bottleneck';
+import { z } from 'zod';
 
 /**
  * API error for REST requests
@@ -18,6 +19,24 @@ 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
  */
@@ -31,6 +50,11 @@ export declare type ConfigRequestProxyOptions = {
     json?: undefined | boolean;
 };
 
+/**
+ * @public
+ */
+export declare type DoLookupResult<TDetails = unknown> = Result<TDetails>[];
+
 /**
  * User options object passed into the integration's `doLookup` method.
  *
@@ -52,17 +76,25 @@ export declare type ConfigRequestProxyOptions = {
  * ```
  * @public
  */
-export declare type DoLookupUserOptions = {
-    [key: string]: PossibleUserOptionValue;
-};
+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 = {
-    display: string;
-    value: string;
-};
+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
@@ -70,41 +102,48 @@ export declare type DropdownUserOptionValue = {
  *
  * @public
  */
-export declare type Entity = {
-    value: string;
-    types: EntityType[];
-    type: EntityType;
-    requestContext: {
-        requestType: 'onDemand';
-        isUserInitiated: boolean;
-    };
-    longitude: number;
-    latitude: number;
-    isURL: boolean;
-    isSHA512: boolean;
-    isSHA256: boolean;
-    isSHA1: boolean;
-    isPrivateIP: boolean;
-    isMD5: boolean;
-    isIPv6: boolean;
-    isIPv4: boolean;
-    isIP: boolean;
-    isHex: boolean;
-    isHash: boolean;
-    isHTMLTag: boolean;
-    isEmail: boolean;
-    isDomain: boolean;
-    hashType: string;
-    displayValue: string;
-    channels: string[];
-    IPType: string;
-};
+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 = StandardEntityType | '*' | 'custom' | `custom.${string}`;
+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
@@ -141,6 +180,39 @@ 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';
 
 /**
@@ -274,6 +346,178 @@ 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>;
+}
+
+/**
+ * @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
  */
@@ -422,7 +666,7 @@ export declare class LibraryUsageError extends IntegrationError {
 /**
  * @public
  */
-export declare type Logger = {
+declare type Logger = {
     child?(arg: unknown): Logger;
     info(...args: unknown[]): void;
     debug(...args: unknown[]): void;
@@ -431,6 +675,8 @@ export declare type Logger = {
     error(...args: unknown[]): void;
     fatal(...args: unknown[]): void;
 };
+export { Logger }
+export { Logger as PolarityLogger }
 
 /**
  * @public
@@ -455,6 +701,52 @@ export declare class NetworkError extends IntegrationError {
  */
 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
@@ -657,7 +949,15 @@ export declare class PolarityRequest {
     /**
      * @public
      */
-    export declare type PossibleUserOptionValue = undefined | string | number | boolean | DropdownUserOptionValue | DropdownUserOptionValue[];
+    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
@@ -687,6 +987,56 @@ export declare class PolarityRequest {
      */
     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.
@@ -821,32 +1171,89 @@ export declare class PolarityRequest {
      * List of supported entity type values
      * @public
      */
-    export declare type StandardEntityType = 'IP' | 'IPv4' | 'IPv4CIDR' | 'IPv6' | 'MAC' | 'MD5' | 'SHA1' | 'SHA256' | 'cve' | 'domain' | 'email' | 'hash' | 'string' | 'url';
+    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 = {
-        integration_id?: string;
-        key: string;
-        value: PossibleUserOptionValue;
-        user_can_edit?: boolean;
-        admin_only?: boolean;
-    };
+    export declare type ValidateOptionsUserOption = z.infer<typeof ValidateOptionsUserOptionSchema>;
 
     /**
      * @public
      */
-    export declare type ValidateOptionsUserOptions = {
-        [key: string]: ValidateOptionsUserOption;
-    };
+    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 = {
-        key: string;
-        message: string;
-    };
+    export declare type ValidationError = z.infer<typeof ValidationErrorSchema>;
+
+    declare const ValidationErrorSchema: z.ZodObject<{
+        key: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
 
     export { }