webpeel 0.20.2 → 0.20.3

package/dist/server/sentry.js

@@ -0,0 +1,38 @@
+/**
+ * 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 * as Sentry from '@sentry/node';
+function parseSampleRate(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        console.warn(`Ignoring invalid SENTRY_TRACES_SAMPLE_RATE="${value}" (expected 0.0 - 1.0)`);
+        return undefined;
+    }
+    return parsed;
+}
+export function createSentryHooks() {
+    const dsn = process.env.SENTRY_DSN?.trim();
+    if (!dsn) {
+        return { enabled: false };
+    }
+    const environment = process.env.SENTRY_ENVIRONMENT || process.env.NODE_ENV || 'production';
+    const tracesSampleRate = parseSampleRate(process.env.SENTRY_TRACES_SAMPLE_RATE);
+    Sentry.init({
+        dsn,
+        enabled: true,
+        environment,
+        release: process.env.SENTRY_RELEASE,
+        tracesSampleRate,
+    });
+    console.log(`Sentry enabled (environment: ${environment})`);
+    return {
+        enabled: true,
+        requestHandler: Sentry.Handlers.requestHandler(),
+        errorHandler: Sentry.Handlers.errorHandler(),
+    };
+}

package/dist/server/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Server-side type augmentations for Express Request.
+ *
+ * Import this file (or the middleware that uses it) to get the augmented
+ * Express.Request type in scope throughout the server package.
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            /** UUID v4 generated by the requestId middleware. Present on every request. */
+            requestId: string;
+        }
+    }
+}
+export {};

package/dist/server/types.js

@@ -0,0 +1,7 @@
+/**
+ * Server-side type augmentations for Express Request.
+ *
+ * Import this file (or the middleware that uses it) to get the augmented
+ * Express.Request type in scope throughout the server package.
+ */
+export {};

package/dist/server/utils/response.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Response helpers — consistent API envelope formatting.
+ *
+ * errorResponse  — always emits the standard error envelope.
+ * successResponse — emits the wrapped success envelope (use only when the
+ *                   client opts-in via ?envelope=true or
+ *                   Accept: application/json+envelope).
+ */
+import type { Response } from 'express';
+/**
+ * Send a uniform error response.
+ *
+ * Shape:
+ * ```json
+ * {
+ *   "success": false,
+ *   "error": { "type", "message", "hint"?, "docs" },
+ *   "metadata": { "requestId" }
+ * }
+ * ```
+ */
+export declare function errorResponse(res: Response, statusCode: number, type: string, message: string, hint?: string): void;
+/**
+ * Send a success response with the standard data/metadata envelope.
+ *
+ * Shape:
+ * ```json
+ * {
+ *   "success": true,
+ *   "data": { ...peelResult },
+ *   "metadata": { "requestId", ...extra }
+ * }
+ * ```
+ */
+export declare function successResponse(res: Response, data: any, extra?: Record<string, any>): void;
+/**
+ * Return true when the incoming request opts in to the success envelope.
+ * Clients signal this via `?envelope=true` or the `Accept` header value
+ * `application/json+envelope`.
+ */
+export declare function wantsEnvelope(req: {
+    query: Record<string, any>;
+    headers: Record<string, any>;
+}): boolean;

package/dist/server/utils/response.js

@@ -0,0 +1,69 @@
+/**
+ * Response helpers — consistent API envelope formatting.
+ *
+ * errorResponse  — always emits the standard error envelope.
+ * successResponse — emits the wrapped success envelope (use only when the
+ *                   client opts-in via ?envelope=true or
+ *                   Accept: application/json+envelope).
+ */
+/**
+ * Send a uniform error response.
+ *
+ * Shape:
+ * ```json
+ * {
+ *   "success": false,
+ *   "error": { "type", "message", "hint"?, "docs" },
+ *   "metadata": { "requestId" }
+ * }
+ * ```
+ */
+export function errorResponse(res, statusCode, type, message, hint) {
+    const requestId = res.req.requestId || 'unknown';
+    res.status(statusCode).json({
+        success: false,
+        error: {
+            type,
+            message,
+            ...(hint ? { hint } : {}),
+            docs: 'https://webpeel.dev/docs/api-reference#errors',
+        },
+        metadata: { requestId },
+    });
+}
+/**
+ * Send a success response with the standard data/metadata envelope.
+ *
+ * Shape:
+ * ```json
+ * {
+ *   "success": true,
+ *   "data": { ...peelResult },
+ *   "metadata": { "requestId", ...extra }
+ * }
+ * ```
+ */
+export function successResponse(res, data, extra) {
+    const requestId = res.req.requestId || 'unknown';
+    res.json({
+        success: true,
+        data,
+        metadata: {
+            requestId,
+            ...(extra ?? {}),
+        },
+    });
+}
+/**
+ * Return true when the incoming request opts in to the success envelope.
+ * Clients signal this via `?envelope=true` or the `Accept` header value
+ * `application/json+envelope`.
+ */
+export function wantsEnvelope(req) {
+    if (req.query['envelope'] === 'true')
+        return true;
+    const accept = req.headers['accept'];
+    if (accept && accept.includes('application/json+envelope'))
+        return true;
+    return false;
+}

package/dist/server/utils/sse.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Server-Sent Events (SSE) utility helpers.
+ */
+import type { Request, Response } from 'express';
+/**
+ * Initialize an SSE response stream.
+ * Must be called before any writes.
+ */
+export declare function initSSE(res: Response): void;
+/**
+ * Send a named SSE event with JSON-serialised data.
+ */
+export declare function sendSSE(res: Response, event: string, data: unknown): void;
+/**
+ * Close an SSE stream.
+ */
+export declare function endSSE(res: Response): void;
+/**
+ * Returns true when the request opts-in to SSE streaming via
+ * `?stream=true` or `Accept: text/event-stream`.
+ */
+export declare function wantsSSE(req: Request): boolean;

package/dist/server/utils/sse.js

@@ -0,0 +1,38 @@
+/**
+ * Server-Sent Events (SSE) utility helpers.
+ */
+/**
+ * Initialize an SSE response stream.
+ * Must be called before any writes.
+ */
+export function initSSE(res) {
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no'); // nginx compatibility
+    res.flushHeaders();
+}
+/**
+ * Send a named SSE event with JSON-serialised data.
+ */
+export function sendSSE(res, event, data) {
+    res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+}
+/**
+ * Close an SSE stream.
+ */
+export function endSSE(res) {
+    res.end();
+}
+/**
+ * Returns true when the request opts-in to SSE streaming via
+ * `?stream=true` or `Accept: text/event-stream`.
+ */
+export function wantsSSE(req) {
+    if (req.query['stream'] === 'true')
+        return true;
+    const accept = req.headers['accept'];
+    if (accept && accept.includes('text/event-stream'))
+        return true;
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webpeel",
-  "version": "0.20.2",
+  "version": "0.20.3",
   "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",
@@ -39,6 +39,7 @@
     "dist/core",
     "dist/integrations",
     "dist/mcp",
+    "dist/server",
     "dist/cli/",
     "README.md",
     "LICENSE",