docs: improve beforeEventBuffer and afterEventBuffer descriptions in API v2 (#26899)

* docs: improve beforeEventBuffer and afterEventBuffer descriptions in API v2

Co-Authored-By: morgan@cal.com <morgan@cal.com>

* fixup! docs: improve beforeEventBuffer and afterEventBuffer descriptions in API v2

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

apps/api/v2/src/ee/event-types/event-types_2024_04_15/inputs/create-event-type.input.ts

@@ -1,16 +1,16 @@
-import { EventTypeLocation_2024_04_15 } from "@/ee/event-types/event-types_2024_04_15/inputs/event-type-location.input";
-import { ApiProperty as DocsProperty, ApiPropertyOptional, ApiHideProperty } from "@nestjs/swagger";
+import { ApiHideProperty, ApiPropertyOptional, ApiProperty as DocsProperty } from "@nestjs/swagger";
 import { Type } from "class-transformer";
 import {
-  IsString,
-  IsNumber,
-  IsBoolean,
-  IsOptional,
-  ValidateNested,
-  Min,
   IsArray,
+  IsBoolean,
   IsInt,
+  IsNumber,
+  IsOptional,
+  IsString,
+  Min,
+  ValidateNested,
 } from "class-validator";
+import { EventTypeLocation_2024_04_15 } from "@/ee/event-types/event-types_2024_04_15/inputs/event-type-location.input";
 
 export const CREATE_EVENT_LENGTH_EXAMPLE = 60;
 export const CREATE_EVENT_SLUG_EXAMPLE = "cooking-class";
@@ -76,13 +76,19 @@ export class CreateEventTypeInput_2024_04_15 {
   @IsOptional()
   @IsInt()
   @Min(0)
-  @ApiPropertyOptional()
+  @ApiPropertyOptional({
+    description:
+      "Extra time automatically blocked on your calendar before a meeting starts. This gives you time to prepare, review notes, or transition from your previous activity.",
+  })
   beforeEventBuffer?: number;
 
   @IsOptional()
   @IsInt()
   @Min(0)
-  @ApiPropertyOptional()
+  @ApiPropertyOptional({
+    description:
+      "Extra time automatically blocked on your calendar after a meeting ends. This gives you time to wrap up, add notes, or decompress before your next commitment.",
+  })
   afterEventBuffer?: number;
 
   // @ApiHideProperty()

apps/api/v2/src/ee/event-types/event-types_2024_04_15/inputs/update-event-type.input.ts

@@ -1,24 +1,23 @@
+import { MAX_SEATS_PER_TIME_SLOT } from "@calcom/platform-constants";
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { Type } from "class-transformer";
+import {
+  IsArray,
+  IsBoolean,
+  IsDate,
+  IsEnum,
+  IsInt,
+  IsNumber,
+  IsOptional,
+  IsString,
+  Max,
+  Min,
+  ValidateNested,
+} from "class-validator";
 import { Editable } from "@/ee/event-types/event-types_2024_04_15/inputs/enums/editable";
 import { BaseField } from "@/ee/event-types/event-types_2024_04_15/inputs/enums/field-type";
 import { Frequency } from "@/ee/event-types/event-types_2024_04_15/inputs/enums/frequency";
 import { EventTypeLocation_2024_04_15 } from "@/ee/event-types/event-types_2024_04_15/inputs/event-type-location.input";
-import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
-import { Type } from "class-transformer";
-import {
-  IsString,
-  IsBoolean,
-  IsOptional,
-  ValidateNested,
-  Min,
-  Max,
-  IsInt,
-  IsEnum,
-  IsArray,
-  IsDate,
-  IsNumber,
-} from "class-validator";
-
-import { MAX_SEATS_PER_TIME_SLOT } from "@calcom/platform-constants";
 
 // note(Lauris): We will gradually expose more properties if any customer needs them.
 // Just uncomment any below when requested. Go to bottom of file to see UpdateEventTypeInput.
@@ -408,13 +407,19 @@ export class UpdateEventTypeInput_2024_04_15 {
   @IsInt()
   @Min(0)
   @IsOptional()
-  @ApiPropertyOptional()
+  @ApiPropertyOptional({
+    description:
+      "Extra time automatically blocked on your calendar before a meeting starts. This gives you time to prepare, review notes, or transition from your previous activity.",
+  })
   beforeEventBuffer?: number;
 
   @IsInt()
   @Min(0)
   @IsOptional()
-  @ApiPropertyOptional()
+  @ApiPropertyOptional({
+    description:
+      "Extra time automatically blocked on your calendar after a meeting ends. This gives you time to wrap up, add notes, or decompress before your next commitment.",
+  })
   afterEventBuffer?: number;
 
   @IsInt()

docs/api-reference/v2/openapi.json

@@ -19317,11 +19317,11 @@
           },
           "beforeEventBuffer": {
             "type": "number",
-            "description": "Time spaces that can be prepended before an event to give more time before it."
+            "description": "Extra time automatically blocked on your calendar before a meeting starts. This gives you time to prepare, review notes, or transition from your previous activity."
           },
           "afterEventBuffer": {
             "type": "number",
-            "description": "Time spaces that can be appended after an event to give more time after it."
+            "description": "Extra time automatically blocked on your calendar after a meeting ends. This gives you time to wrap up, add notes, or decompress before your next commitment."
           },
           "scheduleId": {
             "type": "number",
@@ -21634,11 +21634,11 @@
           },
           "beforeEventBuffer": {
             "type": "number",
-            "description": "Time spaces that can be prepended before an event to give more time before it."
+            "description": "Extra time automatically blocked on your calendar before a meeting starts. This gives you time to prepare, review notes, or transition from your previous activity."
           },
           "afterEventBuffer": {
             "type": "number",
-            "description": "Time spaces that can be appended after an event to give more time after it."
+            "description": "Extra time automatically blocked on your calendar after a meeting ends. This gives you time to wrap up, add notes, or decompress before your next commitment."
           },
           "scheduleId": {
             "type": "number",
@@ -23617,11 +23617,11 @@
           },
           "beforeEventBuffer": {
             "type": "number",
-            "description": "Time spaces that can be prepended before an event to give more time before it."
+            "description": "Extra time automatically blocked on your calendar before a meeting starts. This gives you time to prepare, review notes, or transition from your previous activity."
           },
           "afterEventBuffer": {
             "type": "number",
-            "description": "Time spaces that can be appended after an event to give more time after it."
+            "description": "Extra time automatically blocked on your calendar after a meeting ends. This gives you time to wrap up, add notes, or decompress before your next commitment."
           },
           "scheduleId": {
             "type": "number",
@@ -24210,11 +24210,11 @@
           },
           "beforeEventBuffer": {
             "type": "number",
-            "description": "Time spaces that can be prepended before an event to give more time before it."
+            "description": "Extra time automatically blocked on your calendar before a meeting starts. This gives you time to prepare, review notes, or transition from your previous activity."
           },
           "afterEventBuffer": {
             "type": "number",
-            "description": "Time spaces that can be appended after an event to give more time after it."
+            "description": "Extra time automatically blocked on your calendar after a meeting ends. This gives you time to wrap up, add notes, or decompress before your next commitment."
           },
           "scheduleId": {
             "type": "number",

packages/platform/types/event-types/event-types_2024_06_14/inputs/create-event-type.input.ts

@@ -1,40 +1,39 @@
+import { SUPPORTED_LOCALES } from "@calcom/platform-constants";
+import { SchedulingType } from "@calcom/platform-enums";
 import {
+  ApiExtraModels,
+  ApiHideProperty,
   ApiProperty as DocsProperty,
   ApiPropertyOptional as DocsPropertyOptional,
   getSchemaPath,
-  ApiExtraModels,
-  ApiHideProperty,
 } from "@nestjs/swagger";
-import { Type, Transform, Expose } from "class-transformer";
+import { Expose, Transform, Type } from "class-transformer";
 import {
-  IsString,
-  IsInt,
-  IsBoolean,
-  IsOptional,
-  Min,
-  IsUrl,
-  IsEnum,
-  IsArray,
-  ValidateNested,
   ArrayNotEmpty,
   ArrayUnique,
+  IsArray,
+  IsBoolean,
+  IsEnum,
   IsIn,
+  IsInt,
+  IsOptional,
+  IsString,
+  IsUrl,
+  Min,
+  ValidateNested,
 } from "class-validator";
 
-import { SUPPORTED_LOCALES } from "@calcom/platform-constants";
-import { SchedulingType } from "@calcom/platform-enums";
-
 import { RequiresAtLeastOnePropertyWhenNotDisabled } from "../../../utils/RequiresOneOfPropertiesWhenNotDisabled";
 import { BookerActiveBookingsLimit_2024_06_14 } from "./booker-active-booking-limit.input";
-import { DisableCancelling_2024_06_14 } from "./disable-cancelling.input";
-import { DisableRescheduling_2024_06_14 } from "./disable-rescheduling.input";
 import { BookerLayouts_2024_06_14 } from "./booker-layouts.input";
+import type { InputBookingField_2024_06_14 } from "./booking-fields.input";
 import {
   AddressFieldInput_2024_06_14,
   BooleanFieldInput_2024_06_14,
   CheckboxGroupFieldInput_2024_06_14,
   EmailDefaultFieldInput_2024_06_14,
   GuestsDefaultFieldInput_2024_06_14,
+  LocationDefaultFieldInput_2024_06_14,
   MultiEmailFieldInput_2024_06_14,
   MultiSelectFieldInput_2024_06_14,
   NameDefaultFieldInput_2024_06_14,
@@ -47,11 +46,9 @@ import {
   TextAreaFieldInput_2024_06_14,
   TextFieldInput_2024_06_14,
   TitleDefaultFieldInput_2024_06_14,
-  LocationDefaultFieldInput_2024_06_14,
   UrlFieldInput_2024_06_14,
+  ValidateInputBookingFields_2024_06_14,
 } from "./booking-fields.input";
-import type { InputBookingField_2024_06_14 } from "./booking-fields.input";
-import { ValidateInputBookingFields_2024_06_14 } from "./booking-fields.input";
 import type { BookingLimitsCount_2024_06_14 } from "./booking-limits-count.input";
 import { BaseBookingLimitsCount_2024_06_14, ValidateBookingLimitsCount } from "./booking-limits-count.input";
 import type { BookingLimitsDuration_2024_06_14 } from "./booking-limits-duration.input";
@@ -69,22 +66,24 @@ import {
 import type { ConfirmationPolicy_2024_06_14 } from "./confirmation-policy.input";
 import { BaseConfirmationPolicy_2024_06_14, ValidateConfirmationPolicy } from "./confirmation-policy.input";
 import { DestinationCalendar_2024_06_14 } from "./destination-calendar.input";
+import { DisableCancelling_2024_06_14 } from "./disable-cancelling.input";
+import { DisableRescheduling_2024_06_14 } from "./disable-rescheduling.input";
 import { Disabled_2024_06_14 } from "./disabled.input";
 import { EmailSettings_2024_06_14 } from "./email-settings.input";
 import { EventTypeColor_2024_06_14 } from "./event-type-color.input";
+import type { InputLocation_2024_06_14, InputTeamLocation_2024_06_14 } from "./locations.input";
 import {
   InputAddressLocation_2024_06_14,
   InputAttendeeAddressLocation_2024_06_14,
   InputAttendeeDefinedLocation_2024_06_14,
-  InputOrganizersDefaultApp_2024_06_14,
   InputAttendeePhoneLocation_2024_06_14,
   InputIntegrationLocation_2024_06_14,
   InputLinkLocation_2024_06_14,
+  InputOrganizersDefaultApp_2024_06_14,
   InputPhoneLocation_2024_06_14,
   ValidateLocations_2024_06_14,
   ValidateTeamLocations_2024_06_14,
 } from "./locations.input";
-import type { InputLocation_2024_06_14, InputTeamLocation_2024_06_14 } from "./locations.input";
 import { Recurrence_2024_06_14 } from "./recurrence.input";
 import { Seats_2024_06_14 } from "./seats.input";
 import { CantHaveRecurrenceAndBookerActiveBookingsLimit } from "./validators/CantHaveRecurrenceAndBookerActiveBookingsLimit";
@@ -287,14 +286,16 @@ export class BaseCreateEventTypeInput {
   @IsInt()
   @IsOptional()
   @DocsPropertyOptional({
-    description: "Time spaces that can be prepended before an event to give more time before it.",
+    description:
+      "Extra time automatically blocked on your calendar before a meeting starts. This gives you time to prepare, review notes, or transition from your previous activity.",
   })
   beforeEventBuffer?: number;
 
   @IsInt()
   @IsOptional()
   @DocsPropertyOptional({
-    description: "Time spaces that can be appended after an event to give more time after it.",
+    description:
+      "Extra time automatically blocked on your calendar after a meeting ends. This gives you time to wrap up, add notes, or decompress before your next commitment.",
   })
   afterEventBuffer?: number;
 

packages/platform/types/event-types/event-types_2024_06_14/inputs/update-event-type.input.ts

@@ -1,26 +1,25 @@
-import {
-  ApiPropertyOptional as DocsPropertyOptional,
-  getSchemaPath,
-  ApiExtraModels,
-  ApiHideProperty,
-} from "@nestjs/swagger";
-import { Type, Transform } from "class-transformer";
-import {
-  IsString,
-  IsInt,
-  IsBoolean,
-  IsOptional,
-  Min,
-  ValidateNested,
-  IsArray,
-  ArrayNotEmpty,
-  ArrayUnique,
-  IsUrl,
-  IsIn,
-} from "class-validator";
-
 import { SUPPORTED_LOCALES } from "@calcom/platform-constants";
 import { SchedulingType } from "@calcom/platform-enums";
+import {
+  ApiExtraModels,
+  ApiHideProperty,
+  ApiPropertyOptional as DocsPropertyOptional,
+  getSchemaPath,
+} from "@nestjs/swagger";
+import { Transform, Type } from "class-transformer";
+import {
+  ArrayNotEmpty,
+  ArrayUnique,
+  IsArray,
+  IsBoolean,
+  IsIn,
+  IsInt,
+  IsOptional,
+  IsString,
+  IsUrl,
+  Min,
+  ValidateNested,
+} from "class-validator";
 
 import { RequiresAtLeastOnePropertyWhenNotDisabled } from "../../../utils/RequiresOneOfPropertiesWhenNotDisabled";
 import { BookerActiveBookingsLimit_2024_06_14 } from "./booker-active-booking-limit.input";
@@ -32,6 +31,7 @@ import {
   CheckboxGroupFieldInput_2024_06_14,
   EmailDefaultFieldInput_2024_06_14,
   GuestsDefaultFieldInput_2024_06_14,
+  LocationDefaultFieldInput_2024_06_14,
   MultiEmailFieldInput_2024_06_14,
   MultiSelectFieldInput_2024_06_14,
   NameDefaultFieldInput_2024_06_14,
@@ -44,7 +44,6 @@ import {
   TextAreaFieldInput_2024_06_14,
   TextFieldInput_2024_06_14,
   TitleDefaultFieldInput_2024_06_14,
-  LocationDefaultFieldInput_2024_06_14,
   ValidateInputBookingFields_2024_06_14,
 } from "./booking-fields.input";
 import type { BookingLimitsCount_2024_06_14 } from "./booking-limits-count.input";
@@ -55,28 +54,29 @@ import {
   ValidateBookingLimistsDuration,
 } from "./booking-limits-duration.input";
 import {
+  type BookingWindow_2024_06_14,
   BusinessDaysWindow_2024_06_14,
   CalendarDaysWindow_2024_06_14,
   RangeWindow_2024_06_14,
   ValidateBookingWindow,
-  type BookingWindow_2024_06_14,
 } from "./booking-window.input";
 import type { ConfirmationPolicy_2024_06_14 } from "./confirmation-policy.input";
 import { BaseConfirmationPolicy_2024_06_14, ValidateConfirmationPolicy } from "./confirmation-policy.input";
 import {
+  CalVideoSettings,
   CREATE_EVENT_DESCRIPTION_EXAMPLE,
   CREATE_EVENT_LENGTH_EXAMPLE,
   CREATE_EVENT_SLUG_EXAMPLE,
   CREATE_EVENT_TITLE_EXAMPLE,
   Host,
-  CalVideoSettings,
 } from "./create-event-type.input";
+import { DestinationCalendar_2024_06_14 } from "./destination-calendar.input";
 import { DisableCancelling_2024_06_14 } from "./disable-cancelling.input";
 import { DisableRescheduling_2024_06_14 } from "./disable-rescheduling.input";
-import { DestinationCalendar_2024_06_14 } from "./destination-calendar.input";
 import { Disabled_2024_06_14 } from "./disabled.input";
 import { EmailSettings_2024_06_14 } from "./email-settings.input";
 import { EventTypeColor_2024_06_14 } from "./event-type-color.input";
+import type { InputLocation_2024_06_14, InputTeamLocation_2024_06_14 } from "./locations.input";
 import {
   InputAddressLocation_2024_06_14,
   InputAttendeeAddressLocation_2024_06_14,
@@ -89,7 +89,6 @@ import {
   ValidateLocations_2024_06_14,
   ValidateTeamLocations_2024_06_14,
 } from "./locations.input";
-import type { InputLocation_2024_06_14, InputTeamLocation_2024_06_14 } from "./locations.input";
 import { Recurrence_2024_06_14 } from "./recurrence.input";
 import { Seats_2024_06_14 } from "./seats.input";
 import { CantHaveRecurrenceAndBookerActiveBookingsLimit } from "./validators/CantHaveRecurrenceAndBookerActiveBookingsLimit";
@@ -227,14 +226,16 @@ class BaseUpdateEventTypeInput {
   @IsInt()
   @IsOptional()
   @DocsPropertyOptional({
-    description: "Time spaces that can be prepended before an event to give more time before it.",
+    description:
+      "Extra time automatically blocked on your calendar before a meeting starts. This gives you time to prepare, review notes, or transition from your previous activity.",
   })
   beforeEventBuffer?: number;
 
   @IsInt()
   @IsOptional()
   @DocsPropertyOptional({
-    description: "Time spaces that can be appended after an event to give more time after it.",
+    description:
+      "Extra time automatically blocked on your calendar after a meeting ends. This gives you time to wrap up, add notes, or decompress before your next commitment.",
   })
   afterEventBuffer?: number;