@tantainnovative/ndpr-toolkit 4.0.0 → 5.0.0

package/dist/dsr.d.mts

@@ -331,7 +331,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;
@@ -346,16 +346,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;
-}
-
 /**
  * DSR tracking and analytics component. Supports compliance with NDPA Part IV,
  * providing summary statistics, deadline tracking, and compliance metrics for data subject requests.
@@ -459,15 +449,29 @@ declare interface DSRTrackerProps {
 export declare type DSRType = 'information' | 'access' | 'rectification' | 'erasure' | 'restriction' | 'portability' | 'objection' | 'automated_decision_making' | 'withdraw_consent';
 
 /**
- * Formats a DSR request for display or submission
- * @param request The DSR request to format
- * @returns Formatted request data
+ * 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 formatDSRRequest(request: DSRRequest): {
+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;
+}
 
 /**
  * Legacy status of a data subject request
@@ -518,6 +522,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.
+ */
+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`.
+ */
+declare interface StructuredValidationResult<T> {
+    valid: boolean;
+    errors: StructuredValidationError[];
+    data?: T;
+}
+
 /**
  * Hook for managing Data Subject Requests in compliance with the NDPA.
  *
@@ -638,6 +666,23 @@ declare interface UseDSRReturn {
     isLoading: boolean;
 }
 
+/** Options for {@link validateDsrSubmissionStructured}. */
+export declare interface ValidateDsrSubmissionOptions {
+    /**
+     * Whether the data subject is required to provide an identifier
+     * (NDPC's recommended verification step). Mirror whatever you set on
+     * the client-side `<DSRRequestForm requireIdentityVerification>`.
+     * @default true
+     */
+    requireIdentityVerification?: boolean;
+    /**
+     * Allowed request types. When provided, the payload's `requestType`
+     * must be one of these — useful for locking the server to a specific
+     * set of supported NDPA Part VI §34-38 (plus §35, §36, §37) data-subject rights.
+     */
+    allowedRequestTypes?: string[];
+}
+
 /**
  * Validate a raw DSR submission payload against the same rules
  * `<DSRRequestForm />` enforces client-side. Designed to be called from a
@@ -646,51 +691,38 @@ declare interface UseDSRReturn {
  * the consumer hand-rolling zod / class-validator schemas.
  *
  * Defensive — accepts `unknown` and narrows. Safe to call directly on
- * `await request.json()`.
+ * `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
- * // app/api/dsr/route.ts
- * import { validateDsrSubmission } from '@tantainnovative/ndpr-toolkit/server';
+ * import { validateDsrSubmissionStructured } 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
+ *   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 });
  * }
  * ```
- *
- * @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 });
- * ```
  */
-export declare function validateDsrSubmission(payload: unknown, options?: ValidateDsrSubmissionOptions): DsrSubmissionValidationResult;
-
-/** Options for {@link validateDsrSubmission}. */
-export declare interface ValidateDsrSubmissionOptions {
-    /**
-     * Whether the data subject is required to provide an identifier
-     * (NDPC's recommended verification step). Mirror whatever you set on
-     * the client-side `<DSRRequestForm requireIdentityVerification>`.
-     * @default true
-     */
-    requireIdentityVerification?: boolean;
-    /**
-     * Allowed request types. When provided, the payload's `requestType`
-     * must be one of these — useful for locking the server to a specific
-     * set of supported NDPA Part VI §34-38 (plus §35, §36, §37) data-subject rights.
-     */
-    allowedRequestTypes?: string[];
-}
+export declare function validateDsrSubmissionStructured(payload: unknown, options?: ValidateDsrSubmissionOptions): StructuredValidationResult<DsrSubmissionPayload>;
 
 export { }

package/dist/dsr.d.ts

