@tantainnovative/ndpr-toolkit 4.1.0 → 5.0.0

package/dist/consent.d.mts

@@ -213,7 +213,7 @@ declare interface ConsentContextValue {
     rejectAll: () => void;
     shouldShowBanner: boolean;
     isValid: boolean;
-    validationErrors: string[];
+    validationErrors: StructuredValidationError[];
     resetConsent: () => void;
     isLoading: boolean;
 }
@@ -548,6 +548,30 @@ export declare interface StorageAdapter<T = unknown> {
     remove(): void | Promise<void>;
 }
 
+/**
+ * Single structured validation error with a stable, locale-independent
+ * `code` consumers can switch on programmatically.
+ */
+export declare interface StructuredValidationError {
+    /** Dot-path of the offending field (e.g. `'timestamp'`, `'dataSubject.email'`, `'options[0].purpose'`). */
+    field: string;
+    /** Stable, snake_case error code — safe to switch on across locales. */
+    code: string;
+    /** Human-readable English message — informational only; do not regex-match. */
+    message: string;
+}
+
+/**
+ * Result of a structured validator. `errors` is an array (one entry per
+ * failed rule). `data` is the narrowed, typed payload, only populated on
+ * `valid: true`.
+ */
+export declare interface StructuredValidationResult<T> {
+    valid: boolean;
+    errors: StructuredValidationError[];
+    data?: T;
+}
+
 /**
  * Hook for managing user consent in compliance with the NDPA.
  *
@@ -632,9 +656,10 @@ declare interface UseConsentReturn {
      */
     isValid: boolean;
     /**
-     * Validation errors (if any)
+     * Validation errors (if any). Each entry is a structured `{ field, code,
+     * message }` so consumers can switch on `code` across locales.
      */
-    validationErrors: string[];
+    validationErrors: StructuredValidationError[];
     /**
      * Reset consent settings (clear from storage)
      */
@@ -646,27 +671,40 @@ declare interface UseConsentReturn {
 }
 
 /**
- * Validates consent settings to ensure they meet NDPA requirements
- * @param settings The consent settings to validate
- * @returns An object containing validation result and any error messages
- * @deprecated Use `validateConsentStructured()` for typed `{ field, code, message }[]` errors. The legacy string-returning shape will be removed in 5.0.
+ * Validates consent options against NDPA Section 26 requirements. Each option
+ * is checked for a non-empty `purpose`. Failing options are reported with
+ * `field: 'options[i].purpose'` so consumers can map errors back to the
+ * originating option index.
+ *
+ * Codes emitted:
+ * - `options_required` — empty / missing options array
+ * - `purpose_required` — single option missing a purpose
  */
-export declare function validateConsent(settings: ConsentSettings): {
-    valid: boolean;
-    errors: string[];
-};
+export declare function validateConsentOptionsStructured(options: ConsentOption[]): StructuredValidationResult<ConsentOption[]>;
 
 /**
- * Validates that consent options meet NDPA Section 26 requirements.
- * Each consent option must specify a purpose for which data will be processed,
- * as consent must be specific and informed per the Nigeria Data Protection Act.
- * @param options The consent options to validate
- * @returns An object containing validation result and any error messages
- * @deprecated Use `validateConsentOptionsStructured()` for typed `{ field, code, message }[]` errors. The legacy string-returning shape will be removed in 5.0.
+ * Validates consent settings against NDPA requirements. Returns structured
+ * `{ field, code, message }[]` errors so consumers can switch on `code`
+ * across locales without regex-matching English strings.
+ *
+ * Codes emitted:
+ * - `consents_required`
+ * - `timestamp_required`
+ * - `timestamp_invalid`
+ * - `version_required`
+ * - `method_required`
+ * - `has_interacted_required`
+ * - `consent_stale`
+ *
+ * @example
+ * ```ts
+ * const { valid, errors, data } = validateConsentStructured(settings);
+ * if (!valid) {
+ *   const stale = errors.find((e) => e.code === 'consent_stale');
+ *   if (stale) showRefreshBanner();
+ * }
+ * ```
  */
-export declare function validateConsentOptions(options: ConsentOption[]): {
-    valid: boolean;
-    errors: string[];
-};
+export declare function validateConsentStructured(settings: ConsentSettings): StructuredValidationResult<ConsentSettings>;
 
 export { }

package/dist/consent.d.ts

@@ -213,7 +213,7 @@ declare interface ConsentContextValue {
     rejectAll: () => void;
     shouldShowBanner: boolean;
     isValid: boolean;
-    validationErrors: string[];
+    validationErrors: StructuredValidationError[];
     resetConsent: () => void;
     isLoading: boolean;
 }
@@ -548,6 +548,30 @@ export declare interface StorageAdapter<T = unknown> {
     remove(): void | Promise<void>;
 }
 
