GallerySubscriber/extension/README.md

GallerySubscriber Browser Extension

A Firefox extension that exports authentication cookies and tokens from supported platforms to the GallerySubscriber backend for automated content downloading.

Features

Cookie Export

Automatically extracts authentication cookies from supported platforms and sends them to your GallerySubscriber backend. This enables gallery-dl to download content that requires login authentication.

Supported Platforms

Platform	Auth Type	How It Works
Patreon	Cookies	Exports session cookies after you log in
SubscribeStar	Cookies	Exports session cookies (supports both .com and .adult domains)
Hentai-Foundry	Cookies	Exports session cookies after you log in
Discord	Token	Captures authorization token from API requests

Discord Token Capture

Unlike other platforms that use cookies, Discord requires an authorization token. The extension automatically captures this token by monitoring Discord API requests when you use Discord in your browser. Simply:

1. Open Discord in Firefox
2. Interact with it (switch channels, send a message, etc.)
3. The extension captures and stores your token automatically

Dark/Light Theme Support

The extension automatically matches your system's color scheme preference:

• Detects prefers-color-scheme media query
• Supports manual theme override via data-theme attribute
• Consistent theming across popup and options pages

Installation

Temporary Installation (Development)

1. Open Firefox and navigate to about:debugging#/runtime/this-firefox
2. Click "Load Temporary Add-on"
3. Select any file in the extension folder (e.g., manifest.json)

Permanent Installation (Unsigned)

Requires Firefox Developer Edition or Nightly:

1. Navigate to about:config
2. Set xpinstall.signatures.required to false
3. Go to about:addons → gear icon → "Install Add-on From File"
4. Select gallerysubscriber.xpi

Permanent Installation (Signed)

1. Create an account at addons.mozilla.org
2. Use web-ext sign to sign the extension
3. Install the signed .xpi file

Configuration

Initial Setup

1. Click the extension icon in the toolbar
2. Click "Open Settings" or the gear icon
3. Enter your GallerySubscriber backend URL (e.g., http://localhost:8000)
4. Enter your API key (found in GallerySubscriber web UI → Settings)
5. Click "Test Connection" to verify
6. Click "Save"

Options Page Settings

• API URL: The base URL of your GallerySubscriber backend
• API Key: Authentication key for the extension API

Usage

Exporting Cookies for a Single Platform

1. Log into the platform in Firefox (e.g., patreon.com)
2. Click the GallerySubscriber extension icon
3. Click on the platform card
4. Cookies are exported to the backend

Exporting All Platforms

1. Ensure you're logged into all desired platforms
2. Click the extension icon
3. Click "Export All Platforms"
4. All available cookies/tokens are exported

Checking Platform Status

The popup shows the status of each platform:

• "X cookies ready" - Cookies found, ready to export
• "No cookies found" - Not logged in or cookies expired
• "Token captured" - Discord token available
• "Open Discord in browser" - Need to use Discord to capture token

Architecture

extension/
├── manifest.json          # Extension manifest (Manifest V2)
├── background/
│   └── background.js      # Background script - handles API calls & cookie extraction
├── popup/
│   ├── popup.html         # Popup UI
│   ├── popup.js           # Popup logic
│   └── popup.css          # Popup styles with theme support
├── options/
│   └── options.html       # Settings page (inline CSS/JS)
├── lib/
│   ├── platforms.js       # Platform definitions and configuration
│   ├── cookies.js         # Cookie extraction utilities
│   └── api.js             # Backend API client
└── icons/
    └── icon.svg           # Extension icon

Permissions

The extension requires the following permissions:

Permission	Purpose
cookies	Read cookies from supported platform domains
storage	Store API configuration and Discord token
tabs	Access active tab information
activeTab	Interact with the current tab
webRequest	Monitor Discord API requests to capture token
*://*.patreon.com/*	Access Patreon cookies
*://*.subscribestar.com/*	Access SubscribeStar cookies
*://*.subscribestar.adult/*	Access SubscribeStar Adult cookies
*://*.hentai-foundry.com/*	Access Hentai-Foundry cookies
*://*.discord.com/*	Monitor Discord API for token capture

API Endpoints Used

The extension communicates with these GallerySubscriber backend endpoints:

Endpoint	Method	Purpose
/api/health	GET	Connection test
/api/credentials	POST	Upload cookies/tokens

Troubleshooting

Extension shows "Setup Required"

• Open settings and configure the API URL and key
• Ensure the backend is running and accessible

Connection test fails

• Verify the API URL is correct (include protocol, e.g., http://)
• Check that the backend is running
• Verify the API key matches the one in GallerySubscriber settings

"No cookies found" for a platform

• Ensure you're logged into the platform in Firefox
• Try logging out and back in
• Clear cookies and re-authenticate

Discord token not captured

• Open discord.com in Firefox (not the desktop app)
• Interact with Discord (switch channels, scroll, etc.)
• The token is captured from API requests automatically

Popup is blank or slow

• Check the browser console for errors (about:debugging → Inspect)
• The extension caches connection status for 2 minutes to improve performance

Privacy & Security

• Cookies and tokens are sent only to your configured backend URL
• No data is sent to third parties
• API key is stored locally in browser storage
• Discord tokens are stored locally and only sent to your backend when you export

Version History

1.0.0

• Initial release
• Support for Patreon, SubscribeStar, Hentai-Foundry, Discord
• Dark/light theme support
• Connection caching for improved performance