@mherod/get-cookie 4.2.0 → 4.3.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import * as consola from 'consola';
 
 /**
  * Schema for cookie specification parameters
@@ -12,9 +13,9 @@ import { z } from 'zod';
  * };
  * const result = CookieSpecSchema.safeParse(spec);
  * if (result.success) {
- *   console.log('Valid cookie spec:', result.data);
+ *   logger.info('Valid cookie spec:', result.data);
  * } else {
- *   console.error('Invalid cookie spec:', result.error);
+ *   logger.error('Invalid cookie spec:', result.error);
  * }
  *
  * // Invalid spec (empty name)
@@ -77,9 +78,9 @@ type CookieSpec = z.infer<typeof CookieSpecSchema>;
  * };
  * const result = ExportedCookieSchema.safeParse(cookie);
  * if (result.success) {
- *   console.log('Valid cookie:', result.data);
+ *   logger.info('Valid cookie:', result.data);
  * } else {
- *   console.error('Invalid cookie:', result.error);
+ *   logger.error('Invalid cookie:', result.error);
  * }
  *
  * // Cookie with infinite expiry
@@ -209,7 +210,7 @@ type BrowserName = z.infer<typeof BrowserNameSchema>;
  */
 declare const CookieQueryStrategySchema: z.ZodObject<{
     browserName: z.ZodEnum<["Chrome", "Firefox", "Safari", "internal", "unknown"]>;
-    queryCookies: z.ZodFunction<z.ZodTuple<[z.ZodString, z.ZodString], z.ZodUnknown>, z.ZodPromise<z.ZodArray<z.ZodObject<{
+    queryCookies: z.ZodFunction<z.ZodTuple<[z.ZodString, z.ZodString, z.ZodOptional<z.ZodString>, z.ZodOptional<z.ZodBoolean>], z.ZodUnknown>, z.ZodPromise<z.ZodArray<z.ZodObject<{
         domain: z.ZodEffects<z.ZodString, string, string>;
         name: z.ZodEffects<z.ZodString, string, string>;
         value: z.ZodPipeline<z.ZodEffects<z.ZodString, unknown, string>, z.ZodAny>;
@@ -265,7 +266,7 @@ declare const CookieQueryStrategySchema: z.ZodObject<{
     }>, "many">>>;
 }, "strict", z.ZodTypeAny, {
     browserName: "unknown" | "Chrome" | "Firefox" | "Safari" | "internal";
-    queryCookies: (args_0: string, args_1: string, ...args: unknown[]) => Promise<{
+    queryCookies: (args_0: string, args_1: string, args_2: string | undefined, args_3: boolean | undefined, ...args: unknown[]) => Promise<{
         name: string;
         domain: string;
         value?: any;
@@ -281,7 +282,7 @@ declare const CookieQueryStrategySchema: z.ZodObject<{
     }[]>;
 }, {
     browserName: "unknown" | "Chrome" | "Firefox" | "Safari" | "internal";
-    queryCookies: (args_0: string, args_1: string, ...args: unknown[]) => Promise<{
+    queryCookies: (args_0: string, args_1: string, args_2: string | undefined, args_3: boolean | undefined, ...args: unknown[]) => Promise<{
         name: string;
         value: string;
         domain: string;
@@ -348,96 +349,289 @@ type MultiCookieSpec = CookieSpec | CookieSpec[];
 declare function getCookie(cookieSpec: CookieSpec): Promise<ExportedCookie[]>;
 
 /**
- * Retrieves cookies from Chrome browser storage that match the specified criteria.
- * @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
- * import { getChromeCookie } from "@mherod/get-cookie";
- *
- * // Get all cookies named "sessionId" from Chrome
- * const cookies = await getChromeCookie({ name: "sessionId" });
- *
- * // Get cookies named "userPref" from specific domain in Chrome
- * const domainCookies = await getChromeCookie({
- *   name: "userPref",
- *   domain: "example.com"
- * });
- * ```
+ * Base class for cookie query strategies.
+ * Provides common functionality and standardized error handling for browser-specific implementations.
+ * @implements {CookieQueryStrategy}
+ * @abstract
  */
-declare function getChromeCookie(cookieSpec: CookieSpec): Promise<ExportedCookie[]>;
+declare abstract class BaseCookieQueryStrategy implements CookieQueryStrategy {
+    readonly browserName: BrowserName;
+    /**
+     * Logger instance for this strategy
+     * @protected
+     */
+    protected readonly logger: consola.ConsolaInstance;
+    /**
+     * Creates a new instance of BaseCookieQueryStrategy
+     * @param strategyName - The name of the strategy for logging purposes
+     * @param browserName - The name of the browser this strategy is for
+     */
+    constructor(strategyName: string, browserName: BrowserName);
+    /**
+     * Queries cookies from the browser's cookie store
+     * @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
+     */
+    queryCookies(name: string, domain: string, store?: string, force?: boolean): Promise<ExportedCookie[]>;
+    /**
+     * Executes the browser-specific query logic
+     * @abstract
+     * @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
+     */
+    protected abstract executeQuery(name: string, domain: string, store?: string, force?: boolean): Promise<ExportedCookie[]>;
+}
 
 /**
- * Retrieves cookies from Firefox browser storage that match the specified criteria.
- * @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
+ * Strategy for querying cookies from Chrome browser.
+ * This class extends the BaseCookieQueryStrategy and implements Chrome-specific
+ * cookie extraction logic.
  * @example
  * ```typescript
- * import { getFirefoxCookie } from "@mherod/get-cookie";
- *
- * // Get all cookies named "sessionId" from Firefox
- * const cookies = await getFirefoxCookie({ name: "sessionId" });
- *
- * // Get cookies named "userPref" from specific domain in Firefox
- * const domainCookies = await getFirefoxCookie({
- *   name: "userPref",
- *   domain: "example.com"
- * });
+ * const strategy = new ChromeCookieQueryStrategy();
+ * const cookies = await strategy.queryCookies('session', 'example.com');
  * ```
  */
-declare function getFirefoxCookie(cookieSpec: CookieSpec): Promise<ExportedCookie[]>;
+declare class ChromeCookieQueryStrategy extends BaseCookieQueryStrategy {
+    /**
+     * Creates a new instance of ChromeCookieQueryStrategy
+     */
+    constructor();
+    /**
+     * 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);
+     * ```
+     */
+    protected executeQuery(name: string, domain: string, store?: string, _force?: boolean): Promise<ExportedCookie[]>;
+    private processFile;
+    private processCookie;
+}
 
 /**
- * Retrieves and renders cookies in a grouped format based on their source files.
- * @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
- * @param options - Options for rendering the cookies
- * @param options.showFilePaths - Whether to include file paths in the output
- * @param options.separator - Custom separator for cookie values
- * @returns An array of strings, each representing a group of cookies from a source file
+ * 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", "opera", "vivaldi", "whale"];
+type ChromiumBrowser = (typeof CHROMIUM_BASED_BROWSERS)[number];
+
+/**
+ * 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.
+ */
+declare class ChromiumCookieQueryStrategy extends BaseCookieQueryStrategy {
+    private 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
+     */
+    private listBrowserCookiePaths;
+    /**
+     * Executes the Chromium-specific query logic
+     */
+    protected executeQuery(name: string, domain: string, store?: string, _force?: boolean): Promise<ExportedCookie[]>;
+    private processFile;
+    private processCookie;
+}
+
+/**
+ * Strategy for querying cookies from Firefox browser.
+ * This class extends the BaseCookieQueryStrategy and implements Firefox-specific
+ * cookie extraction logic. It searches for cookie databases in standard Firefox
+ * profile locations and extracts cookies matching the specified name and domain.
  * @example
  * ```typescript
- * // Basic usage - get all cookies named "sessionId" grouped by source file
- * const cookies = await getGroupedRenderedCookies({ name: "sessionId" });
+ * import { FirefoxCookieQueryStrategy } from './FirefoxCookieQueryStrategy';
  *
- * // Get cookies with domain filter and custom rendering options
- * const domainCookies = await getGroupedRenderedCookies(
- *   {
- *     name: "userPref",
- *     domain: "example.com"
- *   },
- *   {
- *     showFilePaths: true,
- *     separator: " | "
- *   }
- * );
+ * const strategy = new FirefoxCookieQueryStrategy();
+ * const cookies = await strategy.queryCookies('sessionid', 'example.com');
+ * console.log(cookies);
  * ```
  */
-declare function getGroupedRenderedCookies(cookieSpec: CookieSpec, options?: Omit<RenderOptions, "format">): Promise<string[]>;
+declare class FirefoxCookieQueryStrategy extends BaseCookieQueryStrategy {
+    /**
+     * 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
+     * @private
+     */
+    private handleDatabaseLockError;
+    /**
+     * 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)
+     * @returns A promise that resolves to an array of exported cookies
+     * @protected
+     */
+    protected executeQuery(name: string, domain: string, store?: string, _force?: boolean): Promise<ExportedCookie[]>;
+}
+
+/**
+ * Strategy for querying cookies from Safari browser.
+ * This class extends the BaseCookieQueryStrategy and implements Safari-specific
+ * cookie extraction logic.
+ */
+declare class SafariCookieQueryStrategy extends BaseCookieQueryStrategy {
+    /**
+     * Creates a new instance of SafariCookieQueryStrategy
+     */
+    constructor();
+    /**
+     * Gets the path to Safari's cookie database
+     * @param home - The user's home directory
+     * @returns Path to the cookie database
+     */
+    private getCookieDbPath;
+    /**
+     * Formats the domain by removing leading dot if present
+     * @param domain - Domain to format
+     * @returns Formatted domain
+     */
+    private formatDomain;
+    /**
+     * Formats the expiry date
+     * @param expiry - Expiry timestamp (Unix epoch seconds)
+     * @returns Formatted expiry date or "Infinity"
+     */
+    private formatExpiry;
+    /**
+     * Checks if a flag bit is set
+     * @param flags - The flags value
+     * @param bit - The bit to check
+     * @returns True if the bit is set, false otherwise
+     */
+    private isFlagSet;
+    /**
+     * Formats the creation timestamp
+     * @param creation - Creation timestamp (Unix epoch seconds)
+     * @returns Formatted creation timestamp in milliseconds or undefined
+     */
+    private formatCreation;
+    /**
+     * Processes a cookie value to ensure it's a string
+     * @param value - The cookie value to process
+     * @returns The processed value as a string
+     */
+    private processValue;
+    /**
+     * Decodes cookies from Safari's binary cookie file
+     * @param cookieDbPath - Path to the cookie database
+     * @param name - Name of the cookie to find
+     * @param domain - Domain to filter cookies by
+     * @returns Array of exported cookies
+     */
+    private decodeCookies;
+    /**
+     * 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)
+     * @returns Array of matching cookies, or empty array if none found
+     * @protected
+     */
+    protected executeQuery(name: string, domain: string, store?: string, _force?: boolean): Promise<ExportedCookie[]>;
+}
 
 /**
- * Retrieves and renders cookies in a merged format
- * @param cookieSpec - The cookie specification to query
- * @param options - Optional rendering options
- * @returns Promise resolving to rendered cookie string
+ * 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
- * const cookieString = await getMergedRenderedCookies(
- *   { name: 'session', domain: 'example.com' },
- *   { separator: '; ' }
- * );
- * console.log(cookieString); // "session=abc123; auth=xyz789"
+ * const strategy = new CompositeCookieQueryStrategy([
+ *   new ChromeCookieQueryStrategy(),
+ *   new FirefoxCookieQueryStrategy(),
+ *   new SafariCookieQueryStrategy()
+ * ]);
+ * const cookies = await strategy.queryCookies('sessionId', 'example.com');
  * ```
  */
-declare function getMergedRenderedCookies(cookieSpec: CookieSpec, options?: Omit<RenderOptions, "format">): Promise<string>;
+declare class CompositeCookieQueryStrategy implements CookieQueryStrategy {
+    private 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[]>;
+}
 
-export { type BrowserName, type CookieQueryStrategy, type CookieSpec, type ExportedCookie, type MultiCookieSpec, type RenderOptions, getChromeCookie, getCookie, getFirefoxCookie, getGroupedRenderedCookies, getMergedRenderedCookies };
+export { type BrowserName, ChromeCookieQueryStrategy, ChromiumCookieQueryStrategy, CompositeCookieQueryStrategy, type CookieQueryStrategy, type CookieSpec, type ExportedCookie, FirefoxCookieQueryStrategy, type MultiCookieSpec, type RenderOptions, SafariCookieQueryStrategy, getCookie };