@tantainnovative/ndpr-toolkit 3.10.5 → 3.11.0

package/dist/index.d.ts

@@ -8,6 +8,112 @@ import { RefObject } from 'react';
  */
 export declare type AdequacyStatus = 'adequate' | 'inadequate' | 'pending_review' | 'unknown';
 
+export declare interface ApiAdapterErrorContext<T = unknown> {
+    /** Which adapter operation triggered this — `load`, `save`, or `remove`. */
+    method: ApiAdapterMethod;
+    /** The endpoint URL that failed. */
+    endpoint: string;
+    /** Underlying error (for network failures / parse errors). */
+    error?: unknown;
+    /** Response object, if a response was received. */
+    response?: Response;
+    /** HTTP status code, if available. */
+    status?: number;
+    /** For `save`, the payload that failed to send. */
+    payload?: T;
+    /** Which retry attempt this is (0 = first try). Capped at `retry.attempts`. */
+    attempt: number;
+}
+
+export declare type ApiAdapterMethod = 'load' | 'save' | 'remove';
+
+export declare interface ApiAdapterOptions<T = unknown> {
+    /**
+     * Extra HTTP headers to send with every request. Useful for `Authorization`,
+     * `X-CSRF-Token`, `X-Requested-With`, etc.
+     *
+     * Can also be a function that returns headers, which lets you read a CSRF
+     * token from the DOM/cookie at request time rather than at adapter
+     * construction time.
+     */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Forwarded to fetch's `credentials` option. Defaults to `'same-origin'`
+     * (the browser default). Set to `'include'` for cross-origin endpoints
+     * that need cookies / auth.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * HTTP method override for the load operation. Defaults to `'GET'`.
+     */
+    loadMethod?: 'GET' | 'POST';
+    /**
+     * HTTP method override for the save operation. Defaults to `'POST'`. Some
+     * REST APIs prefer `'PUT'` for upsert semantics.
+     */
+    saveMethod?: 'POST' | 'PUT' | 'PATCH';
+    /**
+     * Transform the raw JSON response into the expected `T`. Useful for APIs
+     * that wrap responses in `{ data: ... }` or similar envelopes. Called
+     * after `res.json()`. If omitted, the parsed JSON is used as-is.
+     */
+    unwrap?: (raw: unknown) => T | null;
+    /**
+     * Retry policy for failed requests. Defaults to no retries (preserves the
+     * pre-3.6.0 behaviour). When configured, applies to all three operations.
+     */
+    retry?: ApiAdapterRetryConfig;
+    /**
+     * Called when a request fails (after all retries exhausted). The adapter
+     * still returns a graceful null/void result so the consuming hook
+     * doesn't crash — this hook is for telemetry, toasts, or audit logging.
+     */
+    onError?: (ctx: ApiAdapterErrorContext<T>) => void;
+    /**
+     * Called when a request succeeds. Useful for cache invalidation,
+     * analytics, or syncing other state.
+     */
+    onSuccess?: (ctx: ApiAdapterSuccessContext<T>) => void;
+    /**
+     * Per-request fetch options to merge into every request. Use this for
+     * things `fetch` itself supports that aren't directly modelled above —
+     * `signal`, `mode`, `cache`, `redirect`, etc.
+     */
+    fetchInit?: Omit<RequestInit, 'method' | 'headers' | 'body' | 'credentials'>;
+}
+
+export declare interface ApiAdapterRetryConfig {
+    /**
+     * Number of additional attempts after the initial request. Defaults to 0
+     * (no retries). e.g. `attempts: 2` means up to 3 total requests.
+     */
+    attempts?: number;
+    /**
+     * Base delay in ms between attempts. Defaults to 250ms. The actual delay
+     * uses exponential backoff: `baseDelayMs * 2^attempt`.
+     */
+    baseDelayMs?: number;
+    /**
+     * Predicate that decides whether to retry given the failure context. By
+     * default we retry on network errors and 5xx responses, but not on 4xx
+     * (those are client errors that won't fix themselves).
+     */
+    shouldRetry?: (ctx: ApiAdapterErrorContext<unknown>) => boolean;
+}
+
+export declare interface ApiAdapterSuccessContext<T = unknown> {
+    /** Which adapter operation succeeded — `load`, `save`, or `remove`. */
+    method: ApiAdapterMethod;
+    /** The endpoint URL. */
+    endpoint: string;
+    /** Response object. */
+    response: Response;
+    /** For `load` operations, the parsed (and optionally unwrapped) data. */
+    data?: T;
+    /** For `save` operations, the payload that was sent. */
+    payload?: T;
+}
+
 /**
  * Appends a single audit entry to the consent audit log in localStorage.
  * The log is append-only; existing entries are never modified.
@@ -172,7 +278,7 @@ export declare interface BreachNotificationManagerClassNames {
     detailPanel?: string;
 }
 
-declare interface BreachNotificationManagerProps {
+export declare interface BreachNotificationManagerProps {
     /**
      * List of breach reports to manage
      */
