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
@@ -192,6 +192,8 @@ Droploud, GateRush, and DownloadGater gates are handled via their own downloader
 
 **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.
 
+**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**:
 
 - **Lossless (WAV/AIFF/FLAC) files**: Converted to MP3 (320kbps) with metadata and artwork

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,124 @@
+import { mkdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import type { ProgressCallback } from './hypeddit';
+import { 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 AUDIO_OR_ARCHIVE_EXT_RE =
+	/\.(mp3|wav|flac|aiff|aif|m4a|aac|ogg|opus|zip|rar)(\?|$)/i;
+
+/**
+ * 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 {
+		const url = new URL(trimExtractedUrl(value.trim()));
+		if (!/^https?:$/i.test(url.protocol)) return false;
+
+		const host = url.hostname.toLowerCase();
+		if (/(?:^|\.)dropbox\.com$/i.test(host)) return true;
+		if (/(?:^|\.)dropboxusercontent\.com$/i.test(host)) return true;
+		if (/(?:^|\.)drive\.google\.com$/i.test(host)) return true;
+		if (/(?:^|\.)docs\.google\.com$/i.test(host)) return true;
+
+		if (AUDIO_OR_ARCHIVE_EXT_RE.test(url.pathname)) return true;
+		if (url.searchParams.get('dl') === '1') return true;
+		if (url.searchParams.has('raw')) return true;
+
+		return false;
+	} catch {
+		return false;
+	}
+}
+
+/** Normalize share links so fetch gets the file bytes (e.g. Dropbox dl=1). */
+export function normalizeDirectDownloadUrl(url: string): string {
+	const trimmed = trimExtractedUrl(url.trim());
+	try {
+		const parsed = new URL(trimmed);
+		if (/(?:^|\.)dropbox\.com$/i.test(parsed.hostname)) {
+			parsed.searchParams.set('dl', '1');
+			return parsed.toString();
+		}
+		// Google Drive file view → uc?export=download
+		const driveFile = parsed.pathname.match(/\/file\/d\/([^/]+)/);
+		if (
+			/(?:^|\.)drive\.google\.com$/i.test(parsed.hostname) &&
+			driveFile?.[1]
+		) {
+			return `https://drive.google.com/uc?export=download&id=${driveFile[1]}`;
+		}
+		return parsed.toString();
+	} 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;
+}
+
+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 });
+		const response = await fetch(downloadUrl, {
+			redirect: 'follow',
+			headers: {
+				'user-agent': USER_AGENT,
+				accept: '*/*',
+			},
+		});
+		if (!response.ok) {
+			throw new Error(
+				`Direct download failed: HTTP ${response.status} for ${downloadUrl}`,
+			);
+		}
+
+		const contentType = response.headers.get('content-type') ?? '';
+		if (/text\/html/i.test(contentType)) {
+			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 fromHeader = filenameFromContentDisposition(
+			response.headers.get('content-disposition'),
+		);
+		const urlName = basename(new URL(response.url).pathname);
+		const filename =
+			fromHeader ||
+			(urlName && urlName !== '/'
+				? decodeURIComponent(urlName)
+				: `direct-download-${Date.now()}.bin`);
+
+		const target = join('./downloads', filename);
+		await Bun.write(target, await response.arrayBuffer());
+		console.log(`Saved ${filename}`);
+		return filename;
+	}
+
+	async close(): Promise<void> {
+		// no-op (browserless)
+	}
+}

src/index.ts

@@ -1,6 +1,7 @@
 import { confirm, input, select } from '@inquirer/prompts';
 import { AudioProcessor } from './audioProcessor';
 import { loadConfig, saveConfig } from './config';
+import { DirectDownloader } from './directDownload';
 import { DownloadgaterDownloader } from './downloadgater';
 import { DroploudDownloader } from './droploud';
 import { GaterushDownloader } from './gaterush';
