webpeel 0.20.20 → 0.21.0

package/dist/cli/commands/fetch.js

@@ -205,6 +205,55 @@ export async function runFetch(url, options) {
         console.error(usageCheck.message);
         process.exit(1);
     }
+    // ── --export: YouTube transcript download (early exit) ────────────────
+    if (options.export) {
+        const exportFmt = options.export.toLowerCase();
+        const validExportFmts = ['srt', 'txt', 'md', 'json'];
+        if (!validExportFmts.includes(exportFmt)) {
+            console.error(`Error: --export format must be one of: ${validExportFmts.join(', ')}`);
+            process.exit(1);
+        }
+        const exportCfg = loadConfig();
+        const exportApiKey = exportCfg.apiKey || process.env.WEBPEEL_API_KEY;
+        const exportApiUrl = process.env.WEBPEEL_API_URL || 'https://api.webpeel.dev';
+        if (!exportApiKey) {
+            console.error('No API key configured. Run: webpeel auth <your-key>');
+            console.error('Get a free key at: https://app.webpeel.dev/keys');
+            process.exit(2);
+        }
+        const lang = options.language || 'en';
+        const exportUrl = `${exportApiUrl}/v1/transcript/export?url=${encodeURIComponent(url)}&format=${exportFmt}&language=${lang}`;
+        const exportRes = await fetch(exportUrl, {
+            headers: { 'Authorization': `Bearer ${exportApiKey}` },
+            signal: AbortSignal.timeout(options.timeout ?? 90000),
+        });
+        if (!exportRes.ok) {
+            const errBody = await exportRes.text().catch(() => '');
+            try {
+                const errJson = JSON.parse(errBody);
+                const msg = errJson?.error?.message || errJson?.message || exportRes.statusText;
+                console.error(`Export failed (${exportRes.status}): ${msg}`);
+            }
+            catch {
+                console.error(`Export failed (${exportRes.status}): ${exportRes.statusText}`);
+            }
+            process.exit(1);
+        }
+        const exportContent = await exportRes.text();
+        if (options.output) {
+            writeFileSync(options.output, exportContent, 'utf-8');
+            if (!options.silent) {
+                console.error(`Transcript saved to: ${options.output}`);
+            }
+        }
+        else {
+            process.stdout.write(exportContent);
+            if (!exportContent.endsWith('\n'))
+                process.stdout.write('\n');
+        }
+        await cleanup();
+        process.exit(0);
+    }
     // Check cache first (before spinner/network)
     // Default: 5m TTL for all CLI fetches unless --no-cache is set
     let cacheTtlMs;
