webpeel 0.20.2 → 0.20.3

package/dist/server/app.d.ts

@@ -0,0 +1,14 @@
+/**
+ * WebPeel API Server
+ * Express-based REST API for hosted deployments
+ */
+import { Express } from 'express';
+import './types.js';
+export interface ServerConfig {
+    port?: number;
+    corsOrigins?: string[];
+    rateLimitWindowMs?: number;
+    usePostgres?: boolean;
+}
+export declare function createApp(config?: ServerConfig): Express;
+export declare function startServer(config?: ServerConfig): void;

package/dist/server/app.js

@@ -0,0 +1,384 @@
+/**
+ * WebPeel API Server
+ * Express-based REST API for hosted deployments
+ */
+// Force IPv4-first DNS resolution to prevent IPv6 failures in containers
+// (Render's Docker containers can't do IPv6 outbound, causing IANA/Cloudflare sites to fail)
+import dns from 'dns';
+dns.setDefaultResultOrder('ipv4first');
+import express from 'express';
+import './types.js'; // Augments Express.Request with requestId
+import cors from 'cors';
+import { createLogger } from './logger.js';
+const log = createLogger('server');
+import { InMemoryAuthStore } from './auth-store.js';
+import { PostgresAuthStore } from './pg-auth-store.js';
+import { createAuthMiddleware } from './middleware/auth.js';
+import { createRateLimitMiddleware, RateLimiter } from './middleware/rate-limit.js';
+import { createHealthRouter } from './routes/health.js';
+import { createFetchRouter } from './routes/fetch.js';
+import { createSearchRouter } from './routes/search.js';
+import { createUserRouter } from './routes/users.js';
+import { createStripeRouter, createBillingPortalRouter } from './routes/stripe.js';
+import { createOAuthRouter } from './routes/oauth.js';
+import { createStatsRouter } from './routes/stats.js';
+import { createActivityRouter } from './routes/activity.js';
+import { createCLIUsageRouter } from './routes/cli-usage.js';
+import { createJobsRouter } from './routes/jobs.js';
+import { createBatchRouter } from './routes/batch.js';
+import { createAnswerRouter } from './routes/answer.js';
+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 { createDeepFetchRouter } from './routes/deep-fetch.js';
+import { createWatchRouter } from './routes/watch.js';
+import pg from 'pg';
+import { createScreenshotRouter } from './routes/screenshot.js';
+import { createDemoRouter } from './routes/demo.js';
+import { createPlaygroundRouter } from './routes/playground.js';
+import { createJobQueue } from './job-queue.js';
+import { createCompatRouter } from './routes/compat.js';
+import { createExtractRouter } from './routes/extract.js';
+import { createSessionRouter } from './routes/session.js';
+import { createSentryHooks } from './sentry.js';
+import { warmup, cleanup as cleanupFetcher } from '../core/fetcher.js';
+import { registerPremiumHooks } from './premium/index.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+// Resolve path to the OpenAPI spec (works from both src/ and dist/)
+const __dirname_app = dirname(fileURLToPath(import.meta.url));
+let _openApiYaml = null;
+function getOpenApiYaml() {
+    if (_openApiYaml !== null)
+        return _openApiYaml;
+    try {
+        // Try src/server/openapi.yaml relative to compiled dist/server/
+        const candidates = [
+            join(__dirname_app, 'openapi.yaml'),
+            join(__dirname_app, '..', '..', 'src', 'server', 'openapi.yaml'),
+        ];
+        for (const candidate of candidates) {
+            try {
+                _openApiYaml = readFileSync(candidate, 'utf-8');
+                return _openApiYaml;
+            }
+            catch {
+                // try next
+            }
+        }
+        throw new Error('openapi.yaml not found');
+    }
+    catch (e) {
+        return '# openapi.yaml not found\n';
+    }
+}
+export function createApp(config = {}) {
+    const app = express();
+    // SECURITY: Trust proxy for Render/production (HTTPS only)
+    app.set('trust proxy', 1);
+    // ─── Request ID ─────────────────────────────────────────────────────────────
+    // Generate a UUID v4 for every request so errors and logs are traceable.
+    // Must run before all other middleware so req.requestId is always set.
+    app.use((req, res, next) => {
+        req.requestId = crypto.randomUUID();
+        res.setHeader('X-Request-Id', req.requestId);
+        next();
+    });
+    // Hard server-side timeouts — no request runs longer than this
+    app.use((req, res, next) => {
+        const path = req.path;
+        let timeoutMs = 30000; // 30s default
+        if (path.includes('/crawl') || path.includes('/map'))
+            timeoutMs = 300000; // 5min for crawls
+        else if (path.includes('/batch'))
+            timeoutMs = 120000; // 2min for batch
+        else if (path.includes('/screenshot'))
+            timeoutMs = 60000; // 1min for screenshots
+        else if (req.query?.render === 'true')
+            timeoutMs = 60000; // 1min for rendered fetches
+        req.setTimeout(timeoutMs);
+        res.setTimeout(timeoutMs, () => {
+            if (!res.headersSent) {
+                res.status(504).json({
+                    success: false,
+                    error: {
+                        type: 'timeout',
+                        message: `Request timed out after ${timeoutMs / 1000}s`,
+                        hint: 'Try reducing the scope of your request or upgrading your plan for higher limits.',
+                        docs: 'https://webpeel.dev/docs/errors#timeout',
+                    },
+                    metadata: { requestId: req.requestId },
+                });
+            }
+        });
+        next();
+    });
+    // Optional error tracking (enabled only when SENTRY_DSN is set)
+    const sentry = createSentryHooks();
+    if (sentry.requestHandler) {
+        app.use(sentry.requestHandler);
+    }
+    // Stripe webhook route MUST come before express.json() to get raw body
+    const stripeRouter = createStripeRouter();
+    app.use('/v1/webhooks/stripe', express.raw({ type: 'application/json' }), stripeRouter);
+    // Middleware
+    // SECURITY: Limit request body size to prevent DoS
+    app.use(express.json({ limit: '1mb' }));
+    // CORS configuration
+    // Always allow our own domains + any env-configured origins
+    const envOrigins = process.env.CORS_ORIGINS ? process.env.CORS_ORIGINS.split(',').map(s => s.trim()) : [];
+    const defaultOrigins = [
+        'https://app.webpeel.dev',
+        'https://webpeel.dev',
+        // Only allow localhost in development (security: prevents credentialed cross-origin from local pages)
+        ...(process.env.NODE_ENV !== 'production' ? ['http://localhost:3000', 'http://localhost:3001'] : []),
+    ];
+    const corsOrigins = config.corsOrigins || [...new Set([...defaultOrigins, ...envOrigins])];
+    app.use(cors({
+        origin: (origin, callback) => {
+            // Allow requests with no origin (e.g. curl, server-to-server)
+            if (!origin)
+                return callback(null, true);
+            if (corsOrigins.includes(origin))
+                return callback(null, origin);
+            // Unknown origins: allow (API key clients need cross-origin access) but no credentials
+            return callback(null, true);
+        },
+        // credentials: set conditionally via post-cors middleware below
+        credentials: false,
+    }));
+    // Set Access-Control-Allow-Credentials only for trusted origins
+    app.use((req, res, next) => {
+        const origin = req.headers.origin;
+        if (origin && corsOrigins.includes(origin)) {
+            res.setHeader('Access-Control-Allow-Credentials', 'true');
+        }
+        next();
+    });
+    // SECURITY: Security headers
+    app.disable('x-powered-by');
+    app.use((_req, res, next) => {
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('X-Frame-Options', 'DENY');
+        res.setHeader('Strict-Transport-Security', 'max-age=63072000; includeSubDomains; preload');
+        res.setHeader('X-XSS-Protection', '1; mode=block');
+        res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+        res.setHeader('Permissions-Policy', 'geolocation=(), microphone=(), camera=()');
+        // API-safe CSP: JSON-only API does not need scripts/styles/fonts.
+        // Keep this strict to reduce attack surface without affecting API clients.
+        res.setHeader('Content-Security-Policy', "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'");
+        // Best-effort removal of Render's origin header (may be re-added by proxy)
+        res.removeHeader('x-render-origin-server');
+        next();
+    });
+    // SECURITY: JSON parse error handler
+    app.use((err, req, res, next) => {
+        if (err instanceof SyntaxError && 'body' in err) {
+            res.status(400).json({
+                success: false,
+                error: {
+                    type: 'invalid_request',
+                    message: 'Malformed JSON in request body',
+                    hint: 'Ensure the request body is valid JSON',
+                    docs: 'https://webpeel.dev/docs/api-reference#errors',
+                },
+                requestId: req.requestId,
+            });
+            return;
+        }
+        next(err);
+    });
+    // Auth store - Use PostgreSQL if DATABASE_URL is set, otherwise in-memory
+    const usePostgres = config.usePostgres ?? !!process.env.DATABASE_URL;
+    const authStore = usePostgres
+        ? new PostgresAuthStore()
+        : new InMemoryAuthStore();
+    log.info(`Using ${usePostgres ? 'PostgreSQL' : 'in-memory'} auth store`);
+    // PostgreSQL pool for features that need direct DB access (watch, etc.)
+    const pool = process.env.DATABASE_URL
+        ? new pg.Pool({
+            connectionString: process.env.DATABASE_URL,
+            ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: true } : false,
+        })
+        : null;
+    // Job queue - Use PostgreSQL if DATABASE_URL is set, otherwise in-memory
+    const jobQueue = createJobQueue();
+    // Rate limiter
+    const rateLimiter = new RateLimiter(config.rateLimitWindowMs || 3_600_000); // 1 hour
+    // Clean up rate limiter every 5 minutes
+    setInterval(() => {
+        rateLimiter.cleanup();
+    }, 5 * 60 * 1000);
+    // Health check MUST be before auth/rate-limit middleware
+    // Render hits /health every ~30s; rate-limiting it causes 429 → service marked as failed
+    app.use(createHealthRouter());
+    // OpenAPI spec — public, no auth required
+    app.get('/openapi.yaml', (_req, res) => {
+        res.setHeader('Content-Type', 'application/yaml; charset=utf-8');
+        res.setHeader('Cache-Control', 'public, max-age=3600');
+        res.send(getOpenApiYaml());
+    });
+    // Redirect /openapi.json to YAML spec (no extra dependency needed)
+    app.get('/openapi.json', (_req, res) => {
+        res.redirect(301, '/openapi.yaml');
+    });
+    // Developer-friendly redirect
+    app.get('/docs/api', (_req, res) => {
+        res.redirect('/openapi.yaml');
+    });
+    // Demo endpoint — unauthenticated, must be before auth middleware
+    app.use(createDemoRouter());
+    // Playground endpoint — unauthenticated, CORS-locked to webpeel.dev/localhost
+    app.use('/v1/playground', createPlaygroundRouter());
+    // Apply auth middleware globally
+    app.use(createAuthMiddleware(authStore));
+    // Apply rate limiting middleware globally
+    app.use(createRateLimitMiddleware(rateLimiter));
+    app.use(createCompatRouter(jobQueue));
+    app.use(createSessionRouter());
+    app.use(createExtractRouter());
+    app.use(createDeepFetchRouter());
+    if (pool) {
+        app.use(createWatchRouter(pool));
+    }
+    app.use(createFetchRouter(authStore));
+    app.use(createScreenshotRouter(authStore));
+    app.use(createSearchRouter(authStore));
+    app.use(createBillingPortalRouter(pool));
+    app.use(createUserRouter());
+    app.use(createOAuthRouter());
+    app.use(createStatsRouter(authStore));
+    app.use(createActivityRouter(authStore));
+    app.use(createCLIUsageRouter());
+    app.use(createJobsRouter(jobQueue, authStore));
+    app.use(createBatchRouter(jobQueue));
+    // Deprecation headers for declining endpoints
+    app.use('/v1/answer', (_req, res, next) => {
+        res.set('Deprecation', 'true');
+        res.set('Sunset', '2026-06-01');
+        res.set('Link', '</v1/ask>; rel="successor-version"');
+        next();
+    });
+    app.use(createAnswerRouter());
+    app.use(createAskRouter());
+    app.use('/v1/do', createDoRouter());
+    app.use(createYouTubeRouter());
+    app.use(createMcpRouter(authStore, pool));
+    // 404 handler
+    app.use((req, res) => {
+        res.status(404).json({
+            success: false,
+            error: {
+                type: 'not_found',
+                message: 'Not found',
+                docs: 'https://webpeel.dev/docs/api-reference',
+            },
+            requestId: req.requestId,
+        });
+    });
+    // Sentry error middleware should run before the generic error handler.
+    if (sentry.errorHandler) {
+        app.use(sentry.errorHandler);
+    }
+    // Global error response normalizer — ensures ALL errors use the same structured shape.
+    // Catches errors thrown via next(err) that may have a flat format {error: string, message: string}.
+    // Must run before the generic error handler below.
+    app.use((err, req, res, next) => {
+        // Skip if error is already in structured format (has error.type or error.message as object)
+        if (err && typeof err.error === 'object' && err.error !== null) {
+            return next(err);
+        }
+        // Skip standard Error objects (handled by the generic error handler with Playwright sanitization)
+        if (err instanceof Error && !err.hasOwnProperty('statusCode') && !err.hasOwnProperty('status')) {
+            return next(err);
+        }
+        const statusCode = (err && (err.statusCode || err.status)) || 500;
+        if (res.headersSent)
+            return next(err);
+        const requestId = req.requestId || req.headers['x-request-id'] || crypto.randomUUID();
+        res.status(statusCode).json({
+            success: false,
+            error: {
+                type: (err && (err.type || err.error)) || 'server_error',
+                message: (err && err.message) || 'An unexpected error occurred',
+                ...((err && err.hint) ? { hint: err.hint } : {}),
+                ...((err && err.docs) ? { docs: err.docs } : {}),
+            },
+            requestId,
+        });
+    });
+    // Error handler - SECURITY: sanitize errors in production to prevent leaking
+    // Playwright stack traces, internal paths, or other sensitive details.
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    app.use((err, req, res, _next) => {
+        log.error('Unhandled error', { message: err.message, stack: err.stack }); // Log full error server-side
+        if (res.headersSent)
+            return; // Avoid double-send crash
+        if (process.env.NODE_ENV === 'production') {
+            // Strip Playwright/browser launch errors and stack traces from responses
+            const sanitized = (err.message || 'An unexpected error occurred')
+                .replace(/browserType\.launch:.*$/s, 'Browser rendering unavailable on this server. Use the CLI with --render for browser-rendered content.')
+                .replace(/at\s+\S.*\n?/g, '') // strip "at <location>" stack lines
+                .trim() || 'An unexpected error occurred';
+            res.status(500).json({
+                success: false,
+                error: {
+                    type: 'internal_error',
+                    message: sanitized,
+                    docs: 'https://webpeel.dev/docs/api-reference#errors',
+                },
+                requestId: req.requestId,
+            });
+        }
+        else {
+            res.status(500).json({
+                success: false,
+                error: {
+                    type: 'internal_error',
+                    message: err.message || 'An unexpected error occurred',
+                    docs: 'https://webpeel.dev/docs/api-reference#errors',
+                },
+                requestId: req.requestId,
+                stack: err.stack,
+            });
+        }
+    });
+    return app;
+}
+export function startServer(config = {}) {
+    const app = createApp(config);
+    const port = config.port || parseInt(process.env.PORT || '3000', 10);
+    // Activate premium strategy hooks (SWR cache, domain intelligence, race).
+    registerPremiumHooks();
+    // Pre-warm browser resources in the background to reduce first-request latency.
+    void warmup().catch((error) => {
+        log.warn('Browser warmup failed', { error: error instanceof Error ? error.message : String(error) });
+    });
+    const server = app.listen(port, () => {
+        log.info(`WebPeel API server listening on port ${port}`);
+        log.info(`Health: http://localhost:${port}/health  Fetch: /v1/fetch  Search: /v1/search`);
+    });
+    // Graceful shutdown
+    const shutdown = () => {
+        log.info('Shutting down gracefully...');
+        server.close(() => {
+            log.info('Server closed');
+            void cleanupFetcher().finally(() => {
+                process.exit(0);
+            });
+        });
+        // Force shutdown after 10 seconds
+        setTimeout(() => {
+            log.error('Forced shutdown after timeout');
+            process.exit(1);
+        }, 10000);
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+}
+// Start server if run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    startServer();
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Auth store abstraction for API key validation and usage tracking
+ * Designed to easily swap from in-memory to PostgreSQL
+ */
+export interface ApiKeyInfo {
+    key: string;
+    tier: 'free' | 'starter' | 'pro' | 'enterprise' | 'max';
+    rateLimit: number;
+    accountId?: string;
+    createdAt: Date;
+}
+export interface AuthStore {
+    validateKey(key: string): Promise<ApiKeyInfo | null>;
+    trackUsage(key: string, creditsOrType: number | 'basic' | 'stealth' | 'captcha' | 'search'): Promise<void>;
+}
+/**
+ * In-memory auth store for development and self-hosted deployments
+ */
+export declare class InMemoryAuthStore implements AuthStore {
+    private keys;
+    private usage;
+    constructor();
+    validateKey(key: string): Promise<ApiKeyInfo | null>;
+    trackUsage(key: string, creditsOrType: number | 'basic' | 'stealth' | 'captcha' | 'search'): Promise<void>;
+    addKey(keyInfo: ApiKeyInfo): void;
+    getUsage(key: string): number;
+}

package/dist/server/auth-store.js

@@ -0,0 +1,88 @@
+/**
+ * Auth store abstraction for API key validation and usage tracking
+ * Designed to easily swap from in-memory to PostgreSQL
+ */
+import { timingSafeEqual } from 'crypto';
+/**
+ * Validate API key format and strength
+ * SECURITY: Enforce minimum complexity
+ */
+function validateKeyFormat(key) {
+    // Minimum 32 characters
+    if (key.length < 32) {
+        return false;
+    }
+    // Must contain alphanumeric characters
+    if (!/^[a-zA-Z0-9_-]+$/.test(key)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Timing-safe key comparison
+ * SECURITY: Prevent timing attacks on key validation
+ */
+function timingSafeKeyCompare(a, b) {
+    // Ensure equal length for comparison
+    if (a.length !== b.length) {
+        // Compare against dummy to prevent timing leak
+        const dummy = 'x'.repeat(Math.max(a.length, b.length));
+        timingSafeEqual(Buffer.from(dummy), Buffer.from(dummy));
+        return false;
+    }
+    try {
+        return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * In-memory auth store for development and self-hosted deployments
+ */
+export class InMemoryAuthStore {
+    keys = new Map();
+    usage = new Map();
+    constructor() {
+        // SECURITY: Demo key only in development mode
+        // Removed hardcoded demo key - use addKey() or environment variables
+        if (process.env.NODE_ENV === 'development' && process.env.DEMO_KEY) {
+            this.addKey({
+                key: process.env.DEMO_KEY,
+                tier: 'pro',
+                rateLimit: 300,
+                createdAt: new Date(),
+            });
+        }
+    }
+    async validateKey(key) {
+        // Basic validation
+        if (!key || typeof key !== 'string') {
+            return null;
+        }
+        // SECURITY: Timing-safe comparison to prevent timing attacks
+        for (const [storedKey, keyInfo] of this.keys.entries()) {
+            if (timingSafeKeyCompare(key, storedKey)) {
+                return keyInfo;
+            }
+        }
+        // Constant-time operation for invalid key
+        return null;
+    }
+    async trackUsage(key, creditsOrType) {
+        // For in-memory store, just count everything as 1 credit
+        const credits = typeof creditsOrType === 'number' ? creditsOrType : 1;
+        const current = this.usage.get(key) || 0;
+        this.usage.set(key, current + credits);
+    }
+    addKey(keyInfo) {
+        // SECURITY: Validate key format before adding
+        if (!validateKeyFormat(keyInfo.key)) {
+            throw new Error('Invalid API key format: must be at least 32 characters, alphanumeric with - or _');
+        }
+        this.keys.set(keyInfo.key, keyInfo);
+    }
+    getUsage(key) {
+        return this.usage.get(key) || 0;
+    }
+}

package/dist/server/email-service.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Email service using Nodemailer (free, no API key required).
+ * Configure via environment variables:
+ *   EMAIL_SMTP_HOST - SMTP server (e.g. smtp.gmail.com)
+ *   EMAIL_SMTP_PORT - SMTP port (default: 587)
+ *   EMAIL_SMTP_USER - SMTP username / email address
+ *   EMAIL_SMTP_PASS - SMTP password (Gmail: use App Password)
+ *   EMAIL_FROM      - From address (default: EMAIL_SMTP_USER)
+ *
+ * Gmail setup: https://myaccount.google.com/apppasswords
+ * Use "App Password" (not your regular password).
+ */
+export interface UsageAlertEmailParams {
+    toEmail: string;
+    userName?: string;
+    usagePercent: number;
+    used: number;
+    total: number;
+    tier: string;
+}
+export declare function sendUsageAlertEmail(params: UsageAlertEmailParams): Promise<boolean>;

package/dist/server/email-service.js

@@ -0,0 +1,79 @@
+/**
+ * Email service using Nodemailer (free, no API key required).
+ * Configure via environment variables:
+ *   EMAIL_SMTP_HOST - SMTP server (e.g. smtp.gmail.com)
+ *   EMAIL_SMTP_PORT - SMTP port (default: 587)
+ *   EMAIL_SMTP_USER - SMTP username / email address
+ *   EMAIL_SMTP_PASS - SMTP password (Gmail: use App Password)
+ *   EMAIL_FROM      - From address (default: EMAIL_SMTP_USER)
+ *
+ * Gmail setup: https://myaccount.google.com/apppasswords
+ * Use "App Password" (not your regular password).
+ */
+import nodemailer from 'nodemailer';
+function createTransport() {
+    const host = process.env.EMAIL_SMTP_HOST;
+    const user = process.env.EMAIL_SMTP_USER;
+    const pass = process.env.EMAIL_SMTP_PASS;
+    if (!host || !user || !pass) {
+        return null;
+    }
+    return nodemailer.createTransport({
+        host,
+        port: parseInt(process.env.EMAIL_SMTP_PORT || '587'),
+        secure: process.env.EMAIL_SMTP_PORT === '465',
+        auth: { user, pass },
+    });
+}
+export async function sendUsageAlertEmail(params) {
+    const transport = createTransport();
+    if (!transport) {
+        console.warn('[email] SMTP not configured. Set EMAIL_SMTP_HOST, EMAIL_SMTP_USER, EMAIL_SMTP_PASS to enable email alerts.');
+        return false;
+    }
+    const from = process.env.EMAIL_FROM || process.env.EMAIL_SMTP_USER;
+    const html = buildUsageAlertHtml(params);
+    try {
+        await transport.sendMail({
+            from: `WebPeel <${from}>`,
+            to: params.toEmail,
+            subject: `WebPeel: You've used ${params.usagePercent}% of your weekly API limit`,
+            html,
+        });
+        return true;
+    }
+    catch (err) {
+        console.error('[email] Failed to send usage alert:', err);
+        return false;
+    }
+}
+function buildUsageAlertHtml(params) {
+    const { usagePercent, used, total, tier, userName } = params;
+    const color = usagePercent >= 90 ? '#ef4444' : usagePercent >= 75 ? '#f59e0b' : '#5865F2';
+    return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>WebPeel Usage Alert</title></head>
+<body style="margin:0;padding:0;background:#0A0A0F;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;">
+  <div style="max-width:520px;margin:40px auto;background:#111116;border:1px solid #27272a;border-radius:12px;overflow:hidden;">
+    <div style="background:${color};padding:4px 24px;"></div>
+    <div style="padding:32px 24px;">
+      <div style="font-size:24px;font-weight:700;color:#ffffff;margin-bottom:8px;">Usage Alert</div>
+      <div style="font-size:15px;color:#a1a1aa;margin-bottom:24px;">
+        ${userName ? `Hi ${userName}, you've` : "You've"} used <strong style="color:#ffffff;">${usagePercent}%</strong> of your weekly API limit.
+      </div>
+      <div style="background:#18181b;border-radius:8px;padding:16px;margin-bottom:24px;">
+        <div style="font-size:13px;color:#a1a1aa;margin-bottom:8px;">Usage this week</div>
+        <div style="height:8px;background:#27272a;border-radius:4px;overflow:hidden;">
+          <div style="height:100%;width:${Math.min(usagePercent, 100)}%;background:${color};border-radius:4px;"></div>
+        </div>
+        <div style="font-size:13px;color:#a1a1aa;margin-top:8px;">${used} / ${total} requests · ${tier} plan</div>
+      </div>
+      <a href="https://app.webpeel.dev/billing" style="display:inline-block;background:#5865F2;color:#ffffff;padding:12px 24px;border-radius:8px;text-decoration:none;font-weight:600;font-size:14px;">Upgrade Plan →</a>
+      <div style="font-size:12px;color:#71717a;margin-top:24px;">
+        To disable these alerts, visit <a href="https://app.webpeel.dev/settings" style="color:#5865F2;">Settings</a>.
+      </div>
+    </div>
+  </div>
+</body>
+</html>`;
+}