@mherod/get-cookie 4.0.4 → 4.2.0

package/dist/index.d.cts

@@ -27,8 +27,8 @@ import { z } from 'zod';
  * ```
  */
 declare const CookieSpecSchema: z.ZodObject<{
-    name: z.ZodString;
-    domain: z.ZodString;
+    name: z.ZodEffects<z.ZodString, string, string>;
+    domain: z.ZodEffects<z.ZodString, string, string>;
 }, "strict", z.ZodTypeAny, {
     name: string;
     domain: string;
@@ -91,9 +91,9 @@ type CookieSpec = z.infer<typeof CookieSpecSchema>;
  * ```
  */
 declare const ExportedCookieSchema: z.ZodObject<{
-    domain: z.ZodString;
-    name: z.ZodString;
-    value: z.ZodString;
+    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>;
     expiry: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"Infinity">, z.ZodDate, z.ZodNumber]>>;
     meta: z.ZodOptional<z.ZodObject<{
         file: z.ZodOptional<z.ZodString>;
@@ -101,26 +101,26 @@ declare const ExportedCookieSchema: z.ZodObject<{
         decrypted: z.ZodOptional<z.ZodBoolean>;
         secure: z.ZodOptional<z.ZodBoolean>;
         httpOnly: z.ZodOptional<z.ZodBoolean>;
-        path: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
     }, "strict", z.ZodUnknown, z.objectOutputType<{
         file: z.ZodOptional<z.ZodString>;
         browser: z.ZodOptional<z.ZodString>;
         decrypted: z.ZodOptional<z.ZodBoolean>;
         secure: z.ZodOptional<z.ZodBoolean>;
         httpOnly: z.ZodOptional<z.ZodBoolean>;
-        path: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
     }, z.ZodUnknown, "strict">, z.objectInputType<{
         file: z.ZodOptional<z.ZodString>;
         browser: z.ZodOptional<z.ZodString>;
         decrypted: z.ZodOptional<z.ZodBoolean>;
         secure: z.ZodOptional<z.ZodBoolean>;
         httpOnly: z.ZodOptional<z.ZodBoolean>;
-        path: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
     }, z.ZodUnknown, "strict">>>;
 }, "strict", z.ZodTypeAny, {
     name: string;
     domain: string;
-    value: string;
+    value?: any;
     expiry?: number | Date | "Infinity" | undefined;
     meta?: z.objectOutputType<{
         file: z.ZodOptional<z.ZodString>;
@@ -128,12 +128,12 @@ declare const ExportedCookieSchema: z.ZodObject<{
         decrypted: z.ZodOptional<z.ZodBoolean>;
         secure: z.ZodOptional<z.ZodBoolean>;
         httpOnly: z.ZodOptional<z.ZodBoolean>;
-        path: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
     }, z.ZodUnknown, "strict"> | undefined;
 }, {
     name: string;
-    domain: string;
     value: string;
+    domain: string;
     expiry?: number | Date | "Infinity" | undefined;
     meta?: z.objectInputType<{
         file: z.ZodOptional<z.ZodString>;
@@ -141,7 +141,7 @@ declare const ExportedCookieSchema: z.ZodObject<{
         decrypted: z.ZodOptional<z.ZodBoolean>;
         secure: z.ZodOptional<z.ZodBoolean>;
         httpOnly: z.ZodOptional<z.ZodBoolean>;
-        path: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
     }, z.ZodUnknown, "strict"> | undefined;
 }>;
 /**
@@ -196,69 +196,248 @@ declare const RenderOptionsSchema: z.ZodObject<{
  * Type definition for render options
  */
 type RenderOptions = z.infer<typeof RenderOptionsSchema>;
+/**
+ * Schema for browser names
+ */
+declare const BrowserNameSchema: z.ZodEnum<["Chrome", "Firefox", "Safari", "internal", "unknown"]>;
+/**
+ * Type definition for browser names
+ */
+type BrowserName = z.infer<typeof BrowserNameSchema>;
+/**
+ * Schema for cookie query strategy
+ */
+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<{
+        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>;
+        expiry: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"Infinity">, z.ZodDate, z.ZodNumber]>>;
+        meta: z.ZodOptional<z.ZodObject<{
+            file: z.ZodOptional<z.ZodString>;
+            browser: z.ZodOptional<z.ZodString>;
+            decrypted: z.ZodOptional<z.ZodBoolean>;
+            secure: z.ZodOptional<z.ZodBoolean>;
+            httpOnly: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+        }, "strict", z.ZodUnknown, z.objectOutputType<{
+            file: z.ZodOptional<z.ZodString>;
+            browser: z.ZodOptional<z.ZodString>;
+            decrypted: z.ZodOptional<z.ZodBoolean>;
+            secure: z.ZodOptional<z.ZodBoolean>;
+            httpOnly: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+        }, z.ZodUnknown, "strict">, z.objectInputType<{
+            file: z.ZodOptional<z.ZodString>;
+            browser: z.ZodOptional<z.ZodString>;
+            decrypted: z.ZodOptional<z.ZodBoolean>;
+            secure: z.ZodOptional<z.ZodBoolean>;
+            httpOnly: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+        }, z.ZodUnknown, "strict">>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        domain: string;
+        value?: any;
+        expiry?: number | Date | "Infinity" | undefined;
+        meta?: z.objectOutputType<{
+            file: z.ZodOptional<z.ZodString>;
+            browser: z.ZodOptional<z.ZodString>;
+            decrypted: z.ZodOptional<z.ZodBoolean>;
+            secure: z.ZodOptional<z.ZodBoolean>;
+            httpOnly: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+        }, z.ZodUnknown, "strict"> | undefined;
+    }, {
+        name: string;
+        value: string;
+        domain: string;
+        expiry?: number | Date | "Infinity" | undefined;
+        meta?: z.objectInputType<{
+            file: z.ZodOptional<z.ZodString>;
+            browser: z.ZodOptional<z.ZodString>;
+            decrypted: z.ZodOptional<z.ZodBoolean>;
+            secure: z.ZodOptional<z.ZodBoolean>;
+            httpOnly: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+        }, z.ZodUnknown, "strict"> | undefined;
+    }>, "many">>>;
+}, "strict", z.ZodTypeAny, {
+    browserName: "unknown" | "Chrome" | "Firefox" | "Safari" | "internal";
+    queryCookies: (args_0: string, args_1: string, ...args: unknown[]) => Promise<{
+        name: string;
+        domain: string;
+        value?: any;
+        expiry?: number | Date | "Infinity" | undefined;
+        meta?: z.objectOutputType<{
+            file: z.ZodOptional<z.ZodString>;
+            browser: z.ZodOptional<z.ZodString>;
+            decrypted: z.ZodOptional<z.ZodBoolean>;
+            secure: z.ZodOptional<z.ZodBoolean>;
+            httpOnly: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+        }, z.ZodUnknown, "strict"> | undefined;
+    }[]>;
+}, {
+    browserName: "unknown" | "Chrome" | "Firefox" | "Safari" | "internal";
+    queryCookies: (args_0: string, args_1: string, ...args: unknown[]) => Promise<{
+        name: string;
+        value: string;
+        domain: string;
+        expiry?: number | Date | "Infinity" | undefined;
+        meta?: z.objectInputType<{
+            file: z.ZodOptional<z.ZodString>;
+            browser: z.ZodOptional<z.ZodString>;
+            decrypted: z.ZodOptional<z.ZodBoolean>;
+            secure: z.ZodOptional<z.ZodBoolean>;
+            httpOnly: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodOptional<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
+        }, z.ZodUnknown, "strict"> | undefined;
+    }[]>;
+}>;
+/**
+ * Type definition for cookie query strategy
+ */
+type CookieQueryStrategy = z.infer<typeof CookieQueryStrategySchema>;
+/**
+ * Type representing either a single cookie specification or an array of specifications.
+ * Useful when you need to query multiple cookies in a single operation.
+ * @example
+ * ```typescript
+ * // Single cookie spec
+ * const single: MultiCookieSpec = {
+ *   domain: "example.com",
+ *   name: "sessionId"
+ * };
+ *
+ * // Multiple cookie specs
+ * const multiple: MultiCookieSpec = [
+ *   { domain: "example.com", name: "sessionId" },
+ *   { domain: "api.example.com", name: "authToken" }
+ * ];
+ * ```
+ */
+type MultiCookieSpec = CookieSpec | CookieSpec[];
 
 /**
- * Dynamic import for the getCookie function.
- * @internal
- * @returns Promise resolving to the getCookie function
+ * 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 getCookieFn = await getCookie();
- * const cookies = await getCookieFn({ domain: 'example.com' });
- * // Returns: [{ name: 'sessionId', value: 'abc123', domain: '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 const getCookie: () => Promise<(cookieSpec: CookieSpec) => Promise<ExportedCookie[]>>;
+declare function getCookie(cookieSpec: CookieSpec): Promise<ExportedCookie[]>;
+
 /**
- * Dynamic import for Chrome-specific cookie retrieval.
- * @internal
- * @returns Promise resolving to the getChromeCookie function
+ * 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
- * const chromeCookieFn = await getChromeCookie();
- * const cookies = await chromeCookieFn({ domain: 'example.com', secure: true });
- * // Returns Chrome-format cookies: [{ name: 'auth', value: 'xyz789', secure: true }, ...]
+ * 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"
+ * });
  * ```
  */
