@tantainnovative/ndpr-toolkit 4.0.0 → 5.0.0

package/dist/hooks.d.ts

@@ -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 {

package/dist/hooks.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/hooks.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/index.d.mts

@@ -1329,17 +1329,18 @@ export declare interface CrossBorderTransferManagerProps {
      */
     transfers: CrossBorderTransfer[];
     /**
-     * Callback when a new transfer is added
+     * Callback when a new transfer is added.
      */
-    onAddTransfer?: (transfer: Omit<CrossBorderTransfer, 'id' | 'createdAt' | 'updatedAt'>) => void;
+    onAdd?: (transfer: Omit<CrossBorderTransfer, 'id' | 'createdAt' | 'updatedAt'>) => void;
     /**
-     * Callback when a transfer is updated
+     * Callback when a transfer is updated.
      */
-    onUpdateTransfer?: (id: string, updates: Partial<CrossBorderTransfer>) => void;
+    onUpdate?: (id: string, updates: Partial<CrossBorderTransfer>) => void;
     /**
-     * Callback when a transfer is removed
+     * Callback when a transfer is archived. NDPA preference is soft-delete
+     * over hard-delete; consumers should treat this as an archive signal.
      */
-    onRemoveTransfer?: (id: string) => void;
+    onArchive?: (id: string) => void;
     /**
      * Compliance summary data
      */
@@ -2077,7 +2078,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;
@@ -2092,16 +2093,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.
@@ -2216,15 +2207,29 @@ export declare type EffortLevel = 'low' | 'medium' | 'high';
 export declare function exportROPAToCSV(ropa: RecordOfProcessingActivities): string;
 
 /**
- * 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;
+}
 
 /**
  * Generates a summary of all lawful basis documentation across processing activities.
@@ -2417,17 +2422,17 @@ export declare interface LawfulBasisTrackerProps {
      */
     activities: ProcessingActivity[];
     /**
-     * Callback when a new activity is created
+     * Callback when a new activity is created.
      */
-    onAddActivity?: (activity: Omit<ProcessingActivity, 'id' | 'createdAt' | 'updatedAt'>) => void;
+    onAdd?: (activity: Omit<ProcessingActivity, 'id' | 'createdAt' | 'updatedAt'>) => void;
     /**
-     * Callback when an activity is updated
+     * Callback when an activity is updated.
      */
-    onUpdateActivity?: (id: string, updates: Partial<ProcessingActivity>) => void;
+    onUpdate?: (id: string, updates: Partial<ProcessingActivity>) => void;
     /**
-     * Callback when an activity is archived
+     * Callback when an activity is archived.
      */
-    onArchiveActivity?: (id: string) => void;
+    onArchive?: (id: string) => void;
     /**
      * Title displayed on the tracker
      * @default "Lawful Basis Tracker"
@@ -3924,17 +3929,17 @@ export declare interface ROPAManagerProps {
      */
     ropa: RecordOfProcessingActivities;
     /**
-     * Callback when a new record is added
+     * Callback when a new record is added.
      */
-    onAddRecord?: (record: ProcessingRecord) => void;
+    onAdd?: (record: ProcessingRecord) => void;
     /**
-     * Callback when a record is updated
+     * Callback when a record is updated.
      */
-    onUpdateRecord?: (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.
      */
-    onArchiveRecord?: (id: string) => void;
+    onArchive?: (id: string) => void;
     /**
      * Title displayed on the manager
      * @default "Record of Processing Activities (ROPA)"
@@ -4117,6 +4122,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. */
 declare interface TemplateContext {
     /** Organisation details, extended with industry and size. */
@@ -4544,9 +4573,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)
      */
@@ -5221,7 +5251,7 @@ 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 {
     /**
@@ -5235,17 +5265,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 {
@@ -5309,66 +5339,43 @@ export declare interface UseROPAReturn {
 }
 
 /**
- * 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
- */
-export declare function validateConsent(settings: ConsentSettings): {
-    valid: boolean;
-    errors: string[];
-};
-
-/**
- * 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
+ * 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 validateConsentOptions(options: ConsentOption[]): {
-    valid: boolean;
-    errors: string[];
-};
+export declare function validateConsentOptionsStructured(options: ConsentOption[]): StructuredValidationResult<ConsentOption[]>;
 
 /**
- * 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 });
- * ```
  */
-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
@@ -5385,6 +5392,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.