@tantainnovative/ndpr-toolkit 3.13.0 → 4.1.0

package/dist/index.d.mts

@@ -476,16 +476,11 @@ export declare interface BreachReportFormProps {
      */
     title?: string;
     /**
-     * Description text displayed on the form. Canonical name in 3.13+.
-     * Takes precedence over `formDescription` if both are set.
+     * Description text displayed on the form.
+     *
      * @default "Use this form to report a suspected or confirmed data breach in accordance with NDPA Section 40. All fields marked with * are required."
      */
     description?: string;
-    /**
-     * @deprecated Renamed to `description`. Will be removed in 4.0.
-     * If both are set, `description` wins.
-     */
-    formDescription?: string;
     /**
      * Text for the submit button
      * @default "Submit Report"
@@ -1335,16 +1330,40 @@ export declare interface CrossBorderTransferManagerProps {
     transfers: CrossBorderTransfer[];
     /**
      * Callback when a new transfer is added
+     * @deprecated Renamed to `onAdd` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onAddTransfer?: (transfer: Omit<CrossBorderTransfer, 'id' | 'createdAt' | 'updatedAt'>) => void;
     /**
      * Callback when a transfer is updated
+     * @deprecated Renamed to `onUpdate` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onUpdateTransfer?: (id: string, updates: Partial<CrossBorderTransfer>) => void;
     /**
      * Callback when a transfer is removed
+     * @deprecated Renamed to `onArchive` in 4.1 (NDPA prefers soft-delete
+     * over hard delete). The legacy name still fires for backward
+     * compatibility and will be removed in 5.0.
      */
     onRemoveTransfer?: (id: string) => void;
+    /**
+     * Callback when a new transfer is added (uniform 4.1+ name).
+     * Takes precedence over `onAddTransfer` when both are provided.
+     */
+    onAdd?: (transfer: Omit<CrossBorderTransfer, 'id' | 'createdAt' | 'updatedAt'>) => void;
+    /**
+     * Callback when a transfer is updated (uniform 4.1+ name).
+     * Takes precedence over `onUpdateTransfer` when both are provided.
+     */
+    onUpdate?: (id: string, updates: Partial<CrossBorderTransfer>) => void;
+    /**
+     * Callback when a transfer is archived (uniform 4.1+ name). NDPA
+     * preference is soft-delete over hard-delete; consumers should treat
+     * this as an archive signal. Takes precedence over `onRemoveTransfer`
+     * when both are provided.
+     */
+    onArchive?: (id: string) => void;
     /**
      * Compliance summary data
      */
@@ -2224,6 +2243,7 @@ export declare function exportROPAToCSV(ropa: RecordOfProcessingActivities): str
  * 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): {
     formattedRequest: Record<string, unknown>;
@@ -2231,6 +2251,31 @@ export declare function formatDSRRequest(request: DSRRequest): {
     validationErrors: string[];
 };
 
+/**
+ * Structured-result variant of {@link formatDSRRequest}. Same formatting
+ * output, but `validationErrors` is replaced with a typed `errors` array
+ * of `{ field, code, message }`.
+ *
+ * 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>;
+    /** Narrowed input — populated only on `valid: true`. */
+    data?: DSRRequest;
+}
+
 /**
  * Generates a summary of all lawful basis documentation across processing activities.
  *
@@ -2423,16 +2468,37 @@ export declare interface LawfulBasisTrackerProps {
     activities: ProcessingActivity[];
     /**
      * Callback when a new activity is created
+     * @deprecated Renamed to `onAdd` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onAddActivity?: (activity: Omit<ProcessingActivity, 'id' | 'createdAt' | 'updatedAt'>) => void;
     /**
      * Callback when an activity is updated
+     * @deprecated Renamed to `onUpdate` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onUpdateActivity?: (id: string, updates: Partial<ProcessingActivity>) => void;
     /**
      * Callback when an activity is archived
+     * @deprecated Renamed to `onArchive` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onArchiveActivity?: (id: string) => void;
+    /**
+     * Callback when a new activity is created (uniform 4.1+ name).
+     * Takes precedence over `onAddActivity` when both are provided.
+     */
+    onAdd?: (activity: Omit<ProcessingActivity, 'id' | 'createdAt' | 'updatedAt'>) => void;
+    /**
+     * Callback when an activity is updated (uniform 4.1+ name).
+     * Takes precedence over `onUpdateActivity` when both are provided.
+     */
+    onUpdate?: (id: string, updates: Partial<ProcessingActivity>) => void;
+    /**
+     * Callback when an activity is archived (uniform 4.1+ name).
+     * Takes precedence over `onArchiveActivity` when both are provided.
+     */
+    onArchive?: (id: string) => void;
     /**
      * Title displayed on the tracker
      * @default "Lawful Basis Tracker"
@@ -3930,16 +3996,37 @@ export declare interface ROPAManagerProps {
     ropa: RecordOfProcessingActivities;
     /**
      * Callback when a new record is added
+     * @deprecated Renamed to `onAdd` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onAddRecord?: (record: ProcessingRecord) => void;
     /**
      * Callback when a record is updated
+     * @deprecated Renamed to `onUpdate` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onUpdateRecord?: (id: string, updates: Partial<ProcessingRecord>) => void;
     /**
      * Callback when a record is archived
+     * @deprecated Renamed to `onArchive` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onArchiveRecord?: (id: string) => void;
+    /**
+     * Callback when a new record is added (uniform 4.1+ name).
+     * Takes precedence over `onAddRecord` when both are provided.
+     */
+    onAdd?: (record: ProcessingRecord) => void;
+    /**
+     * Callback when a record is updated (uniform 4.1+ name).
+     * Takes precedence over `onUpdateRecord` when both are provided.
+     */
+    onUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
+    /**
+     * Callback when a record is archived (uniform 4.1+ name).
+     * Takes precedence over `onArchiveRecord` when both are provided.
+     */
+    onArchive?: (id: string) => void;
     /**
      * Title displayed on the manager
      * @default "Record of Processing Activities (ROPA)"
@@ -4122,6 +4209,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. */
@@ -4882,9 +4993,18 @@ declare interface UseDSROptions {
      */
     storageKey?: string;
     /**
-     * Whether to use local storage to persist requests
-     * @default true
-     * @deprecated Use adapter instead
+     * Whether to use local storage to persist requests.
+     *
+     * **Changed in 4.0:** the default is now `false`. `useDSR` is the admin
+     * tracker hook and its state contains data subjects' PII; the previous
+     * default (true) stored that PII in the admin's browser localStorage,
+     * which is rarely appropriate. Opt in by passing `useLocalStorage: true`
+     * if you specifically want the old behaviour.
+     *
+     * For production deployments, pass an explicit `adapter` instead.
+     *
+     * @default false (as of 4.0; was `true` in 3.x)
+     * @deprecated Pass an explicit `adapter` instead of toggling this flag.
      */
     useLocalStorage?: boolean;
     /**
@@ -5217,7 +5337,7 @@ declare interface UsePrivacyPolicyReturn {
  * }
  * ```
  */
-export declare function useROPA({ initialData, adapter, onRecordAdd, onRecordUpdate, onRecordArchive, }: UseROPAOptions): UseROPAReturn;
+export declare function useROPA({ initialData, adapter, onRecordAdd, onRecordUpdate, onRecordArchive, onAdd, onUpdate, onArchive, }: UseROPAOptions): UseROPAReturn;
 
 export declare interface UseROPAOptions {
     /**
@@ -5232,16 +5352,37 @@ export declare interface UseROPAOptions {
     adapter?: StorageAdapter<RecordOfProcessingActivities>;
     /**
      * Callback when a record is added
+     * @deprecated Renamed to `onAdd` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onRecordAdd?: (record: ProcessingRecord) => void;
     /**
      * Callback when a record is updated
+     * @deprecated Renamed to `onUpdate` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onRecordUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
     /**
      * Callback when a record is archived
+     * @deprecated Renamed to `onArchive` in 4.1. The legacy name still fires
+     * for backward compatibility and will be removed in 5.0.
      */
     onRecordArchive?: (id: string) => void;
+    /**
+     * Callback when a record is added (uniform 4.1+ name).
+     * Takes precedence over `onRecordAdd` when both are provided.
+     */
+    onAdd?: (record: ProcessingRecord) => void;
+    /**
+     * Callback when a record is updated (uniform 4.1+ name).
+     * Takes precedence over `onRecordUpdate` when both are provided.
+     */
+    onUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
+    /**
+     * Callback when a record is archived (uniform 4.1+ name).
+     * Takes precedence over `onRecordArchive` when both are provided.
+     */
+    onArchive?: (id: string) => void;
 }
 
 export declare interface UseROPAReturn {
@@ -5308,6 +5449,7 @@ 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
+ * @deprecated Use `validateConsentStructured()` for typed `{ field, code, message }[]` errors. The legacy string-returning shape will be removed in 5.0.
  */
 export declare function validateConsent(settings: ConsentSettings): {
     valid: boolean;
@@ -5320,12 +5462,50 @@ export declare function validateConsent(settings: ConsentSettings): {
  * 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[];
 };
 
+/**
+ * Structured-result variant of {@link validateConsentOptions}. Each option
+ * is checked for a non-empty `purpose` (NDPA Section 26). 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 validateConsentOptionsStructured(options: ConsentOption[]): StructuredValidationResult<ConsentOption[]>;
+
+/**
+ * Structured-result variant of {@link validateConsent}. Returns the same
+ * checks as `{ field, code, message }[]` 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 validateConsentStructured(settings: ConsentSettings): StructuredValidationResult<ConsentSettings>;
+
 /**
  * Validate a raw DSR submission payload against the same rules
  * `<DSRRequestForm />` enforces client-side. Designed to be called from a
@@ -5361,6 +5541,8 @@ export declare function validateConsentOptions(options: ConsentOption[]): {
  * ```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;
 
@@ -5381,6 +5563,42 @@ export declare interface ValidateDsrSubmissionOptions {
     allowedRequestTypes?: string[];
 }
 
+/**
+ * Structured-result variant of {@link validateDsrSubmission}. Same rules,
+ * but returns an array of `{ field, code, message }` 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.