@mherod/get-cookie 2.1.2 → 4.0.1

package/dist/index.d.cts

@@ -0,0 +1,252 @@
+/**
+ * Type guard to check if an object matches the CookieRenderOptions interface.
+ * Used to validate render options before processing cookie output.
+ * @param obj - The object to check.
+ * @returns True if the object contains valid render options.
+ * @example
+ * ```typescript
+ * import { isCookieRenderOptions } from 'get-cookie';
+ *
+ * // Valid render options
+ * console.log(isCookieRenderOptions({ format: "json" })); // true
+ * console.log(isCookieRenderOptions({
+ *   format: "text",
+ *   separator: "\n",
+ *   showFilePaths: true
+ * })); // true
+ *
+ * // Invalid examples
+ * console.log(isCookieRenderOptions({ format: "csv" })); // false - invalid format
+ * console.log(isCookieRenderOptions({ separator: "\n" })); // false - missing format
+ * console.log(isCookieRenderOptions(null)); // false
+ * ```
+ */
+type RenderFormat = "merged" | "grouped";
+/**
+ * Options for rendering cookies.
+ * @example
+ * ```typescript
+ * import { RenderOptions } from 'get-cookie';
+ *
+ * // Basic rendering options
+ * const basicOptions: RenderOptions = {
+ *   format: 'merged',
+ *   separator: '; ',
+ *   showFilePaths: false
+ * };
+ *
+ * // Grouped format with file paths
+ * const groupedOptions: RenderOptions = {
+ *   format: 'grouped',
+ *   separator: '; ',
+ *   showFilePaths: true
+ * };
+ *
+ * // Custom separator
+ * const customOptions: RenderOptions = {
+ *   format: 'merged',
+ *   separator: ' && ',
+ *   showFilePaths: false
+ * };
+ * ```
+ */
+interface RenderOptions {
+    /** The format to use when rendering cookies. */
+    format?: RenderFormat;
+    /** The separator to use between cookies. */
+    separator?: string;
+    /** Whether to show file paths in the output. */
+    showFilePaths?: boolean;
+}
+
+/**
+ * Specification for identifying a cookie by its domain and name.
+ * Used to query specific cookies from browser storage.
+ * @remarks
+ * - Domain matching is exact unless using wildcards.
+ * - Name can be "*" to match all cookies for a domain.
+ * - Leading dots in domains match all subdomains.
+ * @example
+ * ```typescript
+ * import { CookieSpec } from 'get-cookie';
+ *
+ * // Basic cookie specification
+ * const cookieSpec: CookieSpec = {
+ *   domain: "example.com",
+ *   name: "sessionId"
+ * };
+ *
+ * // Using wildcards to match all cookies
+ * const allCookies: CookieSpec = {
+ *   domain: "example.com",
+ *   name: "*"  // Match all cookies for example.com
+ * };
+ *
+ * // Subdomain specification
+ * const apiCookies: CookieSpec = {
+ *   domain: "api.example.com",
+ *   name: "auth"
+ * };
+ *
+ * // Match cookies across all subdomains
+ * const allSubdomainCookies: CookieSpec = {
+ *   domain: ".example.com",  // Note the leading dot
+ *   name: "tracking"
+ * };
+ *
+ * // Multiple domain levels
+ * const deepSubdomainCookie: CookieSpec = {
+ *   domain: "dev.api.example.com",
+ *   name: "debug"
+ * };
+ * ```
+ */
+interface CookieSpec {
+    /** The domain the cookie belongs to. */
+    domain: string;
+    /** The name of the cookie. */
+    name: string;
+}
+
+/**
+ * Interface representing a cookie that has been exported from a browser's storage.
+ * This is the core data structure used to represent cookies after they have been
+ * retrieved from various browser storage mechanisms (Chrome, Firefox, etc.).
+ * @remarks
+ * - All cookies must have domain, name, and value properties.
+ * - Expiry is optional and can be a Date, "Infinity", or undefined.
+ * - Meta information is useful for tracking the cookie's origin and state.
+ * @example
+ * ```typescript
+ * import { ExportedCookie } from 'get-cookie';
+ *
+ * // Basic cookie with required fields
+ * const basicCookie: ExportedCookie = {
+ *   domain: "example.com",
+ *   name: "sessionId",
+ *   value: "abc123"
+ * };
+ *
+ * // Cookie with expiry and metadata
+ * const detailedCookie: ExportedCookie = {
+ *   domain: "api.example.com",
+ *   name: "authToken",
+ *   value: "xyz789",
+ *   expiry: new Date("2024-12-31"),
+ *   meta: {
+ *     file: "Cookies.sqlite",
+ *     browser: "Firefox",
+ *     decrypted: true,
+ *     secure: true,
+ *     httpOnly: true,
+ *     path: "/"
+ *   }
+ * };
+ *
+ * // Cookie with infinite expiry (session cookie)
+ * const persistentCookie: ExportedCookie = {
+ *   domain: "app.example.com",
+ *   name: "preferences",
+ *   value: "theme=dark",
+ *   expiry: "Infinity"
+ * };
+ *
+ * // Subdomain cookie example
+ * const subdomainCookie: ExportedCookie = {
+ *   domain: ".example.com",  // Note the leading dot for all subdomains
+ *   name: "tracking",
+ *   value: "user123",
+ *   meta: {
+ *     browser: "Chrome",
+ *     decrypted: true
+ *   }
+ * };
+ * ```
+ */
+interface ExportedCookie {
+    /** The domain the cookie belongs to. */
+    domain: string;
+    /** The name of the cookie. */
+    name: string;
+    /** The value of the cookie. */
+    value: string;
+    /** When the cookie expires (Date object, "Infinity", or undefined). */
+    expiry?: Date | "Infinity";
+    /** Additional metadata about the cookie. */
+    meta?: {
+        /** Path to the file the cookie was exported from. */
+        file?: string;
+        /** Browser the cookie was exported from. */
+        browser?: string;
+        /** Whether the cookie value was decrypted. */
+        decrypted?: boolean;
+        /** Any additional metadata. */
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * Dynamic import for the getCookie function.
+ * @internal
+ * @returns Promise resolving to the getCookie function
+ * @example
+ * ```typescript
+ * const getCookieFn = await getCookie();
+ * const cookies = await getCookieFn({ domain: 'example.com' });
+ * // Returns: [{ name: 'sessionId', value: 'abc123', domain: 'example.com' }, ...]
+ * ```
+ */
+declare const getCookie: () => Promise<(cookieSpec: CookieSpec) => Promise<ExportedCookie[]>>;
+/**
+ * Dynamic import for Chrome-specific cookie retrieval.
+ * @internal
+ * @returns Promise resolving to the getChromeCookie function
+ * @example
+ * ```typescript
+ * const chromeCookieFn = await getChromeCookie();
+ * const cookies = await chromeCookieFn({ domain: 'example.com', secure: true });
+ * // Returns Chrome-format cookies: [{ name: 'auth', value: 'xyz789', secure: true }, ...]
+ * ```
+ */
+declare const getChromeCookie: () => Promise<(cookieSpec: CookieSpec) => Promise<ExportedCookie[]>>;
+/**
+ * Dynamic import for Firefox-specific cookie retrieval.
+ * @internal
+ * @returns Promise resolving to the getFirefoxCookie function
+ * @example
+ * ```typescript
+ * const firefoxCookieFn = await getFirefoxCookie();
+ * const cookies = await firefoxCookieFn({ path: '/api' });
+ * // Returns Firefox-format cookies: [{ name: 'token', value: 'def456', path: '/api' }, ...]
+ * ```
+ */
+declare const getFirefoxCookie: () => Promise<(cookieSpec: CookieSpec) => Promise<ExportedCookie[]>>;
+/**
+ * Dynamic import for retrieving grouped and rendered cookies.
+ * @internal
+ * @returns Promise resolving to the getGroupedRenderedCookies function
+ * @example
+ * ```typescript
+ * const groupedCookiesFn = await getGroupedRenderedCookies();
+ * const cookieStrings = await groupedCookiesFn({ domain: 'example.com' });
+ * // Returns: ['sessionId=abc123; Domain=example.com', 'auth=xyz789; Domain=example.com']
+ * ```
+ */
+declare const getGroupedRenderedCookies: () => Promise<(cookieSpec: CookieSpec) => Promise<string[]>>;
+/**
+ * Dynamic import for retrieving merged and rendered cookies.
+ * @internal
+ * @returns Promise resolving to the getMergedRenderedCookies function
+ * @example
+ * ```typescript
+ * const mergedCookiesFn = await getMergedRenderedCookies();
+ * const cookieString = await mergedCookiesFn(
+ *   { domain: 'example.com' },
+ *   { separator: '; ' }
+ * );
+ * // Returns: "sessionId=abc123; auth=xyz789"
+ * ```
+ */
+declare const getMergedRenderedCookies: () => Promise<(cookieSpec: CookieSpec, options?: Omit<RenderOptions, "format">) => Promise<string>>;
+
+export { getChromeCookie, getCookie, getFirefoxCookie, getGroupedRenderedCookies, getMergedRenderedCookies };

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Type guard to check if an object matches the CookieRenderOptions interface.
+ * Used to validate render options before processing cookie output.
+ * @param obj - The object to check.
+ * @returns True if the object contains valid render options.
+ * @example
+ * ```typescript
+ * import { isCookieRenderOptions } from 'get-cookie';
+ *
+ * // Valid render options
+ * console.log(isCookieRenderOptions({ format: "json" })); // true
+ * console.log(isCookieRenderOptions({
+ *   format: "text",
+ *   separator: "\n",
+ *   showFilePaths: true
+ * })); // true
+ *
+ * // Invalid examples
+ * console.log(isCookieRenderOptions({ format: "csv" })); // false - invalid format
+ * console.log(isCookieRenderOptions({ separator: "\n" })); // false - missing format
+ * console.log(isCookieRenderOptions(null)); // false
+ * ```
+ */
+type RenderFormat = "merged" | "grouped";
+/**
+ * Options for rendering cookies.
+ * @example
+ * ```typescript
+ * import { RenderOptions } from 'get-cookie';
+ *
+ * // Basic rendering options
+ * const basicOptions: RenderOptions = {
+ *   format: 'merged',
+ *   separator: '; ',
+ *   showFilePaths: false
+ * };
+ *
+ * // Grouped format with file paths
+ * const groupedOptions: RenderOptions = {
+ *   format: 'grouped',
+ *   separator: '; ',
+ *   showFilePaths: true
+ * };
+ *
+ * // Custom separator
+ * const customOptions: RenderOptions = {
+ *   format: 'merged',
+ *   separator: ' && ',
+ *   showFilePaths: false
+ * };
+ * ```
+ */
+interface RenderOptions {
+    /** The format to use when rendering cookies. */
+    format?: RenderFormat;
+    /** The separator to use between cookies. */
+    separator?: string;
+    /** Whether to show file paths in the output. */
+    showFilePaths?: boolean;
+}
+
+/**
+ * Specification for identifying a cookie by its domain and name.
+ * Used to query specific cookies from browser storage.
+ * @remarks
+ * - Domain matching is exact unless using wildcards.
+ * - Name can be "*" to match all cookies for a domain.
+ * - Leading dots in domains match all subdomains.
+ * @example
+ * ```typescript
+ * import { CookieSpec } from 'get-cookie';
+ *
+ * // Basic cookie specification
+ * const cookieSpec: CookieSpec = {
+ *   domain: "example.com",
+ *   name: "sessionId"
+ * };
+ *
+ * // Using wildcards to match all cookies
+ * const allCookies: CookieSpec = {
+ *   domain: "example.com",
+ *   name: "*"  // Match all cookies for example.com
+ * };
+ *
+ * // Subdomain specification
+ * const apiCookies: CookieSpec = {
+ *   domain: "api.example.com",
+ *   name: "auth"
+ * };
+ *
+ * // Match cookies across all subdomains
+ * const allSubdomainCookies: CookieSpec = {
+ *   domain: ".example.com",  // Note the leading dot
+ *   name: "tracking"
+ * };
+ *
+ * // Multiple domain levels
+ * const deepSubdomainCookie: CookieSpec = {
+ *   domain: "dev.api.example.com",
+ *   name: "debug"
+ * };
+ * ```
+ */
+interface CookieSpec {
+    /** The domain the cookie belongs to. */
+    domain: string;
+    /** The name of the cookie. */
+    name: string;
+}
+
+/**
+ * Interface representing a cookie that has been exported from a browser's storage.
+ * This is the core data structure used to represent cookies after they have been
+ * retrieved from various browser storage mechanisms (Chrome, Firefox, etc.).
+ * @remarks
+ * - All cookies must have domain, name, and value properties.
+ * - Expiry is optional and can be a Date, "Infinity", or undefined.
+ * - Meta information is useful for tracking the cookie's origin and state.
+ * @example
+ * ```typescript
+ * import { ExportedCookie } from 'get-cookie';
+ *
+ * // Basic cookie with required fields
+ * const basicCookie: ExportedCookie = {
+ *   domain: "example.com",
+ *   name: "sessionId",
+ *   value: "abc123"
+ * };
+ *
+ * // Cookie with expiry and metadata
+ * const detailedCookie: ExportedCookie = {
+ *   domain: "api.example.com",
+ *   name: "authToken",
+ *   value: "xyz789",
+ *   expiry: new Date("2024-12-31"),
+ *   meta: {
+ *     file: "Cookies.sqlite",
+ *     browser: "Firefox",
+ *     decrypted: true,
+ *     secure: true,
+ *     httpOnly: true,
+ *     path: "/"
+ *   }
+ * };
+ *
+ * // Cookie with infinite expiry (session cookie)
+ * const persistentCookie: ExportedCookie = {
+ *   domain: "app.example.com",
+ *   name: "preferences",
+ *   value: "theme=dark",
+ *   expiry: "Infinity"
+ * };
+ *
+ * // Subdomain cookie example
+ * const subdomainCookie: ExportedCookie = {
+ *   domain: ".example.com",  // Note the leading dot for all subdomains
+ *   name: "tracking",
+ *   value: "user123",
+ *   meta: {
+ *     browser: "Chrome",
+ *     decrypted: true
+ *   }
+ * };
+ * ```
+ */
+interface ExportedCookie {
+    /** The domain the cookie belongs to. */
+    domain: string;
+    /** The name of the cookie. */
+    name: string;
+    /** The value of the cookie. */
+    value: string;
+    /** When the cookie expires (Date object, "Infinity", or undefined). */
+    expiry?: Date | "Infinity";
+    /** Additional metadata about the cookie. */
+    meta?: {
+        /** Path to the file the cookie was exported from. */
+        file?: string;
+        /** Browser the cookie was exported from. */
+        browser?: string;
+        /** Whether the cookie value was decrypted. */
+        decrypted?: boolean;
+        /** Any additional metadata. */
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * Dynamic import for the getCookie function.
+ * @internal
+ * @returns Promise resolving to the getCookie function
+ * @example
+ * ```typescript
+ * const getCookieFn = await getCookie();
+ * const cookies = await getCookieFn({ domain: 'example.com' });
+ * // Returns: [{ name: 'sessionId', value: 'abc123', domain: 'example.com' }, ...]
+ * ```
+ */
+declare const getCookie: () => Promise<(cookieSpec: CookieSpec) => Promise<ExportedCookie[]>>;
+/**
+ * Dynamic import for Chrome-specific cookie retrieval.
+ * @internal
+ * @returns Promise resolving to the getChromeCookie function
+ * @example
+ * ```typescript
+ * const chromeCookieFn = await getChromeCookie();
+ * const cookies = await chromeCookieFn({ domain: 'example.com', secure: true });
+ * // Returns Chrome-format cookies: [{ name: 'auth', value: 'xyz789', secure: true }, ...]
+ * ```
+ */
+declare const getChromeCookie: () => Promise<(cookieSpec: CookieSpec) => Promise<ExportedCookie[]>>;
+/**
+ * Dynamic import for Firefox-specific cookie retrieval.
+ * @internal
+ * @returns Promise resolving to the getFirefoxCookie function
+ * @example
+ * ```typescript
+ * const firefoxCookieFn = await getFirefoxCookie();
+ * const cookies = await firefoxCookieFn({ path: '/api' });
+ * // Returns Firefox-format cookies: [{ name: 'token', value: 'def456', path: '/api' }, ...]
+ * ```
+ */
+declare const getFirefoxCookie: () => Promise<(cookieSpec: CookieSpec) => Promise<ExportedCookie[]>>;
+/**
+ * Dynamic import for retrieving grouped and rendered cookies.
+ * @internal
+ * @returns Promise resolving to the getGroupedRenderedCookies function
+ * @example
+ * ```typescript
+ * const groupedCookiesFn = await getGroupedRenderedCookies();
+ * const cookieStrings = await groupedCookiesFn({ domain: 'example.com' });
+ * // Returns: ['sessionId=abc123; Domain=example.com', 'auth=xyz789; Domain=example.com']
+ * ```
+ */
+declare const getGroupedRenderedCookies: () => Promise<(cookieSpec: CookieSpec) => Promise<string[]>>;
+/**
+ * Dynamic import for retrieving merged and rendered cookies.
+ * @internal
+ * @returns Promise resolving to the getMergedRenderedCookies function
+ * @example
+ * ```typescript
+ * const mergedCookiesFn = await getMergedRenderedCookies();
+ * const cookieString = await mergedCookiesFn(
+ *   { domain: 'example.com' },
+ *   { separator: '; ' }
+ * );
+ * // Returns: "sessionId=abc123; auth=xyz789"
+ * ```
+ */
+declare const getMergedRenderedCookies: () => Promise<(cookieSpec: CookieSpec, options?: Omit<RenderOptions, "format">) => Promise<string>>;
+
+export { getChromeCookie, getCookie, getFirefoxCookie, getGroupedRenderedCookies, getMergedRenderedCookies };