@tantainnovative/ndpr-toolkit 3.5.1 → 3.6.0

package/CHANGELOG.md

@@ -2,6 +2,131 @@
 
 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.
 
+## [3.6.0](https://github.com/mr-tanta/ndpr-toolkit/compare/v3.5.5...v3.6.0) (2026-05-24)
+
+### Features (developer feedback)
+
+This release lands changes flagged by integrating teams using the toolkit in production. All additions are backward-compatible — 3.5.x consumers can upgrade without changes.
+
+* **`apiAdapter` is now production-ready.** Adds `credentials` (defaults to `'same-origin'`, set `'include'` for cross-origin), dynamic `headers` (function form for runtime CSRF token lookup), `loadMethod`/`saveMethod` overrides (e.g. `PUT` for upsert APIs), `unwrap` (transform `{ data: ... }` envelopes), configurable `retry` with exponential backoff and a `shouldRetry` predicate (default: retry on network errors + 5xx, skip 4xx), and `onError`/`onSuccess` hooks for telemetry. The pre-3.6.0 `console.warn` behavior is preserved when no `onError` is configured.
+* **`NDPRConsent` exposes a `copy` prop.** Override `title` / `description` / `acceptAll` / `rejectAll` / `customize` / `save` strings without dropping to the lower-level `<ConsentBanner>` API.
+* **`NDPRSubjectRights` adds public-form `submitTo` mode.** Public sites can POST to their backend instead of being state-managed by an adapter. Pairs with `submitOptions` (credentials, headers) and `onSubmitError`. The state-managed `adapter` mode is unchanged.
+* **Per-preset subpath entries** for bundle-size-sensitive consumers:
+  - `@tantainnovative/ndpr-toolkit/presets/consent` — just `NDPRConsent` (~4KB vs ~8KB for the full barrel)
+  - `@tantainnovative/ndpr-toolkit/presets/dsr` — just `NDPRSubjectRights`
+  - `@tantainnovative/ndpr-toolkit/presets/policy` — just `NDPRPrivacyPolicy`
+  The full `/presets` barrel is unchanged. These are additive narrower entries.
+
+### Docs
+
+* README install block now shows Bun, npm, and Yarn alongside pnpm.
+
+### Coming next (3.6.1+)
+
+- Recipe pages for ecommerce / newsletter / contact-form / careers / admin DSR patterns
+- Org-specific privacy policy templates (SaaS, ecommerce, school, healthcare, procurement)
+- Continued bundle reduction
+
+## [3.5.5](https://github.com/mr-tanta/ndpr-toolkit/compare/v3.5.4...v3.5.5) (2026-05-24)
+
+### Features (tests + types)
+
+* **Tests:** 8 new tests for the 72-hour NDPC notification deadline (`useBreach.getBreachesRequiringNotification`) — covers 1h / 24h / 48h / 71.5h / expired / sort-by-urgency / already-notified cases. Test suite now at 1134 passing (up from 1126).
+* **CI:** Tests now run with `--coverage` and the report uploads as a workflow artifact on each run. Thresholds re-set as a ratchet (45% branches, 50% functions, 65% lines/statements — at or just below current to catch regressions, raised in follow-up patches).
+* **types:** `DPIAAnswerMap` and `DPIAAnswerValue` exported from `/` and `/hooks`. `DPIAProvider` and `<NDPRDPIA>` props now use these instead of `Record<string, any>`, restoring callsite type-safety on `onComplete`, `initialAnswers`, and `adapter`.
+
+### Bug Fixes (API contract)
+
+* **useDSR:** `submitRequest` previously declared `Omit<DSRRequest, 'id' | 'status' | 'submittedAt' | 'updatedAt' | 'estimatedCompletionDate'>` — but `submittedAt` and `estimatedCompletionDate` don't exist on `DSRRequest`. Corrected to `Omit<DSRRequest, 'id' | 'status' | 'createdAt' | 'updatedAt' | 'dueDate'>` so the type contract matches the implementation.
+* **useDSR:** `getRequestsByStatus` now accepts `DSRStatus | RequestStatus` instead of only the deprecated `RequestStatus`. Callers using the modern `DSRStatus` literals (e.g. `'awaitingVerification'`) no longer get a type error.
+
+## [3.5.4](https://github.com/mr-tanta/ndpr-toolkit/compare/v3.5.3...v3.5.4) (2026-05-23)
+
+### Features (accessibility)
+
+* **useFocusTrap:** New shared hook that captures `document.activeElement` on activation, traps Tab cycling inside the container, optionally handles Escape, and restores focus on deactivation (WCAG 2.4.3). Exported from `/`, `/hooks`. Drops a previously-missing piece — closing `<ConsentBanner>` now correctly returns focus to whatever triggered it.
+* **prefers-reduced-motion:** Stylesheet now neutralises all toolkit animations (slide-in, fade-in, scale-in) and transitions when the user sets `prefers-reduced-motion: reduce` at the OS level (WCAG 2.3.3). Applies to banners, modals, dashboards, and policy previews.
+
+### Bug Fixes (accessibility)
+
+* **ConsentBanner:** Internal focus trap now restores focus on close (was previously leaving focus at `<body>`). Replaced the duplicated trap implementation with the new shared `useFocusTrap` hook.
+* **BreachReportForm:** Icon-only "remove attachment" button now has an accessible label (`aria-label="Remove attachment {filename}"`) and a 44×44 px touch target. SVG marked `aria-hidden`. WCAG 4.1.2 / 2.5.5.
+* **BreachReportForm:** `dataTypes` fieldset is now properly wired to its error message via `aria-invalid` + `aria-describedby="dataTypes-error"`. Required-asterisk now announced via `<span className="sr-only">(required)</span>` (was visual-only). WCAG 1.3.1 / 3.3.2.
+
+## [3.5.3](https://github.com/mr-tanta/ndpr-toolkit/compare/v3.5.2...v3.5.3) (2026-05-23)
+
+### Bug Fixes (developer experience)
+
+* **dsr:** `<DSRRequestForm>` now throws a clear `[ndpr-toolkit] <DSRRequestForm requestTypes={...}> requires an array of RequestType[]` error when the required prop is missing — previously crashed deep in a minified chunk with `Cannot read properties of undefined (reading 'find')`. Points users at the `<NDPRSubjectRights>` preset for defaults.
+* **dsr:** Default form description updated from "NDPA Part IV, Sections 29-36" to "NDPA Part VI" (matching the 3.5.2 citation fixes).
+
+### Features
+
+* **package.json:** `sideEffects: ["*.css"]` is now declared on both root and workspace manifests — bundlers can reliably tree-shake unused subpaths.
+* **package.json:** `engines.node: ">=18.0.0"` declared. Quiets installer warnings on Node 16 setups and matches React 18/19 requirements.
+* **package.json:** `funding` field added (GitHub Sponsors URL).
+* **keywords:** Added high-intent search terms developers actually type — `ndpa-2023`, `nigeria-compliance`, `data-privacy`, `compliance-tools`, `nitda`, `gdpr`, `gdpr-nigeria`, `africa`, `cookie-banner`, `nextjs`. Improves npm search ranking for queries like "react NDPA" and "cookie consent Nigeria".
+* **root exports:** `useComplianceScore` and `useAdaptivePolicyWizard` now re-exported from the root entry. Previously only on `/hooks` — caused silent discoverability gap when users autocompleted from the bare `@tantainnovative/ndpr-toolkit`.
+
+## [3.5.2](https://github.com/mr-tanta/ndpr-toolkit/compare/v3.5.1...v3.5.2) (2026-05-23)
+
+### ⚠️ Legal correctness — please re-review generated artifacts
+
+3.5.2 corrects NDPA 2023 section citations across the toolkit against the gazetted text of the Act. If you embedded any pre-3.5.2 output (privacy policy text, DPIA labels, breach report templates) in a regulatory submission, please regenerate or manually update the citations. See the migration table below.
+
+### Bug Fixes (legal correctness)
+
+* **dsr:** Right citations now follow NDPA Part VI as gazetted — access = Section 34(1)(a)–(b), rectification = Section 34(1)(c), erasure = Section 34(1)(d) + 34(2), restriction = Section 34(1)(e), withdraw consent = Section 35, object = Section 36, automated decisions = Section 37, portability = Section 38. Previously cited Sections 30–36 in a way that did not match the Act.
+* **dpia:** DPIA + NDPC prior-consultation citations corrected from Section 38/39 to **Section 28** (which covers both per Section 28(1) and 28(2)).
+* **cross-border:** Transfer-mechanism citations now follow NDPA Part VIII — adequacy decision = Section 42, SCCs / BCRs = Section 41(1)(a), NDPC-approved instruments = Section 42(5), and all derogations = Section 43(1)(a)–(f). Previously cited Sections 41–45 in a way that did not match the Act.
+* **lawful-basis, breach:** Sensitive personal data citation corrected from Section 27 to **Section 30**.
+* **policy:** Privacy notice provisions now cite Section 27 (provision of information) rather than Section 29 (controller obligations).
+* **country-adequacy:** Removed fabricated NDPC adequacy claims. NDPC has not (as of publication) published a Section 42 adequacy list. The 22 entries previously labelled `recognizedBy: 'NDPC'` are now `recognizedBy: 'self-assessment'` with a clear disclaimer in the module header.
+* **dsr (types):** DSRType union extends with `'withdraw_consent'` to reflect the explicit Section 35 right.
+
+### Features
+
+* **legal-notice:** New `LEGAL_DISCLAIMER_SHORT`, `LEGAL_DISCLAIMER_LONG`, and `legalDisclaimerBlock()` exports (from `/`, `/core`, `/server`), plus a `<LegalNotice>` component. Injected into all generated artifacts (HTML / Markdown / DOCX / PDF policy exports, regulatory breach report output, DPIA report footer, breach form preview).
+* **breach (NDPC report content):** `BreachReport` / `BreachFormSubmission` extended with the fields the NDPC actually requires under Section 40(2)–(3) — `approximateRecordCount`, `dataSubjectCategories`, `likelyConsequences`, `mitigationMeasures`, `dpoContact`, `isPhasedReport`, `supplementsReportId`. `BreachReportForm` now collects them; `RegulatoryReportGenerator` includes them in the printed NDPC report.
+* **core:** `StorageAdapter` is now re-exported from `/core` for ergonomics (the concrete adapters still live in `/adapters`).
+
+### Build / packaging
+
+* **build:** Sourcemaps are no longer published. Pass `NDPR_SOURCEMAPS=1` to emit them for local debugging. Cuts the published tarball by ~3 MB.
+* **build:** `dist/` is no longer tracked in git. CI rebuilds from source on every publish.
+* **packaging:** Workspace `packages/ndpr-toolkit/package.json` exports now match the root manifest (drops accidental `-entry` suffixes that pointed at non-existent files). Workspace tsup config also aligned.
+* **packaging:** README is now synced from the repo root via `prepublishOnly`, with absolute image URLs so npm renders the hero correctly.
+
+### Release pipeline
+
+* **publish workflow:** Now publishes with `--provenance` (sigstore attestation) and checks out the tagged commit (not main HEAD).
+* **repo:** `main` is now branch-protected — PRs + 1 approval + green CI required, no force-push, no deletions.
+
+### Docs
+
+* **README:** Fixed broken code examples — `Consent.Provider` uses `onChange` (not `onSave`); `getComplianceScore` example now includes all 8 required module inputs; `StorageAdapter` re-export documented.
+
+### Migration table — old → new NDPA citation
+
+| Concept | Old (pre-3.5.2) | Correct (3.5.2+) |
+|---|---|---|
+| Right of access | Section 30 | Section 34(1)(a)–(b) |
+| Right to rectification | Section 31 | Section 34(1)(c) |
+| Right to erasure | Section 32 | Section 34(1)(d), Section 34(2) |
+| Right to restrict processing | Section 33 | Section 34(1)(e) |
+| Right to portability | Section 34 | Section 38 |
+| Right to object | Section 35 | Section 36 |
+| Right to automated-decision opt-out | Section 36 | Section 37 |
+| Right to withdraw consent | (missing) | Section 35 |
+| DPIA + prior consultation | Section 38 / 39 | Section 28 |
+| Sensitive personal data | Section 27 | Section 30 |
+| Cross-border adequacy | Section 41 | Section 42 |
+| Cross-border SCCs / BCRs | Section 42 / 43 | Section 41(1)(a) |
+| Cross-border derogations | Section 45(a)–(e) | Section 43(1)(a)–(f) |
+| Right to complain to NDPC | (missing) | Section 46(1) |
+
+> The toolkit produces guidance artifacts only — not legal advice. Verify with your DPO or qualified Nigerian privacy counsel before relying on any output for a regulatory submission.
+
 ## [3.5.1](https://github.com/mr-tanta/ndpr-toolkit/compare/v3.5.0...v3.5.1) (2026-05-03)
 
 

