@cellaware/utils 8.4.1 → 8.5.0

package/dist/{browser.d.ts → chatwms/pdf.d.ts}

@@ -1,37 +1,3 @@
-import type { Browser } from "playwright-core";
-/**
- * Browserless (hosted) performance & reliability notes
- *
- * 1) Prefer connect-per-request (default)
- *    - We use chromium.connectOverCDP() instead of launching a local browser.
- *    - In serverless, connecting + closing per request is the safest and most cost-predictable option.
- *    - Hosted Browserless usage is typically metered by session/connection time, so leaving connections
- *      open while idle can increase cost.
- *
- * 2) Always isolate work in a fresh BrowserContext per PDF
- *    - Never reuse BrowserContext or Page across requests.
- *    - Context-per-request avoids cookie/storage leaks, cross-request interference, and memory growth.
- *
- * 3) Close deterministically (inner → outer)
- *    - Always close Page, then Context, then Browser (the CDP connection).
- *    - This releases remote resources quickly and prevents “dangling sessions” on the provider side.
- *
- * 4) Waiting strategy
- *    - Default waitUntil: "load" to avoid hanging on long-lived network activity (analytics/beacons).
- *    - If your HTML depends on external assets (remote CSS/fonts/images), consider "networkidle",
- *      or better: emit an explicit readiness signal and waitForFunction() for deterministic completion.
- *
- * 5) Biggest speed wins usually come from reducing network work
- *    - Inline critical CSS and avoid loading third-party scripts if possible.
- *    - Host/inline fonts and images where feasible to reduce variability and speed up rendering.
- *    - The less the page has to fetch, the faster and more consistent PDF generation becomes.
- *
- * 6) Optional burst optimization (only if needed)
- *    - If you generate many PDFs back-to-back on the same warm instance, you can reuse the CDP
- *      connection briefly (with a short idle timeout).
- *    - Still keep Context-per-request. Avoid keeping the connection open indefinitely to prevent idle cost.
- */
-export declare function getBrowser(): Promise<Browser>;
 export interface PdfOptions {
     /**
      * Display header and footer. Defaults to `false`.
@@ -126,4 +92,4 @@ export interface PdfOptions {
      */
     width?: string | number;
 }
-export declare function generatePdf(html: string, pdfOptions?: PdfOptions): Promise<string>;
+export declare function generatePdf(html: string, pdfOptions: PdfOptions): Promise<Buffer>;

package/dist/chatwms/pdf.js

@@ -0,0 +1,132 @@
+import { sleep } from "../util.js";
+/*
+
+In summary -- try to generate a PDF, and if Browserless is busy, politely wait and try again a few times — then give up cleanly.
+
+Step by step details:
+
+1. Send HTML to Browserless
+   - We make an HTTP request to Browserless’s `/pdf` endpoint.
+   - Browserless runs a browser, renders the HTML, and sends back a PDF.
+
+2. If it works → we’re done
+   - We return the PDF immediately.
+
+3. If Browserless is too busy
+   - Browserless may say:
+     - “Too many requests” (429), or
+     - “Service temporarily unavailable” (503/502/504)
+   - This usually means you hit your concurrency limit, not that something is broken.
+
+4. When that happens
+   - We wait a bit
+   - Then try again
+   - But:
+     - We don’t retry forever
+     - We wait slightly longer each time
+     - We add a little randomness so many requests don’t retry at once
+
+5. If Browserless tells us how long to wait
+   - We listen (`Retry-After` header)
+   - That’s the best signal
+
+6. If the request hangs or the network glitches
+   - We cancel it after a timeout
+   - Then retry (once or twice)
+
+7. If it keeps failing
+   - We stop retrying
+   - We throw a clear error explaining what happened
+*/
+const ENDPOINT = "https://production-sfo.browserless.io/pdf";
+const TIMEOUT_MS = 60_000;
+const RETRIES = 3;
+const BASE_DELAY_MS = 3_000;
+const MAX_DELAY_MS = 15_000;
+const JITTER_MS = 1_000;
+function parseRetryAfterMs(retryAfter) {
+    if (!retryAfter)
+        return null;
+    const asSeconds = Number(retryAfter);
+    if (Number.isFinite(asSeconds) && asSeconds >= 0)
+        return Math.floor(asSeconds * 1000);
+    const asDate = Date.parse(retryAfter);
+    if (!Number.isNaN(asDate)) {
+        const delta = asDate - Date.now();
+        return delta > 0 ? delta : 0;
+    }
+    return null;
+}
+function backoffMs(attempt) {
+    const backoff = BASE_DELAY_MS * Math.pow(2, Math.max(0, attempt - 1));
+    const capped = Math.min(backoff, MAX_DELAY_MS);
+    const jitter = Math.floor(Math.random() * (JITTER_MS + 1));
+    return capped + jitter;
+}
+function shouldRetryStatus(status) {
+    return status === 429 || status === 503 || status === 502 || status === 504;
+}
+export async function generatePdf(html, pdfOptions) {
+    const token = process.env.BROWSERLESS_TOKEN;
+    if (!token) {
+        throw new Error('PDF: `BROWSER_TOKEN` environment variable is not set');
+    }
+    const url = new URL(ENDPOINT);
+    url.searchParams.set("token", token);
+    const totalAttempts = 1 + RETRIES;
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        try {
+            const res = await fetch(url.toString(), {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "accept": "application/pdf",
+                },
+                body: JSON.stringify({
+                    html,
+                    options: pdfOptions ??
+                        {
+                            format: "Letter",
+                            printBackground: true,
+                            preferCSSPageSize: true,
+                        }
+                }),
+                signal: controller.signal,
+            });
+            if (res.ok) {
+                const ab = await res.arrayBuffer();
+                return Buffer.from(ab);
+            }
+            const retryable = shouldRetryStatus(res.status);
+            if (retryable && attempt < totalAttempts) {
+                const retryAfter = parseRetryAfterMs(res.headers.get("retry-after"));
+                const delay = retryAfter !== null ? retryAfter + Math.floor(Math.random() * (JITTER_MS + 1)) : backoffMs(attempt);
+                await sleep(delay);
+                continue;
+            }
+            const bodyText = await res.text().catch(() => "");
+            const preview = bodyText ? bodyText.slice(0, 1000) : "";
+            throw new Error(`PDF: Browserless /pdf failed (${res.status} ${res.statusText})` + (preview ? ` — ${preview}` : ""));
+        }
+        catch (err) {
+            const isAbort = err?.name === "AbortError";
+            const isTransientNetwork = isAbort ||
+                err?.code === "ECONNRESET" ||
+                err?.code === "ETIMEDOUT" ||
+                err?.code === "EAI_AGAIN" ||
+                err?.cause?.code === "ECONNRESET" ||
+                err?.cause?.code === "ETIMEDOUT";
+            if (isTransientNetwork && attempt < totalAttempts) {
+                await sleep(backoffMs(attempt));
+                continue;
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    throw new Error("PDF: Browserless /pdf failed");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cellaware/utils",
-    "version": "8.4.1",
+    "version": "8.5.0",
     "description": "Cellaware Utilities for Node.js",
     "author": "Cellaware Technologies",
     "type": "module",
@@ -21,8 +21,7 @@
         "@azure/functions": "^4.5.1",
         "@azure/storage-blob": "^12.16.0",
         "dotenv": "^16.3.1",
-        "langchain": "^0.2.19",
-        "playwright-core": "^1.57.0"
+        "langchain": "^0.2.19"
     },
     "devDependencies": {
         "typescript": "^5.3.2"

package/dist/browser.js

@@ -1,70 +0,0 @@
-import { chromium } from "playwright-core";
-/**
- * Browserless (hosted) performance & reliability notes
- *
- * 1) Prefer connect-per-request (default)
- *    - We use chromium.connectOverCDP() instead of launching a local browser.
- *    - In serverless, connecting + closing per request is the safest and most cost-predictable option.
- *    - Hosted Browserless usage is typically metered by session/connection time, so leaving connections
- *      open while idle can increase cost.
- *
- * 2) Always isolate work in a fresh BrowserContext per PDF
- *    - Never reuse BrowserContext or Page across requests.
- *    - Context-per-request avoids cookie/storage leaks, cross-request interference, and memory growth.
- *
- * 3) Close deterministically (inner → outer)
- *    - Always close Page, then Context, then Browser (the CDP connection).
- *    - This releases remote resources quickly and prevents “dangling sessions” on the provider side.
- *
- * 4) Waiting strategy
- *    - Default waitUntil: "load" to avoid hanging on long-lived network activity (analytics/beacons).
- *    - If your HTML depends on external assets (remote CSS/fonts/images), consider "networkidle",
- *      or better: emit an explicit readiness signal and waitForFunction() for deterministic completion.
- *
- * 5) Biggest speed wins usually come from reducing network work
- *    - Inline critical CSS and avoid loading third-party scripts if possible.
- *    - Host/inline fonts and images where feasible to reduce variability and speed up rendering.
- *    - The less the page has to fetch, the faster and more consistent PDF generation becomes.
- *
- * 6) Optional burst optimization (only if needed)
- *    - If you generate many PDFs back-to-back on the same warm instance, you can reuse the CDP
- *      connection briefly (with a short idle timeout).
- *    - Still keep Context-per-request. Avoid keeping the connection open indefinitely to prevent idle cost.
- */
-export async function getBrowser() {
-    const token = process.env.BROWSERLESS_TOKEN;
-    if (!token) {
-        throw new Error('BROWSER: `BROWSER_TOKEN` environment variable is not set');
-    }
-    const wsEndpoint = `wss://chrome.browserless.io?token=${encodeURIComponent(token)}`;
-    return await chromium.connectOverCDP(wsEndpoint);
-}
-export async function generatePdf(html, pdfOptions) {
-    let browser;
-    let context;
-    let page;
-    try {
-        browser = await getBrowser();
-        context = await browser.newContext();
-        page = await context.newPage();
-        await page.setContent(html, {
-            waitUntil: "load",
-        });
-        const pdfBytes = await page.pdf(pdfOptions ??
-            {
-                format: "Letter",
-                printBackground: true,
-                preferCSSPageSize: true,
-            });
-        return pdfBytes.toString("base64");
-    }
-    catch (err) {
-        console.log(`BROWSER: PDF generation error: ${err.message}`);
-        return '';
-    }
-    finally {
-        await page?.close().catch(() => { });
-        await context?.close().catch(() => { });
-        await browser?.close().catch(() => { });
-    }
-}