@@ -1077,6 +1126,8 @@ export function registerFetchCommands(program) {
         .option('--content-only', 'Output only the raw content field (no metadata, no JSON wrapper) — ideal for piping to LLMs')
         .option('--progress', 'Show engine escalation steps (simple → browser → stealth) with timing')
         .option('--stdin', 'Read HTML from stdin instead of fetching a URL — converts to markdown')
+        .option('--export <format>', 'Export YouTube transcript in the given format: srt, txt, md, json')
+        .option('--output <file>', 'Write output to a file instead of stdout')
         .action(async (url, options) => {
         if (options.stdin) {
             await runStdin(options);

package/dist/core/prompt-guard.js

@@ -8,6 +8,8 @@
 const INJECTION_PATTERNS = [
     // Direct instruction overrides
     { pattern: /ignore\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|rules?|prompts?|guidelines?)/gi, name: 'instruction-override' },
+    { pattern: /ignore\s+rules?/gi, name: 'instruction-override' },
+    { pattern: /override\s+rules?/gi, name: 'instruction-override' },
     { pattern: /disregard\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|rules?|prompts?)/gi, name: 'disregard-instructions' },
     { pattern: /forget\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|rules?|prompts?)/gi, name: 'forget-instructions' },
     { pattern: /override\s+(system|previous|all)\s+(prompt|instructions?|rules?)/gi, name: 'override-system' },

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/server/app.js

@@ -31,6 +31,7 @@ import { createAskRouter } from './routes/ask.js';
 import { createMcpRouter } from './routes/mcp.js';
 import { createDoRouter } from './routes/do.js';
 import { createYouTubeRouter } from './routes/youtube.js';
+import { createTranscriptExportRouter } from './routes/transcript-export.js';
 import { createDeepFetchRouter } from './routes/deep-fetch.js';
 import { createWatchRouter } from './routes/watch.js';
 import pg from 'pg';
@@ -38,6 +39,7 @@ import { createScreenshotRouter } from './routes/screenshot.js';
 import { createDemoRouter } from './routes/demo.js';
 import { createPlaygroundRouter } from './routes/playground.js';
 import { createReaderRouter } from './routes/reader.js';
+import { createSharePublicRouter, createShareRouter } from './routes/share.js';
 import { createJobQueue } from './job-queue.js';
 import { createCompatRouter } from './routes/compat.js';
 import { createCrawlRouter } from './routes/crawl.js';
@@ -46,6 +48,7 @@ import { createExtractRouter } from './routes/extract.js';
 import { createAgentRouter } from './routes/agent.js';
 import { createSessionRouter } from './routes/session.js';
 import { createSentryHooks } from './sentry.js';
+import { requireScope } from './middleware/scope-guard.js';
 import { warmup, cleanup as cleanupFetcher } from '../core/fetcher.js';
 import { registerPremiumHooks } from './premium/index.js';
 import { readFileSync } from 'fs';
@@ -239,6 +242,9 @@ export function createApp(config = {}) {
     app.use(createDemoRouter());
     // Playground endpoint — unauthenticated, CORS-locked to webpeel.dev/localhost
     app.use('/v1/playground', createPlaygroundRouter());
+    // Public share endpoint — GET /s/:id (no auth required, must be before reader router)
+    // Registered first so valid share IDs are served before falling through to reader's /s/* search
+    app.use(createSharePublicRouter(pool));
     // Zero-auth reader API — Jina-style URL prefix (/r/URL) and search (/s/query)
     // Must be BEFORE auth middleware so no API key is required
     app.use(createReaderRouter());
@@ -246,17 +252,33 @@ export function createApp(config = {}) {
     app.use(createAuthMiddleware(authStore));
     // Apply rate limiting middleware globally
     app.use(createRateLimitMiddleware(rateLimiter));
+    // Share links — POST /v1/share (auth required, after auth middleware)
+    app.use(createShareRouter(pool));
     // First-class native routes (registered before compat so they take precedence)
-    app.use('/v1/crawl', createCrawlRouter(jobQueue));
-    app.use('/v1/map', createMapRouter());
+    //
+    // Scope guards enforce API key permission scopes; JWT sessions bypass them.
+    // For routers with relative paths: app.use(path, guard, router)    ← prefix stripped, relative paths match
+    // For routers with absolute paths: app.use(path, guard) then app.use(router) ← guard at path, router sees full path
+    // /v1/crawl — full or read only (router uses relative paths)
+    app.use('/v1/crawl', requireScope('full', 'read'), createCrawlRouter(jobQueue));
+    // /v1/map — full or read only (router uses relative paths)
+    app.use('/v1/map', requireScope('full', 'read'), createMapRouter());
+    // Compat routes (/v1/scrape, /v1/search) — all scopes allowed, no guard needed
     app.use(createCompatRouter(jobQueue));
     app.use(createSessionRouter());
     app.use(createExtractRouter());
+    // /v1/deep-fetch — full or read only (router uses absolute paths, guard before router)
+    app.use('/v1/deep-fetch', requireScope('full', 'read'));
     app.use(createDeepFetchRouter());
+    // /v1/watch — full or read only (router uses absolute paths, guard before router)
     if (pool) {
+        app.use('/v1/watch', requireScope('full', 'read'));
         app.use(createWatchRouter(pool));
     }
+    // /v1/fetch, /v1/search — all scopes allowed, no guard needed
     app.use(createFetchRouter(authStore));
+    // /v1/screenshot — full or read only (router uses absolute paths, guard before router)
+    app.use('/v1/screenshot', requireScope('full', 'read'));
     app.use(createScreenshotRouter(authStore));
     app.use(createSearchRouter(authStore));
     app.use(createBillingPortalRouter(pool));
@@ -266,6 +288,8 @@ export function createApp(config = {}) {
     app.use(createActivityRouter(authStore));
     app.use(createCLIUsageRouter());
     app.use(createJobsRouter(jobQueue, authStore));
+    // /v1/batch — full or read only (router uses absolute paths, guard before router)
+    app.use('/v1/batch', requireScope('full', 'read'));
     app.use(createBatchRouter(jobQueue));
     // Deprecation headers for declining endpoints
     app.use('/v1/answer', (_req, res, next) => {
@@ -274,11 +298,15 @@ export function createApp(config = {}) {
         res.set('Link', '</v1/ask>; rel="successor-version"');
         next();
     });
+    // /v1/answer, /v1/ask — all scopes allowed, no guard needed
     app.use(createAnswerRouter());
     app.use(createAskRouter());
-    app.use('/v1/agent', createAgentRouter());
-    app.use('/v1/do', createDoRouter());
+    // /v1/agent — full or read only (router uses relative paths)
+    app.use('/v1/agent', requireScope('full', 'read'), createAgentRouter());
+    // /v1/do — full only (router uses relative paths; admin-level operation)
+    app.use('/v1/do', requireScope('full'), createDoRouter());
     app.use(createYouTubeRouter());
+    app.use(createTranscriptExportRouter());
     app.use(createMcpRouter(authStore, pool));
     // 404 handler
     app.use((req, res) => {

package/dist/server/auth-store.d.ts

@@ -8,6 +8,7 @@ export interface ApiKeyInfo {
     rateLimit: number;
     accountId?: string;
     createdAt: Date;
+    scope?: 'full' | 'read' | 'restricted';
 }
 export interface AuthStore {
     validateKey(key: string): Promise<ApiKeyInfo | null>;

package/dist/server/middleware/auth.d.ts

@@ -11,6 +11,7 @@
  */
 import { Request, Response, NextFunction } from 'express';
 import { AuthStore, ApiKeyInfo } from '../auth-store.js';
+import { KeyScope } from '../pg-auth-store.js';
 import '../types.js';
 declare global {
     namespace Express {
@@ -22,6 +23,12 @@ declare global {
                 softLimited: boolean;
                 extraUsageAvailable: boolean;
             };
+            /**
+             * Permission scope of the authenticated API key.
+             * Undefined when authenticated via JWT (dashboard session) — JWT users bypass scope enforcement.
+             * Set to 'full' | 'read' | 'restricted' for API key requests.
+             */
+            keyScope?: KeyScope;
         }
     }
 }

package/dist/server/middleware/auth.js

@@ -204,6 +204,10 @@ export function createAuthMiddleware(authStore) {
                 softLimited,
                 extraUsageAvailable,
             };
+            // Attach API key scope (only for API key auth; JWT users get undefined = bypass scope checks)
+            if (keyInfo) {
+                req.keyScope = keyInfo.scope || 'full';
+            }
             next();
         }
         catch (_error) {

package/dist/server/middleware/scope-guard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Scope enforcement middleware for API key permission scoping.
+ *
+ * Keys have one of three scopes:
+ *   'full'       — all endpoints (default)
+ *   'read'       — read/fetch operations only
+ *   'restricted' — /v1/scrape only (for limited sharing)
+ *
+ * JWT-authenticated requests (dashboard sessions) bypass scope enforcement:
+ * req.keyScope is undefined for JWT requests, which are always allowed through.
+ */
+import { Request, Response, NextFunction } from 'express';
+import { KeyScope } from '../pg-auth-store.js';
+/**
+ * Middleware factory that enforces API key scope.
+ * Pass the set of scopes that are permitted to access the guarded route.
+ *
+ * @example
+ * // Only full-access keys may manage billing:
+ * router.post('/v1/billing', requireScope('full'), handler);
+ *
+ * // Read and full keys may scrape:
+ * app.use('/v1/scrape', requireScope('full', 'read', 'restricted'), scrapeRouter);
+ */
+export declare function requireScope(...allowedScopes: KeyScope[]): (req: Request, res: Response, next: NextFunction) => void;

package/dist/server/middleware/scope-guard.js

@@ -0,0 +1,45 @@
+/**
+ * Scope enforcement middleware for API key permission scoping.
+ *
+ * Keys have one of three scopes:
+ *   'full'       — all endpoints (default)
+ *   'read'       — read/fetch operations only
+ *   'restricted' — /v1/scrape only (for limited sharing)
+ *
+ * JWT-authenticated requests (dashboard sessions) bypass scope enforcement:
+ * req.keyScope is undefined for JWT requests, which are always allowed through.
+ */
+/**
+ * Middleware factory that enforces API key scope.
+ * Pass the set of scopes that are permitted to access the guarded route.
+ *
+ * @example
+ * // Only full-access keys may manage billing:
+ * router.post('/v1/billing', requireScope('full'), handler);
+ *
+ * // Read and full keys may scrape:
+ * app.use('/v1/scrape', requireScope('full', 'read', 'restricted'), scrapeRouter);
+ */
+export function requireScope(...allowedScopes) {
+    return (req, res, next) => {
+        // JWT sessions (req.keyScope === undefined) always pass through.
+        // Scope enforcement only applies to API key requests.
+        if (req.keyScope === undefined) {
+            return next();
+        }
+        if (!allowedScopes.includes(req.keyScope)) {
+            res.status(403).json({
+                success: false,
+                error: {
+                    type: 'insufficient_scope',
+                    message: `This API key has '${req.keyScope}' scope. This endpoint requires: ${allowedScopes.join(' or ')}.`,
+                    docs: 'https://webpeel.dev/docs/authentication#scopes',
+                    hint: 'Create a new API key with the required scope in your dashboard.',
+                },
+                requestId: req.requestId,
+            });
+            return;
+        }
+        next();
+    };
+}

package/dist/server/pg-auth-store.d.ts

@@ -3,6 +3,8 @@
  * Uses SHA-256 hashing for API keys and tracks WEEKLY usage with burst limits
  */
 import { AuthStore, ApiKeyInfo } from './auth-store.js';
+/** Permission scope for an API key */
+export type KeyScope = 'full' | 'read' | 'restricted';
 export interface WeeklyUsageInfo {
     week: string;
     basicCount: number;
@@ -39,6 +41,11 @@ export interface ExtraUsageInfo {
 export declare class PostgresAuthStore implements AuthStore {
     private pool;
     constructor(connectionString?: string);
+    /**
+     * Run idempotent schema migrations.
+     * Safe to call on every startup — all statements use IF NOT EXISTS / IF EXISTS.
+     */
+    private ensureSchema;
     /**
      * Hash API key with SHA-256
      * SECURITY: Never store raw API keys

package/dist/server/pg-auth-store.js

@@ -34,6 +34,36 @@ export class PostgresAuthStore {
             idleTimeoutMillis: 30000,
             connectionTimeoutMillis: 10000,
         });
+        // Run idempotent schema migrations on startup
+        this.ensureSchema().catch(err => console.error('[pg-auth-store] Schema migration failed:', err));
+    }
+    /**
+     * Run idempotent schema migrations.
+     * Safe to call on every startup — all statements use IF NOT EXISTS / IF EXISTS.
+     */
+    async ensureSchema() {
+        await this.pool.query(`
+      ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS scope VARCHAR(20) NOT NULL DEFAULT 'full';
+    `);
+        await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS shared_reads (
+        id VARCHAR(12) PRIMARY KEY,
+        url TEXT NOT NULL,
+        title TEXT,
+        content TEXT NOT NULL,
+        tokens INTEGER,
+        created_by TEXT REFERENCES users(id),
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        expires_at TIMESTAMPTZ DEFAULT NOW() + INTERVAL '30 days',
+        view_count INTEGER DEFAULT 0
+      );
+    `);
+        await this.pool.query(`
+      CREATE INDEX IF NOT EXISTS idx_shared_reads_url ON shared_reads(url);
+    `);
+        await this.pool.query(`
+      CREATE INDEX IF NOT EXISTS idx_shared_reads_created_by ON shared_reads(created_by);
+    `);
     }
     /**
      * Hash API key with SHA-256
@@ -108,6 +138,7 @@ export class PostgresAuthStore {
           ak.user_id,
           ak.key_prefix,
           ak.name,
+          ak.scope,
           u.tier,
           u.rate_limit,
           u.weekly_limit,
@@ -129,6 +160,7 @@ export class PostgresAuthStore {
                 rateLimit: row.rate_limit,
                 accountId: row.user_id,
                 createdAt: new Date(),
+                scope: row.scope || 'full',
             };
         }
         catch (error) {

package/dist/server/routes/activity.js

@@ -34,10 +34,12 @@ export function createActivityRouter(authStore) {
         SELECT 
           id,
           url,
+          endpoint,
           method,
           status_code,
           processing_time_ms,
           tokens_used,
+          ip_address,
           created_at
         FROM usage_logs
         WHERE user_id = $1
@@ -49,11 +51,14 @@ export function createActivityRouter(authStore) {
             const requests = result.rows.map((row) => ({
                 id: row.id,
                 url: row.url || 'N/A',
+                endpoint: row.endpoint || null,
                 status: (row.status_code >= 200 && row.status_code < 300) ? 'success' : 'error',
                 responseTime: row.processing_time_ms || 0,
                 mode: row.method || 'basic',
                 timestamp: row.created_at,
                 tokensUsed: row.tokens_used || null,
+                ipAddress: row.ip_address || null,
+                statusCode: row.status_code || null,
             }));
             res.json({ requests });
         }

package/dist/server/routes/share.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shareable read links — short public URLs for fetched content
+ *
+ * POST /v1/share     — create a short link (auth required, 50/day limit)
+ * GET  /s/:id        — serve shared content (public, no auth)
+ *
+ * IDs are 9-char base64url strings (crypto.randomBytes(6).toString('base64url').slice(0, 9))
+ * Shares expire after 30 days. view_count is incremented on every public read.
+ */
+import { Router } from 'express';
+import pg from 'pg';
+/** Generate a cryptographically secure 9-char base64url ID.
+ *  randomBytes(7) → base64url gives 10 chars (7*4/3=9.33→10), slice to 9.
+ *  Note: randomBytes(6) → base64url gives only 8 chars (6/3*4=8), so we need 7+ bytes.
+ */
+export declare function generateShareId(): string;
+export declare function createSharePublicRouter(pool: pg.Pool | null): Router;
+export declare function createShareRouter(pool: pg.Pool | null): Router;

package/dist/server/routes/share.js

@@ -0,0 +1,462 @@
+/**
+ * Shareable read links — short public URLs for fetched content
+ *
+ * POST /v1/share     — create a short link (auth required, 50/day limit)
+ * GET  /s/:id        — serve shared content (public, no auth)
+ *
+ * IDs are 9-char base64url strings (crypto.randomBytes(6).toString('base64url').slice(0, 9))
+ * Shares expire after 30 days. view_count is incremented on every public read.
+ */
+import { Router } from 'express';
+import crypto from 'crypto';
+import { createLogger } from '../logger.js';
+import { peel } from '../../index.js';
+import { validateUrlForSSRF, SSRFError } from '../middleware/url-validator.js';
+const log = createLogger('share');
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/** Generate a cryptographically secure 9-char base64url ID.
+ *  randomBytes(7) → base64url gives 10 chars (7*4/3=9.33→10), slice to 9.
+ *  Note: randomBytes(6) → base64url gives only 8 chars (6/3*4=8), so we need 7+ bytes.
+ */
+export function generateShareId() {
+    return crypto.randomBytes(7).toString('base64url').slice(0, 9);
+}
+/** Base URL for share links */
+function getBaseUrl() {
+    return process.env.API_BASE_URL || 'https://api.webpeel.dev';
+}
+/** Simple markdown → HTML renderer (no external deps) */
+function markdownToHtml(md) {
+    let html = md
+        // Escape raw HTML in content to prevent XSS
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        // Code blocks (``` ... ```)
+        .replace(/```[\w]*\n([\s\S]*?)```/g, (_m, code) => `<pre><code>${code.trim()}</code></pre>`)
+        // Inline code
+        .replace(/`([^`]+)`/g, '<code>$1</code>')
+        // Bold + italic
+        .replace(/\*\*\*([^*]+)\*\*\*/g, '<strong><em>$1</em></strong>')
+        // Bold
+        .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+        // Italic
+        .replace(/\*([^*]+)\*/g, '<em>$1</em>')
+        // Headings
+        .replace(/^### (.+)$/gm, '<h3>$1</h3>')
+        .replace(/^## (.+)$/gm, '<h2>$1</h2>')
+        .replace(/^# (.+)$/gm, '<h1>$1</h1>')
+        // Horizontal rule
+        .replace(/^---$/gm, '<hr>')
+        // Blockquote
+        .replace(/^> (.+)$/gm, '<blockquote>$1</blockquote>')
+        // Unordered list items
+        .replace(/^[\*\-] (.+)$/gm, '<li>$1</li>')
+        // Ordered list items
+        .replace(/^\d+\. (.+)$/gm, '<li>$1</li>')
+        // Links
+        .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2" rel="noopener noreferrer">$1</a>')
+        // Images
+        .replace(/!\[([^\]]*)\]\(([^)]+)\)/g, '<img src="$2" alt="$1">')
+        // Double newlines → paragraph breaks
+        .replace(/\n\n+/g, '\n</p><p>\n')
+        // Remaining single newlines → <br>
+        .replace(/\n/g, '<br>\n');
+    // Wrap consecutive <li> items in <ul>
+    html = html.replace(/(<li>.*?<\/li>\n?)+/gs, (m) => `<ul>\n${m}</ul>\n`);
+    return `<p>\n${html}\n</p>`;
+}
+/** Build the full HTML page for a shared read */
+function buildHtmlPage(share) {
+    const title = share.title ? `${share.title} — WebPeel` : 'Shared Read — WebPeel';
+    const description = share.content.slice(0, 200).replace(/\n/g, ' ').replace(/"/g, '&quot;') + '…';
+    const canonicalUrl = `${getBaseUrl()}/s/${share.id}`;
+    const originalUrl = share.url
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    const bodyHtml = markdownToHtml(share.content);
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title.replace(/</g, '&lt;')}</title>
+  <meta name="description" content="${description}">
+  <link rel="canonical" href="${canonicalUrl}">
+
+  <!-- Open Graph -->
+  <meta property="og:title" content="${(share.title || 'Shared Read').replace(/</g, '&lt;')}">
+  <meta property="og:description" content="${description}">
+  <meta property="og:url" content="${canonicalUrl}">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="WebPeel">
+
+  <!-- Twitter Card -->
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="${(share.title || 'Shared Read').replace(/</g, '&lt;')}">
+  <meta name="twitter:description" content="${description}">
+  <meta name="twitter:site" content="@webpeel">
+
+  <style>
+    *, *::before, *::after { box-sizing: border-box; }
+    :root {
+      --bg: #0f0f11;
+      --surface: #1a1a1f;
+      --border: #2a2a35;
+      --text: #e4e4e7;
+      --muted: #71717a;
+      --accent: #818cf8;
+      --link: #6366f1;
+      --code-bg: #1e1e28;
+      --max-w: 760px;
+    }
+    html { background: var(--bg); }
+    body {
+      margin: 0;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+      font-size: 16px;
+      line-height: 1.75;
+      color: var(--text);
+      background: var(--bg);
+      padding: 0 16px;
+    }
+
+    /* Top bar */
+    .topbar {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      max-width: var(--max-w);
+      margin: 0 auto;
+      padding: 20px 0 16px;
+      border-bottom: 1px solid var(--border);
+      gap: 12px;
+      flex-wrap: wrap;
+    }
+    .logo { display: flex; align-items: center; gap: 8px; text-decoration: none; color: var(--text); }
+    .logo-mark {
+      width: 28px; height: 28px;
+      background: var(--accent);
+      border-radius: 7px;
+      display: flex; align-items: center; justify-content: center;
+      font-size: 14px; font-weight: 700; color: #fff; letter-spacing: -0.5px;
+    }
+    .logo-name { font-weight: 600; font-size: 15px; }
+    .source-link {
+      font-size: 12px; color: var(--muted);
+      text-decoration: none; max-width: 300px;
+      overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    }
+    .source-link:hover { color: var(--accent); }
+
+    /* Main content */
+    main {
+      max-width: var(--max-w);
+      margin: 32px auto;
+    }
+    h1 { font-size: 1.75rem; font-weight: 700; line-height: 1.25; margin: 0 0 24px; color: var(--text); }
+    h2 { font-size: 1.35rem; font-weight: 600; margin: 28px 0 12px; color: var(--text); }
+    h3 { font-size: 1.1rem; font-weight: 600; margin: 24px 0 10px; color: var(--text); }
+    p { margin: 0 0 16px; color: #d4d4d8; }
+    a { color: var(--link); text-decoration: underline; text-underline-offset: 3px; }
+    a:hover { color: var(--accent); }
+    ul, ol { padding-left: 24px; margin: 0 0 16px; }
+    li { margin-bottom: 6px; color: #d4d4d8; }
+    blockquote {
+      border-left: 3px solid var(--accent); margin: 16px 0;
+      padding: 4px 16px; color: var(--muted); font-style: italic;
+    }
+    code {
+      background: var(--code-bg); padding: 2px 6px; border-radius: 4px;
+      font-family: 'Fira Code', 'Cascadia Code', monospace; font-size: 0.875em;
+      color: var(--accent);
+    }
+    pre {
+      background: var(--code-bg); padding: 16px; border-radius: 8px;
+      overflow-x: auto; margin: 16px 0; border: 1px solid var(--border);
+    }
+    pre code { background: none; padding: 0; color: #e4e4e7; }
+    img { max-width: 100%; border-radius: 6px; margin: 8px 0; }
+    hr { border: none; border-top: 1px solid var(--border); margin: 28px 0; }
+
+    /* Meta info */
+    .meta {
+      display: flex; gap: 16px; flex-wrap: wrap;
+      font-size: 12px; color: var(--muted);
+      margin-bottom: 28px; padding-bottom: 20px;
+      border-bottom: 1px solid var(--border);
+    }
+    .meta span { display: flex; align-items: center; gap: 4px; }
+
+    /* Footer */
+    footer {
+      max-width: var(--max-w);
+      margin: 48px auto 32px;
+      padding-top: 24px;
+      border-top: 1px solid var(--border);
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 12px;
+      flex-wrap: wrap;
+    }
+    .footer-left { font-size: 13px; color: var(--muted); }
+    .cta-btn {
+      display: inline-flex; align-items: center; gap-6px;
+      padding: 8px 16px; border-radius: 8px;
+      background: var(--accent); color: #fff;
+      font-size: 13px; font-weight: 600;
+      text-decoration: none; transition: opacity 0.15s;
+    }
+    .cta-btn:hover { opacity: 0.85; color: #fff; }
+
+    @media (max-width: 600px) {
+      h1 { font-size: 1.4rem; }
+      .topbar { flex-direction: column; align-items: flex-start; }
+    }
+  </style>
+</head>
+<body>
+  <!-- Top bar -->
+  <div class="topbar">
+    <a class="logo" href="https://webpeel.dev" target="_blank" rel="noopener">
+      <div class="logo-mark">W</div>
+      <span class="logo-name">WebPeel</span>
+    </a>
+    <a class="source-link" href="${originalUrl}" target="_blank" rel="noopener noreferrer" title="${originalUrl}">
+      ↗ ${originalUrl}
+    </a>
+  </div>
+
+  <!-- Article -->
+  <main>
+    ${share.title ? `<h1>${share.title.replace(/</g, '&lt;').replace(/>/g, '&gt;')}</h1>` : ''}
+    <div class="meta">
+      ${share.tokens != null ? `<span>📝 ${share.tokens.toLocaleString()} tokens</span>` : ''}
+      <span>👁 ${share.view_count.toLocaleString()} views</span>
+      <span>⏰ Expires ${new Date(share.expires_at).toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' })}</span>
+    </div>
+    <div class="content">
+      ${bodyHtml}
+    </div>
+  </main>
+
+  <!-- Footer -->
+  <footer>
+    <span class="footer-left">Powered by <a href="https://webpeel.dev" target="_blank" rel="noopener">WebPeel</a> — clean web reading for humans &amp; AI</span>
+    <a class="cta-btn" href="https://app.webpeel.dev" target="_blank" rel="noopener">
+      Try WebPeel →
+    </a>
+  </footer>
+</body>
+</html>`;
+}
+// ─── Rate limit: 50 shares per day per user ───────────────────────────────────
+const shareRateMap = new Map();
+const SHARE_DAY_LIMIT = 50;
+const SHARE_DAY_MS = 24 * 60 * 60 * 1000;
+function checkShareRateLimit(userId) {
+    const now = Date.now();
+    const entry = shareRateMap.get(userId);
+    if (!entry || entry.resetAt < now) {
+        shareRateMap.set(userId, { count: 1, resetAt: now + SHARE_DAY_MS });
+        return { allowed: true, remaining: SHARE_DAY_LIMIT - 1 };
+    }
+    entry.count++;
+    if (entry.count > SHARE_DAY_LIMIT) {
+        return { allowed: false, remaining: 0 };
+    }
+    return { allowed: true, remaining: SHARE_DAY_LIMIT - entry.count };
+}
+// ─── Public router: GET /s/:id ────────────────────────────────────────────────
+export function createSharePublicRouter(pool) {
+    const router = Router();
+    router.get('/s/:id', async (req, res, next) => {
+        const id = String(req.params['id'] || '');
+        // Only intercept valid-looking 9-char base64url IDs
+        if (!/^[A-Za-z0-9_-]{9}$/.test(id)) {
+            return next();
+        }
+        if (!pool) {
+            // No DB: fall through to reader's search handler
+            return next();
+        }
+        try {
+            // Fetch share and increment view count atomically
+            const result = await pool.query(`UPDATE shared_reads
+         SET view_count = view_count + 1
+         WHERE id = $1
+           AND expires_at > NOW()
+         RETURNING id, url, title, content, tokens, created_at, expires_at, view_count`, [id]);
+            if (result.rows.length === 0) {
+                // Not found or expired — fall through to reader's /s/* search handler
+                return next();
+            }
+            const share = result.rows[0];
+            // Respond based on Accept header
+            const accept = req.headers.accept || '';
+            if (accept.includes('application/json')) {
+                return res.json({
+                    success: true,
+                    shareId: share.id,
+                    url: share.url,
+                    title: share.title,
+                    content: share.content,
+                    tokens: share.tokens,
+                    viewCount: share.view_count,
+                    createdAt: share.created_at,
+                    expiresAt: share.expires_at,
+                });
+            }
+            if (accept.includes('text/markdown')) {
+                res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+                return res.send(share.content);
+            }
+            // Default: return HTML page (also covers text/html)
+            // Override CSP to allow inline styles for the share page
+            res.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; img-src https: data:; " +
+                "frame-ancestors 'none'; base-uri 'none'; form-action 'none'; " +
+                "script-src 'none'");
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            res.setHeader('Cache-Control', 'public, max-age=60, stale-while-revalidate=300');
+            return res.send(buildHtmlPage(share));
+        }
+        catch (err) {
+            log.error('Share GET error:', err.message);
+            return res.status(500).json({
+                success: false,
+                error: { type: 'server_error', message: 'Failed to retrieve share' },
+            });
+        }
+    });
+    return router;
+}
+// ─── Protected router: POST /v1/share ─────────────────────────────────────────
+export function createShareRouter(pool) {
+    const router = Router();
+    router.post('/v1/share', async (req, res) => {
+        // Require auth
+        const userId = req.auth?.keyInfo?.accountId || req.user?.userId;
+        if (!userId) {
+            return res.status(401).json({
+                success: false,
+                error: {
+                    type: 'unauthorized',
+                    message: 'Authentication required to create share links.',
+                    hint: 'Include an Authorization: Bearer <token> header.',
+                    docs: 'https://webpeel.dev/docs/errors#unauthorized',
+                },
+            });
+        }
+        if (!pool) {
+            return res.status(503).json({
+                success: false,
+                error: {
+                    type: 'unavailable',
+                    message: 'Share links require a PostgreSQL database.',
+                },
+            });
+        }
+        // Rate limit: 50 shares per day per user
+        const { allowed, remaining } = checkShareRateLimit(userId);
+        res.setHeader('X-Share-Limit-Remaining', remaining.toString());
+        if (!allowed) {
+            return res.status(429).json({
+                success: false,
+                error: {
+                    type: 'rate_limited',
+                    message: 'Share limit exceeded. Maximum 50 shares per day.',
+                    hint: 'Wait until tomorrow to create more share links.',
+                },
+            });
+        }
+        const { url, content, title } = req.body;
+        if (!url || typeof url !== 'string') {
+            return res.status(400).json({
+                success: false,
+                error: {
+                    type: 'invalid_request',
+                    message: 'url is required.',
+                },
+            });
+        }
+        // SECURITY: SSRF validation
+        try {
+            validateUrlForSSRF(url);
+        }
+        catch (err) {
+            if (err instanceof SSRFError) {
+                return res.status(400).json({
+                    success: false,
+                    error: { type: 'ssrf_blocked', message: err.message },
+                });
+            }
+            throw err;
+        }
+        let shareContent;
+        let shareTitle;
+        let tokens;
+        if (content && typeof content === 'string') {
+            // Content provided directly (user already fetched it in dashboard)
+            shareContent = content;
+            shareTitle = title;
+            tokens = content.split(/\s+/).filter(Boolean).length;
+        }
+        else {
+            // Fetch the URL via peel()
+            try {
+                const result = await peel(url, { timeout: 15000, noEscalate: true });
+                shareContent = result.content || '';
+                shareTitle = result.title;
+                tokens = result.tokens ?? undefined;
+            }
+            catch (err) {
+                log.error('Share: peel failed', { url, error: err.message });
+                return res.status(422).json({
+                    success: false,
+                    error: {
+                        type: 'fetch_failed',
+                        message: `Failed to fetch URL: ${err.message}`,
+                    },
+                });
+            }
+        }
+        if (!shareContent) {
+            return res.status(422).json({
+                success: false,
+                error: {
+                    type: 'empty_content',
+                    message: 'No content could be extracted from the URL.',
+                },
+            });
+        }
+        // Generate a unique ID with retry for collisions (extremely rare)
+        let shareId = '';
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const candidate = generateShareId();
+            const exists = await pool.query('SELECT 1 FROM shared_reads WHERE id = $1', [candidate]);
+            if (exists.rows.length === 0) {
+                shareId = candidate;
+                break;
+            }
+        }
+        if (!shareId) {
+            return res.status(500).json({
+                success: false,
+                error: { type: 'server_error', message: 'Failed to generate unique share ID.' },
+            });
+        }
+        // Insert share into DB
+        await pool.query(`INSERT INTO shared_reads (id, url, title, content, tokens, created_by)
+       VALUES ($1, $2, $3, $4, $5, $6)`, [shareId, url, shareTitle ?? null, shareContent, tokens ?? null, userId]);
+        const shareUrl = `${getBaseUrl()}/s/${shareId}`;
+        log.info('Share created', { shareId, url, userId });
+        return res.status(201).json({
+            success: true,
+            shareId,
+            shareUrl,
+        });
+    });
+    return router;
+}

package/dist/server/routes/transcript-export.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Transcript export endpoint
+ *
+ * GET /v1/transcript/export?url=<youtube_url>&format=srt|txt|md|json
+ *
+ * Downloads a YouTube transcript in the requested format with appropriate
+ * Content-Type and Content-Disposition headers.
+ */
+import { Router } from 'express';
+export declare function createTranscriptExportRouter(): Router;

package/dist/server/routes/transcript-export.js

@@ -0,0 +1,178 @@
+/**
+ * Transcript export endpoint
+ *
+ * GET /v1/transcript/export?url=<youtube_url>&format=srt|txt|md|json
+ *
+ * Downloads a YouTube transcript in the requested format with appropriate
+ * Content-Type and Content-Disposition headers.
+ */
+import { Router } from 'express';
+import crypto from 'crypto';
+import { getYouTubeTranscript, parseYouTubeUrl } from '../../core/youtube.js';
+import { toSRT, toTXT, toMarkdownDoc, toJSON } from '../../core/transcript-export.js';
+// Valid export format values
+const VALID_FORMATS = ['srt', 'txt', 'md', 'json'];
+// Content-Type and file extension per format
+const FORMAT_META = {
+    srt: { contentType: 'text/plain; charset=utf-8', ext: 'srt' },
+    txt: { contentType: 'text/plain; charset=utf-8', ext: 'txt' },
+    md: { contentType: 'text/markdown; charset=utf-8', ext: 'md' },
+    json: { contentType: 'application/json; charset=utf-8', ext: 'json' },
+};
+/**
+ * Sanitise a video title so it is safe to use as a filename.
+ * Strips special characters, collapses spaces to underscores, truncates to 80 chars.
+ */
+function safeFilename(title, fallback) {
+    const base = (title || fallback)
+        .replace(/[^\w\s\-._]/g, '')
+        .replace(/\s+/g, '_')
+        .replace(/_+/g, '_')
+        .slice(0, 80)
+        .replace(/^_+|_+$/g, '');
+    return base || fallback;
+}
+export function createTranscriptExportRouter() {
+    const router = Router();
+    /**
+     * GET /v1/transcript/export
+     *
+     * Query params:
+     *   url      - YouTube video URL (required)
+     *   format   - Output format: srt | txt | md | json  (default: txt)
+     *   language - Preferred transcript language code, e.g. "en" (default: "en")
+     *
+     * Response:
+     *   - 200  file download with appropriate Content-Type / Content-Disposition
+     *   - 400  invalid URL or format
+     *   - 401  missing API key
+     *   - 404  video has no captions
+     *   - 500  extraction failure
+     */
+    router.get('/v1/transcript/export', async (req, res) => {
+        // ── Auth ───────────────────────────────────────────────────────────────
+        const authId = req.auth?.keyInfo?.accountId || req.user?.userId;
+        if (!authId) {
+            res.status(401).json({
+                success: false,
+                error: {
+                    type: 'authentication_required',
+                    message: 'API key required. Get one at https://app.webpeel.dev/keys',
+                    hint: 'Pass your API key in the Authorization header: Bearer <key>',
+                    docs: 'https://webpeel.dev/docs/errors#authentication-required',
+                },
+                requestId: req.requestId || crypto.randomUUID(),
+            });
+            return;
+        }
+        const { url, format, language } = req.query;
+        // ── URL validation ─────────────────────────────────────────────────────
+        if (!url || typeof url !== 'string') {
+            res.status(400).json({
+                success: false,
+                error: {
+                    type: 'invalid_request',
+                    message: 'Missing or invalid "url" parameter. Pass a YouTube URL: GET /v1/transcript/export?url=https://youtu.be/VIDEO_ID&format=srt',
+                    docs: 'https://webpeel.dev/docs/errors#invalid-request',
+                },
+                requestId: req.requestId || crypto.randomUUID(),
+            });
+            return;
+        }
+        const videoId = parseYouTubeUrl(url);
+        if (!videoId) {
+            res.status(400).json({
+                success: false,
+                error: {
+                    type: 'invalid_youtube_url',
+                    message: 'The provided URL is not a valid YouTube video URL.',
+                    hint: 'Supported formats: https://www.youtube.com/watch?v=VIDEO_ID, https://youtu.be/VIDEO_ID',
+                    docs: 'https://webpeel.dev/docs/errors#invalid-youtube-url',
+                },
+                requestId: req.requestId || crypto.randomUUID(),
+            });
+            return;
+        }
+        // ── Format validation ──────────────────────────────────────────────────
+        const rawFormat = (typeof format === 'string' ? format : 'txt').toLowerCase();
+        if (!VALID_FORMATS.includes(rawFormat)) {
+            res.status(400).json({
+                success: false,
+                error: {
+                    type: 'invalid_format',
+                    message: `Invalid format "${format}". Supported formats: ${VALID_FORMATS.join(', ')}`,
+                    docs: 'https://webpeel.dev/docs/errors#invalid-format',
+                },
+                requestId: req.requestId || crypto.randomUUID(),
+            });
+            return;
+        }
+        const fmt = rawFormat;
+        // ── Extract transcript ─────────────────────────────────────────────────
+        try {
+            const lang = typeof language === 'string' ? language : 'en';
+            const transcript = await getYouTubeTranscript(url, { language: lang });
+            // ── Convert to requested format ──────────────────────────────────────
+            let content;
+            switch (fmt) {
+                case 'srt':
+                    content = toSRT(transcript.segments);
+                    break;
+                case 'txt':
+                    content = toTXT(transcript.segments);
+                    break;
+                case 'md':
+                    content = toMarkdownDoc(transcript.title, transcript.channel, transcript.segments);
+                    break;
+                case 'json':
+                    content = toJSON(transcript);
+                    break;
+            }
+            const { contentType, ext } = FORMAT_META[fmt];
+            const filename = safeFilename(transcript.title, videoId);
+            res.setHeader('Content-Type', contentType);
+            res.setHeader('Content-Disposition', `attachment; filename="${filename}.${ext}"`);
+            res.send(content);
+        }
+        catch (error) {
+            const message = error?.message ?? 'Failed to extract YouTube transcript';
+            if (message.includes('No captions available')) {
+                res.status(404).json({
+                    success: false,
+                    error: {
+                        type: 'no_captions',
+                        message: 'No captions are available for this video. The video may not have subtitles enabled.',
+                        hint: 'Try a different video or check if captions are enabled on YouTube.',
+                        docs: 'https://webpeel.dev/docs/errors#no-captions',
+                    },
+                    videoId,
+                    requestId: req.requestId || crypto.randomUUID(),
+                });
+                return;
+            }
+            if (message.includes('Not a valid YouTube URL')) {
+                res.status(400).json({
+                    success: false,
+                    error: {
+                        type: 'invalid_youtube_url',
+                        message,
+                        docs: 'https://webpeel.dev/docs/errors#invalid-youtube-url',
+                    },
+                    requestId: req.requestId || crypto.randomUUID(),
+                });
+                return;
+            }
+            res.status(500).json({
+                success: false,
+                error: {
+                    type: 'extraction_failed',
+                    message: 'Failed to extract YouTube transcript. The video page may have changed or the video is unavailable.',
+                    hint: process.env.NODE_ENV !== 'production' ? message : undefined,
+                    docs: 'https://webpeel.dev/docs/errors#extraction-failed',
+                },
+                requestId: req.requestId || crypto.randomUUID(),
+            });
+        }
+    });
+    return router;
+}

package/dist/server/routes/users.js

@@ -671,7 +671,10 @@ export function createUserRouter() {
     router.post('/v1/keys', jwtAuth, async (req, res) => {
         try {
             const { userId } = req.user;
-            const { name, expiresIn } = req.body;
+            const { name, expiresIn, scope } = req.body;
+            // Validate scope — only allow known values; default to 'full'
+            const validScopes = ['full', 'read', 'restricted'];
+            const keyScope = validScopes.includes(scope) ? scope : 'full';
             // Parse optional expiration
             const expiresAt = parseExpiresIn(expiresIn);
             // Generate API key
@@ -679,15 +682,16 @@ export function createUserRouter() {
             const keyHash = crypto.createHash('sha256').update(apiKey).digest('hex');
             const keyPrefix = PostgresAuthStore.getKeyPrefix(apiKey);
             // Store API key
-            const result = await pool.query(`INSERT INTO api_keys (user_id, key_hash, key_prefix, name, expires_at)
-        VALUES ($1, $2, $3, $4, $5)
-        RETURNING id, key_prefix, name, created_at, expires_at`, [userId, keyHash, keyPrefix, name || 'Unnamed Key', expiresAt]);
+            const result = await pool.query(`INSERT INTO api_keys (user_id, key_hash, key_prefix, name, expires_at, scope)
+        VALUES ($1, $2, $3, $4, $5, $6)
+        RETURNING id, key_prefix, name, created_at, expires_at, scope`, [userId, keyHash, keyPrefix, name || 'Unnamed Key', expiresAt, keyScope]);
             const key = result.rows[0];
             res.status(201).json({
                 id: key.id,
                 key: apiKey, // SECURITY: Only returned once
                 prefix: key.key_prefix,
                 name: key.name,
+                scope: key.scope,
                 createdAt: key.created_at,
                 expiresAt: key.expires_at,
             });
@@ -731,7 +735,7 @@ export function createUserRouter() {
     router.get('/v1/keys', jwtAuth, async (req, res) => {
         try {
             const { userId } = req.user;
-            const result = await pool.query(`SELECT id, key_prefix, name, is_active, created_at, last_used_at, expires_at
+            const result = await pool.query(`SELECT id, key_prefix, name, is_active, created_at, last_used_at, expires_at, scope
         FROM api_keys
         WHERE user_id = $1
         ORDER BY created_at DESC`, [userId]);
@@ -745,6 +749,7 @@ export function createUserRouter() {
                         prefix: key.key_prefix,
                         name: key.name,
                         isActive: key.is_active,
+                        scope: key.scope || 'full',
                         createdAt: key.created_at,
                         lastUsedAt: key.last_used_at,
                         expiresAt: key.expires_at,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webpeel",
-  "version": "0.20.20",
+  "version": "0.21.0",
   "description": "Fast web fetcher for AI agents - stealth mode, crawl mode, page actions, structured extraction, PDF parsing, smart escalation from simple HTTP to headless browser",
   "author": "Jake Liu",
   "license": "AGPL-3.0-only",