+/**
+ * Single structured validation error with a stable, locale-independent
+ * `code` consumers can switch on programmatically.
+ */
+export declare interface StructuredValidationError {
+    /** Dot-path of the offending field (e.g. `'timestamp'`, `'dataSubject.email'`, `'options[0].purpose'`). */
+    field: string;
+    /** Stable, snake_case error code — safe to switch on across locales. */
+    code: string;
+    /** Human-readable English message — informational only; do not regex-match. */
+    message: string;
+}
+
+/**
+ * Result of a structured validator. `errors` is an array (one entry per
+ * failed rule). `data` is the narrowed, typed payload, only populated on
+ * `valid: true`.
+ */
+export declare interface StructuredValidationResult<T> {
+    valid: boolean;
+    errors: StructuredValidationError[];
+    data?: T;
+}
+
 /**
  * Hook for managing user consent in compliance with the NDPA.
  *
@@ -632,9 +656,10 @@ declare interface UseConsentReturn {
      */
     isValid: boolean;
     /**
-     * Validation errors (if any)
+     * Validation errors (if any). Each entry is a structured `{ field, code,
+     * message }` so consumers can switch on `code` across locales.
      */
-    validationErrors: string[];
+    validationErrors: StructuredValidationError[];
     /**
      * Reset consent settings (clear from storage)
      */
@@ -646,27 +671,40 @@ declare interface UseConsentReturn {
 }
 
 /**
- * Validates consent settings to ensure they meet NDPA requirements
- * @param settings The consent settings to validate
- * @returns An object containing validation result and any error messages
- * @deprecated Use `validateConsentStructured()` for typed `{ field, code, message }[]` errors. The legacy string-returning shape will be removed in 5.0.
+ * Validates consent options against NDPA Section 26 requirements. Each option
+ * is checked for a non-empty `purpose`. Failing options are reported with
+ * `field: 'options[i].purpose'` so consumers can map errors back to the
+ * originating option index.
+ *
+ * Codes emitted:
+ * - `options_required` — empty / missing options array
+ * - `purpose_required` — single option missing a purpose
  */
-export declare function validateConsent(settings: ConsentSettings): {
-    valid: boolean;
-    errors: string[];
-};
+export declare function validateConsentOptionsStructured(options: ConsentOption[]): StructuredValidationResult<ConsentOption[]>;
 
 /**
- * Validates that consent options meet NDPA Section 26 requirements.
- * Each consent option must specify a purpose for which data will be processed,
- * as consent must be specific and informed per the Nigeria Data Protection Act.
- * @param options The consent options to validate
- * @returns An object containing validation result and any error messages
- * @deprecated Use `validateConsentOptionsStructured()` for typed `{ field, code, message }[]` errors. The legacy string-returning shape will be removed in 5.0.
+ * Validates consent settings against NDPA requirements. Returns structured
+ * `{ field, code, message }[]` errors so consumers can switch on `code`
+ * across locales without regex-matching English strings.
+ *
+ * Codes emitted:
+ * - `consents_required`
+ * - `timestamp_required`
+ * - `timestamp_invalid`
+ * - `version_required`
+ * - `method_required`
+ * - `has_interacted_required`
+ * - `consent_stale`
+ *
+ * @example
+ * ```ts
+ * const { valid, errors, data } = validateConsentStructured(settings);
+ * if (!valid) {
+ *   const stale = errors.find((e) => e.code === 'consent_stale');
+ *   if (stale) showRefreshBanner();
+ * }
+ * ```
  */
-export declare function validateConsentOptions(options: ConsentOption[]): {
-    valid: boolean;
-    errors: string[];
-};
+export declare function validateConsentStructured(settings: ConsentSettings): StructuredValidationResult<ConsentSettings>;
 
 export { }

package/dist/consent.js

@@ -1,2 +1,2 @@
 "use client";
