feat: add API support for folders (#1967)

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

@@ -2,27 +2,26 @@ import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
 import { createFolder } from '@documenso/lib/server-only/folder/create-folder';
 import { deleteFolder } from '@documenso/lib/server-only/folder/delete-folder';
 import { findFolders } from '@documenso/lib/server-only/folder/find-folders';
+import { findFoldersInternal } from '@documenso/lib/server-only/folder/find-folders-internal';
 import { getFolderBreadcrumbs } from '@documenso/lib/server-only/folder/get-folder-breadcrumbs';
 import { getFolderById } from '@documenso/lib/server-only/folder/get-folder-by-id';
-import { moveFolder } from '@documenso/lib/server-only/folder/move-folder';
-import { pinFolder } from '@documenso/lib/server-only/folder/pin-folder';
-import { unpinFolder } from '@documenso/lib/server-only/folder/unpin-folder';
 import { updateFolder } from '@documenso/lib/server-only/folder/update-folder';
 
 import { authenticatedProcedure, router } from '../trpc';
 import {
-  ZCreateFolderSchema,
-  ZDeleteFolderSchema,
+  ZCreateFolderRequestSchema,
+  ZCreateFolderResponseSchema,
+  ZDeleteFolderRequestSchema,
+  ZFindFoldersInternalRequestSchema,
+  ZFindFoldersInternalResponseSchema,
   ZFindFoldersRequestSchema,
   ZFindFoldersResponseSchema,
   ZGenericSuccessResponse,
   ZGetFoldersResponseSchema,
   ZGetFoldersSchema,
-  ZMoveFolderSchema,
-  ZPinFolderSchema,
   ZSuccessResponseSchema,
-  ZUnpinFolderSchema,
-  ZUpdateFolderSchema,
+  ZUpdateFolderRequestSchema,
+  ZUpdateFolderResponseSchema,
 } from './schema';
 
 export const folderRouter = router({
@@ -43,7 +42,7 @@ export const folderRouter = router({
         },
       });
 
-      const folders = await findFolders({
+      const folders = await findFoldersInternal({
         userId: user.id,
         teamId,
         parentId,
@@ -67,11 +66,47 @@ export const folderRouter = router({
     }),
 
   /**
-   * @private
+   * @public
    */
   findFolders: authenticatedProcedure
+    .meta({
+      openapi: {
+        method: 'GET',
+        path: '/folder',
+        summary: 'Find folders',
+        description: 'Find folders based on a search criteria',
+        tags: ['Folder'],
+      },
+    })
     .input(ZFindFoldersRequestSchema)
     .output(ZFindFoldersResponseSchema)
+    .query(async ({ input, ctx }) => {
+      const { teamId, user } = ctx;
+      const { parentId, type, page, perPage } = input;
+
+      ctx.logger.info({
+        input: {
+          parentId,
+          type,
+        },
+      });
+
+      return await findFolders({
+        userId: user.id,
+        teamId,
+        parentId,
+        type,
+        page,
+        perPage,
+      });
+    }),
+
+  /**
+   * @private
+   */
+  findFoldersInternal: authenticatedProcedure
+    .input(ZFindFoldersInternalRequestSchema)
+    .output(ZFindFoldersInternalResponseSchema)
     .query(async ({ input, ctx }) => {
       const { teamId, user } = ctx;
       const { parentId, type } = input;
@@ -83,7 +118,7 @@ export const folderRouter = router({
         },
       });
 
-      const folders = await findFolders({
+      const folders = await findFoldersInternal({
         userId: user.id,
         teamId,
         parentId,
@@ -107,10 +142,20 @@ export const folderRouter = router({
     }),
 
   /**
-   * @private
+   * @public
    */
   createFolder: authenticatedProcedure
-    .input(ZCreateFolderSchema)
+    .meta({
+      openapi: {
+        method: 'POST',
+        path: '/folder/create',
+        summary: 'Create new folder',
+        description: 'Creates a new folder in your team',
+        tags: ['Folder'],
+      },
+    })
+    .input(ZCreateFolderRequestSchema)
+    .output(ZCreateFolderResponseSchema)
     .mutation(async ({ input, ctx }) => {
       const { teamId, user } = ctx;
       const { name, parentId, type } = input;
@@ -145,181 +190,77 @@ export const folderRouter = router({
         type,
       });
 
-      return {
-        ...result,
-        type,
-      };
+      return result;
     }),
 
   /**
-   * @private
+   * @public
    */
   updateFolder: authenticatedProcedure
-    .input(ZUpdateFolderSchema)
+    .meta({
+      openapi: {
+        method: 'POST',
+        path: '/folder/update',
+        summary: 'Update folder',
+        description: 'Updates an existing folder',
+        tags: ['Folder'],
+      },
+    })
+    .input(ZUpdateFolderRequestSchema)
+    .output(ZUpdateFolderResponseSchema)
     .mutation(async ({ input, ctx }) => {
       const { teamId, user } = ctx;
-      const { id, name, visibility } = input;
+      const { folderId, data } = input;
 
       ctx.logger.info({
         input: {
-          id,
+          folderId,
         },
       });
 
-      const currentFolder = await getFolderById({
-        userId: user.id,
-        teamId,
-        folderId: id,
-      });
-
       const result = await updateFolder({
         userId: user.id,
         teamId,
-        folderId: id,
-        name,
-        visibility,
-        type: currentFolder.type,
+        folderId,
+        data,
       });
 
       return {
         ...result,
-        type: currentFolder.type,
       };
     }),
 
   /**
-   * @private
+   * @public
    */
   deleteFolder: authenticatedProcedure
-    .input(ZDeleteFolderSchema)
+    .meta({
+      openapi: {
+        method: 'POST',
+        path: '/folder/delete',
+        summary: 'Delete folder',
+        description: 'Deletes an existing folder',
+        tags: ['Folder'],
+      },
+    })
+    .input(ZDeleteFolderRequestSchema)
     .output(ZSuccessResponseSchema)
     .mutation(async ({ input, ctx }) => {
       const { teamId, user } = ctx;
-      const { id } = input;
+      const { folderId } = input;
 
       ctx.logger.info({
         input: {
-          id,
+          folderId,
         },
       });
 
       await deleteFolder({
         userId: user.id,
         teamId,
-        folderId: id,
+        folderId,
       });
 
       return ZGenericSuccessResponse;
     }),
-
-  /**
-   * @private
-   */
-  moveFolder: authenticatedProcedure.input(ZMoveFolderSchema).mutation(async ({ input, ctx }) => {
-    const { teamId, user } = ctx;
-    const { id, parentId } = input;
-
-    ctx.logger.info({
-      input: {
-        id,
-        parentId,
-      },
-    });
-
-    const currentFolder = await getFolderById({
-      userId: user.id,
-      teamId,
-      folderId: id,
-    });
-
-    if (parentId !== null) {
-      try {
-        await getFolderById({
-          userId: user.id,
-          teamId,
-          folderId: parentId,
-          type: currentFolder.type,
-        });
-      } catch (error) {
-        throw new AppError(AppErrorCode.NOT_FOUND, {
-          message: 'Parent folder not found',
-        });
-      }
-    }
-
-    const result = await moveFolder({
-      userId: user.id,
-      teamId,
-      folderId: id,
-      parentId,
-      requestMetadata: ctx.metadata,
-    });
-
-    return {
-      ...result,
-      type: currentFolder.type,
-    };
-  }),
-
-  /**
-   * @private
-   */
-  pinFolder: authenticatedProcedure.input(ZPinFolderSchema).mutation(async ({ ctx, input }) => {
-    const { folderId } = input;
-
-    ctx.logger.info({
-      input: {
-        folderId,
-      },
-    });
-
-    const currentFolder = await getFolderById({
-      userId: ctx.user.id,
-      teamId: ctx.teamId,
-      folderId,
-    });
-
-    const result = await pinFolder({
-      userId: ctx.user.id,
-      teamId: ctx.teamId,
-      folderId,
-      type: currentFolder.type,
-    });
-
-    return {
-      ...result,
-      type: currentFolder.type,
-    };
-  }),
-
-  /**
-   * @private
-   */
-  unpinFolder: authenticatedProcedure.input(ZUnpinFolderSchema).mutation(async ({ ctx, input }) => {
-    const { folderId } = input;
-
-    ctx.logger.info({
-      input: {
-        folderId,
-      },
-    });
-
-    const currentFolder = await getFolderById({
-      userId: ctx.user.id,
-      teamId: ctx.teamId,
-      folderId,
-    });
-
-    const result = await unpinFolder({
-      userId: ctx.user.id,
-      teamId: ctx.teamId,
-      folderId,
-      type: currentFolder.type,
-    });
-
-    return {
-      ...result,
-      type: currentFolder.type,
-    };
-  }),
 });

packages/trpc/server/folder-router/schema.ts

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 
 import { ZFolderTypeSchema } from '@documenso/lib/types/folder-type';
-import { ZFindSearchParamsSchema } from '@documenso/lib/types/search-params';
+import { ZFindResultResponse, ZFindSearchParamsSchema } from '@documenso/lib/types/search-params';
 import { DocumentVisibility } from '@documenso/prisma/generated/types';
+import FolderSchema from '@documenso/prisma/generated/zod/modelSchema/FolderSchema';
 
 /**
  * Required for empty responses since we currently can't 201 requests for our openapi setup.
@@ -11,24 +12,23 @@ import { DocumentVisibility } from '@documenso/prisma/generated/types';
  */
 export const ZSuccessResponseSchema = z.object({
   success: z.boolean(),
-  type: ZFolderTypeSchema.optional(),
 });
 
 export const ZGenericSuccessResponse = {
   success: true,
 } satisfies z.infer<typeof ZSuccessResponseSchema>;
 
-export const ZFolderSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  userId: z.number(),
-  teamId: z.number().nullable(),
-  parentId: z.string().nullable(),
-  pinned: z.boolean(),
-  createdAt: z.date(),
-  updatedAt: z.date(),
-  visibility: z.nativeEnum(DocumentVisibility),
-  type: ZFolderTypeSchema,
+export const ZFolderSchema = FolderSchema.pick({
+  id: true,
+  name: true,
+  userId: true,
+  teamId: true,
+  parentId: true,
+  pinned: true,
+  createdAt: true,
+  updatedAt: true,
+  visibility: true,
+  type: true,
 });
 
 export type TFolder = z.infer<typeof ZFolderSchema>;
@@ -51,40 +51,39 @@ export const ZFolderWithSubfoldersSchema = ZFolderSchema.extend({
 
 export type TFolderWithSubfolders = z.infer<typeof ZFolderWithSubfoldersSchema>;
 
-export const ZCreateFolderSchema = z.object({
+const ZFolderParentIdSchema = z
+  .string()
+  .describe(
+    'The folder ID to place this folder within. Leave empty to place folder at the root level.',
+  );
+
+export const ZCreateFolderRequestSchema = z.object({
   name: z.string(),
-  parentId: z.string().optional(),
+  parentId: ZFolderParentIdSchema.optional(),
   type: ZFolderTypeSchema.optional(),
 });
 
-export const ZUpdateFolderSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  visibility: z.nativeEnum(DocumentVisibility),
-  type: ZFolderTypeSchema.optional(),
+export const ZCreateFolderResponseSchema = ZFolderSchema;
+
+export const ZUpdateFolderRequestSchema = z.object({
+  folderId: z.string().describe('The ID of the folder to update'),
+  data: z.object({
+    name: z.string().optional().describe('The name of the folder'),
+    parentId: ZFolderParentIdSchema.optional().nullable(),
+    visibility: z
+      .nativeEnum(DocumentVisibility)
+      .optional()
+      .describe('The visibility of the folder'),
+    pinned: z.boolean().optional().describe('Whether the folder should be pinned'),
+  }),
 });
 
-export type TUpdateFolderSchema = z.infer<typeof ZUpdateFolderSchema>;
+export type TUpdateFolderRequestSchema = z.infer<typeof ZUpdateFolderRequestSchema>;
 
-export const ZDeleteFolderSchema = z.object({
-  id: z.string(),
-  type: ZFolderTypeSchema.optional(),
-});
+export const ZUpdateFolderResponseSchema = ZFolderSchema;
 
-export const ZMoveFolderSchema = z.object({
-  id: z.string(),
-  parentId: z.string().nullable(),
-  type: ZFolderTypeSchema.optional(),
-});
-
-export const ZPinFolderSchema = z.object({
+export const ZDeleteFolderRequestSchema = z.object({
   folderId: z.string(),
-  type: ZFolderTypeSchema.optional(),
-});
-
-export const ZUnpinFolderSchema = z.object({
-  folderId: z.string(),
-  type: ZFolderTypeSchema.optional(),
 });
 
 export const ZGetFoldersSchema = z.object({
@@ -101,11 +100,20 @@ export const ZGetFoldersResponseSchema = z.object({
 export type TGetFoldersResponse = z.infer<typeof ZGetFoldersResponseSchema>;
 
 export const ZFindFoldersRequestSchema = ZFindSearchParamsSchema.extend({
+  parentId: z.string().optional().describe('Filter folders by the parent folder ID'),
+  type: ZFolderTypeSchema.optional().describe('Filter folders by the folder type'),
+});
+
+export const ZFindFoldersResponseSchema = ZFindResultResponse.extend({
+  data: z.array(ZFolderSchema),
+});
+
+export const ZFindFoldersInternalRequestSchema = ZFindSearchParamsSchema.extend({
   parentId: z.string().nullable().optional(),
   type: ZFolderTypeSchema.optional(),
 });
 
-export const ZFindFoldersResponseSchema = z.object({
+export const ZFindFoldersInternalResponseSchema = z.object({
   data: z.array(ZFolderWithSubfoldersSchema),
   breadcrumbs: z.array(ZFolderSchema),
   type: ZFolderTypeSchema.optional(),