-declare const getChromeCookie: () => Promise<(cookieSpec: CookieSpec) => Promise<ExportedCookie[]>>;
+declare function getChromeCookie(cookieSpec: CookieSpec): Promise<ExportedCookie[]>;
+
 /**
- * Dynamic import for Firefox-specific cookie retrieval.
- * @internal
- * @returns Promise resolving to the getFirefoxCookie function
+ * 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
  * @example
  * ```typescript
- * const firefoxCookieFn = await getFirefoxCookie();
- * const cookies = await firefoxCookieFn({ path: '/api' });
- * // Returns Firefox-format cookies: [{ name: 'token', value: 'def456', path: '/api' }, ...]
+ * 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"
+ * });
  * ```
  */
-declare const getFirefoxCookie: () => Promise<(cookieSpec: CookieSpec) => Promise<ExportedCookie[]>>;
+declare function getFirefoxCookie(cookieSpec: CookieSpec): Promise<ExportedCookie[]>;
+
 /**
- * Dynamic import for retrieving grouped and rendered cookies.
- * @internal
- * @returns Promise resolving to the getGroupedRenderedCookies function
+ * 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
  * @example
  * ```typescript
- * const groupedCookiesFn = await getGroupedRenderedCookies();
- * const cookieStrings = await groupedCookiesFn({ domain: 'example.com' });
- * // Returns: ['sessionId=abc123; Domain=example.com', 'auth=xyz789; Domain=example.com']
+ * // Basic usage - get all cookies named "sessionId" grouped by source file
+ * const cookies = await getGroupedRenderedCookies({ name: "sessionId" });
+ *
+ * // Get cookies with domain filter and custom rendering options
+ * const domainCookies = await getGroupedRenderedCookies(
+ *   {
+ *     name: "userPref",
+ *     domain: "example.com"
+ *   },
+ *   {
+ *     showFilePaths: true,
+ *     separator: " | "
+ *   }
+ * );
  * ```
  */
