@automate.ax/integration-contracts 0.144.2 → 0.145.1

package/src/calcom/events.ts

@@ -0,0 +1,502 @@
+import { encodableSchema, type Encodable } from "@automate.ax/codec"
+import * as z from "zod"
+
+export const CALCOM_WEBHOOK_TRIGGER_TYPES = [
+  "AFTER_GUESTS_CAL_VIDEO_NO_SHOW",
+  "AFTER_HOSTS_CAL_VIDEO_NO_SHOW",
+  "BOOKING_CANCELLED",
+  "BOOKING_CREATED",
+  "BOOKING_LOCATION_UPDATED",
+  "BOOKING_NO_SHOW_UPDATED",
+  "BOOKING_PAID",
+  "BOOKING_PAYMENT_INITIATED",
+  "BOOKING_REASSIGNED",
+  "BOOKING_REJECTED",
+  "BOOKING_REQUESTED",
+  "BOOKING_RESCHEDULED",
+  "CALENDAR_ENTRY_REJECTED",
+  "DELEGATION_CREDENTIAL_ERROR",
+  "DELEGATION_CREDENTIAL_ROTATION_REQUIRED",
+  "DELEGATION_CREDENTIAL_SECRET_ROTATED",
+  "DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED",
+  "FORM_SUBMITTED",
+  "FORM_SUBMITTED_NO_EVENT",
+  "INSTANT_MEETING",
+  "INSTANT_MEETING_ACCEPTED",
+  "MEETING_ENDED",
+  "MEETING_STARTED",
+  "OOO_CREATED",
+  "RECORDING_READY",
+  "RECORDING_TRANSCRIPTION_GENERATED",
+  "ROUTING_FORM_FALLBACK_HIT",
+  "WRONG_ASSIGNMENT_REPORT",
+] as const
+
+export type CalcomWebhookTriggerType =
+  (typeof CALCOM_WEBHOOK_TRIGGER_TYPES)[number]
+
+const CALCOM_WEBHOOK_TRIGGER_TYPE_SET = new Set<string>(
+  CALCOM_WEBHOOK_TRIGGER_TYPES,
+)
+
+const CALCOM_PERSON_SCHEMA = z.looseObject({
+  email: z.email(),
+  id: z.number().int().optional(),
+  language: z.looseObject({ locale: z.string() }),
+  name: z.string(),
+  phoneNumber: z.string().nullable().optional(),
+  timeZone: z.string(),
+  username: z.string().nullable().optional(),
+  utcOffset: z.number().optional(),
+})
+const CALCOM_OUT_OF_OFFICE_COVER_SCHEMA = z.looseObject({
+  email: z.email().optional(),
+  id: z.number().int(),
+  name: z.string().nullable().optional(),
+  timeZone: z.string().optional(),
+  username: z.string().nullable().optional(),
+})
+const CALCOM_OUT_OF_OFFICE_USER_SCHEMA = CALCOM_PERSON_SCHEMA.extend({
+  id: z.number().int(),
+  name: z.string().nullable(),
+  timeZone: z.string(),
+  username: z.string().nullable(),
+})
+const ENCODABLE_RECORD_SCHEMA = z.record(z.string(), encodableSchema)
+const BOOKING_PAYLOAD_SCHEMA = z.looseObject({
+  additionalNotes: z.string().optional(),
+  attendees: CALCOM_PERSON_SCHEMA.array(),
+  bookingId: z.number().int(),
+  customInputs: ENCODABLE_RECORD_SCHEMA.nullable().optional(),
+  description: z.string(),
+  endTime: z.string(),
+  eventDescription: z.string().nullable().optional(),
+  eventTitle: z.string().optional(),
+  eventTypeId: z.number().int().nullable().optional(),
+  location: encodableSchema.optional(),
+  metadata: ENCODABLE_RECORD_SCHEMA.optional(),
+  organizer: CALCOM_PERSON_SCHEMA,
+  responses: ENCODABLE_RECORD_SCHEMA.nullable().optional(),
+  startTime: z.string(),
+  status: z.string(),
+  title: z.string(),
+  type: z.string(),
+  uid: z.string(),
+})
+const BOOKING_PAYLOAD_WITH_ICS_SCHEMA = BOOKING_PAYLOAD_SCHEMA.extend({
+  attendeeIcsContent: z.string().optional(),
+  organizerIcsContent: z.string().optional(),
+})
+const FORM_SUBMISSION_PAYLOAD_SCHEMA = z.looseObject({
+  formId: z.string(),
+  formName: z.string(),
+  responses: ENCODABLE_RECORD_SCHEMA,
+  teamId: z.number().int().nullable().optional(),
+})
+const DELEGATION_CREDENTIAL_SCHEMA = z.looseObject({
+  domain: z.string(),
+  id: z.string(),
+  organizationId: z.number().int(),
+  secretExpiresAt: z.iso.datetime({ offset: true }),
+  workspacePlatform: z.string(),
+})
+const CAL_VIDEO_NO_SHOW_SCHEMA = z.looseObject({
+  attendees: CALCOM_PERSON_SCHEMA.array(),
+  bookingId: z.number().int(),
+  bookingUid: z.string(),
+  endTime: z.string(),
+  message: z.string(),
+  participants: encodableSchema.array(),
+  startTime: z.string(),
+  title: z.string(),
+  webhook: z.looseObject({
+    id: z.union([z.number(), z.string()]),
+    subscriberUrl: z.url(),
+    time: z.number(),
+    timeUnit: z.string(),
+  }),
+})
+const CALCOM_MEETING_EVENT_SCHEMA = z.looseObject({
+  attendees: CALCOM_PERSON_SCHEMA.array(),
+  createdAt: z.iso.datetime({ offset: true }),
+  endTime: z.string(),
+  id: z.number().int(),
+  startTime: z.string(),
+  title: z.string(),
+  uid: z.string(),
+})
+const CALCOM_PAYLOAD_SCHEMAS = {
+  AFTER_GUESTS_CAL_VIDEO_NO_SHOW: CAL_VIDEO_NO_SHOW_SCHEMA,
+  AFTER_HOSTS_CAL_VIDEO_NO_SHOW: CAL_VIDEO_NO_SHOW_SCHEMA.extend({
+    hostEmail: z.email(),
+    noShowHost: z.boolean(),
+  }),
+  BOOKING_CANCELLED: BOOKING_PAYLOAD_WITH_ICS_SCHEMA.extend({
+    cancelledBy: z.string().optional(),
+    cancellationReason: z.string().optional(),
+    requestReschedule: z.boolean(),
+  }),
+  BOOKING_CREATED: BOOKING_PAYLOAD_WITH_ICS_SCHEMA,
+  BOOKING_LOCATION_UPDATED: BOOKING_PAYLOAD_SCHEMA.extend({
+    previousLocation: encodableSchema,
+  }),
+  BOOKING_NO_SHOW_UPDATED: z.looseObject({
+    attendees: z.looseObject({ email: z.email(), noShow: z.boolean() }).array(),
+    bookingId: z.number().int().optional(),
+    bookingUid: z.string(),
+    message: z.string(),
+  }),
+  BOOKING_PAID: BOOKING_PAYLOAD_WITH_ICS_SCHEMA.extend({
+    paymentData: ENCODABLE_RECORD_SCHEMA.optional(),
+    paymentId: z.number().int().optional(),
+  }),
+  BOOKING_PAYMENT_INITIATED: BOOKING_PAYLOAD_SCHEMA.extend({
+    paymentData: ENCODABLE_RECORD_SCHEMA.optional(),
+    paymentId: z.number().int().optional(),
+  }),
+  BOOKING_REASSIGNED: BOOKING_PAYLOAD_WITH_ICS_SCHEMA.extend({
+    addedHostUserIds: z.number().int().array(),
+    removedHostUserIds: z.number().int().array(),
+  }),
+  BOOKING_REJECTED: BOOKING_PAYLOAD_SCHEMA.extend({
+    rejectionReason: z.string().optional(),
+  }),
+  BOOKING_REQUESTED: BOOKING_PAYLOAD_SCHEMA.extend({
+    requiresConfirmation: z.boolean(),
+  }),
+  BOOKING_RESCHEDULED: BOOKING_PAYLOAD_WITH_ICS_SCHEMA.extend({
+    rescheduleId: z.number().int().optional(),
+    rescheduleEndTime: z.string().optional(),
+    rescheduleStartTime: z.string().optional(),
+    rescheduleUid: z.string().optional(),
+    rescheduledBy: z.string().optional(),
+  }),
+  CALENDAR_ENTRY_REJECTED: z.looseObject({}),
+  DELEGATION_CREDENTIAL_ERROR: z.looseObject({
+    credential: z.looseObject({
+      appId: z.string(),
+      delegationCredentialId: z.string(),
+      id: z.number().int(),
+      type: z.string(),
+    }),
+    error: z.looseObject({ message: z.string(), type: z.string() }),
+    user: z.looseObject({
+      email: z.email(),
+      id: z.number().int(),
+      organizationId: z.number().int(),
+    }),
+  }),
+  DELEGATION_CREDENTIAL_ROTATION_REQUIRED: z.looseObject({
+    delegationCredential: DELEGATION_CREDENTIAL_SCHEMA,
+  }),
+  DELEGATION_CREDENTIAL_SECRET_ROTATED: z.looseObject({
+    delegationCredential: DELEGATION_CREDENTIAL_SCHEMA,
+  }),
+  DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED: z.looseObject({
+    delegationCredential: DELEGATION_CREDENTIAL_SCHEMA,
+    error: z.looseObject({
+      code: z.enum(["SECRET_MINT_FAILED", "SECRET_PROMOTION_FAILED"]),
+      message: z.string(),
+    }),
+  }),
+  FORM_SUBMITTED: FORM_SUBMISSION_PAYLOAD_SCHEMA,
+  FORM_SUBMITTED_NO_EVENT: FORM_SUBMISSION_PAYLOAD_SCHEMA.extend({
+    redirect: ENCODABLE_RECORD_SCHEMA.optional(),
+    responseId: z.number().int().optional(),
+  }),
+  INSTANT_MEETING: z.looseObject({
+    connectAndJoinUrl: z.url(),
+    customInputs: ENCODABLE_RECORD_SCHEMA,
+    eventTypeId: z.number().int(),
+    eventTypeTitle: z.string(),
+    responses: ENCODABLE_RECORD_SCHEMA,
+    uid: z.string(),
+  }),
+  INSTANT_MEETING_ACCEPTED: z.looseObject({
+    attendees: CALCOM_PERSON_SCHEMA.array(),
+    bookingId: z.number().int(),
+    bookingUid: z.string(),
+    endTime: z.string(),
+    eventTypeId: z.number().int(),
+    organizer: CALCOM_PERSON_SCHEMA,
+    startTime: z.string(),
+    status: z.string(),
+    title: z.string(),
+  }),
+  OOO_CREATED: z.looseObject({
+    oooEntry: z.looseObject({
+      createdAt: z.iso.datetime({ offset: true }),
+      end: z.string(),
+      id: z.number().int(),
+      notes: z.string().nullable(),
+      reason: z.looseObject({
+        emoji: z.string().optional(),
+        reason: z.string().optional(),
+      }),
+      reasonId: z.number().int(),
+      start: z.string(),
+      toUser: CALCOM_OUT_OF_OFFICE_COVER_SCHEMA.nullable(),
+      updatedAt: z.iso.datetime({ offset: true }),
+      user: CALCOM_OUT_OF_OFFICE_USER_SCHEMA,
+      uuid: z.string(),
+    }),
+  }),
+  RECORDING_READY: BOOKING_PAYLOAD_SCHEMA.pick({
+    attendees: true,
+    endTime: true,
+    organizer: true,
+    startTime: true,
+    title: true,
+    uid: true,
+  }).extend({ downloadLink: z.url() }),
+  RECORDING_TRANSCRIPTION_GENERATED: BOOKING_PAYLOAD_SCHEMA.pick({
+    attendees: true,
+    endTime: true,
+    organizer: true,
+    startTime: true,
+    title: true,
+    uid: true,
+  }).extend({
+    downloadLinks: z
+      .looseObject({
+        recording: z.url().optional(),
+        transcription: z
+          .looseObject({ format: z.string(), link: z.url() })
+          .array()
+          .optional(),
+      })
+      .optional(),
+  }),
+  ROUTING_FORM_FALLBACK_HIT: FORM_SUBMISSION_PAYLOAD_SCHEMA,
+  WRONG_ASSIGNMENT_REPORT: z.looseObject({
+    booking: z.looseObject({
+      endTime: z.string(),
+      id: z.number().int(),
+      startTime: z.string(),
+      status: z.string(),
+      title: z.string(),
+      uid: z.string(),
+    }),
+    report: z.looseObject({
+      additionalNotes: z.string().nullable(),
+      correctAssignee: z.string().nullable(),
+      firstAssignmentReason: z.string().nullable(),
+      guest: z.string().nullable(),
+      host: z.looseObject({
+        email: z.email().nullable(),
+        name: z.string().nullable(),
+      }),
+      reportedBy: z.looseObject({
+        email: z.email(),
+        id: z.number().int(),
+        name: z.string().nullable(),
+      }),
+      routingReason: z.string().nullable().optional(),
+    }),
+  }),
+} as const satisfies Record<
+  Exclude<CalcomWebhookTriggerType, "MEETING_ENDED" | "MEETING_STARTED">,
+  z.ZodType
+>
+
+type CalcomWrappedTriggerType = keyof typeof CALCOM_PAYLOAD_SCHEMAS
+
+/** Payload selected by one wrapped Cal.com webhook type. */
+type CalcomPayload<TType extends CalcomWrappedTriggerType> = z.output<
+  (typeof CALCOM_PAYLOAD_SCHEMAS)[TType]
+> & { readonly [key: string]: Encodable }
+
+/** Shared flat payload used by Cal.com meeting lifecycle webhooks. */
+type CalcomMeetingPayload = z.output<typeof CALCOM_MEETING_EVENT_SCHEMA> & {
+  readonly [key: string]: Encodable
+}
+
+/** Common person shape in Cal.com webhook payloads. */
+export type CalcomWebhookPerson = z.output<typeof CALCOM_PERSON_SCHEMA> & {
+  readonly [key: string]: Encodable
+}
+
+/** JSON-safe Cal.com webhook event narrowed by its exact provider type. */
+export type CalcomEvent<
+  TType extends CalcomWebhookTriggerType = CalcomWebhookTriggerType,
+> = TType extends "MEETING_ENDED" | "MEETING_STARTED"
+  ? CalcomMeetingPayload & { triggerEvent: TType }
+  : TType extends CalcomWrappedTriggerType
+    ? {
+        readonly [key: string]: Encodable
+        createdAt: string
+        payload: CalcomPayload<TType>
+        triggerEvent: TType
+      }
+    : never
+
+export const CALCOM_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+export const CALCOM_EVENT_SCHEMA: z.ZodType<CalcomEvent> =
+  z.custom<CalcomEvent>((value) => {
+    if (
+      typeof value !== "object" ||
+      value === null ||
+      !("triggerEvent" in value) ||
+      typeof value.triggerEvent !== "string" ||
+      !isCalcomWebhookTriggerType(value.triggerEvent)
+    ) {
+      return false
+    }
+    return calcomSemanticEventSchema(value.triggerEvent).safeParse(value)
+      .success
+  })
+
+/**
+ * Builds a schema narrowed to one exact Cal.com webhook trigger.
+ *
+ * @param type Exact Cal.com provider event type.
+ */
+export function calcomSemanticEventSchema<
+  TType extends CalcomWebhookTriggerType,
+>(type: TType): z.ZodType<CalcomEvent<TType>> {
+  if (type === "MEETING_ENDED" || type === "MEETING_STARTED") {
+    const schema = CALCOM_MEETING_EVENT_SCHEMA.extend({
+      triggerEvent: z.literal(type),
+    })
+    return z.custom<CalcomEvent<TType>>(
+      (value) => schema.safeParse(value).success,
+    )
+  }
+  if (isCalcomWrappedTriggerType(type)) {
+    const schema = z.looseObject({
+      createdAt: z.iso.datetime({ offset: true }),
+      payload: CALCOM_PAYLOAD_SCHEMAS[type],
+      triggerEvent: z.literal(type),
+    })
+    return z.custom<CalcomEvent<TType>>(
+      (value) => schema.safeParse(value).success,
+    )
+  }
+  return z.never()
+}
+
+/**
+ * Returns whether a string is a supported Cal.com webhook type.
+ *
+ * @param value Candidate provider event type.
+ */
+function isCalcomWebhookTriggerType(
+  value: string,
+): value is CalcomWebhookTriggerType {
+  return CALCOM_WEBHOOK_TRIGGER_TYPE_SET.has(value)
+}
+
+/**
+ * Returns whether a Cal.com webhook carries its data under `payload`.
+ *
+ * @param type Supported Cal.com webhook type.
+ */
+function isCalcomWrappedTriggerType(
+  type: CalcomWebhookTriggerType,
+): type is CalcomWrappedTriggerType {
+  return Object.hasOwn(CALCOM_PAYLOAD_SCHEMAS, type)
+}
+
+type CalcomTriggerContract<TEvent> = {
+  readonly configSchema: typeof CALCOM_TRIGGER_CONFIG_SCHEMA
+  readonly eventSchema: z.ZodType<TEvent>
+}
+
+export const CALCOM_EVENT_TYPE_MAP = {
+  AFTER_GUESTS_CAL_VIDEO_NO_SHOW: "calcom.afterGuestsCalVideoNoShow",
+  AFTER_HOSTS_CAL_VIDEO_NO_SHOW: "calcom.afterHostsCalVideoNoShow",
+  BOOKING_CANCELLED: "calcom.booking.cancelled",
+  BOOKING_CREATED: "calcom.booking.created",
+  BOOKING_LOCATION_UPDATED: "calcom.booking.locationUpdated",
+  BOOKING_NO_SHOW_UPDATED: "calcom.booking.noShowUpdated",
+  BOOKING_PAID: "calcom.booking.paid",
+  BOOKING_PAYMENT_INITIATED: "calcom.booking.paymentInitiated",
+  BOOKING_REASSIGNED: "calcom.booking.reassigned",
+  BOOKING_REJECTED: "calcom.booking.rejected",
+  BOOKING_REQUESTED: "calcom.booking.requested",
+  BOOKING_RESCHEDULED: "calcom.booking.rescheduled",
+  CALENDAR_ENTRY_REJECTED: "calcom.calendarEntryRejected",
+  DELEGATION_CREDENTIAL_ERROR: "calcom.delegationCredential.error",
+  DELEGATION_CREDENTIAL_ROTATION_REQUIRED:
+    "calcom.delegationCredential.rotationRequired",
+  DELEGATION_CREDENTIAL_SECRET_ROTATED:
+    "calcom.delegationCredential.secretRotated",
+  DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED:
+    "calcom.delegationCredential.secretRotationFailed",
+  FORM_SUBMITTED: "calcom.form.submitted",
+  FORM_SUBMITTED_NO_EVENT: "calcom.form.submittedWithoutEvent",
+  INSTANT_MEETING: "calcom.instantMeeting.created",
+  INSTANT_MEETING_ACCEPTED: "calcom.instantMeeting.accepted",
+  MEETING_ENDED: "calcom.meeting.ended",
+  MEETING_STARTED: "calcom.meeting.started",
+  OOO_CREATED: "calcom.outOfOffice.created",
+  RECORDING_READY: "calcom.recording.ready",
+  RECORDING_TRANSCRIPTION_GENERATED: "calcom.recording.transcriptionGenerated",
+  ROUTING_FORM_FALLBACK_HIT: "calcom.routingForm.fallbackHit",
+  WRONG_ASSIGNMENT_REPORT: "calcom.wrongAssignmentReported",
+} as const satisfies Record<CalcomWebhookTriggerType, string>
+
+/** Exact provider-to-platform trigger contract map. */
+type CalcomSemanticContracts = {
+  readonly [TType in CalcomWebhookTriggerType as (typeof CALCOM_EVENT_TYPE_MAP)[TType]]: CalcomTriggerContract<
+    CalcomEvent<TType>
+  >
+} & { readonly "calcom.event": CalcomTriggerContract<CalcomEvent> }
+
+export const calcomTriggerContracts: CalcomSemanticContracts = {
+  "calcom.afterGuestsCalVideoNoShow": contract(
+    "AFTER_GUESTS_CAL_VIDEO_NO_SHOW",
+  ),
+  "calcom.afterHostsCalVideoNoShow": contract("AFTER_HOSTS_CAL_VIDEO_NO_SHOW"),
+  "calcom.booking.cancelled": contract("BOOKING_CANCELLED"),
+  "calcom.booking.created": contract("BOOKING_CREATED"),
+  "calcom.booking.locationUpdated": contract("BOOKING_LOCATION_UPDATED"),
+  "calcom.booking.noShowUpdated": contract("BOOKING_NO_SHOW_UPDATED"),
+  "calcom.booking.paid": contract("BOOKING_PAID"),
+  "calcom.booking.paymentInitiated": contract("BOOKING_PAYMENT_INITIATED"),
+  "calcom.booking.reassigned": contract("BOOKING_REASSIGNED"),
+  "calcom.booking.rejected": contract("BOOKING_REJECTED"),
+  "calcom.booking.requested": contract("BOOKING_REQUESTED"),
+  "calcom.booking.rescheduled": contract("BOOKING_RESCHEDULED"),
+  "calcom.calendarEntryRejected": contract("CALENDAR_ENTRY_REJECTED"),
+  "calcom.delegationCredential.error": contract("DELEGATION_CREDENTIAL_ERROR"),
+  "calcom.delegationCredential.rotationRequired": contract(
+    "DELEGATION_CREDENTIAL_ROTATION_REQUIRED",
+  ),
+  "calcom.delegationCredential.secretRotated": contract(
+    "DELEGATION_CREDENTIAL_SECRET_ROTATED",
+  ),
+  "calcom.delegationCredential.secretRotationFailed": contract(
+    "DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED",
+  ),
+  "calcom.event": {
+    configSchema: CALCOM_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: CALCOM_EVENT_SCHEMA,
+  },
+  "calcom.form.submitted": contract("FORM_SUBMITTED"),
+  "calcom.form.submittedWithoutEvent": contract("FORM_SUBMITTED_NO_EVENT"),
+  "calcom.instantMeeting.accepted": contract("INSTANT_MEETING_ACCEPTED"),
+  "calcom.instantMeeting.created": contract("INSTANT_MEETING"),
+  "calcom.meeting.ended": contract("MEETING_ENDED"),
+  "calcom.meeting.started": contract("MEETING_STARTED"),
+  "calcom.outOfOffice.created": contract("OOO_CREATED"),
+  "calcom.recording.ready": contract("RECORDING_READY"),
+  "calcom.recording.transcriptionGenerated": contract(
+    "RECORDING_TRANSCRIPTION_GENERATED",
+  ),
+  "calcom.routingForm.fallbackHit": contract("ROUTING_FORM_FALLBACK_HIT"),
+  "calcom.wrongAssignmentReported": contract("WRONG_ASSIGNMENT_REPORT"),
+}
+
+/**
+ * Builds one trigger contract for an exact Cal.com provider event.
+ *
+ * @param type Exact Cal.com provider event type.
+ */
+function contract<TType extends CalcomWebhookTriggerType>(type: TType) {
+  return {
+    configSchema: CALCOM_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: calcomSemanticEventSchema(type),
+  }
+}

package/src/calcom/index.ts

@@ -0,0 +1,4 @@
+export * from "./api"
+export * from "./events"
+export * from "./schemas"
+export type { components } from "./openapi-types.generated"