feat: list schedules atom (calcom#24205)

* feat: add api v2 endpoint to fetch all user schedules

* chore: update typing

* feat: custom hook to fetch all user schedules

* refactor: shift logic to transform schedules into function of its own

* init: list schedules atom

* feat: api endpoints for list schedules atom

* refactor: accept redirect url as prop

* fix: pass redirect url prop

* integrate list schedules atom with availability settings

* refactor: extract types to be reused in api v2 endpoints

* skip availability settings page for the time being until we have api v2 endpoints in prod

* feat: add docs for list schedules atom

* fixup

* export Schedule type

* make sure we always have a default schedule if user deletes his default schedule

* chore: implement code rabbit feedback

* chore: implement PR feedback

* fix: resolve merge conflicts

* fix: import path

* update platform libraries

* fix: type check

* resolve  merge conflicts

* update atoms export

* update platform libraries schedule

* chore: arrange atoms in alphabetical order

* update atoms controller to include endpoints for list schedules atom

* add create atom scheule atom

* fix: invalidate schedules on new schedule creation

* chore: add changesets

Author: Ryukemeister

.changeset/lemon-rice-smile.md

@@ -0,0 +1,5 @@
+---
+"@calcom/atoms": minor
+---
+
+This PR adds an atom to list a user's schedule. Furthermore, there was also another atom introduced which can be used to create a new schedule for a user.

apps/api/v2/src/modules/atoms/controllers/atoms.schedules.controller.ts

@@ -25,6 +25,11 @@ import {
 import { z } from "zod";
 
 import { SCHEDULE_READ, SCHEDULE_WRITE, SUCCESS_STATUS } from "@calcom/platform-constants";
+import type {
+  GetAvailabilityListHandlerReturn,
+  DuplicateScheduleHandlerReturn,
+} from "@calcom/platform-libraries/schedules";
+import { getAvailabilityListHandler, duplicateScheduleHandler } from "@calcom/platform-libraries/schedules";
 import type { CreateScheduleHandlerReturn, CreateScheduleSchema } from "@calcom/platform-libraries/schedules";
 import { createScheduleHandler } from "@calcom/platform-libraries/schedules";
 import { FindDetailedScheduleByIdReturnType } from "@calcom/platform-libraries/schedules";
@@ -68,6 +73,21 @@ export class AtomsSchedulesController {
     };
   }
 
+  @Get("/schedules/all")
+  @Version(VERSION_NEUTRAL)
+  @UseGuards(ApiAuthGuard)
+  @Permissions([SCHEDULE_READ])
+  async getAllUserSchedules(
+    @GetUser() user: UserWithProfile
+  ): Promise<ApiResponse<Awaited<GetAvailabilityListHandlerReturn>>> {
+    const userSchedules = await getAvailabilityListHandler({ ctx: { user } });
+
+    return {
+      status: SUCCESS_STATUS,
+      data: userSchedules,
+    };
+  }
+
   @Patch("schedules/:scheduleId")
   @Permissions([SCHEDULE_WRITE])
   @UseGuards(ApiAuthGuard)
@@ -104,4 +124,20 @@ export class AtomsSchedulesController {
       data: createdSchedule,
     };
   }
+
+  @Post("schedules/:scheduleId/duplicate")
+  @Permissions([SCHEDULE_WRITE])
+  @UseGuards(ApiAuthGuard)
+  @ApiOperation({ summary: "Duplicate existing schedule" })
+  async duplicateExistingSchedule(
+    @GetUser() user: UserWithProfile,
+    @Param("scheduleId", ParseIntPipe) scheduleId: number
+  ): Promise<ApiResponse<Awaited<DuplicateScheduleHandlerReturn>>> {
+    const duplicatedSchedule = await duplicateScheduleHandler({ ctx: { user }, input: { scheduleId } });
+
+    return {
+      status: SUCCESS_STATUS,
+      data: duplicatedSchedule,
+    };
+  }
 }

apps/web/app/(use-page-wrapper)/(main-nav)/availability/page.tsx