@@ -351,7 +457,7 @@ export declare interface BreachReportFormClassNames {
     loadingOverlay?: string;
 }
 
-declare interface BreachReportFormProps {
+export declare interface BreachReportFormProps {
     /**
      * Available breach categories
      */
@@ -462,7 +568,7 @@ export declare interface BreachRiskAssessmentClassNames {
     primaryButton?: string;
 }
 
-declare interface BreachRiskAssessmentProps {
+export declare interface BreachRiskAssessmentProps {
     /**
      * The breach data to assess
      */
@@ -703,7 +809,7 @@ export declare interface ConsentBannerClassNames {
     secondaryButton?: string;
 }
 
-declare interface ConsentBannerProps {
+export declare interface ConsentBannerProps {
     /**
      * Array of consent options to display
      */
@@ -844,7 +950,7 @@ export declare interface ConsentManagerClassNames {
     secondaryButton?: string;
 }
 
-declare interface ConsentManagerProps {
+export declare interface ConsentManagerProps {
     /**
      * Array of consent options to display
      */
@@ -1027,7 +1133,7 @@ export declare interface ConsentStorageOptions {
     };
 }
 
-declare interface ConsentStorageProps {
+export declare interface ConsentStorageProps {
     /**
      * Current consent settings
      */
@@ -1075,6 +1181,14 @@ declare interface ConsentStorageProps {
     }) => React__default.ReactNode);
 }
 
+export declare interface CookieAdapterOptions {
+    domain?: string;
+    path?: string;
+    expires?: number;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+
 /**
  * Creates a new audit entry from consent settings. If `previousSettings` is
  * provided, the action is automatically determined by comparing old and new
@@ -1208,7 +1322,7 @@ export declare interface CrossBorderTransferManagerClassNames {
     approvalStatus?: string;
 }
 
-declare interface CrossBorderTransferManagerProps {
+export declare interface CrossBorderTransferManagerProps {
     /**
      * List of cross-border transfers to display
      */
@@ -1401,7 +1515,7 @@ export declare interface DPIAQuestionnaireClassNames {
     progressBar?: string;
 }
 
-declare interface DPIAQuestionnaireProps {
+export declare interface DPIAQuestionnaireProps {
     /**
      * Sections of the DPIA questionnaire
      */
@@ -1510,7 +1624,7 @@ export declare interface DPIAReportClassNames {
     primaryButton?: string;
 }
 
-declare interface DPIAReportProps {
+export declare interface DPIAReportProps {
     /**
      * The DPIA result to display
      */
@@ -1672,7 +1786,7 @@ export declare interface DSRDashboardClassNames {
     detailPanel?: string;
 }
 
-declare interface DSRDashboardProps {
+export declare interface DSRDashboardProps {
     /**
      * List of DSR requests to display
      */
@@ -1853,7 +1967,7 @@ export declare interface DSRRequestFormClassNames {
     loadingOverlay?: string;
 }
 
-declare interface DSRRequestFormProps {
+export declare interface DSRRequestFormProps {
     /**
      * Array of request types that can be submitted
      */
@@ -1959,6 +2073,34 @@ declare interface DSRRequestFormProps {
  */
 export declare type DSRStatus = 'pending' | 'awaitingVerification' | 'inProgress' | 'completed' | 'rejected';
 
+/**
+ * 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`.
+ */
+export declare interface DsrSubmissionPayload {
+    requestType: string;
+    dataSubject: {
+        fullName: string;
+        email: string;
+        phone?: string;
+        identifierType: string;
+        identifierValue: string;
+    };
+    additionalInfo?: Record<string, string | number | boolean | null>;
+    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.
@@ -1977,7 +2119,7 @@ export declare interface DSRTrackerClassNames {
     statusBadge?: string;
 }
 
-declare interface DSRTrackerProps {
+export declare interface DSRTrackerProps {
     /**
      * List of DSR requests to track
      */
@@ -2268,7 +2410,7 @@ export declare interface LawfulBasisTrackerClassNames {
     gapAlert?: string;
 }
 
-declare interface LawfulBasisTrackerProps {
+export declare interface LawfulBasisTrackerProps {
     /**
      * List of processing activities to display
      */
@@ -2868,7 +3010,7 @@ export declare interface PolicyExporterClassNames {
     preview?: string;
 }
 
-declare interface PolicyExporterProps {
+export declare interface PolicyExporterProps {
     /**
      * The policy content to export
      */
@@ -2972,7 +3114,7 @@ export declare interface PolicyGeneratorClassNames {
     complianceNotice?: string;
 }
 
-declare interface PolicyGeneratorProps {
+export declare interface PolicyGeneratorProps {
     /**
      * List of policy sections
      * @default DEFAULT_POLICY_SECTIONS
@@ -3058,7 +3200,7 @@ export declare interface PolicyPreviewClassNames {
     complianceNotice?: string;
 }
 
-declare interface PolicyPreviewProps {
+export declare interface PolicyPreviewProps {
     /**
      * The policy content to preview
      */
@@ -3518,7 +3660,7 @@ export declare interface RegulatoryReportGeneratorClassNames {
     secondaryButton?: string;
 }
 
-declare interface RegulatoryReportGeneratorProps {
+export declare interface RegulatoryReportGeneratorProps {
     /**
      * The breach data to include in the report
      */
@@ -3713,7 +3855,7 @@ export declare interface ROPAManagerClassNames {
     complianceGap?: string;
 }
 
-declare interface ROPAManagerProps {
+export declare interface ROPAManagerProps {
     /**
      * The full Record of Processing Activities
      */
@@ -3856,7 +3998,7 @@ export declare interface StepIndicatorClassNames {
     label?: string;
 }
 
-declare interface StepIndicatorProps {
+export declare interface StepIndicatorProps {
     /**
      * Array of steps to display
      */
@@ -3903,7 +4045,7 @@ declare interface StepIndicatorProps {
     unstyled?: boolean;
 }
 
-declare interface StorageAdapter<T = unknown> {
+export declare interface StorageAdapter<T = unknown> {
     /** Load persisted data. Called once on hook mount. */
     load(): T | null | Promise<T | null>;
     /** Persist data. Called on every state change. */
@@ -4021,6 +4163,28 @@ export declare interface TransferValidationResult {
     warnings: string[];
 }
 
+/**
+ * Multi-step privacy-policy authoring hook that adapts the generated draft
+ * to the supplied template context (industry, processing purposes, data
+ * categories, processors). Auto-persists a draft via the supplied adapter
+ * and surfaces a live compliance score against the configured rule set.
+ *
+ * @example
+ * ```tsx
+ * import { useAdaptivePolicyWizard } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function PolicyWizard() {
+ *   const { currentStep, nextStep, policy, complianceScore } = useAdaptivePolicyWizard();
+ *   return (
+ *     <div>
+ *       <p>Step {currentStep} — compliance: {complianceScore}%</p>
+ *       <button onClick={nextStep}>Next</button>
+ *       {policy && <pre>{policy.title}</pre>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare function useAdaptivePolicyWizard(options?: UseAdaptivePolicyWizardOptions): UseAdaptivePolicyWizardReturn;
 
 export declare interface UseAdaptivePolicyWizardOptions {
@@ -4081,7 +4245,19 @@ export declare interface UseAdaptivePolicyWizardReturn {
 }
 
 /**
- * Hook for managing data breach notifications in compliance with the NDPA (Section 40)
+ * Hook for managing data breach notifications in compliance with the NDPA (Section 40).
+ *
+ * @example
+ * ```tsx
+ * import { useBreach } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function BreachConsole() {
+ *   const { reports, reportBreach } = useBreach({
+ *     categories: [{ id: 'unauthorized-access', name: 'Unauthorised access', description: '' }],
+ *   });
+ *   return <p>{reports.length} breach report(s) on record.</p>;
+ * }
+ * ```
  */
 export declare function useBreach({ categories, initialReports, adapter, storageKey, useLocalStorage, onReport, onAssessment, onNotification, }: UseBreachOptions): UseBreachReturn;
 
@@ -4188,14 +4364,65 @@ declare interface UseBreachReturn {
     isLoading: boolean;
 }
 
+/**
+ * Computes an NDPA compliance score and returns a structured report
+ * (score, rating, per-module breakdown, recommendations).
+ *
+ * The computation is memoised by the structural identity of `input` — passing
+ * a fresh-but-equal object on every render is safe and does not force a recompute.
+ *
+ * @param options - The compliance score options.
+ * @param options.input - A {@link ComplianceInput} snapshot summarising the
+ *   organisation's current compliance posture.
+ * @returns A memoised {@link ComplianceReport} with overall score, rating,
+ *   module-level breakdowns, and prioritised recommendations.
+ *
+ * @example
+ * ```tsx
+ * import { useComplianceScore } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function ComplianceBadge({ input }) {
+ *   const report = useComplianceScore({ input });
+ *   return <span>{report.overallScore}/100 — {report.rating}</span>;
+ * }
+ * ```
+ */
 export declare function useComplianceScore({ input }: UseComplianceScoreOptions): ComplianceReport;
 
 declare interface UseComplianceScoreOptions {
+    /**
+     * Snapshot of the organisation's compliance signals — consent settings,
+     * DSR queue, breach log, lawful-basis register, transfers, ROPA, etc.
+     * The hook recomputes the report whenever this input changes by value
+     * (compared via a stable JSON key under the hood).
+     */
     input: ComplianceInput;
 }
 
 /**
- * Hook for managing user consent in compliance with NDPA
+ * Hook for managing user consent in compliance with the NDPA.
+ *
+ * @example
+ * ```tsx
+ * import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function App() {
+ *   const { hasConsent, acceptAll, rejectAll, shouldShowBanner } = useConsent({
+ *     options: [
+ *       { id: 'necessary', label: 'Necessary', required: true },
+ *       { id: 'analytics', label: 'Analytics' },
+ *     ],
+ *   });
+ *   if (!shouldShowBanner) return null;
+ *   return (
+ *     <div role="dialog">
+ *       <button onClick={acceptAll}>Accept all</button>
+ *       <button onClick={rejectAll}>Reject non-essential</button>
+ *       {hasConsent('analytics') && <AnalyticsScripts />}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare function useConsent({ options, adapter, storageOptions, version, onChange, }: UseConsentOptions): UseConsentReturn;
 
@@ -4268,7 +4495,18 @@ declare interface UseConsentReturn {
 }
 
 /**
- * Hook for managing cross-border data transfers in compliance with NDPA Part VIII (Sections 41-43)
+ * Hook for managing cross-border data transfers in compliance with NDPA Part VIII (Sections 41-43).
+ *
+ * @example
+ * ```tsx
+ * import { useCrossBorderTransfer } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function TransferRegister() {
+ *   const { transfers, getSummary } = useCrossBorderTransfer();
+ *   const summary = getSummary();
+ *   return <p>{summary.totalActiveTransfers} active cross-border transfers.</p>;
+ * }
+ * ```
  */
 export declare function useCrossBorderTransfer({ initialTransfers, adapter, storageKey, useLocalStorage, onAdd, onUpdate, onRemove, }?: UseCrossBorderTransferOptions): UseCrossBorderTransferReturn;
 
@@ -4414,7 +4652,22 @@ declare interface UseDefaultPrivacyPolicyOptions {
 }
 
 /**
- * Hook for conducting Data Protection Impact Assessments in compliance with the NDPA 2023
+ * Hook for conducting Data Protection Impact Assessments in compliance with the NDPA 2023.
+ *
+ * @example
+ * ```tsx
+ * import { useDPIA } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function DPIAWizard({ sections }) {
+ *   const { currentSection, progress, updateAnswer, nextSection } = useDPIA({ sections });
+ *   return (
+ *     <div>
+ *       <h2>{currentSection?.title} ({progress}%)</h2>
+ *       <button onClick={nextSection}>Next</button>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare function useDPIA({ sections, initialAnswers, adapter, storageKey, useLocalStorage, onComplete, }: UseDPIAOptions): UseDPIAReturn;
 
@@ -4517,7 +4770,27 @@ declare interface UseDPIAReturn {
 }
 
 /**
- * Hook for managing Data Subject Requests in compliance with the NDPA
+ * Hook for managing Data Subject Requests in compliance with the NDPA.
+ *
+ * @example
+ * ```tsx
+ * import { useDSR } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function DSRPanel() {
+ *   const { requests, submitRequest } = useDSR({
+ *     requestTypes: [
+ *       { id: 'access', name: 'Access', description: 'Request access', estimatedCompletionTime: 30 },
+ *     ],
+ *   });
+ *   return (
+ *     <ul>
+ *       {requests.map((r) => (
+ *         <li key={r.id}>{r.type} — {r.status}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
  */
 export declare function useDSR({ initialRequests, requestTypes, adapter, storageKey, useLocalStorage, onSubmit, onUpdate, }: UseDSROptions): UseDSRReturn;
 
@@ -4642,6 +4915,16 @@ export declare interface UseFocusTrapOptions {
 /**
  * Hook for managing lawful basis documentation for processing activities
  * in compliance with NDPA 2023 Section 25.
+ *
+ * @example
+ * ```tsx
+ * import { useLawfulBasis } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function LawfulBasisRegistry() {
+ *   const { activities, addActivity } = useLawfulBasis();
+ *   return <p>{activities.length} processing activities documented.</p>;
+ * }
+ * ```
  */
 export declare function useLawfulBasis({ initialActivities, adapter, storageKey, useLocalStorage, onAdd, onUpdate, onRemove, }?: UseLawfulBasisOptions): UseLawfulBasisReturn;
 
@@ -4722,7 +5005,23 @@ declare interface UseLawfulBasisReturn {
 export declare function useNDPRConfig(): NDPRConfig;
 
 /**
- * Hook for generating NDPA-compliant privacy policies
+ * Hook for generating NDPA-compliant privacy policies.
+ *
+ * @example
+ * ```tsx
+ * import { usePrivacyPolicy } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function PolicyBuilder({ templates }) {
+ *   const { policy, selectTemplate, generatePolicy } = usePrivacyPolicy({ templates });
+ *   return (
+ *     <div>
+ *       <button onClick={() => selectTemplate(templates[0].id)}>Select default</button>
+ *       <button onClick={generatePolicy}>Generate</button>
+ *       {policy && <pre>{policy.title}</pre>}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare function usePrivacyPolicy({ templates, initialPolicy, adapter, storageKey, persist, useLocalStorage, onGenerate, }: UsePrivacyPolicyOptions): UsePrivacyPolicyReturn;
 
@@ -4834,6 +5133,21 @@ declare interface UsePrivacyPolicyReturn {
  *
  * Provides state management and utility functions for maintaining
  * a comprehensive register of all data processing activities.
+ *
+ * @example
+ * ```tsx
+ * import { useROPA } from '@tantainnovative/ndpr-toolkit/hooks';
+ *
+ * function ROPARegister({ initialData }) {
+ *   const { ropa, addRecord, exportCSV } = useROPA({ initialData });
+ *   return (
+ *     <div>
+ *       <p>{ropa.records.length} processing records</p>
+ *       <button onClick={() => download(exportCSV())}>Export CSV</button>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export declare function useROPA({ initialData, adapter, onRecordAdd, onRecordUpdate, onRecordArchive, }: UseROPAOptions): UseROPAReturn;
 
@@ -4923,6 +5237,61 @@ export declare function validateConsentOptions(options: ConsentOption[]): {
     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.
+ *
+ * Defensive — accepts `unknown` and narrows. Safe to call directly on
+ * `await request.json()`.
+ *
+ * @example **Next.js Route Handler**
+ * ```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 });
+ * }
+ * ```
+ *
+ * @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[];
+}
+
 /**
  * Validates that all required fields are present on a processing activity
  * and that the lawful basis is properly documented.