@mherod/get-cookie 4.3.2 → 4.4.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import * as consola from 'consola';
+import { ConsolaInstance } from 'consola';
 
 /**
  * Schema for cookie specification parameters
@@ -132,8 +133,8 @@ declare const ExportedCookieSchema: z.ZodObject<{
         path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
     }, z.ZodUnknown, "strict"> | undefined;
 }, {
-    name: string;
     value: string;
+    name: string;
     domain: string;
     expiry?: number | Date | "Infinity" | undefined;
     meta?: z.objectInputType<{
@@ -177,6 +178,29 @@ declare const ExportedCookieSchema: z.ZodObject<{
  * ```
  */
 type ExportedCookie = z.infer<typeof ExportedCookieSchema>;
+/**
+ * Schema for raw cookie data from browser stores
+ */
+declare const CookieRowSchema: z.ZodObject<{
+    expiry: z.ZodOptional<z.ZodNumber>;
+    domain: z.ZodEffects<z.ZodString, string, string>;
+    name: z.ZodEffects<z.ZodString, string, string>;
+    value: z.ZodUnion<[z.ZodString, z.ZodType<Buffer<ArrayBufferLike>, z.ZodTypeDef, Buffer<ArrayBufferLike>>]>;
+}, "strict", z.ZodTypeAny, {
+    value: string | Buffer<ArrayBufferLike>;
+    name: string;
+    domain: string;
+    expiry?: number | undefined;
+}, {
+    value: string | Buffer<ArrayBufferLike>;
+    name: string;
+    domain: string;
+    expiry?: number | undefined;
+}>;
+/**
+ * Type definition for raw cookie data
+ */
+type CookieRow = z.infer<typeof CookieRowSchema>;
 /**
  * Schema for cookie render options
  */
