packages/lib/getBusyTimes.ts (2)

1-13: Complete the JSDoc – list all params & return type

The new header comment is a great start, but only two of the many parameters are documented and there is no @returns section. Consumers who rely on IntelliSense / typedoc will still have to jump into the implementation to understand the full contract.

Consider expanding the block (or linking to the type literal) so that every field accepted by _getBusyTimes is discoverable from the docs:

  /**
   * Gets busy time slots from internal bookings and connected external calendars.
+  *
+  * @returns Promise<EventBusyDetails[]>  Busy intervals with `start`/`end` Date objects
   *
   * @param credentials            …
   * @param selectedCalendars      …
+  * @param userId                 …
+  * @param startTime              ISO-8601 string
+  * @param endTime                ISO-8601 string
+  * @param beforeEventBuffer      Minutes
+  * @param afterEventBuffer       Minutes
+  * @param bypassBusyCalendarTimes When true, skips external calendar lookup
+  * … etc.
   *
   * Other params are used to customize the time window, buffers, rescheduling, etc.
   */

This keeps IDE hints trustworthy and avoids future guesswork.

---

135-182: Hot loop repeatedly instantiates Day.js objects – cache or use timestamps

Inside the reduce, every booking creates up to six dayjs() instances (and several toDate() conversions). For large booking lists this becomes a noticeable hotspot.

A lightweight optimisation:

-    const { id, startTime, endTime, eventType, title, ...rest } = booking;
-    const minutesToBlockBeforeEvent = …
-    const minutesToBlockAfterEvent  = …
-
-    if (rest._count?.seatsReferences) {
-      const bookedAt = `${dayjs(startTime).utc().format()}<>${dayjs(endTime).utc().format()}`;
+    const { id, startTime, endTime, eventType, title, ...rest } = booking;
+    const start = dayjs.utc(startTime);   // one instantiation
+    const end   = dayjs.utc(endTime);     // one instantiation
+
+    const minutesToBlockBeforeEvent = …
+    const minutesToBlockAfterEvent  = …
+
+    if (rest._count?.seatsReferences) {
+      const bookedAt = `${start.format()}<>${end.format()}`;
       …
-          aggregate.push({
-            start: dayjs(startTime).subtract(minutesToBlockBeforeEvent, "minute").toDate(),
-            end: dayjs(startTime).toDate(),
+          aggregate.push({
+            start: start.subtract(minutesToBlockBeforeEvent, "minute").toDate(),
+            end:   start.toDate(),
           });
       …
     }
-    aggregate.push({
-      start: dayjs(startTime).subtract(minutesToBlockBeforeEvent, "minute").toDate(),
-      end: dayjs(endTime).add(minutesToBlockAfterEvent, "minute").toDate(),
+    aggregate.push({
+      start: start.subtract(minutesToBlockBeforeEvent, "minute").toDate(),
+      end:   end.add(minutesToBlockAfterEvent, "minute").toDate(),
       title,
       source: `eventType-${eventType?.id}-booking-${id}`,
     });

Benefits:
• Cuts day-js allocations in half.
• Forces UTC consistently, avoiding accidental TZ drift.

Not critical, but aligns with the performance guideline to limit Day.js in tight loops.

docs/api-reference/v2/calendars/get-busy-times.mdx (1)

13-22: Align parameter names with code-level API

At runtime the service expects an array of credentials and a parallel list of selectedCalendars, not singular credentialId / externalId. If the REST façade truly accepts single-value fields, note that internally they are wrapped as arrays so integrators aren’t surprised when reading the TS docs or source.

A one-liner clarification is enough, for example:

credentialId – (or array credentials[] if you call the TypeScript lib directly) …

This keeps the public docs in sync with the implementation detail just added to getBusyTimes.ts.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro