@miketromba/screenshot-service 0.1.0

package/README.md

@@ -0,0 +1,316 @@
+# Screenshot Service
+
+A high-performance screenshot service that generates web page screenshots on-demand using Puppeteer. Distributed via NPM for easy integration into your projects.
+
+[![npm](https://img.shields.io/npm/v/@miketromba/screenshot-service?style=flat)](https://www.npmjs.com/package/@miketromba/screenshot-service)
+[![Bun](https://img.shields.io/badge/Bun-000000?style=flat&logo=bun&logoColor=white)](https://bun.sh/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Vercel](https://img.shields.io/badge/Vercel-000000?style=flat&logo=vercel&logoColor=white)](https://vercel.com/)
+
+## Quick Start
+
+### Development (Local Server)
+
+Run the screenshot service locally with a single command (requires [Bun](https://bun.sh)):
+
+```bash
+# Start the server on port 3000
+npx @miketromba/screenshot-service
+
+# Or with options
+npx @miketromba/screenshot-service --port 3001
+
+# With authentication
+AUTH_TOKEN=secret npx @miketromba/screenshot-service
+```
+
+### Production (Vercel)
+
+Add the screenshot service to your existing Vercel/Next.js project:
+
+```bash
+npm install @miketromba/screenshot-service
+```
+
+**Next.js App Router** (`app/api/screenshot/route.ts`):
+```ts
+export { GET } from '@miketromba/screenshot-service/vercel'
+```
+
+**Vercel API Routes** (`api/screenshot.ts`):
+```ts
+export { GET } from '@miketromba/screenshot-service/vercel'
+```
+
+Add function configuration to your `vercel.json`:
+```json
+{
+  "functions": {
+    "api/screenshot.ts": {
+      "maxDuration": 60,
+      "memory": 1024
+    }
+  }
+}
+```
+
+Set environment variables in Vercel dashboard:
+- `AUTH_TOKEN` - Bearer token for authentication (optional)
+- `HOST_WHITELIST` - Comma-separated allowed hostnames (optional)
+
+## Overview
+
+The Screenshot Service provides an API for generating screenshots of web pages using Puppeteer. It supports two deployment modes:
+
+- **Development**: Local Bun server with puppeteer-cluster for concurrent processing (up to 10 simultaneous screenshots)
+- **Production**: Vercel serverless function using puppeteer-core + @sparticuz/chromium (scales horizontally)
+
+## Features
+
+- On-demand screenshot generation
+- Configurable screenshot dimensions
+- Support for multiple image formats (PNG, WEBP, JPEG)
+- Adjustable image quality
+- Full page or viewport screenshots
+- Concurrent request handling (up to 10 simultaneous screenshots)
+- Bearer token authentication for secure access
+- Hostname whitelist validation for enhanced security
+
+## Use Cases
+
+### Internal Application Screenshots
+The service is particularly useful for capturing screenshots of authenticated internal applications. For example, in a design tool where previews are protected behind authentication:
+
+1. Set up your internal application with authentication
+2. Configure the screenshot service with the same authentication token
+3. Use the service to capture authenticated views of your application
+
+Example scenario:
+```bash
+# Your design tool has protected preview URLs like:
+# https://design-tool.internal/preview/design-123
+# These URLs require authentication to access
+
+# Configure the screenshot service with your auth token
+export AUTH_TOKEN=your-internal-auth-token
+
+# The service will now be able to access and capture these protected previews
+curl -H "Authorization: Bearer $AUTH_TOKEN" \
+  "http://localhost:3000/screenshot?url=https://design-tool.internal/preview/design-123" \
+  > design-preview.png
+```
+
+This setup ensures that:
+- Your internal application remains secure
+- Only the screenshot service can access protected previews
+- You can programmatically capture authenticated views of your application
+
+## Authentication
+
+Authentication is optional and can be enabled by setting the `AUTH_TOKEN` environment variable. When enabled, all endpoints except the health check (`GET /`) require authentication using a Bearer token. The token must be included in the `Authorization` header of each request.
+
+Format: `Authorization: Bearer <your-token>`
+
+If authentication is enabled and the token is missing or invalid, the server will respond with:
+- `401 Unauthorized`: Missing or invalid Authorization header format
+- `403 Forbidden`: Invalid token
+
+Note: When AUTH_TOKEN is set, it is also used to authenticate requests to the target websites when taking screenshots. This means the service will forward your authentication token to the websites you're capturing.
+
+## API Endpoints
+
+The API is identical for both deployment options, with different base paths:
+
+| Deployment | Health Check | Screenshot |
+|------------|--------------|------------|
+| Docker/Bun | `GET /` | `GET /screenshot` |
+| Vercel | `GET /api` | `GET /api/screenshot` |
+
+### Health Check
+
+Returns server status. This endpoint does not require authentication.
+
+**Response:**
+```json
+{ "online": true }
+```
+
+### Take Screenshot
+
+**Authentication Required**: Yes (Bearer token)
+
+**Query Parameters:**
+
+- `url` (required): The URL to screenshot (must be a valid URL)
+- `fullPage` (optional): Whether to capture the full page or just the viewport
+  - Default: false
+  - Values: "true" or "false"
+- `quality` (optional): Image quality (for JPEG and WEBP only)
+  - Default: 100
+  - Range: 1-100
+- `type` (optional): Output image format
+  - Default: "png"
+  - Values: "png", "webp", "jpeg"
+- `width` (optional): Viewport width in pixels
+  - Default: 1440
+  - Range: 1-1920
+- `height` (optional): Viewport height in pixels
+  - Default: 900
+  - Range: 1-10000
+
+#### Page Loading Options
+
+The service provides several options to control when the screenshot is taken, ensuring content is fully loaded:
+
+- `waitUntil` (optional): When to consider page navigation successful
+  - Default: "networkidle2"
+  - Values:
+    - `"load"` - Wait for the `load` event (all resources loaded)
+    - `"domcontentloaded"` - Wait for the `DOMContentLoaded` event (DOM is ready, but stylesheets/images may still be loading)
+    - `"networkidle0"` - Wait until there are no network connections for at least 500ms (strictest)
+    - `"networkidle2"` - Wait until there are no more than 2 network connections for at least 500ms (default, good balance)
+- `waitForSelector` (optional): CSS selector to wait for before taking the screenshot
+  - Example: ".main-content" or "#hero-image"
+  - Timeout: 30 seconds
+  - Use this when you need to ensure a specific element has rendered
+- `delay` (optional): Additional delay in milliseconds after page load before taking the screenshot
+  - Range: 0-30000 (0-30 seconds)
+  - Use this for animations, transitions, or slow-rendering content
+
+**Note:** The service always waits for web fonts to load (`document.fonts.ready`) before taking screenshots to ensure text renders correctly.
+
+**Response:**
+- Content-Type: image/[type]
+- Body: Binary image data
+
+**Error Responses:**
+- `403 Forbidden`: If the URL's hostname is not in the allowed whitelist
+
+## Environment Variables
+
+- `PORT`: Server port number (default: 3000)
+- `NODE_ENV`: Environment setting ("development" enables request logging)
+- `AUTH_TOKEN`: Optional. When set, used for two purposes:
+  1. The bearer token that clients must provide to access protected endpoints
+  2. The authorization token forwarded to target websites when taking screenshots
+- `MAX_CONCURRENCY`: Maximum number of concurrent screenshot operations (default: 10)
+- `HOST_WHITELIST`: Comma-separated list of allowed hostnames. If empty, all hostnames are allowed
+
+## Technical Details
+
+### Local Development Server
+- Built with [Hono](https://hono.dev/) web framework
+- Uses [Puppeteer](https://pptr.dev/) for browser automation
+- Implements [puppeteer-cluster](https://github.com/thomasdondorf/puppeteer-cluster) for concurrent processing
+- Input validation using [Zod](https://zod.dev/)
+- Requires [Bun](https://bun.sh) runtime
+
+### Vercel Serverless
+- Serverless function with [puppeteer-core](https://pptr.dev/)
+- Uses [@sparticuz/chromium](https://github.com/Sparticuz/chromium) for serverless-optimized Chromium
+- Shared validation and screenshot logic
+
+## Docker Usage (Alternative)
+
+For production deployments where you need full control, you can also run this as a Docker container.
+
+### Building the Image
+
+You can build the Docker image using either the bun script or directly with Docker:
+
+```bash
+# Using bun script (builds with tag: screenshot-service)
+bun run docker:build
+
+# Or directly with Docker
+docker build -t screenshot-service .
+```
+
+### Running the Container
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -e AUTH_TOKEN=your-secret-token \
+  -e HOST_WHITELIST=example.com,test.com \
+  -e MAX_CONCURRENCY=10 \
+  screenshot-service
+```
+
+### Environment Variables
+
+All environment variables can be passed to the container using the `-e` flag or by using a `.env` file:
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  --env-file .env \
+  screenshot-service
+```
+
+### Accessing Local Services from Docker
+
+When running the screenshot service in Docker and you need to capture screenshots of services running on your local machine, you need to:
+
+1. Add the `--add-host=host.docker.internal:host-gateway` flag when running the container
+2. Use `host.docker.internal` instead of `localhost` in your URLs
+
+This is because `localhost` inside the container refers to the container itself, not your host machine.
+
+Example:
+```bash
+# ❌ Instead of:
+curl -H "Authorization: Bearer $AUTH_TOKEN" "http://localhost:3000/screenshot?url=http://localhost:3001/my-app"
+
+# ✅ Use:
+curl -H "Authorization: Bearer $AUTH_TOKEN" "http://localhost:3000/screenshot?url=http://host.docker.internal:3001/my-app"
+```
+
+Note: The `--add-host` flag is required for `host.docker.internal` to work. Make sure to include it in your `docker run` command.
+
+## Vercel Production Notes
+
+### Limitations
+
+- **Cold starts**: First request may take 5-10 seconds (browser launch)
+- **Timeout**: 60 seconds max (configurable up to 300s on Pro plan)
+- **No custom fonts**: Unlike local development, Vercel functions don't include custom fonts. Screenshots may render with different fonts.
+- **Scaling**: Vercel handles scaling automatically via parallel function invocations
+
+### Local Dev vs Vercel
+
+| Feature | Local (npx) | Vercel |
+|---------|-------------|--------|
+| Concurrency | puppeteer-cluster (configurable) | Horizontal scaling |
+| Cold start | None (always running) | 5-10 seconds |
+| Custom fonts | System fonts available | Limited |
+| Max timeout | Unlimited | 60-300 seconds |
+| Cost | Free (local) | Pay per invocation |
+
+## Example Usage
+
+```bash
+# Set your auth token
+export AUTH_TOKEN=your-secret-token
+
+# Basic screenshot
+curl -H "Authorization: Bearer $AUTH_TOKEN" "http://localhost:3006/screenshot?url=https://example.com" > screenshot.png
+
+# Full page JPEG screenshot with 80% quality
+curl -H "Authorization: Bearer $AUTH_TOKEN" "http://localhost:3006/screenshot?url=https://example.com&fullPage=true&type=jpeg&quality=80" > screenshot.jpg
+
+# Custom dimension WEBP screenshot
+curl -H "Authorization: Bearer $AUTH_TOKEN" "http://localhost:3006/screenshot?url=https://example.com&width=1024&height=768&type=webp" > screenshot.webp
+
+# Wait for all network activity to finish (strictest loading strategy)
+curl -H "Authorization: Bearer $AUTH_TOKEN" "http://localhost:3006/screenshot?url=https://example.com&waitUntil=networkidle0" > screenshot.png
+
+# Wait for a specific element to appear before taking screenshot
+curl -H "Authorization: Bearer $AUTH_TOKEN" "http://localhost:3006/screenshot?url=https://example.com&waitForSelector=.main-content" > screenshot.png
+
+# Add a 2-second delay for animations/transitions to complete
+curl -H "Authorization: Bearer $AUTH_TOKEN" "http://localhost:3006/screenshot?url=https://example.com&delay=2000" > screenshot.png
+
+# Combine multiple loading options for complex pages
+curl -H "Authorization: Bearer $AUTH_TOKEN" "http://localhost:3006/screenshot?url=https://example.com&waitUntil=networkidle0&waitForSelector=#hero-image&delay=1000" > screenshot.png
+```

package/bin/cli.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+
+const args = process.argv.slice(2)
+
+// Parse arguments
+let port: number | undefined
+let showHelp = false
+
+for (let i = 0; i < args.length; i++) {
+	const arg = args[i]
+	if (arg === '--help' || arg === '-h') {
+		showHelp = true
+	} else if (arg === '--port' || arg === '-p') {
+		const portArg = args[++i]
+		if (portArg) {
+			port = parseInt(portArg, 10)
+			if (isNaN(port)) {
+				console.error(`Invalid port: ${portArg}`)
+				process.exit(1)
+			}
+		}
+	} else if (arg.startsWith('--port=')) {
+		port = parseInt(arg.split('=')[1], 10)
+		if (isNaN(port)) {
+			console.error(`Invalid port: ${arg.split('=')[1]}`)
+			process.exit(1)
+		}
+	}
+}
+
+if (showHelp) {
+	console.log(`
+@miketromba/screenshot-service - A screenshot service powered by Puppeteer
+
+Usage:
+  npx @miketromba/screenshot-service [options]
+
+Options:
+  -p, --port <port>  Port to run the server on (default: 3000, or PORT env var)
+  -h, --help         Show this help message
+
+Environment Variables:
+  PORT            Server port (default: 3000)
+  AUTH_TOKEN      Bearer token for authentication (optional)
+  HOST_WHITELIST  Comma-separated list of allowed hostnames (optional)
+  MAX_CONCURRENCY Maximum concurrent screenshots (default: 10)
+  NODE_ENV        Set to "development" for verbose logging
+
+Examples:
+  # Start with default settings
+  npx @miketromba/screenshot-service
+
+  # Start on a specific port
+  npx @miketromba/screenshot-service --port 3001
+
+  # Start with authentication
+  AUTH_TOKEN=secret npx @miketromba/screenshot-service
+`)
+	process.exit(0)
+}
+
+// Set port in environment if provided via CLI (takes precedence)
+if (port !== undefined) {
+	process.env.PORT = String(port)
+}
+
+// Import and run the server
+import('../src/server.ts')

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@miketromba/screenshot-service",
+    "version": "0.1.0",
+    "type": "module",
+    "bin": {
+        "screenshot-service": "./bin/cli.ts"
+    },
+    "exports": {
+        ".": {
+            "import": "./src/index.ts",
+            "types": "./src/index.ts"
+        },
+        "./vercel": {
+            "import": "./src/vercel.ts",
+            "types": "./src/vercel.ts"
+        }
+    },
+    "files": [
+        "bin",
+        "src"
+    ],
+    "scripts": {
+        "dev": "bun --watch src/server.ts",
+        "start": "bun run src/server.ts",
+        "docker:build": "docker build -t screenshot-service ."
+    },
+    "dependencies": {
+        "@hono/zod-validator": "^0.4.3",
+        "@sparticuz/chromium": "^143.0.4",
+        "hono": "^4.7.4",
+        "puppeteer-core": "^24.36.0",
+        "zod": "^3.24.2"
+    },
+    "optionalDependencies": {
+        "puppeteer": "^24.6.0",
+        "puppeteer-cluster": "^0.24.0"
+    },
+    "devDependencies": {
+        "@types/bun": "latest"
+    },
+    "trustedDependencies": [
+        "puppeteer"
+    ]
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+// Main package exports - shared utilities, types, and schemas
+export {
+	// Schema and types
+	screenshotQuerySchema,
+	type ScreenshotQuery,
+	type ScreenshotOptions,
+	type AuthResult,
+	type Page,
+
+	// Utilities
+	getHostWhitelist,
+	getAuthToken,
+	isUrlHostnameAllowed,
+	queryToScreenshotOptions,
+	validateBearerToken,
+	captureScreenshot,
+
+	// Constants
+	CHROME_ARGS,
+	USER_AGENT,
+	SCREENSHOT_CSS
+} from './shared'

package/src/server.ts

@@ -0,0 +1,120 @@
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import { logger } from 'hono/logger'
+import { Cluster } from 'puppeteer-cluster'
+import puppeteer from 'puppeteer'
+import { zValidator } from '@hono/zod-validator'
+import {
+	screenshotQuerySchema,
+	isUrlHostnameAllowed,
+	queryToScreenshotOptions,
+	validateBearerToken,
+	captureScreenshot,
+	getHostWhitelist,
+	getAuthToken,
+	CHROME_ARGS
+} from './shared'
+
+const MAX_CONCURRENCY = process.env.MAX_CONCURRENCY
+	? parseInt(process.env.MAX_CONCURRENCY)
+	: 10
+const HOST_WHITELIST = getHostWhitelist()
+const AUTH_TOKEN = getAuthToken()
+const PORT = process.env.PORT ? parseInt(process.env.PORT) : 3000
+const DEV_MODE = process.env.NODE_ENV === 'development'
+
+type PuppeteerOptions = Parameters<typeof puppeteer.launch>[0]
+
+let cluster: Cluster<null, Uint8Array>
+
+async function getCluster() {
+	if (!cluster) {
+		cluster = await Cluster.launch({
+			concurrency: Cluster.CONCURRENCY_CONTEXT,
+			maxConcurrency: MAX_CONCURRENCY,
+			puppeteerOptions: {
+				timeout: 300_000, // 5 minutes -- give it very generous timeout since loading browsers all at once on resource-bound VM is slow
+				headless: true,
+				args: CHROME_ARGS
+			} as PuppeteerOptions
+		})
+	}
+	return cluster
+}
+
+async function takeScreenshot(opts: Parameters<typeof captureScreenshot>[1]) {
+	const cluster = await getCluster()
+	return cluster.execute(null, async ({ page }) => {
+		return captureScreenshot(page, opts, AUTH_TOKEN)
+	})
+}
+
+const app = new Hono()
+
+// Add common middleware
+// Only use logger middleware in development environment
+if (DEV_MODE) {
+	app.use('*', logger())
+}
+
+app.use('*', cors())
+
+// Authentication middleware
+const auth = async (c: any, next: any) => {
+	// Skip auth for health check endpoint
+	if (c.req.path === '/') {
+		return next()
+	}
+	const authResult = validateBearerToken(c.req.header('Authorization'), AUTH_TOKEN!)
+	if (authResult.valid === false) {
+		return c.json({ error: authResult.error }, authResult.status)
+	}
+	return next()
+}
+
+if (AUTH_TOKEN) {
+	app.use('*', auth)
+}
+
+app.get('/', c => {
+	return c.json({ online: true })
+})
+
+app.get(
+	'/screenshot',
+	zValidator('query', screenshotQuerySchema),
+	async c => {
+		const query = c.req.valid('query')
+
+		// Prod logging
+		if (!DEV_MODE) console.log('CAPTURE:', query.url)
+
+		// Check if the URL's hostname is allowed
+		if (!isUrlHostnameAllowed(query.url, HOST_WHITELIST)) {
+			return c.json(
+				{
+					error: `Hostname not allowed. Must be one of: ${HOST_WHITELIST.join(
+						', '
+					)}`
+				},
+				403
+			)
+		}
+
+		const screenshot = await takeScreenshot(queryToScreenshotOptions(query))
+
+		return new Response(Buffer.from(screenshot), {
+			headers: {
+				'Content-Type': `image/${query.type}`
+			}
+		})
+	}
+)
+
+Bun.serve({
+	port: PORT,
+	fetch: app.fetch,
+	idleTimeout: 255 // max value, 5 mins
+})
+
+console.log(`Screenshot service is online on port ${PORT}`)

package/src/shared.ts

@@ -0,0 +1,182 @@
+import { z } from 'zod'
+import type { Page as PuppeteerPage } from 'puppeteer'
+import type { Page as PuppeteerCorePage } from 'puppeteer-core'
+
+// Environment variables
+export const getHostWhitelist = () =>
+	process.env.HOST_WHITELIST?.split(',').map(h => h.trim()) || []
+
+export const getAuthToken = () => process.env.AUTH_TOKEN
+
+// Query parameter schema for screenshot endpoint
+export const screenshotQuerySchema = z.object({
+	url: z.string().url(),
+	fullPage: z.enum(['true', 'false']).optional().default('false'),
+	quality: z.coerce.number().min(1).max(100).optional().default(100),
+	type: z.enum(['png', 'webp', 'jpeg']).optional().default('png'),
+	width: z.coerce.number().min(1).max(1920).optional().default(1440),
+	height: z.coerce.number().min(1).max(10000).optional().default(900),
+	waitUntil: z
+		.enum(['load', 'domcontentloaded', 'networkidle0', 'networkidle2'])
+		.optional()
+		.default('networkidle2'),
+	waitForSelector: z.string().optional(),
+	delay: z.coerce.number().min(0).max(30000).optional()
+})
+
+export type ScreenshotQuery = z.infer<typeof screenshotQuerySchema>
+
+// Screenshot options type used by both implementations
+export type ScreenshotOptions = {
+	url: string
+	fullPage: boolean
+	quality: number
+	type: 'png' | 'webp' | 'jpeg'
+	dimensions: { width: number; height: number }
+	waitUntil: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
+	waitForSelector?: string
+	delay?: number
+}
+
+// Check if URL hostname is in the whitelist
+export function isUrlHostnameAllowed(
+	url: string,
+	whitelist: string[]
+): boolean {
+	try {
+		const hostname = new URL(url).hostname
+		if (!whitelist.length) {
+			return true
+		}
+		return whitelist.some(
+			allowed => hostname === allowed || hostname.endsWith(`.${allowed}`)
+		)
+	} catch {
+		return false
+	}
+}
+
+// Convert validated query params to screenshot options
+export function queryToScreenshotOptions(
+	query: ScreenshotQuery
+): ScreenshotOptions {
+	return {
+		url: query.url,
+		fullPage: query.fullPage === 'true',
+		quality: query.quality,
+		type: query.type,
+		dimensions: {
+			width: query.width,
+			height: query.height
+		},
+		waitUntil: query.waitUntil,
+		waitForSelector: query.waitForSelector,
+		delay: query.delay
+	}
+}
+
+// Common Chrome launch arguments for consistent rendering
+export const CHROME_ARGS = [
+	'--no-sandbox',
+	'--disable-setuid-sandbox',
+	'--font-render-hinting=none',
+	'--disable-font-subpixel-positioning',
+	'--force-color-profile=srgb'
+]
+
+// User agent string
+export const USER_AGENT =
+	'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36'
+
+// CSS for consistent font rendering
+export const SCREENSHOT_CSS = `
+	* {
+		-webkit-print-color-adjust: exact !important;
+		text-rendering: geometricprecision !important;
+		-webkit-font-smoothing: antialiased !important;
+	}
+`
+
+// Page type from either puppeteer or puppeteer-core (both have same runtime API)
+export type Page = PuppeteerPage | PuppeteerCorePage
+
+// Capture screenshot using a page instance (shared logic for both implementations)
+// Uses PuppeteerCorePage internally since both packages have identical runtime APIs
+export async function captureScreenshot(
+	page: Page,
+	opts: ScreenshotOptions,
+	authToken?: string
+): Promise<Uint8Array> {
+	// Cast to PuppeteerCorePage to avoid union type signature conflicts
+	// Both puppeteer and puppeteer-core have identical APIs at runtime
+	const p = page as PuppeteerCorePage
+
+	// Use string format for compatibility with both puppeteer and puppeteer-core
+	await p.setUserAgent(USER_AGENT)
+
+	// Set authorization header for all requests
+	if (authToken) {
+		await p.setExtraHTTPHeaders({
+			Authorization: `Bearer ${authToken}`
+		})
+	}
+
+	await p.setViewport({
+		width: opts.dimensions.width,
+		height: opts.dimensions.height
+	})
+
+	await p.goto(opts.url, {
+		waitUntil: opts.waitUntil
+	})
+
+	// Set custom CSS to ensure consistent font rendering
+	await p.addStyleTag({
+		content: SCREENSHOT_CSS
+	})
+
+	// Wait for specific selector if provided
+	if (opts.waitForSelector) {
+		await p.waitForSelector(opts.waitForSelector, { timeout: 30000 })
+	}
+
+	// Wait for fonts to load
+	await p.evaluateHandle('document.fonts.ready')
+
+	// Additional delay if specified
+	if (opts.delay) {
+		await new Promise(resolve => setTimeout(resolve, opts.delay))
+	}
+
+	const screenshot = await p.screenshot({
+		type: opts.type,
+		...(opts.type !== 'png' ? { quality: opts.quality } : {}),
+		fullPage: opts.fullPage
+	})
+
+	return screenshot as Uint8Array
+}
+
+// Auth validation result type
+export type AuthResult =
+	| { valid: true }
+	| { valid: false; error: string; status: 401 | 403 }
+
+// Validate Bearer token from Authorization header
+export function validateBearerToken(
+	authHeader: string | null | undefined,
+	expectedToken: string
+): AuthResult {
+	if (!authHeader || !authHeader.startsWith('Bearer ')) {
+		return {
+			valid: false,
+			error: 'Authorization header missing or invalid format',
+			status: 401
+		}
+	}
+	const token = authHeader.split(' ')[1]
+	if (token !== expectedToken) {
+		return { valid: false, error: 'Invalid token', status: 403 }
+	}
+	return { valid: true }
+}

package/src/vercel.ts

@@ -0,0 +1,127 @@
+/**
+ * Vercel serverless function handler for screenshot service.
+ *
+ * Usage in your Vercel project:
+ *
+ * ```ts
+ * // api/screenshot.ts (or app/api/screenshot/route.ts for Next.js App Router)
+ * export { GET } from '@miketromba/screenshot-service/vercel'
+ * ```
+ */
+
+import type { Browser, Page } from 'puppeteer-core'
+import puppeteer from 'puppeteer-core'
+import chromium from '@sparticuz/chromium'
+import {
+	screenshotQuerySchema,
+	isUrlHostnameAllowed,
+	queryToScreenshotOptions,
+	validateBearerToken,
+	captureScreenshot,
+	getHostWhitelist,
+	getAuthToken,
+	CHROME_ARGS
+} from './shared'
+
+// Cache browser instance for warm invocations
+let browser: Browser | null = null
+
+async function getBrowser(): Promise<Browser> {
+	if (browser) {
+		return browser
+	}
+
+	browser = await puppeteer.launch({
+		args: [...chromium.args, ...CHROME_ARGS],
+		defaultViewport: null,
+		executablePath: await chromium.executablePath(),
+		headless: true
+	})
+
+	return browser
+}
+
+async function takeScreenshot(
+	opts: Parameters<typeof captureScreenshot>[1],
+	authToken?: string
+): Promise<Uint8Array> {
+	const browser = await getBrowser()
+	const page: Page = await browser.newPage()
+
+	try {
+		return await captureScreenshot(page, opts, authToken)
+	} finally {
+		await page.close()
+	}
+}
+
+/**
+ * GET handler for Vercel serverless functions.
+ * Re-export this from your API route.
+ */
+export async function GET(request: Request): Promise<Response> {
+	const url = new URL(request.url)
+	const params = Object.fromEntries(url.searchParams.entries())
+
+	// Validate query parameters
+	const result = screenshotQuerySchema.safeParse(params)
+	if (!result.success) {
+		return Response.json(
+			{
+				error: 'Invalid query parameters',
+				details: result.error.flatten()
+			},
+			{ status: 400 }
+		)
+	}
+
+	const query = result.data
+	const authToken = getAuthToken()
+	const hostWhitelist = getHostWhitelist()
+
+	// Check authentication if AUTH_TOKEN is set
+	if (authToken) {
+		const authResult = validateBearerToken(
+			request.headers.get('Authorization'),
+			authToken
+		)
+		if (authResult.valid === false) {
+			return Response.json(
+				{ error: authResult.error },
+				{ status: authResult.status }
+			)
+		}
+	}
+
+	// Check if the URL's hostname is allowed
+	if (!isUrlHostnameAllowed(query.url, hostWhitelist)) {
+		return Response.json(
+			{
+				error: `Hostname not allowed. Must be one of: ${hostWhitelist.join(', ')}`
+			},
+			{ status: 403 }
+		)
+	}
+
+	console.log('CAPTURE:', query.url)
+
+	try {
+		const opts = queryToScreenshotOptions(query)
+		const screenshot = await takeScreenshot(opts, authToken)
+
+		return new Response(Buffer.from(screenshot), {
+			headers: {
+				'Content-Type': `image/${query.type}`
+			}
+		})
+	} catch (error) {
+		console.error('Screenshot error:', error)
+		return Response.json(
+			{
+				error: 'Failed to capture screenshot',
+				message: error instanceof Error ? error.message : 'Unknown error'
+			},
+			{ status: 500 }
+		)
+	}
+}