@automate.ax/integration-contracts 0.144.2 → 0.145.0

package/src/calcom/api.ts

@@ -0,0 +1,289 @@
+import type { Encodable } from "@automate.ax/codec"
+import { encodableSchema } from "@automate.ax/codec"
+import * as z from "zod"
+import {
+  calcomSchema,
+  type CalcomSchemaName,
+  type CalcomSchemaValue,
+} from "./schemas"
+
+const CALCOM_API_BASE_URL = "https://api.cal.com/v2/"
+const CALCOM_API_ORIGIN = new URL(CALCOM_API_BASE_URL).origin
+const CALCOM_API_KEY_SECRET_SCHEMA = z.object({
+  apiKey: z.string().trim().min(1),
+})
+
+/** Resolved account accepted by the shared Cal.com API client. */
+export interface CalcomResolvedAccount {
+  connectionMethodId: string
+  secret: Record<string, unknown>
+  serviceId: "calcom"
+}
+
+/** Options for one authenticated Cal.com REST request. */
+export interface CalcomRequestOptions {
+  /** Cal.com request body using provider-native camelCase fields. */
+  body?: Encodable
+
+  /** Version required by the selected Cal.com endpoint. */
+  apiVersion?: string
+
+  /** HTTP verb. Defaults to `GET`. */
+  method?: "DELETE" | "GET" | "PATCH" | "POST" | "PUT"
+
+  /** Query parameters accepted by the selected endpoint. */
+  query?: Record<
+    string,
+    boolean | number | string | (boolean | number | string)[] | null | undefined
+  >
+}
+
+/** Options for one Cal.com REST request with a JSON response. */
+export interface CalcomJsonRequestOptions<TName extends CalcomSchemaName>
+  extends CalcomRequestOptions {
+  /** Frozen OpenAPI response component name. */
+  responseSchema: TName
+}
+
+/** Structured error returned by a rejected Cal.com request. */
+export class CalcomApiError extends Error {
+  readonly body?: Encodable
+  readonly retryAfter?: number
+  readonly status: number
+
+  /**
+   * Creates an error from one rejected Cal.com response.
+   *
+   * @param options Rejected response details.
+   * @param options.body Parsed provider response body.
+   * @param options.retryAfter Provider retry delay in seconds.
+   * @param options.status HTTP response status.
+   */
+  constructor(options: {
+    body?: Encodable
+    retryAfter?: number
+    status: number
+  }) {
+    super(
+      getErrorMessage(options.body) ??
+        `Cal.com API request failed with status ${options.status}.`,
+    )
+    this.name = "CalcomApiError"
+    this.body = options.body
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates an authenticated Cal.com API v2 client.
+ *
+ * @param account Resolved Cal.com API-key account.
+ * @throws When the account uses an unsupported connection method.
+ */
+export function getCalcomApi(account: CalcomResolvedAccount) {
+  const accessToken =
+    account.connectionMethodId === "api-key"
+      ? CALCOM_API_KEY_SECRET_SCHEMA.parse(account.secret).apiKey
+      : undefined
+  if (!accessToken) {
+    throw new Error(
+      `Unsupported Cal.com connection method: ${account.connectionMethodId}`,
+    )
+  }
+
+  return {
+    /**
+     * Sends one request whose JSON response is described inline by Cal.com.
+     *
+     * @param path Relative Cal.com API v2 path.
+     * @param options Request options.
+     */
+    async requestJson(path: string, options: CalcomRequestOptions) {
+      return encodableSchema.parse(
+        await sendCalcomRequest(accessToken, path, options),
+      )
+    },
+
+    /**
+     * Sends one request and validates the complete provider response.
+     *
+     * @param path Relative Cal.com API v2 path.
+     * @param options Request options and response schema.
+     */
+    async request<TName extends CalcomSchemaName>(
+      path: string,
+      options: CalcomJsonRequestOptions<TName>,
+    ): Promise<CalcomSchemaValue<TName>> {
+      return calcomSchema(options.responseSchema).parse(
+        await sendCalcomRequest(accessToken, path, options),
+      )
+    },
+
+    /**
+     * Sends one request whose successful response has no JSON contract.
+     *
+     * @param path Relative Cal.com API v2 path.
+     * @param options Request options.
+     */
+    async requestVoid(path: string, options: CalcomRequestOptions) {
+      await sendCalcomRequest(accessToken, path, options)
+    },
+  }
+}
+
+/**
+ * Encodes every interpolation as one Cal.com URL path segment.
+ *
+ * @param strings Static template segments.
+ * @param values Dynamic path segments.
+ */
+export function calcomPath(
+  strings: TemplateStringsArray,
+  ...values: (number | string)[]
+) {
+  return strings.reduce(
+    (path, part, index) =>
+      `${path}${index === 0 ? "" : encodeURIComponent(String(values[index - 1]))}${part}`,
+    "",
+  )
+}
+
+/**
+ * Sends one authenticated request and parses its response.
+ *
+ * @param accessToken API key.
+ * @param path Relative Cal.com API v2 path.
+ * @param options Request options.
+ */
+async function sendCalcomRequest(
+  accessToken: string,
+  path: string,
+  options: CalcomRequestOptions,
+) {
+  const normalizedPath = path.replace(/^\/+/, "")
+  if (
+    !normalizedPath ||
+    normalizedPath.includes("://") ||
+    normalizedPath.includes("\\") ||
+    normalizedPath.includes("?") ||
+    normalizedPath.includes("#") ||
+    normalizedPath.split("/").some(isTraversalSegment)
+  ) {
+    throw new TypeError("Cal.com API paths must be relative.")
+  }
+  const url = new URL(normalizedPath, CALCOM_API_BASE_URL)
+  if (
+    url.origin !== CALCOM_API_ORIGIN ||
+    !url.pathname.startsWith(new URL(CALCOM_API_BASE_URL).pathname)
+  ) {
+    throw new TypeError("Cal.com API paths must remain on api.cal.com.")
+  }
+  for (const [name, value] of Object.entries(options.query ?? {})) {
+    if (value == null) continue
+    if (Array.isArray(value)) {
+      for (const item of value) url.searchParams.append(name, String(item))
+    } else {
+      url.searchParams.set(name, String(value))
+    }
+  }
+
+  const response = await fetch(url, {
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    headers: {
+      Accept: "application/json",
+      Authorization: `Bearer ${accessToken}`,
+      ...(options.apiVersion ? { "cal-api-version": options.apiVersion } : {}),
+      ...(options.body === undefined
+        ? {}
+        : { "Content-Type": "application/json" }),
+    },
+    method: options.method ?? "GET",
+    redirect: "error",
+  })
+  const parsed = parseJson(await response.text())
+  if (!response.ok) {
+    const body = encodableSchema.safeParse(parsed)
+    throw new CalcomApiError({
+      ...(body.success && { body: body.data }),
+      retryAfter: parseRetryAfter(response.headers.get("Retry-After")),
+      status: response.status,
+    })
+  }
+  return parsed
+}
+
+/**
+ * Returns whether one raw URL segment can traverse or inject path separators.
+ *
+ * @param segment Raw relative-path segment.
+ */
+function isTraversalSegment(segment: string) {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(segment)
+  } catch {
+    return true
+  }
+  return (
+    decoded === "." ||
+    decoded === ".." ||
+    decoded.includes("/") ||
+    decoded.includes("\\")
+  )
+}
+
+/**
+ * Removes Cal.com's success envelope.
+ *
+ * @param response Successful Cal.com response.
+ * @param response.data Provider response data.
+ * @param response.status Provider response status.
+ */
+export function unwrapCalcomData<T>(response: { data: T; status: string }) {
+  return response.data
+}
+
+/**
+ * Parses response JSON without masking the provider's HTTP status.
+ *
+ * @param value Raw provider response body.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Parses a provider retry delay expressed as seconds.
+ *
+ * @param value Retry-After header value.
+ */
+function parseRetryAfter(value: string | null) {
+  if (value === null) return undefined
+  const seconds = Number(value)
+  return Number.isFinite(seconds) ? seconds : undefined
+}
+
+/**
+ * Extracts a provider error message from common Cal.com error envelopes.
+ *
+ * @param value Parsed provider response body.
+ */
+function getErrorMessage(value: Encodable | undefined) {
+  if (!isRecord(value)) return undefined
+  const message = (isRecord(value.error) ? value.error : value).message
+  return typeof message === "string" && message ? message : undefined
+}
+
+/**
+ * Returns whether a value is a non-array object.
+ *
+ * @param value Candidate value.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}