@mherod/get-cookie 4.4.2 → 4.5.0

package/dist/index.d.cts

@@ -98,6 +98,7 @@ declare const ExportedCookieSchema: z.ZodObject<{
         secure: z.ZodOptional<z.ZodBoolean>;
         httpOnly: z.ZodOptional<z.ZodBoolean>;
         path: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+        containerId: z.ZodOptional<z.ZodNumber>;
     }, z.core.$catchall<z.ZodUnknown>>>;
 }, z.core.$strict>;
 /**
@@ -270,6 +271,21 @@ declare class CompositeCookieQueryStrategy implements CookieQueryStrategy {
     queryCookies(name: string, domain: string, store?: string, force?: boolean): Promise<ExportedCookie[]>;
 }
 
+/**
+ * Chromium browser configuration and path management
+ * Supports Chrome, Chromium, Brave, Edge, Opera, Vivaldi, and Whale browsers
+ * across Windows, macOS, and Linux platforms
+ */
+/**
+ * Supported Chromium-based browsers
+ */
+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];
+
 /**
  * Base class for cookie query strategies.
  * Provides common functionality and standardized error handling for browser-specific implementations.
@@ -437,21 +453,6 @@ declare class BrowserLockHandler {
     relaunchBrowser(): Promise<void>;
 }
 
-/**
- * Chromium browser configuration and path management
- * Supports Chrome, Chromium, Brave, Edge, Opera, Vivaldi, and Whale browsers
- * across Windows, macOS, and Linux platforms
- */
-/**
- * Supported Chromium-based browsers
- */
-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;
@@ -463,6 +464,13 @@ interface DecryptionContext {
  * This abstract class provides shared logic for Chrome, Chromium, Brave, Edge, etc.
  */
 declare abstract class BaseChromiumCookieQueryStrategy extends BaseCookieQueryStrategy {
+    /**
+     * Maximum number of profile cookie files read concurrently in a single batch
+     * query. Bounds the number of simultaneously open SQLite handles; kept in line
+     * with the DatabaseConnectionManager default pool size (`maxConnections: 5`)
+     * so a full batch fits the pool without forcing it to open extra connections.
+     */
+    private static readonly MAX_CONCURRENT_PROFILE_READS;
     protected lockHandler: BrowserLockHandler;
     protected browserDisplayName: string;
     protected browserType: ChromiumBrowser;
@@ -473,6 +481,12 @@ declare abstract class BaseChromiumCookieQueryStrategy extends BaseCookieQuerySt
      * @param browserType - The Chromium browser type for password retrieval
      */
     constructor(strategyName: string, browserName: string, browserType?: ChromiumBrowser);
+    /**
+     * Returns the SQL browser type for this strategy.
+     * Falls back to "chrome" for Chromium variants not yet in SqlBrowserType
+     * (e.g. vivaldi, whale), which all share Chrome's cookie schema.
+     */
+    private get sqlBrowserType();
     /**
      * Batch query cookies for multiple specs
      * Optimized to execute combined SQL queries per database file
@@ -581,52 +595,98 @@ declare abstract class BaseChromiumCookieQueryStrategy extends BaseCookieQuerySt
 }
 
 /**
- * Strategy for querying cookies from Chrome browser.
- * This class extends the BaseChromiumCookieQueryStrategy with Chrome-specific logic.
+ * Strategy for querying cookies from Chromium-based browsers (Chrome, Brave, Edge, etc.)
+ * This class extends the BaseChromiumCookieQueryStrategy with browser-specific path discovery
+ * and optional profile-name filtering.
  * @example
  * ```typescript
- * const strategy = new ChromeCookieQueryStrategy();
+ * const strategy = new ChromiumCookieQueryStrategy('brave');
+ * const cookies = await strategy.queryCookies('session', 'example.com');
+ *
+ * // With profile filtering
+ * const strategy = new ChromiumCookieQueryStrategy('chrome', 'Work');
  * const cookies = await strategy.queryCookies('session', 'example.com');
  * ```
  */
-declare class ChromeCookieQueryStrategy extends BaseChromiumCookieQueryStrategy {
+declare class ChromiumCookieQueryStrategy extends BaseChromiumCookieQueryStrategy {
+    private readonly browser;
     private readonly profileName?;
     /**
-     * Creates a new instance of ChromeCookieQueryStrategy
+     * Creates a new instance of ChromiumCookieQueryStrategy
+     * @param browser - The Chromium-based browser to query (chrome, brave, edge, etc.)
      * @param profileName - Optional specific profile name to target
      */
-    constructor(profileName?: string);
+    constructor(browser?: ChromiumBrowser, profileName?: string);
     /**
-     * Get Chrome-specific cookie file paths
+     * Get browser-specific cookie file paths, with optional profile filtering
      * @param store - Optional specific store path
      * @returns Array of cookie file paths
      */
     protected getCookieFilePaths(store?: string): string[];
+    /**
+     * Filter cookie file paths to only include those matching the target profile name.
+     * Reads the browser's Local State file to map profile display names to directories.
+     * @param paths - Array of cookie file paths to filter
+     * @returns Filtered array of cookie file paths
+     */
+    private filterByProfileName;
 }
 
 /**
- * Strategy for querying cookies from Chromium-based browsers (Chrome, Brave, Edge, etc.)
- * This class extends the BaseChromiumCookieQueryStrategy with browser-specific path discovery.
+ * Strategy for querying cookies from Chrome browser.
+ * Extends ChromiumCookieQueryStrategy with Chrome as the target browser.
+ * Supports optional profile-name filtering via the profileName constructor parameter.
  * @example
  * ```typescript
- * const strategy = new ChromiumCookieQueryStrategy('brave');
+ * const strategy = new ChromeCookieQueryStrategy();
+ * const cookies = await strategy.queryCookies('session', 'example.com');
+ *
+ * // With profile filtering
+ * const strategy = new ChromeCookieQueryStrategy('Work');
  * const cookies = await strategy.queryCookies('session', 'example.com');
  * ```
  */
-declare class ChromiumCookieQueryStrategy extends BaseChromiumCookieQueryStrategy {
-    private readonly browser;
+declare class ChromeCookieQueryStrategy extends ChromiumCookieQueryStrategy {
     /**
-     * Creates a new instance of ChromiumCookieQueryStrategy
-     * @param browser - The Chromium-based browser to query (chrome, brave, edge, etc.)
+     * Creates a new instance of ChromeCookieQueryStrategy
+     * @param profileName - Optional specific profile name to target
      */
-    constructor(browser?: ChromiumBrowser);
+    constructor(profileName?: string);
+}
+
+/**
+ * Information about a discovered Chromium browser profile.
+ */
+interface ChromiumProfile {
     /**
-     * Get browser-specific cookie file paths
-     * @param store - Optional specific store path
-     * @returns Array of cookie file paths
+     * Display name of the profile (e.g. "Default", "Person 1", "Work")
      */
-    protected getCookieFilePaths(store?: string): string[];
+    name: string;
+    /**
+     * Profile directory name inside the User Data folder (e.g. "Default", "Profile 1")
+     */
+    directory: string;
+    /**
+     * Absolute path to the profile directory
+     */
+    path: string;
+    /**
+     * Associated email or account user name if available (e.g. "user@example.com")
+     */
+    userName?: string;
+    /**
+     * Browser name/type (e.g. "chrome", "edge", "brave")
+     */
+    browser: string;
 }
+/**
+ * Enumerates installed profiles for a Chromium-based browser (or all Chromium-based browsers).
+ *
+ * @param targetBrowser - Optional browser name (e.g. "chrome", "edge", "brave") or path to User Data dir.
+ *                        If omitted, enumerates profiles across all supported Chromium browsers on the current OS.
+ * @returns Array of discovered ChromiumProfile entries
+ */
+declare function getChromiumProfiles(targetBrowser?: string): ChromiumProfile[];
 
 /**
  * Strategy for querying cookies from Firefox browser.
@@ -644,10 +704,14 @@ declare class ChromiumCookieQueryStrategy extends BaseChromiumCookieQueryStrateg
  */
 declare class FirefoxCookieQueryStrategy extends BaseCookieQueryStrategy {
     private readonly lockHandler;
+    private readonly profileName?;
+    private readonly container?;
     /**
      * Creates a new instance of FirefoxCookieQueryStrategy
+     * @param profileName - Optional specific profile name to target (matches Name in profiles.ini)
+     * @param container - Optional container name, ID, or "none" to filter by
      */
-    constructor();
+    constructor(profileName?: string, container?: string | number);
     /**
      * Creates the query parameters for cookie extraction using the new query builder
      * @param name - The cookie name to search for
@@ -725,10 +789,12 @@ declare class FirefoxCookieQueryStrategy extends BaseCookieQueryStrategy {
  */
 declare class SafariCookieQueryStrategy extends BaseCookieQueryStrategy {
     private readonly lockHandler;
+    private readonly profileName?;
     /**
      * Creates a new instance of SafariCookieQueryStrategy
+     * @param profileName - Ignored; Safari does not support profile filtering
      */
-    constructor();
+    constructor(profileName?: string);
     /**
      * Gets the path to Safari's cookie database
      * @param home - The user's home directory
@@ -1012,4 +1078,4 @@ declare function batchGetCookies(specs: CookieSpec[], options?: BatchGetCookiesO
  */
 declare function batchGetCookiesWithResults(specs: CookieSpec[], options?: Omit<BatchGetCookiesOptions, "deduplicate">): Promise<BatchCookieResult[]>;
 
-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 };
+export { type BatchCookieResult, type BatchGetCookiesOptions, type BrowserName, ChromeCookieQueryStrategy, ChromiumCookieQueryStrategy, type ChromiumProfile, CompositeCookieQueryStrategy, type CookieQueryStrategy, type CookieSpec, type ExportedCookie, FirefoxCookieQueryStrategy, type MultiCookieSpec, type RenderOptions, SafariCookieQueryStrategy, batchGetCookies, batchGetCookiesWithResults, getChromiumProfiles, getCookie };

package/dist/index.d.ts

@@ -98,6 +98,7 @@ declare const ExportedCookieSchema: z.ZodObject<{
         secure: z.ZodOptional<z.ZodBoolean>;
         httpOnly: z.ZodOptional<z.ZodBoolean>;
         path: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+        containerId: z.ZodOptional<z.ZodNumber>;
     }, z.core.$catchall<z.ZodUnknown>>>;
 }, z.core.$strict>;
 /**
@@ -270,6 +271,21 @@ declare class CompositeCookieQueryStrategy implements CookieQueryStrategy {
     queryCookies(name: string, domain: string, store?: string, force?: boolean): Promise<ExportedCookie[]>;
 }
 
+/**
+ * Chromium browser configuration and path management
+ * Supports Chrome, Chromium, Brave, Edge, Opera, Vivaldi, and Whale browsers
+ * across Windows, macOS, and Linux platforms
+ */
+/**
+ * Supported Chromium-based browsers
+ */
+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];
+
 /**
  * Base class for cookie query strategies.
  * Provides common functionality and standardized error handling for browser-specific implementations.
@@ -437,21 +453,6 @@ declare class BrowserLockHandler {
     relaunchBrowser(): Promise<void>;
 }
 
-/**
- * Chromium browser configuration and path management
- * Supports Chrome, Chromium, Brave, Edge, Opera, Vivaldi, and Whale browsers
- * across Windows, macOS, and Linux platforms
- */
-/**
- * Supported Chromium-based browsers
- */
-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;
@@ -463,6 +464,13 @@ interface DecryptionContext {
  * This abstract class provides shared logic for Chrome, Chromium, Brave, Edge, etc.
  */
 declare abstract class BaseChromiumCookieQueryStrategy extends BaseCookieQueryStrategy {
+    /**
+     * Maximum number of profile cookie files read concurrently in a single batch
+     * query. Bounds the number of simultaneously open SQLite handles; kept in line
+     * with the DatabaseConnectionManager default pool size (`maxConnections: 5`)
+     * so a full batch fits the pool without forcing it to open extra connections.
+     */
+    private static readonly MAX_CONCURRENT_PROFILE_READS;
     protected lockHandler: BrowserLockHandler;
     protected browserDisplayName: string;
     protected browserType: ChromiumBrowser;
@@ -473,6 +481,12 @@ declare abstract class BaseChromiumCookieQueryStrategy extends BaseCookieQuerySt
      * @param browserType - The Chromium browser type for password retrieval
      */
     constructor(strategyName: string, browserName: string, browserType?: ChromiumBrowser);
+    /**
+     * Returns the SQL browser type for this strategy.
+     * Falls back to "chrome" for Chromium variants not yet in SqlBrowserType
+     * (e.g. vivaldi, whale), which all share Chrome's cookie schema.
+     */
+    private get sqlBrowserType();
     /**
      * Batch query cookies for multiple specs
      * Optimized to execute combined SQL queries per database file
@@ -581,52 +595,98 @@ declare abstract class BaseChromiumCookieQueryStrategy extends BaseCookieQuerySt
 }
 
 /**
- * Strategy for querying cookies from Chrome browser.
- * This class extends the BaseChromiumCookieQueryStrategy with Chrome-specific logic.
+ * Strategy for querying cookies from Chromium-based browsers (Chrome, Brave, Edge, etc.)
+ * This class extends the BaseChromiumCookieQueryStrategy with browser-specific path discovery
+ * and optional profile-name filtering.
  * @example
  * ```typescript
- * const strategy = new ChromeCookieQueryStrategy();
+ * const strategy = new ChromiumCookieQueryStrategy('brave');
+ * const cookies = await strategy.queryCookies('session', 'example.com');
+ *
+ * // With profile filtering
+ * const strategy = new ChromiumCookieQueryStrategy('chrome', 'Work');
  * const cookies = await strategy.queryCookies('session', 'example.com');
  * ```
  */
-declare class ChromeCookieQueryStrategy extends BaseChromiumCookieQueryStrategy {
+declare class ChromiumCookieQueryStrategy extends BaseChromiumCookieQueryStrategy {
+    private readonly browser;
     private readonly profileName?;
     /**
-     * Creates a new instance of ChromeCookieQueryStrategy
+     * Creates a new instance of ChromiumCookieQueryStrategy
+     * @param browser - The Chromium-based browser to query (chrome, brave, edge, etc.)
      * @param profileName - Optional specific profile name to target
      */
-    constructor(profileName?: string);
+    constructor(browser?: ChromiumBrowser, profileName?: string);
     /**
-     * Get Chrome-specific cookie file paths
+     * Get browser-specific cookie file paths, with optional profile filtering
      * @param store - Optional specific store path
      * @returns Array of cookie file paths
      */
     protected getCookieFilePaths(store?: string): string[];
+    /**
+     * Filter cookie file paths to only include those matching the target profile name.
+     * Reads the browser's Local State file to map profile display names to directories.
+     * @param paths - Array of cookie file paths to filter
+     * @returns Filtered array of cookie file paths
+     */
+    private filterByProfileName;
 }
 
 /**
- * Strategy for querying cookies from Chromium-based browsers (Chrome, Brave, Edge, etc.)
- * This class extends the BaseChromiumCookieQueryStrategy with browser-specific path discovery.
+ * Strategy for querying cookies from Chrome browser.
+ * Extends ChromiumCookieQueryStrategy with Chrome as the target browser.
+ * Supports optional profile-name filtering via the profileName constructor parameter.
  * @example
  * ```typescript
- * const strategy = new ChromiumCookieQueryStrategy('brave');
+ * const strategy = new ChromeCookieQueryStrategy();
+ * const cookies = await strategy.queryCookies('session', 'example.com');
+ *
+ * // With profile filtering
+ * const strategy = new ChromeCookieQueryStrategy('Work');
  * const cookies = await strategy.queryCookies('session', 'example.com');
  * ```
  */
-declare class ChromiumCookieQueryStrategy extends BaseChromiumCookieQueryStrategy {
-    private readonly browser;
+declare class ChromeCookieQueryStrategy extends ChromiumCookieQueryStrategy {
     /**
-     * Creates a new instance of ChromiumCookieQueryStrategy
-     * @param browser - The Chromium-based browser to query (chrome, brave, edge, etc.)
+     * Creates a new instance of ChromeCookieQueryStrategy
+     * @param profileName - Optional specific profile name to target
      */
-    constructor(browser?: ChromiumBrowser);
+    constructor(profileName?: string);
+}
+
+/**
+ * Information about a discovered Chromium browser profile.
+ */
+interface ChromiumProfile {
     /**
-     * Get browser-specific cookie file paths
-     * @param store - Optional specific store path
-     * @returns Array of cookie file paths
+     * Display name of the profile (e.g. "Default", "Person 1", "Work")
      */
-    protected getCookieFilePaths(store?: string): string[];
+    name: string;
+    /**
+     * Profile directory name inside the User Data folder (e.g. "Default", "Profile 1")
+     */
+    directory: string;
+    /**
+     * Absolute path to the profile directory
+     */
+    path: string;
+    /**
+     * Associated email or account user name if available (e.g. "user@example.com")
+     */
+    userName?: string;
+    /**
+     * Browser name/type (e.g. "chrome", "edge", "brave")
+     */
+    browser: string;
 }
+/**
+ * Enumerates installed profiles for a Chromium-based browser (or all Chromium-based browsers).
+ *
+ * @param targetBrowser - Optional browser name (e.g. "chrome", "edge", "brave") or path to User Data dir.
+ *                        If omitted, enumerates profiles across all supported Chromium browsers on the current OS.
+ * @returns Array of discovered ChromiumProfile entries
+ */
+declare function getChromiumProfiles(targetBrowser?: string): ChromiumProfile[];
 
 /**
  * Strategy for querying cookies from Firefox browser.
@@ -644,10 +704,14 @@ declare class ChromiumCookieQueryStrategy extends BaseChromiumCookieQueryStrateg
  */
 declare class FirefoxCookieQueryStrategy extends BaseCookieQueryStrategy {
     private readonly lockHandler;
+    private readonly profileName?;
+    private readonly container?;
     /**
      * Creates a new instance of FirefoxCookieQueryStrategy
+     * @param profileName - Optional specific profile name to target (matches Name in profiles.ini)
+     * @param container - Optional container name, ID, or "none" to filter by
      */
-    constructor();
+    constructor(profileName?: string, container?: string | number);
     /**
      * Creates the query parameters for cookie extraction using the new query builder
      * @param name - The cookie name to search for
@@ -725,10 +789,12 @@ declare class FirefoxCookieQueryStrategy extends BaseCookieQueryStrategy {
  */
 declare class SafariCookieQueryStrategy extends BaseCookieQueryStrategy {
     private readonly lockHandler;
+    private readonly profileName?;
     /**
      * Creates a new instance of SafariCookieQueryStrategy
+     * @param profileName - Ignored; Safari does not support profile filtering
      */
-    constructor();
+    constructor(profileName?: string);
     /**
      * Gets the path to Safari's cookie database
      * @param home - The user's home directory
@@ -1012,4 +1078,4 @@ declare function batchGetCookies(specs: CookieSpec[], options?: BatchGetCookiesO
  */
 declare function batchGetCookiesWithResults(specs: CookieSpec[], options?: Omit<BatchGetCookiesOptions, "deduplicate">): Promise<BatchCookieResult[]>;
 
-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 };
+export { type BatchCookieResult, type BatchGetCookiesOptions, type BrowserName, ChromeCookieQueryStrategy, ChromiumCookieQueryStrategy, type ChromiumProfile, CompositeCookieQueryStrategy, type CookieQueryStrategy, type CookieSpec, type ExportedCookie, FirefoxCookieQueryStrategy, type MultiCookieSpec, type RenderOptions, SafariCookieQueryStrategy, batchGetCookies, batchGetCookiesWithResults, getChromiumProfiles, getCookie };