refactor: v2 event-types

[supalarry]

Overview

1. Version previous v2 event-types under "apps/api/v2/src/ee/event-types/event-types_2024_04_15".
2. Version new v2 event-types under "apps/api/v2/src/ee/event-types/event-types_2024_06_14" aka under version "2024-06-14".
3. Rename and group event-types hooks in "packages/platform/atoms/hooks/event-types". There is a "private" folder containing hooks that require access token, and public that return event types using username and event slug.
4. In "packages/lib/event-types/transformers" define transformers that transform data from new v2 requirements of inputs and outputs to internal event-types representation and vice versa. event-type "locations" and "bookingFields" have changed most notably.
   4.1 transformApiEventTypeForAtom.ts is then using thouse transformers to transform event-type returned by one of the hooks that return event-type in the new format and make it compatible for using it in the rest of our code.
   4.2 v2 API's input-event-types.service.ts is using the transformers to parse event-type input as we have defined it into event-type compatible with rest of our code.
   4.3 v2 API's output-event-types.service.ts uses transformers to then convert internal representation of event-types into output it defines. Event-types output of v2 is defined based on input, so we perform bi-directional transformation when receiving input and then responding with an output.
   4.4 As you see, there is no function transformAtomEventTypeForApi.ts just like we have with schedules transformAtomScheduleForApi - that is because there is no event-types atom yet, and transformAtomEventTypeForApi.ts will have to use transformers to take internal representation of event-type and convert it into format that api v2 expect when we allow creating / updating an event-type using atom. So why do we need transformApiEventTypeForAtom.ts if we don't have event-types atom? Because BookerPlatformWrapper is using event-type via useEventType() hook, and BookerPlatformWrapper uses transformApiEventTypeForAtom.ts to transform received event-type into format compatible with the Booker atom.
5. The inputs and outputs of v2 API are defined in "packages/platform/types/event-types/event-types_2024_06_14".
6. e2e tests for previous event-types version and new one can be ran by cd apps/api/v2 and then runniing:

npx jest apps/api/v2/src/ee/event-types/event-types_2024_04_15/controllers/event-types.controller.e2e-spec.ts --config jest-e2e.json

npx jest apps/api/v2/src/ee/event-types/event-types_2024_06_14/controllers/event-types.controller.e2e-spec.ts --config jest-e2e.json

v2 API updates

First I will show examples of requests, and then walk through possible "locations" and "bookingFields" values and describe what properties have changed in this release.

Requests

Create event type - POST http://localhost:5555/api/v2/event-types

Requires access token

As you see in the request, in the booking fields we have radio button group. When booking this event-type it looks like:

and in the e-mail sent to the person booked the booking field appears too:

Get one by id - GET http://localhost:5555/api/v2/event-types/:id

Requires access token

Get one by username and event slug - GET http://localhost:5555/api/v2/event-types?username=X&eventSlug=Y

