@cellaware/utils 8.3.23 → 8.4.1

package/dist/azure/cosmos.js

@@ -243,7 +243,7 @@ export async function cosmosDelete(databaseId, collectionId, partitionKey, query
 export async function _cosmosUpdate(endpoint, key, databaseId, collectionId, partitionKey, query, data) {
     try {
         if (Array.isArray(data)) {
-            throw new Error('Input `data` cannot be an array');
+            throw new Error('COSMOS: Input `data` cannot be an array');
         }
         const cosmosClient = new CosmosClient({
             endpoint,

package/dist/browser.d.ts

@@ -0,0 +1,129 @@
+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`.
+     */
+    displayHeaderFooter?: boolean;
+    /**
+     * HTML template for the print footer. Should use the same format as the
+     * [`headerTemplate`](https://playwright.dev/docs/api/class-page#page-pdf-option-header-template).
+     */
+    footerTemplate?: string;
+    /**
+     * Paper format. If set, takes priority over
+     * [`width`](https://playwright.dev/docs/api/class-page#page-pdf-option-width) or
+     * [`height`](https://playwright.dev/docs/api/class-page#page-pdf-option-height) options. Defaults to 'Letter'.
+     */
+    format?: string;
+    /**
+     * HTML template for the print header. Should be valid HTML markup with following classes used to inject printing
+     * values into them:
+     * - `'date'` formatted print date
+     * - `'title'` document title
+     * - `'url'` document location
+     * - `'pageNumber'` current page number
+     * - `'totalPages'` total pages in the document
+     */
+    headerTemplate?: string;
+    /**
+     * Paper height, accepts values labeled with units.
+     */
+    height?: string | number;
+    /**
+     * Paper orientation. Defaults to `false`.
+     */
+    landscape?: boolean;
+    /**
+     * Paper margins, defaults to none.
+     */
+    margin?: {
+        /**
+         * Top margin, accepts values labeled with units. Defaults to `0`.
+         */
+        top?: string | number;
+        /**
+         * Right margin, accepts values labeled with units. Defaults to `0`.
+         */
+        right?: string | number;
+        /**
+         * Bottom margin, accepts values labeled with units. Defaults to `0`.
+         */
+        bottom?: string | number;
+        /**
+         * Left margin, accepts values labeled with units. Defaults to `0`.
+         */
+        left?: string | number;
+    };
+    /**
+     * Whether or not to embed the document outline into the PDF. Defaults to `false`.
+     */
+    outline?: boolean;
+    /**
+     * Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
+     */
+    pageRanges?: string;
+    /**
+     * The file path to save the PDF to. If [`path`](https://playwright.dev/docs/api/class-page#page-pdf-option-path) is a
+     * relative path, then it is resolved relative to the current working directory. If no path is provided, the PDF won't
+     * be saved to the disk.
+     */
+    path?: string;
+    /**
+     * Give any CSS `@page` size declared in the page priority over what is declared in
+     * [`width`](https://playwright.dev/docs/api/class-page#page-pdf-option-width) and
+     * [`height`](https://playwright.dev/docs/api/class-page#page-pdf-option-height) or
+     * [`format`](https://playwright.dev/docs/api/class-page#page-pdf-option-format) options. Defaults to `false`, which
+     * will scale the content to fit the paper size.
+     */
+    preferCSSPageSize?: boolean;
+    /**
+     * Print background graphics. Defaults to `false`.
+     */
+    printBackground?: boolean;
+    /**
+     * Scale of the webpage rendering. Defaults to `1`. Scale amount must be between 0.1 and 2.
+     */
+    scale?: number;
+    /**
+     * Whether or not to generate tagged (accessible) PDF. Defaults to `false`.
+     */
+    tagged?: boolean;
+    /**
+     * Paper width, accepts values labeled with units.
+     */
+    width?: string | number;
+}
+export declare function generatePdf(html: string, pdfOptions?: PdfOptions): Promise<string>;

package/dist/browser.js

@@ -0,0 +1,70 @@
+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(() => { });
+    }
+}

package/package.json

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