feat: dictate next signer (#1719)

Adds next recipient dictation functionality to document signing flow,
allowing assistants and signers to update the next recipient's
information during the signing process.

## Related Issue

N/A

## Changes Made

- Added form handling for next recipient dictation in signing dialogs
- Implemented UI for updating next recipient information
- Added e2e tests covering dictation scenarios:
  - Regular signing with dictation enabled
  - Assistant role with dictation
  - Parallel signing flow
  - Disabled dictation state

## Testing Performed

- Added comprehensive e2e tests covering:
  - Sequential signing with dictation
  - Assistant role dictation
  - Parallel signing without dictation
  - Form validation and state management
- Tested on Chrome and Firefox
- Verified recipient state updates in database

packages/lib/server-only/document-meta/upsert-document-meta.ts

@@ -24,6 +24,7 @@ export type CreateDocumentMetaOptions = {
   redirectUrl?: string;
   emailSettings?: TDocumentEmailSettings;
   signingOrder?: DocumentSigningOrder;
+  allowDictateNextSigner?: boolean;
   distributionMethod?: DocumentDistributionMethod;
   typedSignatureEnabled?: boolean;
   language?: SupportedLanguageCodes;
@@ -41,6 +42,7 @@ export const upsertDocumentMeta = async ({
   password,
   redirectUrl,
   signingOrder,
+  allowDictateNextSigner,
   emailSettings,
   distributionMethod,
   typedSignatureEnabled,
@@ -93,6 +95,7 @@ export const upsertDocumentMeta = async ({
         documentId,
         redirectUrl,
         signingOrder,
+        allowDictateNextSigner,
         emailSettings,
         distributionMethod,
         typedSignatureEnabled,
@@ -106,6 +109,7 @@ export const upsertDocumentMeta = async ({
         timezone,
         redirectUrl,
         signingOrder,
+        allowDictateNextSigner,
         emailSettings,
         distributionMethod,
         typedSignatureEnabled,

packages/lib/server-only/document/complete-document-with-token.ts

@@ -7,7 +7,10 @@ import {
   WebhookTriggerEvents,
 } from '@prisma/client';
 
-import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
+import {
+  DOCUMENT_AUDIT_LOG_TYPE,
+  RECIPIENT_DIFF_TYPE,
+} from '@documenso/lib/types/document-audit-logs';
 import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
 import { fieldsContainUnsignedRequiredField } from '@documenso/lib/utils/advanced-fields-helpers';
 import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
@@ -30,6 +33,10 @@ export type CompleteDocumentWithTokenOptions = {
   userId?: number;
   authOptions?: TRecipientActionAuth;
   requestMetadata?: RequestMetadata;
+  nextSigner?: {
+    email: string;
+    name: string;
+  };
 };
 
 const getDocument = async ({ token, documentId }: CompleteDocumentWithTokenOptions) => {
@@ -57,6 +64,7 @@ export const completeDocumentWithToken = async ({
   token,
   documentId,
   requestMetadata,
+  nextSigner,
 }: CompleteDocumentWithTokenOptions) => {
   const document = await getDocument({ token, documentId });
 
@@ -146,7 +154,6 @@ export const completeDocumentWithToken = async ({
           recipientName: recipient.name,
           recipientId: recipient.id,
           recipientRole: recipient.role,
-          // actionAuth: derivedRecipientActionAuth || undefined,
         },
       }),
     });
@@ -164,6 +171,9 @@ export const completeDocumentWithToken = async ({
     select: {
       id: true,
       signingOrder: true,
+      name: true,
+      email: true,
+      role: true,
     },
     where: {
       documentId: document.id,
@@ -186,9 +196,49 @@ export const completeDocumentWithToken = async ({
       const [nextRecipient] = pendingRecipients;
 
       await prisma.$transaction(async (tx) => {
+        if (nextSigner && document.documentMeta?.allowDictateNextSigner) {
+          await tx.documentAuditLog.create({
+            data: createDocumentAuditLogData({
+              type: DOCUMENT_AUDIT_LOG_TYPE.RECIPIENT_UPDATED,
+              documentId: document.id,
+              user: {
+                name: recipient.name,
+                email: recipient.email,
+              },
+              requestMetadata,
+              data: {
+                recipientEmail: nextRecipient.email,
+                recipientName: nextRecipient.name,
+                recipientId: nextRecipient.id,
+                recipientRole: nextRecipient.role,
+                changes: [
+                  {
+                    type: RECIPIENT_DIFF_TYPE.NAME,
+                    from: nextRecipient.name,
+                    to: nextSigner.name,
+                  },
+                  {
+                    type: RECIPIENT_DIFF_TYPE.EMAIL,
+                    from: nextRecipient.email,
+                    to: nextSigner.email,
+                  },
+                ],
+              },
+            }),
+          });
+        }
+
         await tx.recipient.update({
           where: { id: nextRecipient.id },
-          data: { sendStatus: SendStatus.SENT },
+          data: {
+            sendStatus: SendStatus.SENT,
+            ...(nextSigner && document.documentMeta?.allowDictateNextSigner
+              ? {
+                  name: nextSigner.name,
+                  email: nextSigner.email,
+                }
+              : {}),
+          },
         });
 
         await jobs.triggerJob({

packages/lib/server-only/recipient/get-next-pending-recipient.ts

@@ -0,0 +1,37 @@
+import { prisma } from '@documenso/prisma';
+
+export const getNextPendingRecipient = async ({
+  documentId,
+  currentRecipientId,
+}: {
+  documentId: number;
+  currentRecipientId: number;
+}) => {
+  const recipients = await prisma.recipient.findMany({
+    where: {
+      documentId,
+    },
+    orderBy: [
+      {
+        signingOrder: {
+          sort: 'asc',
+          nulls: 'last',
+        },
+      },
+      {
+        id: 'asc',
+      },
+    ],
+  });
+
+  const currentIndex = recipients.findIndex((r) => r.id === currentRecipientId);
+
+  if (currentIndex === -1 || currentIndex === recipients.length - 1) {
+    return null;
+  }
+
+  return {
+    ...recipients[currentIndex + 1],
+    token: '',
+  };
+};

packages/lib/server-only/template/create-document-from-template.ts

@@ -83,6 +83,7 @@ export type CreateDocumentFromTemplateOptions = {
     language?: SupportedLanguageCodes;
     distributionMethod?: DocumentDistributionMethod;
     typedSignatureEnabled?: boolean;
+    allowDictateNextSigner?: boolean;
     emailSettings?: TDocumentEmailSettings;
   };
   requestMetadata: ApiRequestMetadata;
@@ -404,6 +405,10 @@ export const createDocumentFromTemplate = async ({
               template.team?.teamGlobalSettings?.documentLanguage,
             typedSignatureEnabled:
               override?.typedSignatureEnabled ?? template.templateMeta?.typedSignatureEnabled,
+            allowDictateNextSigner:
+              override?.allowDictateNextSigner ??
+              template.templateMeta?.allowDictateNextSigner ??
+              false,
           },
         },
         recipients: {

packages/lib/types/document.ts

@@ -51,6 +51,7 @@ export const ZDocumentSchema = DocumentSchema.pick({
     documentId: true,
     redirectUrl: true,
     typedSignatureEnabled: true,
+    allowDictateNextSigner: true,
     language: true,
     emailSettings: true,
   }).nullable(),

packages/lib/types/template.ts

@@ -45,6 +45,7 @@ export const ZTemplateSchema = TemplateSchema.pick({
     dateFormat: true,
     signingOrder: true,
     typedSignatureEnabled: true,
+    allowDictateNextSigner: true,
     distributionMethod: true,
     templateId: true,
     redirectUrl: true,

packages/lib/types/webhook-payload.ts

@@ -46,6 +46,7 @@ export const ZWebhookDocumentMetaSchema = z.object({
   dateFormat: z.string(),
   redirectUrl: z.string().nullable(),
   signingOrder: z.nativeEnum(DocumentSigningOrder),
+  allowDictateNextSigner: z.boolean(),
   typedSignatureEnabled: z.boolean(),
   language: z.string(),
   distributionMethod: z.nativeEnum(DocumentDistributionMethod),