feat: assistant role (#1588)

Introduces the ability for users with the **Assistant** role to prefill
fields on behalf of other signers. Assistants can fill in various field
types such as text, checkboxes, dates, and more, streamlining the
document preparation process before it reaches the final signers.

packages/lib/server-only/field/get-fields-for-token.ts

@@ -1,15 +1,55 @@
 import { prisma } from '@documenso/prisma';
+import { FieldType, RecipientRole, SigningStatus } from '@documenso/prisma/client';
 
 export type GetFieldsForTokenOptions = {
   token: string;
 };
 
 export const getFieldsForToken = async ({ token }: GetFieldsForTokenOptions) => {
+  if (!token) {
+    throw new Error('Missing token');
+  }
+
+  const recipient = await prisma.recipient.findFirst({
+    where: { token },
+  });
+
+  if (!recipient) {
+    return [];
+  }
+
+  if (recipient.role === RecipientRole.ASSISTANT) {
+    return await prisma.field.findMany({
+      where: {
+        OR: [
+          {
+            type: {
+              not: FieldType.SIGNATURE,
+            },
+            recipient: {
+              signingStatus: {
+                not: SigningStatus.SIGNED,
+              },
+              signingOrder: {
+                gte: recipient.signingOrder ?? 0,
+              },
+            },
+            documentId: recipient.documentId,
+          },
+          {
+            recipientId: recipient.id,
+          },
+        ],
+      },
+      include: {
+        signature: true,
+      },
+    });
+  }
+
   return await prisma.field.findMany({
     where: {
-      recipient: {
-        token,
-      },
+      recipientId: recipient.id,
     },
     include: {
       signature: true,

packages/lib/server-only/field/remove-signed-field-with-token.ts

@@ -1,4 +1,4 @@
-import { DocumentStatus, SigningStatus } from '@prisma/client';
+import { DocumentStatus, RecipientRole, SigningStatus } from '@prisma/client';
 
 import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
 import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
@@ -16,11 +16,28 @@ export const removeSignedFieldWithToken = async ({
   fieldId,
   requestMetadata,
 }: RemovedSignedFieldWithTokenOptions) => {
+  const recipient = await prisma.recipient.findFirstOrThrow({
+    where: {
+      token,
+    },
+  });
+
   const field = await prisma.field.findFirstOrThrow({
     where: {
       id: fieldId,
       recipient: {
-        token,
+        ...(recipient.role !== RecipientRole.ASSISTANT
+          ? {
+              id: recipient.id,
+            }
+          : {
+              signingOrder: {
+                gte: recipient.signingOrder ?? 0,
+              },
+              signingStatus: {
+                not: SigningStatus.SIGNED,
+              },
+            }),
       },
     },
     include: {
@@ -29,7 +46,7 @@ export const removeSignedFieldWithToken = async ({
     },
   });
 
-  const { document, recipient } = field;
+  const { document } = field;
 
   if (!document) {
     throw new Error(`Document not found for field ${field.id}`);
@@ -39,7 +56,10 @@ export const removeSignedFieldWithToken = async ({
     throw new Error(`Document ${document.id} must be pending`);
   }
 
-  if (recipient?.signingStatus === SigningStatus.SIGNED) {
+  if (
+    recipient?.signingStatus === SigningStatus.SIGNED ||
+    field.recipient.signingStatus === SigningStatus.SIGNED
+  ) {
     throw new Error(`Recipient ${recipient.id} has already signed`);
   }
 
@@ -65,20 +85,22 @@ export const removeSignedFieldWithToken = async ({
       },
     });
 
-    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,
-        },
-      }),
-    });
+    if (recipient.role !== RecipientRole.ASSISTANT) {
+      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,
+          },
+        }),
+      });
+    }
   });
 };

packages/lib/server-only/field/sign-field-with-token.ts

@@ -1,4 +1,4 @@
-import { DocumentStatus, FieldType, SigningStatus } from '@prisma/client';
+import { DocumentStatus, FieldType, RecipientRole, SigningStatus } from '@prisma/client';
 import { DateTime } from 'luxon';
 import { match } from 'ts-pattern';
 