-'use strict';var chunkSJDDNB6M_js=require('./chunk-SJDDNB6M.js'),chunk42UJFTII_js=require('./chunk-42UJFTII.js'),chunkZD2W3YU2_js=require('./chunk-ZD2W3YU2.js'),chunk3IA3KDII_js=require('./chunk-3IA3KDII.js'),chunkROOUYQD4_js=require('./chunk-ROOUYQD4.js');require('./chunk-L2VO3MEJ.js'),require('./chunk-C2KEXHRX.js');var chunkD3HHDWBR_js=require('./chunk-D3HHDWBR.js'),chunkAME4HJR4_js=require('./chunk-AME4HJR4.js');require('./chunk-YDKWD6MQ.js'),require('./chunk-TTMGFC6C.js'),require('./chunk-VWED6UTN.js');var chunkRFPLZDIO_js=require('./chunk-RFPLZDIO.js'),react=require('react'),jsxRuntime=require('react/jsx-runtime');var v=react.createContext(null);function p(){let t=react.useContext(v);if(!t)throw new Error("Consent compound components must be wrapped in <Consent.Provider>. Example: <Consent.Provider options={...}><Consent.Banner /></Consent.Provider>");return t}var g=({options:t,adapter:n,version:s,onChange:r,children:c})=>{let C=chunkROOUYQD4_js.a({options:t,adapter:n,version:s,onChange:r}),o=chunkRFPLZDIO_js.b(chunkRFPLZDIO_js.a({},C),{options:t});return jsxRuntime.jsx(v.Provider,{value:o,children:c})};var P=({classNames:t,unstyled:n})=>{let{options:s,settings:r}=p(),[c,C]=react.useState(()=>{let o={};return s.forEach(i=>{var a,_;o[i.id]=(_=(a=r==null?void 0:r.consents[i.id])!=null?a:i.defaultValue)!=null?_:false;}),o});return jsxRuntime.jsx("div",{className:chunkAME4HJR4_js.a("ndpr-consent-banner__options-list",t==null?void 0:t.root,n),"data-ndpr-component":"consent-option-list",children:s.map(o=>jsxRuntime.jsxs("div",{className:chunkAME4HJR4_js.a("ndpr-consent-banner__option",t==null?void 0:t.optionItem,n),children:[jsxRuntime.jsx("input",{id:`consent-${o.id}`,type:"checkbox",checked:c[o.id]||false,onChange:i=>C(a=>chunkRFPLZDIO_js.b(chunkRFPLZDIO_js.a({},a),{[o.id]:i.target.checked})),disabled:o.required,className:chunkAME4HJR4_js.a("ndpr-consent-banner__option-checkbox",t==null?void 0:t.optionCheckbox,n),"aria-label":o.label}),jsxRuntime.jsxs("div",{className:n?"":"ndpr-consent-banner__option-text",children:[jsxRuntime.jsxs("label",{htmlFor:`consent-${o.id}`,className:chunkAME4HJR4_js.a("ndpr-consent-banner__option-label",t==null?void 0:t.optionLabel,n),children:[o.label,o.required&&jsxRuntime.jsx("span",{className:n?"":"ndpr-consent-banner__required-marker",children:" *"})]}),jsxRuntime.jsx("p",{className:chunkAME4HJR4_js.a("ndpr-consent-banner__option-description",t==null?void 0:t.optionDescription,n),children:o.description})]})]},o.id))})};var R=({children:t,className:n,unstyled:s})=>{let{acceptAll:r}=p();return jsxRuntime.jsx("button",{onClick:r,className:chunkAME4HJR4_js.a("ndpr-consent-banner__button ndpr-consent-banner__button--primary",n,s),"data-ndpr-component":"consent-accept-button",children:t!=null?t:"Accept All"})};var S=({children:t,className:n,unstyled:s})=>{let{rejectAll:r}=p();return jsxRuntime.jsx("button",{onClick:r,className:chunkAME4HJR4_js.a("ndpr-consent-banner__button ndpr-consent-banner__button--secondary",n,s),"data-ndpr-component":"consent-reject-button",children:t!=null?t:"Reject All"})};var y=({children:t,className:n,unstyled:s,consents:r})=>{let{updateConsent:c,options:C}=p();return jsxRuntime.jsx("button",{onClick:()=>{if(r)c(r);else {let i={};C.forEach(a=>{i[a.id]=a.required||false;}),c(i);}},className:chunkAME4HJR4_js.a("ndpr-consent-banner__button ndpr-consent-banner__button--primary",n,s),"data-ndpr-component":"consent-save-button",children:t!=null?t:"Save Preferences"})};var I={Provider:g,OptionList:P,AcceptButton:R,RejectButton:S,SaveButton:y,Banner:chunkZD2W3YU2_js.a,Settings:chunk42UJFTII_js.a,Storage:chunkSJDDNB6M_js.a};Object.defineProperty(exports,"ConsentStorage",{enumerable:true,get:function(){return chunkSJDDNB6M_js.a}});Object.defineProperty(exports,"ConsentManager",{enumerable:true,get:function(){return chunk42UJFTII_js.a}});Object.defineProperty(exports,"ConsentBanner",{enumerable:true,get:function(){return chunkZD2W3YU2_js.a}});Object.defineProperty(exports,"appendAuditEntry",{enumerable:true,get:function(){return chunk3IA3KDII_js.c}});Object.defineProperty(exports,"createAuditEntry",{enumerable:true,get:function(){return chunk3IA3KDII_js.a}});Object.defineProperty(exports,"getAuditLog",{enumerable:true,get:function(){return chunk3IA3KDII_js.b}});Object.defineProperty(exports,"useConsent",{enumerable:true,get:function(){return chunkROOUYQD4_js.a}});Object.defineProperty(exports,"validateConsent",{enumerable:true,get:function(){return chunkD3HHDWBR_js.a}});Object.defineProperty(exports,"validateConsentOptions",{enumerable:true,get:function(){return chunkD3HHDWBR_js.c}});Object.defineProperty(exports,"resolveClass",{enumerable:true,get:function(){return chunkAME4HJR4_js.a}});exports.Consent=I;exports.ConsentAcceptButton=R;exports.ConsentOptionList=P;exports.ConsentProvider=g;exports.ConsentRejectButton=S;exports.ConsentSaveButton=y;exports.useConsentCompound=p;
+'use strict';var chunkSJDDNB6M_js=require('./chunk-SJDDNB6M.js'),chunk42UJFTII_js=require('./chunk-42UJFTII.js'),chunkZD2W3YU2_js=require('./chunk-ZD2W3YU2.js'),chunk3IA3KDII_js=require('./chunk-3IA3KDII.js'),chunkQKXGVT2Q_js=require('./chunk-QKXGVT2Q.js');require('./chunk-L2VO3MEJ.js'),require('./chunk-C2KEXHRX.js');var chunkDKLJ5DYN_js=require('./chunk-DKLJ5DYN.js'),chunkAME4HJR4_js=require('./chunk-AME4HJR4.js');require('./chunk-YDKWD6MQ.js'),require('./chunk-TTMGFC6C.js'),require('./chunk-VWED6UTN.js');var chunkRFPLZDIO_js=require('./chunk-RFPLZDIO.js'),react=require('react'),jsxRuntime=require('react/jsx-runtime');var v=react.createContext(null);function p(){let t=react.useContext(v);if(!t)throw new Error("Consent compound components must be wrapped in <Consent.Provider>. Example: <Consent.Provider options={...}><Consent.Banner /></Consent.Provider>");return t}var g=({options:t,adapter:n,version:s,onChange:r,children:c})=>{let d=chunkQKXGVT2Q_js.a({options:t,adapter:n,version:s,onChange:r}),o=chunkRFPLZDIO_js.b(chunkRFPLZDIO_js.a({},d),{options:t});return jsxRuntime.jsx(v.Provider,{value:o,children:c})};var S=({classNames:t,unstyled:n})=>{let{options:s,settings:r}=p(),[c,d]=react.useState(()=>{let o={};return s.forEach(i=>{var a,_;o[i.id]=(_=(a=r==null?void 0:r.consents[i.id])!=null?a:i.defaultValue)!=null?_:false;}),o});return jsxRuntime.jsx("div",{className:chunkAME4HJR4_js.a("ndpr-consent-banner__options-list",t==null?void 0:t.root,n),"data-ndpr-component":"consent-option-list",children:s.map(o=>jsxRuntime.jsxs("div",{className:chunkAME4HJR4_js.a("ndpr-consent-banner__option",t==null?void 0:t.optionItem,n),children:[jsxRuntime.jsx("input",{id:`consent-${o.id}`,type:"checkbox",checked:c[o.id]||false,onChange:i=>d(a=>chunkRFPLZDIO_js.b(chunkRFPLZDIO_js.a({},a),{[o.id]:i.target.checked})),disabled:o.required,className:chunkAME4HJR4_js.a("ndpr-consent-banner__option-checkbox",t==null?void 0:t.optionCheckbox,n),"aria-label":o.label}),jsxRuntime.jsxs("div",{className:n?"":"ndpr-consent-banner__option-text",children:[jsxRuntime.jsxs("label",{htmlFor:`consent-${o.id}`,className:chunkAME4HJR4_js.a("ndpr-consent-banner__option-label",t==null?void 0:t.optionLabel,n),children:[o.label,o.required&&jsxRuntime.jsx("span",{className:n?"":"ndpr-consent-banner__required-marker",children:" *"})]}),jsxRuntime.jsx("p",{className:chunkAME4HJR4_js.a("ndpr-consent-banner__option-description",t==null?void 0:t.optionDescription,n),children:o.description})]})]},o.id))})};var P=({children:t,className:n,unstyled:s})=>{let{acceptAll:r}=p();return jsxRuntime.jsx("button",{onClick:r,className:chunkAME4HJR4_js.a("ndpr-consent-banner__button ndpr-consent-banner__button--primary",n,s),"data-ndpr-component":"consent-accept-button",children:t!=null?t:"Accept All"})};var R=({children:t,className:n,unstyled:s})=>{let{rejectAll:r}=p();return jsxRuntime.jsx("button",{onClick:r,className:chunkAME4HJR4_js.a("ndpr-consent-banner__button ndpr-consent-banner__button--secondary",n,s),"data-ndpr-component":"consent-reject-button",children:t!=null?t:"Reject All"})};var y=({children:t,className:n,unstyled:s,consents:r})=>{let{updateConsent:c,options:d}=p();return jsxRuntime.jsx("button",{onClick:()=>{if(r)c(r);else {let i={};d.forEach(a=>{i[a.id]=a.required||false;}),c(i);}},className:chunkAME4HJR4_js.a("ndpr-consent-banner__button ndpr-consent-banner__button--primary",n,s),"data-ndpr-component":"consent-save-button",children:t!=null?t:"Save Preferences"})};var I={Provider:g,OptionList:S,AcceptButton:P,RejectButton:R,SaveButton:y,Banner:chunkZD2W3YU2_js.a,Settings:chunk42UJFTII_js.a,Storage:chunkSJDDNB6M_js.a};Object.defineProperty(exports,"ConsentStorage",{enumerable:true,get:function(){return chunkSJDDNB6M_js.a}});Object.defineProperty(exports,"ConsentManager",{enumerable:true,get:function(){return chunk42UJFTII_js.a}});Object.defineProperty(exports,"ConsentBanner",{enumerable:true,get:function(){return chunkZD2W3YU2_js.a}});Object.defineProperty(exports,"appendAuditEntry",{enumerable:true,get:function(){return chunk3IA3KDII_js.c}});Object.defineProperty(exports,"createAuditEntry",{enumerable:true,get:function(){return chunk3IA3KDII_js.a}});Object.defineProperty(exports,"getAuditLog",{enumerable:true,get:function(){return chunk3IA3KDII_js.b}});Object.defineProperty(exports,"useConsent",{enumerable:true,get:function(){return chunkQKXGVT2Q_js.a}});Object.defineProperty(exports,"validateConsentOptionsStructured",{enumerable:true,get:function(){return chunkDKLJ5DYN_js.b}});Object.defineProperty(exports,"validateConsentStructured",{enumerable:true,get:function(){return chunkDKLJ5DYN_js.a}});Object.defineProperty(exports,"resolveClass",{enumerable:true,get:function(){return chunkAME4HJR4_js.a}});exports.Consent=I;exports.ConsentAcceptButton=P;exports.ConsentOptionList=S;exports.ConsentProvider=g;exports.ConsentRejectButton=R;exports.ConsentSaveButton=y;exports.useConsentCompound=p;

