@medicus.ai/medicus-report-pdf-generator 1.3.13 → 1.3.15

package/.vscode/settings.json

@@ -1,4 +1,4 @@
-{
-    "search.useIgnoreFiles": true,
-    "search.useGlobalIgnoreFiles": true
+{
+    "search.useIgnoreFiles": true,
+    "search.useGlobalIgnoreFiles": true
 }

package/HANDOVER.md

@@ -0,0 +1,146 @@
+# Handover: Medicus PDF Generator
+
+**Audience:** software engineers taking over this project who are not frontend specialists. You don't need deep CSS/HTML expertise to maintain this — you need to understand it as a **data-in, PDF-out rendering pipeline** with some unusual, homegrown templating. This document is the fast path to being productive. Full details, with file:line-level citations, are in [`docs/`](docs/README.md) — this file tells you what matters most and when to go read which doc.
+
+---
+
+## 1. What this thing actually is
+
+`@medicus.ai/medicus-report-pdf-generator` is an **npm library**, not a service. There is no HTTP server, no listener, no routes anywhere in this repo. A host application (per the README, originally a Meteor app) `require()`s it and calls its exported functions directly — or, optionally, through `run.js`, which forks a child process for isolation.
+
+It has:
+- **No authentication or authorization.** No JWT, no sessions, no API keys — check `package.json`, there's nothing auth-related in the dependency list. Whatever calls this library is trusted completely; access control is 100% the host application's job.
+- **No database.** Every call is stateless: JSON in, PDF/HTML/base64 out. The only persistent side effects are files written to `output/` or the OS temp directory (see §6).
+- **Four distinct report "products"**, each with its own generator file and its own quirks (see §4). They are not built on a shared rendering engine — each independently reimplements the same "read HTML fragment from disk, do string replacement, build a DOM with jsdom+jQuery, hand to Puppeteer" pattern.
+
+If you remember one mental model: **this package is a fancy `data.json + template.html → report.pdf` compiler, called once per report, with no state carried between calls** (aside from a few shared-singleton gotchas noted below).
+
+---
+
+## 2. The one fact that will save you the most time
+
+**`index.js` requires `lib/pdf_generator.min.js` — not `lib/pdf_generator.js`.**
+
+These look like a source/minified-build pair. They are not. There's no build script anywhere in this repo that produces one from the other (no webpack config exists, despite `webpack` sitting in `devDependencies`). Git history proves it: `pdf_generator.js` was last edited in **March 2021**; `pdf_generator.min.js` was last edited in **July 2025** — completely independent edit histories, over four years apart.
+
+**If you're asked to fix a bug in the core "Medicus" lab report and you edit `lib/pdf_generator.js`, your fix will silently not ship.** Edit `lib/pdf_generator.min.js` instead. This is the single highest-value thing to internalize before touching this codebase. Full detail: [`docs/01-architecture-overview.md §1.4`](docs/01-architecture-overview.md#14-critical-fact-the-core-report-renderer-that-actually-runs-is-pdf_generatorminjs-not-pdf_generatorjs).
+
+(Longer-term: either delete `pdf_generator.js` and rename `.min.js` to something honest, or wire up a real build step. Either fixes this permanently.)
+
+---
+
+## 3. How data flows in
+
+Every report-generating export in `index.js` follows the same shape: the caller passes a JSON *string* (or, for the core report, a raw base64 string) whose real content — patient data, biomarkers, scores, questions, whatever — is **base64-encoded** inside a `data` field, alongside plain-text sibling fields like `client`, `language`, and (if emailing) SMTP config.
+
+```js
+{
+  "data": "<base64 of the actual report JSON>",
+  "client": "Mediclinic",
+  "language": "en",
+  "host": "smtp...", "port": 587, "authUser": "...", "authPass": "...",  // only if emailing
+  "pdfPassword": "..."  // generateFullPdf only — output gets encrypted
+}
+```
+
+**Base64 is encoding, not security.** Anyone who can see a request to this library (including anyone reading a debug log) can trivially recover everything inside it, including SMTP credentials riding alongside the report data. See §7.
+
+---
+
+## 4. The four report pipelines — know which one you're in before debugging
+
+- **Core "Medicus"** — module `lib/pdf_generator.min.js`. Clinical lab report: biomarkers, panels, reference ranges, doctor notes, insights. No questionnaires. Entry point: `generateMedicusPDF`.
+- **Wellbeing** — module `lib/wellbeing_report_generator.js` (+ `lib/template.js`, `lib/big_integral_questionnaire.js`). Patient wellbeing/lifestyle report — questionnaire scores and Q&A, optionally merged with a full lab report ("SmartReport"). Entry points: `generateNascoPDF` (plain), `generateFullPdf` (branded + SmartReport + PDF encryption).
+- **Corporate** — module `lib/corporate_report_generator.js`. Population-level analytics report for an employer/corporate client. Entry point: `generateCorporateReportPDF`.
+- **SanusX** — module `lib/sanusx_report_generator.js`. Consumer "Health Hero" wellbeing report with an avatar/scoring gimmick. Entry point: `generateSanuxPDF`.
+
+They genuinely don't share code — a fix in one does not apply to the others. Before debugging "the report looks wrong," identify which of these four you're actually looking at. Full detail per pipeline, including known bugs specific to each: [`docs/04-report-pipelines.md`](docs/04-report-pipelines.md).
+
+---
+
+## 5. Whitelabelling in one paragraph (and its landmines)
+
+Branding is chosen by a plain string (`client`/`clientName`) in the request payload, which each generator maps — independently, and **inconsistently** — to a `config/{Brand}.json` file (colors, logos) and sometimes a `templates/{Brand}/` folder (full HTML layout). There is no environment variable and no central "client registry." Five different pieces of code (the wellbeing generator, the corporate generator, the email module, the sanusx generator, and the fact that the core report doesn't do this at all) each have their own rule for turning a client string into a filename, and they disagree on casing and on which strings get special-cased (only `"pha"` → `"Pha"` is handled specially, and only in some of them). One of these (`corporate_report_generator.js`) lower-cases the client string before building a path to a capitalized filename — this only works today because of case-insensitive filesystems; it will break on Linux. `sanusx_report_generator.js` ignores the client string for branding entirely. **Before onboarding a new brand, read [`docs/02-configuration-and-whitelabelling.md`](docs/02-configuration-and-whitelabelling.md) in full** — guessing "just add a config file" will not be enough.
+
+---
+
+## 6. Where do the questions come from? (the thing you specifically asked about)
+
+**This library does not own or store questionnaire content.** There is no question bank, no question-ID lookup, no survey schema in this repository. Every question's text and its answer arrive **together, pre-rendered**, as flat `{title, value}` pairs inside the JSON payload — the host application (whatever system runs the actual questionnaire/survey with the patient) is responsible for assembling that array before calling this library.
+
+Concretely, in the wellbeing pipeline:
+```js
+"Profile": [
+  { "title": "What is your gender?", "value": "Male" },
+  { "title": "Over the last 2 weeks, how often have you been bothered by feeling down, depressed, or hopeless?",
+    "value": "More than half the days" }
+  // ...
+]
+```
+
+This gets laid out as a two-column "Quiz Answers" table by `renderDoctorDetails()` in `lib/wellbeing_report_generator.js` — plain layout code, no interpretation of what the question means. Numeric scores (PHQ‑9 totals, etc.) are a *separate* field (`data.wellbeing.calculation`) that's also pre-computed upstream — this library doesn't score anything either. The core lab-report pipeline has no question concept at all (its domain is biomarkers, not questionnaires).
+
+**One trap:** `lib/big_integral_questionnaire.js` looks like a real questionnaire-rendering feature but currently renders **100% hardcoded dummy data** — it is a design/preview scaffold, not wired to real patient answers. If someone asks why it doesn't reflect real data, that's expected, not a bug to "fix" quickly — it needs real wiring designed first.
+
+Also worth flagging to whoever owns data quality upstream: the answer *values* rendered into this table are **not HTML-escaped**. If free-text ever flows into `Profile[].value` from a less-trusted source, that's an injection risk into the rendered page.
+
+Full detail, including exactly which field goes where in which pipeline: [`docs/05-questions-and-data-model.md`](docs/05-questions-and-data-model.md).
+
+---
+
+## 7. Security posture — what to tell people who ask
+
+- **No auth in this library** (see §1). Access control lives entirely in the host application.
+- **SMTP credentials travel as plaintext JSON fields**, inside a payload that's only base64-encoded, not encrypted. This is the most concrete, fixable security gap: see [`docs/07-email-notifications.md §7.4`](docs/07-email-notifications.md#74-security-considerations). If asked to harden this, moving SMTP credentials to host-app-side environment configuration (rather than per-call payload fields) is the right direction.
+- The `secure` flag callers pass for SMTP is silently ignored (dead code) — the transport actually always forces STARTTLS via `requireTLS: true`, so it's not literally insecure, just misleading.
+- Unescaped answer text in the wellbeing Q&A table (§6) is a latent XSS-into-rendered-PDF risk if upstream data isn't sanitized.
+- No secrets are hardcoded in the codebase itself (verified during this review).
+
+---
+
+## 8. Internationalization and RTL — the short version
+
+Two separate, independently configured instances of the `i18n` npm package exist: one for the core report (`locales/`), one for **everything else** — wellbeing, corporate, *and* SanusX — (`locales/wellbeing/`, despite the folder name). If you're hunting for a translation string and the generator you're editing isn't the core lab report, look in `locales/wellbeing/`, not `locales/`.
+
+RTL (Arabic) support works via three overlapping mechanisms (whole alternate template files, alternate block partials, inline CSS direction switches) and — important gotcha — three of the four generators forcibly rewrite any Arabic-ish language code to `ar-SA`, meaning `ar-AE` is effectively unreachable. SanusX's RTL is outright broken (never triggers). Locale state also lives on a shared, process-global singleton, so concurrent report-generation calls in the same process can theoretically leak one request's language into another's — the codebase already fixed an analogous bug for temp file paths but not for this. Full detail: [`docs/06-internationalization.md`](docs/06-internationalization.md).
+
+---
+
+## 9. Running/testing this locally
+
+There's no formal test framework (no Jest/Mocha in `devDependencies`, `package.json`'s only script is `"start": "node index.js"`, which just requires the library — it does nothing on its own). What exists instead:
+
+- **`test.js`** (root) — an ad hoc script that calls `generateHTMLWellbeingReportWithSmartReport`/`generatePDFReport` directly against fixture data from `testing-reports/` and writes to `output/nasco-sample.pdf` (and an encrypted copy via `node-qpdf2`). Swap which fixture variable is assigned to `data`/`client` at the top of the file to test a different brand/scenario.
+- **`testing-reports/{mediclinic,pha}/*.js`** — example payloads (`doctor-data.js` has `IsDoctor: true` with a full PHQ‑9/GAD‑7-style `Profile` array — the best reference for the Q&A shape described in §6).
+- **`preview-big-integral.js`** — standalone harness for the `big_integral_questionnaire.js` dummy-data table.
+- **`tests/test.js`, `tests/test-qr-code.js`** — more ad hoc scripts; `test-qr-code.js` is the reference for how `generatePatientQR` expects a caller-pre-rendered HTML/SVG string.
+- Puppeteer needs a compatible Chromium available; `downloadfile.js` is a one-off helper that fetches a pinned Chromium build for Windows if you need it locally.
+
+There is no CI test suite validating rendered PDF output — verification today is manual (run a script, open the resulting PDF in `output/`).
+
+---
+
+## 10. If you're prioritizing what to fix first
+
+In order of leverage for time invested:
+
+1. Resolve the `pdf_generator.js` vs `.min.js` divergence (§2) — either delete the stale file or add a real build step. Highest risk of silent, confusing bugs.
+2. Unify client-name → config/template resolution into one shared helper, used by all five places that currently reimplement it differently (§5).
+3. Fix the SMTP-credentials-in-plaintext-payload pattern (§7) — at minimum, stop it from ever landing in debug logs; ideally move it out of the payload entirely.
+4. Scope locale state per-request instead of a shared singleton (§8) — currently a latent concurrency bug.
+5. Everything else is cataloged, ranked, and cross-referenced in [`docs/08-known-issues-and-technical-debt.md`](docs/08-known-issues-and-technical-debt.md) — treat that file as your punch list.
+
+---
+
+## 11. Full documentation index
+
+For anything beyond this summary, go to [`docs/README.md`](docs/README.md), which indexes:
+
+1. [Architecture Overview](docs/01-architecture-overview.md)
+2. [Configuration & Whitelabelling](docs/02-configuration-and-whitelabelling.md)
+3. [Templating & Rendering Pipeline](docs/03-templating-and-rendering.md)
+4. [Report Pipelines](docs/04-report-pipelines.md)
+5. [Questions, Answers & the Data Model](docs/05-questions-and-data-model.md)
+6. [Internationalization (i18n) & RTL](docs/06-internationalization.md)
+7. [Email Notifications](docs/07-email-notifications.md)
+8. [Known Issues & Technical Debt](docs/08-known-issues-and-technical-debt.md)

package/README.md

@@ -1,27 +1,27 @@
-# Medicus Pdf Generator
-
-This package is a stand-alone lightweight nodejs library for generating medical reports in a PDF format.
-
-## Installation
-
-using this command.
-
-```bash
-npm install @medicus.ai/medicus-report-pdf-generator
-```
-
-## Usage
-
-```python
-const {generateMedicusPDF} = require('@medicus.ai/medicus-report-pdf-generator');
-
-async function generatePDF(json) {
-   try {
-        const data = await generateMedicusPDF(json);
-        return data;
-    }
-    catch (e) {
-        throw new Meteor.Error(500, 'error', e);
-    }
-}
+# Medicus Pdf Generator
+
+This package is a stand-alone lightweight nodejs library for generating medical reports in a PDF format.
+
+## Installation
+
+using this command.
+
+```bash
+npm install @medicus.ai/medicus-report-pdf-generator
+```
+
+## Usage
+
+```python
+const {generateMedicusPDF} = require('@medicus.ai/medicus-report-pdf-generator');
+
+async function generatePDF(json) {
+   try {
+        const data = await generateMedicusPDF(json);
+        return data;
+    }
+    catch (e) {
+        throw new Meteor.Error(500, 'error', e);
+    }
+}
 ```

package/app/i18n.config.js

@@ -1,21 +1,21 @@
-const i18n = require('i18n');
-const path = require('path');
-
-i18n.configure({
-    locales: ['en', 'de', 'fr', 'ar-AE', 'ar-SA', 'pt', 'zh-CN'],
-    defaultLocale: 'en',
-    // sets a custom cookie name to parse locale settings from - defaults to NULL
-    cookie: 'currentLang',
-    queryParameter: 'lang',
-    directory: path.resolve(__dirname + '/../locales'),
-    api: {
-        '__': 'translate',
-        '__n': 'translateN'
-    },
-    // Downcase locale when passed on queryParam; e.g. lang=en-US becomes
-    // en-us.  When set to false, the queryParam value will be used as passed;
-    // e.g. lang=en-US remains en-US.
-    preserveLegacyCase: true
-});
-
+const i18n = require('i18n');
+const path = require('path');
+
+i18n.configure({
+    locales: ['en', 'de', 'fr', 'ar-AE', 'ar-SA', 'pt', 'zh-CN'],
+    defaultLocale: 'en',
+    // sets a custom cookie name to parse locale settings from - defaults to NULL
+    cookie: 'currentLang',
+    queryParameter: 'lang',
+    directory: path.resolve(__dirname + '/../locales'),
+    api: {
+        '__': 'translate',
+        '__n': 'translateN'
+    },
+    // Downcase locale when passed on queryParam; e.g. lang=en-US becomes
+    // en-us.  When set to false, the queryParam value will be used as passed;
+    // e.g. lang=en-US remains en-US.
+    preserveLegacyCase: true
+});
+
 module.exports = i18n;

package/app/i18n_wellbeing.config.js

@@ -1,21 +1,21 @@
-const i18n = require('i18n');
-const path = require('path');
-
-i18n.configure({
-    locales: ['en', 'de', 'fr', 'ar-AE', 'ar-SA', 'pt', 'zh-CN', 'tr', 'es'],
-    defaultLocale: 'en',
-    // sets a custom cookie name to parse locale settings from - defaults to NULL
-    cookie: 'currentLang',
-    queryParameter: 'lang',
-    directory: path.resolve(__dirname + '/../locales/wellbeing'),
-    api: {
-        '__': 'translate',
-        '__n': 'translateN'
-    },
-    // Downcase locale when passed on queryParam; e.g. lang=en-US becomes
-    // en-us.  When set to false, the queryParam value will be used as passed;
-    // e.g. lang=en-US remains en-US.
-    preserveLegacyCase: true
-});
-
+const i18n = require('i18n');
+const path = require('path');
+
+i18n.configure({
+    locales: ['en', 'de', 'fr', 'ar-AE', 'ar-SA', 'pt', 'zh-CN', 'tr', 'es'],
+    defaultLocale: 'en',
+    // sets a custom cookie name to parse locale settings from - defaults to NULL
+    cookie: 'currentLang',
+    queryParameter: 'lang',
+    directory: path.resolve(__dirname + '/../locales/wellbeing'),
+    api: {
+        '__': 'translate',
+        '__n': 'translateN'
+    },
+    // Downcase locale when passed on queryParam; e.g. lang=en-US becomes
+    // en-us.  When set to false, the queryParam value will be used as passed;
+    // e.g. lang=en-US remains en-US.
+    preserveLegacyCase: true
+});
+
 module.exports = i18n;

package/app/services/localeService.js

@@ -1,29 +1,29 @@
-/**
- * LocaleService
- */
-function LocaleService(i18nProvider) {
-    this.i18nProvider = i18nProvider;
-    this.getCurrentLocale = function () {
-        return this.i18nProvider.getLocale();
-    }
-    this.translatePlurals = function (phrase, count) {
-        return this.i18nProvider.translateN(phrase, count)
-    }
-
-
-    this.setLocale = function (locale) {
-        if (this.getLocales().indexOf(locale) !== -1) {
-            this.i18nProvider.setLocale(locale)
-        }
-    }
-
-    this.t = function (string, args = undefined) {
-        return this.i18nProvider.__(string, args).message
-    }
-
-    this.getLocales = function () {
-        return this.i18nProvider.getLocales();
-    }
-}
-
+/**
+ * LocaleService
+ */
+function LocaleService(i18nProvider) {
+    this.i18nProvider = i18nProvider;
+    this.getCurrentLocale = function () {
+        return this.i18nProvider.getLocale();
+    }
+    this.translatePlurals = function (phrase, count) {
+        return this.i18nProvider.translateN(phrase, count)
+    }
+
+
+    this.setLocale = function (locale) {
+        if (this.getLocales().indexOf(locale) !== -1) {
+            this.i18nProvider.setLocale(locale)
+        }
+    }
+
+    this.t = function (string, args = undefined) {
+        return this.i18nProvider.__(string, args).message
+    }
+
+    this.getLocales = function () {
+        return this.i18nProvider.getLocales();
+    }
+}
+
 module.exports = LocaleService;