@tantainnovative/ndpr-toolkit 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [5.1.0](https://github.com/mr-tanta/ndpr-toolkit/compare/v5.0.1...v5.1.0) (2026-05-28)
+
+Security hygiene for the optional PDF-export peer. No change to the toolkit's own code — peer range + docs only.
+
+### Changed
+
+- **`jspdf` peer range widened: `^3.0.3` → `^3.0.3 || ^4.2.1`.** jspdf ≤ 4.2.0 carries three advisories — `GHSA-67pg-wm7f-q7fj` (High, CVSS 8.7: `addImage` GIF out-of-memory DoS), `GHSA-cjw8-79x6-5cj4` (Medium: `addJS` shared-state cross-user data leakage in concurrent server-side use), and a Critical path-traversal/LFI item. jspdf **4.2.1** clears all of them (`npm audit`: 0 vulnerabilities). The old `^3.0.3` peer pinned consumers to vulnerable 3.x; the widened range lets them install the patched 4.2.1+.
+
+  The toolkit's `exportPDF` only uses core jsPDF text/vector primitives — it never calls `addImage`, `addJS`, or `.html()` — so the toolkit's own PDF path was never a sink for these CVEs. The bump is for consumers who install jspdf and want a clean audit. jspdf stays an **optional** peer (dynamic `import('jspdf')`); consumers who don't export PDFs never install it.
+
+### Docs
+
+- README + `exportPDF` JSDoc now note that PDF export needs **jspdf ≥ 4.2.1**, and that installing it with `--omit=optional` (npm) / `--no-optional` (pnpm) drops jspdf's optional deps (`canvg`, `core-js`, `dompurify`, `html2canvas`) for a dependency-free PDF surface — the toolkit uses none of them.
+
+### Verification
+
+- `npm audit` against `jspdf@4.2.1` — 0 vulnerabilities
+- `pnpm jest --no-coverage`, `pnpm verify:tarball`, `npx tsc --noEmit -p tsconfig.json` — all green
+
+## [5.0.1](https://github.com/mr-tanta/ndpr-toolkit/compare/v5.0.0...v5.0.1) (2026-05-28)
+
+Docs-only patch. No runtime code change.
+
+- README refresh for 5.0: structured-result validator examples (route-handler + client branching), new Internationalization section listing all seven shipped locales (en, yo, ig, ha, pcm, ar, fr) with RTL guidance, `/server` and `/core` import examples switched to `validateConsentStructured`, `cookieAdapter` default documented as 180 days with NDPA Section 26 rationale, and every `raw.githubusercontent.com/.../vN.N.N/...` image URL pinned to the v5.0.0 tag.
+
+The npm page now matches the v5 surface. No code, types, or exports changed — `^5.0.0` consumers do not need to upgrade unless they want the new README on their npm page.
+
 ## [5.0.0](https://github.com/mr-tanta/ndpr-toolkit/compare/v4.1.0...v5.0.0) (2026-05-27)
 
 Closes the deprecation window opened by 4.1.0. Every removal here was already deprecated and dev-warned in 4.1, so if your 4.1.x dev console was clean, your 5.0 upgrade is a one-line bump. Full migration table in [`/docs/guides/migrating-4-1-to-5-0`](https://ndprtoolkit.com.ng/docs/guides/migrating-4-1-to-5-0).

package/README.md

@@ -9,19 +9,19 @@
 [![CI](https://github.com/mr-tanta/ndpr-toolkit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mr-tanta/ndpr-toolkit/actions/workflows/ci.yml)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@tantainnovative/ndpr-toolkit)](https://bundlephobia.com/package/@tantainnovative/ndpr-toolkit)
 
-v3 ships **zero-config presets**, **pluggable storage adapters**, **compound components**, and a **compliance score engine** — eight production-ready modules covering consent, data subject rights, DPIA, breach notification, privacy policies, lawful basis, cross-border transfers, and ROPA.
+v5 ships **zero-config presets**, **pluggable storage adapters**, **compound components**, **structured-error validators**, a **compliance score engine**, and **seven shipped locales** (en, yo, ig, ha, pcm, ar, fr) — eight production-ready modules covering consent, data subject rights, DPIA, breach notification, privacy policies, lawful basis, cross-border transfers, and ROPA.
 
-**[Documentation](https://ndprtoolkit.com.ng)** | **[Live Demos](https://ndprtoolkit.com.ng/ndpr-demos)** | **[npm](https://www.npmjs.com/package/@tantainnovative/ndpr-toolkit)** | **[Blog](https://ndprtoolkit.com.ng/blog)** | **[v3.11.0 Release](https://github.com/mr-tanta/ndpr-toolkit/releases/tag/v3.11.0)**
+**[Documentation](https://ndprtoolkit.com.ng)** | **[Live Demos](https://ndprtoolkit.com.ng/ndpr-demos)** | **[npm](https://www.npmjs.com/package/@tantainnovative/ndpr-toolkit)** | **[Blog](https://ndprtoolkit.com.ng/blog)** | **[v5.0.0 Release](https://github.com/mr-tanta/ndpr-toolkit/releases/tag/v5.0.0)**
 
 [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/mr-tanta/ndpr-toolkit/tree/main/examples/nextjs-app)
 [![Open in CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/github/mr-tanta/ndpr-toolkit/main/examples/nextjs-app)
 
-> **What's new in 3.11.0:** Every component's `Props` interface is now re-exported from the root (consumers can finally wrap toolkit components without copying types). Adapter ecosystem types (`ApiAdapterErrorContext`, `StorageAdapter<T>`, …) and DSR validator types reachable from `/server` + root. 9 new component docs pages cover `NDPRThemeProvider`, `NDPRProvider`, `NDPRDashboard`, `AdaptivePolicyWizard`, `PolicyPage`, the 3 Lite manager variants, and `LegalNotice`.
+> **What's new in 5.0:** Structured-result validators are now the only shape — `validateConsentStructured`, `validateDsrSubmissionStructured`, `formatDSRRequestStructured`, etc. return `{ field, code, message }[]` so consumers can switch on stable, locale-independent codes (`email_invalid_format`, `consent_stale`, …) instead of regex-matching English strings. Uniform `onAdd` / `onUpdate` / `onArchive` callbacks across `LawfulBasisTracker`, `CrossBorderTransferManager`, `ROPAManager`, and `useROPA`. `NDPRDPIA.onResult(result)` replaces `onComplete(answers)` — the callback now receives the full computed `DPIAResult` (risk level, can-proceed verdict, recommendations). Upgrading from 4.1? See the [4.1 → 5.0 migration guide](https://ndprtoolkit.com.ng/docs/guides/migrating-4-1-to-5-0).
 >
-> **3.10.x highlights:** Typed theming via `<NDPRThemeProvider>`, a `/headless` subpath alias of `/hooks`, the production-grade DSR backend reference at `examples/dsr-backend-reference/`, plus the `verify:tarball` CI gate that catches broken exports at PR time. Upgrading from 3.7.x? See the [3.7 → 3.10 upgrade guide](https://ndprtoolkit.com.ng/docs/guides/upgrading-3-7-to-3-10). Full history in the [CHANGELOG](https://github.com/mr-tanta/ndpr-toolkit/blob/main/CHANGELOG.md).
+> **Recent highlights:** Arabic + French locales with RTL-correct CSS (4.1.0). React 17 dropped from peers; `^18 || ^19` is the honest range (4.0.0). 17 components wired through `useNDPRLocale()` for full Yoruba / Igbo / Hausa / Pidgin coverage (3.13.0). Typed theming via `<NDPRThemeProvider>`, `verify:tarball` CI gate that catches broken exports at PR time (3.10.x). Full history in the [CHANGELOG](https://github.com/mr-tanta/ndpr-toolkit/blob/main/CHANGELOG.md).
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/hero.png" alt="NDPA Toolkit — NDPA Compliance Made Beautiful" width="800" />
+  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v5.0.0/public/screenshots/hero.png" alt="NDPA Toolkit — NDPA Compliance Made Beautiful" width="800" />
 </p>
 
 ---
@@ -71,7 +71,7 @@ import { cookieAdapter, apiAdapter, composeAdapters, localStorageAdapter } from
 The full SSR pattern (cookie read server-side → banner hydrates already-resolved, no flash) is in the [Server-Side Storage guide](https://ndprtoolkit.com.ng/docs/guides/server-side-storage).
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/consent-demo.png" alt="Consent Management Demo — interactive consent banner with state inspector" width="800" />
+  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v5.0.0/public/screenshots/consent-demo.png" alt="Consent Management Demo — interactive consent banner with state inspector" width="800" />
   <br />
   <em>Interactive consent demo with configurable position, theme, storage, and real-time state inspector</em>
 </p>
@@ -278,7 +278,8 @@ The recommended entry for backend and serverless contexts. Pure validators, gene
 
 ```ts
 import {
-  validateConsent,
+  validateConsentStructured,
+  validateDsrSubmissionStructured,
   generatePolicyText,
   exportHTML,
   getComplianceScore,
@@ -292,7 +293,7 @@ Build-output guard tests assert this entry never carries a `"use client"` direct
 Adds the `NDPRProvider` React Context on top of `/server`'s pure surface. Use when you want types and validators alongside the provider in the same import.
 
 ```ts
-import { NDPRProvider, validateConsent, getComplianceScore } from '@tantainnovative/ndpr-toolkit/core';
+import { NDPRProvider, validateConsentStructured, getComplianceScore } from '@tantainnovative/ndpr-toolkit/core';
 ```
 
 ### Adapters — pluggable storage
@@ -357,9 +358,44 @@ import { composeAdapters, apiAdapter, localStorageAdapter } from '@tantainnovati
 
 **Cookie (server-readable, for SSR consent gating):**
 ```tsx
-<NDPRConsent adapter={cookieAdapter('ndpr_consent', { expires: 365 })} />
+<NDPRConsent adapter={cookieAdapter('ndpr_consent', { expires: 180 })} />
 ```
 
+`expires` defaults to **180 days** (since 3.10.5). NDPA Section 26 doesn't pin a number, but 6 months is the common practice for non-essential cookies and matches what regulators have published elsewhere — long enough to avoid daily re-prompting, short enough that consent stays meaningful.
+
+---
+
+## Structured-Result Validators
+
+Every validator returns a typed `{ field, code, message }[]` so client and server code can branch on stable, locale-independent codes — not regex-matched English strings.
+
+**Next.js Route Handler:**
+```ts
+import { validateDsrSubmissionStructured } from '@tantainnovative/ndpr-toolkit/server';
+
+export async function POST(req: Request) {
+  const { valid, errors, data } = validateDsrSubmissionStructured(await req.json());
+  if (!valid) {
+    return Response.json({ errors }, { status: 422 });
+    // errors: Array<{ field: 'dataSubject.email', code: 'email_invalid_format', message: '...' }>
+  }
+  // `data` is the narrowed `DsrSubmissionPayload`
+  await dsrStore.create(data);
+  return Response.json({ ok: true }, { status: 201 });
+}
+```
+
+**Client-side branching:**
+```ts
+import { validateConsentStructured } from '@tantainnovative/ndpr-toolkit';
+
+const { valid, errors } = validateConsentStructured(settings);
+const stale = errors.find((e) => e.code === 'consent_stale');
+if (stale) showRefreshBanner();
+```
+
+Each validator's emitted `code` values are documented in its JSDoc (and listed in the [CHANGELOG 5.0 entry](https://github.com/mr-tanta/ndpr-toolkit/blob/main/CHANGELOG.md#500-2026-05-27)). The legacy string-returning shapes (`validateConsent`, `validateDsrSubmission`, `formatDSRRequest`, `validateConsentOptions`) were removed in 5.0 — see the [4.1 → 5.0 migration guide](https://ndprtoolkit.com.ng/docs/guides/migrating-4-1-to-5-0) if you're upgrading.
+
 ---
 
 ## Compliance Score
@@ -448,13 +484,13 @@ Every module has an interactive demo. No signup, no setup — try them instantly
 
 <p align="center">
   <a href="https://ndprtoolkit.com.ng/ndpr-demos">
-    <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/demos-overview.png" alt="8 interactive live demos — zero setup required" width="800" />
+    <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v5.0.0/public/screenshots/demos-overview.png" alt="8 interactive live demos — zero setup required" width="800" />
   </a>
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/dsr-demo.png" alt="Data Subject Rights — 8 rights with request tracking" width="400" />
-  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.11.0/public/screenshots/breach-demo.png" alt="Breach Notification — 72-hour countdown with step-by-step workflow" width="400" />
+  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v5.0.0/public/screenshots/dsr-demo.png" alt="Data Subject Rights — 8 rights with request tracking" width="400" />
+  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v5.0.0/public/screenshots/breach-demo.png" alt="Breach Notification — 72-hour countdown with step-by-step workflow" width="400" />
 </p>
 
 <p align="center">
@@ -491,6 +527,34 @@ Cookie-bridged consent that hydrates without a flash. Each scaffold reads the `n
 
 ---
 
+## Internationalization
+
+Wrap your app in `<NDPRProvider locale={...}>` and every shipped component picks up the translation:
+
+```tsx
+import { NDPRProvider, arabicLocale, frenchLocale } from '@tantainnovative/ndpr-toolkit/core';
+
+<NDPRProvider locale={arabicLocale}>
+  <App />
+</NDPRProvider>
+```
+
+Seven locales ship out of the box:
+
+| Locale | Export | Notes |
+|---|---|---|
+| English | `defaultLocale` | Default |
+| Yoruba | `yorubaLocale` | |
+| Igbo | `igboLocale` | |
+| Hausa | `hausaLocale` | |
+| Nigerian Pidgin | `pidginLocale` | |
+| Arabic | `arabicLocale` | Modern Standard; RTL-aware. Set `dir="rtl"` on a parent and `styles.css` mirrors correctly (logical properties as of 4.1). |
+| French | `frenchLocale` | Francophone West African register; uses GDPR-equivalent French terms where they carry meaning. |
+
+Override individual strings via `mergeLocale(base, partial)`. Component prop overrides (`title`, `description`, etc.) still win over the provider locale — the resolution order is **prop → provider locale → English default**.
+
+---
+
 ## All 8 Modules
 
 | Module | Import path | NDPA reference | Key exports |
@@ -590,7 +654,7 @@ Each component exports its `ClassNames` TypeScript interface for autocomplete. F
 | `/dsr` | DSR components + hook | `react` | No |
 | `/dpia` | DPIA components + hook | `react` | No |
 | `/breach` | Breach components + hook | `react` | No |
-| `/policy` | Policy components + hook | `react`, `jspdf`, `docx` (optional) | No |
+| `/policy` | Policy components + hook | `react`, `jspdf` ≥ 4.2.1, `docx` (both optional) | No |
 | `/lawful-basis` | Lawful basis component + hook | `react` | No |
 | `/lawful-basis/lite` | Read-only `LawfulBasisTrackerLite` — ~65% smaller than `/lawful-basis` | `react` | No |
 | `/cross-border` | Cross-border component + hook | `react` | No |
@@ -602,6 +666,17 @@ Each component exports its `ClassNames` TypeScript interface for autocomplete. F
 
 [^core]: `/core` re-exports the React `NDPRProvider` for backward compatibility. For strictly server-side imports use `/server` — it carries the same pure validators with no React surface.
 
+### PDF / DOCX export peers
+
+`PolicyExporter` (and `exportPDF` / `exportDOCX` from `/policy`) load `jspdf` / `docx` via dynamic `import()` only when you actually export — they're optional peers, so consumers who don't export documents never install them. If you do export to PDF:
+
+```bash
+npm install jspdf@^4.2.1 --omit=optional      # npm
+pnpm add jspdf@^4.2.1 --no-optional           # pnpm
+```
+
+Use **jspdf ≥ 4.2.1** — earlier versions (≤ 4.2.0) carry advisories `GHSA-67pg-wm7f-q7fj` and `GHSA-cjw8-79x6-5cj4`, fixed in 4.2.1. The `--omit=optional` / `--no-optional` flag drops jspdf's own optional deps (`canvg`, `core-js`, `dompurify`, `html2canvas`); the toolkit's PDF export uses only core jsPDF text/vector APIs, so it works without them and you get a leaner, dependency-flag-free install.
+
 ### Bundle size guidance
 
 The toolkit is published with `sideEffects: ["*.css"]`, so a modern bundler (Vite, Next.js / Webpack, esbuild, Bun) will tree-shake unused exports. A few practical rules to keep your bundle small:

package/dist/policy.d.mts

@@ -236,6 +236,11 @@ export declare function exportMarkdown(policy: PrivacyPolicy): string;
 /**
  * Export a PrivacyPolicy to a PDF Blob using jspdf (optional peer dependency).
  *
+ * Requires jspdf >= 4.2.1 (earlier versions carry GHSA-67pg-wm7f-q7fj and
+ * GHSA-cjw8-79x6-5cj4). This function uses only core jsPDF text/vector APIs —
+ * never `addImage`, `addJS`, or `.html()` — so jspdf's optional deps
+ * (canvg, core-js, dompurify, html2canvas) can be omitted (`--omit=optional`).
+ *
  * Features:
  * - Optional cover page with title, organisation, date, version and compliance badge
  * - Optional table of contents page

package/dist/policy.d.ts

@@ -236,6 +236,11 @@ export declare function exportMarkdown(policy: PrivacyPolicy): string;
 /**
  * Export a PrivacyPolicy to a PDF Blob using jspdf (optional peer dependency).
  *
+ * Requires jspdf >= 4.2.1 (earlier versions carry GHSA-67pg-wm7f-q7fj and
+ * GHSA-cjw8-79x6-5cj4). This function uses only core jsPDF text/vector APIs —
+ * never `addImage`, `addJS`, or `.html()` — so jspdf's optional deps
+ * (canvg, core-js, dompurify, html2canvas) can be omitted (`--omit=optional`).
+ *
  * Features:
  * - Optional cover page with title, organisation, date, version and compliance badge
  * - Optional table of contents page

package/dist/server.d.mts

@@ -1134,6 +1134,11 @@ export declare function exportMarkdown(policy: PrivacyPolicy): string;
 /**
  * Export a PrivacyPolicy to a PDF Blob using jspdf (optional peer dependency).
  *
+ * Requires jspdf >= 4.2.1 (earlier versions carry GHSA-67pg-wm7f-q7fj and
+ * GHSA-cjw8-79x6-5cj4). This function uses only core jsPDF text/vector APIs —
+ * never `addImage`, `addJS`, or `.html()` — so jspdf's optional deps
+ * (canvg, core-js, dompurify, html2canvas) can be omitted (`--omit=optional`).
+ *
  * Features:
  * - Optional cover page with title, organisation, date, version and compliance badge
  * - Optional table of contents page

package/dist/server.d.ts

@@ -1134,6 +1134,11 @@ export declare function exportMarkdown(policy: PrivacyPolicy): string;
 /**
  * Export a PrivacyPolicy to a PDF Blob using jspdf (optional peer dependency).
  *
+ * Requires jspdf >= 4.2.1 (earlier versions carry GHSA-67pg-wm7f-q7fj and
+ * GHSA-cjw8-79x6-5cj4). This function uses only core jsPDF text/vector APIs —
+ * never `addImage`, `addJS`, or `.html()` — so jspdf's optional deps
+ * (canvg, core-js, dompurify, html2canvas) can be omitted (`--omit=optional`).
+ *
  * Features:
  * - Optional cover page with title, organisation, date, version and compliance badge
  * - Optional table of contents page

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tantainnovative/ndpr-toolkit",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "private": false,
   "description": "Nigeria Data Protection Toolkit — enterprise-grade compliance components for the Nigeria Data Protection Act (NDPA) 2023",
   "pnpm": {
@@ -303,7 +303,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "docx": ">=8.0.0",
-    "jspdf": "^3.0.3",
+    "jspdf": "^3.0.3 || ^4.2.1",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "tailwind-merge": "^2.6.0"