feat: smart-link resolve, direct downloads, and Bandcamp album track pick

README.md

@@ -1,10 +1,10 @@
 # sc-gate-dl
 
-Download and tag SoundCloud tracks unlocked via Hypeddit, Droploud, GateRush, DownloadGater, or Bandcamp.
+Download and tag SoundCloud tracks unlocked via Hypeddit, Droploud, GateRush, DownloadGater, Bandcamp, or a direct download link.
 
 ## Features
 
-- 🎵 Automatically download audio from Hypeddit, Droploud, GateRush, DownloadGater, and Bandcamp links
+- 🎵 Automatically download audio from Hypeddit, Droploud, GateRush, DownloadGater, Bandcamp, and direct file links (e.g. Dropbox `dl=1`)
 - ⚡ Browserless fast path that skips the browser for gates that don't need real verification (see [How It Works](#how-it-works))
 - 🔄 Handles multiple gate types (see [How It Works](#how-it-works))
 - 📝 Fetches metadata from the provided SoundCloud link
@@ -190,7 +190,9 @@ Panel size/position is remembered in `localStorage` (`sc-gate-dl-panel-geom`).
 
 Droploud, GateRush, and DownloadGater gates are handled via their own downloaders with similar email / social unlock flows.
 
-**Bandcamp / yt-dlp**: When a SoundCloud track’s purchase URL (or description) points at Bandcamp instead of a gate, the file is downloaded with [yt-dlp](https://github.com/yt-dlp/yt-dlp) (browserless). For Bandcamp album links, the matching track is selected from the SoundCloud title. Traditional unlock gates still take priority if both are present. If no gate or Bandcamp URL is found, the CLI and Web UI can fall back to downloading the SoundCloud track itself via yt-dlp.
+**Bandcamp / yt-dlp**: When a SoundCloud track’s purchase URL (or description) points at Bandcamp instead of a gate, the file is downloaded with [yt-dlp](https://github.com/yt-dlp/yt-dlp) (browserless). For Bandcamp album links, the matching track is selected from the SoundCloud title; if auto-match fails, the CLI and Web UI let you pick a track from the album. Traditional unlock gates still take priority if both are present. If no gate or Bandcamp URL is found, the CLI and Web UI can fall back to downloading the SoundCloud track itself via yt-dlp.
+
+**Direct download**: Paste a file URL (Dropbox with `dl=1`, Google Drive file links, or any http(s) URL ending in a common audio/archive extension). The file is fetched browserlessly — useful when a gate is unsupported but you already have the download link.
 
 **File Processing**:
 

src/browserLaunch.ts

@@ -4,13 +4,14 @@ import type { Browser } from 'puppeteer';
 export type AppBrowserLaunchOptions = {
 	headless?: boolean;
 	userDataDir?: string;
+	/** Extra Chromium/CloakBrowser flags merged onto the defaults. */
 	args?: string[];
 	/** Passed through to Puppeteer via cloakbrowser `launchOptions`. */
 	defaultViewport?: { width: number; height: number } | null;
 	humanize?: boolean;
 };
 
-const DEFAULT_ARGS = [
+export const DEFAULT_BROWSER_ARGS = [
 	'--no-sandbox',
 	'--disable-setuid-sandbox',
 	'--mute-audio',
@@ -38,12 +39,14 @@ export async function launchAppBrowser(
 
 	const geoip = Boolean(proxy) && process.env.CLOAKBROWSER_GEOIP === 'true';
 
+	const args = [...DEFAULT_BROWSER_ARGS, ...(options.args ?? [])];
+
 	const launchOpts = {
 		headless: options.headless ?? true,
 		humanize: options.humanize ?? true,
 		stealthArgs: true,
 		...(proxy ? { proxy, ...(geoip ? { geoip: true } : {}) } : {}),
-		args: options.args ?? DEFAULT_ARGS,
+		args,
 		launchOptions: {
 			...(options.defaultViewport !== undefined
 				? { defaultViewport: options.defaultViewport }

src/directDownload.ts

@@ -0,0 +1,199 @@
+import { mkdir, unlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import {
+	normalizeDirectDownloadParsedUrl,
+	urlLooksLikeDirectDownload,
+} from './directLinkRules';
+import type { ProgressCallback } from './hypeddit';
+import { safeFetch } from './safeOutboundUrl';
+import { sanitizeFilenamePart, trimExtractedUrl } from './utils';
+
+const USER_AGENT =
+	'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+
+const FETCH_TIMEOUT_MS = 60_000;
+const MAX_REDIRECTS = 10;
+/** Cap downloads (audio / zip packages). */
+const MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024;
+
+/**
+ * True for http(s) URLs that look like a direct file download (Dropbox, Drive,
+ * or a path with a common audio/archive extension) — not HTML gate pages.
+ */
+export function isDirectDownloadUrl(value: string): boolean {
+	try {
+		return urlLooksLikeDirectDownload(new URL(trimExtractedUrl(value.trim())));
+	} catch {
+		return false;
+	}
+}
+
+/** Normalize share links so fetch gets the file bytes (e.g. Dropbox dl=0 → dl=1). */
+export function normalizeDirectDownloadUrl(url: string): string {
+	const trimmed = trimExtractedUrl(url.trim());
+	try {
+		return normalizeDirectDownloadParsedUrl(new URL(trimmed));
+	} catch {
+		return trimmed;
+	}
+}
+
+function filenameFromContentDisposition(value: string | null): string | null {
+	if (!value) return null;
+	const star = value.match(/filename\*=(?:UTF-8'')?([^;]+)/i)?.[1];
+	if (star) {
+		return decodeURIComponent(star.replace(/["']/g, ''));
+	}
+	const plain = value.match(/filename=["']?([^"';]+)["']?/i)?.[1];
+	return plain ? plain.trim() : null;
+}
+
+function safeDownloadFilename(raw: string | null): string | null {
+	if (!raw) return null;
+	const base = basename(raw);
+	const cleaned = sanitizeFilenamePart(base);
+	return cleaned || null;
+}
+
+async function writeBodyWithSizeLimit(
+	body: ReadableStream<Uint8Array>,
+	target: string,
+	maxBytes: number,
+): Promise<void> {
+	const writer = Bun.file(target).writer();
+	const reader = body.getReader();
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			total += value.byteLength;
+			if (total > maxBytes) {
+				await reader.cancel();
+				throw new Error(
+					`Direct download too large (${total} bytes; max ${maxBytes})`,
+				);
+			}
+			writer.write(value);
+		}
+		await writer.end();
+	} catch (error) {
+		try {
+			writer.end();
+		} catch {
+			// ignore
+		}
+		await unlink(target).catch(() => {});
+		throw error;
+	}
+}
+
+export class DirectDownloader {
+	private progressCallback: ProgressCallback | null = null;
+
+	setProgressCallback(callback: ProgressCallback): void {
+		this.progressCallback = callback;
+	}
+
+	async downloadAudio(url: string): Promise<string> {
+		const downloadUrl = normalizeDirectDownloadUrl(url);
+		console.log(`Downloading direct file: ${downloadUrl}`);
+		this.progressCallback?.('downloading', 'Downloading direct file...', 40, {
+			browserless: true,
+		});
+
+		await mkdir('./downloads', { recursive: true });
+
+		let current = downloadUrl;
+		let response: Response | null = null;
+		let finalUrl = current;
+
+		for (let hop = 0; hop < MAX_REDIRECTS; hop++) {
+			const result = await safeFetch(current, {
+				signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+				headers: {
+					'user-agent': USER_AGENT,
+					accept: '*/*',
+				},
+			});
+			finalUrl = result.url;
+			response = result.response;
+
+			if (response.status >= 300 && response.status < 400) {
+				const location = response.headers.get('location');
+				await response.body?.cancel().catch(() => {});
+				if (!location) {
+					throw new Error(
+						`Direct download redirect missing Location from ${current}`,
+					);
+				}
+				current = new URL(location, current).toString();
+				continue;
+			}
+			break;
+		}
+
+		if (!response) {
+			throw new Error(`Direct download failed for ${downloadUrl}`);
+		}
+		if (response.status >= 300 && response.status < 400) {
+			throw new Error(
+				`Direct download exceeded ${MAX_REDIRECTS} redirects for ${downloadUrl}`,
+			);
+		}
+		if (!response.ok) {
+			throw new Error(
+				`Direct download failed: HTTP ${response.status} for ${finalUrl}`,
+			);
+		}
+
+		const contentType = response.headers.get('content-type') ?? '';
+		if (/text\/html/i.test(contentType)) {
+			await response.body?.cancel().catch(() => {});
+			throw new Error(
+				'Direct download returned HTML instead of a file — check that the link is a direct download (e.g. Dropbox with dl=1).',
+			);
+		}
+
+		const contentLengthHeader = response.headers.get('content-length');
+		if (contentLengthHeader) {
+			const contentLength = Number(contentLengthHeader);
+			if (
+				Number.isFinite(contentLength) &&
+				contentLength > MAX_DOWNLOAD_BYTES
+			) {
+				await response.body?.cancel().catch(() => {});
+				throw new Error(
+					`Direct download too large (${contentLength} bytes; max ${MAX_DOWNLOAD_BYTES})`,
+				);
+			}
+		}
+
+		const fromHeader = safeDownloadFilename(
+			filenameFromContentDisposition(
+				response.headers.get('content-disposition'),
+			),
+		);
+		const urlName = safeDownloadFilename(
+			decodeURIComponent(basename(new URL(finalUrl).pathname)),
+		);
+		const filename =
+			fromHeader ||
+			(urlName && urlName !== '/'
+				? urlName
+				: `direct-download-${Date.now()}.bin`);
+
+		if (!response.body) {
+			throw new Error(`Direct download returned an empty body for ${finalUrl}`);
+		}
+
+		const target = join('./downloads', filename);
+		await writeBodyWithSizeLimit(response.body, target, MAX_DOWNLOAD_BYTES);
+		console.log(`Saved ${filename}`);
+		return filename;
+	}
+
+	async close(): Promise<void> {
+		// no-op (browserless)
+	}
+}

src/directLinkRules.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared direct-download URL rules (no imports from utils / downloaders) so
+ * matchers and the downloader cannot drift apart.
+ */
+
+export const AUDIO_OR_ARCHIVE_EXT_RE =
+	/\.(mp3|wav|flac|aiff|aif|m4a|aac|ogg|opus|zip|rar)(\?|$)/i;
+
+/** Google Drive file IDs are long URL-safe tokens. */
+const DRIVE_FILE_ID_RE = /^[a-zA-Z0-9_-]{10,}$/;
+
+export function isKnownDirectDownloadHost(hostname: string): boolean {
+	const host = hostname.toLowerCase();
+	return (
+		/(?:^|\.)dropbox\.com$/i.test(host) ||
+		/(?:^|\.)dropboxusercontent\.com$/i.test(host) ||
+		/(?:^|\.)drive\.google\.com$/i.test(host)
+	);
+}
+
+/** Extract a validated Drive file id from path (`/file/d/ID`) or `id` query. */
+export function extractDriveFileId(url: URL): string | null {
+	const fromPath = url.pathname.match(/\/file\/d\/([^/]+)/)?.[1];
+	if (fromPath && DRIVE_FILE_ID_RE.test(fromPath)) return fromPath;
+	const fromQuery = url.searchParams.get('id');
+	if (fromQuery && DRIVE_FILE_ID_RE.test(fromQuery)) return fromQuery;
+	return null;
+}
+
+/** True when a parsed URL looks like a direct file link, not an HTML gate page. */
+export function urlLooksLikeDirectDownload(url: URL): boolean {
+	if (!/^https?:$/i.test(url.protocol)) return false;
+	const host = url.hostname.toLowerCase();
+	if (
+		/(?:^|\.)dropbox\.com$/i.test(host) ||
+		/(?:^|\.)dropboxusercontent\.com$/i.test(host)
+	) {
+		return true;
+	}
+	if (/(?:^|\.)drive\.google\.com$/i.test(host)) {
+		return extractDriveFileId(url) !== null;
+	}
+	if (AUDIO_OR_ARCHIVE_EXT_RE.test(url.pathname)) return true;
+	return false;
+}
+
+/**
+ * Normalize share links so fetch gets the file bytes.
+ * Dropbox: force `dl=1` (rewrites `dl=0` preview links and adds `dl` when missing).
+ * Drive: only rewrite when a valid file id is present.
+ */
+export function normalizeDirectDownloadParsedUrl(url: URL): string {
+	if (/(?:^|\.)dropbox\.com$/i.test(url.hostname)) {
+		const parsed = new URL(url.toString());
+		parsed.searchParams.set('dl', '1');
+		return parsed.toString();
+	}
+	if (/(?:^|\.)drive\.google\.com$/i.test(url.hostname)) {
+		const id = extractDriveFileId(url);
+		if (!id) {
+			throw new Error(
+				`Malformed Google Drive link (missing valid file id): ${url}`,
+			);
+		}
+		const download = new URL('https://drive.google.com/uc');
+		download.searchParams.set('export', 'download');
+		download.searchParams.set('id', id);
+		// Link-shared files may require resourcekey alongside the file id.
+		let resourceKey: string | null = null;
+		for (const [key, value] of url.searchParams) {
+			if (key.toLowerCase() === 'resourcekey' && value) {
+				resourceKey = value;
+				break;
+			}
+		}
+		if (resourceKey) {
+			download.searchParams.set('resourcekey', resourceKey);
+		}
+		return download.toString();
+	}
+	return url.toString();
+}