@tantainnovative/ndpr-toolkit 3.4.0 → 3.5.0

package/dist/dsr.d.mts

@@ -1,37 +1,654 @@
-import { c as DSRRequestFormProps } from './DSRRequestForm-DRouEr9j.mjs';
-export { D as DSRFormSubmission, a as DSRRequestForm, b as DSRRequestFormClassNames } from './DSRRequestForm-DRouEr9j.mjs';
-import { d as DSRDashboardProps, e as DSRTrackerProps } from './DSRTracker-CSVDfgQQ.mjs';
-export { D as DSRDashboard, a as DSRDashboardClassNames, b as DSRTracker, c as DSRTrackerClassNames } from './DSRTracker-CSVDfgQQ.mjs';
-import { U as UseDSRReturn } from './useDSR-WvHk8_iu.mjs';
-export { u as useDSR } from './useDSR-WvHk8_iu.mjs';
-export { f as formatDSRRequest } from './dsr-XZ_HqTlA.mjs';
-import { c as RequestType, D as DSRRequest } from './dsr-yKbqX531.mjs';
-export { a as DSRStatus, b as DSRType, R as RequestStatus } from './dsr-yKbqX531.mjs';
-import * as React from 'react';
-import React__default from 'react';
-import { S as StorageAdapter } from './types-DK2CoKOC.mjs';
-
-interface DSRProviderProps {
-    requestTypes: RequestType[];
-    adapter?: StorageAdapter<DSRRequest[]>;
-    storageKey?: string;
-    useLocalStorage?: boolean;
-    onSubmit?: (request: DSRRequest) => void;
-    onUpdate?: (request: DSRRequest) => void;
-    children: React__default.ReactNode;
-}
-declare const DSRProvider: React__default.FC<DSRProviderProps>;
-
-declare const DSR: {
-    Provider: React.FC<DSRProviderProps>;
-    Form: React.FC<DSRRequestFormProps>;
-    Dashboard: React.FC<DSRDashboardProps>;
-    Tracker: React.FC<DSRTrackerProps>;
-};
-
-interface DSRContextValue extends UseDSRReturn {
-    requestTypes: RequestType[];
-}
-declare function useDSRCompound(): DSRContextValue;
-
-export { DSR, DSRProvider, type DSRProviderProps, DSRRequest, RequestType, StorageAdapter, useDSRCompound };
+import * as React_2 from 'react';
+import React__default from 'react';
+
+export declare const DSR: {
+    Provider: React_2.FC<DSRProviderProps>;
+    Form: React_2.FC<DSRRequestFormProps>;
+    Dashboard: React_2.FC<DSRDashboardProps>;
+    Tracker: React_2.FC<DSRTrackerProps>;
+};
+
+declare interface DSRContextValue extends UseDSRReturn {
+    requestTypes: RequestType[];
+}
+
+/**
+ * Data Subject Request dashboard component. Supports compliance with NDPA Part IV,
+ * providing tools to track, manage, and respond to data subject requests within required timeframes.
+ */
+export declare const DSRDashboard: React__default.FC<DSRDashboardProps>;
+
+export declare interface DSRDashboardClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    filters?: string;
+    requestList?: string;
+    requestItem?: string;
+    statusBadge?: string;
+    detailPanel?: string;
+}
+
+declare interface DSRDashboardProps {
+    /**
+     * List of DSR requests to display
+     */
+    requests: DSRRequest[];
+    /**
+     * Callback function called when a request is selected
+     */
+    onSelectRequest?: (requestId: string) => void;
+    /**
+     * Callback function called when a request status is updated
+     */
+    onUpdateStatus?: (requestId: string, status: DSRStatus) => void;
+    /**
+     * Callback function called when a request is assigned
+     */
+    onAssignRequest?: (requestId: string, assignee: string) => void;
+    /**
+     * Title displayed on the dashboard
+     * @default "Data Subject Request Dashboard"
+     */
+    title?: string;
+    /**
+     * Description text displayed on the dashboard
+     * @default "Track and manage data subject requests in compliance with NDPA Part IV requirements."
+     */
+    description?: string;
+    /**
+     * Custom CSS class for the dashboard
+     */
+    className?: string;
+    /**
+     * Custom CSS class for the buttons
+     */
+    buttonClassName?: string;
+    /**
+     * Whether to show the request details
+     * @default true
+     */
+    showRequestDetails?: boolean;
+    /**
+     * Whether to show the request timeline
+     * @default true
+     */
+    showRequestTimeline?: boolean;
+    /**
+     * Whether to show the deadline alerts
+     * @default true
+     */
+    showDeadlineAlerts?: boolean;
+    /**
+     * List of possible assignees
+     */
+    assignees?: string[];
+    /**
+     * Object of CSS class overrides keyed by semantic section name.
+     */
+    classNames?: DSRDashboardClassNames;
+    /**
+     * When true, all default Tailwind classes are removed so consumers
+     * can style from scratch using classNames.
+     */
+    unstyled?: boolean;
+}
+
+/**
+ * Represents the data submitted by the DSR request form.
+ */
+export declare interface DSRFormSubmission {
+    /** The selected request type identifier */
+    requestType: string;
+    /** Data subject personal information */
+    dataSubject: {
+        fullName: string;
+        email: string;
+        phone?: string;
+        identifierType: string;
+        identifierValue: string;
+    };
+    /** Additional information provided for the selected request type */
+    additionalInfo?: Record<string, string | number | boolean | null>;
+    /** Timestamp (ms) when the form was submitted */
+    submittedAt: number;
+}
+
+export declare const DSRProvider: React__default.FC<DSRProviderProps>;
+
+export declare interface DSRProviderProps {
+    requestTypes: RequestType[];
+    adapter?: StorageAdapter<DSRRequest[]>;
+    storageKey?: string;
+    useLocalStorage?: boolean;
+    onSubmit?: (request: DSRRequest) => void;
+    onUpdate?: (request: DSRRequest) => void;
+    children: React__default.ReactNode;
+}
+
+/**
+ * Represents a data subject request
+ */
+export declare interface DSRRequest {
+    /** Unique identifier for the request */
+    id: string;
+    /** Type of request */
+    type: DSRType;
+    /** Current status of the request */
+    status: DSRStatus;
+    /** Timestamp when the request was submitted */
+    createdAt: number;
+    /** Timestamp when the request was last updated */
+    updatedAt: number;
+    /** Timestamp when the request was completed (if applicable) */
+    completedAt?: number;
+    /** Timestamp when the identity was verified (if applicable) */
+    verifiedAt?: number;
+    /**
+     * Due date for responding to the request (timestamp)
+     * NDPA requires response within 30 days of receipt
+     */
+    dueDate?: number;
+    /** Description or details of the request */
+    description?: string;
+    /**
+     * The lawful basis under which the data was originally processed
+     * Relevant for evaluating objection and erasure requests
+     */
+    lawfulBasis?: string;
+    /** Data subject information */
+    subject: {
+        name: string;
+        email: string;
+        phone?: string;
+        identifierValue?: string;
+        identifierType?: string;
+    };
+    /** Additional information provided by the data subject */
+    additionalInfo?: Record<string, string | number | boolean | null>;
+    /** Notes added by staff processing the request */
+    internalNotes?: Array<{
+        timestamp: number;
+        author: string;
+        note: string;
+    }>;
+    /** Verification status */
+    verification?: {
+        verified: boolean;
+        method?: string;
+        verifiedAt?: number;
+        verifiedBy?: string;
+    };
+    /** Reason for rejection (if status is 'rejected') */
+    rejectionReason?: string;
+    /** Files attached to the request */
+    attachments?: Array<{
+        id: string;
+        name: string;
+        type: string;
+        url: string;
+        addedAt: number;
+    }>;
+    /**
+     * Whether an extension was requested for this DSR
+     * NDPA allows a one-time extension of 30 days with justification
+     */
+    extensionRequested?: boolean;
+    /** Reason for the extension, if requested */
+    extensionReason?: string;
+}
+
+/**
+ * Data Subject Request form component. Implements NDPA Part IV, Sections 29-36
+ * covering data subject rights including access, rectification, erasure, and portability.
+ */
+export declare const DSRRequestForm: React__default.FC<DSRRequestFormProps>;
+
+export declare interface DSRRequestFormClassNames {
+    root?: string;
+    title?: string;
+    description?: string;
+    form?: string;
+    fieldGroup?: string;
+    label?: string;
+    input?: string;
+    select?: string;
+    textarea?: string;
+    submitButton?: string;
+    /** Alias for submitButton */
+    primaryButton?: string;
+    successMessage?: string;
+    /** Custom class applied when isSubmitting is true (e.g. a loading overlay) */
+    loadingOverlay?: string;
+}
+
+declare interface DSRRequestFormProps {
+    /**
+     * Array of request types that can be submitted
+     */
+    requestTypes: RequestType[];
+    /**
+     * Callback function called when form is submitted
+     */
+    onSubmit: (data: DSRFormSubmission) => void;
+    /**
+     * Callback function called when form validation fails
+     */
+    onValidationError?: (errors: Record<string, string>) => void;
+    /**
+     * Title displayed on the form
+     * @default "Submit a Data Subject Request"
+     */
+    title?: string;
+    /**
+     * Description text displayed on the form
+     * @default "Use this form to exercise your rights under the Nigeria Data Protection Act (NDPA), Part IV, Sections 29-36."
+     */
+    description?: string;
+    /**
+     * Text for the submit button
+     * @default "Submit Request"
+     */
+    submitButtonText?: string;
+    /**
+     * Custom CSS class for the form
+     */
+    className?: string;
+    /**
+     * Custom CSS class for the submit button
+     */
+    buttonClassName?: string;
+    /**
+     * Whether to show a confirmation message after submission
+     * @default true
+     */
+    showConfirmation?: boolean;
+    /**
+     * Confirmation message to display after submission
+     * @default "Your request has been submitted successfully. You will receive a confirmation email shortly."
+     */
+    confirmationMessage?: string;
+    /**
+     * Whether to require identity verification
+     * @default true
+     */
+    requireIdentityVerification?: boolean;
+    /**
+     * Types of identifiers accepted for verification
+     * @default ["email", "account", "customer_id"]
+     */
+    identifierTypes?: Array<{
+        id: string;
+        label: string;
+    }>;
+    /**
+     * Whether to collect additional contact information
+     * @default true
+     */
+    collectAdditionalContact?: boolean;
+    /**
+     * Custom labels for form fields
+     */
+    labels?: {
+        name?: string;
+        email?: string;
+        requestType?: string;
+        description?: string;
+        submit?: string;
+    };
+    /**
+     * Object of CSS class overrides keyed by semantic section name.
+     */
+    classNames?: DSRRequestFormClassNames;
+    /**
+     * When true, all default Tailwind classes are removed so consumers
+     * can style from scratch using classNames.
+     */
+    unstyled?: boolean;
+    /**
+     * Whether the form is currently submitting.
+     * When true, the submit button is disabled and shows "Submitting..." text.
+     */
+    isSubmitting?: boolean;
+    /**
+     * Default values to pre-fill form fields.
+     * Useful for editing existing requests or pre-populating known data.
+     */
+    defaultValues?: Partial<DSRFormSubmission>;
+    /**
+     * Callback fired when the form is reset via the Reset button.
+     * To fully remount the component (clearing all internal state),
+     * change the `key` prop from the parent.
+     */
+    onReset?: () => void;
+}
+
+/**
+ * Status of a data subject request
+ */
+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.
+ */
+export declare const DSRTracker: React__default.FC<DSRTrackerProps>;
+
+export declare interface DSRTrackerClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    stats?: string;
+    statCard?: string;
+    table?: string;
+    tableHeader?: string;
+    tableRow?: string;
+    statusBadge?: string;
+}
+
+declare interface DSRTrackerProps {
+    /**
+     * List of DSR requests to track
+     */
+    requests: DSRRequest[];
+    /**
+     * Callback function called when a request is selected
+     */
+    onSelectRequest?: (requestId: string) => void;
+    /**
+     * Title displayed on the tracker
+     * @default "DSR Request Tracker"
+     */
+    title?: string;
+    /**
+     * Description text displayed on the tracker
+     * @default "Track the status and progress of data subject requests as required by NDPA Part IV."
+     */
+    description?: string;
+    /**
+     * Custom CSS class for the tracker
+     */
+    className?: string;
+    /**
+     * Custom CSS class for the buttons
+     */
+    buttonClassName?: string;
+    /**
+     * Whether to show the summary statistics
+     * @default true
+     */
+    showSummaryStats?: boolean;
+    /**
+     * Whether to show the request type breakdown
+     * @default true
+     */
+    showTypeBreakdown?: boolean;
+    /**
+     * Whether to show the status breakdown
+     * @default true
+     */
+    showStatusBreakdown?: boolean;
+    /**
+     * Whether to show the timeline chart
+     * @default true
+     */
+    showTimelineChart?: boolean;
+    /**
+     * Whether to show the overdue requests
+     * @default true
+     */
+    showOverdueRequests?: boolean;
+    /**
+     * Object of CSS class overrides keyed by semantic section name.
+     */
+    classNames?: DSRTrackerClassNames;
+    /**
+     * When true, all default Tailwind classes are removed so consumers
+     * can style from scratch using classNames.
+     */
+    unstyled?: boolean;
+}
+
+/**
+ * Data Subject Rights types aligned with NDPA 2023 Part IV (Sections 29-36)
+ */
+/**
+ * Types of data subject requests per NDPA Part IV
+ * - 'information': Right to be informed (Section 29)
+ * - 'access': Right of access (Section 30)
+ * - 'rectification': Right to rectification (Section 31)
+ * - 'erasure': Right to erasure (Section 32)
+ * - 'restriction': Right to restrict processing (Section 33)
+ * - 'portability': Right to data portability (Section 34)
+ * - 'objection': Right to object (Section 35)
+ * - 'automated_decision_making': Rights related to automated decision-making (Section 36)
+ */
+export declare type DSRType = 'information' | 'access' | 'rectification' | 'erasure' | 'restriction' | 'portability' | 'objection' | 'automated_decision_making';
+
+/**
+ * Formats a DSR request for display or submission
+ * @param request The DSR request to format
+ * @returns Formatted request data
+ */
+export declare function formatDSRRequest(request: DSRRequest): {
+    formattedRequest: Record<string, unknown>;
+    isValid: boolean;
+    validationErrors: string[];
+};
+
+/**
+ * Legacy status of a data subject request
+ * @deprecated Use DSRStatus instead
+ */
+export declare type RequestStatus = 'pending' | 'verifying' | 'processing' | 'completed' | 'rejected';
+
+/**
+ * Represents a type of data subject request (detailed configuration)
+ */
+export declare interface RequestType {
+    /** Unique identifier for the request type */
+    id: string;
+    /** Display name for the request type */
+    name: string;
+    /** Description of what this request type entails */
+    description: string;
+    /**
+     * NDPA section reference (e.g., "Section 30" for access requests)
+     */
+    ndpaSection?: string;
+    /**
+     * Estimated time to fulfill this type of request (in days)
+     * NDPA requires response within 30 days
+     */
+    estimatedCompletionTime: number;
+    /** Whether additional information is required for this request type */
+    requiresAdditionalInfo: boolean;
+    /** Custom fields required for this request type */
+    additionalFields?: Array<{
+        id: string;
+        label: string;
+        type: 'text' | 'textarea' | 'select' | 'checkbox' | 'file';
+        options?: string[];
+        required: boolean;
+        placeholder?: string;
+    }>;
+}
+
+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. */
+    save(data: T): void | Promise<void>;
+    /** Clear persisted data. Called on reset. */
+    remove(): void | Promise<void>;
+}
+
+/**
+ * Hook for managing Data Subject Requests in compliance with the NDPA
+ */
+export declare function useDSR({ initialRequests, requestTypes, adapter, storageKey, useLocalStorage, onSubmit, onUpdate, }: UseDSROptions): UseDSRReturn;
+
+export declare function useDSRCompound(): DSRContextValue;
+
+declare interface UseDSROptions {
+    /**
+     * Initial requests to load
+     */
+    initialRequests?: DSRRequest[];
+    /**
+     * Available request types
+     */
+    requestTypes: RequestType[];
+    /**
+     * Pluggable storage adapter. When provided, takes precedence over storageKey/useLocalStorage.
+     */
+    adapter?: StorageAdapter<DSRRequest[]>;
+    /**
+     * Storage key for requests
+     * @default "ndpr_dsr_requests"
+     * @deprecated Use adapter instead
+     */
+    storageKey?: string;
+    /**
+     * Whether to use local storage to persist requests
+     * @default true
+     * @deprecated Use adapter instead
+     */
+    useLocalStorage?: boolean;
+    /**
+     * Callback function called when a request is submitted
+     */
+    onSubmit?: (request: DSRRequest) => void;
+    /**
+     * Callback function called when a request is updated
+     */
+    onUpdate?: (request: DSRRequest) => void;
+}
+
+declare interface UseDSRReturn {
+    /**
+     * All requests
+     */
+    requests: DSRRequest[];
+    /**
+     * Submit a new request
+     */
+    submitRequest: (requestData: Omit<DSRRequest, 'id' | 'status' | 'submittedAt' | 'updatedAt' | 'estimatedCompletionDate'>) => DSRRequest;
+    /**
+     * Update an existing request
+     */
+    updateRequest: (id: string, updates: Partial<DSRRequest>) => DSRRequest | null;
+    /**
+     * Get a request by ID
+     */
+    getRequest: (id: string) => DSRRequest | null;
+    /**
+     * Get requests by status
+     */
+    getRequestsByStatus: (status: RequestStatus) => DSRRequest[];
+    /**
+     * Get requests by type
+     */
+    getRequestsByType: (type: string) => DSRRequest[];
+    /**
+     * Get the request type definition by ID
+     */
+    getRequestType: (typeId: string) => RequestType | undefined;
+    /**
+     * Format a request for display or submission
+     */
+    formatRequest: (request: DSRRequest) => Record<string, unknown>;
+    /**
+     * Clear all requests
+     */
+    clearRequests: () => void;
+    /**
+     * Whether the adapter is still loading data (relevant for async adapters)
+     */
+    isLoading: boolean;
+}
+
+/**
+ * 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 IV §29-36 rights.
+     */
+    allowedRequestTypes?: string[];
+}
+
+export { }