feat: add envelopes api (#2105)

packages/trpc/server/document-router/create-document-formdata.ts

@@ -0,0 +1,136 @@
+import { EnvelopeType } from '@prisma/client';
+
+import { getServerLimits } from '@documenso/ee/server-only/limits/server';
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { createEnvelope } from '@documenso/lib/server-only/envelope/create-envelope';
+import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
+import { mapSecondaryIdToDocumentId } from '@documenso/lib/utils/envelope';
+import { prisma } from '@documenso/prisma';
+
+import { authenticatedProcedure } from '../trpc';
+import {
+  ZCreateDocumentFormDataRequestSchema,
+  ZCreateDocumentFormDataResponseSchema,
+  createDocumentFormDataMeta,
+} from './create-document-formdata.types';
+
+/**
+ * Temporary endpoint for V2 Beta until we allow passthrough documents on create.
+ *
+ * @public
+ */
+export const createDocumentFormDataRoute = authenticatedProcedure
+  .meta(createDocumentFormDataMeta)
+  .input(ZCreateDocumentFormDataRequestSchema)
+  .output(ZCreateDocumentFormDataResponseSchema)
+  .mutation(async ({ input, ctx }) => {
+    const { teamId, user } = ctx;
+
+    const { payload, file } = input;
+
+    const {
+      title,
+      externalId,
+      visibility,
+      globalAccessAuth,
+      globalActionAuth,
+      recipients,
+      meta,
+      folderId,
+      attachments,
+    } = payload;
+
+    const { remaining } = await getServerLimits({ userId: user.id, teamId });
+
+    if (remaining.documents <= 0) {
+      throw new AppError(AppErrorCode.LIMIT_EXCEEDED, {
+        message: 'You have reached your document limit for this month. Please upgrade your plan.',
+        statusCode: 400,
+      });
+    }
+
+    const documentData = await putPdfFileServerSide(file);
+
+    const createdEnvelope = await createEnvelope({
+      userId: ctx.user.id,
+      teamId,
+      normalizePdf: false, // Not normalizing because of presigned URL.
+      internalVersion: 1,
+      data: {
+        type: EnvelopeType.DOCUMENT,
+        title,
+        externalId,
+        visibility,
+        globalAccessAuth,
+        globalActionAuth,
+        recipients: (recipients || []).map((recipient) => ({
+          ...recipient,
+          fields: (recipient.fields || []).map((field) => ({
+            ...field,
+            page: field.pageNumber,
+            positionX: field.pageX,
+            positionY: field.pageY,
+            documentDataId: documentData.id,
+          })),
+        })),
+        folderId,
+        envelopeItems: [
+          {
+            // If you ever allow more than 1 in this endpoint, make sure to use `maximumEnvelopeItemCount` to limit it.
+            documentDataId: documentData.id,
+          },
+        ],
+      },
+      attachments,
+      meta: {
+        ...meta,
+        emailSettings: meta?.emailSettings ?? undefined,
+      },
+      requestMetadata: ctx.metadata,
+    });
+
+    const envelopeItems = await prisma.envelopeItem.findMany({
+      where: {
+        envelopeId: createdEnvelope.id,
+      },
+      include: {
+        documentData: true,
+      },
+    });
+
+    const legacyDocumentId = mapSecondaryIdToDocumentId(createdEnvelope.secondaryId);
+
+    const firstDocumentData = envelopeItems[0].documentData;
+
+    if (!firstDocumentData) {
+      throw new Error('Document data not found');
+    }
+
+    return {
+      document: {
+        ...createdEnvelope,
+        envelopeId: createdEnvelope.id,
+        documentDataId: firstDocumentData.id,
+        documentData: {
+          ...firstDocumentData,
+          envelopeItemId: envelopeItems[0].id,
+        },
+        documentMeta: {
+          ...createdEnvelope.documentMeta,
+          documentId: legacyDocumentId,
+        },
+        id: legacyDocumentId,
+        fields: createdEnvelope.fields.map((field) => ({
+          ...field,
+          documentId: legacyDocumentId,
+          templateId: null,
+        })),
+        recipients: createdEnvelope.recipients.map((recipient) => ({
+          ...recipient,
+          documentId: legacyDocumentId,
+          templateId: null,
+        })),
+      },
+      folder: createdEnvelope.folder, // Todo: Remove this prior to api-v2 release.
+    };
+  });

packages/trpc/server/document-router/create-document-formdata.types.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { zfd } from 'zod-form-data';
+
+import { ZDocumentSchema } from '@documenso/lib/types/document';
+import {
+  ZDocumentAccessAuthTypesSchema,
+  ZDocumentActionAuthTypesSchema,
+} from '@documenso/lib/types/document-auth';
+import { ZDocumentFormValuesSchema } from '@documenso/lib/types/document-form-values';
+import { ZDocumentMetaCreateSchema } from '@documenso/lib/types/document-meta';
+import { ZEnvelopeAttachmentTypeSchema } from '@documenso/lib/types/envelope-attachment';
+import {
+  ZFieldHeightSchema,
+  ZFieldPageNumberSchema,
+  ZFieldPageXSchema,
+  ZFieldPageYSchema,
+  ZFieldWidthSchema,
+} from '@documenso/lib/types/field';
+import { ZFieldAndMetaSchema } from '@documenso/lib/types/field-meta';
+
+import { zodFormData } from '../../utils/zod-form-data';
+import { ZCreateRecipientSchema } from '../recipient-router/schema';
+import type { TrpcRouteMeta } from '../trpc';
+import {
+  ZDocumentExternalIdSchema,
+  ZDocumentTitleSchema,
+  ZDocumentVisibilitySchema,
+} from './schema';
+
+export const createDocumentFormDataMeta: TrpcRouteMeta = {
+  openapi: {
+    method: 'POST',
+    path: '/document/create/formdata',
+    contentTypes: ['multipart/form-data'],
+    summary: 'Create document',
+    description: 'Create a document using form data.',
+    tags: ['Document'],
+  },
+};
+
+const ZCreateDocumentFormDataPayloadRequestSchema = z.object({
+  title: ZDocumentTitleSchema,
+  externalId: ZDocumentExternalIdSchema.optional(),
+  visibility: ZDocumentVisibilitySchema.optional(),
+  globalAccessAuth: z.array(ZDocumentAccessAuthTypesSchema).optional(),
+  globalActionAuth: z.array(ZDocumentActionAuthTypesSchema).optional(),
+  formValues: ZDocumentFormValuesSchema.optional(),
+  folderId: z
+    .string()
+    .describe(
+      'The ID of the folder to create the document in. If not provided, the document will be created in the root folder.',
+    )
+    .optional(),
+  recipients: z
+    .array(
+      ZCreateRecipientSchema.extend({
+        fields: ZFieldAndMetaSchema.and(
+          z.object({
+            pageNumber: ZFieldPageNumberSchema,
+            pageX: ZFieldPageXSchema,
+            pageY: ZFieldPageYSchema,
+            width: ZFieldWidthSchema,
+            height: ZFieldHeightSchema,
+          }),
+        )
+          .array()
+          .optional(),
+      }),
+    )
+
+    .optional(),
+  attachments: z
+    .array(
+      z.object({
+        label: z.string().min(1, 'Label is required'),
+        data: z.string().url('Must be a valid URL'),
+        type: ZEnvelopeAttachmentTypeSchema.optional().default('link'),
+      }),
+    )
+    .optional(),
+  meta: ZDocumentMetaCreateSchema.optional(),
+});
+
+// !: Can't use zfd.formData() here because it receives `undefined`
+// !: somewhere in the pipeline of our openapi schema generation and throws
+// !: an error.
+export const ZCreateDocumentFormDataRequestSchema = zodFormData({
+  payload: zfd.json(ZCreateDocumentFormDataPayloadRequestSchema),
+  file: zfd.file(),
+});
+
+export const ZCreateDocumentFormDataResponseSchema = z.object({
+  document: ZDocumentSchema,
+});
+
+export type TCreateDocumentFormDataRequest = z.infer<typeof ZCreateDocumentFormDataRequestSchema>;
+export type TCreateDocumentFormDataResponse = z.infer<typeof ZCreateDocumentFormDataResponseSchema>;

packages/trpc/server/document-router/create-document.ts

@@ -3,20 +3,28 @@ import { EnvelopeType } from '@prisma/client';
 import { getServerLimits } from '@documenso/ee/server-only/limits/server';
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
 import { createEnvelope } from '@documenso/lib/server-only/envelope/create-envelope';
+import { putNormalizedPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
 import { mapSecondaryIdToDocumentId } from '@documenso/lib/utils/envelope';
 
 import { authenticatedProcedure } from '../trpc';
 import {
   ZCreateDocumentRequestSchema,
   ZCreateDocumentResponseSchema,
+  createDocumentMeta,
 } from './create-document.types';
 
 export const createDocumentRoute = authenticatedProcedure
-  .input(ZCreateDocumentRequestSchema) // Note: Before releasing this to public, update the response schema to be correct.
+  .meta(createDocumentMeta)
+  .input(ZCreateDocumentRequestSchema)
   .output(ZCreateDocumentResponseSchema)
   .mutation(async ({ input, ctx }) => {
     const { user, teamId } = ctx;
-    const { title, documentDataId, timezone, folderId, attachments } = input;
+
+    const { payload, file } = input;
+
+    const { title, timezone, folderId, attachments } = payload;
+
+    const { id: documentDataId } = await putNormalizedPdfFileServerSide(file);
 
     ctx.logger.info({
       input: {
@@ -55,6 +63,7 @@ export const createDocumentRoute = authenticatedProcedure
     });
 
     return {
-      legacyDocumentId: mapSecondaryIdToDocumentId(document.secondaryId),
+      envelopeId: document.id,
+      id: mapSecondaryIdToDocumentId(document.secondaryId),
     };
   });

packages/trpc/server/document-router/create-document.types.ts

@@ -1,23 +1,26 @@
 import { z } from 'zod';
+import { zfd } from 'zod-form-data';
 
 import { ZDocumentMetaTimezoneSchema } from '@documenso/lib/types/document-meta';
 import { ZEnvelopeAttachmentTypeSchema } from '@documenso/lib/types/envelope-attachment';
 
+import { zodFormData } from '../../utils/zod-form-data';
+import type { TrpcRouteMeta } from '../trpc';
 import { ZDocumentTitleSchema } from './schema';
 
-// Currently not in use until we allow passthrough documents on create.
-// export const createDocumentMeta: TrpcRouteMeta = {
-//   openapi: {
-//     method: 'POST',
-//     path: '/document/create',
-//     summary: 'Create document',
-//     tags: ['Document'],
-//   },
-// };
+export const createDocumentMeta: TrpcRouteMeta = {
+  openapi: {
+    method: 'POST',
+    path: '/document/create',
+    contentTypes: ['multipart/form-data'],
+    summary: 'Create document',
+    description: 'Create a document using form data.',
+    tags: ['Document'],
+  },
+};
 
-export const ZCreateDocumentRequestSchema = z.object({
+export const ZCreateDocumentPayloadSchema = z.object({
   title: ZDocumentTitleSchema,
-  documentDataId: z.string().min(1),
   timezone: ZDocumentMetaTimezoneSchema.optional(),
   folderId: z.string().describe('The ID of the folder to create the document in').optional(),
   attachments: z
@@ -31,9 +34,16 @@ export const ZCreateDocumentRequestSchema = z.object({
     .optional(),
 });
 
-export const ZCreateDocumentResponseSchema = z.object({
-  legacyDocumentId: z.number(),
+export const ZCreateDocumentRequestSchema = zodFormData({
+  payload: zfd.json(ZCreateDocumentPayloadSchema),
+  file: zfd.file(),
 });
 
+export const ZCreateDocumentResponseSchema = z.object({
+  envelopeId: z.string(),
+  id: z.number(),
+});
+
+export type TCreateDocumentPayloadSchema = z.infer<typeof ZCreateDocumentPayloadSchema>;
 export type TCreateDocumentRequest = z.infer<typeof ZCreateDocumentRequestSchema>;
 export type TCreateDocumentResponse = z.infer<typeof ZCreateDocumentResponseSchema>;

packages/trpc/server/document-router/download-document-beta.ts

@@ -0,0 +1,96 @@
+import type { DocumentData } from '@prisma/client';
+import { DocumentDataType, EnvelopeType } from '@prisma/client';
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { getEnvelopeById } from '@documenso/lib/server-only/envelope/get-envelope-by-id';
+import { getPresignGetUrl } from '@documenso/lib/universal/upload/server-actions';
+import { isDocumentCompleted } from '@documenso/lib/utils/document';
+
+import { authenticatedProcedure } from '../trpc';
+import {
+  ZDownloadDocumentRequestSchema,
+  ZDownloadDocumentResponseSchema,
+  downloadDocumentMeta,
+} from './download-document-beta.types';
+
+export const downloadDocumentBetaRoute = authenticatedProcedure
+  .meta(downloadDocumentMeta)
+  .input(ZDownloadDocumentRequestSchema)
+  .output(ZDownloadDocumentResponseSchema)
+  .query(async ({ input, ctx }) => {
+    const { teamId, user } = ctx;
+    const { documentId, version } = input;
+
+    ctx.logger.info({
+      input: {
+        documentId,
+        version,
+      },
+    });
+
+    const envelope = await getEnvelopeById({
+      id: {
+        type: 'documentId',
+        id: documentId,
+      },
+      type: EnvelopeType.DOCUMENT,
+      userId: user.id,
+      teamId,
+    });
+
+    // This error is done AFTER the get envelope so we can test access controls without S3.
+    if (process.env.NEXT_PUBLIC_UPLOAD_TRANSPORT !== 's3') {
+      throw new AppError(AppErrorCode.INVALID_REQUEST, {
+        message: 'Document downloads are only available when S3 storage is configured.',
+      });
+    }
+
+    const documentData: DocumentData | undefined = envelope.envelopeItems[0]?.documentData;
+
+    if (envelope.envelopeItems.length !== 1 || !documentData) {
+      throw new AppError(AppErrorCode.INVALID_REQUEST, {
+        message:
+          'This endpoint only supports documents with a single item. Use envelopes API instead.',
+      });
+    }
+
+    if (documentData.type !== DocumentDataType.S3_PATH) {
+      throw new AppError(AppErrorCode.INVALID_REQUEST, {
+        message: 'Document is not stored in S3 and cannot be downloaded via URL.',
+      });
+    }
+
+    if (version === 'signed' && !isDocumentCompleted(envelope.status)) {
+      throw new AppError(AppErrorCode.INVALID_REQUEST, {
+        message: 'Document is not completed yet.',
+      });
+    }
+
+    try {
+      const data =
+        version === 'original' ? documentData.initialData || documentData.data : documentData.data;
+
+      const { url } = await getPresignGetUrl(data);
+
+      const baseTitle = envelope.title.replace(/\.pdf$/, '');
+      const suffix = version === 'signed' ? '_signed.pdf' : '.pdf';
+      const filename = `${baseTitle}${suffix}`;
+
+      return {
+        downloadUrl: url,
+        filename,
+        contentType: 'application/pdf',
+      };
+    } catch (error) {
+      ctx.logger.error({
+        error,
+        message: 'Failed to generate download URL',
+        documentId,
+        version,
+      });
+
+      throw new AppError(AppErrorCode.UNKNOWN_ERROR, {
+        message: 'Failed to generate download URL',
+      });
+    }
+  });

packages/trpc/server/document-router/download-document-beta.types.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+import type { TrpcRouteMeta } from '../trpc';
+
+export const downloadDocumentMeta: TrpcRouteMeta = {
+  openapi: {
+    method: 'GET',
+    path: '/document/{documentId}/download-beta',
+    summary: 'Download document (beta)',
+    description: 'Get a pre-signed download URL for the original or signed version of a document',
+    tags: ['Document'],
+  },
+};
+
+export const ZDownloadDocumentRequestSchema = z.object({
+  documentId: z.number().describe('The ID of the document to download.'),
+  version: z
+    .enum(['original', 'signed'])
+    .describe(
+      'The version of the document to download. "signed" returns the completed document with signatures, "original" returns the original uploaded document.',
+    )
+    .default('signed'),
+});
+
+export const ZDownloadDocumentResponseSchema = z.object({
+  downloadUrl: z.string().describe('Pre-signed URL for downloading the PDF file'),
+  filename: z.string().describe('The filename of the PDF file'),
+  contentType: z.string().describe('MIME type of the file'),
+});
+
+export type TDownloadDocumentRequest = z.infer<typeof ZDownloadDocumentRequestSchema>;
+export type TDownloadDocumentResponse = z.infer<typeof ZDownloadDocumentResponseSchema>;

packages/trpc/server/document-router/download-document.ts

@@ -1,11 +1,3 @@
-import type { DocumentData } from '@prisma/client';
-import { DocumentDataType, EnvelopeType } from '@prisma/client';
-
-import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
-import { getEnvelopeById } from '@documenso/lib/server-only/envelope/get-envelope-by-id';
-import { getPresignGetUrl } from '@documenso/lib/universal/upload/server-actions';
-import { isDocumentCompleted } from '@documenso/lib/utils/document';
-
 import { authenticatedProcedure } from '../trpc';
 import {
   ZDownloadDocumentRequestSchema,
@@ -17,8 +9,7 @@ export const downloadDocumentRoute = authenticatedProcedure
   .meta(downloadDocumentMeta)
   .input(ZDownloadDocumentRequestSchema)
   .output(ZDownloadDocumentResponseSchema)
-  .query(async ({ input, ctx }) => {
-    const { teamId, user } = ctx;
+  .query(({ input, ctx }) => {
     const { documentId, version } = input;
 
     ctx.logger.info({
@@ -28,69 +19,5 @@ export const downloadDocumentRoute = authenticatedProcedure
       },
     });
 
-    const envelope = await getEnvelopeById({
-      id: {
-        type: 'documentId',
-        id: documentId,
-      },
-      type: EnvelopeType.DOCUMENT,
-      userId: user.id,
-      teamId,
-    });
-
-    // This error is done AFTER the get envelope so we can test access controls without S3.
-    if (process.env.NEXT_PUBLIC_UPLOAD_TRANSPORT !== 's3') {
-      throw new AppError(AppErrorCode.INVALID_REQUEST, {
-        message: 'Document downloads are only available when S3 storage is configured.',
-      });
-    }
-
-    const documentData: DocumentData | undefined = envelope.envelopeItems[0]?.documentData;
-
-    if (envelope.envelopeItems.length !== 1 || !documentData) {
-      throw new AppError(AppErrorCode.INVALID_REQUEST, {
-        message:
-          'This endpoint only supports documents with a single item. Use envelopes API instead.',
-      });
-    }
-
-    if (documentData.type !== DocumentDataType.S3_PATH) {
-      throw new AppError(AppErrorCode.INVALID_REQUEST, {
-        message: 'Document is not stored in S3 and cannot be downloaded via URL.',
-      });
-    }
-
-    if (version === 'signed' && !isDocumentCompleted(envelope.status)) {
-      throw new AppError(AppErrorCode.INVALID_REQUEST, {
-        message: 'Document is not completed yet.',
-      });
-    }
-
-    try {
-      const data =
-        version === 'original' ? documentData.initialData || documentData.data : documentData.data;
-
-      const { url } = await getPresignGetUrl(data);
-
-      const baseTitle = envelope.title.replace(/\.pdf$/, '');
-      const suffix = version === 'signed' ? '_signed.pdf' : '.pdf';
-      const filename = `${baseTitle}${suffix}`;
-
-      return {
-        downloadUrl: url,
-        filename,
-        contentType: 'application/pdf',
-      };
-    } catch (error) {
-      ctx.logger.error({
-        error,
-        message: 'Failed to generate download URL',
-        documentId,
-        version,
-      });
-
-      throw new AppError(AppErrorCode.UNKNOWN_ERROR, {
-        message: 'Failed to generate download URL',
-      });
-    }
+    throw new Error('NOT_IMPLEMENTED');
   });

packages/trpc/server/document-router/download-document.types.ts

@@ -5,10 +5,12 @@ import type { TrpcRouteMeta } from '../trpc';
 export const downloadDocumentMeta: TrpcRouteMeta = {
   openapi: {
     method: 'GET',
-    path: '/document/{documentId}/download-beta',
-    summary: 'Download document (beta)',
-    description: 'Get a pre-signed download URL for the original or signed version of a document',
+    path: '/document/{documentId}/download',
+    summary: 'Download document',
     tags: ['Document'],
+    responseHeaders: z.object({
+      'Content-Type': z.literal('application/pdf'),
+    }),
   },
 };
 
@@ -22,11 +24,7 @@ export const ZDownloadDocumentRequestSchema = z.object({
     .default('signed'),
 });
 
-export const ZDownloadDocumentResponseSchema = z.object({
-  downloadUrl: z.string().describe('Pre-signed URL for downloading the PDF file'),
-  filename: z.string().describe('The filename of the PDF file'),
-  contentType: z.string().describe('MIME type of the file'),
-});
+export const ZDownloadDocumentResponseSchema = z.instanceof(Uint8Array);
 
 export type TDownloadDocumentRequest = z.infer<typeof ZDownloadDocumentRequestSchema>;
 export type TDownloadDocumentResponse = z.infer<typeof ZDownloadDocumentResponseSchema>;

packages/trpc/server/document-router/find-inbox.ts

@@ -92,6 +92,14 @@ export const findInbox = async ({ userId, page = 1, perPage = 10, orderBy }: Fin
             url: true,
           },
         },
+        envelopeItems: {
+          select: {
+            id: true,
+            envelopeId: true,
+            title: true,
+            order: true,
+          },
+        },
       },
     }),
     prisma.envelope.count({

packages/trpc/server/document-router/router.ts

@@ -5,11 +5,13 @@ import { deleteAttachmentRoute } from './attachment/delete-attachment';
 import { findAttachmentsRoute } from './attachment/find-attachments';
 import { updateAttachmentRoute } from './attachment/update-attachment';
 import { createDocumentRoute } from './create-document';
+import { createDocumentFormDataRoute } from './create-document-formdata';
 import { createDocumentTemporaryRoute } from './create-document-temporary';
 import { deleteDocumentRoute } from './delete-document';
 import { distributeDocumentRoute } from './distribute-document';
 import { downloadDocumentRoute } from './download-document';
 import { downloadDocumentAuditLogsRoute } from './download-document-audit-logs';
+import { downloadDocumentBetaRoute } from './download-document-beta';
 import { downloadDocumentCertificateRoute } from './download-document-certificate';
 import { duplicateDocumentRoute } from './duplicate-document';
 import { findDocumentAuditLogsRoute } from './find-document-audit-logs';
@@ -38,8 +40,10 @@ export const documentRouter = router({
   share: shareDocumentRoute,
 
   // Temporary v2 beta routes to be removed once V2 is fully released.
+  downloadBeta: downloadDocumentBetaRoute,
   download: downloadDocumentRoute,
   createDocumentTemporary: createDocumentTemporaryRoute,
+  createDocumentFormData: createDocumentFormDataRoute,
 
   // Internal document routes for custom frontend requests.
   getDocumentByToken: getDocumentByTokenRoute,