Sweet Cookie

https://github.com/steipete/sweet-cookie
Admin
Sweet Cookie is a dependency-light browser cookie extraction library that prioritizes inline cookies...
Tokens:10,499
Snippets:88
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install @steipete/sweet-cookie

Source: https://github.com/steipete/sweet-cookie/blob/main/packages/core/README.md

Install the package using npm. This is the initial setup step before using the library.

```bash
npm i @steipete/sweet-cookie
```

--------------------------------

### Install Dependencies for Repo/Dev

Source: https://github.com/steipete/sweet-cookie/blob/main/README.md

Install project dependencies for local development using pnpm.

```bash
pnpm i
```

--------------------------------

### Install Sweet Cookie with npm

Source: https://github.com/steipete/sweet-cookie/blob/main/README.md

Install the Sweet Cookie library using npm. This command is also applicable for pnpm and bun.

```bash
npm i @steipete/sweet-cookie
# or: pnpm add @steipete/sweet-cookie
# or: bun add @steipete/sweet-cookie
```

--------------------------------

### Minimal Library Usage: Get and Format Cookies

Source: https://github.com/steipete/sweet-cookie/blob/main/README.md

Demonstrates minimal usage of the Sweet Cookie library to retrieve specific cookies for a given URL and format them into a cookie header. Includes handling of potential warnings.

```typescript
import { getCookies, toCookieHeader } from "@steipete/sweet-cookie";

const { cookies, warnings } = await getCookies({
	url: "https://example.com/",
	names: ["session", "csrf"],
	browsers: ["chrome", "edge", "firefox", "safari"],
});

for (const warning of warnings) console.warn(warning);

const cookieHeader = toCookieHeader(cookies, { dedupeByName: true });
```

--------------------------------

### Get Package Version

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/RELEASING.md

A helper script to extract the current version from the core package.json file.

```bash
ver="$(node -p 'require("./packages/core/package.json").version')"
echo "$ver"
```

--------------------------------

### Smoke Test Sweet Cookie Installation

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/RELEASING.md

Performs a smoke test by installing the sweet-cookie package in a fresh directory and verifying that the imported functions are available. Replace "${ver}" with the actual version number.

```bash
rm -rf /tmp/sweet-cookie-smoke && mkdir -p /tmp/sweet-cookie-smoke
cd /tmp/sweet-cookie-smoke
npm init -y >/dev/null
npm i @steipete/sweet-cookie@"${ver}"
node -e "import { getCookies, toCookieHeader } from '@steipete/sweet-cookie'; console.log(typeof getCookies, typeof toCookieHeader);"
```

--------------------------------

### Library Usage: Inline Cookies from File

Source: https://github.com/steipete/sweet-cookie/blob/main/README.md

Example of using inline cookies by providing a path to a JSON file. This method bypasses local browser database access and works on any OS/runtime.

```typescript
await getCookies({
	url: "https://example.com/",
	browsers: ["chrome"],
	inlineCookiesFile: "/path/to/cookies.json", // or inlineCookiesJson / inlineCookiesBase64
});
```

--------------------------------

### Library Usage: Multiple Origins with Merge Mode

Source: https://github.com/steipete/sweet-cookie/blob/main/README.md

Example of retrieving cookies from multiple specified origins for a given URL, merging the results. Useful for scenarios involving OAuth or SSO redirects.

```typescript
const { cookies } = await getCookies({
	url: "https://app.example.com/",
	origins: ["https://accounts.example.com/", "https://login.example.com/"],
	names: ["session", "xsrf"],
	browsers: ["chrome"],
	mode: "merge",
});
```

--------------------------------

### Get Cookies and Format Header

Source: https://github.com/steipete/sweet-cookie/blob/main/packages/core/README.md

Use `getCookies` to extract cookies from specified browsers for a given URL and optionally filter by name. The `toCookieHeader` function then formats these cookies into a string suitable for HTTP headers, with an option to deduplicate by name.

```typescript
import { getCookies, toCookieHeader } from "@steipete/sweet-cookie";

const { cookies, warnings } = await getCookies({
	url: "https://example.com/",
	names: ["session", "csrf"],
	browsers: ["chrome", "edge", "firefox", "safari"],
});

for (const w of warnings) console.warn(w);
const cookieHeader = toCookieHeader(cookies, { dedupeByName: true });
```

--------------------------------

### macOS Chromium Targeting

Source: https://github.com/steipete/sweet-cookie/blob/main/packages/core/README.md