@@ -9,6 +9,7 @@ import { getServerSession } from "@calcom/features/auth/lib/getServerSession";
 import { OrganizationRepository } from "@calcom/features/ee/organizations/repositories/OrganizationRepository";
 import { PermissionCheckService } from "@calcom/features/pbac/services/permission-check.service";
 import { AvailabilitySliderTable } from "@calcom/features/timezone-buddy/components/AvailabilitySliderTable";
+import { getScheduleListItemData } from "@calcom/lib/schedules/transformers/getScheduleListItemData";
 import { MembershipRole } from "@calcom/prisma/enums";
 import { availabilityRouter } from "@calcom/trpc/server/routers/viewer/availability/_router";
 
@@ -56,15 +57,7 @@ const Page = async ({ searchParams: _searchParams }: PageProps) => {
   // This is because the data is cached and as a result the data is converted to a string
   const availabilities = {
     ...cachedAvailabilities,
-    schedules: cachedAvailabilities.schedules.map((schedule) => ({
-      ...schedule,
-      availability: schedule.availability.map((avail) => ({
-        ...avail,
-        startTime: new Date(avail.startTime),
-        endTime: new Date(avail.endTime),
-        date: avail.date ? new Date(avail.date) : null,
-      })),
-    })),
+    schedules: cachedAvailabilities.schedules.map((schedule) => getScheduleListItemData(schedule)),
   };
 
   const organizationId = session?.user?.profile?.organizationId ?? session?.user.org?.id;

apps/web/modules/availability/availability-view.tsx

@@ -141,6 +141,7 @@ export function AvailabilityList({ availabilities }: AvailabilityListProps) {
             <ul className="divide-subtle divide-y" data-testid="schedules" ref={animationParentRef}>
               {availabilities.schedules.map((schedule) => (
                 <ScheduleListItem
+                  redirectUrl={`/availability/${schedule.id}`}
                   displayOptions={{
                     hour12: user?.timeFormat ? user.timeFormat === 12 : undefined,
                     timeZone: user?.timeZone,

docs/mint.json

@@ -209,18 +209,19 @@
           "group": "Atoms",
           "icon": "atom",
           "pages": [
-            "platform/atoms/cal-provider",
-            "platform/atoms/google-calendar-connect",
-            "platform/atoms/outlook-calendar-connect",
             "platform/atoms/apple-calendar-connect",
             "platform/atoms/availability-settings",
             "platform/atoms/booker",
-            "platform/atoms/event-type",
+            "platform/atoms/cal-provider",
             "platform/atoms/calendar-settings",
-            "platform/atoms/payment-form",
-            "platform/atoms/conferencing-apps",
             "platform/atoms/calendar-view",
-            "platform/atoms/create-schedule"
+            "platform/atoms/conferencing-apps",
+            "platform/atoms/create-schedule",
+            "platform/atoms/event-type",
+            "platform/atoms/google-calendar-connect",
+            "platform/atoms/list-schedules",
+            "platform/atoms/outlook-calendar-connect",
+            "platform/atoms/payment-form"
           ]
         },
         {

docs/platform/atoms/list-schedules.mdx

@@ -0,0 +1,116 @@
+---
+title: "List schedules"
+---
+
+The List schedules atom displays all of a user's availability schedules and provides management actions such as delete, duplicate, and edit capabilities for each schedule.
+
+Below code snippet can be used to render the List schedules atom
+
+```js
+import { ListSchedules } from "@calcom/atoms";
+
+export default function ListSchedules() {
+  return (
+    <>
+      <ListSchedules getRedirectUrl={(scheduleId) => `/availability/${scheduleId}`} />
+    </>
+  );
+}
+```
+
+For a demonstration of the List schedules atom, please refer to the video below.
+
+<p></p>
+
+    <iframe
+      height="315"
+      style={{ width: "100%", maxWidth: "560px" }}
+      src="https://www.loom.com/embed/8e020a4848d543548c519d3a7cd532c6?sid=e6ccad23-8372-402a-8fd3-c0180bc9113c"
+      frameborder="0"
+      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen="true"
+    ></iframe>
+
+<p></p>
+
+Below is a list of props that can be passed to the List schedules atom.
+
+<p></p>
+
+| Name           | Required | Description                                                                                                       |
+| :------------- | :------- | :---------------------------------------------------------------------------------------------------------------- |
+| getRedirectUrl | No       | Callback function that determines where the user should be redirected when they click on a schedule from the atom |
+
+## Combining list schedules atom with availability settings atom
+
+The List schedules atom works best when combined with the Availability settings atom to provide a seamless experience. In order to combine both of atom, here are the steps we recommend:
+
+<Steps>
+    <Step title="Setup list schedules atom"> 
+    Create a page for demostrating the list schedules atom.
+
+    Below code snippet can be used to setup the list schedules atom on a new page
+
+```js
+import { ListSchedules } from "@calcom/atoms";
+
+export default function ListSchedules() {
+  return (
+    <>
+      <ListSchedules getRedirectUrl={(scheduleId) => `/availability/${scheduleId}`} />
+    </>
+  );
+}
+```
+
+`getRedirectUrl` prop is a callback function that determines where the user should be redirected when they click on a schedule from the atom. Say if you want to display your availability settings atom on the page `/availability/:scheduleId`, you need to make sure you return the exact same url when you call the `getRedirectUrl` function.
+
+    </Step>
+    <Step title="Setup availability settings atom">
+    Create a page for demonstrating the availability settings atom. This should be a dynamic route that accepts a schedule id as a query parameter, and then the schedule id gets passed to the availability settings atom.
+
+      Below code snippet can be used to obtain the `scheduleId` and display the availability settings atom
+
+```js
+import { AvailabilitySettings } from "@calcom/atoms";
+import { useRouter } from "next/router";
+
+export default function Availability() {
+  const router = useRouter();
+
+  return (
+    <>
+       <AvailabilitySettings
+          id={router.query.scheduleId as string}
+          onUpdateSuccess={() => {
+            console.log("Updated schedule successfully");
+          }}
+       />
+    </>
+  )
+}
+```
+
+    </Step>
+
+</Steps>
+
+-Below video shows a demonstration of how we combined the list schedules atom and availability settings atom in one of our example app to create a seamless availability management experience.
+
+<p></p>
+
+    <iframe
+      height="315"
+      style={{ width: "100%", maxWidth: "560px" }}
+      src="https://www.loom.com/embed/76b65330e61e47eb95b7072ed3a42ec8?sid=9373ec6f-ba55-431e-98de-5dd3fb252a8a"
+      frameborder="0"
+      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen="true"
+    ></iframe>
+
+<p></p>
+
+<Info>
+  Link to the example app can be found
+  [here](https://github.com/calcom/cal.com/tree/main/packages/platform/examples/base)
+</Info>

packages/features/schedules/components/ScheduleListItem.tsx

@@ -26,6 +26,7 @@ export function ScheduleListItem({
   updateDefault,
   isDeletable,
   duplicateFunction,
+  redirectUrl,
 }: {
   schedule: RouterOutputs["viewer"]["availability"]["list"]["schedules"][number];
   deleteFunction: ({ scheduleId }: { scheduleId: number }) => void;
@@ -37,17 +38,15 @@ export function ScheduleListItem({
   isDeletable: boolean;
   updateDefault: ({ scheduleId, isDefault }: { scheduleId: number; isDefault: boolean }) => void;
   duplicateFunction: ({ scheduleId }: { scheduleId: number }) => void;
+  redirectUrl: string;
 }) {
   const { t, i18n } = useLocale();
 
   return (
     <li key={schedule.id}>
       <div className="hover:bg-muted flex items-center justify-between px-3 py-5 transition sm:px-4">
         <div className="group flex w-full items-center justify-between ">
-          <Link
-            href={`/availability/${schedule.id}`}
-            className="flex-grow truncate text-sm"
-            title={schedule.name}>
+          <Link href={redirectUrl} className="flex-grow truncate text-sm" title={schedule.name}>
             <div className="space-x-2 rtl:space-x-reverse">
               <span className="text-emphasis truncate font-medium">{schedule.name}</span>
               {schedule.isDefault && (

packages/lib/schedules/transformers/getScheduleListItemData.ts

@@ -0,0 +1,26 @@
+export type Schedule = {
+  isDefault: boolean;
+  id: number;
+  name: string;
+  timeZone: string | null;
+  availability: {
+    id: number;
+    userId: number | null;
+    startTime: Date;
+    endTime: Date;
+    eventTypeId: number | null;
+    date: Date | null;
+    days: number[];
+    scheduleId: number | null;
+  }[];
+};
+
+export const getScheduleListItemData = (schedule: Schedule) => ({
+  ...schedule,
+  availability: schedule.availability.map((avail) => ({
+    ...avail,
+    startTime: new Date(avail.startTime),
+    endTime: new Date(avail.endTime),
+    date: avail.date ? new Date(avail.date) : null,
+  })),
+});

packages/platform/atoms/hooks/schedules/useAtomCreateSchedule.ts

@@ -6,6 +6,7 @@ import type { CreateScheduleHandlerReturn } from "@calcom/trpc/server/routers/vi
 import { TCreateInputSchema as CreateScheduleSchema } from "@calcom/trpc/server/routers/viewer/availability/schedule/create.schema";
 
 import http from "../../lib/http";
+import { QUERY_KEY as SchedulesQueryKey } from "./useAtomGetAllSchedules";
 import { QUERY_KEY as ScheduleQueryKey } from "./useAtomSchedule";
 
 interface useAtomCreateScheduleOptions {
@@ -35,6 +36,7 @@ export const useAtomCreateSchedule = (
       if (data.status === SUCCESS_STATUS) {
         onSuccess?.(data);
         queryClient.invalidateQueries({ queryKey: [ScheduleQueryKey] });
+        queryClient.invalidateQueries({ queryKey: [SchedulesQueryKey] });
       } else {
         onError?.(data);
       }

packages/platform/atoms/hooks/schedules/useAtomDuplicateSchedule.ts

@@ -0,0 +1,45 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { SUCCESS_STATUS } from "@calcom/platform-constants";
+import type { ApiResponse, ApiErrorResponse } from "@calcom/platform-types";
+import type { DuplicateScheduleHandlerReturn } from "@calcom/trpc/server/routers/viewer/availability/schedule/duplicate.handler";
+
+import http from "../../lib/http";
+import { QUERY_KEY as ScheduleQueryKey } from "./useAtomSchedule";
+
+interface useAtomDuplicateScheduleOptions {
+  onSuccess?: (res: ApiResponse<DuplicateScheduleHandlerReturn>) => void;
+  onError?: (err: ApiErrorResponse) => void;
+}
+
+export const useAtomDuplicateSchedule = (
+  { onSuccess, onError }: useAtomDuplicateScheduleOptions = {
+    onSuccess: () => {
+      return;
+    },
+    onError: () => {
+      return;
+    },
+  }
+) => {
+  const queryClient = useQueryClient();
+
+  return useMutation<ApiResponse<DuplicateScheduleHandlerReturn>, unknown, { scheduleId: number }>({
+    mutationFn: async ({ scheduleId }: { scheduleId: number }) => {
+      const url = `atoms/schedules/${scheduleId}/duplicate`;
+      const response = await http.post<ApiResponse<DuplicateScheduleHandlerReturn>>(url);
+      return response.data;
+    },
+    onSuccess: (data) => {
+      if (data.status === SUCCESS_STATUS) {
+        onSuccess?.(data);
+        queryClient.invalidateQueries({ queryKey: [ScheduleQueryKey] });
+      } else {
+        onError?.(data);
+      }
+    },
+    onError: (err) => {
+      onError?.(err as ApiErrorResponse);
+    },
+  });
+};