feat: add template enhancements (#1154)

## Description

General enhancements for templates.

## Changes Made

Added the following changes to the template flow:
- Allow adding document meta settings
- Allow adding email settings
- Allow adding document access & action authentication
- Allow adding recipient action authentication
- Save the state between template steps similar to how it works for
documents

Other changes:
- Extract common fields between document and template flows
- Remove the title field from "Use template" since we now have it as
part of the template flow
- Add new API endpoint for generating templates

## Testing Performed

Added E2E tests for templates and creating documents from templates

packages/api/v1/contract.ts

@@ -12,6 +12,8 @@ import {
   ZDeleteFieldMutationSchema,
   ZDeleteRecipientMutationSchema,
   ZDownloadDocumentSuccessfulSchema,
+  ZGenerateDocumentFromTemplateMutationResponseSchema,
+  ZGenerateDocumentFromTemplateMutationSchema,
   ZGetDocumentsQuerySchema,
   ZSendDocumentForSigningMutationSchema,
   ZSuccessfulDocumentResponseSchema,
@@ -85,6 +87,24 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Create a new document from an existing template',
+      deprecated: true,
+      description: `This has been deprecated in favour of "/api/v1/templates/:templateId/generate-document". You may face unpredictable behavior using this endpoint as it is no longer maintained.`,
+    },
+
+    generateDocumentFromTemplate: {
+      method: 'POST',
+      path: '/api/v1/templates/:templateId/generate-document',
+      body: ZGenerateDocumentFromTemplateMutationSchema,
+      responses: {
+        200: ZGenerateDocumentFromTemplateMutationResponseSchema,
+        400: ZUnsuccessfulResponseSchema,
+        401: ZUnsuccessfulResponseSchema,
+        404: ZUnsuccessfulResponseSchema,
+        500: ZUnsuccessfulResponseSchema,
+      },
+      summary: 'Create a new document from an existing template',
+      description:
+        'Create a new document from an existing template. Passing in values for title and meta will override the original values defined in the template. If you do not pass in values for recipients, it will use the values defined in the template.',
     },
 
     sendDocument: {

packages/api/v1/implementation.ts

@@ -1,6 +1,7 @@
 import { createNextRoute } from '@ts-rest/next';
 
 import { getServerLimits } from '@documenso/ee/server-only/limits/server';
+import { AppError } from '@documenso/lib/errors/app-error';
 import { createDocumentData } from '@documenso/lib/server-only/document-data/create-document-data';
 import { upsertDocumentMeta } from '@documenso/lib/server-only/document-meta/upsert-document-meta';
 import { createDocument } from '@documenso/lib/server-only/document/create-document';
@@ -19,6 +20,8 @@ import { getRecipientById } from '@documenso/lib/server-only/recipient/get-recip
 import { getRecipientsForDocument } from '@documenso/lib/server-only/recipient/get-recipients-for-document';
 import { setRecipientsForDocument } from '@documenso/lib/server-only/recipient/set-recipients-for-document';
 import { updateRecipient } from '@documenso/lib/server-only/recipient/update-recipient';
+import type { CreateDocumentFromTemplateResponse } from '@documenso/lib/server-only/template/create-document-from-template';
+import { createDocumentFromTemplate } from '@documenso/lib/server-only/template/create-document-from-template';
 import { createDocumentFromTemplateLegacy } from '@documenso/lib/server-only/template/create-document-from-template-legacy';
 import { extractNextApiRequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
 import { getFile } from '@documenso/lib/universal/upload/get-file';
@@ -351,6 +354,85 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
     };
   }),
 