Does not require any authentication. Since we are using event-types endpoint, it returns data containing array with 1 element`.

Get many by username - GET http://localhost:5555/api/v2/event-types?username=X

Does not require any authentication

Update - PATCH http://localhost:5555/api/v2/event-types/:id

Let's add a text field when booking. We include existing radio group booking field + new one in the request body:

Which makes it look like in the booker:

Accessing booking fields responses - GET booking by it's UID http://localhost:5555/api/v2/ee/bookings/:uid:

If we book the event-type, then the responses to bookingFields of the event-type appears under "responses" and their key is the "slug" you passed when creating the event-type. Here is booking responses for booker in the last screenshot:

locations

As you see in requests above, event-type locations is an array that can accept event-type location objects. Here are the possible location examples:

location - address

{
        "type": "address",
        "address": "London road 10-1",
        "public": true
}

location - link

{
        "type": "link",
        "link": "https://customvideo.com/join/123456"
}

location - integration

{
        "type": "integration",
        "integration": "cal-video",
        "public": true
}

location - phone

{
        "type": "phone",
        "phone": "+37120993151",
        "public": true
}

The public property controls whether or not the location is seen in booker during booking the event-type.
With public: true :

With public: false :

The locations types can be seen in locations.input.ts.

bookingFields

As you see in requests above, event-type booking fields is an array that can accept booking field objects. Here are the possible booking fields examples:

booking field - name

{
  "type": "name",
  "slug": "name",
  "label": "Your name",
  "required": true,
  "placeholder": "alice"
}

booking field - email

{
  "type": "email",
  "slug": "email",
  "label": "Your email",
  "required": true,
  "placeholder": "example@example.com"
}

booking field - phone

{
  "type": "phone",
  "slug": "phone",
  "label": "Your phone number",
  "required": true,
  "placeholder": "123456789"
}

booking field - address

{
  "type": "address",
  "slug": "address",
  "label": "Your address",
  "required": true,
  "placeholder": "1234 Main St"
}

booking field - text

{
  "type": "text",
  "slug": "text",
  "label": "Your text",
  "required": true,
  "placeholder": "Enter your text"
}

booking field - number

{
  "type": "number",
  "slug": "number",
  "label": "Your number",
  "required": true,
  "placeholder": "100"
}

booking field - textarea

{
  "type": "textarea",
  "slug": "textarea",
  "label": "Your detailed information",
  "required": true,
  "placeholder": "Detailed description here..."
}

booking field - select

{
  "type": "select",
  "slug": "select",
  "label": "Your selection",
  "required": true,
  "placeholder": "Select...",
  "options": ["Option 1", "Option 2"]
}

booking field - multiselect

{
  "type": "multiselect",
  "slug": "multiselect",
  "label": "Your multiple selections",
  "required": true,
  "options": ["Option 1", "Option 2"]
}

booking field - multiemail

{
  "type": "multiemail",
  "slug": "multiemail",
  "label": "Your multiple emails",
  "required": true,
  "placeholder": "example@example.com"
}

booking field - checkbox

{
  "type": "checkbox",
  "slug": "checkbox",
  "label": "Your checkboxes",
  "required": true,
  "options": ["Checkbox 1", "Checkbox 2"]
}

booking field - radio

{
  "type": "radio",
  "slug": "radio",
  "label": "Your radio buttons",
  "required": true,
  "options": ["Radio 1", "Radio 2"]
}

booking field - boolean

{
  "type": "boolean",
  "slug": "boolean",
  "label": "Agree to terms?",
  "required": true
}

booking fields types can be seen in file booking-fields.input.ts

default bookingFields

If no booking fields are provided, then only user name and email fields will appear in the booker. There are no more default fields like "What is this meeting about" or "Additional notes" - it's up to users to set it up.

Properties changed

event-type length

Previously event-type length was denoted by "length" property in the request and response bodies, but now it's made more specific and is named "lengthInMinutes" for more clarity.

location visibility

Previously whether or not to display event-type location during booking was controlled by "location.displayLocationPublicly", but now it's "location.public".

booking field name

Booking field has "name" property to access it in the responses of a booking. In requests and responses it is re-named to "slug", because we have event-type slug, and most probably one would format it in slug like "x-y-z" way.

Hooks

It's possible to import following hooks from the atoms package:

useEventType

Fetch event type using username and eventSlug

useEventTypes

Fetch all event types by username

useEventTypeById

Fetch specifify event type by id, but since there is no username this hook is only available with managed user's access token.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

3 Ignored Deployments

Name	Status	Preview	Comments	Updated (UTC)
ai	⬜️ Ignored (Inspect)	Visit Preview		Jun 20, 2024 11:06am
cal	⬜️ Ignored (Inspect)	Visit Preview		Jun 20, 2024 11:06am
calcom-web-canary	⬜️ Ignored (Inspect)	Visit Preview		Jun 20, 2024 11:06am

[socket-security]

New and removed dependencies detected. Learn more about Socket for GitHub ↗︎

Package	New capabilities	Transitives	Size	Publisher
npm/@calcom/platform-libraries-0.0.13@0.0.13	None	0	0 B
npm/@calcom/twipla@0.0.0-use.local	None	0	0 B
npm/@calcom/umami@0.0.0-use.local	None	0	0 B
npm/redis-errors@1.2.0	None	0	8.85 kB	bridgear

🚮 Removed packages: npm/@mux/mux-player-react@2.7.0, npm/@mux/mux-player@2.7.0, npm/@mux/mux-video@0.19.0, npm/@mux/playback-core@0.24.0, npm/castable-video@1.0.10, npm/custom-media-element@1.2.3, npm/hls.js@1.5.11

View full report↗︎

[graphite-app]

Graphite Automations

"Add foundation team as reviewer" took an action on this PR • (06/19/24)

1 reviewer was added to this PR based on Keith Williams's automation.

"Add platform team as reviewer" took an action on this PR • (06/19/24)

1 reviewer was added to this PR based on Keith Williams's automation.

"Add consumer team as reviewer" took an action on this PR • (06/19/24)

1 reviewer was added to this PR based on Keith Williams's automation.

[ThyMinimalDev]

what does System mean ?

[supalarry]

If you see file transformApiEventTypeForAtom.ts and then function getBookingFields, then you can see that system fields are the default booking fields added by us.

The logic is taken from "packages/features/bookings/lib/getBookingFields.ts" that takes event-type booking fields and using "ensureBookingInputsHaveSystemFields" function adds default fields.