@iflow-mcp/jakeliume-webpeel 0.22.0

package/dist/core/threat-feeds.js

@@ -0,0 +1,104 @@
+/**
+ * Community threat intelligence feeds — cached in-memory, refreshed every 6 hours.
+ *
+ * Sources (all free, no API key):
+ * - URLhaus (abuse.ch): ~150K active malware distribution URLs
+ *   API: https://urlhaus-api.abuse.ch/v1/url/ (POST with url=<url>)
+ * - PhishTank: community-verified phishing URLs
+ *   API: https://checkurl.phishtank.com/checkurl/ (POST with url=<url>&format=json)
+ * - OpenPhish: curated phishing feed
+ *   Feed: https://openphish.com/feed.txt (plain text, one URL per line, ~5K URLs)
+ *
+ * Strategy:
+ * - On startup, fetch OpenPhish feed into a Set (small, fast lookup)
+ * - For URLhaus and PhishTank, do real-time API lookups with 2s timeout
+ * - Cache results for 1 hour to avoid hammering APIs
+ */
+// Cache for URL lookups (avoid re-checking same URL)
+const resultCache = new Map();
+const CACHE_TTL = 3600_000; // 1 hour
+// OpenPhish feed (loaded once, refreshed every 6h)
+let openPhishSet = null;
+let openPhishLastFetch = 0;
+const OPENPHISH_REFRESH = 6 * 3600_000;
+async function loadOpenPhishFeed() {
+    if (openPhishSet && Date.now() - openPhishLastFetch < OPENPHISH_REFRESH) {
+        return openPhishSet;
+    }
+    try {
+        const res = await fetch('https://openphish.com/feed.txt', {
+            signal: AbortSignal.timeout(5000),
+        });
+        if (res.ok) {
+            const text = await res.text();
+            openPhishSet = new Set(text.split('\n').filter(Boolean).map(u => u.trim().toLowerCase()));
+            openPhishLastFetch = Date.now();
+        }
+    }
+    catch { /* silent — feed optional */ }
+    return openPhishSet ?? new Set();
+}
+export async function checkThreatFeeds(url) {
+    // Check cache first
+    const normalizedUrl = url.toLowerCase();
+    const cached = resultCache.get(normalizedUrl);
+    if (cached && cached.expires > Date.now())
+        return cached.result;
+    const threats = [];
+    let details;
+    let source = 'none';
+    // 1. OpenPhish (local Set lookup — instant)
+    const phishSet = await loadOpenPhishFeed();
+    if (phishSet.has(normalizedUrl)) {
+        threats.push('OPENPHISH_PHISHING');
+        source = 'openphish';
+    }
+    // 2. URLhaus API (2s timeout)
+    try {
+        const res = await fetch('https://urlhaus-api.abuse.ch/v1/url/', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: `url=${encodeURIComponent(url)}`,
+            signal: AbortSignal.timeout(2000),
+        });
+        if (res.ok) {
+            const data = await res.json();
+            if (data.query_status === 'listed') {
+                threats.push('URLHAUS_MALWARE');
+                source = 'urlhaus';
+                details = `URLhaus: ${data.threat || 'malware'}, tags: ${(data.tags || []).join(', ') || 'none'}`;
+            }
+        }
+    }
+    catch { /* timeout or network error — skip silently */ }
+    // 3. PhishTank API (2s timeout) — only if not already flagged
+    if (threats.length === 0) {
+        try {
+            const res = await fetch('https://checkurl.phishtank.com/checkurl/', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: `url=${encodeURIComponent(url)}&format=json&app_key=`,
+                signal: AbortSignal.timeout(2000),
+            });
+            if (res.ok) {
+                const data = await res.json();
+                if (data.results?.in_database &&
+                    data.results?.verified === 'yes' &&
+                    data.results?.valid === 'yes') {
+                    threats.push('PHISHTANK_PHISHING');
+                    source = 'phishtank';
+                }
+            }
+        }
+        catch { /* timeout — skip */ }
+    }
+    const result = {
+        safe: threats.length === 0,
+        threats,
+        source,
+        details,
+    };
+    // Cache the result
+    resultCache.set(normalizedUrl, { result, expires: Date.now() + CACHE_TTL });
+    return result;
+}