package/README.md

@@ -16,7 +16,7 @@ v3 ships **zero-config presets**, **pluggable storage adapters**, **compound com
 > **What's new in 3.4.0:** components now ship styled defaults via a real stylesheet — Tailwind is no longer required. Add `import "@tantainnovative/ndpr-toolkit/styles";` once in your app entry. Plus a new `/server` subpath for RSC-safe pure-logic imports (validators, generators, scoring) with zero React in the import graph. Backward-compatible at the component API level. Full notes on the [release page](https://github.com/mr-tanta/ndpr-toolkit/releases/tag/v3.4.0).
 
 <p align="center">
-  <img src="public/screenshots/hero.png" alt="NDPA Toolkit — NDPA Compliance Made Beautiful" width="800" />
+  <img src="https://raw.githubusercontent.com/mr-tanta/ndpr-toolkit/v3.5.2/public/screenshots/hero.png" alt="NDPA Toolkit — NDPA Compliance Made Beautiful" width="800" />
 </p>
 
 ---
@@ -65,7 +65,7 @@ import { apiAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
 That's it. NDPA-compliant consent with server-side persistence in under 20 lines.
 
 <p align="center">
-  <img src="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/v3.5.2/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>
@@ -74,14 +74,26 @@ That's it. NDPA-compliant consent with server-side persistence in under 20 lines
 
 ## Install
 
+Pick your package manager:
+
 ```bash
+# pnpm
 pnpm add @tantainnovative/ndpr-toolkit
+
+# Bun
+bun add @tantainnovative/ndpr-toolkit
+
+# npm
+npm install @tantainnovative/ndpr-toolkit
+
+# Yarn
+yarn add @tantainnovative/ndpr-toolkit
 ```
 
 Add the stylesheet import once in your app entry so components render with default styles:
 
 ```ts
-// app/layout.tsx (Next.js App Router) or src/main.tsx (Vite/CRA)
+// app/layout.tsx (Next.js App Router) or src/main.tsx (Vite/CRA/Bun)
 import "@tantainnovative/ndpr-toolkit/styles";
 ```
 
@@ -90,7 +102,11 @@ The stylesheet is opinionated but token-driven — override any `--ndpr-*` CSS c
 Install UI peer dependencies (only needed if you use the higher-level Radix-based components from `/presets`):
 
 ```bash
+# pnpm
 pnpm add @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-label @radix-ui/react-slot lucide-react tailwind-merge clsx class-variance-authority
+
+# Bun
+bun add @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-label @radix-ui/react-slot lucide-react tailwind-merge clsx class-variance-authority
 ```
 
 Or scaffold instantly with the CLI:
@@ -127,7 +143,7 @@ Full control over layout without rebuilding logic.
 ```tsx
 import { Consent } from '@tantainnovative/ndpr-toolkit/consent';
 
-<Consent.Provider options={options} onSave={handleSave}>
+<Consent.Provider options={options} onChange={handleSave}>
   <div className="my-layout">
     <Consent.OptionList />
     <div className="flex gap-2">
@@ -249,7 +265,12 @@ const report = getComplianceScore({
     supportsObjection: false,
     responseTimelineDays: 30,
   },
-  // ... other modules
+  dpia: { conductedForHighRisk: true, documentedRisks: true, mitigationMeasures: true },
+  breach: { hasNotificationProcess: true, notifiesWithin72Hours: true, hasRiskAssessment: true, hasRecordKeeping: true },
+  policy: { hasPrivacyPolicy: true, isPubliclyAccessible: true, lastUpdated: '2026-01-01', coversAllSections: true },
+  lawfulBasis: { documentedForAllProcessing: true, hasLegitimateInterestAssessment: false },
+  crossBorder: { hasTransferMechanisms: true, adequacyAssessed: true, ndpcApprovalObtained: false },
+  ropa: { maintained: true, includesAllProcessing: true, lastReviewed: '2026-01-01' },
 });
 
 console.log(report.score);         // e.g. 74
@@ -306,13 +327,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="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/v3.5.2/public/screenshots/demos-overview.png" alt="8 interactive live demos — zero setup required" width="800" />
   </a>
 </p>
 
 <p align="center">
-  <img src="public/screenshots/dsr-demo.png" alt="Data Subject Rights — 8 rights with request tracking" width="400" />
-  <img src="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/v3.5.2/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.5.2/public/screenshots/breach-demo.png" alt="Breach Notification — 72-hour countdown with step-by-step workflow" width="400" />
 </p>
 
 <p align="center">

package/dist/adapters.d.mts

@@ -1,7 +1,141 @@
-export declare function apiAdapter<T = unknown>(endpoint: string, options?: ApiAdapterOptions): StorageAdapter<T>;
+/**
+ * Production-ready API storage adapter.
+ *
+ * Backward-compatible with the 3.5.x signature — `apiAdapter('/api/x')`
+ * still works exactly as before. New options are all opt-in.
+ *
+ * @example basic
+ *   const adapter = apiAdapter<ConsentSettings>('/api/consent');
+ *
+ * @example with credentials and CSRF
+ *   const adapter = apiAdapter<ConsentSettings>('/api/consent', {
+ *     credentials: 'include',
+ *     headers: () => ({
+ *       'X-CSRF-Token': document.querySelector<HTMLMetaElement>(
+ *         'meta[name="csrf-token"]'
+ *       )?.content ?? '',
+ *     }),
+ *   });
+ *
+ * @example with retry + telemetry
+ *   const adapter = apiAdapter<ConsentSettings>('/api/consent', {
+ *     retry: { attempts: 2, baseDelayMs: 300 },
+ *     onError: (ctx) => Sentry.captureException(ctx.error, { extra: ctx }),
+ *     onSuccess: (ctx) => analytics.track('consent_saved', { method: ctx.method }),
+ *   });
+ *
+ * @example with response unwrap
+ *   const adapter = apiAdapter<ConsentSettings>('/api/consent', {
+ *     // API returns { data: ConsentSettings, ok: true }
+ *     unwrap: (raw) => (raw as { data: ConsentSettings }).data,
+ *   });
+ */
+export declare function apiAdapter<T = unknown>(endpoint: string, options?: ApiAdapterOptions<T>): StorageAdapter<T>;
 
-export declare interface ApiAdapterOptions {
-    headers?: Record<string, string>;
+declare interface ApiAdapterErrorContext<T = unknown> {
+    /** Which adapter operation triggered this — `load`, `save`, or `remove`. */
+    method: ApiAdapterMethod;
+    /** The endpoint URL that failed. */
+    endpoint: string;
+    /** Underlying error (for network failures / parse errors). */
+    error?: unknown;
+    /** Response object, if a response was received. */
+    response?: Response;
+    /** HTTP status code, if available. */
+    status?: number;
+    /** For `save`, the payload that failed to send. */
+    payload?: T;
+    /** Which retry attempt this is (0 = first try). Capped at `retry.attempts`. */
+    attempt: number;
+}
+
+declare type ApiAdapterMethod = 'load' | 'save' | 'remove';
+
+export declare interface ApiAdapterOptions<T = unknown> {
+    /**
+     * Extra HTTP headers to send with every request. Useful for `Authorization`,
+     * `X-CSRF-Token`, `X-Requested-With`, etc.
+     *
+     * Can also be a function that returns headers, which lets you read a CSRF
+     * token from the DOM/cookie at request time rather than at adapter
+     * construction time.
+     */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Forwarded to fetch's `credentials` option. Defaults to `'same-origin'`
+     * (the browser default). Set to `'include'` for cross-origin endpoints
+     * that need cookies / auth.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * HTTP method override for the load operation. Defaults to `'GET'`.
+     */
+    loadMethod?: 'GET' | 'POST';
+    /**
+     * HTTP method override for the save operation. Defaults to `'POST'`. Some
+     * REST APIs prefer `'PUT'` for upsert semantics.
+     */
+    saveMethod?: 'POST' | 'PUT' | 'PATCH';
+    /**
+     * Transform the raw JSON response into the expected `T`. Useful for APIs
+     * that wrap responses in `{ data: ... }` or similar envelopes. Called
+     * after `res.json()`. If omitted, the parsed JSON is used as-is.
+     */
+    unwrap?: (raw: unknown) => T | null;
+    /**
+     * Retry policy for failed requests. Defaults to no retries (preserves the
+     * pre-3.6.0 behaviour). When configured, applies to all three operations.
+     */
+    retry?: ApiAdapterRetryConfig;
+    /**
+     * Called when a request fails (after all retries exhausted). The adapter
+     * still returns a graceful null/void result so the consuming hook
+     * doesn't crash — this hook is for telemetry, toasts, or audit logging.
+     */
+    onError?: (ctx: ApiAdapterErrorContext<T>) => void;
+    /**
+     * Called when a request succeeds. Useful for cache invalidation,
+     * analytics, or syncing other state.
+     */
+    onSuccess?: (ctx: ApiAdapterSuccessContext<T>) => void;
+    /**
+     * Per-request fetch options to merge into every request. Use this for
+     * things `fetch` itself supports that aren't directly modelled above —
+     * `signal`, `mode`, `cache`, `redirect`, etc.
+     */
+    fetchInit?: Omit<RequestInit, 'method' | 'headers' | 'body' | 'credentials'>;
+}
+
+declare interface ApiAdapterRetryConfig {
+    /**
+     * Number of additional attempts after the initial request. Defaults to 0
+     * (no retries). e.g. `attempts: 2` means up to 3 total requests.
+     */
+    attempts?: number;
+    /**
+     * Base delay in ms between attempts. Defaults to 250ms. The actual delay
+     * uses exponential backoff: `baseDelayMs * 2^attempt`.
+     */
+    baseDelayMs?: number;
+    /**
+     * Predicate that decides whether to retry given the failure context. By
+     * default we retry on network errors and 5xx responses, but not on 4xx
+     * (those are client errors that won't fix themselves).
+     */
+    shouldRetry?: (ctx: ApiAdapterErrorContext<unknown>) => boolean;
+}
+
+declare interface ApiAdapterSuccessContext<T = unknown> {
+    /** Which adapter operation succeeded — `load`, `save`, or `remove`. */
+    method: ApiAdapterMethod;
+    /** The endpoint URL. */
+    endpoint: string;
+    /** Response object. */
+    response: Response;
+    /** For `load` operations, the parsed (and optionally unwrapped) data. */
+    data?: T;
+    /** For `save` operations, the payload that was sent. */
+    payload?: T;
 }
 
 export declare function composeAdapters<T = unknown>(primary: StorageAdapter<T>, ...secondaries: StorageAdapter<T>[]): StorageAdapter<T>;

package/dist/adapters.d.ts

@@ -1,7 +1,141 @@
-export declare function apiAdapter<T = unknown>(endpoint: string, options?: ApiAdapterOptions): StorageAdapter<T>;
+/**
+ * Production-ready API storage adapter.
+ *
+ * Backward-compatible with the 3.5.x signature — `apiAdapter('/api/x')`
+ * still works exactly as before. New options are all opt-in.
+ *
+ * @example basic
+ *   const adapter = apiAdapter<ConsentSettings>('/api/consent');
+ *
+ * @example with credentials and CSRF
+ *   const adapter = apiAdapter<ConsentSettings>('/api/consent', {
+ *     credentials: 'include',
+ *     headers: () => ({
+ *       'X-CSRF-Token': document.querySelector<HTMLMetaElement>(
+ *         'meta[name="csrf-token"]'
+ *       )?.content ?? '',
+ *     }),
+ *   });
+ *
+ * @example with retry + telemetry
+ *   const adapter = apiAdapter<ConsentSettings>('/api/consent', {
+ *     retry: { attempts: 2, baseDelayMs: 300 },
+ *     onError: (ctx) => Sentry.captureException(ctx.error, { extra: ctx }),
+ *     onSuccess: (ctx) => analytics.track('consent_saved', { method: ctx.method }),
+ *   });
+ *
+ * @example with response unwrap
+ *   const adapter = apiAdapter<ConsentSettings>('/api/consent', {
+ *     // API returns { data: ConsentSettings, ok: true }
+ *     unwrap: (raw) => (raw as { data: ConsentSettings }).data,
+ *   });
+ */
+export declare function apiAdapter<T = unknown>(endpoint: string, options?: ApiAdapterOptions<T>): StorageAdapter<T>;
 
-export declare interface ApiAdapterOptions {
-    headers?: Record<string, string>;
+declare interface ApiAdapterErrorContext<T = unknown> {
+    /** Which adapter operation triggered this — `load`, `save`, or `remove`. */
+    method: ApiAdapterMethod;
+    /** The endpoint URL that failed. */
+    endpoint: string;
+    /** Underlying error (for network failures / parse errors). */
+    error?: unknown;
+    /** Response object, if a response was received. */
+    response?: Response;
+    /** HTTP status code, if available. */
+    status?: number;
+    /** For `save`, the payload that failed to send. */
+    payload?: T;
+    /** Which retry attempt this is (0 = first try). Capped at `retry.attempts`. */
+    attempt: number;
+}
+
+declare type ApiAdapterMethod = 'load' | 'save' | 'remove';
+
+export declare interface ApiAdapterOptions<T = unknown> {
+    /**
+     * Extra HTTP headers to send with every request. Useful for `Authorization`,
+     * `X-CSRF-Token`, `X-Requested-With`, etc.
+     *
+     * Can also be a function that returns headers, which lets you read a CSRF
+     * token from the DOM/cookie at request time rather than at adapter
+     * construction time.
+     */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Forwarded to fetch's `credentials` option. Defaults to `'same-origin'`
+     * (the browser default). Set to `'include'` for cross-origin endpoints
+     * that need cookies / auth.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * HTTP method override for the load operation. Defaults to `'GET'`.
+     */
+    loadMethod?: 'GET' | 'POST';
+    /**
+     * HTTP method override for the save operation. Defaults to `'POST'`. Some
+     * REST APIs prefer `'PUT'` for upsert semantics.
+     */
+    saveMethod?: 'POST' | 'PUT' | 'PATCH';
+    /**
+     * Transform the raw JSON response into the expected `T`. Useful for APIs
+     * that wrap responses in `{ data: ... }` or similar envelopes. Called
+     * after `res.json()`. If omitted, the parsed JSON is used as-is.
+     */
+    unwrap?: (raw: unknown) => T | null;
+    /**
+     * Retry policy for failed requests. Defaults to no retries (preserves the
+     * pre-3.6.0 behaviour). When configured, applies to all three operations.
+     */
+    retry?: ApiAdapterRetryConfig;
+    /**
+     * Called when a request fails (after all retries exhausted). The adapter
+     * still returns a graceful null/void result so the consuming hook
+     * doesn't crash — this hook is for telemetry, toasts, or audit logging.
+     */
+    onError?: (ctx: ApiAdapterErrorContext<T>) => void;
+    /**
+     * Called when a request succeeds. Useful for cache invalidation,
+     * analytics, or syncing other state.
+     */
+    onSuccess?: (ctx: ApiAdapterSuccessContext<T>) => void;
+    /**
+     * Per-request fetch options to merge into every request. Use this for
+     * things `fetch` itself supports that aren't directly modelled above —
+     * `signal`, `mode`, `cache`, `redirect`, etc.
+     */
+    fetchInit?: Omit<RequestInit, 'method' | 'headers' | 'body' | 'credentials'>;
+}
+
+declare interface ApiAdapterRetryConfig {
+    /**
+     * Number of additional attempts after the initial request. Defaults to 0
+     * (no retries). e.g. `attempts: 2` means up to 3 total requests.
+     */
+    attempts?: number;
+    /**
+     * Base delay in ms between attempts. Defaults to 250ms. The actual delay
+     * uses exponential backoff: `baseDelayMs * 2^attempt`.
+     */
+    baseDelayMs?: number;
+    /**
+     * Predicate that decides whether to retry given the failure context. By
+     * default we retry on network errors and 5xx responses, but not on 4xx
+     * (those are client errors that won't fix themselves).
+     */
+    shouldRetry?: (ctx: ApiAdapterErrorContext<unknown>) => boolean;
+}
+
+declare interface ApiAdapterSuccessContext<T = unknown> {
+    /** Which adapter operation succeeded — `load`, `save`, or `remove`. */
+    method: ApiAdapterMethod;
+    /** The endpoint URL. */
+    endpoint: string;
+    /** Response object. */
+    response: Response;
+    /** For `load` operations, the parsed (and optionally unwrapped) data. */
+    data?: T;
+    /** For `save` operations, the payload that was sent. */
+    payload?: T;
 }
 
 export declare function composeAdapters<T = unknown>(primary: StorageAdapter<T>, ...secondaries: StorageAdapter<T>[]): StorageAdapter<T>;

package/dist/adapters.js

@@ -1,2 +1 @@
-'use strict';var chunkJBSCER34_js=require('./chunk-JBSCER34.js'),chunkA4PK7JB2_js=require('./chunk-A4PK7JB2.js'),chunkELKB2AFZ_js=require('./chunk-ELKB2AFZ.js');require('./chunk-MQFZHA2D.js');Object.defineProperty(exports,"apiAdapter",{enumerable:true,get:function(){return chunkJBSCER34_js.a}});Object.defineProperty(exports,"composeAdapters",{enumerable:true,get:function(){return chunkJBSCER34_js.c}});Object.defineProperty(exports,"memoryAdapter",{enumerable:true,get:function(){return chunkJBSCER34_js.b}});Object.defineProperty(exports,"cookieAdapter",{enumerable:true,get:function(){return chunkA4PK7JB2_js.b}});Object.defineProperty(exports,"sessionStorageAdapter",{enumerable:true,get:function(){return chunkA4PK7JB2_js.a}});Object.defineProperty(exports,"localStorageAdapter",{enumerable:true,get:function(){return chunkELKB2AFZ_js.a}});//# sourceMappingURL=adapters.js.map
-//# sourceMappingURL=adapters.js.map
+'use strict';var chunkROTLSZMV_js=require('./chunk-ROTLSZMV.js'),chunk7ZZO7GVB_js=require('./chunk-7ZZO7GVB.js'),chunkVWED6UTN_js=require('./chunk-VWED6UTN.js');require('./chunk-RFPLZDIO.js');Object.defineProperty(exports,"apiAdapter",{enumerable:true,get:function(){return chunkROTLSZMV_js.a}});Object.defineProperty(exports,"composeAdapters",{enumerable:true,get:function(){return chunkROTLSZMV_js.c}});Object.defineProperty(exports,"memoryAdapter",{enumerable:true,get:function(){return chunkROTLSZMV_js.b}});Object.defineProperty(exports,"cookieAdapter",{enumerable:true,get:function(){return chunk7ZZO7GVB_js.b}});Object.defineProperty(exports,"sessionStorageAdapter",{enumerable:true,get:function(){return chunk7ZZO7GVB_js.a}});Object.defineProperty(exports,"localStorageAdapter",{enumerable:true,get:function(){return chunkVWED6UTN_js.a}});

package/dist/adapters.mjs

@@ -1,2 +1 @@
-export{a as apiAdapter,c as composeAdapters,b as memoryAdapter}from'./chunk-RY3PGVLZ.mjs';export{b as cookieAdapter,a as sessionStorageAdapter}from'./chunk-R3OYAJI6.mjs';export{a as localStorageAdapter}from'./chunk-6WIP33TW.mjs';import'./chunk-WWT2ZSNU.mjs';//# sourceMappingURL=adapters.mjs.map
-//# sourceMappingURL=adapters.mjs.map
+export{a as apiAdapter,c as composeAdapters,b as memoryAdapter}from'./chunk-PL4XNCQA.mjs';export{b as cookieAdapter,a as sessionStorageAdapter}from'./chunk-UASG46LP.mjs';export{a as localStorageAdapter}from'./chunk-DBZSN4WP.mjs';import'./chunk-ZJYULEER.mjs';

package/dist/breach.d.mts

@@ -67,6 +67,44 @@ export declare interface BreachFormSubmission {
     dataTypes: string[];
     /** Estimated number of affected data subjects */
     estimatedAffectedSubjects?: number;
+    /**
+     * Approximate number of personal data RECORDS concerned. Distinct from
+     * subject count (one subject may have many records). NDPA Section 40(2).
+     */
+    approximateRecordCount?: number;
+    /**
+     * Categories of data subjects affected (e.g. customers, employees, minors).
+     * NDPA Section 40(2).
+     */
+    dataSubjectCategories?: string[];
+    /** Whether sensitive personal data (NDPA Section 30) is involved */
+    involvesSensitiveData?: boolean;
+    /**
+     * Likely consequences of the breach for affected data subjects.
+     * Required content for the NDPC report and Section 40(3) communications.
+     */
+    likelyConsequences?: string;
+    /**
+     * Measures taken or proposed to mitigate adverse effects.
+     * NDPA Section 40(3).
+     */
+    mitigationMeasures?: string;
+    /**
+     * Data Protection Officer contact details (Section 32(3)(c) — DPO is the
+     * named NDPC contact). Falls back to organisation-level DPO if omitted.
+     */
+    dpoContact?: {
+        name: string;
+        email: string;
+        phone?: string;
+    };
+    /**
+     * Whether this is a phased / interim report submitted under Section 40(2)
+     * before complete information is available.
+     */
+    isPhasedReport?: boolean;
+    /** ID of the prior phased report this report supplements, if any. */
+    supplementsReportId?: string;
     /** Current status of the breach */
     status: 'ongoing' | 'contained' | 'resolved';
     /** Initial actions taken to address the breach */
@@ -214,10 +252,51 @@ export declare interface BreachReport {
     affectedSystems: string[];
     /** Types of data involved in the breach */
     dataTypes: string[];
-    /** Whether sensitive personal data is involved (NDPA Section 27) */
+    /** Whether sensitive personal data is involved (NDPA Section 30) */
     involvesSensitiveData?: boolean;
     /** Estimated number of data subjects affected */
     estimatedAffectedSubjects?: number;
+    /**
+     * Approximate number of personal data RECORDS concerned (distinct from subject count).
+     * Required content under NDPA Section 40(1)(a) and Section 40(2).
+     */
+    approximateRecordCount?: number;
+    /**
+     * Categories of data subjects affected (e.g. customers, employees, minors, patients).
+     * Required content under NDPA Section 40(1)(a) and Section 40(2).
+     */
+    dataSubjectCategories?: string[];
+    /**
+     * Likely consequences of the breach for affected data subjects (e.g. identity theft,
+     * financial loss, reputational damage). Reported to the NDPC and, where applicable,
+     * communicated to data subjects under Section 40(3).
+     */
+    likelyConsequences?: string;
+    /**
+     * Measures taken or proposed to mitigate adverse effects of the breach.
+     * Required content for Section 40(3) communications to data subjects.
+     */
+    mitigationMeasures?: string;
+    /**
+     * Whether this is a phased / interim report submitted before full investigation
+     * is complete. The NDPC permits phased reporting where complete information is
+     * not available within 72 hours.
+     */
+    isPhasedReport?: boolean;
+    /**
+     * ID of the prior phased report this report supplements, if any.
+     */
+    supplementsReportId?: string;
+    /**
+     * Data Protection Officer contact details. The DPO is the named contact point
+     * for the NDPC per NDPA Section 32(3)(c). Required content in the regulatory
+     * report (Section 40(2)).
+     */
+    dpoContact?: {
+        name: string;
+        email: string;
+        phone?: string;
+    };
     /** Whether the breach is ongoing or contained */
     status: 'ongoing' | 'contained' | 'resolved';
     /** Initial actions taken to address the breach */