package/dist/consent.mjs

@@ -1,2 +1,2 @@
 "use client";
-import {a}from'./chunk-XOH4WXOZ.mjs';export{a as ConsentStorage}from'./chunk-XOH4WXOZ.mjs';import {a as a$1}from'./chunk-BPMVJOHH.mjs';export{a as ConsentManager}from'./chunk-BPMVJOHH.mjs';import {a as a$2}from'./chunk-I2ZBMR7F.mjs';export{a as ConsentBanner}from'./chunk-I2ZBMR7F.mjs';export{c as appendAuditEntry,a as createAuditEntry,b as getAuditLog}from'./chunk-V7UFP6QU.mjs';import {a as a$3}from'./chunk-7Z7NURIA.mjs';export{a as useConsent}from'./chunk-7Z7NURIA.mjs';import'./chunk-YTU4FNM2.mjs';import'./chunk-XC3DLYEG.mjs';export{a as validateConsent,c as validateConsentOptions}from'./chunk-NI54X543.mjs';import {a as a$5}from'./chunk-SFGW37LE.mjs';export{a as resolveClass}from'./chunk-SFGW37LE.mjs';import'./chunk-FRQFU44F.mjs';import'./chunk-V5TZJJWU.mjs';import'./chunk-DBZSN4WP.mjs';import {b,a as a$4}from'./chunk-ZJYULEER.mjs';import {createContext,useContext,useState}from'react';import {jsx,jsxs}from'react/jsx-runtime';var v=createContext(null);function p(){let t=useContext(v);if(!t)throw new Error("Consent compound components must be wrapped in <Consent.Provider>. Example: <Consent.Provider options={...}><Consent.Banner /></Consent.Provider>");return t}var g=({options:t,adapter:n,version:s,onChange:r,children:c})=>{let C=a$3({options:t,adapter:n,version:s,onChange:r}),o=b(a$4({},C),{options:t});return jsx(v.Provider,{value:o,children:c})};var P=({classNames:t,unstyled:n})=>{let{options:s,settings:r}=p(),[c,C]=useState(()=>{let o={};return s.forEach(i=>{var a,_;o[i.id]=(_=(a=r==null?void 0:r.consents[i.id])!=null?a:i.defaultValue)!=null?_:false;}),o});return jsx("div",{className:a$5("ndpr-consent-banner__options-list",t==null?void 0:t.root,n),"data-ndpr-component":"consent-option-list",children:s.map(o=>jsxs("div",{className:a$5("ndpr-consent-banner__option",t==null?void 0:t.optionItem,n),children:[jsx("input",{id:`consent-${o.id}`,type:"checkbox",checked:c[o.id]||false,onChange:i=>C(a=>b(a$4({},a),{[o.id]:i.target.checked})),disabled:o.required,className:a$5("ndpr-consent-banner__option-checkbox",t==null?void 0:t.optionCheckbox,n),"aria-label":o.label}),jsxs("div",{className:n?"":"ndpr-consent-banner__option-text",children:[jsxs("label",{htmlFor:`consent-${o.id}`,className:a$5("ndpr-consent-banner__option-label",t==null?void 0:t.optionLabel,n),children:[o.label,o.required&&jsx("span",{className:n?"":"ndpr-consent-banner__required-marker",children:" *"})]}),jsx("p",{className:a$5("ndpr-consent-banner__option-description",t==null?void 0:t.optionDescription,n),children:o.description})]})]},o.id))})};var R=({children:t,className:n,unstyled:s})=>{let{acceptAll:r}=p();return jsx("button",{onClick:r,className:a$5("ndpr-consent-banner__button ndpr-consent-banner__button--primary",n,s),"data-ndpr-component":"consent-accept-button",children:t!=null?t:"Accept All"})};var S=({children:t,className:n,unstyled:s})=>{let{rejectAll:r}=p();return jsx("button",{onClick:r,className:a$5("ndpr-consent-banner__button ndpr-consent-banner__button--secondary",n,s),"data-ndpr-component":"consent-reject-button",children:t!=null?t:"Reject All"})};var y=({children:t,className:n,unstyled:s,consents:r})=>{let{updateConsent:c,options:C}=p();return jsx("button",{onClick:()=>{if(r)c(r);else {let i={};C.forEach(a=>{i[a.id]=a.required||false;}),c(i);}},className:a$5("ndpr-consent-banner__button ndpr-consent-banner__button--primary",n,s),"data-ndpr-component":"consent-save-button",children:t!=null?t:"Save Preferences"})};var I={Provider:g,OptionList:P,AcceptButton:R,RejectButton:S,SaveButton:y,Banner:a$2,Settings:a$1,Storage:a};export{I as Consent,R as ConsentAcceptButton,P as ConsentOptionList,g as ConsentProvider,S as ConsentRejectButton,y as ConsentSaveButton,p as useConsentCompound};
+import {a}from'./chunk-XOH4WXOZ.mjs';export{a as ConsentStorage}from'./chunk-XOH4WXOZ.mjs';import {a as a$1}from'./chunk-BPMVJOHH.mjs';export{a as ConsentManager}from'./chunk-BPMVJOHH.mjs';import {a as a$2}from'./chunk-I2ZBMR7F.mjs';export{a as ConsentBanner}from'./chunk-I2ZBMR7F.mjs';export{c as appendAuditEntry,a as createAuditEntry,b as getAuditLog}from'./chunk-V7UFP6QU.mjs';import {a as a$3}from'./chunk-PQ5IPUJN.mjs';export{a as useConsent}from'./chunk-PQ5IPUJN.mjs';import'./chunk-YTU4FNM2.mjs';import'./chunk-XC3DLYEG.mjs';export{b as validateConsentOptionsStructured,a as validateConsentStructured}from'./chunk-R3ZKV2J7.mjs';import {a as a$5}from'./chunk-SFGW37LE.mjs';export{a as resolveClass}from'./chunk-SFGW37LE.mjs';import'./chunk-FRQFU44F.mjs';import'./chunk-V5TZJJWU.mjs';import'./chunk-DBZSN4WP.mjs';import {b,a as a$4}from'./chunk-ZJYULEER.mjs';import {createContext,useContext,useState}from'react';import {jsx,jsxs}from'react/jsx-runtime';var v=createContext(null);function p(){let t=useContext(v);if(!t)throw new Error("Consent compound components must be wrapped in <Consent.Provider>. Example: <Consent.Provider options={...}><Consent.Banner /></Consent.Provider>");return t}var g=({options:t,adapter:n,version:s,onChange:r,children:c})=>{let d=a$3({options:t,adapter:n,version:s,onChange:r}),o=b(a$4({},d),{options:t});return jsx(v.Provider,{value:o,children:c})};var S=({classNames:t,unstyled:n})=>{let{options:s,settings:r}=p(),[c,d]=useState(()=>{let o={};return s.forEach(i=>{var a,_;o[i.id]=(_=(a=r==null?void 0:r.consents[i.id])!=null?a:i.defaultValue)!=null?_:false;}),o});return jsx("div",{className:a$5("ndpr-consent-banner__options-list",t==null?void 0:t.root,n),"data-ndpr-component":"consent-option-list",children:s.map(o=>jsxs("div",{className:a$5("ndpr-consent-banner__option",t==null?void 0:t.optionItem,n),children:[jsx("input",{id:`consent-${o.id}`,type:"checkbox",checked:c[o.id]||false,onChange:i=>d(a=>b(a$4({},a),{[o.id]:i.target.checked})),disabled:o.required,className:a$5("ndpr-consent-banner__option-checkbox",t==null?void 0:t.optionCheckbox,n),"aria-label":o.label}),jsxs("div",{className:n?"":"ndpr-consent-banner__option-text",children:[jsxs("label",{htmlFor:`consent-${o.id}`,className:a$5("ndpr-consent-banner__option-label",t==null?void 0:t.optionLabel,n),children:[o.label,o.required&&jsx("span",{className:n?"":"ndpr-consent-banner__required-marker",children:" *"})]}),jsx("p",{className:a$5("ndpr-consent-banner__option-description",t==null?void 0:t.optionDescription,n),children:o.description})]})]},o.id))})};var P=({children:t,className:n,unstyled:s})=>{let{acceptAll:r}=p();return jsx("button",{onClick:r,className:a$5("ndpr-consent-banner__button ndpr-consent-banner__button--primary",n,s),"data-ndpr-component":"consent-accept-button",children:t!=null?t:"Accept All"})};var R=({children:t,className:n,unstyled:s})=>{let{rejectAll:r}=p();return jsx("button",{onClick:r,className:a$5("ndpr-consent-banner__button ndpr-consent-banner__button--secondary",n,s),"data-ndpr-component":"consent-reject-button",children:t!=null?t:"Reject All"})};var y=({children:t,className:n,unstyled:s,consents:r})=>{let{updateConsent:c,options:d}=p();return jsx("button",{onClick:()=>{if(r)c(r);else {let i={};d.forEach(a=>{i[a.id]=a.required||false;}),c(i);}},className:a$5("ndpr-consent-banner__button ndpr-consent-banner__button--primary",n,s),"data-ndpr-component":"consent-save-button",children:t!=null?t:"Save Preferences"})};var I={Provider:g,OptionList:S,AcceptButton:P,RejectButton:R,SaveButton:y,Banner:a$2,Settings:a$1,Storage:a};export{I as Consent,P as ConsentAcceptButton,S as ConsentOptionList,g as ConsentProvider,R as ConsentRejectButton,y as ConsentSaveButton,p as useConsentCompound};