@@ -54,20 +54,41 @@ export const signFieldWithToken = async ({
   authOptions,
   requestMetadata,
 }: SignFieldWithTokenOptions) => {
+  const recipient = await prisma.recipient.findFirstOrThrow({
+    where: {
+      token,
+    },
+  });
+
   const field = await prisma.field.findFirstOrThrow({
     where: {
       id: fieldId,
       recipient: {
-        token,
+        ...(recipient.role !== RecipientRole.ASSISTANT
+          ? {
+              id: recipient.id,
+            }
+          : {
+              signingStatus: {
+                not: SigningStatus.SIGNED,
+              },
+              signingOrder: {
+                gte: recipient.signingOrder ?? 0,
+              },
+            }),
       },
     },
     include: {
-      document: true,
+      document: {
+        include: {
+          recipients: true,
+        },
+      },
       recipient: true,
     },
   });
 
-  const { document, recipient } = field;
+  const { document } = field;
 
   if (!document) {
     throw new Error(`Document not found for field ${field.id}`);
@@ -85,7 +106,10 @@ export const signFieldWithToken = async ({
     throw new Error(`Document ${document.id} must be pending for signing`);
   }
 
-  if (recipient?.signingStatus === SigningStatus.SIGNED) {
+  if (
+    recipient.signingStatus === SigningStatus.SIGNED ||
+    field.recipient.signingStatus === SigningStatus.SIGNED
+  ) {
     throw new Error(`Recipient ${recipient.id} has already signed`);
   }
 
@@ -181,6 +205,8 @@ export const signFieldWithToken = async ({
     throw new Error('Typed signatures are not allowed. Please draw your signature');
   }
 
+  const assistant = recipient.role === RecipientRole.ASSISTANT ? recipient : undefined;
+
   return await prisma.$transaction(async (tx) => {
     const updatedField = await tx.field.update({
       where: {
@@ -217,11 +243,14 @@ export const signFieldWithToken = async ({
 
     await tx.documentAuditLog.create({
       data: createDocumentAuditLogData({
-        type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_FIELD_INSERTED,
+        type:
+          assistant && field.recipientId !== assistant.id
+            ? DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_FIELD_PREFILLED
+            : DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_FIELD_INSERTED,
         documentId: document.id,
         user: {
-          email: recipient.email,
-          name: recipient.name,
+          email: assistant?.email ?? recipient.email,
+          name: assistant?.name ?? recipient.name,
         },
         requestMetadata,
         data: {

packages/lib/server-only/recipient/get-recipient-by-token.ts

@@ -9,5 +9,8 @@ export const getRecipientByToken = async ({ token }: GetRecipientByTokenOptions)
     where: {
       token,
     },
+    include: {
+      fields: true,
+    },
   });
 };

packages/lib/server-only/recipient/get-recipients-for-assistant.ts

@@ -0,0 +1,57 @@
+import { prisma } from '@documenso/prisma';
+import { FieldType } from '@documenso/prisma/client';
+
+import { AppError, AppErrorCode } from '../../errors/app-error';
+
+export interface GetRecipientsForAssistantOptions {
+  token: string;
+}
+
+export const getRecipientsForAssistant = async ({ token }: GetRecipientsForAssistantOptions) => {
+  const assistant = await prisma.recipient.findFirst({
+    where: {
+      token,
+    },
+  });
+
+  if (!assistant) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Assistant not found',
+    });
+  }
+
+  let recipients = await prisma.recipient.findMany({
+    where: {
+      documentId: assistant.documentId,
+      signingOrder: {
+        gte: assistant.signingOrder ?? 0,
+      },
+    },
+    include: {
+      fields: {
+        where: {
+          OR: [
+            {
+              recipientId: assistant.id,
+            },
+            {
+              type: {
+                not: FieldType.SIGNATURE,
+              },
+              documentId: assistant.documentId,
+            },
+          ],
+        },
+      },
+    },
+  });
+
+  // Omit the token for recipients other than the assistant so
+  // it doesn't get sent to the client.
+  recipients = recipients.map((recipient) => ({
+    ...recipient,
+    token: recipient.id === assistant.id ? token : '',
+  }));
+
+  return recipients;
+};