feat: initial document audit logs implementation (#922)

Added initial implementation of document audit logs.
2025-11-13 16:23:06 +10:00 · 2024-02-12 12:04:53 +11:00
parent 4f990a7030
commit 3a32bc62c5
26 changed files with 1382 additions and 224 deletions
--- a/packages/lib/server-only/field/remove-signed-field-with-token.ts
+++ b/packages/lib/server-only/field/remove-signed-field-with-token.ts
@ -1,16 +1,21 @@
 'use server';

+import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
+import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
+import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
 import { prisma } from '@documenso/prisma';
 import { DocumentStatus, SigningStatus } from '@documenso/prisma/client';

 export type RemovedSignedFieldWithTokenOptions = {
  token: string;
  fieldId: number;
+  requestMetadata?: RequestMetadata;
 };

 export const removeSignedFieldWithToken = async ({
  token,
  fieldId,
+  requestMetadata,
 }: RemovedSignedFieldWithTokenOptions) => {
  const field = await prisma.field.findFirstOrThrow({
    where: {
@ -44,8 +49,8 @@ export const removeSignedFieldWithToken = async ({
    throw new Error(`Field ${fieldId} has no recipientId`);
  }

-  await Promise.all([
-    prisma.field.update({
+  await prisma.$transaction(async (tx) => {
+    await tx.field.update({
      where: {
        id: field.id,
      },
@ -53,11 +58,28 @@ export const removeSignedFieldWithToken = async ({
        customText: '',
        inserted: false,
      },
-    }),
-    prisma.signature.deleteMany({
+    });
+
+    await tx.signature.deleteMany({
      where: {
        fieldId: field.id,
      },
-    }),
-  ]);
+    });
+
+    await tx.documentAuditLog.create({
+      data: createDocumentAuditLogData({
+        type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_FIELD_UNINSERTED,
+        documentId: document.id,
+        user: {
+          name: recipient?.name,
+          email: recipient?.email,
+        },
+        requestMetadata,
+        data: {
+          field: field.type,
+          fieldId: field.secondaryId,
+        },
+      }),
+    });
+  });
 };
--- a/packages/lib/server-only/field/set-fields-for-document.ts
+++ b/packages/lib/server-only/field/set-fields-for-document.ts
@ -1,3 +1,9 @@
+import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
+import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
+import {
+  createDocumentAuditLogData,
+  diffFieldChanges,
+} from '@documenso/lib/utils/document-audit-logs';
 import { prisma } from '@documenso/prisma';
 import type { FieldType } from '@documenso/prisma/client';
 import { SendStatus, SigningStatus } from '@documenso/prisma/client';
@ -15,12 +21,14 @@ export interface SetFieldsForDocumentOptions {
    pageWidth: number;
    pageHeight: number;
  }[];
+  requestMetadata?: RequestMetadata;
 }

 export const setFieldsForDocument = async ({
  userId,
  documentId,
  fields,
+  requestMetadata,
 }: SetFieldsForDocumentOptions) => {
  const document = await prisma.document.findFirst({
    where: {
@ -42,6 +50,17 @@ export const setFieldsForDocument = async ({
    },
  });

+  const user = await prisma.user.findFirstOrThrow({
+    where: {
+      id: userId,
+    },
+    select: {
+      id: true,
+      name: true,
+      email: true,
+    },
+  });
+
  if (!document) {
    throw new Error('Document not found');
  }
@ -79,56 +98,123 @@ export const setFieldsForDocument = async ({
      );
    });

-  const persistedFields = await prisma.$transaction(
-    // Disabling as wrapping promises here causes type issues
-    // eslint-disable-next-line @typescript-eslint/promise-function-async
-    linkedFields.map((field) =>
-      prisma.field.upsert({
-        where: {
-          id: field._persisted?.id ?? -1,
-          documentId,
-        },
-        update: {
-          page: field.pageNumber,
-          positionX: field.pageX,
-          positionY: field.pageY,
-          width: field.pageWidth,
-          height: field.pageHeight,
-        },
-        create: {
-          type: field.type,
-          page: field.pageNumber,
-          positionX: field.pageX,
-          positionY: field.pageY,
-          width: field.pageWidth,
-          height: field.pageHeight,
-          customText: '',
-          inserted: false,
-          Document: {
-            connect: {
-              id: documentId,
-            },
+  const persistedFields = await prisma.$transaction(async (tx) => {
+    await Promise.all(
+      linkedFields.map(async (field) => {
+        const fieldSignerEmail = field.signerEmail.toLowerCase();
+
+        const upsertedField = await tx.field.upsert({
+          where: {
+            id: field._persisted?.id ?? -1,
+            documentId,
          },
-          Recipient: {
-            connect: {
-              documentId_email: {
-                documentId,
-                email: field.signerEmail.toLowerCase(),
+          update: {
+            page: field.pageNumber,
+            positionX: field.pageX,
+            positionY: field.pageY,
+            width: field.pageWidth,
+            height: field.pageHeight,
+          },
+          create: {
+            type: field.type,
+            page: field.pageNumber,
+            positionX: field.pageX,
+            positionY: field.pageY,
+            width: field.pageWidth,
+            height: field.pageHeight,
+            customText: '',
+            inserted: false,
+            Document: {
+              connect: {
+                id: documentId,
+              },
+            },
+            Recipient: {
+              connect: {
+                documentId_email: {
+                  documentId,
+                  email: fieldSignerEmail,
+                },
              },
            },
          },
-        },
+        });
+
+        if (upsertedField.recipientId === null) {
+          throw new Error('Not possible');
+        }
+
+        const baseAuditLog = {
+          fieldId: upsertedField.secondaryId,
+          fieldRecipientEmail: fieldSignerEmail,
+          fieldRecipientId: upsertedField.recipientId,
+          fieldType: upsertedField.type,
+        };
+
+        const changes = field._persisted ? diffFieldChanges(field._persisted, upsertedField) : [];
+
+        // Handle field updated audit log.
+        if (field._persisted && changes.length > 0) {
+          await tx.documentAuditLog.create({
+            data: createDocumentAuditLogData({
+              type: DOCUMENT_AUDIT_LOG_TYPE.FIELD_UPDATED,
+              documentId: documentId,
+              user,
+              requestMetadata,
+              data: {
+                changes,
+                ...baseAuditLog,
+              },
+            }),
+          });
+        }
+
+        // Handle field created audit log.
+        if (!field._persisted) {
+          await tx.documentAuditLog.create({
+            data: createDocumentAuditLogData({
+              type: DOCUMENT_AUDIT_LOG_TYPE.FIELD_CREATED,
+              documentId: documentId,
+              user,
+              requestMetadata,
+              data: {
+                ...baseAuditLog,
+              },
+            }),
+          });
+        }
+
+        return upsertedField;
      }),
-    ),
-  );
+    );
+  });

  if (removedFields.length > 0) {
-    await prisma.field.deleteMany({
-      where: {
-        id: {
-          in: removedFields.map((field) => field.id),
+    await prisma.$transaction(async (tx) => {
+      await tx.field.deleteMany({
+        where: {
+          id: {
+            in: removedFields.map((field) => field.id),
+          },
        },
-      },
+      });
+
+      await tx.documentAuditLog.createMany({
+        data: removedFields.map((field) =>
+          createDocumentAuditLogData({
+            type: DOCUMENT_AUDIT_LOG_TYPE.FIELD_DELETED,
+            documentId: documentId,
+            user,
+            requestMetadata,
+            data: {
+              fieldId: field.secondaryId,
+              fieldRecipientEmail: field.Recipient?.email ?? '',
+              fieldRecipientId: field.recipientId ?? -1,
+              fieldType: field.type,
+            },
+          }),
+        ),
+      });
    });
  }

--- a/packages/lib/server-only/field/sign-field-with-token.ts
+++ b/packages/lib/server-only/field/sign-field-with-token.ts
@ -1,18 +1,23 @@
 'use server';

 import { DateTime } from 'luxon';
+import { match } from 'ts-pattern';

 import { prisma } from '@documenso/prisma';
 import { DocumentStatus, FieldType, SigningStatus } from '@documenso/prisma/client';

 import { DEFAULT_DOCUMENT_DATE_FORMAT } from '../../constants/date-formats';
 import { DEFAULT_DOCUMENT_TIME_ZONE } from '../../constants/time-zones';
+import { DOCUMENT_AUDIT_LOG_TYPE } from '../../types/document-audit-logs';
+import type { RequestMetadata } from '../../universal/extract-request-metadata';
+import { createDocumentAuditLogData } from '../../utils/document-audit-logs';

 export type SignFieldWithTokenOptions = {
  token: string;
  fieldId: number;
  value: string;
  isBase64?: boolean;
+  requestMetadata?: RequestMetadata;
 };

 export const signFieldWithToken = async ({
@ -20,6 +25,7 @@ export const signFieldWithToken = async ({
  fieldId,
  value,
  isBase64,
+  requestMetadata,
 }: SignFieldWithTokenOptions) => {
  const field = await prisma.field.findFirstOrThrow({
    where: {
@ -40,6 +46,10 @@ export const signFieldWithToken = async ({
    throw new Error(`Document not found for field ${field.id}`);
  }

+  if (!recipient) {
+    throw new Error(`Recipient not found for field ${field.id}`);
+  }
+
  if (document.status === DocumentStatus.COMPLETED) {
    throw new Error(`Document ${document.id} has already been completed`);
  }
@ -123,6 +133,38 @@ export const signFieldWithToken = async ({
      });
    }

+    await tx.documentAuditLog.create({
+      data: createDocumentAuditLogData({
+        type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_FIELD_INSERTED,
+        documentId: document.id,
+        user: {
+          email: recipient.email,
+          name: recipient.name,
+        },
+        requestMetadata,
+        data: {
+          recipientEmail: recipient.email,
+          recipientId: recipient.id,
+          recipientName: recipient.name,
+          recipientRole: recipient.role,
+          fieldId: updatedField.secondaryId,
+          field: match(updatedField.type)
+            .with(FieldType.SIGNATURE, FieldType.FREE_SIGNATURE, (type) => ({
+              type,
+              data: signatureImageAsBase64 || typedSignature || '',
+            }))
+            .with(FieldType.DATE, FieldType.EMAIL, FieldType.NAME, FieldType.TEXT, (type) => ({
+              type,
+              data: updatedField.customText,
+            }))
+            .exhaustive(),
+          fieldSecurity: {
+            type: 'NONE',
+          },
+        },
+      }),
+    });
+
    return updatedField;
  });
 };