-declare const getGroupedRenderedCookies: () => Promise<(cookieSpec: CookieSpec) => Promise<string[]>>;
+declare function getGroupedRenderedCookies(cookieSpec: CookieSpec, options?: Omit<RenderOptions, "format">): Promise<string[]>;
+
 /**
- * Dynamic import for retrieving merged and rendered cookies.
- * @internal
- * @returns Promise resolving to the getMergedRenderedCookies function
+ * 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
  * @example
  * ```typescript
- * const mergedCookiesFn = await getMergedRenderedCookies();
- * const cookieString = await mergedCookiesFn(
- *   { domain: 'example.com' },
+ * const cookieString = await getMergedRenderedCookies(
+ *   { name: 'session', domain: 'example.com' },
  *   { separator: '; ' }
  * );
- * // Returns: "sessionId=abc123; auth=xyz789"
+ * console.log(cookieString); // "session=abc123; auth=xyz789"
  * ```
  */
-declare const getMergedRenderedCookies: () => Promise<(cookieSpec: CookieSpec, options?: Omit<RenderOptions, "format">) => Promise<string>>;
+declare function getMergedRenderedCookies(cookieSpec: CookieSpec, options?: Omit<RenderOptions, "format">): Promise<string>;
 
-export { getChromeCookie, getCookie, getFirefoxCookie, getGroupedRenderedCookies, getMergedRenderedCookies };
+export { type BrowserName, type CookieQueryStrategy, type CookieSpec, type ExportedCookie, type MultiCookieSpec, type RenderOptions, getChromeCookie, getCookie, getFirefoxCookie, getGroupedRenderedCookies, getMergedRenderedCookies };