@@ -10,7 +11,7 @@ import { SoundcloudClient } from './soundcloud';
 import {
 	getFfmpegBin,
 	getFfprobeBin,
-	resolveGateProviderUrl,
+	resolveGateUrlOrFollow,
 	validateSoundcloudUrl,
 } from './utils';
 import { YtDlpDownloader } from './ytdlp';
@@ -65,7 +66,7 @@ try {
 					value: 'ytdlp' as const,
 				},
 				{
-					name: 'Enter a Hypeddit / Droploud / GateRush / DownloadGater / Bandcamp URL',
+					name: 'Enter a gate / Bandcamp / direct download / resolvable URL',
 					value: 'manual' as const,
 				},
 			],
@@ -77,16 +78,16 @@ try {
 		} else {
 			gateUrl = await input({
 				message:
-					'Enter the Hypeddit, Droploud, GateRush, DownloadGater, or Bandcamp URL',
-				validate: (value) => {
-					const resolved = resolveGateProviderUrl(value);
+					'Enter a Hypeddit, Droploud, GateRush, DownloadGater, Bandcamp, direct download, or smart-link URL',
+				validate: async (value) => {
+					const resolved = await resolveGateUrlOrFollow(value);
 					if (!resolved || resolved.provider === 'soundcloud') {
-						return 'A valid Hypeddit, Droploud, GateRush, DownloadGater, or Bandcamp URL is required';
+						return 'A valid Hypeddit, Droploud, GateRush, DownloadGater, Bandcamp, direct download, or resolvable gate URL is required';
 					}
 					return true;
 				},
 			});
-			const resolved = resolveGateProviderUrl(gateUrl);
+			const resolved = await resolveGateUrlOrFollow(gateUrl);
 			gate =
 				resolved && resolved.provider !== 'soundcloud'
 					? {
@@ -103,14 +104,16 @@ try {
 
 	if (!gateUrl || !gate) {
 		throw new Error(
-			'A valid Hypeddit, Droploud, GateRush, DownloadGater, Bandcamp, or SoundCloud URL is required',
+			'A valid Hypeddit, Droploud, GateRush, DownloadGater, Bandcamp, direct download, or SoundCloud URL is required',
 		);
 	}
 
-	const isYtDlp =
-		gate.provider === 'bandcamp' || gate.provider === 'soundcloud';
+	const isBrowserless =
+		gate.provider === 'bandcamp' ||
+		gate.provider === 'soundcloud' ||
+		gate.provider === 'direct';
 
-	const headless = isYtDlp
+	const headless = isBrowserless
 		? true
 		: config
 			? config.headless
@@ -119,7 +122,7 @@ try {
 					default: true,
 				});
 
-	const initializeLogins = isYtDlp
+	const initializeLogins = isBrowserless
 		? false
 		: config
 			? config.initializeLogins
@@ -146,6 +149,9 @@ try {
 		downloadFilename = await ytDlpDownloader.downloadAudio(gateUrl, {
 			matchTitle: track.title,
 		});
+	} else if (gate.provider === 'direct') {
+		const directDownloader = new DirectDownloader();
+		downloadFilename = await directDownloader.downloadAudio(gateUrl);
 	} else if (gate.provider === 'droploud') {
 		usedBrowser = true;
 		const droploudDownloader = new DroploudDownloader(gateConfig);

src/server.ts

@@ -3,6 +3,7 @@ import { cp, mkdir, rm } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
 import type { SoundcloudTrack } from 'soundcloud.ts';
 import { AudioProcessor } from './audioProcessor';
+import { DirectDownloader } from './directDownload';
 import { DownloadgaterDownloader } from './downloadgater';
 import { renameDownloadFileExclusive } from './downloadRename';
 import { DroploudDownloader } from './droploud';
@@ -14,12 +15,12 @@ import { SoundcloudClient } from './soundcloud';
 import type { Job, Metadata, OutputFormat } from './types';
 import {
 	artistTitleFilename,
-	extractGateUrl,
+	extractAndResolveGateUrl,
 	getDefaultMetadata,
 	getFfmpegBin,
 	getFfprobeBin,
 	isMp3Format,
-	resolveGateProviderUrl,
+	resolveGateUrlOrFollow,
 	validateGateUrl,
 	validateSoundcloudUrl,
 } from './utils';
@@ -180,12 +181,14 @@ async function runDownloadProcess(jobId: string): Promise<void> {
 	const job = jobStore.get(jobId);
 	if (!job?.hypedditUrl) return;
 
-	const gateUrl = job.hypedditUrl;
-	const resolved = resolveGateProviderUrl(gateUrl);
+	const resolved = await resolveGateUrlOrFollow(job.hypedditUrl);
 	if (!resolved) {
 		jobStore.setError(jobId, 'Unsupported gate URL');
 		return;
 	}
+	if (resolved.url !== job.hypedditUrl) {
+		jobStore.update(jobId, { hypedditUrl: resolved.url });
+	}
 	const { url: downloadSourceUrl, provider } = resolved;
 
 	const throwIfCancelled = () => {
@@ -314,6 +317,20 @@ async function runDownloadProcess(jobId: string): Promise<void> {
 			downloadFilename =
 				await downloadgaterDownloader.downloadAudio(downloadSourceUrl);
 			throwIfCancelled();
+		} else if (provider === 'direct') {
+			jobStore.updateProgress(
+				jobId,
+				'downloading',
+				'Downloading direct file...',
+				40,
+				{ browserless: true },
+			);
+			const directDownloader = new DirectDownloader();
+			activeDownloaders.set(jobId, directDownloader);
+			directDownloader.setProgressCallback(emitProgress);
+			downloadFilename =
+				await directDownloader.downloadAudio(downloadSourceUrl);
+			throwIfCancelled();
 		} else {
 			// Hypeddit: always try plain HTTP first (email + social skip gates).
 			jobStore.updateProgress(
@@ -647,7 +664,7 @@ const server = Bun.serve({
 
 					const hypedditUrl = skipAutomaticHypedditFetch
 						? null
-						: extractGateUrl(track);
+						: await extractAndResolveGateUrl(track);
 					const defaultMetadata = getDefaultMetadata(track);
 
 					const updatedJob = jobStore.update(job.id, {
@@ -716,7 +733,7 @@ const server = Bun.serve({
 						return jsonResponse({ error: validation }, { status: 400 });
 					}
 
-					const resolved = resolveGateProviderUrl(hypedditUrl);
+					const resolved = await resolveGateUrlOrFollow(hypedditUrl);
 					if (!resolved) {
 						return jsonResponse(
 							{ error: 'Could not extract a supported URL' },

src/soundcloud.ts

@@ -8,8 +8,8 @@ import Soundcloud, {
 	type SoundcloudUser,
 } from 'soundcloud.ts';
 import {
+	extractAndResolveGateUrl,
 	extractCaptchaDeliveryUrl,
-	extractGateUrl,
 	loadCookies,
 } from './utils';
 
@@ -518,7 +518,7 @@ export class SoundcloudClient {
 	}
 
 	async getGateURL(track: SoundcloudTrack) {
-		const gate = extractGateUrl(track);
+		const gate = await extractAndResolveGateUrl(track);
 		if (!gate) {
 			return null;
 		}
@@ -529,11 +529,13 @@ export class SoundcloudClient {
 					? 'GateRush'
 					: gate.provider === 'downloadgater'
 						? 'DownloadGater'
-						: gate.provider === 'bandcamp'
-							? 'Bandcamp'
-							: gate.provider === 'soundcloud'
-								? 'SoundCloud'
-								: 'Hypeddit';
+						: gate.provider === 'direct'
+							? 'direct download'
+							: gate.provider === 'bandcamp'
+								? 'Bandcamp'
+								: gate.provider === 'soundcloud'
+									? 'SoundCloud'
+									: 'Hypeddit';
 		const sourceLabel =
 			gate.type === 'purchase_url' ? 'purchase URL' : 'description';
 		console.log(