feat: add envelopes api (#2105)

apps/remix/server/api/download/download.ts

@@ -0,0 +1,192 @@
+import { sValidator } from '@hono/standard-validator';
+import { EnvelopeType } from '@prisma/client';
+import { Hono } from 'hono';
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { getEnvelopeById } from '@documenso/lib/server-only/envelope/get-envelope-by-id';
+import { getApiTokenByToken } from '@documenso/lib/server-only/public-api/get-api-token-by-token';
+import { buildTeamWhereQuery } from '@documenso/lib/utils/teams';
+import { prisma } from '@documenso/prisma';
+
+import type { HonoEnv } from '../../router';
+import { handleEnvelopeItemFileRequest } from '../files/files.helpers';
+import {
+  ZDownloadDocumentRequestParamsSchema,
+  ZDownloadEnvelopeItemRequestParamsSchema,
+} from './download.types';
+
+export const downloadRoute = new Hono<HonoEnv>()
+  /**
+   * Download an envelope item by its ID.
+   * Requires API key authentication via Authorization header.
+   */
+  .get(
+    '/envelopeItem/:envelopeItemId/download',
+    sValidator('param', ZDownloadEnvelopeItemRequestParamsSchema),
+    async (c) => {
+      const logger = c.get('logger');
+
+      try {
+        const { envelopeItemId, version } = c.req.valid('param');
+        const authorizationHeader = c.req.header('authorization');
+
+        // Support for both "Authorization: Bearer api_xxx" and "Authorization: api_xxx"
+        const [token] = (authorizationHeader || '').split('Bearer ').filter((s) => s.length > 0);
+
+        if (!token) {
+          throw new AppError(AppErrorCode.UNAUTHORIZED, {
+            message: 'API token was not provided',
+          });
+        }
+
+        const apiToken = await getApiTokenByToken({ token });
+
+        if (apiToken.user.disabled) {
+          throw new AppError(AppErrorCode.UNAUTHORIZED, {
+            message: 'User is disabled',
+          });
+        }
+
+        logger.info({
+          auth: 'api',
+          source: 'apiV2',
+          path: c.req.path,
+          userId: apiToken.user.id,
+          apiTokenId: apiToken.id,
+          envelopeItemId,
+          version,
+        });
+
+        const envelopeItem = await prisma.envelopeItem.findFirst({
+          where: {
+            id: envelopeItemId,
+            envelope: {
+              team: buildTeamWhereQuery({ teamId: apiToken.teamId, userId: apiToken.user.id }),
+            },
+          },
+          include: {
+            envelope: true,
+            documentData: true,
+          },
+        });
+
+        if (!envelopeItem) {
+          return c.json({ error: 'Envelope item not found' }, 404);
+        }
+
+        if (!envelopeItem.documentData) {
+          return c.json({ error: 'Document data not found' }, 404);
+        }
+
+        return await handleEnvelopeItemFileRequest({
+          title: envelopeItem.title,
+          status: envelopeItem.envelope.status,
+          documentData: envelopeItem.documentData,
+          version: version || 'signed',
+          isDownload: true,
+          context: c,
+        });
+      } catch (error) {
+        logger.error(error);
+
+        if (error instanceof AppError) {
+          if (error.code === AppErrorCode.UNAUTHORIZED) {
+            return c.json({ error: error.message }, 401);
+          }
+
+          return c.json({ error: error.message }, 400);
+        }
+
+        return c.json({ error: 'Internal server error' }, 500);
+      }
+    },
+  )
+  /**
+   * Download a document by its ID.
+   * Requires API key authentication via Authorization header.
+   */
+  .get(
+    '/document/:documentId/download',
+    sValidator('param', ZDownloadDocumentRequestParamsSchema),
+    async (c) => {
+      const logger = c.get('logger');
+
+      try {
+        const { documentId, version } = c.req.valid('param');
+        const authorizationHeader = c.req.header('authorization');
+
+        // Support for both "Authorization: Bearer api_xxx" and "Authorization: api_xxx"
+        const [token] = (authorizationHeader || '').split('Bearer ').filter((s) => s.length > 0);
+
+        if (!token) {
+          throw new AppError(AppErrorCode.UNAUTHORIZED, {
+            message: 'API token was not provided',
+          });
+        }
+
+        const apiToken = await getApiTokenByToken({ token });
+
+        if (apiToken.user.disabled) {
+          throw new AppError(AppErrorCode.UNAUTHORIZED, {
+            message: 'User is disabled',
+          });
+        }
+
+        logger.info({
+          auth: 'api',
+          source: 'apiV2',
+          path: c.req.path,
+          userId: apiToken.user.id,
+          apiTokenId: apiToken.id,
+          documentId,
+          version,
+        });
+
+        const envelope = await getEnvelopeById({
+          id: {
+            type: 'documentId',
+            id: documentId,
+          },
+          type: EnvelopeType.DOCUMENT,
+          userId: apiToken.user.id,
+          teamId: apiToken.teamId,
+        }).catch(() => null);
+
+        if (!envelope) {
+          return c.json({ error: 'Document not found' }, 404);
+        }
+
+        // Get the first envelope item (documents have exactly one)
+        const [envelopeItem] = envelope.envelopeItems;
+
+        if (!envelopeItem) {
+          return c.json({ error: 'Document item not found' }, 404);
+        }
+
+        if (!envelopeItem.documentData) {
+          return c.json({ error: 'Document data not found' }, 404);
+        }
+
+        return await handleEnvelopeItemFileRequest({
+          title: envelopeItem.title,
+          status: envelope.status,
+          documentData: envelopeItem.documentData,
+          version: version || 'signed',
+          isDownload: true,
+          context: c,
+        });
+      } catch (error) {
+        logger.error(error);
+
+        if (error instanceof AppError) {
+          if (error.code === AppErrorCode.UNAUTHORIZED) {
+            return c.json({ error: error.message }, 401);
+          }
+
+          return c.json({ error: error.message }, 400);
+        }
+
+        return c.json({ error: 'Internal server error' }, 500);
+      }
+    },
+  );

apps/remix/server/api/download/download.types.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+export const ZDownloadEnvelopeItemRequestParamsSchema = z.object({
+  envelopeItemId: z.string().describe('The ID of the envelope item to download.'),
+  version: z
+    .enum(['original', 'signed'])
+    .optional()
+    .default('signed')
+    .describe(
+      'The version of the envelope item to download. "signed" returns the completed document with signatures, "original" returns the original uploaded document.',
+    ),
+});
+
+export type TDownloadEnvelopeItemRequestParams = z.infer<
+  typeof ZDownloadEnvelopeItemRequestParamsSchema
+>;
+
+export const ZDownloadDocumentRequestParamsSchema = z.object({
+  documentId: z.coerce.number().describe('The ID of the document to download.'),
+  version: z
+    .enum(['original', 'signed'])
+    .optional()
+    .default('signed')
+    .describe(
+      'The version of the document to download. "signed" returns the completed document with signatures, "original" returns the original uploaded document.',
+    ),
+});
+
+export type TDownloadDocumentRequestParams = z.infer<typeof ZDownloadDocumentRequestParamsSchema>;

apps/remix/server/api/files.ts

@@ -1,100 +0,0 @@
-import { PDFDocument } from '@cantoo/pdf-lib';
-import { sValidator } from '@hono/standard-validator';
-import { Hono } from 'hono';
-
-import { APP_DOCUMENT_UPLOAD_SIZE_LIMIT } from '@documenso/lib/constants/app';
-import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
-import { createDocumentData } from '@documenso/lib/server-only/document-data/create-document-data';
-import { putFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
-import {
-  getPresignGetUrl,
-  getPresignPostUrl,
-} from '@documenso/lib/universal/upload/server-actions';
-
-import type { HonoEnv } from '../router';
-import {
-  type TGetPresignedGetUrlResponse,
-  type TGetPresignedPostUrlResponse,
-  ZGetPresignedGetUrlRequestSchema,
-  ZGetPresignedPostUrlRequestSchema,
-  ZUploadPdfRequestSchema,
-} from './files.types';
-
-export const filesRoute = new Hono<HonoEnv>()
-  /**
-   * Uploads a document file to the appropriate storage location and creates
-   * a document data record.
-   */
-  .post('/upload-pdf', sValidator('form', ZUploadPdfRequestSchema), async (c) => {
-    try {
-      const { file } = c.req.valid('form');
-
-      if (!file) {
-        return c.json({ error: 'No file provided' }, 400);
-      }
-
-      // Todo: (RR7) This is new.
-      // Add file size validation.
-      // Convert MB to bytes (1 MB = 1024 * 1024 bytes)
-      const MAX_FILE_SIZE = APP_DOCUMENT_UPLOAD_SIZE_LIMIT * 1024 * 1024;
-
-      if (file.size > MAX_FILE_SIZE) {
-        return c.json({ error: 'File too large' }, 400);
-      }
-
-      const arrayBuffer = await file.arrayBuffer();
-
-      const pdf = await PDFDocument.load(arrayBuffer).catch((e) => {
-        console.error(`PDF upload parse error: ${e.message}`);
-
-        throw new AppError('INVALID_DOCUMENT_FILE');
-      });
-
-      if (pdf.isEncrypted) {
-        throw new AppError('INVALID_DOCUMENT_FILE');
-      }
-
-      // Todo: (RR7) Test this.
-      if (!file.name.endsWith('.pdf')) {
-        Object.defineProperty(file, 'name', {
-          writable: true,
-          value: `${file.name}.pdf`,
-        });
-      }
-
-      const { type, data } = await putFileServerSide(file);
-
-      const result = await createDocumentData({ type, data });
-
-      return c.json(result);
-    } catch (error) {
-      console.error('Upload failed:', error);
-      return c.json({ error: 'Upload failed' }, 500);
-    }
-  })
-  .post('/presigned-get-url', sValidator('json', ZGetPresignedGetUrlRequestSchema), async (c) => {
-    const { key } = await c.req.json();
-
-    try {
-      const { url } = await getPresignGetUrl(key || '');
-
-      return c.json({ url } satisfies TGetPresignedGetUrlResponse);
-    } catch (err) {
-      console.error(err);
-
-      throw new AppError(AppErrorCode.UNKNOWN_ERROR);
-    }
-  })
-  .post('/presigned-post-url', sValidator('json', ZGetPresignedPostUrlRequestSchema), async (c) => {
-    const { fileName, contentType } = c.req.valid('json');
-
-    try {
-      const { key, url } = await getPresignPostUrl(fileName, contentType);
-
-      return c.json({ key, url } satisfies TGetPresignedPostUrlResponse);
-    } catch (err) {
-      console.error(err);
-
-      throw new AppError(AppErrorCode.UNKNOWN_ERROR);
-    }
-  });

apps/remix/server/api/files.types.ts

@@ -1,38 +0,0 @@
-import { z } from 'zod';
-
-import DocumentDataSchema from '@documenso/prisma/generated/zod/modelSchema/DocumentDataSchema';
-
-export const ZUploadPdfRequestSchema = z.object({
-  file: z.instanceof(File),
-});
-
-export const ZUploadPdfResponseSchema = DocumentDataSchema.pick({
-  type: true,
-  id: true,
-});
-
-export type TUploadPdfRequest = z.infer<typeof ZUploadPdfRequestSchema>;
-export type TUploadPdfResponse = z.infer<typeof ZUploadPdfResponseSchema>;
-
-export const ZGetPresignedPostUrlRequestSchema = z.object({
-  fileName: z.string().min(1),
-  contentType: z.string().min(1),
-});
-
-export const ZGetPresignedPostUrlResponseSchema = z.object({
-  key: z.string().min(1),
-  url: z.string().min(1),
-});
-
-export const ZGetPresignedGetUrlRequestSchema = z.object({
-  key: z.string().min(1),
-});
-
-export const ZGetPresignedGetUrlResponseSchema = z.object({
-  url: z.string().min(1),
-});
-
-export type TGetPresignedPostUrlRequest = z.infer<typeof ZGetPresignedPostUrlRequestSchema>;
-export type TGetPresignedPostUrlResponse = z.infer<typeof ZGetPresignedPostUrlResponseSchema>;
-export type TGetPresignedGetUrlRequest = z.infer<typeof ZGetPresignedGetUrlRequestSchema>;
-export type TGetPresignedGetUrlResponse = z.infer<typeof ZGetPresignedGetUrlResponseSchema>;

apps/remix/server/api/files/files.helpers.ts

@@ -0,0 +1,81 @@
+import { type DocumentDataType, DocumentStatus } from '@prisma/client';
+import { type Context } from 'hono';
+
+import { sha256 } from '@documenso/lib/universal/crypto';
+import { getFileServerSide } from '@documenso/lib/universal/upload/get-file.server';
+
+import type { HonoEnv } from '../../router';
+
+type HandleEnvelopeItemFileRequestOptions = {
+  title: string;
+  status: DocumentStatus;
+  documentData: {
+    type: DocumentDataType;
+    data: string;
+    initialData: string;
+  };
+  version: 'signed' | 'original';
+  isDownload: boolean;
+  context: Context<HonoEnv>;
+};
+
+/**
+ * Helper function to handle envelope item file requests (both view and download)
+ */
+export const handleEnvelopeItemFileRequest = async ({
+  title,
+  status,
+  documentData,
+  version,
+  isDownload,
+  context: c,
+}: HandleEnvelopeItemFileRequestOptions) => {
+  const documentDataToUse = version === 'signed' ? documentData.data : documentData.initialData;
+
+  const etag = Buffer.from(sha256(documentDataToUse)).toString('hex');
+
+  if (c.req.header('If-None-Match') === etag) {
+    return c.body(null, 304);
+  }
+
+  const file = await getFileServerSide({
+    type: documentData.type,
+    data: documentDataToUse,
+  }).catch((error) => {
+    console.error(error);
+
+    return null;
+  });
+
+  if (!file) {
+    return c.json({ error: 'File not found' }, 404);
+  }
+
+  c.header('Content-Type', 'application/pdf');
+  c.header('ETag', etag);
+
+  if (!isDownload) {
+    if (status === DocumentStatus.COMPLETED) {
+      c.header('Cache-Control', 'public, max-age=31536000, immutable');
+    } else {
+      // Set a tiny 1 minute cache, with must-revalidate to ensure the client always checks for updates.
+      c.header('Cache-Control', 'public, max-age=60, must-revalidate');
+    }
+  }
+
+  if (isDownload) {
+    // Generate filename following the pattern from envelope-download-dialog.tsx
+    const baseTitle = title.replace(/\.pdf$/, '');
+    const suffix = version === 'signed' ? '_signed.pdf' : '.pdf';
+    const filename = `${baseTitle}${suffix}`;
+
+    c.header('Content-Disposition', `attachment; filename="${filename}"`);
+
+    // For downloads, prevent caching to ensure fresh data
+    c.header('Cache-Control', 'no-cache, no-store, must-revalidate');
+    c.header('Pragma', 'no-cache');
+    c.header('Expires', '0');
+  }
+
+  return c.body(file);
+};

apps/remix/server/api/files/files.ts

@@ -0,0 +1,307 @@
+import { sValidator } from '@hono/standard-validator';
+import type { Prisma } from '@prisma/client';
+import { Hono } from 'hono';
+
+import { getOptionalSession } from '@documenso/auth/server/lib/utils/get-session';
+import { APP_DOCUMENT_UPLOAD_SIZE_LIMIT } from '@documenso/lib/constants/app';
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { getTeamById } from '@documenso/lib/server-only/team/get-team';
+import { putNormalizedPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
+import { getPresignPostUrl } from '@documenso/lib/universal/upload/server-actions';
+import { prisma } from '@documenso/prisma';
+
+import type { HonoEnv } from '../../router';
+import { handleEnvelopeItemFileRequest } from './files.helpers';
+import {
+  type TGetPresignedPostUrlResponse,
+  ZGetEnvelopeItemFileDownloadRequestParamsSchema,
+  ZGetEnvelopeItemFileRequestParamsSchema,
+  ZGetEnvelopeItemFileTokenDownloadRequestParamsSchema,
+  ZGetEnvelopeItemFileTokenRequestParamsSchema,
+  ZGetPresignedPostUrlRequestSchema,
+  ZUploadPdfRequestSchema,
+} from './files.types';
+
+export const filesRoute = new Hono<HonoEnv>()
+  /**
+   * Uploads a document file to the appropriate storage location and creates
+   * a document data record.
+   */
+  .post('/upload-pdf', sValidator('form', ZUploadPdfRequestSchema), async (c) => {
+    try {
+      const { file } = c.req.valid('form');
+
+      if (!file) {
+        return c.json({ error: 'No file provided' }, 400);
+      }
+
+      // Todo: (RR7) This is new.
+      // Add file size validation.
+      // Convert MB to bytes (1 MB = 1024 * 1024 bytes)
+      const MAX_FILE_SIZE = APP_DOCUMENT_UPLOAD_SIZE_LIMIT * 1024 * 1024;
+
+      if (file.size > MAX_FILE_SIZE) {
+        return c.json({ error: 'File too large' }, 400);
+      }
+
+      const result = await putNormalizedPdfFileServerSide(file);
+
+      return c.json(result);
+    } catch (error) {
+      console.error('Upload failed:', error);
+      return c.json({ error: 'Upload failed' }, 500);
+    }
+  })
+  .post('/presigned-post-url', sValidator('json', ZGetPresignedPostUrlRequestSchema), async (c) => {
+    const { fileName, contentType } = c.req.valid('json');
+
+    try {
+      const { key, url } = await getPresignPostUrl(fileName, contentType);
+
+      return c.json({ key, url } satisfies TGetPresignedPostUrlResponse);
+    } catch (err) {
+      console.error(err);
+
+      throw new AppError(AppErrorCode.UNKNOWN_ERROR);
+    }
+  })
+  .get(
+    '/envelope/:envelopeId/envelopeItem/:envelopeItemId',
+    sValidator('param', ZGetEnvelopeItemFileRequestParamsSchema),
+    async (c) => {
+      const { envelopeId, envelopeItemId } = c.req.valid('param');
+
+      const session = await getOptionalSession(c);
+
+      if (!session.user) {
+        return c.json({ error: 'Unauthorized' }, 401);
+      }
+
+      const envelope = await prisma.envelope.findFirst({
+        where: {
+          id: envelopeId,
+        },
+        include: {
+          envelopeItems: {
+            where: {
+              id: envelopeItemId,
+            },
+            include: {
+              documentData: true,
+            },
+          },
+        },
+      });
+
+      if (!envelope) {
+        return c.json({ error: 'Envelope not found' }, 404);
+      }
+
+      const [envelopeItem] = envelope.envelopeItems;
+
+      if (!envelopeItem) {
+        return c.json({ error: 'Envelope item not found' }, 404);
+      }
+
+      const team = await getTeamById({
+        userId: session.user.id,
+        teamId: envelope.teamId,
+      }).catch((error) => {
+        console.error(error);
+
+        return null;
+      });
+
+      if (!team) {
+        return c.json(
+          { error: 'User does not have access to the team that this envelope is associated with' },
+          403,
+        );
+      }
+
+      if (!envelopeItem.documentData) {
+        return c.json({ error: 'Document data not found' }, 404);
+      }
+
+      return await handleEnvelopeItemFileRequest({
+        title: envelopeItem.title,
+        status: envelope.status,
+        documentData: envelopeItem.documentData,
+        version: 'signed',
+        isDownload: false,
+        context: c,
+      });
+    },
+  )
+  .get(
+    '/envelope/:envelopeId/envelopeItem/:envelopeItemId/download/:version?',
+    sValidator('param', ZGetEnvelopeItemFileDownloadRequestParamsSchema),
+    async (c) => {
+      const { envelopeId, envelopeItemId, version } = c.req.valid('param');
+
+      const session = await getOptionalSession(c);
+
+      if (!session.user) {
+        return c.json({ error: 'Unauthorized' }, 401);
+      }
+
+      const envelope = await prisma.envelope.findFirst({
+        where: {
+          id: envelopeId,
+        },
+        include: {
+          envelopeItems: {
+            where: {
+              id: envelopeItemId,
+            },
+            include: {
+              documentData: true,
+            },
+          },
+        },
+      });
+
+      if (!envelope) {
+        return c.json({ error: 'Envelope not found' }, 404);
+      }
+
+      const [envelopeItem] = envelope.envelopeItems;
+
+      if (!envelopeItem) {
+        return c.json({ error: 'Envelope item not found' }, 404);
+      }
+
+      const team = await getTeamById({
+        userId: session.user.id,
+        teamId: envelope.teamId,
+      }).catch((error) => {
+        console.error(error);
+
+        return null;
+      });
+
+      if (!team) {
+        return c.json(
+          { error: 'User does not have access to the team that this envelope is associated with' },
+          403,
+        );
+      }
+
+      if (!envelopeItem.documentData) {
+        return c.json({ error: 'Document data not found' }, 404);
+      }
+
+      return await handleEnvelopeItemFileRequest({
+        title: envelopeItem.title,
+        status: envelope.status,
+        documentData: envelopeItem.documentData,
+        version,
+        isDownload: true,
+        context: c,
+      });
+    },
+  )
+  .get(
+    '/token/:token/envelopeItem/:envelopeItemId',
+    sValidator('param', ZGetEnvelopeItemFileTokenRequestParamsSchema),
+    async (c) => {
+      const { token, envelopeItemId } = c.req.valid('param');
+
+      let envelopeWhereQuery: Prisma.EnvelopeItemWhereUniqueInput = {
+        id: envelopeItemId,
+        envelope: {
+          recipients: {
+            some: {
+              token,
+            },
+          },
+        },
+      };
+
+      if (token.startsWith('qr_')) {
+        envelopeWhereQuery = {
+          id: envelopeItemId,
+          envelope: {
+            qrToken: token,
+          },
+        };
+      }
+
+      const envelopeItem = await prisma.envelopeItem.findUnique({
+        where: envelopeWhereQuery,
+        include: {
+          envelope: true,
+          documentData: true,
+        },
+      });
+
+      if (!envelopeItem) {
+        return c.json({ error: 'Envelope item not found' }, 404);
+      }
+
+      if (!envelopeItem.documentData) {
+        return c.json({ error: 'Document data not found' }, 404);
+      }
+
+      return await handleEnvelopeItemFileRequest({
+        title: envelopeItem.title,
+        status: envelopeItem.envelope.status,
+        documentData: envelopeItem.documentData,
+        version: 'signed',
+        isDownload: false,
+        context: c,
+      });
+    },
+  )
+  .get(
+    '/token/:token/envelopeItem/:envelopeItemId/download/:version?',
+    sValidator('param', ZGetEnvelopeItemFileTokenDownloadRequestParamsSchema),
+    async (c) => {
+      const { token, envelopeItemId, version } = c.req.valid('param');
+
+      let envelopeWhereQuery: Prisma.EnvelopeItemWhereUniqueInput = {
+        id: envelopeItemId,
+        envelope: {
+          recipients: {
+            some: {
+              token,
+            },
+          },
+        },
+      };
+
+      if (token.startsWith('qr_')) {
+        envelopeWhereQuery = {
+          id: envelopeItemId,
+          envelope: {
+            qrToken: token,
+          },
+        };
+      }
+
+      const envelopeItem = await prisma.envelopeItem.findUnique({
+        where: envelopeWhereQuery,
+        include: {
+          envelope: true,
+          documentData: true,
+        },
+      });
+
+      if (!envelopeItem) {
+        return c.json({ error: 'Envelope item not found' }, 404);
+      }
+
+      if (!envelopeItem.documentData) {
+        return c.json({ error: 'Document data not found' }, 404);
+      }
+
+      return await handleEnvelopeItemFileRequest({
+        title: envelopeItem.title,
+        status: envelopeItem.envelope.status,
+        documentData: envelopeItem.documentData,
+        version,
+        isDownload: true,
+        context: c,
+      });
+    },
+  );

apps/remix/server/api/files/files.types.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+
+import DocumentDataSchema from '@documenso/prisma/generated/zod/modelSchema/DocumentDataSchema';
+
+export const ZUploadPdfRequestSchema = z.object({
+  file: z.instanceof(File),
+});
+
+export const ZUploadPdfResponseSchema = DocumentDataSchema.pick({
+  type: true,
+  id: true,
+});
+
+export type TUploadPdfRequest = z.infer<typeof ZUploadPdfRequestSchema>;
+export type TUploadPdfResponse = z.infer<typeof ZUploadPdfResponseSchema>;
+
+export const ZGetPresignedPostUrlRequestSchema = z.object({
+  fileName: z.string().min(1),
+  contentType: z.string().min(1),
+});
+
+export const ZGetPresignedPostUrlResponseSchema = z.object({
+  key: z.string().min(1),
+  url: z.string().min(1),
+});
+
+export type TGetPresignedPostUrlRequest = z.infer<typeof ZGetPresignedPostUrlRequestSchema>;
+export type TGetPresignedPostUrlResponse = z.infer<typeof ZGetPresignedPostUrlResponseSchema>;
+
+export const ZGetEnvelopeItemFileRequestParamsSchema = z.object({
+  envelopeId: z.string().min(1),
+  envelopeItemId: z.string().min(1),
+});
+
+export type TGetEnvelopeItemFileRequestParams = z.infer<
+  typeof ZGetEnvelopeItemFileRequestParamsSchema
+>;
+
+export const ZGetEnvelopeItemFileTokenRequestParamsSchema = z.object({
+  token: z.string().min(1),
+  envelopeItemId: z.string().min(1),
+});
+
+export type TGetEnvelopeItemFileTokenRequestParams = z.infer<
+  typeof ZGetEnvelopeItemFileTokenRequestParamsSchema
+>;
+
+export const ZGetEnvelopeItemFileDownloadRequestParamsSchema = z.object({
+  envelopeId: z.string().min(1),
+  envelopeItemId: z.string().min(1),
+  version: z.enum(['signed', 'original']).default('signed'),
+});
+
+export type TGetEnvelopeItemFileDownloadRequestParams = z.infer<
+  typeof ZGetEnvelopeItemFileDownloadRequestParamsSchema
+>;
+
+export const ZGetEnvelopeItemFileTokenDownloadRequestParamsSchema = z.object({
+  token: z.string().min(1),
+  envelopeItemId: z.string().min(1),
+  version: z.enum(['signed', 'original']).default('signed'),
+});
+
+export type TGetEnvelopeItemFileTokenDownloadRequestParams = z.infer<
+  typeof ZGetEnvelopeItemFileTokenDownloadRequestParamsSchema
+>;

apps/remix/server/router.ts

@@ -8,13 +8,14 @@ import type { Logger } from 'pino';
 
 import { tsRestHonoApp } from '@documenso/api/hono';
 import { auth } from '@documenso/auth/server';
-import { API_V2_BETA_URL } from '@documenso/lib/constants/app';
+import { API_V2_BETA_URL, API_V2_URL } from '@documenso/lib/constants/app';
 import { jobsClient } from '@documenso/lib/jobs/client';
 import { getIpAddress } from '@documenso/lib/universal/get-ip-address';
 import { logger } from '@documenso/lib/utils/logger';
 import { openApiDocument } from '@documenso/trpc/server/open-api';
 
-import { filesRoute } from './api/files';
+import { downloadRoute } from './api/download/download';
+import { filesRoute } from './api/files/files';
 import { type AppContext, appContext } from './context';
 import { appMiddleware } from './middleware';
 import { openApiTrpcServerHandler } from './trpc/hono-trpc-open-api';
@@ -89,9 +90,26 @@ app.route('/api/v1', tsRestHonoApp);
 app.use('/api/jobs/*', jobsClient.getApiHandler());
 app.use('/api/trpc/*', reactRouterTrpcServer);
 
+// Unstable API server routes. Order matters for these two.
+app.get(`${API_V2_URL}/openapi.json`, (c) => c.json(openApiDocument));
+app.use(`${API_V2_URL}/*`, cors());
+// Shadows the download routes that tRPC defines since tRPC-to-openapi doesn't support their return types.
+app.route(`${API_V2_URL}`, downloadRoute);
+app.use(`${API_V2_URL}/*`, async (c) =>
+  openApiTrpcServerHandler(c, {
+    isBeta: false,
+  }),
+);
+
 // Unstable API server routes. Order matters for these two.
 app.get(`${API_V2_BETA_URL}/openapi.json`, (c) => c.json(openApiDocument));
 app.use(`${API_V2_BETA_URL}/*`, cors());
-app.use(`${API_V2_BETA_URL}/*`, async (c) => openApiTrpcServerHandler(c));
+// Shadows the download routes that tRPC defines since tRPC-to-openapi doesn't support their return types.
+app.route(`${API_V2_BETA_URL}`, downloadRoute);
+app.use(`${API_V2_BETA_URL}/*`, async (c) =>
+  openApiTrpcServerHandler(c, {
+    isBeta: true,
+  }),
+);
 
 export default app;

apps/remix/server/trpc/hono-trpc-open-api.ts

@@ -1,15 +1,22 @@
 import type { Context } from 'hono';
-import { createOpenApiFetchHandler } from 'trpc-to-openapi';
 
-import { API_V2_BETA_URL } from '@documenso/lib/constants/app';
+import { API_V2_BETA_URL, API_V2_URL } from '@documenso/lib/constants/app';
 import { AppError, genericErrorCodeToTrpcErrorCodeMap } from '@documenso/lib/errors/app-error';
 import { createTrpcContext } from '@documenso/trpc/server/context';
 import { appRouter } from '@documenso/trpc/server/router';
+import { createOpenApiFetchHandler } from '@documenso/trpc/utils/openapi-fetch-handler';
 import { handleTrpcRouterError } from '@documenso/trpc/utils/trpc-error-handler';
 
-export const openApiTrpcServerHandler = async (c: Context) => {
+type OpenApiTrpcServerHandlerOptions = {
+  isBeta: boolean;
+};
+
+export const openApiTrpcServerHandler = async (
+  c: Context,
+  { isBeta }: OpenApiTrpcServerHandlerOptions,
+) => {
   return createOpenApiFetchHandler<typeof appRouter>({
-    endpoint: API_V2_BETA_URL,
+    endpoint: isBeta ? API_V2_BETA_URL : API_V2_URL,
     router: appRouter,
     createContext: async () => createTrpcContext({ c, requestSource: 'apiV2' }),
     req: c.req.raw,