@tantainnovative/ndpr-recipes 0.1.0

package/src/adapters/prisma-dsr.ts

@@ -0,0 +1,163 @@
+/**
+ * Prisma adapter for the Data Subject Rights (DSR) module.
+ *
+ * Implements StorageAdapter<DSRRequest[]> backed by the `ndpr_dsr_requests`
+ * Prisma model.
+ *
+ * Behaviour
+ * ---------
+ * - LOAD  → returns all DSR requests submitted by the given subject email.
+ * - SAVE  → upserts each request in the array by ID.
+ * - REMOVE → soft-deletes all requests for the subject by setting status to
+ *            'rejected' with an internal note (preserves the audit trail).
+ *
+ * Usage
+ * -----
+ * Copy this file into your project, then wire it into the toolkit hook:
+ *
+ *   import { PrismaClient } from '@prisma/client';
+ *   import { useDSR } from '@tantainnovative/ndpr-toolkit';
+ *   import { prismaDSRAdapter } from './adapters/prisma-dsr';
+ *
+ *   const prisma = new PrismaClient();
+ *
+ *   function DSRPage() {
+ *     const adapter = prismaDSRAdapter(prisma, session.user.email);
+ *     const { requests, submitRequest } = useDSR({ adapter });
+ *     // ...
+ *   }
+ *
+ * Server-side usage (e.g. Next.js API route)
+ * ------------------------------------------
+ * You can also call adapter.save() directly inside a POST handler after
+ * validating the incoming DSRFormSubmission from the toolkit's DSRRequestForm.
+ *
+ * Prerequisites
+ * -------------
+ * - The `ndpr_dsr_requests` table must exist (run the ndpr-recipes Prisma migration).
+ * - `@prisma/client` must be installed in your project.
+ * - `@tantainnovative/ndpr-toolkit` must be installed in your project.
+ */
+
+import type { PrismaClient } from '@prisma/client';
+import type { StorageAdapter } from '@tantainnovative/ndpr-toolkit';
+import type { DSRRequest } from '@tantainnovative/ndpr-toolkit';
+
+/**
+ * Creates a Prisma-backed StorageAdapter for DSRRequest[].
+ *
+ * @param prisma       - Your application's PrismaClient instance.
+ * @param subjectEmail - The data subject's email address used to scope all queries.
+ * @returns A StorageAdapter<DSRRequest[]> ready to pass to useDSR().
+ */
+export function prismaDSRAdapter(
+  prisma: PrismaClient,
+  subjectEmail: string,
+): StorageAdapter<DSRRequest[]> {
+  return {
+    /**
+     * Load all DSR requests for the subject.
+     * Returns an empty array (not null) when no requests exist — the hook
+     * will display an empty state rather than triggering an initial-load flow.
+     */
+    async load(): Promise<DSRRequest[]> {
+      const rows = await (prisma as any).dSRRequest.findMany({
+        where: { subjectEmail },
+        orderBy: { submittedAt: 'desc' },
+      });
+
+      return rows.map(mapRowToDSRRequest);
+    },
+
+    /**
+     * Persist the current list of DSR requests.
+     * Each request is upserted individually by ID so partial updates work
+     * (e.g. a status change to a single request doesn't overwrite others).
+     */
+    async save(requests: DSRRequest[]): Promise<void> {
+      await Promise.all(
+        requests.map((req) =>
+          (prisma as any).dSRRequest.upsert({
+            where: { id: req.id },
+            update: mapDSRRequestToRow(req),
+            create: {
+              id: req.id,
+              ...mapDSRRequestToRow(req),
+            },
+          }),
+        ),
+      );
+    },
+
+    /**
+     * Soft-delete all pending/in-progress requests for this subject.
+     * Completed and already-rejected requests are left untouched so the
+     * historical record is preserved for accountability purposes.
+     */
+    async remove(): Promise<void> {
+      await (prisma as any).dSRRequest.updateMany({
+        where: {
+          subjectEmail,
+          status: { notIn: ['completed', 'rejected'] },
+        },
+        data: {
+          status: 'rejected',
+          internalNotes: 'Soft-deleted via adapter.remove()',
+        },
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mapping helpers — translate between the Prisma row shape and DSRRequest
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a raw Prisma row to the DSRRequest shape expected by the toolkit.
+ */
+function mapRowToDSRRequest(row: any): DSRRequest {
+  return {
+    id: row.id,
+    type: row.type,
+    status: row.status,
+    createdAt: row.submittedAt.getTime(),
+    updatedAt: row.acknowledgedAt?.getTime() ?? row.submittedAt.getTime(),
+    completedAt: row.completedAt?.getTime(),
+    dueDate: row.dueAt.getTime(),
+    description: row.description ?? undefined,
+    subject: {
+      name: row.subjectName,
+      email: row.subjectEmail,
+      phone: row.subjectPhone ?? undefined,
+      identifierType: row.identifierType,
+      identifierValue: row.identifierValue,
+    },
+    internalNotes: row.internalNotes
+      ? [{ timestamp: Date.now(), author: 'system', note: row.internalNotes }]
+      : undefined,
+  };
+}
+
+/**
+ * Map a DSRRequest to the Prisma `create`/`update` data shape.
+ * Fields not present on the toolkit type (e.g. assignedTo) default to null.
+ */
+function mapDSRRequestToRow(req: DSRRequest): Record<string, unknown> {
+  return {
+    type: req.type,
+    status: req.status,
+    subjectName: req.subject.name,
+    subjectEmail: req.subject.email,
+    subjectPhone: req.subject.phone ?? null,
+    identifierType: req.subject.identifierType ?? 'email',
+    identifierValue: req.subject.identifierValue ?? req.subject.email,
+    description: req.description ?? null,
+    internalNotes: req.internalNotes?.map((n) => n.note).join('\n') ?? null,
+    submittedAt: new Date(req.createdAt),
+    acknowledgedAt: req.updatedAt ? new Date(req.updatedAt) : null,
+    completedAt: req.completedAt ? new Date(req.completedAt) : null,
+    // NDPA mandates a 30-day response window; dueAt should be set on creation.
+    dueAt: req.dueDate ? new Date(req.dueDate) : new Date(req.createdAt + 30 * 24 * 60 * 60 * 1000),
+  };
+}

package/src/adapters/prisma-ropa.ts

@@ -0,0 +1,205 @@
+/**
+ * Prisma adapter for the ROPA (Record of Processing Activities) module.
+ *
+ * Implements StorageAdapter<RecordOfProcessingActivities> backed by the
+ * `ndpr_processing_records` Prisma model.
+ *
+ * The toolkit's useROPA() hook stores a single RecordOfProcessingActivities
+ * object that wraps an array of ProcessingRecord entries plus organisation
+ * metadata. This adapter maps between that object and the flat Prisma table.
+ *
+ * Behaviour
+ * ---------
+ * - LOAD  → reads all ProcessingRecord rows and assembles them into a
+ *           RecordOfProcessingActivities using the org metadata you provide.
+ * - SAVE  → upserts each ProcessingRecord individually by ID.
+ * - REMOVE → marks all active records as 'archived' (no hard deletes).
+ *
+ * Organisation metadata
+ * ---------------------
+ * Because the ROPA object includes organisation-level fields (name, contact,
+ * address, DPO details) that are not stored in the processing records table,
+ * you must supply them when creating the adapter. Typically these come from
+ * your app's settings or environment config.
+ *
+ * Usage
+ * -----
+ * Copy this file into your project, then wire it into the toolkit hook:
+ *
+ *   import { PrismaClient } from '@prisma/client';
+ *   import { useROPA } from '@tantainnovative/ndpr-toolkit';
+ *   import { prismaROPAAdapter } from './adapters/prisma-ropa';
+ *
+ *   const prisma = new PrismaClient();
+ *
+ *   function ROPAPage() {
+ *     const adapter = prismaROPAAdapter(prisma, {
+ *       organizationName: process.env.ORG_NAME!,
+ *       organizationContact: process.env.DPO_EMAIL!,
+ *       organizationAddress: process.env.ORG_ADDRESS!,
+ *     });
+ *     const { ropa, addRecord } = useROPA({ adapter });
+ *     // ...
+ *   }
+ *
+ * Prerequisites
+ * -------------
+ * - The `ndpr_processing_records` table must exist (run the ndpr-recipes migration).
+ * - `@prisma/client` must be installed in your project.
+ * - `@tantainnovative/ndpr-toolkit` must be installed in your project.
+ */
+
+import type { PrismaClient } from '@prisma/client';
+import type { StorageAdapter } from '@tantainnovative/ndpr-toolkit';
+import type { RecordOfProcessingActivities, ProcessingRecord } from '@tantainnovative/ndpr-toolkit';
+
+/** Organisation metadata required to construct the ROPA envelope */
+export interface ROPAOrgMetadata {
+  organizationName: string;
+  organizationContact: string;
+  organizationAddress: string;
+  dpoDetails?: {
+    name: string;
+    email: string;
+    phone?: string;
+  };
+  ndpcRegistrationNumber?: string;
+}
+
+/**
+ * Creates a Prisma-backed StorageAdapter for RecordOfProcessingActivities.
+ *
+ * @param prisma   - Your application's PrismaClient instance.
+ * @param orgMeta  - Organisation-level metadata used to build the ROPA envelope.
+ * @returns A StorageAdapter<RecordOfProcessingActivities> ready to pass to useROPA().
+ */
+export function prismaROPAAdapter(
+  prisma: PrismaClient,
+  orgMeta: ROPAOrgMetadata,
+): StorageAdapter<RecordOfProcessingActivities> {
+  return {
+    /**
+     * Load all processing records and wrap them in a RecordOfProcessingActivities.
+     * Returns null if no records exist yet so the hook renders an empty ROPA.
+     */
+    async load(): Promise<RecordOfProcessingActivities | null> {
+      const rows = await (prisma as any).processingRecord.findMany({
+        orderBy: { createdAt: 'asc' },
+      });
+
+      if (rows.length === 0) return null;
+
+      const records: ProcessingRecord[] = rows.map(mapRowToProcessingRecord);
+      const lastUpdated = Math.max(...rows.map((r: any) => r.updatedAt.getTime()));
+
+      return {
+        id: 'ropa-' + orgMeta.organizationName.toLowerCase().replace(/\s+/g, '-'),
+        organizationName: orgMeta.organizationName,
+        organizationContact: orgMeta.organizationContact,
+        organizationAddress: orgMeta.organizationAddress,
+        dpoDetails: orgMeta.dpoDetails,
+        ndpcRegistrationNumber: orgMeta.ndpcRegistrationNumber,
+        records,
+        lastUpdated,
+        version: '1.0',
+      };
+    },
+
+    /**
+     * Persist the ROPA by upserting each ProcessingRecord individually.
+     * The organisation envelope fields are not stored in the database — they
+     * come from orgMeta on every load.
+     */
+    async save(ropa: RecordOfProcessingActivities): Promise<void> {
+      await Promise.all(
+        ropa.records.map((record) =>
+          (prisma as any).processingRecord.upsert({
+            where: { id: record.id },
+            update: mapProcessingRecordToRow(record),
+            create: {
+              id: record.id,
+              ...mapProcessingRecordToRow(record),
+            },
+          }),
+        ),
+      );
+    },
+
+    /**
+     * Archive all active processing records without deleting them.
+     * Archived records are excluded from active ROPA reports but are retained
+     * for audit purposes as required by the NDPA accountability principle.
+     */
+    async remove(): Promise<void> {
+      await (prisma as any).processingRecord.updateMany({
+        where: { status: 'active' },
+        data: { status: 'archived' },
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mapping helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a raw Prisma ProcessingRecord row to the toolkit's ProcessingRecord type.
+ * Several rich fields on the toolkit type (controllerDetails, lawfulBasisJustification, etc.)
+ * are not in the simplified Prisma schema — they default to placeholder values.
+ * Extend the schema with additional columns if you need full round-trip fidelity.
+ */
+function mapRowToProcessingRecord(row: any): ProcessingRecord {
+  return {
+    id: row.id,
+    // `name` and `description` are derived from purpose since the schema is simplified.
+    name: row.purpose,
+    description: row.purpose,
+    controllerDetails: {
+      name: '',
+      contact: '',
+      address: '',
+    },
+    lawfulBasis: row.lawfulBasis as ProcessingRecord['lawfulBasis'],
+    lawfulBasisJustification: '',
+    purposes: [row.purpose],
+    dataCategories: (row.dataCategories as string[]) ?? [],
+    dataSubjectCategories: (row.dataSubjects as string[]) ?? [],
+    recipients: (row.recipients as string[]) ?? [],
+    crossBorderTransfers: row.transferCountries
+      ? (row.transferCountries as string[]).map((country: string) => ({
+          destinationCountry: country,
+          safeguards: '',
+          transferMechanism: row.transferMechanism ?? '',
+        }))
+      : undefined,
+    retentionPeriod: row.retentionPeriod,
+    securityMeasures: (row.securityMeasures as string[]) ?? [],
+    dataSource: 'data_subject',
+    dpiaRequired: row.dpiaConducted,
+    automatedDecisionMaking: false,
+    status: row.status as ProcessingRecord['status'],
+    createdAt: row.createdAt.getTime(),
+    updatedAt: row.updatedAt.getTime(),
+  };
+}
+
+/**
+ * Map a toolkit ProcessingRecord to the Prisma `create`/`update` data shape.
+ * Composite toolkit fields are flattened to match the simplified Prisma schema.
+ */
+function mapProcessingRecordToRow(record: ProcessingRecord): Record<string, unknown> {
+  return {
+    purpose: record.purposes[0] ?? record.name,
+    lawfulBasis: record.lawfulBasis,
+    dataCategories: record.dataCategories,
+    dataSubjects: record.dataSubjectCategories,
+    recipients: record.recipients,
+    retentionPeriod: record.retentionPeriod,
+    securityMeasures: record.securityMeasures,
+    transferCountries: record.crossBorderTransfers?.map((t) => t.destinationCountry) ?? null,
+    transferMechanism: record.crossBorderTransfers?.[0]?.transferMechanism ?? null,
+    dpiaConducted: record.dpiaRequired,
+    status: record.status,
+  };
+}