Event Types Platform Transformers
Purpose and Scope
The API v2 platform area is the part of Cal.diy that exposes API endpoints for the self-hosted scheduling product. Inside that platform area, event type transformation code is organized as a versioned namespace under event-types_2024_06_14. An event type is the scheduling configuration that controls how a bookable meeting behaves: booking fields, locations, recurrence, availability limits, layout, confirmation behavior, colors, and seats. The transformer namespace exists so API-facing payloads and internal Cal.diy representations can evolve without forcing every caller to know the same internal data shape.
Sources: apps/api/v2/src/platform/README.md, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/index.ts
This page is for developers working on API v2 event type endpoints, client-facing DTOs, or internal event type persistence and service logic. The key concept is directionality. The api-to-internal side accepts API-shaped values and normalizes them for internal use. The internal-to-api side takes internal event type data and presents it back through the public API contract. Keeping those directions separate makes reviews easier because a change to input normalization does not automatically imply a change to output serialization.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/internal-to-api/index.ts
The namespace is also explicitly versioned. The suffix 2024_06_14 is not just a folder name; it is a boundary that lets API v2 preserve a dated contract for event type behavior. When a public field changes meaning, when a field is renamed, or when a new representation needs to coexist with an older one, the versioned directory gives maintainers a place to add or adjust transformations without treating every event type endpoint as an unversioned moving target.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformed/index.ts
Relevant Source Files
apps/api/v2/src/platform/README.md— identifies this directory as the API v2 platform area containing Cal.diy API endpoints.apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformed/index.ts— exposes the transformed event type surface for this API version by re-exporting./event-type.tranformed.apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/index.ts— root barrel for the event type transformer namespace; it re-exports API-to-internal, internal-to-API, and internal location transformer modules.apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts— public export point for input-side event type transformation modules.apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/internal-to-api/index.ts— public export point for output-side event type transformation modules.
System-to-Code Mapping
The platform README gives the broad scope: API v2 contains API endpoints for Cal.diy. The event type folder then narrows that platform into a specific versioned API domain. Within that domain, the transformed index and the transformers index play different roles. The transformed export is the named surface for the event type after transformation. The transformer export is the operational surface that collects conversion functions by direction and topic. This distinction helps readers separate the shape being produced from the functions that produce or consume it.
Sources: apps/api/v2/src/platform/README.md, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformed/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/index.ts
The root transformer barrel exports three groups: ./api-to-internal, ./internal-to-api, and ./internal/locations. The first two groups are the primary contract for API boundary conversion. The third indicates that not every helper is necessarily public API serialization or API input normalization; some transformer code supports internal location handling. When adding a new event type feature, first decide whether the change belongs to inbound API parsing, outbound API response formatting, or an internal helper used by the platform implementation.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/index.ts
The inbound side exports modules for booking-fields, locations, recurrence, interval-limits, future-booking-limits, booker-layouts, confirmation-policy, event-colors, and seats. These names describe the API fields or groups that need translation before Cal.diy uses them internally. For example, a request payload can express display or scheduling choices in API terminology, while internal services may expect more constrained values, normalized naming, or structures aligned with persistence and business logic.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts
The outbound side mirrors most of those concerns but not always with identical module names. It exports booking-fields, locations, recurrence, interval-limits, future-booking-limits, booker-layouts, event-type-colors, requires-confirmation, and seats. The differences matter. Inbound code names the confirmation conversion as confirmation-policy, while outbound code exposes requires-confirmation. Inbound color conversion is exported as event-colors, while outbound color conversion is exported as event-type-colors. Those names suggest that the API contract can model a concept differently depending on direction.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/internal-to-api/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts
API Components
Use the barrels as the public import boundary for this namespace. Code that needs versioned event type conversion should import from the versioned transformer index or one of its directional indexes rather than reaching into individual implementation files by assumption. That keeps call sites aligned with what the namespace intentionally exports. It also allows maintainers to add private helper modules beneath a transformer group without accidentally making them part of the platform contract.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/internal-to-api/index.ts
| Export surface | Re-exported modules | Use when |
|---|---|---|
transformed/index.ts | ./event-type.tranformed | You need the transformed event type API surface for event-types_2024_06_14. |
transformers/index.ts | ./api-to-internal, ./internal-to-api, ./internal/locations | You need the complete transformer namespace for this event type API version. |
transformers/api-to-internal/index.ts | booking-fields, locations, recurrence, interval-limits, future-booking-limits, booker-layouts, confirmation-policy, event-colors, seats | You are converting API request/input values into internal representations. |
transformers/internal-to-api/index.ts | booking-fields, locations, recurrence, interval-limits, future-booking-limits, booker-layouts, event-type-colors, requires-confirmation, seats | You are converting internal event type values into API response/output values. |
The compact reference also shows which event type topics are symmetrical and which are directional. Booking fields, locations, recurrence, interval limits, future booking limits, booker layouts, and seats are present on both sides. Confirmation and colors are present on both sides conceptually, but their exported names differ. That asymmetry is a signal to check the exact module before assuming an inbound request field maps one-to-one to an outbound response field.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/internal-to-api/index.ts
Implementation Details
The source evidence shows a barrel-first design. A barrel file is an index module that re-exports other modules so consumers can depend on a stable namespace instead of a long list of individual files. Here, each directional folder has its own barrel, and the versioned transformer folder has a higher-level barrel above them. This layout keeps the API v2 event type conversion code discoverable: start at the versioned root, choose a direction, and then choose the event type concern you are changing.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/internal-to-api/index.ts
When implementing a new field, add or update transformation logic in both directions only if the API supports both input and output for that field. Some fields may be response-only, request-only, or internally derived. The current export lists demonstrate that the two directions are intentionally separate, so do not create a shared transformer merely because two modules have similar names. Shared helpers can exist, but the public directional exports should continue to communicate whether code is handling API input or API output.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/internal-to-api/index.ts
Pay particular attention to naming when reviewing confirmation and color changes. The inbound transformer exports confirmation-policy, while the outbound transformer exports requires-confirmation. That implies the API may accept a policy-like object or value but expose a confirmation requirement in another form. Likewise, inbound event-colors and outbound event-type-colors should be treated as two named conversion points, not as interchangeable filenames. Tests and endpoint code should import the appropriate side for the direction they are exercising.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts, apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/internal-to-api/index.ts
Execution Flow
A typical write path begins with an API v2 request that contains event type configuration. Endpoint or service code should select the api-to-internal transformer for each field group it accepts. Booking fields, locations, recurrence, interval limits, future booking limits, booker layouts, confirmation policy, colors, and seats can each be normalized through their corresponding inbound module. After transformation, downstream internal code can work with Cal.diy-oriented values rather than public API payload details.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/api-to-internal/index.ts
A typical read path moves in the opposite direction. Internal event type data is assembled by the platform service, then passed through internal-to-api conversion before it is returned to callers. This is where internal concepts become response fields such as booking fields, locations, recurrence, limits, booker layouts, event type colors, required confirmation state, and seats. Keeping this final response step explicit protects API clients from accidental leakage of internal naming or persistence details.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformers/internal-to-api/index.ts
The transformed namespace is the place to look when you need the exported transformed event type surface itself rather than the conversion operations. Its index re-exports ./event-type.tranformed, using the filename exactly as it appears in the repository. Treat that export as part of the versioned surface and avoid renaming imports locally in a way that hides the version or the transformed-event-type role from reviewers.
Sources: apps/api/v2/src/platform/event-types/event-types_2024_06_14/transformed/index.ts
Next Steps
When changing API v2 event type behavior, start by identifying the API version, then choose the correct transformation direction. Add inbound handling under api-to-internal for request payloads, outbound handling under internal-to-api for response payloads, and use the versioned root barrel when exposing a new transformer as part of the namespace. After the code change, inspect endpoint usage to make sure imports come through the intended public barrel and that tests cover both request normalization and response serialization when the field supports both.
For broader context, read the API v2 overview before changing endpoint behavior, then use the platform atoms and booking feature pages to understand how client-facing booking experiences consume event type data. If your work changes a field used by embedded or platform clients, coordinate the transformer change with the corresponding client package so the public API contract and UI expectations stay aligned.