@@ -331,7 +331,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;
@@ -346,16 +346,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;
-}
-
 /**
  * DSR tracking and analytics component. Supports compliance with NDPA Part IV,
  * providing summary statistics, deadline tracking, and compliance metrics for data subject requests.
@@ -459,15 +449,29 @@ declare interface DSRTrackerProps {
 export declare type DSRType = 'information' | 'access' | 'rectification' | 'erasure' | 'restriction' | 'portability' | 'objection' | 'automated_decision_making' | 'withdraw_consent';
 
 /**
- * Formats a DSR request for display or submission
- * @param request The DSR request to format
- * @returns Formatted request data
+ * 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 formatDSRRequest(request: DSRRequest): {
+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;
+}
 
 /**
  * Legacy status of a data subject request
@@ -518,6 +522,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.
+ */
+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`.
+ */
+declare interface StructuredValidationResult<T> {
+    valid: boolean;
+    errors: StructuredValidationError[];
+    data?: T;
+}
+
 /**
  * Hook for managing Data Subject Requests in compliance with the NDPA.
  *
@@ -638,6 +666,23 @@ declare interface UseDSRReturn {
     isLoading: boolean;
 }
 
+/** Options for {@link validateDsrSubmissionStructured}. */
+export declare interface ValidateDsrSubmissionOptions {
+    /**
+     * Whether the data subject is required to provide an identifier
+     * (NDPC's recommended verification step). Mirror whatever you set on
+     * the client-side `<DSRRequestForm requireIdentityVerification>`.
+     * @default true
+     */
+    requireIdentityVerification?: boolean;
+    /**
+     * Allowed request types. When provided, the payload's `requestType`
+     * must be one of these — useful for locking the server to a specific
+     * set of supported NDPA Part VI §34-38 (plus §35, §36, §37) data-subject rights.
+     */
+    allowedRequestTypes?: string[];
+}
+
 /**
  * Validate a raw DSR submission payload against the same rules
  * `<DSRRequestForm />` enforces client-side. Designed to be called from a
@@ -646,51 +691,38 @@ declare interface UseDSRReturn {
  * the consumer hand-rolling zod / class-validator schemas.
  *
  * Defensive — accepts `unknown` and narrows. Safe to call directly on
- * `await request.json()`.
+ * `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
- * // app/api/dsr/route.ts
- * import { validateDsrSubmission } from '@tantainnovative/ndpr-toolkit/server';
+ * import { validateDsrSubmissionStructured } 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
+ *   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 });
  * }
  * ```
- *
- * @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 });
- * ```
  */
-export declare function validateDsrSubmission(payload: unknown, options?: ValidateDsrSubmissionOptions): DsrSubmissionValidationResult;
-
-/** Options for {@link validateDsrSubmission}. */
-export declare interface ValidateDsrSubmissionOptions {
-    /**
-     * Whether the data subject is required to provide an identifier
-     * (NDPC's recommended verification step). Mirror whatever you set on
-     * the client-side `<DSRRequestForm requireIdentityVerification>`.
-     * @default true
-     */
-    requireIdentityVerification?: boolean;
-    /**
-     * Allowed request types. When provided, the payload's `requestType`
-     * must be one of these — useful for locking the server to a specific
-     * set of supported NDPA Part VI §34-38 (plus §35, §36, §37) data-subject rights.
-     */
-    allowedRequestTypes?: string[];
-}
+export declare function validateDsrSubmissionStructured(payload: unknown, options?: ValidateDsrSubmissionOptions): StructuredValidationResult<DsrSubmissionPayload>;
 
 export { }

package/dist/dsr.js

@@ -1,2 +1,2 @@
 "use client";