+  generateDocumentFromTemplate: authenticatedMiddleware(async (args, user, team) => {
+    const { body, params } = args;
+
+    const { remaining } = await getServerLimits({ email: user.email, teamId: team?.id });
+
+    if (remaining.documents <= 0) {
+      return {
+        status: 400,
+        body: {
+          message: 'You have reached the maximum number of documents allowed for this month',
+        },
+      };
+    }
+
+    const templateId = Number(params.templateId);
+
+    let document: CreateDocumentFromTemplateResponse | null = null;
+
+    try {
+      document = await createDocumentFromTemplate({
+        templateId,
+        userId: user.id,
+        teamId: team?.id,
+        recipients: body.recipients,
+        override: {
+          title: body.title,
+          ...body.meta,
+        },
+      });
+    } catch (err) {
+      return AppError.toRestAPIError(err);
+    }
+
+    if (body.formValues) {
+      const fileName = document.title.endsWith('.pdf') ? document.title : `${document.title}.pdf`;
+
+      const pdf = await getFile(document.documentData);
+
+      const prefilled = await insertFormValuesInPdf({
+        pdf: Buffer.from(pdf),
+        formValues: body.formValues,
+      });
+
+      const newDocumentData = await putPdfFile({
+        name: fileName,
+        type: 'application/pdf',
+        arrayBuffer: async () => Promise.resolve(prefilled),
+      });
+
+      await updateDocument({
+        documentId: document.id,
+        userId: user.id,
+        teamId: team?.id,
+        data: {
+          formValues: body.formValues,
+          documentData: {
+            connect: {
+              id: newDocumentData.id,
+            },
+          },
+        },
+      });
+    }
+
+    return {
+      status: 200,
+      body: {
+        documentId: document.id,
+        recipients: document.Recipient.map((recipient) => ({
+          recipientId: recipient.id,
+          name: recipient.name,
+          email: recipient.email,
+          token: recipient.token,
+          role: recipient.role,
+        })),
+      },
+    };
+  }),
+
   sendDocument: authenticatedMiddleware(async (args, user, team) => {
     const { id } = args.params;
 

packages/api/v1/schema.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 
+import { ZUrlSchema } from '@documenso/lib/schemas/common';
 import {
   FieldType,
   ReadStatus,
@@ -141,6 +142,59 @@ export type TCreateDocumentFromTemplateMutationResponseSchema = z.infer<
   typeof ZCreateDocumentFromTemplateMutationResponseSchema
 >;
 
+export const ZGenerateDocumentFromTemplateMutationSchema = z.object({
+  title: z.string().optional(),
+  recipients: z
+    .array(
+      z.object({
+        id: z.number(),
+        name: z.string().optional(),
+        email: z.string().email().min(1),
+      }),
+    )
+    .refine(
+      (schema) => {
+        const emails = schema.map((signer) => signer.email.toLowerCase());
+        const ids = schema.map((signer) => signer.id);
+
+        return new Set(emails).size === emails.length && new Set(ids).size === ids.length;
+      },
+      { message: 'Recipient IDs and emails must be unique' },
+    ),
+  meta: z
+    .object({
+      subject: z.string(),
+      message: z.string(),
+      timezone: z.string(),
+      dateFormat: z.string(),
+      redirectUrl: ZUrlSchema,
+    })
+    .partial()
+    .optional(),
+  formValues: z.record(z.string(), z.union([z.string(), z.boolean(), z.number()])).optional(),
+});
+
+export type TGenerateDocumentFromTemplateMutationSchema = z.infer<
+  typeof ZGenerateDocumentFromTemplateMutationSchema
+>;
+
+export const ZGenerateDocumentFromTemplateMutationResponseSchema = z.object({
+  documentId: z.number(),
+  recipients: z.array(
+    z.object({
+      recipientId: z.number(),
+      name: z.string(),
+      email: z.string().email().min(1),
+      token: z.string(),
+      role: z.nativeEnum(RecipientRole),
+    }),
+  ),
+});
+
+export type TGenerateDocumentFromTemplateMutationResponseSchema = z.infer<
+  typeof ZGenerateDocumentFromTemplateMutationResponseSchema
+>;
+
 export const ZCreateRecipientMutationSchema = z.object({
   name: z.string().min(1),
   email: z.string().email().min(1),