package/dist/core/timing.d.ts

@@ -0,0 +1,21 @@
+export interface PipelineTiming {
+    total: number;
+    fetch: number;
+    parse: number;
+    prune: number;
+    convert: number;
+    metadata: number;
+    readability?: number;
+    quickAnswer?: number;
+    domainExtract?: number;
+    budget?: number;
+}
+export declare class Timer {
+    private marks;
+    private durations;
+    private start;
+    constructor();
+    mark(name: string): void;
+    end(name: string): number;
+    toTiming(): PipelineTiming;
+}

package/dist/core/timing.js

@@ -0,0 +1,33 @@
+export class Timer {
+    marks = new Map();
+    durations = new Map();
+    start;
+    constructor() {
+        this.start = Date.now();
+    }
+    mark(name) {
+        this.marks.set(name, Date.now());
+    }
+    end(name) {
+        const markTime = this.marks.get(name);
+        if (!markTime)
+            return 0;
+        const duration = Date.now() - markTime;
+        this.durations.set(name, duration);
+        return duration;
+    }
+    toTiming() {
+        return {
+            total: Date.now() - this.start,
+            fetch: this.durations.get('fetch') ?? 0,
+            parse: this.durations.get('parse') ?? 0,
+            prune: this.durations.get('prune') ?? 0,
+            convert: this.durations.get('convert') ?? 0,
+            metadata: this.durations.get('metadata') ?? 0,
+            readability: this.durations.get('readability'),
+            quickAnswer: this.durations.get('quickAnswer'),
+            domainExtract: this.durations.get('domainExtract'),
+            budget: this.durations.get('budget'),
+        };
+    }
+}

package/dist/core/transcript-export.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Transcript export format converters.
+ *
+ * Converts YouTube transcript data into SRT, plain text, Markdown, or JSON
+ * so users can download transcripts in their preferred format.
+ */
+import type { TranscriptSegment, YouTubeTranscript } from './youtube.js';
+export type { TranscriptSegment, YouTubeTranscript as TranscriptResult };
+/**
+ * Format seconds as an SRT timestamp: HH:MM:SS,mmm
+ *
+ * @example formatSRTTimestamp(3661.5) → "01:01:01,500"
+ */
+export declare function formatSRTTimestamp(seconds: number): string;
+/**
+ * Convert transcript segments to SRT subtitle format.
+ *
+ * SRT structure:
+ * ```
+ * 1
+ * 00:00:01,000 --> 00:00:04,500
+ * We're no strangers to love
+ *
+ * 2
+ * 00:00:04,500 --> 00:00:08,000
+ * You know the rules and so do I
+ * ```
+ */
+export declare function toSRT(segments: TranscriptSegment[]): string;
+/**
+ * Convert transcript segments to plain text.
+ * One line per segment, no timestamps.
+ */
+export declare function toTXT(segments: TranscriptSegment[]): string;
+/**
+ * Convert transcript to a clean Markdown document.
+ * Includes title, channel header, and timestamped transcript lines.
+ *
+ * @param title   - Video title
+ * @param channel - Channel name
+ * @param segments - Transcript segments
+ */
+export declare function toMarkdownDoc(title: string, channel: string, segments: TranscriptSegment[]): string;
+/**
+ * Convert full transcript result to pretty-printed JSON.
+ */
+export declare function toJSON(result: YouTubeTranscript): string;

package/dist/core/transcript-export.js

