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/api/v1/implementation.ts

@@ -293,6 +293,7 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
         timezone,
         dateFormat: dateFormat?.value,
         redirectUrl: body.meta.redirectUrl,
+        signingOrder: body.meta.signingOrder,
         requestMetadata: extractNextApiRequestMetadata(args.req),
       });
 
@@ -325,6 +326,7 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
             email: recipient.email,
             token: recipient.token,
             role: recipient.role,
+            signingOrder: recipient.signingOrder,
 
             signingUrl: `${NEXT_PUBLIC_WEBAPP_URL()}/sign/${recipient.token}`,
           })),
@@ -496,6 +498,7 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
           email: recipient.email,
           token: recipient.token,
           role: recipient.role,
+          signingOrder: recipient.signingOrder,
 
           signingUrl: `${NEXT_PUBLIC_WEBAPP_URL()}/sign/${recipient.token}`,
         })),
@@ -588,6 +591,7 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
           email: recipient.email,
           token: recipient.token,
           role: recipient.role,
+          signingOrder: recipient.signingOrder,
 
           signingUrl: `${NEXT_PUBLIC_WEBAPP_URL()}/sign/${recipient.token}`,
         })),
@@ -713,7 +717,7 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
 
   createRecipient: authenticatedMiddleware(async (args, user, team) => {
     const { id: documentId } = args.params;
-    const { name, email, role, authOptions } = args.body;
+    const { name, email, role, authOptions, signingOrder } = args.body;
 
     const document = await getDocumentById({
       id: Number(documentId),
@@ -762,11 +766,16 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
         userId: user.id,
         teamId: team?.id,
         recipients: [
-          ...recipients,
+          ...recipients.map(({ email, name }) => ({
+            email,
+            name,
+            role,
+          })),
           {
             email,
             name,
             role,
+            signingOrder,
             actionAuth: authOptions?.actionAuth ?? null,
           },
         ],
@@ -799,7 +808,7 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
 
   updateRecipient: authenticatedMiddleware(async (args, user, team) => {
     const { id: documentId, recipientId } = args.params;
-    const { name, email, role, authOptions } = args.body;
+    const { name, email, role, authOptions, signingOrder } = args.body;
 
     const document = await getDocumentById({
       id: Number(documentId),
@@ -833,6 +842,7 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
       email,
       name,
       role,
+      signingOrder,
       actionAuth: authOptions?.actionAuth,
       requestMetadata: extractNextApiRequestMetadata(args.req),
     }).catch(() => null);

packages/api/v1/schema.ts

@@ -13,6 +13,7 @@ import {
 import { ZFieldMetaSchema } from '@documenso/lib/types/field-meta';
 import {
   DocumentDataType,
+  DocumentSigningOrder,
   FieldType,
   ReadStatus,
   RecipientRole,
@@ -103,6 +104,7 @@ export const ZCreateDocumentMutationSchema = z.object({
       name: z.string().min(1),
       email: z.string().email().min(1),
       role: z.nativeEnum(RecipientRole).optional().default(RecipientRole.SIGNER),
+      signingOrder: z.number().nullish(),
     }),
   ),
   meta: z
@@ -123,6 +125,7 @@ export const ZCreateDocumentMutationSchema = z.object({
           enum: DATE_FORMATS.map((format) => format.value),
         }),
       redirectUrl: z.string(),
+      signingOrder: z.nativeEnum(DocumentSigningOrder).optional(),
     })
     .partial(),
   authOptions: z
@@ -147,6 +150,7 @@ export const ZCreateDocumentMutationResponseSchema = z.object({
       email: z.string().email().min(1),
       token: z.string(),
       role: z.nativeEnum(RecipientRole),
+      signingOrder: z.number().nullish(),
 
       signingUrl: z.string(),
     }),
@@ -165,6 +169,7 @@ export const ZCreateDocumentFromTemplateMutationSchema = z.object({
       name: z.string().min(1),
       email: z.string().email().min(1),
       role: z.nativeEnum(RecipientRole).optional().default(RecipientRole.SIGNER),
+      signingOrder: z.number().nullish(),
     }),
   ),
   meta: z
@@ -174,6 +179,7 @@ export const ZCreateDocumentFromTemplateMutationSchema = z.object({
       timezone: z.string(),
       dateFormat: z.string(),
       redirectUrl: z.string(),
+      signingOrder: z.nativeEnum(DocumentSigningOrder).optional(),
     })
     .partial()
     .optional(),
@@ -200,6 +206,7 @@ export const ZCreateDocumentFromTemplateMutationResponseSchema = z.object({
       email: z.string().email().min(1),
       token: z.string(),
       role: z.nativeEnum(RecipientRole).optional().default(RecipientRole.SIGNER),
+      signingOrder: z.number().nullish(),
 
       signingUrl: z.string(),
     }),
@@ -219,6 +226,7 @@ export const ZGenerateDocumentFromTemplateMutationSchema = z.object({
         id: z.number(),
         name: z.string().optional(),
         email: z.string().email().min(1),
+        signingOrder: z.number().nullish(),
       }),
     )
     .refine(
@@ -237,6 +245,7 @@ export const ZGenerateDocumentFromTemplateMutationSchema = z.object({
       timezone: z.string(),
       dateFormat: z.string(),
       redirectUrl: ZUrlSchema,
+      signingOrder: z.nativeEnum(DocumentSigningOrder).optional(),
     })
     .partial()
     .optional(),
@@ -263,6 +272,7 @@ export const ZGenerateDocumentFromTemplateMutationResponseSchema = z.object({
       email: z.string().email().min(1),
       token: z.string(),
       role: z.nativeEnum(RecipientRole),
+      signingOrder: z.number().nullish(),
 
       signingUrl: z.string(),
     }),
@@ -277,6 +287,7 @@ export const ZCreateRecipientMutationSchema = z.object({
   name: z.string().min(1),
   email: z.string().email().min(1),
   role: z.nativeEnum(RecipientRole).optional().default(RecipientRole.SIGNER),
+  signingOrder: z.number().nullish(),
   authOptions: z
     .object({
       actionAuth: ZRecipientActionAuthTypesSchema.optional(),
@@ -305,6 +316,7 @@ export const ZSuccessfulRecipientResponseSchema = z.object({
   email: z.string().email().min(1),
   name: z.string(),
   role: z.nativeEnum(RecipientRole),
+  signingOrder: z.number().nullish(),
   token: z.string(),
   // !: Not used for now
   // expired: z.string(),
@@ -422,6 +434,7 @@ export const ZTemplateMetaSchema = z.object({
   dateFormat: z.string().nullish(),
   templateId: z.number(),
   redirectUrl: z.string().nullish(),
+  signingOrder: z.nativeEnum(DocumentSigningOrder).nullish().default(DocumentSigningOrder.PARALLEL),
 });
 
 export const ZTemplateSchema = z.object({
@@ -443,6 +456,7 @@ export const ZRecipientSchema = z.object({
   email: z.string().email().min(1),
   name: z.string(),
   token: z.string(),
+  signingOrder: z.number().nullish(),
   documentDeletedAt: z.date().nullish(),
   expired: z.date().nullish(),
   signedAt: z.date().nullish(),
@@ -496,6 +510,7 @@ export const ZTemplateWithDataSchema = ZTemplateSchema.extend({
     id: true,
     email: true,
     name: true,
+    signingOrder: true,
     authOptions: true,
     role: true,
   }).array(),