webpeel 0.20.2 → 0.20.3

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

@@ -0,0 +1,15 @@
+/**
+ * WebPeel Watch REST API
+ *
+ * POST   /v1/watch           — Create a new watch
+ * GET    /v1/watch           — List watches for the authenticated account
+ * GET    /v1/watch/:id       — Get a single watch entry
+ * POST   /v1/watch/:id/check — Manually trigger a content check
+ * PATCH  /v1/watch/:id       — Update a watch (pause/resume/interval)
+ * DELETE /v1/watch/:id       — Delete a watch
+ *
+ * All routes require API-key authentication via the global auth middleware.
+ */
+import { Router } from 'express';
+import pg from 'pg';
+export declare function createWatchRouter(pool: pg.Pool): Router;

package/dist/server/routes/watch.js

@@ -0,0 +1,309 @@
+/**
+ * WebPeel Watch REST API
+ *
+ * POST   /v1/watch           — Create a new watch
+ * GET    /v1/watch           — List watches for the authenticated account
+ * GET    /v1/watch/:id       — Get a single watch entry
+ * POST   /v1/watch/:id/check — Manually trigger a content check
+ * PATCH  /v1/watch/:id       — Update a watch (pause/resume/interval)
+ * DELETE /v1/watch/:id       — Delete a watch
+ *
+ * All routes require API-key authentication via the global auth middleware.
+ */
+import { Router } from 'express';
+import { WatchManager, computeLineDiff } from '../../core/watch-manager.js';
+/** Rough token estimate: ~4 characters per token (GPT-style approximation). */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export function createWatchRouter(pool) {
+    const router = Router();
+    const manager = new WatchManager(pool);
+    // ─── Require authentication helper ─────────────────────────────────────────
+    function requireAuth(req, res) {
+        const accountId = req.auth?.keyInfo?.accountId;
+        if (!accountId) {
+            res.status(401).json({
+                success: false,
+                error: { type: 'unauthorized', message: 'API key required. Pass via Authorization: Bearer <key>.', docs: 'https://webpeel.dev/docs/authentication' },
+                requestId: req.requestId,
+            });
+            return null;
+        }
+        return accountId;
+    }
+    // ─── POST /v1/watch — create a watch ────────────────────────────────────────
+    router.post('/v1/watch', async (req, res) => {
+        const accountId = requireAuth(req, res);
+        if (!accountId)
+            return;
+        const { url, webhookUrl, checkIntervalMinutes, intervalMinutes: intervalMinutesAlias, interval, selector } = req.body;
+        // Accept interval aliases: checkIntervalMinutes (canonical), intervalMinutes, interval
+        const resolvedIntervalInput = checkIntervalMinutes ?? intervalMinutesAlias ?? interval;
+        if (!url || typeof url !== 'string') {
+            res.status(400).json({
+                success: false,
+                error: { type: 'invalid_request', message: 'Missing or invalid "url" parameter.' },
+                requestId: req.requestId,
+            });
+            return;
+        }
+        if (url.length > 2048) {
+            res.status(400).json({
+                success: false,
+                error: { type: 'invalid_url', message: 'URL too long (max 2048 characters).' },
+                requestId: req.requestId,
+            });
+            return;
+        }
+        try {
+            new URL(url);
+        }
+        catch {
+            res.status(400).json({
+                success: false,
+                error: { type: 'invalid_url', message: 'URL format is invalid.', hint: 'Ensure the URL includes a scheme (https://) and a valid hostname.' },
+                requestId: req.requestId,
+            });
+            return;
+        }
+        if (webhookUrl !== undefined && (typeof webhookUrl !== 'string' || webhookUrl.length > 2048)) {
+            res.status(400).json({ success: false, error: { type: 'invalid_request', message: 'Invalid "webhookUrl".' }, requestId: req.requestId });
+            return;
+        }
+        const intervalMinutes = resolvedIntervalInput !== undefined ? Number(resolvedIntervalInput) : 60;
+        if (!Number.isFinite(intervalMinutes) || intervalMinutes < 1 || intervalMinutes > 44640) {
+            res.status(400).json({
+                success: false,
+                error: { type: 'invalid_request', message: '"checkIntervalMinutes" must be between 1 and 44640 (31 days).' },
+                requestId: req.requestId,
+            });
+            return;
+        }
+        try {
+            const entry = await manager.create(accountId, url, {
+                webhookUrl: typeof webhookUrl === 'string' ? webhookUrl : undefined,
+                checkIntervalMinutes: intervalMinutes,
+                selector: typeof selector === 'string' ? selector : undefined,
+            });
+            res.status(201).json({ ok: true, watch: entry });
+        }
+        catch (err) {
+            console.error('[watch] create error:', err);
+            res.status(500).json({
+                success: false,
+                error: { type: 'internal_error', message: 'Failed to create watch.' },
+                requestId: req.requestId,
+            });
+        }
+    });
+    // ─── GET /v1/watch — list watches ───────────────────────────────────────────
+    router.get('/v1/watch', async (req, res) => {
+        const accountId = requireAuth(req, res);
+        if (!accountId)
+            return;
+        try {
+            const watches = await manager.list(accountId);
+            res.json({ ok: true, watches });
+        }
+        catch (err) {
+            console.error('[watch] list error:', err);
+            res.status(500).json({
+                success: false,
+                error: { type: 'internal_error', message: 'Failed to list watches.' },
+                requestId: req.requestId,
+            });
+        }
+    });
+    // ─── GET /v1/watch/:id — get a watch ────────────────────────────────────────
+    router.get('/v1/watch/:id', async (req, res) => {
+        const accountId = requireAuth(req, res);
+        if (!accountId)
+            return;
+        const watchId = req.params['id'];
+        try {
+            const entry = await manager.get(watchId);
+            if (!entry) {
+                res.status(404).json({
+                    success: false,
+                    error: { type: 'not_found', message: 'Watch not found.' },
+                    requestId: req.requestId,
+                });
+                return;
+            }
+            if (entry.accountId !== accountId) {
+                res.status(403).json({ success: false, error: { type: 'forbidden', message: 'Access denied.' }, requestId: req.requestId });
+                return;
+            }
+            res.json({ ok: true, watch: entry });
+        }
+        catch (err) {
+            console.error('[watch] get error:', err);
+            res.status(500).json({
+                success: false,
+                error: { type: 'internal_error', message: 'Failed to get watch.' },
+                requestId: req.requestId,
+            });
+        }
+    });
+    // ─── POST /v1/watch/:id/check — manual check ─────────────────────────────────
+    //
+    // Query params:
+    //   ?diff=true  — Return a line-level diff alongside the full content, with
+    //                 token-savings metadata.  Default behaviour (no param) is
+    //                 unchanged — returns the raw WatchDiff object.
+    router.post('/v1/watch/:id/check', async (req, res) => {
+        const accountId = requireAuth(req, res);
+        if (!accountId)
+            return;
+        const watchId = req.params['id'];
+        const includeDiff = req.query['diff'] === 'true';
+        try {
+            const entry = await manager.get(watchId);
+            if (!entry) {
+                res.status(404).json({
+                    success: false,
+                    error: { type: 'not_found', message: 'Watch not found.' },
+                    requestId: req.requestId,
+                });
+                return;
+            }
+            if (entry.accountId !== accountId) {
+                res.status(403).json({ success: false, error: { type: 'forbidden', message: 'Access denied.' }, requestId: req.requestId });
+                return;
+            }
+            const watchDiff = await manager.check(watchId);
+            if (includeDiff) {
+                // Compute line-level diff between previous and current content.
+                const lineDiff = computeLineDiff(watchDiff.previousContent, watchDiff.content);
+                const fullTokens = estimateTokens(watchDiff.content);
+                const diffText = [...lineDiff.added, ...lineDiff.removed].join('\n');
+                const diffTokens = estimateTokens(diffText);
+                const result = {
+                    changed: watchDiff.changed,
+                    content: watchDiff.content,
+                    diffTokens,
+                    fullTokens,
+                };
+                if (lineDiff.changed) {
+                    result.diff = {
+                        added: lineDiff.added,
+                        removed: lineDiff.removed,
+                        summary: lineDiff.summary,
+                        changePercent: lineDiff.changePercent,
+                    };
+                }
+                res.json({ ok: true, diff: result });
+            }
+            else {
+                res.json({ ok: true, diff: watchDiff });
+            }
+        }
+        catch (err) {
+            console.error('[watch] manual check error:', err);
+            res.status(500).json({
+                success: false,
+                error: {
+                    type: 'check_failed',
+                    message: err instanceof Error ? err.message : 'Check failed.',
+                    docs: 'https://webpeel.dev/docs/errors#check_failed',
+                },
+                requestId: req.requestId,
+            });
+        }
+    });
+    // ─── PATCH /v1/watch/:id — update a watch ───────────────────────────────────
+    router.patch('/v1/watch/:id', async (req, res) => {
+        const accountId = requireAuth(req, res);
+        if (!accountId)
+            return;
+        const watchId = req.params['id'];
+        const { status, webhookUrl, checkIntervalMinutes, intervalMinutes: patchIntervalMinutesAlias, interval: patchInterval, selector } = req.body;
+        // Accept interval aliases
+        const resolvedPatchInterval = checkIntervalMinutes ?? patchIntervalMinutesAlias ?? patchInterval;
+        try {
+            const existing = await manager.get(watchId);
+            if (!existing) {
+                res.status(404).json({
+                    success: false,
+                    error: { type: 'not_found', message: 'Watch not found.' },
+                    requestId: req.requestId,
+                });
+                return;
+            }
+            if (existing.accountId !== accountId) {
+                res.status(403).json({ success: false, error: { type: 'forbidden', message: 'Access denied.' }, requestId: req.requestId });
+                return;
+            }
+            // Handle pause/resume as a convenience.
+            if (status === 'paused') {
+                await manager.pause(watchId);
+            }
+            else if (status === 'active') {
+                await manager.resume(watchId);
+            }
+            const updates = {};
+            if (webhookUrl !== undefined) {
+                updates.webhookUrl = typeof webhookUrl === 'string' ? webhookUrl : undefined;
+            }
+            if (resolvedPatchInterval !== undefined) {
+                const n = Number(resolvedPatchInterval);
+                if (!Number.isFinite(n) || n < 1 || n > 44640) {
+                    res.status(400).json({
+                        success: false,
+                        error: { type: 'invalid_request', message: '"checkIntervalMinutes" must be between 1 and 44640.' },
+                        requestId: req.requestId,
+                    });
+                    return;
+                }
+                updates.checkIntervalMinutes = n;
+            }
+            if (selector !== undefined) {
+                updates.selector = typeof selector === 'string' ? selector : undefined;
+            }
+            const updated = await manager.update(watchId, updates);
+            res.json({ ok: true, watch: updated ?? existing });
+        }
+        catch (err) {
+            console.error('[watch] update error:', err);
+            res.status(500).json({
+                success: false,
+                error: { type: 'internal_error', message: 'Failed to update watch.' },
+                requestId: req.requestId,
+            });
+        }
+    });
+    // ─── DELETE /v1/watch/:id — delete a watch ───────────────────────────────────
+    router.delete('/v1/watch/:id', async (req, res) => {
+        const accountId = requireAuth(req, res);
+        if (!accountId)
+            return;
+        const watchId = req.params['id'];
+        try {
+            const existing = await manager.get(watchId);
+            if (!existing) {
+                res.status(404).json({
+                    success: false,
+                    error: { type: 'not_found', message: 'Watch not found.' },
+                    requestId: req.requestId,
+                });
+                return;
+            }
+            if (existing.accountId !== accountId) {
+                res.status(403).json({ success: false, error: { type: 'forbidden', message: 'Access denied.' }, requestId: req.requestId });
+                return;
+            }
+            await manager.delete(watchId);
+            res.json({ ok: true, deleted: watchId });
+        }
+        catch (err) {
+            console.error('[watch] delete error:', err);
+            res.status(500).json({
+                success: false,
+                error: { type: 'internal_error', message: 'Failed to delete watch.' },
+                requestId: req.requestId,
+            });
+        }
+    });
+    return router;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Webhook delivery with HMAC-SHA256 signing
+ * // AUTH: Not a route handler — this is an outbound utility function (HMAC-signed payloads)
+ *
+ * Sends webhook notifications for job events with retry logic
+ */
+import type { WebhookConfig, WebhookDeliveryResult } from '../job-queue.js';
+/**
+ * Validate webhook URL — must be HTTPS, not localhost, not private IPs.
+ * Throws an error if the URL is invalid.
+ */
+export declare function validateWebhookUrl(url: string): void;
+/**
+ * Normalize webhook input — accept either a URL string or a WebhookConfig object.
+ * When a string URL is passed, defaults to subscribing to all events.
+ */
+export declare function normalizeWebhook(webhook: string | WebhookConfig, defaultEvents?: WebhookConfig['events']): WebhookConfig;
+/**
+ * Send a webhook notification
+ *
+ * @param webhook - Webhook configuration or URL string
+ * @param event - Event type (started | page | completed | failed)
+ * @param payload - Event payload
+ * @returns Delivery result with status, or null if the event was skipped
+ */
+export declare function sendWebhook(webhook: string | WebhookConfig, event: string, payload: any): Promise<WebhookDeliveryResult | null>;

package/dist/server/routes/webhooks.js

@@ -0,0 +1,170 @@
+/**
+ * Webhook delivery with HMAC-SHA256 signing
+ * // AUTH: Not a route handler — this is an outbound utility function (HMAC-signed payloads)
+ *
+ * Sends webhook notifications for job events with retry logic
+ */
+import { createHmac } from 'crypto';
+import { createLogger } from '../logger.js';
+const log = createLogger('webhook');
+/** Maximum payload size before truncation (1MB) */
+const MAX_PAYLOAD_BYTES = 1_000_000;
+/**
+ * Validate webhook URL — must be HTTPS, not localhost, not private IPs.
+ * Throws an error if the URL is invalid.
+ */
+export function validateWebhookUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid webhook URL: ${url}`);
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`Webhook URL must use HTTPS (got ${parsed.protocol})`);
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    // Block localhost and loopback
+    if (hostname === 'localhost' ||
+        hostname === '127.0.0.1' ||
+        hostname === '::1' ||
+        hostname === '0.0.0.0') {
+        throw new Error(`Webhook URL must not target localhost or loopback addresses`);
+    }
+    // Block private IP ranges
+    const privateRanges = [
+        /^10\./, // 10.0.0.0/8
+        /^172\.(1[6-9]|2\d|3[01])\./, // 172.16.0.0/12
+        /^192\.168\./, // 192.168.0.0/16
+        /^169\.254\./, // 169.254.0.0/16 (link-local)
+        /^fc[0-9a-f]{2}:/i, // IPv6 unique local
+        /^fe[89ab][0-9a-f]:/i, // IPv6 link-local
+    ];
+    if (privateRanges.some(re => re.test(hostname))) {
+        throw new Error(`Webhook URL must not target private IP ranges`);
+    }
+}
+/**
+ * Normalize webhook input — accept either a URL string or a WebhookConfig object.
+ * When a string URL is passed, defaults to subscribing to all events.
+ */
+export function normalizeWebhook(webhook, defaultEvents = ['started', 'page', 'completed', 'failed']) {
+    if (typeof webhook === 'string') {
+        return {
+            url: webhook,
+            events: defaultEvents,
+        };
+    }
+    // Ensure events array exists (guard against malformed objects)
+    if (!Array.isArray(webhook.events)) {
+        return { ...webhook, events: defaultEvents };
+    }
+    return webhook;
+}
+/**
+ * Send a webhook notification
+ *
+ * @param webhook - Webhook configuration or URL string
+ * @param event - Event type (started | page | completed | failed)
+ * @param payload - Event payload
+ * @returns Delivery result with status, or null if the event was skipped
+ */
+export async function sendWebhook(webhook, event, payload) {
+    const config = normalizeWebhook(webhook);
+    // Check if this event should be sent
+    if (!config.events.includes(event)) {
+        return null;
+    }
+    // Validate URL (HTTPS only, no localhost, no private IPs)
+    try {
+        validateWebhookUrl(config.url);
+    }
+    catch (err) {
+        log.error(`Webhook URL rejected — ${err.message}`);
+        return {
+            url: config.url,
+            delivered: false,
+            error: err.message,
+        };
+    }
+    const webhookPayload = {
+        event,
+        timestamp: new Date().toISOString(),
+        data: {
+            ...payload,
+            ...config.metadata,
+        },
+    };
+    let body = JSON.stringify(webhookPayload);
+    // Size limit: if payload > 1MB, truncate data and include a note
+    if (Buffer.byteLength(body, 'utf8') > MAX_PAYLOAD_BYTES) {
+        const summary = {
+            event,
+            timestamp: webhookPayload.timestamp,
+            data: {
+                ...config.metadata,
+                _truncated: true,
+                _reason: 'Payload exceeded 1MB limit. Use the job ID to fetch full results via the API.',
+                jobId: payload.jobId,
+                total: payload.total,
+                completed: payload.completed,
+                failed: payload.failed,
+            },
+        };
+        body = JSON.stringify(summary);
+        log.warn(`Webhook payload truncated (>1MB) for event "${event}" to ${config.url}`);
+    }
+    // Generate HMAC-SHA256 signature if secret is provided
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': 'WebPeel-Webhook/1.0',
+    };
+    if (config.secret) {
+        const signature = createHmac('sha256', config.secret)
+            .update(body)
+            .digest('hex');
+        headers['X-WebPeel-Signature'] = signature;
+    }
+    // Retry logic: 3 attempts with exponential backoff (1s, 2s, 4s)
+    const maxRetries = 3;
+    let lastError = null;
+    const startTime = Date.now();
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            const response = await fetch(config.url, {
+                method: 'POST',
+                headers,
+                body,
+                signal: AbortSignal.timeout(10000), // 10s timeout
+            });
+            if (response.ok) {
+                const elapsed = Date.now() - startTime;
+                log.info(`Webhook delivered to ${config.url} — status ${response.status} — ${elapsed}ms`);
+                return {
+                    url: config.url,
+                    delivered: true,
+                    deliveredAt: new Date().toISOString(),
+                    statusCode: response.status,
+                };
+            }
+            // Non-2xx response — record for retry
+            lastError = new Error(`Webhook returned ${response.status}`);
+        }
+        catch (error) {
+            lastError = error;
+        }
+        // Exponential backoff before next retry: 1s, 2s, 4s
+        if (attempt < maxRetries - 1) {
+            const delayMs = Math.pow(2, attempt) * 1000;
+            await new Promise(resolve => setTimeout(resolve, delayMs));
+        }
+    }
+    // All retries exhausted
+    log.error(`Webhook delivery failed to ${config.url} after ${maxRetries} attempts — ${lastError?.message}`);
+    return {
+        url: config.url,
+        delivered: false,
+        error: lastError?.message,
+    };
+}

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

@@ -0,0 +1,6 @@
+/**
+ * YouTube transcript endpoint
+ * GET /v1/youtube?url=<youtube_url>&language=en
+ */
+import { Router } from 'express';
+export declare function createYouTubeRouter(): Router;

package/dist/server/routes/youtube.js

@@ -0,0 +1,130 @@
+/**
+ * YouTube transcript endpoint
+ * GET /v1/youtube?url=<youtube_url>&language=en
+ */
+import { Router } from 'express';
+import crypto from 'crypto';
+import { getYouTubeTranscript, parseYouTubeUrl } from '../../core/youtube.js';
+export function createYouTubeRouter() {
+    const router = Router();
+    /**
+     * GET /v1/youtube
+     * Extract transcript and metadata from a YouTube video.
+     *
+     * Query params:
+     *   url      - YouTube video URL (required)
+     *   language - Preferred language code, default "en" (optional)
+     *
+     * Example:
+     *   curl "https://api.webpeel.dev/v1/youtube?url=https://youtu.be/dQw4w9WgXcQ"
+     */
+    router.get('/v1/youtube', async (req, res) => {
+        // AUTH: require authentication (global middleware sets req.auth)
+        const ytAuthId = req.auth?.keyInfo?.accountId || req.user?.userId;
+        if (!ytAuthId) {
+            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, language } = req.query;
+        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/youtube?url=https://youtu.be/VIDEO_ID',
+                    hint: 'Example: curl "https://api.webpeel.dev/v1/youtube?url=https://youtu.be/dQw4w9WgXcQ"',
+                    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',
+                },
+                supported: [
+                    'https://www.youtube.com/watch?v=VIDEO_ID',
+                    'https://youtu.be/VIDEO_ID',
+                    'https://www.youtube.com/embed/VIDEO_ID',
+                    'https://m.youtube.com/watch?v=VIDEO_ID',
+                ],
+                requestId: req.requestId || crypto.randomUUID(),
+            });
+            return;
+        }
+        try {
+            const lang = typeof language === 'string' ? language : 'en';
+            const transcript = await getYouTubeTranscript(url, { language: lang });
+            res.json({
+                success: true,
+                videoId: transcript.videoId,
+                title: transcript.title,
+                channel: transcript.channel,
+                duration: transcript.duration,
+                language: transcript.language,
+                availableLanguages: transcript.availableLanguages,
+                fullText: transcript.fullText,
+                segments: transcript.segments,
+                url: `https://www.youtube.com/watch?v=${videoId}`,
+            });
+        }
+        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.`,
+                        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,
+                        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;
+            }
+            console.error('[youtube route] Error:', error);
+            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/sentry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Optional Sentry integration for the API server.
+ *
+ * Enabled only when SENTRY_DSN is set.
+ * This keeps local/self-hosted setups dependency-light by default.
+ */
+import type { ErrorRequestHandler, RequestHandler } from 'express';
+export interface SentryHooks {
+    enabled: boolean;
+    requestHandler?: RequestHandler;
+    errorHandler?: ErrorRequestHandler;
+}
+export declare function createSentryHooks(): SentryHooks;