On macOS, you can specifically target a Chromium-based browser like Brave using the `chromiumBrowser` option within `getCookies`. This allows for more precise cookie extraction when multiple Chromium variants are installed.

```typescript
await getCookies({
	url: "https://example.com/",
	browsers: ["chrome"],
	chromiumBrowser: "brave",
});
```

--------------------------------

### Run development lifecycle commands

Source: https://github.com/steipete/sweet-cookie/blob/main/README.md

Execute standard build, linting, and testing tasks using pnpm.

```bash
pnpm build
pnpm typecheck
pnpm lint
pnpm test
pnpm test:bun
```

--------------------------------

### Publish to npm

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/RELEASING.md

Navigates to the core package directory and publishes the package to npm. Ensure you are authenticated with npm before running.

```bash
cd packages/core
npm publish
```

--------------------------------

### Environment Configuration

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Configure library behavior using environment variables for CI/CD and containerized environments.

```APIDOC
## Environment Variables

### Description
Configure Sweet Cookie behavior via environment variables. These settings are used as defaults when options are not explicitly provided in the `getCookies` function.

### Configuration Variables
- **SWEET_COOKIE_BROWSERS** (string) - Comma or space-separated list of browsers to check.
- **SWEET_COOKIE_MODE** (string) - Default merge mode ("merge" or "first").
- **SWEET_COOKIE_CHROME_PROFILE** (string) - Default Chrome profile name.
- **SWEET_COOKIE_LINUX_KEYRING** (string) - Linux keyring provider ("gnome", "kwallet", or "basic").
```

--------------------------------

### Verify GitHub Release Body Rendering

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/RELEASING.md

Fetches the body of a GitHub release and displays the first few lines to verify rendering. Replace "v${ver}" with the actual tag.

```bash
gh release view "v${ver}" --json body --jq .body | head
```

--------------------------------

### Create GitHub Release

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/RELEASING.md

Creates a GitHub release using the GitHub CLI. It uses the version tag and a file containing the release notes. Replace "${ver}" with the actual version number.

```bash
gh release create "v${ver}" \
  --title "v${ver}" \
  --notes-file "/tmp/sweet-cookie-v${ver}-notes.md"
```

--------------------------------

### Configure Sweet Cookie via Environment Variables

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Set library behavior globally using environment variables, which are automatically applied when options are omitted in getCookies.

```bash
# Set default browser order (comma or space-separated)
export SWEET_COOKIE_BROWSERS="chrome,edge,firefox"
# Alternative name
export SWEET_COOKIE_SOURCES="chrome edge safari"

# Set default mode
export SWEET_COOKIE_MODE="merge"  # or "first"

# Set default profiles
export SWEET_COOKIE_CHROME_PROFILE="Default"
export SWEET_COOKIE_EDGE_PROFILE="Profile 2"
export SWEET_COOKIE_FIREFOX_PROFILE="default-release"

# Linux keyring configuration
export SWEET_COOKIE_LINUX_KEYRING="gnome"  # gnome | kwallet | basic

# Linux safe storage password overrides (when keyring access fails)
export SWEET_COOKIE_CHROME_SAFE_STORAGE_PASSWORD="your-password"
export SWEET_COOKIE_EDGE_SAFE_STORAGE_PASSWORD="your-password"
export SWEET_COOKIE_BRAVE_SAFE_STORAGE_PASSWORD="your-password"
```

```typescript
import { getCookies } from "@steipete/sweet-cookie";

// Environment variables are used when options are not provided
const { cookies } = await getCookies({
  url: "https://example.com/",
  // browsers defaults to SWEET_COOKIE_BROWSERS if not specified
  // mode defaults to SWEET_COOKIE_MODE if not specified
  // chromeProfile defaults to SWEET_COOKIE_CHROME_PROFILE if not specified
});
```

--------------------------------

### Load Extension Export and Use with getCookies

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Demonstrates loading an extension's JSON cookie export and using it with the `getCookies` function from the Sweet Cookie library. The library accepts the full export or a plain `Cookie[]` array. An optional `names` filter can be applied.

```typescript
import { getCookies } from "@steipete/sweet-cookie";
import { readFileSync } from "node:fs";

// Load extension export and use with getCookies
const exportedJson = readFileSync("/path/to/cookies-export.json", "utf8");

const { cookies } = await getCookies({
  url: "https://chatgpt.com/",
  inlineCookiesJson: exportedJson, // Accepts full export or just Cookie[]
  names: ["__Secure-next-auth.session-token"], // Optional filter
});

// The library also accepts plain Cookie[] arrays
const plainArray = JSON.stringify([
  { name: "session", value: "abc", domain: "example.com", path: "/" }
]);

const { cookies: plainCookies } = await getCookies({
  url: "https://example.com/",
  inlineCookiesJson: plainArray,
});
```

