feat: signing order (#1290)

Adds the ability to specify an optional signing order for documents.
When specified a document will be considered sequential with recipients
only being allowed to sign in the order that they were specified in.

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

@@ -7,6 +7,7 @@ import {
   diffDocumentMetaChanges,
 } from '@documenso/lib/utils/document-audit-logs';
 import { prisma } from '@documenso/prisma';
+import type { DocumentSigningOrder } from '@documenso/prisma/client';
 
 export type CreateDocumentMetaOptions = {
   documentId: number;
@@ -16,6 +17,7 @@ export type CreateDocumentMetaOptions = {
   password?: string;
   dateFormat?: string;
   redirectUrl?: string;
+  signingOrder?: DocumentSigningOrder;
   userId: number;
   requestMetadata: RequestMetadata;
 };
@@ -29,6 +31,7 @@ export const upsertDocumentMeta = async ({
   password,
   userId,
   redirectUrl,
+  signingOrder,
   requestMetadata,
 }: CreateDocumentMetaOptions) => {
   const user = await prisma.user.findFirstOrThrow({
@@ -78,6 +81,7 @@ export const upsertDocumentMeta = async ({
         timezone,
         documentId,
         redirectUrl,
+        signingOrder,
       },
       update: {
         subject,
@@ -86,6 +90,7 @@ export const upsertDocumentMeta = async ({
         dateFormat,
         timezone,
         redirectUrl,
+        signingOrder,
       },
     });
 

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

@@ -2,11 +2,18 @@ import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-log
 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';
+import {
+  DocumentSigningOrder,
+  DocumentStatus,
+  RecipientRole,
+  SendStatus,
+  SigningStatus,
+} from '@documenso/prisma/client';
 import { WebhookTriggerEvents } from '@documenso/prisma/client';
 
 import { jobs } from '../../jobs/client';
 import type { TRecipientActionAuth } from '../../types/document-auth';
+import { getIsRecipientsTurnToSign } from '../recipient/get-is-recipient-turn';
 import { triggerWebhook } from '../webhooks/trigger/trigger-webhook';
 import { sendPendingEmail } from './send-pending-email';
 
@@ -29,6 +36,7 @@ const getDocument = async ({ token, documentId }: CompleteDocumentWithTokenOptio
       },
     },
     include: {
+      documentMeta: true,
       Recipient: {
         where: {
           token,
@@ -59,6 +67,16 @@ export const completeDocumentWithToken = async ({
     throw new Error(`Recipient ${recipient.id} has already signed`);
   }
 
+  if (document.documentMeta?.signingOrder === DocumentSigningOrder.SEQUENTIAL) {
+    const isRecipientsTurn = await getIsRecipientsTurnToSign({ token: recipient.token });
+
+    if (!isRecipientsTurn) {
+      throw new Error(
+        `Recipient ${recipient.id} attempted to complete the document before it was their turn`,
+      );
+    }
+  }
+
   const fields = await prisma.field.findMany({
     where: {
       documentId: document.id,
@@ -120,17 +138,48 @@ export const completeDocumentWithToken = async ({
     });
   });
 
-  const pendingRecipients = await prisma.recipient.count({
+  const pendingRecipients = await prisma.recipient.findMany({
+    select: {
+      id: true,
+      signingOrder: true,
+    },
     where: {
       documentId: document.id,
       signingStatus: {
         not: SigningStatus.SIGNED,
       },
+      role: {
+        not: RecipientRole.CC,
+      },
     },
+    // Composite sort so our next recipient is always the one with the lowest signing order or id
+    // if there is a tie.
+    orderBy: [{ signingOrder: { sort: 'asc', nulls: 'last' } }, { id: 'asc' }],
   });
 
-  if (pendingRecipients > 0) {
+  if (pendingRecipients.length > 0) {
     await sendPendingEmail({ documentId, recipientId: recipient.id });
+
+    if (document.documentMeta?.signingOrder === DocumentSigningOrder.SEQUENTIAL) {
+      const [nextRecipient] = pendingRecipients;
+
+      await prisma.$transaction(async (tx) => {
+        await tx.recipient.update({
+          where: { id: nextRecipient.id },
+          data: { sendStatus: SendStatus.SENT },
+        });
+
+        await jobs.triggerJob({
+          name: 'send.signing.requested.email',
+          payload: {
+            userId: document.userId,
+            documentId: document.id,
+            recipientId: nextRecipient.id,
+            requestMetadata,
+          },
+        });
+      });
+    }
   }
 
   const haveAllRecipientsSigned = await prisma.document.findFirst({
@@ -138,7 +187,7 @@ export const completeDocumentWithToken = async ({
       id: document.id,
       Recipient: {
         every: {
-          signingStatus: SigningStatus.SIGNED,
+          OR: [{ signingStatus: SigningStatus.SIGNED }, { role: RecipientRole.CC }],
         },
       },
     },

packages/lib/server-only/document/send-document.tsx

@@ -3,7 +3,13 @@ import type { RequestMetadata } from '@documenso/lib/universal/extract-request-m
 import { putPdfFile } from '@documenso/lib/universal/upload/put-file';
 import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
 import { prisma } from '@documenso/prisma';
-import { DocumentStatus, RecipientRole, SendStatus, SigningStatus } from '@documenso/prisma/client';
+import {
+  DocumentSigningOrder,
+  DocumentStatus,
+  RecipientRole,
+  SendStatus,
+  SigningStatus,
+} from '@documenso/prisma/client';
 import { WebhookTriggerEvents } from '@documenso/prisma/client';
 
 import { jobs } from '../../jobs/client';
@@ -57,7 +63,9 @@ export const sendDocument = async ({
           }),
     },
     include: {
-      Recipient: true,
+      Recipient: {
+        orderBy: [{ signingOrder: { sort: 'asc', nulls: 'last' } }, { id: 'asc' }],
+      },
       documentMeta: true,
       documentData: true,
     },
@@ -75,6 +83,21 @@ export const sendDocument = async ({
     throw new Error('Can not send completed document');
   }
 
+  const signingOrder = document.documentMeta?.signingOrder || DocumentSigningOrder.PARALLEL;
+
+  let recipientsToNotify = document.Recipient;
+
+  if (signingOrder === DocumentSigningOrder.SEQUENTIAL) {
+    // Get the currently active recipient.
+    recipientsToNotify = document.Recipient.filter(
+      (r) => r.signingStatus === SigningStatus.NOT_SIGNED && r.role !== RecipientRole.CC,
+    ).slice(0, 1);
+
+    // Secondary filter so we aren't resending if the current active recipient has already
+    // received the document.
+    recipientsToNotify.filter((r) => r.sendStatus !== SendStatus.SENT);
+  }
+
   const { documentData } = document;
 
   if (!documentData.data) {
@@ -135,7 +158,7 @@ export const sendDocument = async ({
 
   if (sendEmail) {
     await Promise.all(
-      document.Recipient.map(async (recipient) => {
+      recipientsToNotify.map(async (recipient) => {
         if (recipient.sendStatus === SendStatus.SENT || recipient.role === RecipientRole.CC) {
           return;
         }

packages/lib/server-only/recipient/get-is-recipient-turn.ts

@@ -0,0 +1,46 @@
+import { prisma } from '@documenso/prisma';
+import { DocumentSigningOrder, SigningStatus } from '@documenso/prisma/client';
+
+export type GetIsRecipientTurnOptions = {
+  token: string;
+};
+
+export async function getIsRecipientsTurnToSign({ token }: GetIsRecipientTurnOptions) {
+  const document = await prisma.document.findFirstOrThrow({
+    where: {
+      Recipient: {
+        some: {
+          token,
+        },
+      },
+    },
+    include: {
+      documentMeta: true,
+      Recipient: {
+        orderBy: {
+          signingOrder: 'asc',
+        },
+      },
+    },
+  });
+
+  if (document.documentMeta?.signingOrder !== DocumentSigningOrder.SEQUENTIAL) {
+    return true;
+  }
+
+  const recipients = document.Recipient;
+
+  const currentRecipientIndex = recipients.findIndex((r) => r.token === token);
+
+  if (currentRecipientIndex === -1) {
+    return false;
+  }
+
+  for (let i = 0; i < currentRecipientIndex; i++) {
+    if (recipients[i].signingStatus !== SigningStatus.SIGNED) {
+      return false;
+    }
+  }
+
+  return true;
+}

packages/lib/server-only/recipient/set-recipients-for-document.ts

@@ -27,6 +27,7 @@ export interface SetRecipientsForDocumentOptions {
     email: string;
     name: string;
     role: RecipientRole;
+    signingOrder?: number | null;
     actionAuth?: TRecipientActionAuthTypes | null;
   }[];
   requestMetadata?: RequestMetadata;
@@ -156,6 +157,7 @@ export const setRecipientsForDocument = async ({
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
+            signingOrder: recipient.signingOrder,
             documentId,
             sendStatus: recipient.role === RecipientRole.CC ? SendStatus.SENT : SendStatus.NOT_SENT,
             signingStatus:
@@ -166,6 +168,7 @@ export const setRecipientsForDocument = async ({
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
+            signingOrder: recipient.signingOrder,
             token: nanoid(),
             documentId,
             sendStatus: recipient.role === RecipientRole.CC ? SendStatus.SENT : SendStatus.NOT_SENT,

packages/lib/server-only/recipient/set-recipients-for-template.ts

@@ -24,6 +24,7 @@ export type SetRecipientsForTemplateOptions = {
     email: string;
     name: string;
     role: RecipientRole;
+    signingOrder?: number | null;
     actionAuth?: TRecipientActionAuthTypes | null;
   }[];
 };
@@ -162,6 +163,7 @@ export const setRecipientsForTemplate = async ({
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
+            signingOrder: recipient.signingOrder,
             templateId,
             authOptions,
           },
@@ -169,6 +171,7 @@ export const setRecipientsForTemplate = async ({
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
+            signingOrder: recipient.signingOrder,
             token: nanoid(),
             templateId,
             authOptions,

packages/lib/server-only/recipient/update-recipient.ts

@@ -18,6 +18,7 @@ export type UpdateRecipientOptions = {
   email?: string;
   name?: string;
   role?: RecipientRole;
+  signingOrder?: number | null;
   actionAuth?: TRecipientActionAuthTypes | null;
   userId: number;
   teamId?: number;
@@ -30,6 +31,7 @@ export const updateRecipient = async ({
   email,
   name,
   role,
+  signingOrder,
   actionAuth,
   userId,
   teamId,
@@ -112,6 +114,7 @@ export const updateRecipient = async ({
         email: email?.toLowerCase() ?? recipient.email,
         name: name ?? recipient.name,
         role: role ?? recipient.role,
+        signingOrder,
         authOptions: createRecipientAuthOptions({
           accessAuth: recipientAuthOptions.accessAuth,
           actionAuth: actionAuth ?? null,

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

@@ -10,6 +10,7 @@ export type CreateDocumentFromTemplateLegacyOptions = {
     name?: string;
     email: string;
     role?: RecipientRole;
+    signingOrder?: number | null;
   }[];
 };
 
@@ -73,6 +74,7 @@ export const createDocumentFromTemplateLegacy = async ({
           email: recipient.email,
           name: recipient.name,
           role: recipient.role,
+          signingOrder: recipient.signingOrder,
           token: nanoid(),
         })),
       },
@@ -129,12 +131,14 @@ export const createDocumentFromTemplateLegacy = async ({
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
+            signingOrder: recipient.signingOrder,
           },
           create: {
             documentId: document.id,
             email: recipient.email,
             name: recipient.name,
             role: recipient.role,
+            signingOrder: recipient.signingOrder,
             token: nanoid(),
           },
         });

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

@@ -1,6 +1,6 @@
 import { nanoid } from '@documenso/lib/universal/id';
 import { prisma } from '@documenso/prisma';
-import type { Field } from '@documenso/prisma/client';
+import type { DocumentSigningOrder, Field } from '@documenso/prisma/client';
 import {
   DocumentSource,
   type Recipient,
@@ -41,6 +41,7 @@ export type CreateDocumentFromTemplateOptions = {
     id: number;
     name?: string;
     email: string;
+    signingOrder?: number | null;
   }[];
 
   /**
@@ -54,6 +55,7 @@ export type CreateDocumentFromTemplateOptions = {
     password?: string;
     dateFormat?: string;
     redirectUrl?: string;
+    signingOrder?: DocumentSigningOrder;
   };
   requestMetadata?: RequestMetadata;
 };
@@ -134,6 +136,7 @@ export const createDocumentFromTemplate = async ({
       name: foundRecipient ? foundRecipient.name ?? '' : templateRecipient.name,
       email: foundRecipient ? foundRecipient.email : templateRecipient.email,
       role: templateRecipient.role,
+      signingOrder: foundRecipient?.signingOrder ?? templateRecipient.signingOrder,
       authOptions: templateRecipient.authOptions,
     };
   });
@@ -168,6 +171,8 @@ export const createDocumentFromTemplate = async ({
             password: override?.password || template.templateMeta?.password,
             dateFormat: override?.dateFormat || template.templateMeta?.dateFormat,
             redirectUrl: override?.redirectUrl || template.templateMeta?.redirectUrl,
+            signingOrder:
+              override?.signingOrder || template.templateMeta?.signingOrder || undefined,
           },
         },
         Recipient: {

packages/lib/server-only/template/update-template-settings.ts

@@ -33,7 +33,7 @@ export const updateTemplateSettings = async ({
   meta,
   data,
 }: UpdateTemplateSettingsOptions) => {
-  if (Object.values(data).length === 0) {
+  if (Object.values(data).length === 0 && Object.keys(meta ?? {}).length === 0) {
     throw new AppError(AppErrorCode.INVALID_BODY, 'Missing data to update');
   }