npm - @medicus.ai/medicus-report-pdf-generator - Versions diffs - 1.3.13 → 1.3.15 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (178) hide show

package/.vscode/settings.json +3 -3
package/HANDOVER.md +146 -0
package/README.md +26 -26
package/app/i18n.config.js +20 -20
package/app/i18n_wellbeing.config.js +20 -20
package/app/services/localeService.js +28 -28
package/assets/Mediclinic/css/nasco_report.css +6297 -6297
package/assets/Mediclinic/css/nasco_report_rtl.css +851 -851
package/assets/Mediclinic/css/style.css +33 -33
package/assets/Mediclinic/js/js.js +112 -112
package/assets/Mediclinic/js/raphael.js +8437 -8437
package/assets/arabic.css +275 -275
package/assets/charts.min.js +7 -7
package/assets/corporate_report/css/report.css +582 -582
package/assets/corporate_report/css/report_rtl.css +144 -144
package/assets/corporate_report/js/js.js +14 -14
package/assets/data/data.json +124 -124
package/assets/data/data2.json +675 -675
package/assets/data/pdf_data_with_history.json +1255 -1255
package/assets/doctor-note-insight-icon.svg +11 -11
package/assets/imc/css/style.css +61 -61
package/assets/jquery-1.4.min.js +151 -151
package/assets/jquery-2.1.0.min.js +3 -3
package/assets/js.js +201 -201
package/assets/medicus_pdf/arabic.css +444 -444
package/assets/medicus_pdf/styles.css +2427 -2427
package/assets/print.css +4 -4
package/assets/qr-code-style.css +68 -68
package/assets/qrcode.min.js +3 -3
package/assets/raphael-min.js +10 -10
package/assets/sanusx/css/sanusx_report.css +707 -707
package/assets/sizing.js +2 -2
package/assets/styles.css +1545 -1545
package/assets/styles.min.css +1358 -1358
package/assets/translation.js +30 -30
package/assets/wellbeing/css/nasco_report.css +3472 -3472
package/assets/wellbeing/css/nasco_report_rtl.css +679 -679
package/assets/wellbeing/js/js.js +111 -111
package/assets/wellbeing/js/raphael.js +8437 -8437
package/base64/cairo-font.js +2 -2
package/config/Mediclinic.json +37 -37
package/config/Najeeb.ai.json +35 -35
package/config/Pha.json +64 -64
package/config/bionext.json +37 -37
package/config/default.json +35 -35
package/config/diagnostikare.json +34 -34
package/config/maisonsante.json +39 -39
package/config/nasco.json +35 -35
package/config/sanitas.json +35 -35
package/config/sanusx.json +34 -34
package/config/test.txt +4 -4
package/data converter.js +53 -53
package/docs/01-architecture-overview.md +149 -0
package/docs/02-configuration-and-whitelabelling.md +111 -0
package/docs/03-templating-and-rendering.md +71 -0
package/docs/04-report-pipelines.md +128 -0
package/docs/05-questions-and-data-model.md +67 -0
package/docs/06-internationalization.md +59 -0
package/docs/07-email-notifications.md +59 -0
package/docs/08-known-issues-and-technical-debt.md +41 -0
package/docs/README.md +22 -0
package/downloadfile.js +6 -6
package/example.txt +1188 -1188
package/index.js +481 -480
package/lib/big_integral_questionnaire.js +370 -298
package/lib/corporate_report_generator.js +399 -399
package/lib/pdf_generator.min.js +525 -525
package/lib/sanusx_report_generator.js +533 -533
package/lib/sendEmail.js +343 -343
package/lib/template.js +2227 -2227
package/lib/wellbeing_report_generator.js +2164 -2134
package/locales/ar-AE.json +169 -169
package/locales/ar-SA.json +169 -169
package/locales/ar.json +397 -397
package/locales/de.json +169 -169
package/locales/en.json +229 -229
package/locales/fr.json +168 -168
package/locales/pt.json +165 -165
package/locales/wellbeing/ar-AE.json +149 -149
package/locales/wellbeing/ar-SA.json +257 -257
package/locales/wellbeing/de.json +301 -301
package/locales/wellbeing/en.json +423 -423
package/locales/wellbeing/es.json +133 -133
package/locales/wellbeing/fr.json +121 -121
package/locales/wellbeing/it-IT.json +121 -121
package/locales/wellbeing/pt.json +121 -121
package/locales/wellbeing/tr.json +121 -121
package/locales/wellbeing/zh-CN.json +121 -121
package/locales/zh-CN.json +165 -165
package/package.json +47 -47
package/preview-big-integral.js +75 -75
package/run.js +15 -15
package/templates/Mediclinic/blocks/first-section.html +205 -205
package/templates/Mediclinic/blocks/footer.html +7 -7
package/templates/Mediclinic/blocks/header-template.html +5 -5
package/templates/Mediclinic/blocks/header.html +20 -20
package/templates/Mediclinic/blocks/patient-table.html +38 -38
package/templates/Mediclinic/blocks/pdf-header.html +9 -9
package/templates/Mediclinic/blocks/tips.html +8 -8
package/templates/Mediclinic/ltr_no_pages.html +37 -37
package/templates/Mediclinic/rtl_no_pages.html +42 -42
package/templates/Mediclinic/wellbeing_template.html +41 -41
package/templates/Pha/blocks/first-section.html +207 -207
package/templates/Pha/blocks/footer.html +7 -7
package/templates/Pha/blocks/header-template.html +5 -5
package/templates/Pha/blocks/header.html +20 -20
package/templates/Pha/blocks/patient-table.html +38 -38
package/templates/Pha/blocks/pdf-header.html +8 -8
package/templates/Pha/blocks/tips.html +8 -8
package/templates/Pha/ltr_no_pages.html +37 -37
package/templates/Pha/rtl_no_pages.html +42 -42
package/templates/Pha/wellbeing_template.html +41 -41
package/templates/base.html +23 -23
package/templates/blocks/ar-first-page-header.html +68 -68
package/templates/blocks/ar-footer.html +54 -54
package/templates/blocks/ar-header.html +67 -67
package/templates/blocks/biomarker-compact-ar.html +27 -27
package/templates/blocks/biomarker-compact.html +27 -27
package/templates/blocks/biomarker-details.html +41 -41
package/templates/blocks/biomarker-insight.html +22 -22
package/templates/blocks/biomarker-min.html +9 -9
package/templates/blocks/doctor-note.html +11 -11
package/templates/blocks/footer.html +35 -35
package/templates/blocks/header-first-page.html +46 -46
package/templates/blocks/header.html +49 -49
package/templates/blocks/panel-compact.html +38 -38
package/templates/blocks/panel-details.html +16 -16
package/templates/blocks/report-summary.html +16 -16
package/templates/blocks/section-title.html +4 -4
package/templates/blocks/signature.html +16 -16
package/templates/blocks/summary-insight.html +15 -15
package/templates/blocks/summary.html +9 -9
package/templates/corporate_report/cover_page.html +23 -23
package/templates/corporate_report/footer.html +9 -9
package/templates/corporate_report/ltr_no_pages.html +20 -20
package/templates/corporate_report/page.html +24 -24
package/templates/corporate_report/participant_analytics.html +5 -5
package/templates/corporate_report/rtl_no_pages.html +20 -20
package/templates/empty.html +10 -10
package/templates/first_page_head.html +157 -157
package/templates/imc/first-header-template.html +53 -53
package/templates/ltr.html +1368 -1368
package/templates/ltr_no_pages.html +89 -89
package/templates/maisonsante/blocks/first-section.html +151 -207
package/templates/maisonsante/blocks/footer.html +7 -7
package/templates/maisonsante/blocks/header-template.html +5 -5
package/templates/maisonsante/blocks/header.html +20 -20
package/templates/maisonsante/blocks/patient-table.html +38 -38
package/templates/maisonsante/blocks/pdf-header.html +8 -8
package/templates/maisonsante/blocks/tips.html +8 -8
package/templates/maisonsante/ltr_no_pages.html +38 -38
package/templates/maisonsante/rtl_no_pages.html +43 -43
package/templates/maisonsante/wellbeing_template.html +41 -41
package/templates/no_pages.html +1224 -1224
package/templates/popup/popup-template.html +129 -129
package/templates/rtl_no_pages.html +92 -92
package/templates/sanusx/blocks/footer.html +6 -6
package/templates/sanusx/blocks/header.html +20 -20
package/templates/sanusx/blocks/personal-details.html +123 -123
package/templates/sanusx/blocks/predictions-section.html +57 -57
package/templates/sanusx/blocks/recommendations-section.html +6 -6
package/templates/sanusx/blocks/super-power-section.html +29 -29
package/templates/sanusx/blocks/tips.html +8 -8
package/templates/sanusx/ltr_no_pages.html +26 -26
package/templates/sanusx/rtl_no_pages.html +36 -36
package/templates/template.html +1377 -1377
package/templates/wellbeing/blocks/first-section.html +106 -106
package/templates/wellbeing/blocks/footer.html +7 -7
package/templates/wellbeing/blocks/header.html +37 -37
package/templates/wellbeing/blocks/tips.html +8 -8
package/templates/wellbeing/ltr_no_pages.html +35 -35
package/templates/wellbeing/rtl_no_pages.html +36 -36
package/templates/wellbeing/wellbeing_template.html +43 -43
package/test.js +74 -74
package/testing-reports/mediclinic/arabic-data.js +0 -439
package/testing-reports/mediclinic/doctor-data.js +0 -523
package/testing-reports/mediclinic/with-wellbeing.js +0 -415
package/testing-reports/pha/notes-example.js +0 -397