--------------------------------

### Library Usage: Specify Chrome Profile or DB Path

Source: https://github.com/steipete/sweet-cookie/blob/main/README.md

Shows how to target a specific Chrome profile or provide an explicit path to the Chrome cookie database file for cookie extraction.

```typescript
await getCookies({
	url: "https://example.com/",
	browsers: ["chrome"], // or ['edge']
	chromeProfile: "Default", // or '/path/to/.../Network/Cookies'
});
```

--------------------------------

### Library Usage: Specify Edge Profile or DB Path

Source: https://github.com/steipete/sweet-cookie/blob/main/README.md

Illustrates specifying a particular Edge profile or providing an explicit path to the Edge cookie database file for cookie retrieval.

```typescript
await getCookies({
	url: "https://example.com/",
	browsers: ["edge"],
	edgeProfile: "Default", // or '/path/to/.../Network/Cookies'
});
```

--------------------------------

### getCookies with Profile Selection

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Shows how to target specific browser profiles for cookie extraction, useful for managing multiple profiles.

```APIDOC
## GET /getCookies (Profile Selection)

### Description
Specifies which browser profile to read cookies from, useful when multiple profiles exist or when targeting a specific cookie database path.

### Method
GET

### Endpoint
/getCookies

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to filter cookies by.
- **browsers** (string[]) - Required - An array containing the specific browser (e.g., "chrome", "edge", "firefox") to target.
- **chromeProfile** (string) - Optional - The name or full path of the Chrome profile directory to use (e.g., "Default", "Profile 2", or `/Users/me/Library/Application Support/Google/Chrome/Profile 2`).
- **edgeProfile** (string) - Optional - The name or full path of the Edge profile directory to use (e.g., "Default").
- **firefoxProfile** (string) - Optional - The name or full path of the Firefox profile directory to use (e.g., "default-release" or a path).

### Request Example (Chrome Default Profile)
```json
{
  "url": "https://example.com/",
  "browsers": ["chrome"],
  "chromeProfile": "Default"
}
```

### Request Example (Firefox Specific Profile)
```json
{
  "url": "https://example.com/",
  "browsers": ["firefox"],
  "firefoxProfile": "default-release"
}
```

### Response
#### Success Response (200)
- **cookies** (Cookie[]) - An array of Cookie objects extracted from the specified browser profile.

### Response Example
```json
{
  "cookies": [
    { "name": "session", "value": "abc123...", "domain": "example.com", "path": "/" }
  ]
}
```
```

--------------------------------

### Extract Changelog Section for Release Notes

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/RELEASING.md

Extracts the changelog entries for a specific version from CHANGELOG.md to be used as release notes. Replace "$ver" with the actual version number.

```bash
ver="$(node -p 'require("./packages/core/package.json").version')"
awk -v start="$ver" ' 
  BEGIN { p=0 } 
  $0 ~ ("^## " start " ") { p=1; next } 
  $0 ~ "^## " { if (p) exit } 
  p { print } 
' CHANGELOG.md >"/tmp/sweet-cookie-v${ver}-notes.md"
```

--------------------------------

### Verify npm Package Version

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/RELEASING.md

Checks the currently published version of the @steipete/sweet-cookie package on npm.

```bash
npm view @steipete/sweet-cookie version
```

--------------------------------

### Extension Output - JSON Format

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/spec.md

The JSON output format for the extension, including metadata and cookie details.

```APIDOC
## GET /api/extension/output/json

### Description
Exports cookies in a JSON format, including metadata about the generation process and the cookies themselves.

### Method
GET

### Endpoint
/api/extension/output/json

### Response
#### Success Response (200)
- **version** (number) - The version of the output format.
- **generatedAt** (string) - The timestamp when the output was generated (ISO 8601 format).
- **source** (string) - The source of the cookie data (e.g., "sweet-cookie").
- **browser** (string) - The browser from which cookies were extracted.
- **targetUrl** (string) - The target URL associated with the cookies.
- **origins** (string[]) - An array of origins related to the cookies.
- **cookies** (Cookie[]) - An array of cookie objects, compatible with common CDP-ish shapes.

#### Response Example
```json
{
  "version": 1,
  "generatedAt": "2025-12-27T18:00:00.000Z",
  "source": "sweet-cookie",
  "browser": "chrome",
  "targetUrl": "https://chatgpt.com/",
  "origins": ["https://chatgpt.com/"],
  "cookies": [
    {
      "name": "__Secure-next-auth.session-token",
      "value": "…",
      "domain": "chatgpt.com",
      "path": "/",
      "secure": true,
      "httpOnly": true,
      "sameSite": "Lax",
      "expires": 1767225600
    }
  ]
}
```
```