@@ -251,8 +275,8 @@ declare const CookieQueryStrategySchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
         }, z.ZodUnknown, "strict"> | undefined;
     }, {
-        name: string;
         value: string;
+        name: string;
         domain: string;
         expiry?: number | Date | "Infinity" | undefined;
         meta?: z.objectInputType<{
@@ -283,8 +307,8 @@ declare const CookieQueryStrategySchema: z.ZodObject<{
 }, {
     browserName: "unknown" | "Chrome" | "Firefox" | "Safari" | "internal";
     queryCookies: (args_0: string, args_1: string, args_2: string | undefined, args_3: boolean | undefined, ...args: unknown[]) => Promise<{
-        name: string;
         value: string;
+        name: string;
         domain: string;
         expiry?: number | Date | "Infinity" | undefined;
         meta?: z.objectInputType<{
@@ -322,31 +346,73 @@ type CookieQueryStrategy = z.infer<typeof CookieQueryStrategySchema>;
 type MultiCookieSpec = CookieSpec | CookieSpec[];
 
 /**
- * Retrieves browser cookies that match the specified cookie name and domain criteria.
- * This function provides a way to search and filter cookies based on given specifications.
- * @param cookieSpec - The cookie specification containing search criteria
- * @param cookieSpec.name - The name of the cookie to search for
- * @param cookieSpec.domain - (optional) The domain to filter cookies by
- * @returns An array of ExportedCookie objects that match the specification
- * @throws Will catch and handle any errors during cookie querying, logging a warning
- * to the console without throwing to the caller
+ * A composite strategy that combines multiple cookie query strategies.
+ * This class implements the CookieQueryStrategy interface and allows querying cookies
+ * from multiple browser-specific strategies simultaneously.
  * @example
  * ```typescript
- * import { getCookie } from "@mherod/get-cookie";
- *
- * // Get all cookies named "sessionId"
- * const cookies = await getCookie({ name: "sessionId" });
- * // Returns: [{ name: "sessionId", value: "abc123", domain: ".example.com", ... }]
- *
- * // Get cookies named "userPref" from specific domain
- * const domainCookies = await getCookie({
- *   name: "userPref",
- *   domain: "example.com"
- * });
- * // Returns: [{ name: "userPref", value: "darkMode", domain: "example.com", ... }]
+ * const strategy = new CompositeCookieQueryStrategy([
+ *   new ChromeCookieQueryStrategy(),
+ *   new FirefoxCookieQueryStrategy(),
+ *   new SafariCookieQueryStrategy()
+ * ]);
+ * const cookies = await strategy.queryCookies('sessionId', 'example.com');
  * ```
  */
-declare function getCookie(cookieSpec: CookieSpec): Promise<ExportedCookie[]>;
+declare class CompositeCookieQueryStrategy implements CookieQueryStrategy {
+    private readonly strategies;
+    private readonly logger;
+    /**
+     * The browser name identifier for this strategy
+     * @remarks Always returns 'internal' as this is a composite strategy
+     */
+    readonly browserName: BrowserName;
+    /**
+     * Creates a new instance of CompositeCookieQueryStrategy
+     * @param strategies - Array of browser-specific strategies to use for querying cookies
+     * @remarks
+     * - Each strategy in the array should implement the CookieQueryStrategy interface
+     * - The order of strategies determines the order of cookie querying
+     * - Failed strategies will be gracefully handled and skipped
+     * @example
+     * ```typescript
+     * const strategy = new CompositeCookieQueryStrategy([
+     *   new ChromeCookieQueryStrategy(),
+     *   new FirefoxCookieQueryStrategy()
+     * ]);
+     * ```
+     */
+    constructor(strategies: CookieQueryStrategy[]);
+    /**
+     * Handles strategy-specific errors and logs them appropriately
+     * @internal
+     * @param error - The error that occurred during strategy execution
+     * @param strategy - The strategy that failed
+     */
+    private handleStrategyError;
+    /**
+     * Queries cookies using all available strategies in parallel
+     * @param name - The name pattern to match cookies against
+     * @param domain - The domain pattern to match cookies against
+     * @param store - The store pattern to match cookies against
+     * @param force - Whether to force operations despite warnings (e.g., locked databases)
+     * @returns Promise resolving to combined array of cookies from all strategies
+     * @remarks
+     * - Failures in individual strategies are logged but don't affect other strategies
+     * - Results are combined from all successful strategy queries
+     * - Empty arrays are returned for failed strategy queries
+     * @example
+     * ```typescript
+     * const strategy = new CompositeCookieQueryStrategy([
+     *   new ChromeCookieQueryStrategy(),
+     *   new FirefoxCookieQueryStrategy()
+     * ]);
+     * const cookies = await strategy.queryCookies('sessionId', 'example.com');
+     * console.log(cookies); // Combined results from all browsers
+     * ```
+     */
+    queryCookies(name: string, domain: string, store?: string, force?: boolean): Promise<ExportedCookie[]>;
+}
 
 /**
  * Base class for cookie query strategies.
@@ -390,38 +456,129 @@ declare abstract class BaseCookieQueryStrategy implements CookieQueryStrategy {
 }
 
 /**
- * Strategy for querying cookies from Chrome browser.
- * This class extends the BaseCookieQueryStrategy and implements Chrome-specific
- * cookie extraction logic.
+ * Create a logger instance with a component tag
+ * @param component - The component name to tag logs with
+ * @returns A logger instance that prefixes all messages with the component tag
  * @example
  * ```typescript
- * const strategy = new ChromeCookieQueryStrategy();
- * const cookies = await strategy.queryCookies('session', 'example.com');
+ * const dbLogger = createTaggedLogger('Database');
+ * dbLogger.info('Connection established');
  * ```
  */
-declare class ChromeCookieQueryStrategy extends BaseCookieQueryStrategy {
+declare function createTaggedLogger(component: string): ConsolaInstance;
+
+/**
+ * Interface for platform-specific browser control operations
+ * Following SOLID principles - Interface Segregation
+ */
+interface PlatformBrowserControl {
     /**
-     * Creates a new instance of ChromeCookieQueryStrategy
+     * Check if the browser is supported on this platform
+     * @param browserName - The name of the browser to check
+     * @returns True if the browser is supported on this platform
      */
-    constructor();
+    isBrowserSupported(browserName: BrowserName): boolean;
     /**
-     * Executes the Chrome-specific query logic
-     * @param name - The name pattern to match cookies against
-     * @param domain - The domain pattern to match cookies against
-     * @param store - Optional path to a specific cookie store file
-     * @param _force - Whether to force operations despite warnings (e.g., locked databases)
-     * @returns A promise that resolves to an array of exported cookies
-     * @protected
-     * @example
-     * ```typescript
-     * // This method is called internally by queryCookies
-     * const cookies = await strategy.queryCookies('session', 'example.com');
-     * console.log(cookies);
-     * ```
+     * Get executable names for a browser on this platform
+     * @param browserName - The name of the browser
+     * @returns Array of executable names for the browser
+     */
+    getBrowserExecutables(browserName: BrowserName): string[];
+    /**
+     * Launch a browser on this platform
+     * @param browserName - The name of the browser to launch
+     * @returns Promise that resolves when the browser is launched
+     * @throws {Error} When the browser is not supported or cannot be launched
+     */
+    launchBrowser(browserName: BrowserName): Promise<void>;
+    /**
+     * Get the platform name
+     * @returns The name of the current platform
+     */
+    getPlatformName(): string;
+    /**
+     * Check if a browser is installed
+     * @param browserName - The name of the browser to check
+     * @returns Promise that resolves to true if the browser is installed
+     */
+    isBrowserInstalled(browserName: BrowserName): Promise<boolean>;
+}
+
+/**
+ * Result of a browser conflict handling operation
+ */
+interface BrowserLockResult {
+    /** Whether the conflict was resolved */
+    resolved: boolean;
+    /** Whether the browser should be relaunched */
+    shouldRelaunch: boolean;
+}
+/**
+ * Shared handler for browser lock/permission issues
+ * Follows DRY principle to avoid duplicating logic across browser strategies
+ * Uses Strategy pattern for platform-specific operations
+ */
+declare class BrowserLockHandler {
+    private readonly logger;
+    private readonly browserName;
+    private readonly platformControl;
+    /**
+     * Creates a new BrowserLockHandler instance
+     * @param logger - Tagged logger instance for this handler
+     * @param browserName - Name of the browser this handler manages
+     * @param platformControl - Optional platform control strategy (for testing)
+     */
+    constructor(logger: ReturnType<typeof createTaggedLogger>, browserName: BrowserName, platformControl?: PlatformBrowserControl);
+    /**
+     * Handle database lock or permission errors
+     * @param error - The error to check
+     * @param file - The file that was locked/inaccessible
+     * @param processes - Running processes for this browser
+     * @param autoClose - Whether to attempt auto-closing the browser
+     * @returns Promise that resolves to lock result
      */
-    protected executeQuery(name: string, domain: string, store?: string, _force?: boolean): Promise<ExportedCookie[]>;
-    private processFile;
-    private processCookie;
+    handleBrowserConflict(error: unknown, file: string, processes: Array<{
+        pid: number;
+        command: string;
+    }>, autoClose?: boolean): Promise<BrowserLockResult>;
+    /**
+     * Check if an error indicates a database lock or permission issue
+     * @param error - The error to check
+     * @returns True if this is a lock-related error
+     */
+    private isLockError;
+    /**
+     * Log detailed file handle information
+     * @param file - The file that was locked
+     * @param processes - Browser processes detected
+     */
+    private logFileHandleInfo;
+    /**
+     * Handle process conflicts and optionally close the browser
+     * @param file - The file that was locked
+     * @param processes - Browser processes detected
+     * @param autoClose - Whether to attempt auto-closing
+     * @returns Promise that resolves to lock result
+     */
+    private handleProcessConflict;
+    /**
+     * Handle detected browser processes
+     * @param file - The file that was locked
+     * @param processes - Browser processes detected
+     * @param autoClose - Whether to attempt auto-closing
+     * @returns Promise that resolves to lock result
+     */
+    private handleBrowserProcesses;
+    /**
+     * Attempt to close the browser gracefully
+     * @returns Promise that resolves to lock result
+     */
+    private attemptBrowserClose;
+    /**
+     * Relaunch browser after successful operation
+     * @returns Promise that resolves when browser is relaunched
+     */
+    relaunchBrowser(): Promise<void>;
 }
 
 /**
@@ -432,31 +589,186 @@ declare class ChromeCookieQueryStrategy extends BaseCookieQueryStrategy {
 /**
  * Supported Chromium-based browsers
  */
-declare const CHROMIUM_BASED_BROWSERS: readonly ["chrome", "chromium", "brave", "edge", "opera", "vivaldi", "whale"];
+declare const CHROMIUM_BASED_BROWSERS: readonly ["chrome", "chromium", "brave", "edge", "arc", "opera", "opera-gx", "vivaldi", "whale"];
+/**
+ * Type representing all supported Chromium-based browsers.
+ * This includes Chrome, Edge, Brave, Arc, Opera, and other Chromium derivatives.
+ */
 type ChromiumBrowser = (typeof CHROMIUM_BASED_BROWSERS)[number];
 
+interface DecryptionContext {
+    file: string;
+    password: string | Buffer;
+    browser: string;
+    metaVersion?: number;
+}
+/**
+ * Base strategy for querying cookies from Chromium-based browsers.
+ * This abstract class provides shared logic for Chrome, Chromium, Brave, Edge, etc.
+ */
+declare abstract class BaseChromiumCookieQueryStrategy extends BaseCookieQueryStrategy {
+    protected lockHandler: BrowserLockHandler;
+    protected browserDisplayName: string;
+    protected browserType: ChromiumBrowser;
+    /**
+     * Creates a new instance of BaseChromiumCookieQueryStrategy
+     * @param strategyName - Name of the strategy for logging
+     * @param browserName - Display name of the browser
+     * @param browserType - The Chromium browser type for password retrieval
+     */
+    constructor(strategyName: string, browserName: string, browserType?: ChromiumBrowser);
+    /**
+     * Batch query cookies for multiple specs
+     * Optimized to execute combined SQL queries per database file
+     * @param specs - Array of cookie specifications
+     * @returns Array of exported cookies
+     */
+    batchQueryCookies(specs: CookieSpec[]): Promise<ExportedCookie[]>;
+    /**
+     * Process a batch of specs for a single cookie file
+     * @param file - Cookie file path
+     * @param specs - Array of cookie specifications
+     * @param password - Decryption password
+     * @returns Array of exported cookies
+     */
+    protected processBatchFile(file: string, specs: CookieSpec[], password: string | Buffer): Promise<ExportedCookie[]>;
+    /**
+     * Get cookie file paths for the browser
+     * @param store - Optional specific store path
+     * @returns Array of cookie file paths
+     */
+    protected abstract getCookieFilePaths(store?: string): string[];
+    /**
+     * Get the browser-specific display name
+     * @returns Browser display name
+     */
+    protected getBrowserName(): string;
+    /**
+     * Executes the Chromium-specific query logic
+     * @param name - The name pattern to match cookies against
+     * @param domain - The domain pattern to match cookies against
+     * @param store - Optional path to a specific cookie store file
+     * @param force - Whether to force operations despite warnings
+     * @returns A promise that resolves to an array of exported cookies
+     */
+    protected executeQuery(name: string, domain: string, store?: string, force?: boolean): Promise<ExportedCookie[]>;
+    /**
+     * Check if the current platform is supported
+     * @returns True if platform is supported
+     */
+    protected isPlatformSupported(): boolean;
+    /**
+     * Get cookie files to process
+     * @param store - Optional specific store path
+     * @returns Array of file paths
+     */
+    protected getCookieFiles(store?: string): string[];
+    /**
+     * Convert error to string message
+     * @param error - The error to convert
+     * @returns Error message string
+     */
+    protected getErrorMessage(error: unknown): string;
+    /**
+     * Process a file with retry logic for lock conflicts
+     * @param file - Cookie file path
+     * @param name - Cookie name pattern
+     * @param domain - Domain pattern
+     * @param password - Decryption password
+     * @param force - Force processing
+     * @returns Array of exported cookies
+     */
+    private processFileWithRetry;
+    /**
+     * Handle file processing errors
+     * @param error - The error that occurred
+     * @param file - File path
+     * @param name - Cookie name pattern
+     * @param domain - Domain pattern
+     * @param force - Whether to force operations
+     * @returns Lock result indicating if resolved and should relaunch
+     */
+    private handleFileError;
+    /**
+     * Retry after browser close
+     * @param file - Cookie file path
+     * @param name - Cookie name pattern
+     * @param domain - Domain pattern
+     * @param password - Decryption password
+     * @param shouldRelaunch - Whether to relaunch browser
+     * @returns Array of exported cookies
+     */
+    private retryAfterBrowserClose;
+    /**
+     * Process a single cookie file
+     * @param file - Cookie file path
+     * @param name - Cookie name pattern
+     * @param domain - Domain pattern
+     * @param password - Decryption password
+     * @returns Array of exported cookies
+     */
+    protected processFile(file: string, name: string, domain: string, password: string | Buffer): Promise<ExportedCookie[]>;
+    /**
+     * Get meta version from Chrome database
+     * @param file - Database file path
+     * @returns Meta version number
+     */
+    protected getMetaVersion(file: string): Promise<number>;
+    /**
+     * Process a single cookie
+     * @param cookie - Cookie row from database
+     * @param context - Decryption context
+     * @returns Exported cookie
+     */
+    protected processCookie(cookie: CookieRow, context: DecryptionContext): Promise<ExportedCookie>;
+}
+
+/**
+ * Strategy for querying cookies from Chrome browser.
+ * This class extends the BaseChromiumCookieQueryStrategy with Chrome-specific logic.
+ * @example
+ * ```typescript
+ * const strategy = new ChromeCookieQueryStrategy();
+ * const cookies = await strategy.queryCookies('session', 'example.com');
+ * ```
+ */
+declare class ChromeCookieQueryStrategy extends BaseChromiumCookieQueryStrategy {
+    private readonly profileName?;
+    /**
+     * Creates a new instance of ChromeCookieQueryStrategy
+     * @param profileName - Optional specific profile name to target
+     */
+    constructor(profileName?: string);
+    /**
+     * Get Chrome-specific cookie file paths
+     * @param store - Optional specific store path
+     * @returns Array of cookie file paths
+     */
+    protected getCookieFilePaths(store?: string): string[];
+}
+
 /**
  * Strategy for querying cookies from Chromium-based browsers (Chrome, Brave, Edge, etc.)
- * This class extends the BaseCookieQueryStrategy and implements Chromium-specific
- * cookie extraction logic that works across multiple browsers.
+ * This class extends the BaseChromiumCookieQueryStrategy with browser-specific path discovery.
+ * @example
+ * ```typescript
+ * const strategy = new ChromiumCookieQueryStrategy('brave');
+ * const cookies = await strategy.queryCookies('session', 'example.com');
+ * ```
  */
-declare class ChromiumCookieQueryStrategy extends BaseCookieQueryStrategy {
-    private browser;
+declare class ChromiumCookieQueryStrategy extends BaseChromiumCookieQueryStrategy {
+    private readonly browser;
     /**
      * Creates a new instance of ChromiumCookieQueryStrategy
      * @param browser - The Chromium-based browser to query (chrome, brave, edge, etc.)
      */
     constructor(browser?: ChromiumBrowser);
     /**
-     * Lists all cookie file paths for the specified browser
+     * Get browser-specific cookie file paths
+     * @param store - Optional specific store path
+     * @returns Array of cookie file paths
      */
-    private listBrowserCookiePaths;
-    /**
-     * Executes the Chromium-specific query logic
-     */
-    protected executeQuery(name: string, domain: string, store?: string, _force?: boolean): Promise<ExportedCookie[]>;
-    private processFile;
-    private processCookie;
+    protected getCookieFilePaths(store?: string): string[];
 }
 
 /**
@@ -474,28 +786,79 @@ declare class ChromiumCookieQueryStrategy extends BaseCookieQueryStrategy {
  * ```
  */
 declare class FirefoxCookieQueryStrategy extends BaseCookieQueryStrategy {
+    private readonly lockHandler;
     /**
      * Creates a new instance of FirefoxCookieQueryStrategy
      */
     constructor();
     /**
-     * Check if an error indicates a database lock and provide helpful advice
-     * @param error - The error to check
-     * @param file - The database file that was locked
-     * @returns Promise that resolves after providing advice
+     * Creates the query parameters for cookie extraction using the new query builder
+     * @param name - The cookie name to search for
+     * @param domain - The domain pattern to match cookies against
+     * @param file - The database file path for metadata
+     * @returns Query configuration object
+     * @private
+     */
+    private createCookieQueryConfig;
+    /**
+     * Handles errors that occur during cookie extraction
+     * @param error - The error that occurred
+     * @param file - The database file being queried
+     * @param force - Whether operations are being forced
+     * @param name - The cookie name being searched
+     * @param domain - The domain being searched
+     * @returns Promise resolving to retry configuration
+     * @private
+     */
+    private handleCookieExtractionError;
+    /**
+     * Logs cookie extraction errors in a consistent format
+     * @param error - The error to log
+     * @param file - The file that failed
+     * @param name - The cookie name
+     * @param domain - The domain
+     * @private
+     */
+    private logExtractError;
+    /**
+     * Performs a retry attempt after browser closure
+     * @param queryConfig - The cookie query configuration
+     * @param shouldRelaunch - Whether to relaunch the browser after success
+     * @returns Promise resolving to extracted cookies
+     * @private
+     */
+    private performRetryAfterClose;
+    /**
+     * Processes a single Firefox cookie file for the given parameters
+     * @param file - The cookie file to process
+     * @param name - The cookie name to search for
+     * @param domain - The domain pattern to match
+     * @param force - Whether to force operations despite warnings
+     * @returns Promise resolving to extracted cookies from this file
+     * @private
+     */
+    private processCookieFile;
+    /**
+     * Execute query using the new SQL utilities
+     * @param queryConfig - Query configuration from createCookieQueryConfig
+     * @param queryConfig.file
+     * @param queryConfig.sql
+     * @param queryConfig.params
+     * @param queryConfig.rowTransform
+     * @returns Promise resolving to exported cookies
      * @private
      */
-    private handleDatabaseLockError;
+    private executeQueryWithNewUtilities;
     /**
      * Executes the Firefox-specific query logic
      * @param name - The name pattern to match cookies against
      * @param domain - The domain pattern to match cookies against
      * @param store - Optional path to a specific cookie store file
-     * @param _force - Whether to force operations despite warnings (e.g., locked databases)
+     * @param force - Whether to force operations despite warnings (e.g., locked databases)
      * @returns A promise that resolves to an array of exported cookies
      * @protected
      */
-    protected executeQuery(name: string, domain: string, store?: string, _force?: boolean): Promise<ExportedCookie[]>;
+    protected executeQuery(name: string, domain: string, store?: string, force?: boolean): Promise<ExportedCookie[]>;
 }
 
 /**
@@ -504,6 +867,7 @@ declare class FirefoxCookieQueryStrategy extends BaseCookieQueryStrategy {
  * cookie extraction logic.
  */
 declare class SafariCookieQueryStrategy extends BaseCookieQueryStrategy {
+    private readonly lockHandler;
     /**
      * Creates a new instance of SafariCookieQueryStrategy
      */
@@ -517,7 +881,7 @@ declare class SafariCookieQueryStrategy extends BaseCookieQueryStrategy {
     /**
      * Formats the domain by removing leading dot if present
      * @param domain - Domain to format
-     * @returns Formatted domain
+     * @returns Formatted domain or empty string if domain is invalid
      */
     private formatDomain;
     /**
@@ -550,88 +914,245 @@ declare class SafariCookieQueryStrategy extends BaseCookieQueryStrategy {
      * @param cookieDbPath - Path to the cookie database
      * @param name - Name of the cookie to find
      * @param domain - Domain to filter cookies by
+     * @param force - Whether to skip interactive prompts
      * @returns Array of exported cookies
      */
     private decodeCookies;
+    /**
+     * Check file permissions and handle permission errors
+     * @param cookieDbPath - Path to the cookie database
+     * @param force - Whether to skip interactive prompts
+     * @returns True if permissions are granted, false otherwise
+     */
+    private checkAndHandlePermissions;
+    /**
+     * Process and filter cookies based on name and domain criteria
+     * @param cookies - Raw cookies from binary file
+     * @param name - Name filter
+     * @param domain - Domain filter
+     * @param cookieDbPath - Path to cookie database for metadata
+     * @returns Processed and filtered cookies
+     */
+    private processCookies;
+    /**
+     * Check if cookie matches the search criteria
+     * @param cookie - Raw cookie object
+     * @param name - Name filter
+     * @param domain - Domain filter
+     * @returns True if cookie matches criteria
+     */
+    private matchesCriteria;
+    /**
+     * Type guard to check if an object is a valid cookie object
+     * @param cookie - Object to check
+     * @returns True if object has expected cookie properties
+     */
+    private isCookieObject;
+    /**
+     * Map raw cookie to ExportedCookie format
+     * @param cookie - Raw cookie object
+     * @param cookieDbPath - Path to cookie database for metadata
+     * @returns Formatted ExportedCookie
+     */
+    private mapToExportedCookie;
+    /**
+     * Handle errors that occur during cookie decoding
+     * @param error - The error that occurred
+     * @param cookieDbPath - Path to the cookie database
+     * @param name - Name filter used
+     * @param domain - Domain filter used
+     * @param force - Whether interactive prompts were skipped
+     * @returns Empty array as fallback
+     */
+    private handleDecodingError;
+    /**
+     * Handle permission-related errors
+     * @param error - The error that occurred
+     * @param cookieDbPath - Path to the cookie database
+     * @param name - Name filter used
+     * @param domain - Domain filter used
+     * @param force - Whether interactive prompts were skipped
+     */
+    private handlePermissionError;
+    /**
+     * Log non-permission errors that occur during decoding
+     * @param error - The error that occurred
+     * @param cookieDbPath - Path to the cookie database
+     * @param name - Name filter used
+     * @param domain - Domain filter used
+     */
+    private logDecodingError;
     /**
      * Executes the Safari-specific query logic
      * @param name - Name of the cookie to find
      * @param domain - Domain to filter cookies by
      * @param store - Optional store path
-     * @param _force - Whether to force operations despite warnings (e.g., locked databases)
+     * @param force - Whether to force operations despite warnings (e.g., locked databases)
      * @returns Array of matching cookies, or empty array if none found
      * @protected
      */
-    protected executeQuery(name: string, domain: string, store?: string, _force?: boolean): Promise<ExportedCookie[]>;
+    protected executeQuery(name: string, domain: string, store?: string, force?: boolean): Promise<ExportedCookie[]>;
+    /**
+     * Validate home directory
+     * @param home - Home directory path
+     * @returns True if valid, false otherwise
+     */
+    private isValidHomeDirectory;
+    /**
+     * Attempt to decode cookies with lock conflict handling
+     * @param cookieDbPath - Path to cookie database
+     * @param name - Normalized cookie name filter
+     * @param domain - Normalized domain filter
+     * @param force - Whether to force operations
+     * @returns Result object with success status and data
+     */
+    private attemptDecodeWithLockHandling;
+    /**
+     * Handle browser lock conflicts
+     * @param error - The error that occurred
+     * @param cookieDbPath - Path to cookie database
+     * @param force - Whether to force operations
+     * @returns Result indicating what action to take next
+     */
+    private handleLockConflict;
+    /**
+     * Check if error indicates a lock conflict
+     * @param error - Error to check
+     * @returns True if this is a lock-related error
+     */
+    private isLockError;
+    /**
+     * Retry cookie extraction after browser was closed
+     * @param cookieDbPath - Path to cookie database
+     * @param name - Cookie name filter
+     * @param domain - Domain filter
+     * @param force - Whether to force operations
+     * @param shouldRelaunch - Whether browser should be relaunched
+     * @returns Cookies or empty array
+     */
+    private retryAfterBrowserClose;
+    /**
+     * Handle failure during retry attempt
+     * @param retryError - Error that occurred during retry
+     * @param cookieDbPath - Path to cookie database
+     * @param shouldRelaunch - Whether browser should be relaunched
+     * @returns Empty array
+     */
+    private handleRetryFailure;
+    /**
+     * Log query errors
+     * @param error - The error that occurred
+     * @param name - Cookie name filter
+     * @param domain - Domain filter
+     */
+    private logQueryError;
 }
 
 /**
- * A composite strategy that combines multiple cookie query strategies.
- * This class implements the CookieQueryStrategy interface and allows querying cookies
- * from multiple browser-specific strategies simultaneously.
+ * Retrieves browser cookies that match the specified cookie name and domain criteria.
+ * This function provides a way to search and filter cookies based on given specifications.
+ * @param cookieSpec - The cookie specification containing search criteria
+ * @param cookieSpec.name - The name of the cookie to search for
+ * @param cookieSpec.domain - (optional) The domain to filter cookies by
+ * @returns An array of ExportedCookie objects that match the specification
+ * @throws Will catch and handle any errors during cookie querying, logging a warning
+ * to the console without throwing to the caller
  * @example
  * ```typescript
- * const strategy = new CompositeCookieQueryStrategy([
- *   new ChromeCookieQueryStrategy(),
- *   new FirefoxCookieQueryStrategy(),
- *   new SafariCookieQueryStrategy()
- * ]);
- * const cookies = await strategy.queryCookies('sessionId', 'example.com');
+ * import { getCookie } from "@mherod/get-cookie";
+ *
+ * // Get all cookies named "sessionId"
+ * const cookies = await getCookie({ name: "sessionId" });
+ * // Returns: [{ name: "sessionId", value: "abc123", domain: ".example.com", ... }]
+ *
+ * // Get cookies named "userPref" from specific domain
+ * const domainCookies = await getCookie({
+ *   name: "userPref",
+ *   domain: "example.com"
+ * });
+ * // Returns: [{ name: "userPref", value: "darkMode", domain: "example.com", ... }]
  * ```
  */
-declare class CompositeCookieQueryStrategy implements CookieQueryStrategy {
-    private strategies;
-    private readonly logger;
+declare function getCookie(cookieSpec: CookieSpec): Promise<ExportedCookie[]>;
+
+/**
+ * Options for batch cookie retrieval
+ */
+interface BatchGetCookiesOptions {
     /**
-     * The browser name identifier for this strategy
-     * @remarks Always returns 'internal' as this is a composite strategy
+     * Whether to deduplicate cookies across all specs
+     * When true, keeps the cookie with the longest value for each unique name+domain combination
+     * @default true
      */
-    readonly browserName: BrowserName;
+    deduplicate?: boolean;
     /**
-     * Creates a new instance of CompositeCookieQueryStrategy
-     * @param strategies - Array of browser-specific strategies to use for querying cookies
-     * @remarks
-     * - Each strategy in the array should implement the CookieQueryStrategy interface
-     * - The order of strategies determines the order of cookie querying
-     * - Failed strategies will be gracefully handled and skipped
-     * @example
-     * ```typescript
-     * const strategy = new CompositeCookieQueryStrategy([
-     *   new ChromeCookieQueryStrategy(),
-     *   new FirefoxCookieQueryStrategy()
-     * ]);
-     * ```
+     * Maximum number of concurrent requests
+     * @default 10
      */
-    constructor(strategies: CookieQueryStrategy[]);
+    concurrency?: number;
     /**
-     * Handles strategy-specific errors and logs them appropriately
-     * @internal
-     * @param error - The error that occurred during strategy execution
-     * @param strategy - The strategy that failed
+     * Whether to continue on errors for individual specs
+     * When true, errors for individual specs won't fail the entire batch
+     * @default true
      */
-    private handleStrategyError;
+    continueOnError?: boolean;
+}
+/**
+ * Result for a single cookie spec in batch operation
+ */
+interface BatchCookieResult {
     /**
-     * Queries cookies using all available strategies in parallel
-     * @param name - The name pattern to match cookies against
-     * @param domain - The domain pattern to match cookies against
-     * @param store - The store pattern to match cookies against
-     * @param force - Whether to force operations despite warnings (e.g., locked databases)
-     * @returns Promise resolving to combined array of cookies from all strategies
-     * @remarks
-     * - Failures in individual strategies are logged but don't affect other strategies
-     * - Results are combined from all successful strategy queries
-     * - Empty arrays are returned for failed strategy queries
-     * @example
-     * ```typescript
-     * const strategy = new CompositeCookieQueryStrategy([
-     *   new ChromeCookieQueryStrategy(),
-     *   new FirefoxCookieQueryStrategy()
-     * ]);
-     * const cookies = await strategy.queryCookies('sessionId', 'example.com');
-     * console.log(cookies); // Combined results from all browsers
-     * ```
+     * The original spec that was queried
      */
-    queryCookies(name: string, domain: string, store?: string, force?: boolean): Promise<ExportedCookie[]>;
+    spec: CookieSpec;
+    /**
+     * The cookies retrieved for this spec
+     */
+    cookies: ExportedCookie[];
+    /**
+     * Error if the query failed (only when continueOnError is true)
+     */
+    error?: Error;
 }
+/**
+ * Retrieves multiple cookie specifications in parallel with intelligent deduplication.
+ * This function efficiently fetches cookies for multiple specifications and can optionally
+ * deduplicate the results to keep only the most valid cookie for each unique name+domain pair.
+ * @param specs - Array of cookie specifications to retrieve
+ * @param options - Options for batch retrieval
+ * @returns Array of exported cookies, optionally deduplicated
+ * @example
+ * ```typescript
+ * import { batchGetCookies } from "@mherod/get-cookie";
+ *
+ * // Fetch multiple cookies in parallel
+ * const cookies = await batchGetCookies([
+ *   { name: "auth", domain: "api.example.com" },
+ *   { name: "session", domain: "example.com" },
+ *   { name: "token", domain: "*.example.com" }
+ * ]);
+ *
+ * // With options
+ * const cookies = await batchGetCookies(
+ *   [
+ *     { name: "auth", domain: "api.example.com" },
+ *     { name: "session", domain: "example.com" }
+ *   ],
+ *   {
+ *     deduplicate: true,  // Keep only the best cookie for each name+domain
+ *     concurrency: 5,     // Limit concurrent requests
+ *     continueOnError: true // Don't fail entire batch on individual errors
+ *   }
+ * );
+ * ```
+ */
+declare function batchGetCookies(specs: CookieSpec[], options?: BatchGetCookiesOptions): Promise<ExportedCookie[]>;
+/**
+ * Retrieves multiple cookie specifications with detailed results for each spec
+ * @param specs - Array of cookie specifications to retrieve
+ * @param options - Options for batch retrieval
+ * @returns Array of batch results with cookies and potential errors
+ */
+declare function batchGetCookiesWithResults(specs: CookieSpec[], options?: Omit<BatchGetCookiesOptions, "deduplicate">): Promise<BatchCookieResult[]>;
 
-export { type BrowserName, ChromeCookieQueryStrategy, ChromiumCookieQueryStrategy, CompositeCookieQueryStrategy, type CookieQueryStrategy, type CookieSpec, type ExportedCookie, FirefoxCookieQueryStrategy, type MultiCookieSpec, type RenderOptions, SafariCookieQueryStrategy, getCookie };
+export { type BatchCookieResult, type BatchGetCookiesOptions, type BrowserName, ChromeCookieQueryStrategy, ChromiumCookieQueryStrategy, CompositeCookieQueryStrategy, type CookieQueryStrategy, type CookieSpec, type ExportedCookie, FirefoxCookieQueryStrategy, type MultiCookieSpec, type RenderOptions, SafariCookieQueryStrategy, batchGetCookies, batchGetCookiesWithResults, getCookie };