@iflow-mcp/jakeliume-webpeel 0.22.0

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/usage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Usage API endpoints — professional usage tracking
+ *
+ * GET /v1/usage            — current period usage (credits, remaining, period dates)
+ * GET /v1/usage/historical — per-week history (last 12 weeks)
+ * GET /v1/usage/daily      — daily breakdown for current week
+ */
+import { Router } from 'express';
+export declare function createUsageRouter(): Router;

package/dist/server/routes/usage.js

@@ -0,0 +1,279 @@
+/**
+ * Usage API endpoints — professional usage tracking
+ *
+ * GET /v1/usage            — current period usage (credits, remaining, period dates)
+ * GET /v1/usage/historical — per-week history (last 12 weeks)
+ * GET /v1/usage/daily      — daily breakdown for current week
+ */
+import { Router } from 'express';
+import pg from 'pg';
+const { Pool } = pg;
+// ─── ISO week helpers ────────────────────────────────────────────────────────
+/** Parse an ISO week string (e.g. "2026-W13") → Monday 00:00 UTC */
+function isoWeekToMonday(week) {
+    const [yearStr, wStr] = week.split('-W');
+    const year = parseInt(yearStr, 10);
+    const weekNum = parseInt(wStr, 10);
+    // ISO week 1 = the week containing Jan 4th
+    const jan4 = new Date(Date.UTC(year, 0, 4));
+    const jan4DayOfWeek = jan4.getUTCDay() || 7; // Mon=1 … Sun=7
+    const monday = new Date(jan4);
+    monday.setUTCDate(jan4.getUTCDate() - (jan4DayOfWeek - 1) + (weekNum - 1) * 7);
+    return monday;
+}
+/** Return the current ISO week string, e.g. "2026-W13" */
+function getCurrentWeek() {
+    const now = new Date();
+    const year = now.getUTCFullYear();
+    const jan4 = new Date(Date.UTC(year, 0, 4));
+    const weekNum = Math.ceil(((now.getTime() - jan4.getTime()) / 86_400_000 + jan4.getUTCDay() + 1) / 7);
+    return `${year}-W${String(weekNum).padStart(2, '0')}`;
+}
+/** Subtract `n` weeks from a week string */
+function subtractWeeks(week, n) {
+    const monday = isoWeekToMonday(week);
+    monday.setUTCDate(monday.getUTCDate() - n * 7);
+    const year = monday.getUTCFullYear();
+    const jan4 = new Date(Date.UTC(year, 0, 4));
+    const weekNum = Math.ceil(((monday.getTime() - jan4.getTime()) / 86_400_000 + jan4.getUTCDay() + 1) / 7);
+    return `${year}-W${String(weekNum).padStart(2, '0')}`;
+}
+// ─── 501 stub (no DB configured) ─────────────────────────────────────────────
+function noDB(req, res) {
+    res.status(501).json({
+        success: false,
+        error: {
+            type: 'not_configured',
+            message: 'Usage tracking requires PostgreSQL backend',
+            docs: 'https://webpeel.dev/docs/errors#not_configured',
+        },
+        requestId: req.requestId,
+    });
+}
+// ─── Router factory ───────────────────────────────────────────────────────────
+export function createUsageRouter() {
+    const router = Router();
+    const dbUrl = process.env.DATABASE_URL;
+    if (!dbUrl) {
+        router.get('/v1/usage', noDB);
+        router.get('/v1/usage/historical', noDB);
+        router.get('/v1/usage/daily', noDB);
+        return router;
+    }
+    const pool = new Pool({
+        connectionString: dbUrl,
+        ssl: dbUrl.includes('sslmode=require')
+            ? { rejectUnauthorized: process.env.PG_REJECT_UNAUTHORIZED !== 'false' }
+            : undefined,
+        max: 5,
+    });
+    // ── GET /v1/usage ─────────────────────────────────────────────────────────
+    router.get('/v1/usage', async (req, res) => {
+        try {
+            if (!req.auth?.keyInfo?.accountId) {
+                res.status(401).json({
+                    success: false,
+                    error: { type: 'unauthorized', message: 'Valid API key required', docs: 'https://webpeel.dev/docs/authentication' },
+                    requestId: req.requestId,
+                });
+                return;
+            }
+            const userId = req.auth.keyInfo.accountId;
+            const currentWeek = getCurrentWeek();
+            const now = new Date();
+            const currentHour = now.toISOString().substring(0, 13); // "2026-03-26T10"
+            // Plan
+            const planResult = await pool.query('SELECT tier, weekly_limit, burst_limit FROM users WHERE id = $1', [userId]);
+            if (planResult.rows.length === 0) {
+                res.status(404).json({ success: false, error: { type: 'user_not_found', message: 'User not found' }, requestId: req.requestId });
+                return;
+            }
+            const plan = planResult.rows[0];
+            const weeklyLimit = plan.weekly_limit || 125;
+            const burstLimit = plan.burst_limit || 25;
+            // Weekly usage (sum across all active API keys)
+            const weeklyResult = await pool.query(`SELECT
+          COALESCE(SUM(wu.basic_count), 0)   AS basic_count,
+          COALESCE(SUM(wu.stealth_count), 0) AS stealth_count,
+          COALESCE(SUM(wu.captcha_count), 0) AS captcha_count,
+          COALESCE(SUM(wu.search_count), 0)  AS search_count,
+          COALESCE(SUM(wu.total_count), 0)   AS total_count,
+          COALESCE(MAX(wu.rollover_credits), 0) AS rollover_credits
+        FROM api_keys ak
+        LEFT JOIN weekly_usage wu
+          ON wu.api_key_id = ak.id AND wu.week = $2
+        WHERE ak.user_id = $1 AND ak.is_active = true`, [userId, currentWeek]);
+            const weekly = weeklyResult.rows[0];
+            const creditsUsed = parseInt(weekly.total_count) || 0;
+            const rolloverCredits = parseInt(weekly.rollover_credits) || 0;
+            const creditsTotal = weeklyLimit + rolloverCredits;
+            const creditsRemaining = Math.max(0, creditsTotal - creditsUsed);
+            // Period dates
+            const weekStart = isoWeekToMonday(currentWeek);
+            const weekEnd = new Date(weekStart);
+            weekEnd.setUTCDate(weekStart.getUTCDate() + 7);
+            // Burst usage
+            const burstResult = await pool.query(`SELECT COALESCE(SUM(bu.count), 0) AS burst_used
+        FROM api_keys ak
+        LEFT JOIN burst_usage bu
+          ON bu.api_key_id = ak.id AND bu.hour_bucket = $2
+        WHERE ak.user_id = $1 AND ak.is_active = true`, [userId, currentHour]);
+            const burstUsed = parseInt(burstResult.rows[0]?.burst_used) || 0;
+            const minutesRemaining = 59 - now.getUTCMinutes();
+            res.json({
+                success: true,
+                data: {
+                    plan: {
+                        tier: plan.tier,
+                        weeklyLimit,
+                        burstLimit,
+                    },
+                    currentPeriod: {
+                        week: currentWeek,
+                        start: weekStart.toISOString(),
+                        end: weekEnd.toISOString(),
+                        creditsUsed,
+                        creditsRemaining,
+                        creditsTotal,
+                        rolloverCredits,
+                        percentUsed: creditsTotal > 0 ? Math.round((creditsUsed / creditsTotal) * 1000) / 10 : 0,
+                        breakdown: {
+                            fetch: parseInt(weekly.basic_count) || 0,
+                            search: parseInt(weekly.search_count) || 0,
+                            stealth: parseInt(weekly.stealth_count) || 0,
+                            captcha: parseInt(weekly.captcha_count) || 0,
+                        },
+                    },
+                    burst: {
+                        currentHour,
+                        used: burstUsed,
+                        limit: burstLimit,
+                        remaining: Math.max(0, burstLimit - burstUsed),
+                        resetsIn: minutesRemaining <= 0 ? '< 1m' : `${minutesRemaining}m`,
+                    },
+                    canFetch: creditsRemaining > 0 && burstUsed < burstLimit,
+                    upgradeUrl: 'https://webpeel.dev/pricing',
+                },
+            });
+        }
+        catch (err) {
+            console.error('[usage] GET /v1/usage error:', err);
+            res.status(500).json({
+                success: false,
+                error: { type: 'internal_error', message: 'Failed to retrieve usage', docs: 'https://webpeel.dev/docs/errors#internal_error' },
+                requestId: req.requestId,
+            });
+        }
+    });
+    // ── GET /v1/usage/historical ──────────────────────────────────────────────
+    router.get('/v1/usage/historical', async (req, res) => {
+        try {
+            if (!req.auth?.keyInfo?.accountId) {
+                res.status(401).json({
+                    success: false,
+                    error: { type: 'unauthorized', message: 'Valid API key required', docs: 'https://webpeel.dev/docs/authentication' },
+                    requestId: req.requestId,
+                });
+                return;
+            }
+            const userId = req.auth.keyInfo.accountId;
+            const currentWeek = getCurrentWeek();
+            const oldestWeek = subtractWeeks(currentWeek, 11); // 12 weeks total
+            const result = await pool.query(`SELECT
+          wu.week,
+          SUM(wu.basic_count)   AS basic_count,
+          SUM(wu.stealth_count) AS stealth_count,
+          SUM(wu.captcha_count) AS captcha_count,
+          SUM(wu.search_count)  AS search_count,
+          SUM(wu.total_count)   AS total_count
+        FROM api_keys ak
+        JOIN weekly_usage wu ON wu.api_key_id = ak.id
+        WHERE ak.user_id = $1
+          AND wu.week >= $2
+          AND wu.week <= $3
+        GROUP BY wu.week
+        ORDER BY wu.week DESC`, [userId, oldestWeek, currentWeek]);
+            const periods = result.rows.map((row) => {
+                const weekStart = isoWeekToMonday(row.week);
+                const weekEnd = new Date(weekStart);
+                weekEnd.setUTCDate(weekStart.getUTCDate() + 7);
+                return {
+                    week: row.week,
+                    start: weekStart.toISOString(),
+                    end: weekEnd.toISOString(),
+                    creditsUsed: parseInt(row.total_count) || 0,
+                    breakdown: {
+                        fetch: parseInt(row.basic_count) || 0,
+                        search: parseInt(row.search_count) || 0,
+                        stealth: parseInt(row.stealth_count) || 0,
+                        captcha: parseInt(row.captcha_count) || 0,
+                    },
+                };
+            });
+            const total = periods.reduce((sum, p) => sum + p.creditsUsed, 0);
+            res.json({
+                success: true,
+                data: { periods, total },
+            });
+        }
+        catch (err) {
+            console.error('[usage] GET /v1/usage/historical error:', err);
+            res.status(500).json({
+                success: false,
+                error: { type: 'internal_error', message: 'Failed to retrieve historical usage', docs: 'https://webpeel.dev/docs/errors#internal_error' },
+                requestId: req.requestId,
+            });
+        }
+    });
+    // ── GET /v1/usage/daily ───────────────────────────────────────────────────
+    router.get('/v1/usage/daily', async (req, res) => {
+        try {
+            if (!req.auth?.keyInfo?.accountId) {
+                res.status(401).json({
+                    success: false,
+                    error: { type: 'unauthorized', message: 'Valid API key required', docs: 'https://webpeel.dev/docs/authentication' },
+                    requestId: req.requestId,
+                });
+                return;
+            }
+            const userId = req.auth.keyInfo.accountId;
+            const currentWeek = getCurrentWeek();
+            const weekStart = isoWeekToMonday(currentWeek);
+            const weekEnd = new Date(weekStart);
+            weekEnd.setUTCDate(weekStart.getUTCDate() + 7);
+            const result = await pool.query(`SELECT
+          DATE(created_at)                                               AS date,
+          COUNT(*)                                                       AS requests,
+          ROUND(
+            100.0 * SUM(CASE WHEN status_code < 400 THEN 1 ELSE 0 END)
+            / NULLIF(COUNT(*), 0), 1
+          )                                                              AS success_rate,
+          ROUND(AVG(processing_time_ms))                                 AS avg_response_time
+        FROM usage_logs
+        WHERE user_id = $1
+          AND created_at >= $2
+          AND created_at < $3
+        GROUP BY DATE(created_at)
+        ORDER BY DATE(created_at) ASC`, [userId, weekStart.toISOString(), weekEnd.toISOString()]);
+            const days = result.rows.map((row) => ({
+                date: row.date instanceof Date ? row.date.toISOString().slice(0, 10) : String(row.date),
+                requests: parseInt(row.requests) || 0,
+                successRate: parseFloat(row.success_rate) || 0,
+                avgResponseTime: parseInt(row.avg_response_time) || 0,
+            }));
+            res.json({
+                success: true,
+                data: { days },
+            });
+        }
+        catch (err) {
+            console.error('[usage] GET /v1/usage/daily error:', err);
+            res.status(500).json({
+                success: false,
+                error: { type: 'internal_error', message: 'Failed to retrieve daily usage', docs: 'https://webpeel.dev/docs/errors#internal_error' },
+                requestId: req.requestId,
+            });
+        }
+    });
+    return router;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * User authentication and API key management routes
+ */
+import { Router } from 'express';
+/**
+ * Create user routes
+ */
+export declare function createUserRouter(): Router;