--------------------------------

### Set Advanced Options

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Adjust timeouts, include expired cookies, and enable debug warnings to troubleshoot provider behavior.

```typescript
import { getCookies } from "@steipete/sweet-cookie";

const { cookies, warnings } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome", "edge"],

  // Timeout for OS helpers (keychain/keyring/DPAPI calls)
  timeoutMs: 10000, // 10 seconds

  // Include expired cookies in results (default: false)
  includeExpired: true,

  // Enable extra provider warnings for debugging (no raw cookie values)
  debug: true,
});

// Debug warnings provide insight into provider behavior
if (warnings.length > 0) {
  console.log("Provider warnings:");
  for (const warning of warnings) {
    console.log(`  - ${warning}`);
  }
}
// Example warnings:
// - "Chrome: Keychain access timed out after 10000ms"
// - "Firefox: Profile directory not found"
// - "Safari: Cookies.binarycookies not readable"
```

--------------------------------

### Tag Git Repository

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/RELEASING.md

Tags the current commit with a version number and pushes the tag to the origin. Ensure the version variable is set before running.

```bash
ver="$(node -p 'require("./packages/core/package.json").version')"
git tag -a "v${ver}" -m "v${ver}"
git push origin "v${ver}"
```

--------------------------------

### Extension Output - Base64 Payload

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/spec.md

The Base64 encoded JSON output format for the extension, suitable for clipboard transfer.

```APIDOC
## GET /api/extension/output/base64

### Description
Exports cookies in a Base64 encoded JSON string format. This is useful for quick transfer via clipboard or chat.

### Method
GET

### Endpoint
/api/extension/output/base64

### Response
#### Success Response (200)
- **payload** (string) - The Base64 encoded JSON string representing the cookie data and metadata.

#### Response Example
```
"ewogICAgInZlcnNpb24iOiAxLAogICAgImdlbmVyYXRlZEF0IjogIjIwMjUtMTItMjcvMTg6MDA6MDAuMDAwWiIsCiAgICAic291cmNlIjogInN3ZWV0LWNvb2tpZSIsCiAgICAiYnJvd3NlciI6ICJjaHJvbWUiLAogICAgInRhcmdldFVybCI6ICJodHRwczovL2NoYXRncHQuY29tLyIsCiAgICAib3JpZ2lucyI6IFsiSHR0cHM6Ly9jaGF0Z3B0LmNvbS8iXSwKICAgICJjb29raWVzIjogWwogICAgICAgIHsKICAgICAgICAibmFtZSI6ICJfX1NlY3VyZS1uZXh0LWF1dGgub3NzaW9uLXRva2VuIiwKICAgICAgICAidmFsdWUiOiAi4oCmIiwKICAgICAgICAiZG9tYWluIjogImNoYXRncHQuY29tIiwKICAgICAgICAicGF0aCI6ICcvIiwKICAgICAgICAic2VjdXJlIjogdHJ1ZSwKICAgICAgICAiaHR0cE9ubHkiOiB0cnVlLAogICAgICAgICJzYW1lU2l0ZSI6ICJMYXgiLAogICAgICAgICJleHBpcmVzIjogMTc2NzIyNTYwMAogICAgICB9CiAgICBdCn0="
```
```

--------------------------------

### getCookies with Multiple Origins

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Demonstrates extracting cookies across multiple domains, essential for OAuth and SSO workflows.

