Data types

/** `direct`: confirmed on the spot. `approval`: `pending` until the host decides. */
export type BookingType = 'direct' | 'approval';
 
/**
 * Who can open the hosted page at www.clndr.pro/{username}/{slug}.
 * API keys see all of their owner's pages regardless.
 */
export type Visibility = 'public' | 'private' | 'team';
 
/** The dashboard creates text, email, textarea and phone; select comes with `options`. */
export type QuestionType = 'text' | 'email' | 'textarea' | 'phone' | 'select' | 'checkbox';
 
/** `completed` is reserved; nothing sets it today. */
export type BookingStatus = 'pending' | 'confirmed' | 'cancelled' | 'completed';
 
/**
 * Whether the booking's Google Calendar event was created, as recorded when
 * the guest booked or the host acted in the dashboard. PATCH/DELETE through
 * the API don't update it: check google_calendar_event_id after those.
 */
export type SyncStatus = 'not_synced' | 'pending' | 'synced' | 'failed';

export interface BookingPageSummary {
  /** Send as `bookingPageId` when you create a booking. */
  id: string;
  /** Unique per account: lowercase letters, digits and hyphens. */
  slug: string;
  title: string;
  /** Markdown written by the host. Render it as Markdown. */
  description: string | null;
  /** Length of every slot, 1–480. */
  duration_minutes: number;
  booking_type: BookingType;
  /** How far ahead guests can book. `null` = no limit. */
  max_days_ahead: number | null;
  /** Gap between consecutive slots. */
  buffer_time_minutes: number | null;
  visibility: Visibility;
  /** Confirmed bookings get a Google Calendar event with a Meet link. */
  auto_generate_meet_link: boolean | null;
  /** Inactive pages are listed but can't be read, offer no slots and can't be booked. */
  is_active: boolean | null;
  created_at: string;
}

export interface BookingPage extends BookingPageSummary {
  /** The host's clndr.pro account id. */
  user_id: string;
  updated_at: string;
  /** The availability schedule the page uses. `null` = all of the host's schedules. */
  availability_set_id: string | null;
  /** The team allowed to book a `team` page. */
  allowed_team_id: string | null;
  /** Whether the hosted page asks visitors of a private page for an access code. */
  show_access_code_prompt: boolean;
  /** Whether the page is listed on www.clndr.pro/{username}. */
  show_on_profile: boolean;
}

export interface UserProfile {
  /** 3–30 characters: lowercase letters, digits, `_` and `-`. */
  username: string;
  full_name: string | null;
  bio: string | null;
  avatar_url: string | null;
  /** IANA timezone the host's availability is defined in, e.g. "Europe/London". */
  timezone: string;
}

export interface BookingQuestion {
  /** Send as `responses[].questionId`. */
  id: string;
  question_text: string;
  question_type: QuestionType;
  /** Choices for a `select` question; `null` otherwise. */
  options: string[] | null;
  /** Collect an answer before submitting. The API doesn't enforce it. */
  is_required: boolean | null;
  /** Show questions in ascending order. */
  order_index: number;
}

export interface BookingPageDetail {
  bookingPage: BookingPage;
  userProfile: UserProfile;
  /** Active questions, sorted by `order_index`. */
  questions: BookingQuestion[];
}

export interface TimeSlot {
  /** UTC with milliseconds, e.g. "2026-10-15T08:40:00.000Z". */
  start: string;
  /** `start` plus the page's `duration_minutes`. */
  end: string;
}

export interface Booking {
  id: string;
  booking_page_id: string;
  /** The host. */
  user_id: string;
  guest_name: string;
  guest_email: string;
  /** Postgres timestamps, e.g. "2026-10-15T08:40:00+00:00". Parse with `new Date()`. */
  start_time: string;
  end_time: string;
  status: BookingStatus;
  cancellation_reason: string | null;
  reminder_sent: boolean | null;
  /** Set once a Meet link exists: at booking time on direct pages, at confirmation on approval pages. */
  google_meet_link: string | null;
  google_calendar_event_id: string | null;
  google_calendar_id: string | null;
  /** Not updated by PATCH/DELETE through the API; see SyncStatus. */
  sync_status: SyncStatus;
  last_synced_at: string | null;
  /** Why the Google event couldn't be created, e.g. "Google Calendar is not connected". */
  sync_failure_reason: string | null;
  created_at: string;
  /** Changes on every status change: use it to detect updates when you sync. */
  updated_at: string;
}

export interface BookingResponse {
  question_id: string;
  answer: string;
}
 
export interface BookingWithResponses extends Booking {
  meeting_responses: BookingResponse[];
}

import type { BookingWithResponses } from '@/types/clndr';
 
const booking = (await clndr.bookings.get(id)) as unknown as BookingWithResponses;
for (const r of booking.meeting_responses) console.log(r.question_id, r.answer);

export interface CreateBookingInput {
  /** `id` of one of your booking pages. */
  bookingPageId: string;
  guestName: string;
  /** Confirmation emails go here. */
  guestEmail: string;
  /** A slot's `start`, unchanged. */
  startTime: string;
  /** The same slot's `end`. */
  endTime: string;
  /**
   * Answers, one per answered question. Leave out skipped questions. Every
   * `questionId` must belong to this page: one unknown id and none are saved.
   */
  responses?: Array<{ questionId: string; answer: string }>;
}

export interface UpdateBookingInput {
  status: 'confirmed' | 'cancelled';
  /** Stored as `cancellation_reason`. Omitting it clears any earlier reason. */
  reason?: string;
}

export interface ApiError {
  /** A sentence you can log, e.g. "Booking page not found". */
  error: string;
}

npx openapi-typescript https://docs.clndr.pro/openapi.json -o types/clndr-api.d.ts