Cal.com Scheduling Integration

# Cal.com Scheduling Integration for Google Antigravity IDE

Integrate Cal.com scheduling into your applications using Google Antigravity IDE. This guide covers API integration, embedded booking, webhooks, and custom availability patterns for appointment-based features.

## API Client Setup

```typescript
// src/lib/cal.ts
import { createClient, type CalClient } from "@calcom/sdk";

export const cal = createClient({
  apiKey: process.env.CAL_API_KEY!,
  baseUrl: process.env.CAL_API_URL ?? "https://api.cal.com/v1",
});

// Type definitions
export interface EventType {
  id: number;
  title: string;
  slug: string;
  length: number;
  description?: string;
  locations: Array<{
    type: string;
    link?: string;
    address?: string;
  }>;
  customInputs: Array<{
    id: number;
    label: string;
    type: "text" | "textLong" | "number" | "bool" | "phone";
    required: boolean;
  }>;
}

export interface Booking {
  id: number;
  uid: string;
  title: string;
  description?: string;
  startTime: string;
  endTime: string;
  attendees: Array<{
    email: string;
    name: string;
    timeZone: string;
  }>;
  status: "ACCEPTED" | "PENDING" | "CANCELLED" | "REJECTED";
  location?: string;
  metadata: Record<string, unknown>;
}

export interface AvailabilitySlot {
  start: string;
  end: string;
}
```

## Availability and Booking API

```typescript
// src/services/scheduling.ts
import { cal, type Booking, type AvailabilitySlot } from "@/lib/cal";

export async function getEventTypes(): Promise<EventType[]> {
  const response = await cal.get("/event-types");
  return response.event_types;
}

export async function getAvailability(
  eventTypeId: number,
  dateFrom: string,
  dateTo: string,
  timeZone: string = "UTC"
): Promise<AvailabilitySlot[]> {
  const response = await cal.get("/availability", {
    params: {
      eventTypeId,
      dateFrom,
      dateTo,
      timeZone,
    },
  });

  return response.slots.flatMap((day: { slots: AvailabilitySlot[] }) => day.slots);
}

export async function createBooking(data: {
  eventTypeId: number;
  start: string;
  end: string;
  name: string;
  email: string;
  timeZone: string;
  notes?: string;
  customInputs?: Record<string, string | number | boolean>;
  metadata?: Record<string, unknown>;
}): Promise<Booking> {
  const response = await cal.post("/bookings", {
    eventTypeId: data.eventTypeId,
    start: data.start,
    end: data.end,
    responses: {
      name: data.name,
      email: data.email,
      notes: data.notes,
      ...data.customInputs,
    },
    timeZone: data.timeZone,
    language: "en",
    metadata: data.metadata,
  });

  return response.booking;
}

export async function cancelBooking(
  bookingId: number,
  reason?: string
): Promise<void> {
  await cal.delete(`/bookings/${bookingId}`, {
    data: { reason },
  });
}

export async function rescheduleBooking(
  bookingId: number,
  newStart: string,
  reason?: string
): Promise<Booking> {
  const response = await cal.patch(`/bookings/${bookingId}`, {
    start: newStart,
    rescheduleReason: reason,
  });

  return response.booking;
}
```

## Embedded Booking Component

```typescript
// src/components/BookingEmbed.tsx
"use client";

import { useEffect, useRef, useState } from "react";
import Cal, { getCalApi } from "@calcom/embed-react";

interface BookingEmbedProps {
  calLink: string;
  eventTypeSlug?: string;
  prefillData?: {
    name?: string;
    email?: string;
    notes?: string;
    guests?: string[];
    customInputs?: Record<string, string>;
  };
  onBookingComplete?: (booking: { uid: string; title: string }) => void;
  theme?: "light" | "dark" | "auto";
  hideEventTypeDetails?: boolean;
}

export function BookingEmbed({
  calLink,
  eventTypeSlug,
  prefillData,
  onBookingComplete,
  theme = "auto",
  hideEventTypeDetails = false,
}: BookingEmbedProps) {
  const [isReady, setIsReady] = useState(false);
  const calRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    (async () => {
      const cal = await getCalApi();
      
      // Configure UI settings
      cal("ui", {
        theme,
        hideEventTypeDetails,
        layout: "month_view",
        styles: {
          branding: { brandColor: "#3b82f6" },
        },
      });

      // Listen for booking events
      cal("on", {
        action: "bookingSuccessful",
        callback: (e) => {
          onBookingComplete?.(e.detail.data);
        },
      });

      setIsReady(true);
    })();
  }, [theme, hideEventTypeDetails, onBookingComplete]);

  const calUrl = eventTypeSlug
    ? `${calLink}/${eventTypeSlug}`
    : calLink;

  return (
    <div ref={calRef} className="cal-embed-container">
      {isReady && (
        <Cal
          calLink={calUrl}
          config={{
            name: prefillData?.name,
            email: prefillData?.email,
            notes: prefillData?.notes,
            guests: prefillData?.guests,
            ...prefillData?.customInputs,
          }}
          style={{
            width: "100%",
            height: "100%",
            overflow: "scroll",
          }}
        />
      )}
    </div>
  );
}
```

## Webhook Handler

```typescript
// src/app/api/webhooks/cal/route.ts
import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";
import { db } from "@/lib/db";
import { sendEmail } from "@/lib/email";

const WEBHOOK_SECRET = process.env.CAL_WEBHOOK_SECRET!;

function verifySignature(payload: string, signature: string): boolean {
  const expectedSignature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

export async function POST(request: NextRequest) {
  const payload = await request.text();
  const signature = request.headers.get("x-cal-signature-256") ?? "";

  if (!verifySignature(payload, signature)) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }

  const event = JSON.parse(payload);

  switch (event.triggerEvent) {
    case "BOOKING_CREATED":
      await handleBookingCreated(event.payload);
      break;
    case "BOOKING_CANCELLED":
      await handleBookingCancelled(event.payload);
      break;
    case "BOOKING_RESCHEDULED":
      await handleBookingRescheduled(event.payload);
      break;
    case "MEETING_ENDED":
      await handleMeetingEnded(event.payload);
      break;
  }

  return NextResponse.json({ received: true });
}

async function handleBookingCreated(booking: Booking) {
  await db.appointment.create({
    data: {
      calBookingId: booking.id,
      calBookingUid: booking.uid,
      title: booking.title,
      startTime: new Date(booking.startTime),
      endTime: new Date(booking.endTime),
      attendeeEmail: booking.attendees[0]?.email,
      attendeeName: booking.attendees[0]?.name,
      status: "scheduled",
    },
  });

  await sendEmail({
    to: booking.attendees[0]?.email,
    template: "booking-confirmation",
    variables: {
      title: booking.title,
      startTime: booking.startTime,
      location: booking.location,
    },
  });
}
```

## Best Practices for Google Antigravity IDE

When integrating Cal.com with Google Antigravity, use the SDK for type-safe API calls. Implement webhook signature verification. Use embedded booking for seamless UX. Cache availability data appropriately. Handle timezone conversions carefully. Let Gemini 3 generate booking flows from your scheduling requirements.

Google Antigravity excels at building complete scheduling integrations with proper error handling.