@@ -0,0 +1,107 @@
+/**
+ * Transcript export format converters.
+ *
+ * Converts YouTube transcript data into SRT, plain text, Markdown, or JSON
+ * so users can download transcripts in their preferred format.
+ */
+// ---------------------------------------------------------------------------
+// Timestamp helpers
+// ---------------------------------------------------------------------------
+/**
+ * Format seconds as an SRT timestamp: HH:MM:SS,mmm
+ *
+ * @example formatSRTTimestamp(3661.5) → "01:01:01,500"
+ */
+export function formatSRTTimestamp(seconds) {
+    const totalMs = Math.round(Math.max(0, seconds) * 1000);
+    const ms = totalMs % 1000;
+    const totalSec = Math.floor(totalMs / 1000);
+    const s = totalSec % 60;
+    const totalMin = Math.floor(totalSec / 60);
+    const m = totalMin % 60;
+    const h = Math.floor(totalMin / 60);
+    return (`${String(h).padStart(2, '0')}:` +
+        `${String(m).padStart(2, '0')}:` +
+        `${String(s).padStart(2, '0')},` +
+        `${String(ms).padStart(3, '0')}`);
+}
+/**
+ * Format seconds as a human-readable timestamp: M:SS or H:MM:SS
+ *
+ * @example formatReadableTimestamp(125.3) → "2:05"
+ */
+function formatReadableTimestamp(seconds) {
+    const totalSec = Math.floor(Math.max(0, seconds));
+    const h = Math.floor(totalSec / 3600);
+    const m = Math.floor((totalSec % 3600) / 60);
+    const s = totalSec % 60;
+    if (h > 0) {
+        return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
+    }
+    return `${m}:${String(s).padStart(2, '0')}`;
+}
+// ---------------------------------------------------------------------------
+// Export functions
+// ---------------------------------------------------------------------------
+/**
+ * Convert transcript segments to SRT subtitle format.
+ *
+ * SRT structure:
+ * ```
+ * 1
+ * 00:00:01,000 --> 00:00:04,500
+ * We're no strangers to love
+ *
+ * 2
+ * 00:00:04,500 --> 00:00:08,000
+ * You know the rules and so do I
+ * ```
+ */
+export function toSRT(segments) {
+    if (segments.length === 0)
+        return '';
+    return segments
+        .map((seg, i) => {
+        const start = formatSRTTimestamp(seg.start);
+        const end = formatSRTTimestamp(seg.start + Math.max(0, seg.duration));
+        return `${i + 1}\n${start} --> ${end}\n${seg.text}`;
+    })
+        .join('\n\n');
+}
+/**
+ * Convert transcript segments to plain text.
+ * One line per segment, no timestamps.
+ */
+export function toTXT(segments) {
+    return segments.map((seg) => seg.text).join('\n');
+}
+/**
+ * Convert transcript to a clean Markdown document.
+ * Includes title, channel header, and timestamped transcript lines.
+ *
+ * @param title   - Video title
+ * @param channel - Channel name
+ * @param segments - Transcript segments
+ */
+export function toMarkdownDoc(title, channel, segments) {
+    const lines = [];
+    lines.push(`# ${title || 'Transcript'}`);
+    lines.push('');
+    if (channel) {
+        lines.push(`**Channel:** ${channel}`);
+        lines.push('');
+    }
+    lines.push('## Transcript');
+    lines.push('');
+    for (const seg of segments) {
+        const ts = formatReadableTimestamp(seg.start);
+        lines.push(`**[${ts}]** ${seg.text}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Convert full transcript result to pretty-printed JSON.
+ */
+export function toJSON(result) {
+    return JSON.stringify(result, null, 2);
+}

package/dist/core/user-agents.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Realistic User Agent Rotation for WebPeel
+ *
+ * Provides a curated list of real-world Chrome user agents (132-136 range)
+ * across Windows, macOS, and Linux platforms. Used when stealth mode is active
+ * and no custom UA is set — prevents the default "Chrome for Testing" UA which
+ * is an instant bot-detection signal.
+ *
+ * Also provides `getSecCHUA()` for generating correct Sec-CH-UA header values
+ * that match the selected user agent (version-accurate brand hints).
+ */
+/**
+ * Full UA pool for HTTP-only requests (Chrome + Firefox + Safari + Edge + Mobile).
+ * NOT for browser contexts — use getRealisticUserAgent() there (Chrome-only).
+ */
+export declare const HTTP_UAS: readonly string[];
+/**
+ * Returns a realistic, recent Chrome user agent string.
+ * Randomly picks from a curated list of real-world UAs (Chrome 132-136 range).
+ *
+ * @param platform - Optionally restrict to a specific OS platform.
+ *                   When omitted, picks from all platforms (weighted: ~55% Windows, ~35% Mac, ~10% Linux).
+ *
+ * @example
+ * ```ts
+ * // Random platform
+ * const ua = getRealisticUserAgent();
+ *
+ * // Force Windows UA (e.g. for LinkedIn, which is more common on Windows)
+ * const ua = getRealisticUserAgent('windows');
+ * ```
+ */
+export declare function getRealisticUserAgent(platform?: 'windows' | 'mac' | 'linux'): string;
+/**
+ * Returns a random UA from the full list (all platforms).
+ * Equivalent to `getRealisticUserAgent()` with no arguments.
+ */
+export declare function getRandomUA(): string;
+/**
+ * Returns a realistic user agent for HTTP-only (non-browser) requests.
+ * Unlike `getRealisticUserAgent()` which is Chrome-only for browser contexts,
+ * this function returns from a wider pool: Chrome, Firefox, Safari, Edge, and Mobile.
+ *
+ * Weight distribution (approximate):
+ * - Chrome Windows:  ~30%
+ * - Chrome macOS:    ~25%
+ * - Chrome Linux:    ~10%
+ * - Firefox:         ~15%
+ * - Safari:          ~10%
+ * - Edge:             ~5%
+ * - Mobile Chrome:    ~5%
+ *
+ * @example
+ * ```ts
+ * const ua = getHttpUA(); // e.g. "Mozilla/5.0 ... Firefox/133.0"
+ * ```
+ */
+export declare function getHttpUA(): string;
+/**
+ * The full curated list of realistic user agents (Chrome-only, all platforms).
+ * Exported for inspection / testing.
+ */
+export declare const REALISTIC_USER_AGENTS: readonly string[];
+/**
+ * Get a Sec-CH-UA header value that matches the given user agent string.
+ *
+ * Extracts the Chrome major version from the UA string and returns a properly
+ * formatted `Sec-CH-UA` header value, e.g.:
+ *   `"Chromium";v="136", "Google Chrome";v="136", "Not.A/Brand";v="24"`
+ *
+ * Falls back to a sane Chrome 136 value when the UA doesn't contain a
+ * recognizable Chrome version.
+ *
+ * @param userAgent - Full user agent string (e.g. from getRealisticUserAgent())
+ */
+export declare function getSecCHUA(userAgent: string): string;
+/**
+ * Determine the Sec-CH-UA-Platform header value based on the user agent string.
+ *
+ * @param userAgent - Full user agent string
+ */
+export declare function getSecCHUAPlatform(userAgent: string): string;

package/dist/core/user-agents.js

@@ -0,0 +1,239 @@
+/**
+ * Realistic User Agent Rotation for WebPeel
+ *
+ * Provides a curated list of real-world Chrome user agents (132-136 range)
+ * across Windows, macOS, and Linux platforms. Used when stealth mode is active
+ * and no custom UA is set — prevents the default "Chrome for Testing" UA which
+ * is an instant bot-detection signal.
+ *
+ * Also provides `getSecCHUA()` for generating correct Sec-CH-UA header values
+ * that match the selected user agent (version-accurate brand hints).
+ */
+// ── Curated UA lists ──────────────────────────────────────────────────────────
+const WINDOWS_UAS = [
+    // Chrome 132
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36',
+    // Chrome 133
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36',
+    // Chrome 134
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36',
+    // Chrome 135
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36',
+    // Chrome 136
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36',
+];
+const MAC_UAS = [
+    // Chrome 132 macOS
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36',
+    // Chrome 133 macOS
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36',
+    // Chrome 134 macOS
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36',
+    // Chrome 135 macOS
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36',
+    // Chrome 136 macOS
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36',
+];
+const LINUX_UAS = [
+    // Chrome 133 Linux
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36',
+    // Chrome 135 Linux
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36',
+    // Chrome 136 Linux
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36',
+];
+/** All Chrome UAs combined (fallback when no platform is specified) */
+const ALL_UAS = [...WINDOWS_UAS, ...MAC_UAS, ...LINUX_UAS];
+// ── Extended pools for non-Chrome browsers (HTTP-only use) ───────────────────
+/** Firefox UAs — Windows, Mac, Linux */
+const FIREFOX_UAS = [
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:133.0) Gecko/20100101 Firefox/133.0',
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:134.0) Gecko/20100101 Firefox/134.0',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 14.7; rv:133.0) Gecko/20100101 Firefox/133.0',
+    'Mozilla/5.0 (X11; Linux x86_64; rv:133.0) Gecko/20100101 Firefox/133.0',
+];
+/** Safari UAs — macOS */
+const SAFARI_UAS = [
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.2 Safari/605.1.15',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 15_0) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Safari/605.1.15',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Safari/605.1.15',
+];
+/** Microsoft Edge UAs */
+const EDGE_UAS = [
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0',
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36 Edg/133.0.0.0',
+];
+/** Mobile Chrome UAs */
+const MOBILE_CHROME_UAS = [
+    'Mozilla/5.0 (Linux; Android 14; SM-S928B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Mobile Safari/537.36',
+    'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Mobile Safari/537.36',
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 18_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/131.0.6778.103 Mobile/15E148 Safari/604.1',
+];
+/**
+ * Full UA pool for HTTP-only requests (Chrome + Firefox + Safari + Edge + Mobile).
+ * NOT for browser contexts — use getRealisticUserAgent() there (Chrome-only).
+ */
+export const HTTP_UAS = [
+    ...ALL_UAS,
+    ...FIREFOX_UAS,
+    ...SAFARI_UAS,
+    ...EDGE_UAS,
+    ...MOBILE_CHROME_UAS,
+];
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Returns a realistic, recent Chrome user agent string.
+ * Randomly picks from a curated list of real-world UAs (Chrome 132-136 range).
+ *
+ * @param platform - Optionally restrict to a specific OS platform.
+ *                   When omitted, picks from all platforms (weighted: ~55% Windows, ~35% Mac, ~10% Linux).
+ *
+ * @example
+ * ```ts
+ * // Random platform
+ * const ua = getRealisticUserAgent();
+ *
+ * // Force Windows UA (e.g. for LinkedIn, which is more common on Windows)
+ * const ua = getRealisticUserAgent('windows');
+ * ```
+ */
+export function getRealisticUserAgent(platform) {
+    let pool;
+    if (platform === 'windows') {
+        pool = WINDOWS_UAS;
+    }
+    else if (platform === 'mac') {
+        pool = MAC_UAS;
+    }
+    else if (platform === 'linux') {
+        pool = LINUX_UAS;
+    }
+    else {
+        // Weighted random: Windows ~55%, Mac ~35%, Linux ~10%
+        const roll = Math.random();
+        if (roll < 0.55) {
+            pool = WINDOWS_UAS;
+        }
+        else if (roll < 0.90) {
+            pool = MAC_UAS;
+        }
+        else {
+            pool = LINUX_UAS;
+        }
+    }
+    const idx = Math.floor(Math.random() * pool.length);
+    return pool[idx];
+}
+/**
+ * Returns a random UA from the full list (all platforms).
+ * Equivalent to `getRealisticUserAgent()` with no arguments.
+ */
+export function getRandomUA() {
+    const idx = Math.floor(Math.random() * ALL_UAS.length);
+    return ALL_UAS[idx];
+}
+/**
+ * Returns a realistic user agent for HTTP-only (non-browser) requests.
+ * Unlike `getRealisticUserAgent()` which is Chrome-only for browser contexts,
+ * this function returns from a wider pool: Chrome, Firefox, Safari, Edge, and Mobile.
+ *
+ * Weight distribution (approximate):
+ * - Chrome Windows:  ~30%
+ * - Chrome macOS:    ~25%
+ * - Chrome Linux:    ~10%
+ * - Firefox:         ~15%
+ * - Safari:          ~10%
+ * - Edge:             ~5%
+ * - Mobile Chrome:    ~5%
+ *
+ * @example
+ * ```ts
+ * const ua = getHttpUA(); // e.g. "Mozilla/5.0 ... Firefox/133.0"
+ * ```
+ */
+export function getHttpUA() {
+    const roll = Math.random();
+    let pool;
+    if (roll < 0.30) {
+        pool = WINDOWS_UAS;
+    }
+    else if (roll < 0.55) {
+        pool = MAC_UAS;
+    }
+    else if (roll < 0.65) {
+        pool = LINUX_UAS;
+    }
+    else if (roll < 0.80) {
+        pool = FIREFOX_UAS;
+    }
+    else if (roll < 0.90) {
+        pool = SAFARI_UAS;
+    }
+    else if (roll < 0.95) {
+        pool = EDGE_UAS;
+    }
+    else {
+        pool = MOBILE_CHROME_UAS;
+    }
+    return pool[Math.floor(Math.random() * pool.length)];
+}
+/**
+ * The full curated list of realistic user agents (Chrome-only, all platforms).
+ * Exported for inspection / testing.
+ */
+export const REALISTIC_USER_AGENTS = ALL_UAS;
+// ── Sec-CH-UA header generation ───────────────────────────────────────────────
+/**
+ * The "Not A Brand" token format varies by Chrome version.
+ *
+ * Chrome 132-133: `"Not_A Brand";v="8"`
+ * Chrome 134-135: `"Not)A;Brand";v="99"`
+ * Chrome 136+:    `"Not.A/Brand";v="24"`
+ *
+ * This matches real Chrome behavior to avoid client-hint fingerprinting.
+ */
+function getNotABrandToken(chromeVersion) {
+    if (chromeVersion >= 136) {
+        return '"Not.A/Brand";v="24"';
+    }
+    else if (chromeVersion >= 134) {
+        return '"Not)A;Brand";v="99"';
+    }
+    else {
+        return '"Not_A Brand";v="8"';
+    }
+}
+/**
+ * Get a Sec-CH-UA header value that matches the given user agent string.
+ *
+ * Extracts the Chrome major version from the UA string and returns a properly
+ * formatted `Sec-CH-UA` header value, e.g.:
+ *   `"Chromium";v="136", "Google Chrome";v="136", "Not.A/Brand";v="24"`
+ *
+ * Falls back to a sane Chrome 136 value when the UA doesn't contain a
+ * recognizable Chrome version.
+ *
+ * @param userAgent - Full user agent string (e.g. from getRealisticUserAgent())
+ */
+export function getSecCHUA(userAgent) {
+    // Extract Chrome major version from UA string
+    // Matches patterns like: Chrome/136.0.0.0 or Chrome/132
+    const match = userAgent.match(/Chrome\/(\d+)/i);
+    const version = match ? parseInt(match[1], 10) : 136;
+    const notABrand = getNotABrandToken(version);
+    return `"Chromium";v="${version}", "Google Chrome";v="${version}", ${notABrand}`;
+}
+/**
+ * Determine the Sec-CH-UA-Platform header value based on the user agent string.
+ *
+ * @param userAgent - Full user agent string
+ */
+export function getSecCHUAPlatform(userAgent) {
+    if (userAgent.includes('Windows'))
+        return '"Windows"';
+    if (userAgent.includes('Macintosh'))
+        return '"macOS"';
+    if (userAgent.includes('Linux'))
+        return '"Linux"';
+    return '"Unknown"';
+}

package/dist/core/vertical-search.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Vertical search — specialized endpoints for shopping, news, images, videos.
+ * Primary: SearXNG (reliable, structured JSON, no CAPTCHA issues from datacenter).
+ * Fallback: Google scraping via peel() (for shopping only).
+ */
+export interface ShoppingResult {
+    title: string;
+    price?: string;
+    currency?: string;
+    store: string;
+    url: string;
+    imageUrl?: string;
+    rating?: number;
+    reviewCount?: number;
+    condition?: string;
+}
+export interface NewsResult {
+    title: string;
+    url: string;
+    source: string;
+    date?: string;
+    snippet?: string;
+    imageUrl?: string;
+    category?: string;
+}
+export interface ImageResult {
+    title: string;
+    url: string;
+    imageUrl: string;
+    width?: number;
+    height?: number;
+    source?: string;
+}
+export interface VideoResult {
+    title: string;
+    url: string;
+    platform: string;
+    duration?: string;
+    date?: string;
+    thumbnailUrl?: string;
+    channel?: string;
+    views?: string;
+}
+export interface VerticalSearchOptions {
+    query: string;
+    count?: number;
+    country?: string;
+    language?: string;
+    freshness?: string;
+}
+export declare function searchShopping(opts: VerticalSearchOptions): Promise<ShoppingResult[]>;
+export declare function searchNews(opts: VerticalSearchOptions): Promise<NewsResult[]>;
+export declare function searchImages(opts: VerticalSearchOptions): Promise<ImageResult[]>;
+export declare function searchVideos(opts: VerticalSearchOptions): Promise<VideoResult[]>;