@automate.ax/integration-contracts 0.115.6 → 0.118.0

package/src/tidycal/api.ts

@@ -0,0 +1,239 @@
+import type { Encodable } from "@automate.ax/codec"
+import { encodableSchema } from "@automate.ax/codec"
+import * as z from "zod"
+
+const TIDYCAL_API_BASE_URL = "https://tidycal.com/api/"
+const TIDYCAL_API_ORIGIN = new URL(TIDYCAL_API_BASE_URL).origin
+const TIDYCAL_PERSONAL_ACCESS_TOKEN_SECRET_SCHEMA = z.object({
+  apiKey: z.string().min(1),
+})
+const TIDYCAL_OAUTH_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+})
+
+/** Resolved TidyCal account accepted by the shared API client. */
+export interface TidyCalResolvedAccount {
+  connectionMethodId: string
+  secret: Record<string, unknown>
+  serviceId: "tidycal"
+}
+
+/** Options for one authenticated TidyCal REST request. */
+export interface TidyCalRequestOptions<TSchema extends z.ZodType> {
+  /** Public camelCase JSON body. */
+  body?: Encodable
+
+  /** HTTP verb. Defaults to `GET`. */
+  method?: "DELETE" | "GET" | "PATCH" | "POST"
+
+  /** Public camelCase query parameters. */
+  query?: Record<string, boolean | number | string | undefined>
+
+  /** Schema for the normalized provider response. */
+  responseSchema: TSchema
+}
+
+/** Structured TidyCal REST error. */
+export class TidyCalApiError extends Error {
+  /** Normalized provider error payload, when it was valid JSON. */
+  readonly body?: Encodable
+
+  /** Retry delay in seconds, when TidyCal returned one. */
+  readonly retryAfter?: number
+
+  /** HTTP status returned by TidyCal. */
+  readonly status: number
+
+  /**
+   * Creates a structured error from one TidyCal response.
+   *
+   * @param options - Response status, provider body, and retry metadata.
+   * @param options.body - Normalized provider error payload.
+   * @param options.retryAfter - Retry delay in seconds.
+   * @param options.status - HTTP response status.
+   */
+  constructor(options: {
+    body?: Encodable
+    retryAfter?: number
+    status: number
+  }) {
+    super(
+      getErrorMessage(options.body) ??
+        `TidyCal API request failed with status ${options.status}.`,
+    )
+    this.name = "TidyCalApiError"
+    this.body = options.body
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates an authenticated TidyCal REST client.
+ *
+ * @param account - Resolved OAuth or personal-access-token account.
+ * @throws When the connection method or secret shape is unsupported.
+ */
+export function getTidyCalApi(account: TidyCalResolvedAccount) {
+  const accessToken =
+    account.connectionMethodId === "oauth"
+      ? TIDYCAL_OAUTH_SECRET_SCHEMA.parse(account.secret).accessToken
+      : account.connectionMethodId === "personal-access-token"
+        ? TIDYCAL_PERSONAL_ACCESS_TOKEN_SECRET_SCHEMA.parse(account.secret)
+            .apiKey
+        : undefined
+  if (!accessToken) {
+    throw new Error(
+      `Unsupported TidyCal connection method: ${account.connectionMethodId}`,
+    )
+  }
+
+  /**
+   * Runs one request and returns its normalized response.
+   *
+   * @param path - TidyCal API path relative to the API root.
+   * @param options - Method, parameters, and response schema.
+   */
+  async function request<TSchema extends z.ZodType>(
+    path: string,
+    options: TidyCalRequestOptions<TSchema>,
+  ): Promise<z.output<TSchema>> {
+    const url = new URL(path.replace(/^\//, ""), TIDYCAL_API_BASE_URL)
+    if (url.origin !== TIDYCAL_API_ORIGIN) {
+      throw new Error("TidyCal API paths must use the TidyCal API origin.")
+    }
+    for (const [name, value] of Object.entries(options.query ?? {})) {
+      if (value !== undefined)
+        url.searchParams.set(toSnakeCase(name), String(value))
+    }
+    const response = await fetch(url, {
+      body:
+        options.body === undefined
+          ? undefined
+          : JSON.stringify(toTidyCal(options.body)),
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${accessToken}`,
+        ...(options.body === undefined
+          ? {}
+          : { "Content-Type": "application/json" }),
+      },
+      method: options.method ?? "GET",
+    })
+    const normalized = fromTidyCal(parseJson(await response.text()))
+    if (!response.ok) {
+      const body = encodableSchema.safeParse(normalized)
+      throw new TidyCalApiError({
+        ...(body.success && { body: body.data }),
+        retryAfter: parseFiniteNumber(response.headers.get("Retry-After")),
+        status: response.status,
+      })
+    }
+    return options.responseSchema.parse(normalized)
+  }
+
+  return { request }
+}
+
+/**
+ * Converts public camelCase JSON to TidyCal wire keys.
+ *
+ * @param value - Codec-safe public value.
+ */
+export function toTidyCal(value: Encodable): Encodable {
+  if (value instanceof Date) return value.toISOString()
+  if (Array.isArray(value)) return value.map(toTidyCal)
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      toSnakeCase(key),
+      toTidyCal(item),
+    ]),
+  )
+}
+
+/**
+ * Converts TidyCal wire JSON to public camelCase keys.
+ *
+ * @param value - Untrusted provider JSON value.
+ */
+export function fromTidyCal(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(fromTidyCal)
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      toCamelCase(key),
+      fromTidyCal(item),
+    ]),
+  )
+}
+
+/**
+ * Returns whether a value is a plain JSON object.
+ *
+ * @param value - Value to inspect.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Parses JSON without obscuring the eventual structured API error.
+ *
+ * @param value - Response text to parse.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Parses a finite numeric response header.
+ *
+ * @param value - Header value.
+ */
+function parseFiniteNumber(value: string | null) {
+  if (value === null) return undefined
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}
+
+/**
+ * Extracts the provider's primary error text without weakening its payload.
+ *
+ * @param body - Normalized provider error body.
+ */
+function getErrorMessage(body: Encodable | undefined) {
+  if (!isPlainObject(body)) return undefined
+  if (typeof body.message === "string") return body.message
+  const errors = body.errors
+  if (!isPlainObject(errors)) return undefined
+  const first = Object.values(errors)[0]
+  if (typeof first === "string") return first
+  return Array.isArray(first) && typeof first[0] === "string"
+    ? first[0]
+    : undefined
+}
+
+/**
+ * Converts one camelCase public key to snake_case.
+ *
+ * @param value - Public key.
+ */
+function toSnakeCase(value: string) {
+  return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+}
+
+/**
+ * Converts one snake_case provider key to camelCase.
+ *
+ * @param value - Provider key.
+ */
+function toCamelCase(value: string) {
+  return value.replace(/_([a-z0-9])/g, (_, letter: string) =>
+    letter.toUpperCase(),
+  )
+}

package/src/tidycal/index.ts

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

package/src/tidycal/schemas.ts

@@ -0,0 +1,105 @@
+import * as z from "zod"
+
+const DATE_TIME_SCHEMA = z.iso.datetime({ offset: true })
+const ID_SCHEMA = z.number().int().positive()
+
+export const TIDYCAL_ACCOUNT_SCHEMA = z.object({
+  currencySymbol: z.string(),
+  email: z.email(),
+  language: z.string(),
+  lifetimeProAt: DATE_TIME_SCHEMA.nullable(),
+  name: z.string(),
+  profilePictureUrl: z.url().nullable(),
+  vanityPath: z.string(),
+})
+
+export const TIDYCAL_CONTACT_SCHEMA = z.object({
+  createdAt: DATE_TIME_SCHEMA,
+  email: z.email(),
+  id: ID_SCHEMA,
+  ipAddress: z.string().nullable().optional(),
+  name: z.string(),
+  phoneNumber: z.string().nullable().optional(),
+  timezone: z.string().nullable().optional(),
+  updatedAt: DATE_TIME_SCHEMA,
+})
+
+export const TIDYCAL_PAYMENT_SCHEMA = z.object({
+  amount: z.number().nonnegative(),
+  bookingId: ID_SCHEMA,
+  createdAt: DATE_TIME_SCHEMA,
+  currency: z.string(),
+  id: ID_SCHEMA,
+  paymentId: z.string(),
+  updatedAt: DATE_TIME_SCHEMA,
+})
+
+export const TIDYCAL_QUESTION_SCHEMA = z.object({
+  answer: z.string(),
+  bookingId: ID_SCHEMA,
+  createdAt: DATE_TIME_SCHEMA,
+  id: ID_SCHEMA,
+  question: z.string(),
+  updatedAt: DATE_TIME_SCHEMA,
+})
+
+export const TIDYCAL_BOOKING_SCHEMA = z.object({
+  bookingTypeId: ID_SCHEMA,
+  cancelledAt: DATE_TIME_SCHEMA.nullable(),
+  contact: TIDYCAL_CONTACT_SCHEMA,
+  contactId: ID_SCHEMA,
+  createdAt: DATE_TIME_SCHEMA,
+  endsAt: DATE_TIME_SCHEMA,
+  id: ID_SCHEMA,
+  meetingId: z.string().nullable().optional(),
+  meetingUrl: z.url().nullable().optional(),
+  payment: TIDYCAL_PAYMENT_SCHEMA.nullable().optional(),
+  questions: TIDYCAL_QUESTION_SCHEMA.array(),
+  startsAt: DATE_TIME_SCHEMA,
+  timezone: z.string(),
+  updatedAt: DATE_TIME_SCHEMA,
+})
+
+export const TIDYCAL_BOOKING_TYPE_SCHEMA = z.object({
+  bookingThresholdMinutes: z.number().int().min(0),
+  createdAt: DATE_TIME_SCHEMA,
+  currencyCode: z.string().nullable().optional(),
+  description: z.string(),
+  disabledAt: DATE_TIME_SCHEMA.nullable(),
+  durationMinutes: z.number().int().positive(),
+  id: ID_SCHEMA,
+  latestAvailabilityDays: z.number().int().min(0),
+  maxBookings: z.number().int().positive(),
+  paddingMinutes: z.number().int().min(0),
+  paymentPlatform: z.enum(["paypal", "stripe", "tidycal"]).nullable(),
+  paymentPlatformId: z.string().nullable().optional(),
+  price: z.number().nonnegative(),
+  private: z.boolean(),
+  redirectUrl: z.url().nullable(),
+  title: z.string(),
+  updatedAt: DATE_TIME_SCHEMA,
+  url: z.url(),
+  urlSlug: z.string(),
+  userId: ID_SCHEMA,
+})
+
+export const TIDYCAL_TIMESLOT_SCHEMA = z.object({
+  availableBookings: z.number().int().nonnegative(),
+  endsAt: DATE_TIME_SCHEMA,
+  startsAt: DATE_TIME_SCHEMA,
+})
+
+export const TIDYCAL_TEAM_SCHEMA = z.object({
+  createdAt: DATE_TIME_SCHEMA,
+  id: ID_SCHEMA,
+  name: z.string(),
+  updatedAt: DATE_TIME_SCHEMA,
+})
+
+export const TIDYCAL_TEAM_USER_SCHEMA = z.object({
+  createdAt: DATE_TIME_SCHEMA,
+  email: z.email(),
+  id: ID_SCHEMA,
+  name: z.string(),
+  updatedAt: DATE_TIME_SCHEMA,
+})

package/src/triggers.ts

@@ -12,6 +12,7 @@ import type { googleFormsTriggerContracts } from "./google-forms"
 import type { googleMeetTriggerContracts } from "./google-meet"
 import type { googleSheetsTriggerContracts } from "./google-sheets"
 import type { linearTriggerContracts } from "./linear"
+import type { millionVerifierTriggerContracts } from "./millionverifier"
 import type { notionTriggerContracts } from "./notion"
 import type { outlookTriggerContracts } from "./outlook"
 import type { resendTriggerContracts } from "./resend"
@@ -38,6 +39,7 @@ export type TriggerContractMap = typeof airtableTriggerContracts &
   typeof googleMeetTriggerContracts &
   typeof googleSheetsTriggerContracts &
   typeof linearTriggerContracts &
+  typeof millionVerifierTriggerContracts &
   typeof notionTriggerContracts &
   typeof outlookTriggerContracts &
   typeof resendTriggerContracts &