package/dist/core.d.mts

@@ -815,7 +815,7 @@ export declare type DSRStatus = 'pending' | 'awaitingVerification' | 'inProgress
 /**
  * Validated DSR submission shape — matches what `<DSRRequestForm onSubmit>`
  * emits client-side. Use this as the typed parameter for your server-side
- * handler after `validateDsrSubmission` returns `valid: true`.
+ * handler after `validateDsrSubmissionStructured` returns `valid: true`.
  */
 export declare interface DsrSubmissionPayload {
     requestType: string;
@@ -830,16 +830,6 @@ export declare interface DsrSubmissionPayload {
     submittedAt: number;
 }
 
-/** Result of validating a raw DSR submission payload. */
-export declare interface DsrSubmissionValidationResult {
-    /** True when the payload conforms to the DSR submission contract. */
-    valid: boolean;
-    /** Field-keyed error messages. Empty when `valid` is true. */
-    errors: Record<string, string>;
-    /** The narrowed, typed payload — only populated when `valid` is true. */
-    data?: DsrSubmissionPayload;
-}
-
 /**
  * Data Subject Rights types aligned with NDPA 2023 Part VI (Sections 34-38)
  * and the related provisions in Part V (Section 27 — information to the data subject)
@@ -936,16 +926,29 @@ export declare function exportROPAToCSV(ropa: RecordOfProcessingActivities): str
 export declare function findUnfilledTokens(rendered: string): string[];
 
 /**
- * Formats a DSR request for display or submission
- * @param request The DSR request to format
- * @returns Formatted request data
- * @deprecated Use `formatDSRRequestStructured()` for typed `{ field, code, message }[]` errors. The legacy string-returning shape will be removed in 5.0.
- */
-export declare function formatDSRRequest(request: DSRRequest): {
+ * Format a DSR request for display or submission. Returns the formatted
+ * payload plus a typed `errors` array of `{ field, code, message }` for any
+ * required fields missing from the source request.
+ *
+ * Codes emitted:
+ * - `request_id_required`
+ * - `request_type_required`
+ * - `request_status_required`
+ * - `created_at_required`
+ * - `subject_name_required`
+ * - `subject_email_required`
+ */
+export declare function formatDSRRequestStructured(request: DSRRequest): FormatDSRRequestStructuredResult;
+
+/** Result of {@link formatDSRRequestStructured}. */
+export declare interface FormatDSRRequestStructuredResult {
+    valid: boolean;
+    errors: StructuredValidationError[];
+    /** Formatted request payload — always populated regardless of `valid`. */
     formattedRequest: Record<string, unknown>;
-    isValid: boolean;
-    validationErrors: string[];
-};
+    /** Narrowed input — populated only on `valid: true`. */
+    data?: DSRRequest;
+}
 
 export declare const frenchLocale: Required<{
     [K in keyof NDPRLocale]: Required<NonNullable<NDPRLocale[K]>>;
@@ -2016,6 +2019,30 @@ export declare interface StorageAdapter<T = unknown> {
     remove(): void | Promise<void>;
 }
 
+/**
+ * Single structured validation error with a stable, locale-independent
+ * `code` consumers can switch on programmatically.
+ */
+export declare interface StructuredValidationError {
+    /** Dot-path of the offending field (e.g. `'timestamp'`, `'dataSubject.email'`, `'options[0].purpose'`). */
+    field: string;
+    /** Stable, snake_case error code — safe to switch on across locales. */
+    code: string;
+    /** Human-readable English message — informational only; do not regex-match. */
+    message: string;
+}
+
+/**
+ * Result of a structured validator. `errors` is an array (one entry per
+ * failed rule). `data` is the narrowed, typed payload, only populated on
+ * `valid: true`.
+ */
+export declare interface StructuredValidationResult<T> {
+    valid: boolean;
+    errors: StructuredValidationError[];
+    data?: T;
+}
+
 /** Full context used to generate an adaptive privacy policy. */
 export declare interface TemplateContext {
     /** Organisation details, extended with industry and size. */
@@ -2155,70 +2182,43 @@ export declare function useNDPRConfig(): NDPRConfig;
 export declare function useNDPRLocale(): typeof defaultLocale;
 
 /**
- * Validates consent settings to ensure they meet NDPA requirements
- * @param settings The consent settings to validate
- * @returns An object containing validation result and any error messages
- * @deprecated Use `validateConsentStructured()` for typed `{ field, code, message }[]` errors. The legacy string-returning shape will be removed in 5.0.
+ * Validates consent options against NDPA Section 26 requirements. Each option
+ * is checked for a non-empty `purpose`. Failing options are reported with
+ * `field: 'options[i].purpose'` so consumers can map errors back to the
+ * originating option index.
+ *
+ * Codes emitted:
+ * - `options_required` — empty / missing options array
+ * - `purpose_required` — single option missing a purpose
  */
-export declare function validateConsent(settings: ConsentSettings): {
-    valid: boolean;
-    errors: string[];
-};
+export declare function validateConsentOptionsStructured(options: ConsentOption[]): StructuredValidationResult<ConsentOption[]>;
 
 /**
- * Validates that consent options meet NDPA Section 26 requirements.
- * Each consent option must specify a purpose for which data will be processed,
- * as consent must be specific and informed per the Nigeria Data Protection Act.
- * @param options The consent options to validate
- * @returns An object containing validation result and any error messages
- * @deprecated Use `validateConsentOptionsStructured()` for typed `{ field, code, message }[]` errors. The legacy string-returning shape will be removed in 5.0.
- */
-export declare function validateConsentOptions(options: ConsentOption[]): {
-    valid: boolean;
-    errors: string[];
-};
-
-/**
- * Validate a raw DSR submission payload against the same rules
- * `<DSRRequestForm />` enforces client-side. Designed to be called from a
- * server-side handler (Next.js Route Handler, NestJS controller, Express
- * middleware, Cloudflare Worker) so client and server stay in sync without
- * the consumer hand-rolling zod / class-validator schemas.
+ * Validates consent settings against NDPA requirements. Returns structured
+ * `{ field, code, message }[]` errors so consumers can switch on `code`
+ * across locales without regex-matching English strings.
  *
- * Defensive — accepts `unknown` and narrows. Safe to call directly on
- * `await request.json()`.
+ * Codes emitted:
+ * - `consents_required`
+ * - `timestamp_required`
+ * - `timestamp_invalid`
+ * - `version_required`
+ * - `method_required`
+ * - `has_interacted_required`
+ * - `consent_stale`
  *
- * @example **Next.js Route Handler**
+ * @example
  * ```ts
- * // app/api/dsr/route.ts
- * import { validateDsrSubmission } from '@tantainnovative/ndpr-toolkit/server';
- *
- * export async function POST(req: Request) {
- *   const { valid, errors, data } = validateDsrSubmission(await req.json());
- *   if (!valid) return Response.json({ errors }, { status: 422 });
- *   // `data` is the typed DsrSubmissionPayload
- *   await dsrStore.create(data);
- *   return Response.json({ ok: true }, { status: 201 });
+ * const { valid, errors, data } = validateConsentStructured(settings);
+ * if (!valid) {
+ *   const stale = errors.find((e) => e.code === 'consent_stale');
+ *   if (stale) showRefreshBanner();
  * }
  * ```
- *
- * @example **Lock to specific request types**
- * ```ts
- * validateDsrSubmission(payload, {
- *   allowedRequestTypes: ['access', 'erasure', 'rectification'],
- * });
- * ```
- *
- * @example **Skip identity verification (e.g. authenticated session)**
- * ```ts
- * validateDsrSubmission(payload, { requireIdentityVerification: false });
- * ```
- *
- * @deprecated Use `validateDsrSubmissionStructured()` for typed `{ field, code, message }[]` errors. The legacy string-returning shape will be removed in 5.0.
  */
-export declare function validateDsrSubmission(payload: unknown, options?: ValidateDsrSubmissionOptions): DsrSubmissionValidationResult;
+export declare function validateConsentStructured(settings: ConsentSettings): StructuredValidationResult<ConsentSettings>;
 
-/** Options for {@link validateDsrSubmission}. */
+/** Options for {@link validateDsrSubmissionStructured}. */
 export declare interface ValidateDsrSubmissionOptions {
     /**
      * Whether the data subject is required to provide an identifier
@@ -2235,6 +2235,48 @@ export declare interface ValidateDsrSubmissionOptions {
     allowedRequestTypes?: string[];
 }
 
+/**
+ * Validate a raw DSR submission payload against the same rules
+ * `<DSRRequestForm />` enforces client-side. Designed to be called from a
+ * server-side handler (Next.js Route Handler, NestJS controller, Express
+ * middleware, Cloudflare Worker) so client and server stay in sync without
+ * the consumer hand-rolling zod / class-validator schemas.
+ *
+ * Defensive — accepts `unknown` and narrows. Safe to call directly on
+ * `await request.json()`. Returns `{ field, code, message }[]` errors so
+ * callers can switch on `code` programmatically across locales.
+ *
+ * Codes emitted:
+ * - `payload_not_object`
+ * - `request_type_required`
+ * - `request_type_not_allowed`
+ * - `data_subject_required`
+ * - `full_name_required`
+ * - `email_required`
+ * - `email_invalid_format`
+ * - `phone_invalid_type`
+ * - `identifier_type_required`
+ * - `identifier_value_required`
+ * - `submitted_at_invalid`
+ * - `additional_info_invalid_type`
+ * - `payload_final_narrowing_failed`
+ *
+ * @example **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 });
+ *   }
+ *   await dsrStore.create(data);
+ *   return Response.json({ ok: true }, { status: 201 });
+ * }
+ * ```
+ */
+export declare function validateDsrSubmissionStructured(payload: unknown, options?: ValidateDsrSubmissionOptions): StructuredValidationResult<DsrSubmissionPayload>;
+
 /**
  * Validates that all required fields are present on a processing activity
  * and that the lawful basis is properly documented.