-'use strict';var chunkWMISQDSV_js=require('./chunk-WMISQDSV.js'),chunkUZNWXJ2W_js=require('./chunk-UZNWXJ2W.js');require('./chunk-UXUMYP4L.js');var chunk5F2IAUWJ_js=require('./chunk-5F2IAUWJ.js'),chunkOZHUINWS_js=require('./chunk-OZHUINWS.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 p=react.createContext(null);function P(){let e=react.useContext(p);if(!e)throw new Error("DSR compound components must be wrapped in <DSR.Provider>. Example: <DSR.Provider requestTypes={...}><DSR.Form /></DSR.Provider>");return e}var m=({requestTypes:e,adapter:S,storageKey:D,useLocalStorage:d,onSubmit:u,onUpdate:i,children:n})=>{let f=chunk5F2IAUWJ_js.a({requestTypes:e,adapter:S,storageKey:D,useLocalStorage:d,onSubmit:u,onUpdate:i}),x=chunkRFPLZDIO_js.b(chunkRFPLZDIO_js.a({},f),{requestTypes:e});return jsxRuntime.jsx(p.Provider,{value:x,children:n})};var C={Provider:m,Form:chunkUZNWXJ2W_js.a,Dashboard:chunkWMISQDSV_js.a,Tracker:chunkWMISQDSV_js.b};Object.defineProperty(exports,"DSRDashboard",{enumerable:true,get:function(){return chunkWMISQDSV_js.a}});Object.defineProperty(exports,"DSRTracker",{enumerable:true,get:function(){return chunkWMISQDSV_js.b}});Object.defineProperty(exports,"DSRRequestForm",{enumerable:true,get:function(){return chunkUZNWXJ2W_js.a}});Object.defineProperty(exports,"useDSR",{enumerable:true,get:function(){return chunk5F2IAUWJ_js.a}});Object.defineProperty(exports,"formatDSRRequest",{enumerable:true,get:function(){return chunkOZHUINWS_js.b}});Object.defineProperty(exports,"validateDsrSubmission",{enumerable:true,get:function(){return chunkOZHUINWS_js.a}});exports.DSR=C;exports.DSRProvider=m;exports.useDSRCompound=P;
+'use strict';var chunkASEUTU45_js=require('./chunk-ASEUTU45.js'),chunkUZNWXJ2W_js=require('./chunk-UZNWXJ2W.js');require('./chunk-UXUMYP4L.js');var chunkTVA6D6S4_js=require('./chunk-TVA6D6S4.js'),chunkR2ZZMATR_js=require('./chunk-R2ZZMATR.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 p=react.createContext(null);function P(){let e=react.useContext(p);if(!e)throw new Error("DSR compound components must be wrapped in <DSR.Provider>. Example: <DSR.Provider requestTypes={...}><DSR.Form /></DSR.Provider>");return e}var R=({requestTypes:e,adapter:S,storageKey:D,useLocalStorage:u,onSubmit:d,onUpdate:n,children:i})=>{let f=chunkTVA6D6S4_js.a({requestTypes:e,adapter:S,storageKey:D,useLocalStorage:u,onSubmit:d,onUpdate:n}),x=chunkRFPLZDIO_js.b(chunkRFPLZDIO_js.a({},f),{requestTypes:e});return jsxRuntime.jsx(p.Provider,{value:x,children:i})};var C={Provider:R,Form:chunkUZNWXJ2W_js.a,Dashboard:chunkASEUTU45_js.a,Tracker:chunkASEUTU45_js.b};Object.defineProperty(exports,"DSRDashboard",{enumerable:true,get:function(){return chunkASEUTU45_js.a}});Object.defineProperty(exports,"DSRTracker",{enumerable:true,get:function(){return chunkASEUTU45_js.b}});Object.defineProperty(exports,"DSRRequestForm",{enumerable:true,get:function(){return chunkUZNWXJ2W_js.a}});Object.defineProperty(exports,"useDSR",{enumerable:true,get:function(){return chunkTVA6D6S4_js.a}});Object.defineProperty(exports,"formatDSRRequestStructured",{enumerable:true,get:function(){return chunkR2ZZMATR_js.b}});Object.defineProperty(exports,"validateDsrSubmissionStructured",{enumerable:true,get:function(){return chunkR2ZZMATR_js.a}});exports.DSR=C;exports.DSRProvider=R;exports.useDSRCompound=P;

package/dist/dsr.mjs

@@ -1,2 +1,2 @@
 "use client";
-import {b,a}from'./chunk-NB6SKG76.mjs';export{a as DSRDashboard,b as DSRTracker}from'./chunk-NB6SKG76.mjs';import {a as a$1}from'./chunk-L3FR4PQE.mjs';export{a as DSRRequestForm}from'./chunk-L3FR4PQE.mjs';import'./chunk-EWVK45Z3.mjs';import {a as a$2}from'./chunk-GUERZD4O.mjs';export{a as useDSR}from'./chunk-GUERZD4O.mjs';export{b as formatDSRRequest,a as validateDsrSubmission}from'./chunk-VPNK7OID.mjs';import'./chunk-SFGW37LE.mjs';import'./chunk-FRQFU44F.mjs';import'./chunk-V5TZJJWU.mjs';import'./chunk-DBZSN4WP.mjs';import {b as b$1,a as a$3}from'./chunk-ZJYULEER.mjs';import {createContext,useContext}from'react';import {jsx}from'react/jsx-runtime';var p=createContext(null);function P(){let e=useContext(p);if(!e)throw new Error("DSR compound components must be wrapped in <DSR.Provider>. Example: <DSR.Provider requestTypes={...}><DSR.Form /></DSR.Provider>");return e}var m=({requestTypes:e,adapter:S,storageKey:D,useLocalStorage:d,onSubmit:u,onUpdate:i,children:n})=>{let f=a$2({requestTypes:e,adapter:S,storageKey:D,useLocalStorage:d,onSubmit:u,onUpdate:i}),x=b$1(a$3({},f),{requestTypes:e});return jsx(p.Provider,{value:x,children:n})};var C={Provider:m,Form:a$1,Dashboard:a,Tracker:b};export{C as DSR,m as DSRProvider,P as useDSRCompound};
+import {b,a}from'./chunk-SBSYHCPK.mjs';export{a as DSRDashboard,b as DSRTracker}from'./chunk-SBSYHCPK.mjs';import {a as a$1}from'./chunk-L3FR4PQE.mjs';export{a as DSRRequestForm}from'./chunk-L3FR4PQE.mjs';import'./chunk-EWVK45Z3.mjs';import {a as a$2}from'./chunk-ZSRO4L3C.mjs';export{a as useDSR}from'./chunk-ZSRO4L3C.mjs';export{b as formatDSRRequestStructured,a as validateDsrSubmissionStructured}from'./chunk-RRVML7CU.mjs';import'./chunk-SFGW37LE.mjs';import'./chunk-FRQFU44F.mjs';import'./chunk-V5TZJJWU.mjs';import'./chunk-DBZSN4WP.mjs';import {b as b$1,a as a$3}from'./chunk-ZJYULEER.mjs';import {createContext,useContext}from'react';import {jsx}from'react/jsx-runtime';var p=createContext(null);function P(){let e=useContext(p);if(!e)throw new Error("DSR compound components must be wrapped in <DSR.Provider>. Example: <DSR.Provider requestTypes={...}><DSR.Form /></DSR.Provider>");return e}var R=({requestTypes:e,adapter:S,storageKey:D,useLocalStorage:u,onSubmit:d,onUpdate:n,children:i})=>{let f=a$2({requestTypes:e,adapter:S,storageKey:D,useLocalStorage:u,onSubmit:d,onUpdate:n}),x=b$1(a$3({},f),{requestTypes:e});return jsx(p.Provider,{value:x,children:i})};var C={Provider:R,Form:a$1,Dashboard:a,Tracker:b};export{C as DSR,R as DSRProvider,P as useDSRCompound};

package/dist/headless.d.mts

@@ -1457,6 +1457,19 @@ declare interface StorageAdapter<T = unknown> {
     remove(): void | Promise<void>;
 }
 
+/**
+ * Single structured validation error with a stable, locale-independent
+ * `code` consumers can switch on programmatically.
+ */
+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;
+}
+
 /** Full context used to generate an adaptive privacy policy. */
 declare interface TemplateContext {
     /** Organisation details, extended with industry and size. */
@@ -1832,9 +1845,10 @@ export 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)
      */
@@ -2503,7 +2517,7 @@ export declare interface UsePrivacyPolicyReturn {
  * }
  * ```
  */
-export declare function useROPA({ initialData, adapter, onRecordAdd, onRecordUpdate, onRecordArchive, }: UseROPAOptions): UseROPAReturn;
+export declare function useROPA({ initialData, adapter, onAdd, onUpdate, onArchive, }: UseROPAOptions): UseROPAReturn;
 
 export declare interface UseROPAOptions {
     /**
@@ -2517,17 +2531,17 @@ export declare interface UseROPAOptions {
      */
     adapter?: StorageAdapter<RecordOfProcessingActivities>;
     /**
-     * Callback when a record is added
+     * Callback when a record is added.
      */
-    onRecordAdd?: (record: ProcessingRecord) => void;
+    onAdd?: (record: ProcessingRecord) => void;
     /**
-     * Callback when a record is updated
+     * Callback when a record is updated.
      */
-    onRecordUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
+    onUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
     /**
-     * Callback when a record is archived
+     * Callback when a record is archived.
      */
-    onRecordArchive?: (id: string) => void;
+    onArchive?: (id: string) => void;
 }
 
 export declare interface UseROPAReturn {

package/dist/headless.d.ts

@@ -1457,6 +1457,19 @@ declare interface StorageAdapter<T = unknown> {
     remove(): void | Promise<void>;
 }
 
+/**
+ * Single structured validation error with a stable, locale-independent
+ * `code` consumers can switch on programmatically.
+ */
+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;
+}
+
 /** Full context used to generate an adaptive privacy policy. */
 declare interface TemplateContext {
     /** Organisation details, extended with industry and size. */
@@ -1832,9 +1845,10 @@ export 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)
      */
@@ -2503,7 +2517,7 @@ export declare interface UsePrivacyPolicyReturn {
  * }
  * ```
  */
-export declare function useROPA({ initialData, adapter, onRecordAdd, onRecordUpdate, onRecordArchive, }: UseROPAOptions): UseROPAReturn;
+export declare function useROPA({ initialData, adapter, onAdd, onUpdate, onArchive, }: UseROPAOptions): UseROPAReturn;
 
 export declare interface UseROPAOptions {
     /**
@@ -2517,17 +2531,17 @@ export declare interface UseROPAOptions {
      */
     adapter?: StorageAdapter<RecordOfProcessingActivities>;
     /**
-     * Callback when a record is added
+     * Callback when a record is added.
      */
-    onRecordAdd?: (record: ProcessingRecord) => void;
+    onAdd?: (record: ProcessingRecord) => void;
     /**
-     * Callback when a record is updated
+     * Callback when a record is updated.
      */
-    onRecordUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
+    onUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
     /**
-     * Callback when a record is archived
+     * Callback when a record is archived.
      */
-    onRecordArchive?: (id: string) => void;
+    onArchive?: (id: string) => void;
 }
 
 export declare interface UseROPAReturn {

package/dist/headless.js

@@ -1,2 +1,2 @@
 "use client";
-'use strict';require('./chunk-OZCNFB5C.js');var chunkFC3PTJFL_js=require('./chunk-FC3PTJFL.js'),chunkEHQVTFYO_js=require('./chunk-EHQVTFYO.js'),chunkRC3XFXTJ_js=require('./chunk-RC3XFXTJ.js'),chunkQHW4UKGJ_js=require('./chunk-QHW4UKGJ.js'),chunkIRRUYR6M_js=require('./chunk-IRRUYR6M.js'),chunkHHK5LHEG_js=require('./chunk-HHK5LHEG.js'),chunkO2WEABB3_js=require('./chunk-O2WEABB3.js');require('./chunk-JS7SYL5P.js'),require('./chunk-RDALAH3Y.js'),require('./chunk-3YTAOT5O.js'),require('./chunk-D2ZKDQVL.js'),require('./chunk-6LJHLE6G.js'),require('./chunk-YFBDJ4FH.js'),require('./chunk-WZYCBW2R.js'),require('./chunk-4CVBQC66.js');var chunkHOAC5VUF_js=require('./chunk-HOAC5VUF.js'),chunkL2VO3MEJ_js=require('./chunk-L2VO3MEJ.js');require('./chunk-C2KEXHRX.js'),require('./chunk-B46SJB5V.js');var chunk5F2IAUWJ_js=require('./chunk-5F2IAUWJ.js');require('./chunk-OZHUINWS.js');var chunkJLQT3W3E_js=require('./chunk-JLQT3W3E.js');require('./chunk-TQZWJGJ2.js'),require('./chunk-ZVOIR4QH.js'),require('./chunk-VWED6UTN.js'),require('./chunk-RFPLZDIO.js');Object.defineProperty(exports,"useComplianceScore",{enumerable:true,get:function(){return chunkFC3PTJFL_js.a}});Object.defineProperty(exports,"useBreach",{enumerable:true,get:function(){return chunkEHQVTFYO_js.a}});Object.defineProperty(exports,"useDefaultPrivacyPolicy",{enumerable:true,get:function(){return chunkRC3XFXTJ_js.b}});Object.defineProperty(exports,"usePrivacyPolicy",{enumerable:true,get:function(){return chunkRC3XFXTJ_js.a}});Object.defineProperty(exports,"useAdaptivePolicyWizard",{enumerable:true,get:function(){return chunkQHW4UKGJ_js.a}});Object.defineProperty(exports,"useLawfulBasis",{enumerable:true,get:function(){return chunkIRRUYR6M_js.a}});Object.defineProperty(exports,"useCrossBorderTransfer",{enumerable:true,get:function(){return chunkHHK5LHEG_js.a}});Object.defineProperty(exports,"useROPA",{enumerable:true,get:function(){return chunkO2WEABB3_js.a}});Object.defineProperty(exports,"useConsent",{enumerable:true,get:function(){return chunkHOAC5VUF_js.a}});Object.defineProperty(exports,"useFocusTrap",{enumerable:true,get:function(){return chunkL2VO3MEJ_js.a}});Object.defineProperty(exports,"useDSR",{enumerable:true,get:function(){return chunk5F2IAUWJ_js.a}});Object.defineProperty(exports,"useDPIA",{enumerable:true,get:function(){return chunkJLQT3W3E_js.a}});
+'use strict';require('./chunk-OZCNFB5C.js');var chunkFC3PTJFL_js=require('./chunk-FC3PTJFL.js'),chunkEHQVTFYO_js=require('./chunk-EHQVTFYO.js'),chunkRC3XFXTJ_js=require('./chunk-RC3XFXTJ.js'),chunkQHW4UKGJ_js=require('./chunk-QHW4UKGJ.js'),chunkIRRUYR6M_js=require('./chunk-IRRUYR6M.js'),chunkHHK5LHEG_js=require('./chunk-HHK5LHEG.js'),chunkTLIHFGIJ_js=require('./chunk-TLIHFGIJ.js');require('./chunk-JS7SYL5P.js'),require('./chunk-RDALAH3Y.js'),require('./chunk-3YTAOT5O.js'),require('./chunk-D2ZKDQVL.js'),require('./chunk-6LJHLE6G.js'),require('./chunk-YFBDJ4FH.js'),require('./chunk-WZYCBW2R.js'),require('./chunk-4CVBQC66.js');var chunkQKXGVT2Q_js=require('./chunk-QKXGVT2Q.js'),chunkL2VO3MEJ_js=require('./chunk-L2VO3MEJ.js');require('./chunk-C2KEXHRX.js'),require('./chunk-DKLJ5DYN.js');var chunkTVA6D6S4_js=require('./chunk-TVA6D6S4.js');require('./chunk-R2ZZMATR.js');var chunkJLQT3W3E_js=require('./chunk-JLQT3W3E.js');require('./chunk-TQZWJGJ2.js'),require('./chunk-ZVOIR4QH.js'),require('./chunk-VWED6UTN.js'),require('./chunk-RFPLZDIO.js');Object.defineProperty(exports,"useComplianceScore",{enumerable:true,get:function(){return chunkFC3PTJFL_js.a}});Object.defineProperty(exports,"useBreach",{enumerable:true,get:function(){return chunkEHQVTFYO_js.a}});Object.defineProperty(exports,"useDefaultPrivacyPolicy",{enumerable:true,get:function(){return chunkRC3XFXTJ_js.b}});Object.defineProperty(exports,"usePrivacyPolicy",{enumerable:true,get:function(){return chunkRC3XFXTJ_js.a}});Object.defineProperty(exports,"useAdaptivePolicyWizard",{enumerable:true,get:function(){return chunkQHW4UKGJ_js.a}});Object.defineProperty(exports,"useLawfulBasis",{enumerable:true,get:function(){return chunkIRRUYR6M_js.a}});Object.defineProperty(exports,"useCrossBorderTransfer",{enumerable:true,get:function(){return chunkHHK5LHEG_js.a}});Object.defineProperty(exports,"useROPA",{enumerable:true,get:function(){return chunkTLIHFGIJ_js.a}});Object.defineProperty(exports,"useConsent",{enumerable:true,get:function(){return chunkQKXGVT2Q_js.a}});Object.defineProperty(exports,"useFocusTrap",{enumerable:true,get:function(){return chunkL2VO3MEJ_js.a}});Object.defineProperty(exports,"useDSR",{enumerable:true,get:function(){return chunkTVA6D6S4_js.a}});Object.defineProperty(exports,"useDPIA",{enumerable:true,get:function(){return chunkJLQT3W3E_js.a}});

package/dist/headless.mjs

@@ -1,2 +1,2 @@
 "use client";
-import'./chunk-GQYBS3A7.mjs';export{a as useComplianceScore}from'./chunk-IQO3SIAG.mjs';export{a as useBreach}from'./chunk-RFXGD5NE.mjs';export{b as useDefaultPrivacyPolicy,a as usePrivacyPolicy}from'./chunk-UVXS7KRV.mjs';export{a as useAdaptivePolicyWizard}from'./chunk-KE2FZH2V.mjs';export{a as useLawfulBasis}from'./chunk-B6BRD5SL.mjs';export{a as useCrossBorderTransfer}from'./chunk-KDAZQO3N.mjs';export{a as useROPA}from'./chunk-WKUC65HL.mjs';import'./chunk-IVSNHT24.mjs';import'./chunk-7RBO42IW.mjs';import'./chunk-WTGKZX7J.mjs';import'./chunk-NBQQ2GN3.mjs';import'./chunk-BIJSMSUU.mjs';import'./chunk-7BJXI2HI.mjs';import'./chunk-LWIKDDSU.mjs';import'./chunk-XP5PL6K7.mjs';export{a as useConsent}from'./chunk-IHNAFXDM.mjs';export{a as useFocusTrap}from'./chunk-YTU4FNM2.mjs';import'./chunk-XC3DLYEG.mjs';import'./chunk-PJNKQPQP.mjs';export{a as useDSR}from'./chunk-GUERZD4O.mjs';import'./chunk-VPNK7OID.mjs';export{a as useDPIA}from'./chunk-I3V3ITN7.mjs';import'./chunk-LRRENTT5.mjs';import'./chunk-ITCY2Z66.mjs';import'./chunk-DBZSN4WP.mjs';import'./chunk-ZJYULEER.mjs';
+import'./chunk-GQYBS3A7.mjs';export{a as useComplianceScore}from'./chunk-IQO3SIAG.mjs';export{a as useBreach}from'./chunk-RFXGD5NE.mjs';export{b as useDefaultPrivacyPolicy,a as usePrivacyPolicy}from'./chunk-UVXS7KRV.mjs';export{a as useAdaptivePolicyWizard}from'./chunk-KE2FZH2V.mjs';export{a as useLawfulBasis}from'./chunk-B6BRD5SL.mjs';export{a as useCrossBorderTransfer}from'./chunk-KDAZQO3N.mjs';export{a as useROPA}from'./chunk-FRMVSG4N.mjs';import'./chunk-IVSNHT24.mjs';import'./chunk-7RBO42IW.mjs';import'./chunk-WTGKZX7J.mjs';import'./chunk-NBQQ2GN3.mjs';import'./chunk-BIJSMSUU.mjs';import'./chunk-7BJXI2HI.mjs';import'./chunk-LWIKDDSU.mjs';import'./chunk-XP5PL6K7.mjs';export{a as useConsent}from'./chunk-PQ5IPUJN.mjs';export{a as useFocusTrap}from'./chunk-YTU4FNM2.mjs';import'./chunk-XC3DLYEG.mjs';import'./chunk-R3ZKV2J7.mjs';export{a as useDSR}from'./chunk-ZSRO4L3C.mjs';import'./chunk-RRVML7CU.mjs';export{a as useDPIA}from'./chunk-I3V3ITN7.mjs';import'./chunk-LRRENTT5.mjs';import'./chunk-ITCY2Z66.mjs';import'./chunk-DBZSN4WP.mjs';import'./chunk-ZJYULEER.mjs';

package/dist/hooks.d.mts

@@ -1343,6 +1343,19 @@ declare interface StorageAdapter<T = unknown> {
     remove(): void | Promise<void>;
 }
 
+/**
+ * Single structured validation error with a stable, locale-independent
+ * `code` consumers can switch on programmatically.
+ */
+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;
+}
+
 /** Full context used to generate an adaptive privacy policy. */
 declare interface TemplateContext {
     /** Organisation details, extended with industry and size. */
@@ -1718,9 +1731,10 @@ export 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)
      */
@@ -2389,7 +2403,7 @@ export declare interface UsePrivacyPolicyReturn {
  * }
  * ```
  */
-export declare function useROPA({ initialData, adapter, onRecordAdd, onRecordUpdate, onRecordArchive, }: UseROPAOptions): UseROPAReturn;
+export declare function useROPA({ initialData, adapter, onAdd, onUpdate, onArchive, }: UseROPAOptions): UseROPAReturn;
 
 export declare interface UseROPAOptions {
     /**
@@ -2403,17 +2417,17 @@ export declare interface UseROPAOptions {
      */
     adapter?: StorageAdapter<RecordOfProcessingActivities>;
     /**
-     * Callback when a record is added
+     * Callback when a record is added.
      */
-    onRecordAdd?: (record: ProcessingRecord) => void;
+    onAdd?: (record: ProcessingRecord) => void;
     /**
-     * Callback when a record is updated
+     * Callback when a record is updated.
      */
-    onRecordUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
+    onUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
     /**
-     * Callback when a record is archived
+     * Callback when a record is archived.
      */
-    onRecordArchive?: (id: string) => void;
+    onArchive?: (id: string) => void;
 }
 
 export declare interface UseROPAReturn {