package/docs/06-internationalization.md ADDED Viewed

@@ -0,0 +1,59 @@
+# 6. Internationalization (i18n) & RTL
+## 6.1 Library and the two independent configurations
+The project uses the **`i18n` npm package** (`"i18n": "^0.8.3"` in `package.json`, resolving to `0.8.6` installed) — not `i18n-nodejs`, not a custom framework. There are **two independently configured instances** of this same package, each a process-wide singleton:
+- **`app/i18n.config.js`** — `locales`: `en`, `de`, `fr`, `ar-AE`, `ar-SA`, `pt`, `zh-CN`. Directory: `locales/`. Used by: `lib/pdf_generator.js` / `.min.js` (core report) only.
+- **`app/i18n_wellbeing.config.js`** — `locales`: `en`, `de`, `fr`, `ar-AE`, `ar-SA`, `pt`, `zh-CN`, `tr`, `es`. Directory: `locales/wellbeing/`. Used by: `wellbeing_report_generator.js`, `template.js`, `corporate_report_generator.js`, `sanusx_report_generator.js`.
+**Every generator except the core lab report pulls its strings from `locales/wellbeing/`, not `locales/`** — including the corporate report and SanusX report, despite neither being "wellbeing" products. This is a non-obvious naming trap when you're hunting for a string to translate: check which config the generator you're editing actually requires before assuming which locale folder to edit.
+Both configs also set `cookie: 'currentLang'`, `queryParameter: 'lang'`, and alias the translate API to `translate`/`translateN` instead of the package default `__`/`__n`. Neither sets `objectNotation`, `fallbacks`, or `updateFiles`, so package defaults apply (see 6.5).
+Because Node caches `require()`d modules, every file that requires either config gets the **same shared mutable object** — locale state is process-global, not per-request. See 6.6.
+## 6.2 `app/services/localeService.js`
+A thin wrapper class, instantiated separately by each generator with its own `i18n` singleton:
+- `t(key, args)` → `i18nProvider.__(key, args).message` — the actual string getter. In practice, `args` is never passed at any call site in this codebase — the package's built-in `%s`/vsprintf-style interpolation is wired up but unused.
+- `setLocale(locale)` → **only** calls through to the underlying `i18n.setLocale(locale)` if `locale` is already in that instance's configured `locales` array; otherwise it silently no-ops (see 6.5 for why this matters).
+- `getLocales()`, `getCurrentLocale()`, `translatePlurals()` — thin proxies.
+Instead of the package's own `%s` interpolation, this codebase uses ad hoc single-token placeholders baked directly into translation strings and manually substituted at the call site, e.g. `localeService.t('predictionsDesc').replace("{$val}", finalScore)`.
+`lib/template.js` additionally has a second, parallel string-getter, `getLocale(key)`, used at a couple of call sites instead of `localeService.t(key)` — worth confirming both resolve against the same underlying data before refactoring either.
+## 6.3 Locale JSON shape
+Flat (no nesting — `objectNotation` is off), but each value is normally an **object**, not a plain string:
+```json
+// locales/en.json
+"APPROVED BY": { "message": "Approved", "description": "before the doctor signature..." }
+```
+`LocaleService.t()` must append `.message` itself because of this shape. `locales/en.json` covers header/report labels, section titles, footer/pagination text, biomarker table headers, month names, and a `bigIntegral*` block. `locales/wellbeing/en.json` (424 lines) covers patient-header labels, section labels (`lifeStyle`/`body`/`mind`/`psychological`/`physical`), disclaimer text, corporate-report strings (`Copyright`, `Participant Analytics`), email body strings, and SanusX avatar/prediction content (including the `{$val}`/`{$value}` tokens mentioned above).
+## 6.4 RTL handling — three overlapping mechanisms
+1. **Whole alternate template files.** Every report family ships a matched pair, `rtl_no_pages.html` / `ltr_no_pages.html` (also under each brand subfolder). The RTL variant hardcodes `<html dir="rtl" lang="ar">` and loads a dedicated `assets/arabic.min.css` alongside the normal stylesheet.
+2. **Alternate block partials for Arabic.** The core report swaps in `templates/blocks/ar-first-page-header.html`, `ar-header.html`, `ar-footer.html`, `biomarker-compact-ar.html` when RTL.
+3. **Inline CSS direction/attribute switching** for pieces that aren't full templates — dozens of `isRtl ? ... : ...` inline-style branches (float/padding/text-align) scattered through `lib/template.js` and the report generators.
+**RTL detection is a substring test:** `language.indexOf('ar') !== -1`, applied independently in the core report, wellbeing generator, and corporate report generator. In **all three** of those, once `isRtl` is true, **the language is forcibly overwritten to `'ar-SA'`**, regardless of whether the caller actually asked for `ar`, `ar-AE`, or `ar-SA`. Practical effect: **`locales/ar-AE.json` / `locales/wellbeing/ar-AE.json` are functionally unreachable** through those three pipelines — only `sanusx_report_generator.js` skips this coercion (though SanusX has its own, separate RTL problem — see [doc 4.D](04-report-pipelines.md#4d-sanusx-report): it never computes an `isRtl` flag at all and always loads the LTR template).
+## 6.5 Fallback logic — two layers that disagree
+- **Package layer:** if a requested locale isn't in the configured `locales` list and there's no `fallbacks` entry (there never is, here), `i18n`'s own `setLocale`/`translate` internals force the locale to `defaultLocale` (`'en'`) — the behavior you'd naively expect.
+- **`LocaleService` layer:** `setLocale()` only forwards to the package **if** the requested locale is already in `getLocales()`. If it isn't, the package's `setLocale` is **never called at all**, so its own fallback-to-`en` logic never runs — **the previously active locale on the shared singleton simply stays in effect.** Net effect: requesting an unsupported locale does not deterministically fall back to English; it silently reuses whatever locale a prior call last set on that same process-global singleton.
+- Separately, the package's `updateFiles: true` default means a **missing translation key** (not a missing locale) causes the literal key string to be auto-persisted back into that locale's JSON file on disk the first time it's looked up, rather than falling back to another locale's text. This is visible today in `locales/wellbeing/en.json`, where a few keys near the bottom (e.g. `bigIntegralSystem`) are stored as bare strings rather than the usual `{message, description}` object — almost certainly auto-written by a prior lookup from the (currently unused) `big_integral_questionnaire.js` locale hook. **If that hook is ever wired up for real, `.message` access on these bare-string entries will return `undefined`, producing blank text in the PDF** — worth fixing (wrap them as proper `{message, description}` objects) before relying on them.
+## 6.6 Gotchas for a new engineer
+- **Global, non-request-scoped locale state.** `i18n.setLocale(...)` mutates a shared, cached singleton. If two report-generation calls run concurrently in the same Node process (this package does not enforce single-threaded/sequential use), one request's language can leak into another's mid-render. There is no per-request locale scoping in use, though the `i18n` package does support it (passing a `req`/`res`-like context) — it's simply not adopted here. This is the same class of bug the codebase already had to specifically work around for temp file paths in `generateFullPdf` (see [doc 1.7](01-architecture-overview.md#17-filetemp-file-handling--an-evolving-pattern-worth-knowing)) — locale state was not given the same treatment.
+- **Orphaned locale files.** `locales/ar.json` exists on disk but is **not** in `app/i18n.config.js`'s `locales` array, and — telling sign — its key set matches the *wellbeing* schema, not the main lab-report schema, suggesting it was dropped in the wrong directory. `locales/wellbeing/it-IT.json` similarly exists but `'it-IT'` is absent from `app/i18n_wellbeing.config.js`'s `locales` array. Neither file is ever loaded.
+- **`ar-AE` is effectively dead** in three of the four generators (see 6.4).
+- **Dead RTL template:** `templates/sanusx/rtl_no_pages.html` is never read by any code path.
+- If you add a new locale, you must add it to **both** the correct `locales` array *and* the `LocaleService`'s implicit gate (it derives from the same array, so this is really one step) — but remember to check whether the RTL-coercion-to-`ar-SA` logic needs updating too if it's a new Arabic variant.

package/docs/07-email-notifications.md ADDED Viewed

@@ -0,0 +1,59 @@
+# 7. Email Notifications
+## 7.1 Module and exports
+`lib/sendEmail.js` uses **nodemailer** and exports two functions:
+- **`sendNascoEmail(data, pdfAttachmentPath, mailConfig, clientName)`** — sends a report email with the generated PDF attached. Used by `generateNascoPDF`, `generateFullPdf`, and `generateSanuxPDF` in `index.js` (i.e. shared across the wellbeing, extended-wellbeing, and SanusX flows, despite the "Nasco" name).
+- **`sendEmailNotification(data)`** — a generic notification email, no PDF pipeline attached. Wired to `index.js`'s exported `sendEmail(json)`.
+## 7.2 SMTP transport configuration — entirely caller-supplied
+There are **no environment variables and no hardcoded SMTP credentials** anywhere in this module. The transport is built directly from a `mailConfig` object that the caller constructs and passes in:
+```js
+// index.js — constructed identically in generateNascoPDF, generateFullPdf, generateSanuxPDF
+let mailConfig = {
+    host: reportData.host,
+    port: reportData.port,
+    authUser: reportData.authUser,
+    authPass: reportData.authPass,
+    sendFromEmail: reportData.sendFromEmail,
+    secure: reportData.secure
+}
+```
+```js
+// lib/sendEmail.js
+var transporter = nodemailer.createTransport({
+    host: mailConfig.host,
+    port: mailConfig.port,
+    secure: false,          // NOTE: hardcoded, see below
+    pool: true,
+    requireTLS: true,
+    maxConnections: 20,
+    maxMessages: 1,
+    auth: { user: mailConfig.authUser, pass: mailConfig.authPass }
+});
+```
+**Known bug:** `mailConfig.secure` is collected from the caller in all three call sites but **never actually read** by `sendMail` — the transporter hardcodes `secure: false` and instead forces a STARTTLS upgrade via `requireTLS: true`. So the connection isn't unencrypted (an unsupportable-TLS server will fail closed), but a caller who explicitly sets `secure: true` expecting implicit TLS (port-465 style) gets no such thing — the flag is dead code. If you ever need genuinely implicit-TLS support, this is where to add it.
+`maxMessages: 1` combined with `pool: true` means a new SMTP connection/handshake is opened per message despite pooling being enabled — a minor inefficiency, not a security issue.
+`sendEmailNotification` builds its own, differently-shaped `mailConfig` inline from the same style of caller-supplied fields.
+## 7.3 Email content
+- **Attachment:** yes — the generated PDF, attached by **file path** (nodemailer reads it from disk, not from an in-memory buffer): `attachments: [{ path: pdfAttach, filename: data.name + " WellbeingReport.pdf", contentType: "application/pdf" }]`. In the `generateFullPdf` flow, this path is a per-call, UUID-suffixed temp file that gets unlinked after send (see [doc 1.7](01-architecture-overview.md#17-filetemp-file-handling--an-evolving-pattern-worth-knowing)); in the older `generateNascoPDF`/`generateSanuxPDF` flows it's a fixed shared filename under `output/`.
+- **Subject/body (`sendNascoEmail`):** subject is a fixed, localized string (`localeService.t('wellbeingReport')`); the body is a hardcoded, i18n-translated multi-paragraph template — genuinely translated, but not caller-customizable beyond the patient's name.
+- **Subject/body (`sendEmailNotification`):** fully caller-driven — `data.emailSubject`, plus `customHeaderHTML`/`customBodyHTML`/`customFooterHTML` override fields.
+- **Branding:** `sendNascoEmail` pulls `logo`, `signature`, and a color from `config/{clientName}.json` (falling back to `config/default.json`) — using the client string **as-is, with no case-normalization and no `pha`→`Pha` mapping** (a third, different resolution rule from the ones in [doc 2.2](02-configuration-and-whitelabelling.md#22-how-clientclientname-resolves-to-a-config-file--and-why-its-inconsistent) — the caller must pass the exact on-disk filename casing here).
+- **RTL:** email HTML uses a `lang === "ar"` check to flip `float`/`text-align`/`direction` in its hand-built inline styles — a simpler mechanism than the report templates', and using a different placeholder syntax: single-brace `{token}` (e.g. `{logo}`, `{header_text}`), not the `{{double-brace}}` convention used in the PDF templates. Don't apply PDF-template assumptions when editing email strings.
+## 7.4 Security considerations
+- **SMTP credentials travel in plaintext inside the request payload.** `authUser`/`authPass` are plain JSON fields on the same object that's only base64-*encoded* (not encrypted) end to end — see [doc 1.3](01-architecture-overview.md#13-entry-points-indexjs). Anyone who can observe the call to this library (or a log of it) can trivially recover the SMTP password. If `isDebugging` logging is ever extended to dump the full `reportData`/`mailConfig` object, credentials would land in `output/LOGS-*.txt` in plaintext.
+- **No enforcement of the caller's `secure` intent** — see 7.2. This is a config-drift risk more than an active vulnerability (the connection still requires TLS via `requireTLS`), but it means the `secure` field is misleading and should either be honored or removed from the API surface.
+- **No hardcoded credentials found** in this module. The only hardcoded value is the fallback sender address `noreply@medicus.ai`, which is not a secret.
+- **Recommendation for anyone hardening this:** if the host application controls both ends, consider moving SMTP credentials to a per-deployment secret/environment variable inside the *host* app rather than passing them through this library's payload on every call — this library has no mechanism for that today, so it would be a host-application-level change, not a change to this package's public API shape necessarily, but worth raising with whoever owns the calling system.

package/docs/08-known-issues-and-technical-debt.md ADDED Viewed

@@ -0,0 +1,41 @@
+# 8. Known Issues & Technical Debt
+Consolidated from all the research behind this documentation set, ranked roughly by how much time/pain each one can cost a new engineer. Each links to the doc section with full detail.
+## Critical — will actively bite you
+1. **`index.js` requires `lib/pdf_generator.min.js`, not `lib/pdf_generator.js`.** The two files have diverged independently since 2021 with no build step connecting them. Editing the readable source file silently does nothing. → [doc 1.4](01-architecture-overview.md#14-critical-fact-the-core-report-renderer-that-actually-runs-is-pdf_generatorminjs-not-pdf_generatorjs)
+2. **SMTP credentials travel as plaintext JSON fields** inside a payload that's only base64-*encoded*, not encrypted. A logged request or an intercepted call leaks the SMTP password outright. → [doc 7.4](07-email-notifications.md#74-security-considerations)
+3. **Client-name → config-file resolution is inconsistent across all five places that do it** (wellbeing generator, corporate generator, sendEmail, sanusx generator, core report which doesn't do it at all). Onboarding a new brand or debugging "why isn't my branding showing" requires checking the exact rule for the specific generator in use. → [doc 2.2](02-configuration-and-whitelabelling.md#22-how-clientclientname-resolves-to-a-config-file--and-why-its-inconsistent)
+4. **`corporate_report_generator.js` lower-cases the client string before building a filename path**, but the actual `config/*.json` files are capitalized. Works today only because of case-insensitive filesystems (Windows/macOS); will silently fall back to `default.json` on Linux. → [doc 2.2](02-configuration-and-whitelabelling.md#22-how-clientclientname-resolves-to-a-config-file--and-why-its-inconsistent)
+5. **`generateFullPdf`'s `showHeaderLogo || true` bug** — the header logo can never be suppressed regardless of what the caller passes. → [doc 4.B](04-report-pipelines.md#4b-wellbeing-report--optional-merged-smartreport)
+## High — will cost real debugging time
+6. **`sanusx_report_generator.js` ignores its `clientName` parameter for branding entirely** — always loads `config/sanusx.json`. Effectively single-brand despite accepting a client argument. → [doc 4.D](04-report-pipelines.md#4d-sanusx-report)
+7. **SanusX RTL support is broken** — no `isRtl` flag is ever computed, the LTR template loads unconditionally, and the RTL template that does exist on disk references asset paths that don't exist under `assets/sanusx/`. → [doc 4.D](04-report-pipelines.md#4d-sanusx-report)
+8. **SanusX's PDF is hard-limited to one page** (`pageRanges: '1'`) — any overflow is silently dropped, not pushed to page 2. → [doc 4.D](04-report-pipelines.md#4d-sanusx-report)
+9. **`lib/big_integral_questionnaire.js` renders 100% hardcoded dummy data**, not real patient answers. Easy to mistake for a real, working feature. → [doc 4.B.1](04-report-pipelines.md#4b1-libbig_integral_questionnairejs--read-this-before-assuming-its-a-real-feature)
+10. **Locale state is a process-global mutable singleton** (`i18n.setLocale(...)` mutates a shared, cached module). Concurrent report-generation calls in the same process can leak one request's language into another's render. The codebase already had to specifically patch around an analogous bug for temp-file paths (`generateFullPdf`'s UUID scheme) but never applied the same fix to locale state. → [doc 6.6](06-internationalization.md#66-gotchas-for-a-new-engineer)
+11. **Older flows (`generateMedicusPDF`, `generateNascoPDF`, `generateSanuxPDF`) write to fixed, shared filenames under `output/`** with no cleanup — concurrent requests can clobber each other's files, and disk usage grows unbounded over time. Only `generateFullPdf` was hardened with per-call UUID temp paths + cleanup. → [doc 1.7](01-architecture-overview.md#17-filetemp-file-handling--an-evolving-pattern-worth-knowing)
+12. **`LocaleService.setLocale()` silently no-ops on an unsupported locale** instead of falling back to English like the underlying package would — the previously active locale on the shared singleton just stays in effect. → [doc 6.5](06-internationalization.md#65-fallback-logic--two-layers-that-disagree)
+13. **`renderDoctorDetails` (wellbeing `data.Profile`) does not HTML-escape answer values** — a real risk if any upstream source of Q&A text isn't already sanitized. → [doc 5.4](05-questions-and-data-model.md#54-security-note-unescaped-answer-text)
+## Medium — worth fixing, lower urgency
+14. **No fallback from a brand template folder to shared `templates/blocks/`** for individual missing blocks — the "extended" wellbeing flow throws `ENOENT` if a client folder is incomplete or missing entirely; only `Mediclinic`, `Pha`, `maisonsante` are supported today. → [doc 2.4](02-configuration-and-whitelabelling.md#24-template-folder-selection--no-blocks-level-fallback)
+15. **Two independent copies of Chart.js** (npm `chart.js`, unused/dead server-side import, vs. bundled `assets/charts.min.js`, actually used client-side inside headless Chrome) can silently drift out of version sync. → [doc 3.4](03-templating-and-rendering.md#34-charts)
+16. **`generatePatientQR`/`generateQrCode` doesn't generate QR codes** — it's a generic "rasterize this HTML string" utility; the caller must pre-render the QR (e.g. as inline SVG) before calling it. Misleading name. → [doc 3.5](03-templating-and-rendering.md#35-qr-codes--two-unrelated-mechanisms)
+17. **Orphaned/dead locale files**: `locales/ar.json` (wrong schema for its directory, not in the configured locales list) and `locales/wellbeing/it-IT.json` (not in the configured locales list). → [doc 6.6](06-internationalization.md#66-gotchas-for-a-new-engineer)
+18. **`ar-AE` is functionally unreachable** in three of the four generators — RTL detection coerces any `"ar"`-containing language straight to `ar-SA`. → [doc 6.4](06-internationalization.md#64-rtl-handling--three-overlapping-mechanisms)
+19. **Auto-write-on-missing-key behavior** (`i18n`'s `updateFiles: true` default) has already silently written malformed entries into `locales/wellbeing/en.json` (bare strings instead of `{message, description}` objects) from a currently-unused lookup path — a landmine if that lookup is ever wired up for real. → [doc 6.5](06-internationalization.md#65-fallback-logic--two-layers-that-disagree)
+20. **Corporate report has a live external CDN dependency at render time** (`page.addScriptTag({ url: 'https://cdn.jsdelivr.net/...' })`) — unlike the other three pipelines, which bundle their own JS/CSS locally. A network outage or CDN change could break corporate-report generation specifically. → [doc 4.C](04-report-pipelines.md#4c-corporate-report)
+21. **Onboarding a new brand's corporate-report cover background requires editing shared CSS by client-name selector** (`.cover-overlay-container.bionext {...}`), bypassing the config-JSON theming model otherwise used everywhere else. → [doc 4.C](04-report-pipelines.md#4c-corporate-report)
+22. **Corporate/SanusX translation strings live in the `locales/wellbeing/` bucket**, not a dedicated namespace, despite neither product being "wellbeing." → [doc 6.1](06-internationalization.md#61-library-and-the-two-independent-configurations)
+23. **`sendNascoEmail` is reused across wellbeing, extended-wellbeing, and SanusX flows** despite its Nasco-specific name — a shared helper with a misleading, client-specific name baked into common infrastructure. → [doc 7.1](07-email-notifications.md#71-module-and-exports)
+24. **Dead code accumulation**: unused `templates/base.html`/`template.html`/`ltr.html`/`no_pages.html`/`empty.html`/`first_page_head.html`; `templates/popup/popup-template.html` (unreferenced anywhere); `templates/sanusx/blocks/tips.html` (unreferenced — a different `tips.html` under `templates/wellbeing/blocks/` is the one actually read); `combinePDFBuffers`/`isEmpty` copy-pasted but unused in `corporate_report_generator.js`; `generateHeaderInfo()`'s output computed but discarded (target selector commented out); `historyData` always an empty array, returned but never populated, across all three non-core generators; dead `chart.js`/`qr-image`/`qrcode` npm imports server-side. None of these are actively harmful, but they add noise when searching the codebase and should be pruned opportunistically.
+25. **`mailConfig.secure` is collected from every caller but never read** by the actual transport — dead parameter, misleading API surface. → [doc 7.2](07-email-notifications.md#72-smtp-transport-configuration--entirely-caller-supplied)
+## Suggested first fixes if you're picking one place to start
+If asked to spend a day improving this codebase's reliability rather than adding features, the highest-leverage fixes are (1) wiring an actual build step (or simply deleting `pdf_generator.js` and renaming `.min.js`) to remove the source/runtime divergence risk, (3)/(4) unifying client-name resolution into one shared helper function used by all five call sites, and (10) scoping locale state per-request instead of relying on a shared singleton.

package/docs/README.md ADDED Viewed

@@ -0,0 +1,22 @@
+# Medicus PDF Generator — Documentation
+This is the full technical documentation for `@medicus.ai/medicus-report-pdf-generator`, a Node.js library that turns JSON health-report data into branded PDF documents (and, for one flow, emails them out).
+**Read this first:** [`08-known-issues-and-technical-debt.md`](08-known-issues-and-technical-debt.md) and the project-root [`HANDOVER.md`](../HANDOVER.md) contain the handful of facts that will save you the most debugging time (in particular: `index.js` runs `lib/pdf_generator.min.js`, not the readable `lib/pdf_generator.js`).
+## Contents
+1. [Architecture Overview](01-architecture-overview.md) — what this package is, module map, entry points, dependencies, data flow.
+2. [Configuration & Whitelabelling](02-configuration-and-whitelabelling.md) — the `config/` system, how a `client` string selects branding/templates, per-generator inconsistencies.
+3. [Templating & Rendering Pipeline](03-templating-and-rendering.md) — how HTML is built from data (no template engine — string replace + jsdom/jQuery), how it becomes a PDF (Puppeteer), charts, QR codes.
+4. [Report Pipelines](04-report-pipelines.md) — the four distinct report generators (Core "Medicus", Wellbeing, Corporate, SanusX): purpose, entry points, data shape, brand support.
+5. [Questions, Answers & the Data Model](05-questions-and-data-model.md) — directly answers "where do questions come from and how are they rendered."
+6. [Internationalization (i18n) & RTL](06-internationalization.md) — locale system, Arabic/RTL handling, gotchas.
+7. [Email Notifications](07-email-notifications.md) — `lib/sendEmail.js`, SMTP config, security notes.
+8. [Known Issues & Technical Debt](08-known-issues-and-technical-debt.md) — consolidated list of bugs, dead code, and risks found while writing this documentation.
+## What this project is NOT
+- It is **not a web server**. There is no HTTP listener, no routes, no session handling anywhere in this repository. It is a plain npm library — `index.js` exports async functions that a **host application** (e.g. a Meteor app, per the README) calls directly in-process, or via the `run.js` child-process wrapper.
+- It has **no authentication or authorization layer**. There are no auth-related dependencies in `package.json` (no JWT, no passport, no session store). Any access control, user identity, or permission checking is entirely the host application's responsibility — this package trusts whatever JSON payload it is handed.
+- It has **no database**. Every function call is stateless: it receives a JSON payload (usually base64-encoded), renders it, and returns a PDF/HTML/base64 string. Nothing is persisted except transient files under `output/` or the OS temp directory.

package/downloadfile.js CHANGED Viewed

@@ -1,7 +1,7 @@
-const puppeteer = require('puppeteer');
-const browserFetcher = puppeteer.createBrowserFetcher({platform: 'win64'});
-const revision = require('puppeteer/package').puppeteer.chromium_revision;
-browserFetcher.download(revision)
-    .then(() => console.log('Done, with revision number: ', revision))
+const puppeteer = require('puppeteer');
+const browserFetcher = puppeteer.createBrowserFetcher({platform: 'win64'});
+const revision = require('puppeteer/package').puppeteer.chromium_revision;
+browserFetcher.download(revision)
+    .then(() => console.log('Done, with revision number: ', revision))
     .catch(error => console.log('Error', error));