```APIDOC
## GET /getCookies (Multi-Origin)

### Description
Extracts cookies across multiple specified origins, commonly needed for OAuth flows and single sign-on where authentication spans multiple origins. The `mode: "merge"` option combines cookies from all specified origins and browsers.

### Method
GET

### Endpoint
/getCookies

### Parameters
#### Query Parameters
- **url** (string) - Required - The primary URL for context.
- **origins** (string[]) - Required - An array of URLs representing different origins to extract cookies from.
- **names** (string[]) - Optional - An array of cookie names to allowlist.
- **browsers** (string[]) - Optional - An array of browser identifiers to extract cookies from.
- **mode** (string) - Optional - Set to "merge" to combine cookies from all specified origins. Defaults to "merge".

### Request Example
```json
{
  "url": "https://app.example.com/",
  "origins": [
    "https://accounts.example.com/",
    "https://login.example.com/",
    "https://auth.example.com/"
  ],
  "names": ["session", "xsrf", "access_token"],
  "browsers": ["chrome"],
  "mode": "merge"
}
```

### Response
#### Success Response (200)
- **cookies** (Cookie[]) - An array of Cookie objects matching any of the specified origins and criteria.

### Response Example
```json
{
  "cookies": [
    { "name": "session", "value": "abc123...", "domain": "app.example.com", "path": "/" },
    { "name": "xsrf", "value": "def456...", "domain": "accounts.example.com", "path": "/" },
    { "name": "access_token", "value": "ghi789...", "domain": "login.example.com", "path": "/" }
  ]
}
```
```

--------------------------------

### Library Usage: Target Specific Chromium Browser on macOS

Source: https://github.com/steipete/sweet-cookie/blob/main/README.md

Demonstrates how to specify a particular Chromium-family browser on macOS when using the 'chrome' backend for cookie extraction.

```typescript
await getCookies({
	url: "https://example.com/",
	browsers: ["chrome"],
	chromiumBrowser: "arc", // 'chrome' | 'brave' | 'arc' | 'chromium'
});
```

--------------------------------

### Library API - toCookieHeader

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/spec.md

Converts an array of Cookie objects into a formatted `Cookie` header string.

```APIDOC
## POST /api/cookie-header

### Description
Converts an array of cookie objects into a single string suitable for the `Cookie` HTTP header.

### Method
POST

### Endpoint
/api/cookie-header

### Parameters
#### Request Body
- **cookies** (Cookie[]) - Required - An array of cookie objects to format.
- **options** (object) - Optional - Formatting options.

### Request Example
```json
{
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123xyz",
      "domain": ".example.com",
      "path": "/"
    },
    {
      "name": "user_pref",
      "value": "dark_mode",
      "domain": "example.com",
      "path": "/settings"
    }
  ]
}
```

### Response
#### Success Response (200)
- **cookieHeader** (string) - The formatted `Cookie` header string.

#### Response Example
```
"session_id=abc123xyz; path=/; domain=.example.com, user_pref=dark_mode; path=/settings; domain=example.com"
```
```

--------------------------------

### Library API - getCookies

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/spec.md

The main function to retrieve cookies from specified sources.

```APIDOC
## GET /api/cookies

### Description
Retrieves cookies based on the provided options. It can fetch cookies from local browsers or inline sources.

### Method
GET

### Endpoint
/api/cookies

### Parameters
#### Query Parameters
- **url** (string) - Required - The primary target URL for filtering cookies.
- **origins** (string[]) - Optional - Additional origins to consider for cookie retrieval.
- **names** (string[]) - Optional - An allowlist of cookie names to retrieve.
- **browsers** (string[]) - Optional - An ordered list of browser sources to check (e.g., `chrome`, `edge`, `safari`, `firefox`).
- **mode** (string) - Optional - Specifies how to handle multiple cookies for the same domain: `merge` (default) or `first`.
- **profile** (string) - Optional - The name or path of the Chrome profile to use.
- **chromeProfile** (string) - Optional - Explicitly specify the Chrome profile name or path.
- **edgeProfile** (string) - Optional - The name or path of the Edge profile to use.
- **firefoxProfile** (string) - Optional - The name or path of the Firefox profile to use.
- **safariCookiesFile** (string) - Optional - Override the default path to the Safari `Cookies.binarycookies` file.
- **timeoutMs** (number) - Optional - Timeout in milliseconds for OS helper operations (keychain, keyring, DPAPI).
- **debug** (boolean) - Optional - Enable extra provider warnings (does not include raw values).
- **includeExpired** (boolean) - Optional - Whether to include expired cookies in the results.
- **inlineCookiesJson** (string) - Optional - Inline cookies provided as a JSON string.
- **inlineCookiesBase64** (string) - Optional - Inline cookies provided as a Base64 encoded string.
- **inlineCookiesFile** (string) - Optional - Path to a file containing inline cookies.

### Response
#### Success Response (200)
- **cookies** (Cookie[]) - An array of cookie objects.
- **warnings** (string[]) - An array of warnings encountered during cookie retrieval.

#### Response Example
```json
{
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123xyz",
      "domain": ".example.com",
      "path": "/",
      "expires": 1700000000,
      "secure": true,
      "httpOnly": false,
      "sameSite": "Lax",
      "source": {
        "browser": "chrome",
        "profile": "Default"
      }
    }
  ],
  "warnings": []
}
```
```

