@automate.ax/integration-contracts 0.148.0 → 0.150.0

package/src/calcom/events.ts

@@ -330,7 +330,42 @@ export type CalcomEvent<
       }
     : never
 
-export const CALCOM_TRIGGER_CONFIG_SCHEMA = z.object({})
+export const CALCOM_USER_WEBHOOK_SCOPE_SCHEMA = z.object({
+  type: z.literal("user"),
+})
+export const CALCOM_TEAM_WEBHOOK_SCOPE_SCHEMA = z.object({
+  eventTypeId: z.number().int().positive(),
+  teamId: z.number().int().positive(),
+  type: z.literal("team"),
+})
+export const CALCOM_ORGANIZATION_WEBHOOK_SCOPE_SCHEMA = z.object({
+  organizationId: z.number().int().positive(),
+  type: z.literal("organization"),
+})
+export const CALCOM_WEBHOOK_SCOPE_SCHEMA = z.discriminatedUnion("type", [
+  CALCOM_USER_WEBHOOK_SCOPE_SCHEMA,
+  CALCOM_TEAM_WEBHOOK_SCOPE_SCHEMA,
+  CALCOM_ORGANIZATION_WEBHOOK_SCOPE_SCHEMA,
+])
+export type CalcomWebhookScope = z.output<typeof CALCOM_WEBHOOK_SCOPE_SCHEMA>
+
+export const CALCOM_USER_TRIGGER_CONFIG_SCHEMA = z.object({
+  scope: CALCOM_USER_WEBHOOK_SCOPE_SCHEMA.optional(),
+})
+export const CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA = z.object({
+  scope: z
+    .discriminatedUnion("type", [
+      CALCOM_USER_WEBHOOK_SCOPE_SCHEMA,
+      CALCOM_TEAM_WEBHOOK_SCOPE_SCHEMA,
+    ])
+    .optional(),
+})
+export const CALCOM_ORGANIZATION_TRIGGER_CONFIG_SCHEMA = z.object({
+  scope: CALCOM_ORGANIZATION_WEBHOOK_SCOPE_SCHEMA,
+})
+export const CALCOM_BROAD_TRIGGER_CONFIG_SCHEMA = z.object({
+  scope: CALCOM_WEBHOOK_SCOPE_SCHEMA.optional(),
+})
 
 export const CALCOM_EVENT_SCHEMA: z.ZodType<CalcomEvent> =
   z.custom<CalcomEvent>((value) => {
@@ -398,8 +433,14 @@ function isCalcomWrappedTriggerType(
   return Object.hasOwn(CALCOM_PAYLOAD_SCHEMAS, type)
 }
 
+type CalcomTriggerConfigSchema =
+  | typeof CALCOM_BROAD_TRIGGER_CONFIG_SCHEMA
+  | typeof CALCOM_ORGANIZATION_TRIGGER_CONFIG_SCHEMA
+  | typeof CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA
+  | typeof CALCOM_USER_TRIGGER_CONFIG_SCHEMA
+
 type CalcomTriggerContract<TEvent> = {
-  readonly configSchema: typeof CALCOM_TRIGGER_CONFIG_SCHEMA
+  readonly configSchema: CalcomTriggerConfigSchema
   readonly eventSchema: z.ZodType<TEvent>
 }
 
@@ -444,59 +485,137 @@ type CalcomSemanticContracts = {
   >
 } & { readonly "calcom.event": CalcomTriggerContract<CalcomEvent> }
 
-export const calcomTriggerContracts: CalcomSemanticContracts = {
+export const calcomTriggerContracts = {
   "calcom.afterGuestsCalVideoNoShow": contract(
     "AFTER_GUESTS_CAL_VIDEO_NO_SHOW",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.afterHostsCalVideoNoShow": contract(
+    "AFTER_HOSTS_CAL_VIDEO_NO_SHOW",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.cancelled": contract(
+    "BOOKING_CANCELLED",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.created": contract(
+    "BOOKING_CREATED",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.locationUpdated": contract(
+    "BOOKING_LOCATION_UPDATED",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.noShowUpdated": contract(
+    "BOOKING_NO_SHOW_UPDATED",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.paid": contract(
+    "BOOKING_PAID",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.paymentInitiated": contract(
+    "BOOKING_PAYMENT_INITIATED",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.reassigned": contract(
+    "BOOKING_REASSIGNED",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.rejected": contract(
+    "BOOKING_REJECTED",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.requested": contract(
+    "BOOKING_REQUESTED",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.booking.rescheduled": contract(
+    "BOOKING_RESCHEDULED",
+    CALCOM_TEAM_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.calendarEntryRejected": contract(
+    "CALENDAR_ENTRY_REJECTED",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.delegationCredential.error": contract(
+    "DELEGATION_CREDENTIAL_ERROR",
+    CALCOM_ORGANIZATION_TRIGGER_CONFIG_SCHEMA,
   ),
-  "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_ORGANIZATION_TRIGGER_CONFIG_SCHEMA,
   ),
   "calcom.delegationCredential.secretRotated": contract(
     "DELEGATION_CREDENTIAL_SECRET_ROTATED",
+    CALCOM_ORGANIZATION_TRIGGER_CONFIG_SCHEMA,
   ),
   "calcom.delegationCredential.secretRotationFailed": contract(
     "DELEGATION_CREDENTIAL_SECRET_ROTATION_FAILED",
+    CALCOM_ORGANIZATION_TRIGGER_CONFIG_SCHEMA,
   ),
   "calcom.event": {
-    configSchema: CALCOM_TRIGGER_CONFIG_SCHEMA,
+    configSchema: CALCOM_BROAD_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.form.submitted": contract(
+    "FORM_SUBMITTED",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.form.submittedWithoutEvent": contract(
+    "FORM_SUBMITTED_NO_EVENT",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.instantMeeting.accepted": contract(
+    "INSTANT_MEETING_ACCEPTED",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.instantMeeting.created": contract(
+    "INSTANT_MEETING",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.meeting.ended": contract(
+    "MEETING_ENDED",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.meeting.started": contract(
+    "MEETING_STARTED",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.outOfOffice.created": contract(
+    "OOO_CREATED",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.recording.ready": contract(
+    "RECORDING_READY",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
   "calcom.recording.transcriptionGenerated": contract(
     "RECORDING_TRANSCRIPTION_GENERATED",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
   ),
-  "calcom.routingForm.fallbackHit": contract("ROUTING_FORM_FALLBACK_HIT"),
-  "calcom.wrongAssignmentReported": contract("WRONG_ASSIGNMENT_REPORT"),
-}
+  "calcom.routingForm.fallbackHit": contract(
+    "ROUTING_FORM_FALLBACK_HIT",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+  "calcom.wrongAssignmentReported": contract(
+    "WRONG_ASSIGNMENT_REPORT",
+    CALCOM_USER_TRIGGER_CONFIG_SCHEMA,
+  ),
+} as const satisfies CalcomSemanticContracts
 
 /**
  * Builds one trigger contract for an exact Cal.com provider event.
  *
  * @param type Exact Cal.com provider event type.
+ * @param configSchema Trigger configuration schema.
  */
-function contract<TType extends CalcomWebhookTriggerType>(type: TType) {
+function contract<
+  TType extends CalcomWebhookTriggerType,
+  TConfigSchema extends CalcomTriggerConfigSchema,
+>(type: TType, configSchema: TConfigSchema) {
   return {
-    configSchema: CALCOM_TRIGGER_CONFIG_SCHEMA,
+    configSchema,
     eventSchema: calcomSemanticEventSchema(type),
   }
 }

package/src/krisp/api.ts

@@ -0,0 +1,215 @@
+import type { Encodable } from "@automate.ax/codec"
+import { encodableSchema } from "@automate.ax/codec"
+import * as z from "zod"
+
+const KRISP_API_BASE_URL = "https://meeting-api.krisp.ai/v1/"
+const KRISP_API_ORIGIN = new URL(KRISP_API_BASE_URL).origin
+const KRISP_SECRET_SCHEMA = z.object({ apiKey: z.string().min(1) })
+
+/** Options for one authenticated Krisp REST request. */
+export interface KrispRequestOptions<TSchema extends z.ZodType> {
+  /** Public camelCase JSON body. */
+  body?: Encodable
+
+  /** HTTP verb. Defaults to `GET`. */
+  method?: "GET" | "POST"
+
+  /** Public camelCase query parameters. */
+  query?: Record<
+    string,
+    boolean | number | readonly string[] | string | undefined
+  >
+
+  /** Schema for the normalized provider response. */
+  responseSchema: TSchema
+}
+
+/** Structured Krisp REST failure. */
+export class KrispApiError extends Error {
+  /** Normalized provider error payload, when valid JSON was returned. */
+  readonly body?: Encodable
+
+  /** Retry delay in seconds, when Krisp returned one. */
+  readonly retryAfter?: number
+
+  /** HTTP status returned by Krisp. */
+  readonly status: number
+
+  /**
+   * Creates a structured Krisp API error.
+   *
+   * @param options - Provider status, body, and retry metadata.
+   * @param options.body - Normalized provider error body.
+   * @param options.retryAfter - Retry delay in seconds.
+   * @param options.status - HTTP status.
+   */
+  constructor(options: {
+    body?: Encodable
+    retryAfter?: number
+    status: number
+  }) {
+    super(
+      getErrorMessage(options.body) ??
+        `Krisp API request failed with status ${options.status}.`,
+    )
+    this.name = "KrispApiError"
+    this.body = options.body
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates an authenticated Krisp Meeting Assistant REST client.
+ *
+ * @param secret - Resolved Krisp API-key secret.
+ */
+export function getKrispApi(secret: Record<string, unknown>) {
+  const { apiKey } = KRISP_SECRET_SCHEMA.parse(secret)
+
+  return {
+    /**
+     * Runs one Krisp request and returns its normalized response.
+     *
+     * @param path - API path relative to the v1 root.
+     * @param options - Method, parameters, and response schema.
+     */
+    async request<TSchema extends z.ZodType>(
+      path: string,
+      options: KrispRequestOptions<TSchema>,
+    ): Promise<z.output<TSchema>> {
+      const url = new URL(path.replace(/^\//, ""), KRISP_API_BASE_URL)
+      if (url.origin !== KRISP_API_ORIGIN) {
+        throw new Error("Krisp API paths must use the Krisp API origin.")
+      }
+      for (const [name, value] of Object.entries(options.query ?? {})) {
+        if (value === undefined) continue
+        url.searchParams.set(
+          toSnakeCase(name),
+          Array.isArray(value) ? value.join(",") : String(value),
+        )
+      }
+      const response = await fetch(url, {
+        body:
+          options.body === undefined
+            ? undefined
+            : JSON.stringify(toKrisp(options.body)),
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${apiKey}`,
+          ...(options.body === undefined
+            ? {}
+            : { "Content-Type": "application/json" }),
+        },
+        method: options.method ?? "GET",
+      })
+      const normalized = fromKrisp(parseJson(await response.text()))
+      if (!response.ok) {
+        const body = encodableSchema.safeParse(normalized)
+        throw new KrispApiError({
+          ...(body.success && { body: body.data }),
+          retryAfter: parseFiniteNumber(response.headers.get("Retry-After")),
+          status: response.status,
+        })
+      }
+      return options.responseSchema.parse(normalized)
+    },
+  }
+}
+
+/**
+ * Converts public camelCase JSON to Krisp wire keys.
+ *
+ * @param value - Public value to normalize.
+ */
+export function toKrisp(value: Encodable): Encodable {
+  if (value instanceof Date) return value.toISOString()
+  if (Array.isArray(value)) return value.map(toKrisp)
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      toSnakeCase(key),
+      toKrisp(item),
+    ]),
+  )
+}
+
+/**
+ * Converts Krisp wire JSON to public camelCase keys.
+ *
+ * @param value - Provider value to normalize.
+ */
+export function fromKrisp(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(fromKrisp)
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      toCamelCase(key),
+      fromKrisp(item),
+    ]),
+  )
+}
+
+/**
+ * Checks whether a value is a key-value object.
+ *
+ * @param value - Candidate value.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Parses a JSON response body without obscuring the HTTP status on failure.
+ *
+ * @param value - Raw response text.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Parses an optional finite numeric header.
+ *
+ * @param value - Raw header value.
+ */
+function parseFiniteNumber(value: string | null) {
+  if (value === null) return undefined
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}
+
+/**
+ * Extracts Krisp's human-readable error string.
+ *
+ * @param body - Normalized provider error body.
+ */
+function getErrorMessage(body: Encodable | undefined) {
+  return isPlainObject(body) && typeof body.error === "string"
+    ? body.error
+    : undefined
+}
+
+/**
+ * Converts one public camelCase key to Krisp snake_case.
+ *
+ * @param value - Public key.
+ */
+function toSnakeCase(value: string) {
+  return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+}
+
+/**
+ * Converts one Krisp snake_case key to public camelCase.
+ *
+ * @param value - Provider key.
+ */
+function toCamelCase(value: string) {
+  return value.replace(/_([a-z0-9])/g, (_, letter: string) =>
+    letter.toUpperCase(),
+  )
+}

package/src/krisp/index.ts

@@ -0,0 +1,2 @@
+export * from "./api"
+export * from "./schemas"

package/src/krisp/schemas.ts

@@ -0,0 +1,122 @@
+import * as z from "zod"
+import type { Encodable } from "@automate.ax/codec"
+
+const DATE_TIME_SCHEMA = z.iso.datetime({ offset: true })
+
+/** Krisp profile represented by a personal API key. */
+export const KRISP_PROFILE_SCHEMA = z.object({
+  avatar: z.url().nullable().prefault(null),
+  email: z.email(),
+  firstName: z.string().nullable().prefault(null),
+  id: z.number().int().positive(),
+  lastName: z.string().nullable().prefault(null),
+  teamId: z.number().int().positive(),
+  workspaceId: z.number().int().positive(),
+})
+
+/** Calendar attendee or diarized speaker attached to a Krisp meeting. */
+export const KRISP_PARTICIPANT_SCHEMA = z.object({
+  email: z.string().nullable().prefault(null),
+  firstName: z.string().nullable().prefault(null),
+  lastName: z.string().nullable().prefault(null),
+  photo: z.url().nullable().prefault(null),
+  status: z.string().nullable().prefault(null),
+})
+
+/** Meeting metadata returned by Krisp list and detail endpoints. */
+export const KRISP_MEETING_SCHEMA = z.object({
+  duration: z.number().int().nonnegative().nullable(),
+  id: z.string().min(1),
+  ownership: z.enum(["owned", "shared"]),
+  participants: KRISP_PARTICIPANT_SCHEMA.array().optional(),
+  source: z.string().nullable(),
+  startedAt: DATE_TIME_SCHEMA.nullable(),
+  status: z.string(),
+  tags: z.string().array(),
+  title: z.string(),
+})
+
+/** One diarized transcript segment. Times are seconds from recording start. */
+export const KRISP_TRANSCRIPT_SEGMENT_SCHEMA = z.object({
+  end: z.number().nonnegative(),
+  speaker: z.number().int().nonnegative(),
+  start: z.number().nonnegative(),
+  text: z.string(),
+})
+
+const KRISP_NOTE_ASSIGNEE_SCHEMA = z.record(z.string(), z.json())
+
+export interface KrispNoteBlock {
+  [key: string]: Encodable
+  assignee?: z.output<typeof KRISP_NOTE_ASSIGNEE_SCHEMA> | null
+  children?: KrispNoteBlock[]
+  completed?: boolean | null
+  dueDate?: string | null
+  text?: string
+  type: string
+}
+
+/** Recursive block returned by Krisp's fixed and custom meeting-note sections. */
+export const KRISP_NOTE_BLOCK_SCHEMA: z.ZodType<KrispNoteBlock> = z.lazy(() =>
+  z.object({
+    assignee: KRISP_NOTE_ASSIGNEE_SCHEMA.nullable().optional(),
+    children: KRISP_NOTE_BLOCK_SCHEMA.array().optional(),
+    completed: z.boolean().nullable().optional(),
+    dueDate: z.string().nullable().optional(),
+    text: z.string().optional(),
+    type: z.string(),
+  }),
+)
+
+/** Complete Krisp meeting detail with optional heavy transcript and note data. */
+export const KRISP_MEETING_DETAIL_SCHEMA = KRISP_MEETING_SCHEMA.extend({
+  language: z.string().nullable().prefault(null),
+  meetingType: z.string().nullable().prefault(null),
+  notes: z
+    .object({ blocks: KRISP_NOTE_BLOCK_SCHEMA.array() })
+    .nullable()
+    .optional(),
+  transcript: z
+    .object({
+      language: z.string().nullable().prefault(null),
+      segments: KRISP_TRANSCRIPT_SEGMENT_SCHEMA.array().prefault([]),
+      speakers: z.record(z.string(), KRISP_PARTICIPANT_SCHEMA).prefault({}),
+    })
+    .nullable()
+    .optional(),
+})
+
+/** One action item extracted from a Krisp meeting. */
+export const KRISP_ACTION_ITEM_SCHEMA = z.object({
+  assignee: KRISP_PARTICIPANT_SCHEMA.nullable().prefault(null),
+  completed: z.boolean().nullable().prefault(null),
+  dueDate: z.string().nullable().prefault(null),
+  id: z.string().min(1),
+  meetingId: z.string().min(1),
+  meetingStartedAt: DATE_TIME_SCHEMA.nullable().prefault(null),
+  meetingTitle: z.string(),
+  title: z.string(),
+})
+
+/** Tag used to organize Krisp meetings. */
+export const KRISP_TAG_SCHEMA = z.object({
+  color: z.string().nullable(),
+  createdAt: DATE_TIME_SCHEMA,
+  id: z.string().min(1),
+  name: z.string(),
+})
+
+/** Recording-import identity returned after Krisp issues an upload URL. */
+export const KRISP_IMPORT_SCHEMA = z.object({
+  expiresAt: DATE_TIME_SCHEMA,
+  importId: z.string().min(1),
+  url: z.url(),
+})
+
+/** Current processing state for a Krisp recording import. */
+export const KRISP_IMPORT_STATUS_SCHEMA = z.object({
+  error: z.string().nullable().prefault(null),
+  importId: z.string().min(1),
+  meetingId: z.string().min(1).nullable().prefault(null),
+  status: z.enum(["uploading", "processing", "ready", "failed"]),
+})