@miketromba/screenshot-service 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { screenshotQuerySchema, type ScreenshotQuery, type ScreenshotOptions, type AuthResult, type Page, getHostWhitelist, getAuthToken, isUrlHostnameAllowed, queryToScreenshotOptions, validateBearerToken, captureScreenshot, CHROME_ARGS, USER_AGENT, SCREENSHOT_CSS } from './shared';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,IAAI,EAGT,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EAGjB,WAAW,EACX,UAAU,EACV,cAAc,EACd,MAAM,UAAU,CAAA"}

package/dist/index.js

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

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":""}

package/dist/server.js

@@ -0,0 +1,84 @@
+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 SCREENSHOT_HOST_WHITELIST = getHostWhitelist();
+const SCREENSHOT_AUTH_TOKEN = getAuthToken();
+const PORT = process.env.PORT ? parseInt(process.env.PORT) : 3000;
+const DEV_MODE = process.env.NODE_ENV === 'development';
+let cluster;
+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
+            }
+        });
+    }
+    return cluster;
+}
+async function takeScreenshot(opts) {
+    const cluster = await getCluster();
+    return cluster.execute(null, async ({ page }) => {
+        return captureScreenshot(page, opts, SCREENSHOT_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, next) => {
+    // Skip auth for health check endpoint
+    if (c.req.path === '/') {
+        return next();
+    }
+    const authResult = validateBearerToken(c.req.header('Authorization'), SCREENSHOT_AUTH_TOKEN);
+    if (authResult.valid === false) {
+        return c.json({ error: authResult.error }, authResult.status);
+    }
+    return next();
+};
+if (SCREENSHOT_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, SCREENSHOT_HOST_WHITELIST)) {
+        return c.json({
+            error: `Hostname not allowed. Must be one of: ${SCREENSHOT_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/dist/shared.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import type { Page as PuppeteerPage } from 'puppeteer';
+import type { Page as PuppeteerCorePage } from 'puppeteer-core';
+export declare const getHostWhitelist: () => string[];
+export declare const getAuthToken: () => string | undefined;
+export declare const screenshotQuerySchema: z.ZodObject<{
+    url: z.ZodString;
+    fullPage: z.ZodDefault<z.ZodOptional<z.ZodEnum<["true", "false"]>>>;
+    quality: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    type: z.ZodDefault<z.ZodOptional<z.ZodEnum<["png", "webp", "jpeg"]>>>;
+    width: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    height: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    waitUntil: z.ZodDefault<z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle0", "networkidle2"]>>>;
+    waitForSelector: z.ZodOptional<z.ZodString>;
+    delay: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    fullPage: "true" | "false";
+    quality: number;
+    type: "png" | "webp" | "jpeg";
+    width: number;
+    height: number;
+    waitUntil: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+    waitForSelector?: string | undefined;
+    delay?: number | undefined;
+}, {
+    url: string;
+    fullPage?: "true" | "false" | undefined;
+    quality?: number | undefined;
+    type?: "png" | "webp" | "jpeg" | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2" | undefined;
+    waitForSelector?: string | undefined;
+    delay?: number | undefined;
+}>;
+export type ScreenshotQuery = z.infer<typeof screenshotQuerySchema>;
+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;
+};
+export declare function isUrlHostnameAllowed(url: string, whitelist: string[]): boolean;
+export declare function queryToScreenshotOptions(query: ScreenshotQuery): ScreenshotOptions;
+export declare const CHROME_ARGS: string[];
+export declare 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";
+export declare const SCREENSHOT_CSS = "\n\t* {\n\t\t-webkit-print-color-adjust: exact !important;\n\t\ttext-rendering: geometricprecision !important;\n\t\t-webkit-font-smoothing: antialiased !important;\n\t}\n";
+export type Page = PuppeteerPage | PuppeteerCorePage;
+export declare function captureScreenshot(page: Page, opts: ScreenshotOptions, authToken?: string): Promise<Uint8Array>;
+export type AuthResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+    status: 401 | 403;
+};
+export declare function validateBearerToken(authHeader: string | null | undefined, expectedToken: string): AuthResult;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,IAAI,IAAI,aAAa,EAAE,MAAM,WAAW,CAAA;AACtD,OAAO,KAAK,EAAE,IAAI,IAAI,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAG/D,eAAO,MAAM,gBAAgB,gBAC8C,CAAA;AAE3E,eAAO,MAAM,YAAY,0BAA0C,CAAA;AAGnE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAahC,CAAA;AAEF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAGnE,MAAM,MAAM,iBAAiB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;IAC7B,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IAC7C,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,cAAc,GAAG,cAAc,CAAA;IACxE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAGD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EAAE,GACjB,OAAO,CAYT;AAGD,wBAAgB,wBAAwB,CACvC,KAAK,EAAE,eAAe,GACpB,iBAAiB,CAcnB;AAGD,eAAO,MAAM,WAAW,UAMvB,CAAA;AAGD,eAAO,MAAM,UAAU,0HACiG,CAAA;AAGxH,eAAO,MAAM,cAAc,+KAM1B,CAAA;AAGD,MAAM,MAAM,IAAI,GAAG,aAAa,GAAG,iBAAiB,CAAA;AAIpD,wBAAsB,iBAAiB,CACtC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,iBAAiB,EACvB,SAAS,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAiDrB;AAGD,MAAM,MAAM,UAAU,GACnB;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAA;CAAE,CAAA;AAGrD,wBAAgB,mBAAmB,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,aAAa,EAAE,MAAM,GACnB,UAAU,CAaZ"}

package/dist/shared.js

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+// Environment variables
+export const getHostWhitelist = () => process.env.SCREENSHOT_HOST_WHITELIST?.split(',').map(h => h.trim()) || [];
+export const getAuthToken = () => process.env.SCREENSHOT_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()
+});
+// Check if URL hostname is in the whitelist
+export function isUrlHostnameAllowed(url, whitelist) {
+    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) {
+    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;
+	}
+`;
+// 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, opts, authToken) {
+    // Cast to PuppeteerCorePage to avoid union type signature conflicts
+    // Both puppeteer and puppeteer-core have identical APIs at runtime
+    const p = page;
+    // 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;
+}
+// Validate Bearer token from Authorization header
+export function validateBearerToken(authHeader, expectedToken) {
+    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/dist/vercel.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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'
+ * ```
+ */
+/**
+ * GET handler for Vercel serverless functions.
+ * Re-export this from your API route.
+ */
+export declare function GET(request: Request): Promise<Response>;
+//# sourceMappingURL=vercel.d.ts.map

package/dist/vercel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel.d.ts","sourceRoot":"","sources":["../src/vercel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgDH;;;GAGG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkE7D"}

package/dist/vercel.js

@@ -0,0 +1,86 @@
+/**
+ * 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 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 = null;
+async function getBrowser() {
+    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, authToken) {
+    const browser = await getBrowser();
+    const 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) {
+    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 SCREENSHOT_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 });
+    }
+}

package/package.json

@@ -1,25 +1,28 @@
 {
     "name": "@miketromba/screenshot-service",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "type": "module",
     "bin": {
         "screenshot-service": "bin/cli.ts"
     },
     "exports": {
         ".": {
-            "import": "./src/index.ts",
-            "types": "./src/index.ts"
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
         },
         "./vercel": {
-            "import": "./src/vercel.ts",
-            "types": "./src/vercel.ts"
+            "import": "./dist/vercel.js",
+            "types": "./dist/vercel.d.ts"
         }
     },
     "files": [
+        "dist",
         "bin",
         "src"
     ],
     "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build",
         "dev": "bun --watch src/server.ts",
         "start": "bun run src/server.ts",
         "docker:build": "docker build -t screenshot-service ."
@@ -36,7 +39,8 @@
         "puppeteer-cluster": "^0.24.0"
     },
     "devDependencies": {
-        "@types/bun": "latest"
+        "@types/bun": "latest",
+        "typescript": "^5.0.0"
     },
     "trustedDependencies": [
         "puppeteer"