--------------------------------

### Configure Cookie Merge Modes

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Control how results from multiple browsers are combined using the mode option. Use 'merge' to deduplicate results or 'first' to stop after the first successful provider.

```typescript
import { getCookies } from "@steipete/sweet-cookie";

// mode: "merge" (default) - Combine cookies from all browsers, dedupe by name+domain+path
const { cookies: mergedCookies } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome", "firefox", "safari"],
  mode: "merge",
});

// mode: "first" - Return cookies from the first browser that yields results
const { cookies: firstCookies } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome", "firefox", "safari"],
  mode: "first", // Stops after Chrome if Chrome has cookies
});

// Useful when you only need cookies from one browser and want to fail fast
const { cookies, warnings } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome"],
  mode: "first",
  timeoutMs: 5000, // Timeout for keychain/keyring access
});
```

--------------------------------

### Target Specific Browser Profiles

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Specify profile names or directory paths to target cookies from specific browser instances.

```typescript
import { getCookies } from "@steipete/sweet-cookie";

// Target a specific Chrome profile by name
const { cookies: chromeDefault } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome"],
  chromeProfile: "Default", // Profile directory name
});

// Target a specific Chrome profile by full path
const { cookies: chromeCustom } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome"],
  chromeProfile: "/Users/me/Library/Application Support/Google/Chrome/Profile 2",
});

// Target a specific Edge profile
const { cookies: edgeCookies } = await getCookies({
  url: "https://example.com/",
  browsers: ["edge"],
  edgeProfile: "Default",
});

// Target a specific Firefox profile
const { cookies: firefoxCookies } = await getCookies({
  url: "https://example.com/",
  browsers: ["firefox"],
  firefoxProfile: "default-release", // Profile name or directory path
});
```

--------------------------------

### Convert Cookies to HTTP Header with TypeScript

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Use toCookieHeader to format an array of cookies into a string for the Cookie header, with options for deduplication and sorting.

```typescript
import { getCookies, toCookieHeader } from "@steipete/sweet-cookie";

const { cookies } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome"],
});

// Basic usage - sorted by name
const header = toCookieHeader(cookies);
// Output: "csrf=xyz789; session=abc123"

// Deduplicate by name (keeps first occurrence)
const dedupedHeader = toCookieHeader(cookies, { dedupeByName: true });
// Output: "csrf=xyz789; session=abc123"

// Preserve original order (no sorting)
const unsortedHeader = toCookieHeader(cookies, { sort: "none" });
// Output: "session=abc123; csrf=xyz789" (original order)

// Combined options
const finalHeader = toCookieHeader(cookies, {
  dedupeByName: true,
  sort: "name",
});

// Use with fetch
const response = await fetch("https://api.example.com/data", {
  headers: {
    Cookie: finalHeader,
  },
});
```

--------------------------------

### toCookieHeader

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Converts an array of cookie objects into a formatted HTTP Cookie header string.

```APIDOC
## toCookieHeader

### Description
Converts an array of cookies into an HTTP `Cookie` header string, with optional deduplication and sorting.

### Parameters
#### Request Body
- **cookies** (Array<Cookie>) - Required - The array of cookie objects to convert.
- **options** (Object) - Optional - Configuration options for the output.
  - **dedupeByName** (boolean) - Optional - If true, keeps only the first occurrence of a cookie name.
  - **sort** (string) - Optional - Sorting strategy: "name" or "none". Defaults to "name".

### Request Example
```typescript
const header = toCookieHeader(cookies, { dedupeByName: true, sort: "name" });
```

### Response
#### Success Response (200)
- **string** - The formatted Cookie header string.
```

--------------------------------

### Target Chromium Browsers on macOS

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Specify a chromiumBrowser to avoid multiple keychain prompts on macOS. Without this, the library may check multiple browser roots by default.

```typescript
import { getCookies } from "@steipete/sweet-cookie";

// Target Brave browser specifically on macOS
const { cookies: braveCookies } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome"],
  chromiumBrowser: "brave", // 'chrome' | 'brave' | 'arc' | 'chromium'
});

// Target Arc browser
const { cookies: arcCookies } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome"],
  chromiumBrowser: "arc",
});

// Without chromiumBrowser, macOS checks Chrome and Brave roots by default
const { cookies: defaultCookies } = await getCookies({
  url: "https://example.com/",
  browsers: ["chrome"],
  // Will try Chrome first, then Brave
});
```

--------------------------------

### Extract Cookies for Multiple Origins

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Configure multi-origin extraction to support OAuth and SSO flows where authentication spans several domains.

```typescript
import { getCookies } from "@steipete/sweet-cookie";

// Multi-origin extraction for OAuth/SSO flows
const { cookies } = await getCookies({
  url: "https://app.example.com/",
  origins: [
    "https://accounts.example.com/",
    "https://login.example.com/",
    "https://auth.example.com/",
  ],
  names: ["session", "xsrf", "access_token"],
  browsers: ["chrome"],
  mode: "merge", // Combine cookies from all browsers (default)
});

// All cookies matching any of the specified origins are returned
console.log(`Found ${cookies.length} cookies across ${new Set(cookies.map(c => c.domain)).size} domains`);
```

--------------------------------

### Extract Cookies from Browsers

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Use getCookies to retrieve specific cookies from local browser databases. The function returns both the cookie data and any non-fatal warnings encountered during extraction.

```typescript
import { getCookies } from "@steipete/sweet-cookie";

// Basic usage - extract specific cookies from local browsers
const { cookies, warnings } = await getCookies({
  url: "https://example.com/",
  names: ["session", "csrf"],
  browsers: ["chrome", "edge", "firefox", "safari"],
});

// Log any warnings (missing keyring tools, schema drift, etc.)
for (const warning of warnings) {
  console.warn(warning);
}

// Output: Array of Cookie objects
// [
//   {
//     name: "session",
//     value: "abc123...",
//     domain: "example.com",
//     path: "/",
//     expires: 1767225600,
//     secure: true,
//     httpOnly: true,
//     sameSite: "Lax",
//     source: { browser: "chrome", profile: "Default" }
//   },
//   { name: "csrf", value: "xyz789...", domain: "example.com", path: "/" }
// ]
```

--------------------------------

### getCookies - Extract Cookies from Browsers

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Extracts cookies from specified browsers and/or inline payloads, with options to filter by URL, origin, and cookie names.

```APIDOC
## GET /getCookies

### Description
Extracts cookies from one or more browser backends and/or inline payloads. Returns cookies filtered by URL/origins and an optional name allowlist, along with non-fatal warnings from providers.

### Method
GET

### Endpoint
/getCookies

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to filter cookies by.
- **names** (string[]) - Optional - An array of cookie names to allowlist.
- **browsers** (string[]) - Optional - An array of browser identifiers (e.g., "chrome", "edge", "firefox", "safari") to extract cookies from. Defaults to all supported browsers.
- **origins** (string[]) - Optional - An array of additional origins to extract cookies from, useful for OAuth/SSO flows.
- **chromeProfile** (string) - Optional - Specifies the Chrome profile directory name or full path.
- **edgeProfile** (string) - Optional - Specifies the Edge profile directory name or full path.
- **firefoxProfile** (string) - Optional - Specifies the Firefox profile directory name or full path.
- **mode** (string) - Optional - Determines how cookies from multiple origins are handled. "merge" (default) combines all cookies. Other modes might be supported.

### Request Example
```json
{
  "url": "https://example.com/",
  "names": ["session", "csrf"],
  "browsers": ["chrome", "edge", "firefox", "safari"]
}
```

### Response
#### Success Response (200)
- **cookies** (Cookie[]) - An array of Cookie objects matching the criteria.
- **warnings** (string[]) - An array of non-fatal warnings encountered during extraction.

### Response Example
```json
{
  "cookies": [
    {
      "name": "session",
      "value": "abc123...",
      "domain": "example.com",
      "path": "/",
      "expires": 1767225600,
      "secure": true,
      "httpOnly": true,
      "sameSite": "Lax",
      "source": { "browser": "chrome", "profile": "Default" }
    },
    { "name": "csrf", "value": "xyz789...", "domain": "example.com", "path": "/" }
  ],
  "warnings": ["Keyring tool not found for Linux", "Firefox profile schema has drifted"]
}
```
```

--------------------------------

### Define CDP-Compatible Cookie Objects

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Utilize the Cookie interface for type-safe cookie handling, compatible with Chrome DevTools Protocol structures.

```typescript
import type { Cookie, BrowserName, CookieSameSite } from "@steipete/sweet-cookie";

// Full Cookie interface
const cookie: Cookie = {
  name: "session",           // Required: cookie name
  value: "abc123xyz",        // Required: cookie value (may be empty string)
  domain: "example.com",     // Optional: hostname without leading dot
  path: "/",                 // Optional: defaults to "/" when omitted
  url: "https://example.com", // Optional: useful for host-only cookies
  expires: 1767225600,       // Optional: Unix timestamp in seconds (omit for session)
  secure: true,              // Optional: HTTPS only
  httpOnly: true,            // Optional: not accessible to JavaScript
  sameSite: "Lax",           // Optional: "Strict" | "Lax" | "None"
  source: {                  // Optional: provenance metadata
    browser: "chrome",       // Which browser: "chrome" | "edge" | "firefox" | "safari"
    profile: "Default",      // Optional: profile identifier
    origin: "https://example.com", // Optional: origin that produced this cookie
    storeId: "0",            // Optional: cookie store identifier
  },
};

// Type definitions
type BrowserName = "chrome" | "edge" | "firefox" | "safari";
type CookieSameSite = "Strict" | "Lax" | "None";
```

--------------------------------

### Inject Inline Cookies

Source: https://context7.com/steipete/sweet-cookie/llms.txt

Provide cookies directly via JSON, base64 strings, or file paths to bypass browser database access. This is useful for reliability when using exports from the companion Chrome extension.

```typescript
import { getCookies } from "@steipete/sweet-cookie";

// From JSON string (Cookie[] or { cookies: Cookie[] } format)
const { cookies: jsonCookies } = await getCookies({
  url: "https://chatgpt.com/",
  inlineCookiesJson: JSON.stringify({
    cookies: [
      { name: "session", value: "abc123", domain: "chatgpt.com", path: "/" },
      { name: "csrf", value: "xyz789", domain: "chatgpt.com", path: "/" },
    ],
  }),
  browsers: ["chrome"], // Skipped when inline yields cookies
});

// From base64-encoded JSON (clipboard-friendly from extension)
const base64Payload = Buffer.from(JSON.stringify({
  cookies: [{ name: "session", value: "abc123", domain: "chatgpt.com", path: "/" }]
})).toString("base64");

const { cookies: base64Cookies } = await getCookies({
  url: "https://chatgpt.com/",
  inlineCookiesBase64: base64Payload,
});

// From file path (exported from extension)
const { cookies: fileCookies } = await getCookies({
  url: "https://chatgpt.com/",
  inlineCookiesFile: "/path/to/exported-cookies.json",
});
```

--------------------------------

### Inline Cookie Payload Schema

Source: https://context7.com/steipete/sweet-cookie/llms.txt

This JSON schema represents cookies exported from a Chrome MV3 extension. It includes metadata about the export and a list of cookies with their properties.

```json
{
  "version": 1,
  "generatedAt": "2025-12-27T18:00:00.000Z",
  "source": "sweet-cookie",
  "browser": "chrome",
  "targetUrl": "https://chatgpt.com/",
  "origins": ["https://chatgpt.com/"],
  "cookies": [
    {
      "name": "__Secure-next-auth.session-token",
      "value": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0...",
      "domain": "chatgpt.com",
      "path": "/",
      "secure": true,
      "httpOnly": true,
      "sameSite": "Lax",
      "expires": 1767225600
    },
    {
      "name": "cf_clearance",
      "value": "abc123...",
      "domain": ".chatgpt.com",
      "path": "/",
      "secure": true,
      "httpOnly": true,
      "sameSite": "None",
      "expires": 1735660800
    }
  ]
}
```

--------------------------------

### JSON Cookie Export Structure

Source: https://github.com/steipete/sweet-cookie/blob/main/docs/spec.md

This JSON structure represents exported cookies, including metadata and an array of cookie objects. The 'expires' field should be in Unix seconds when available, and omitted for session cookies.

```json
{
	"version": 1,
	"generatedAt": "2025-12-27T18:00:00.000Z",
	"source": "sweet-cookie",
	"browser": "chrome",
	"targetUrl": "https://chatgpt.com/",
	"origins": ["https://chatgpt.com/"],
	"cookies": [
		{
			"name": "__Secure-next-auth.session-token",
			"value": "…",
			"domain": "chatgpt.com",
			"path": "/",
			"secure": true,
			"httpOnly": true,
			"sameSite": "Lax",
			"expires": 1767225600
		}
	]
}
```
Tokens:
Raw