Fync
Providers

Google Calendar

Manage calendars, events, and scheduling

Google Calendar API

Quick Setup

import { GoogleCalendar } from '@remcostoeten/fync';
const calendar = GoogleCalendar({ token: process.env.GOOGLE_TOKEN! });

Calendar Management

Basic Calendar Operations

// List all calendars
const calendars = await calendar.getCalendars();

// Get specific calendar details
const primaryCalendar = await calendar.getCalendar('primary');
const workCalendar = await calendar.getCalendar('work@example.com');

// Create new calendar
await calendar.calendars.insertCalendar({
  summary: 'Work Schedule',
  description: 'My work-related events',
  timeZone: 'America/New_York'
});

Calendar List Management

// Add calendar to your list
await calendar.calendarList.insertCalendarListEntry({
  id: 'calendar@example.com'
});

// Update calendar settings
await calendar.calendarList.updateCalendarListEntry({
  colorId: '3',
  selected: true,
  defaultReminders: [{ method: 'popup', minutes: 10 }]
}, { calendarId: 'calendar@example.com' });

// Remove from calendar list
await calendar.calendarList.deleteCalendarListEntry({
  calendarId: 'calendar@example.com'
});

📋 Event Management

Creating Events

// Create a simple event
const meeting = await calendar.createEvent('primary', {
  summary: 'Team Meeting',
  description: 'Weekly sync with the team',
  start: { dateTime: '2024-01-15T10:00:00Z' },
  end: { dateTime: '2024-01-15T11:00:00Z' },
  attendees: [
    { email: 'colleague@example.com' },
    { email: 'manager@example.com' }
  ],
  reminders: {
    useDefault: false,
    overrides: [
      { method: 'email', minutes: 1440 }, // 1 day before
      { method: 'popup', minutes: 10 }    // 10 minutes before
    ]
  }
});

// Quick add event from natural language
const lunch = await calendar.quickAddEvent('primary', 'Lunch with Sarah tomorrow at 12:30pm');

Getting Events

// Get upcoming events
const upcomingEvents = await calendar.getUpcomingEvents('primary', 10);

// Get today's events
const todayEvents = await calendar.getTodaysEvents('primary');

// Get events in date range
const weekEvents = await calendar.getEventsInDateRange('primary',
  new Date('2024-01-15'),
  new Date('2024-01-22')
);

// Get specific event
const event = await calendar.getEvent('primary', 'eventId123');

// Get all events from all calendars
const allEvents = await calendar.getAllCalendarEvents(20);

Searching & Filtering Events

// Search events by keyword
const searchResults = await calendar.searchEvents('meeting', 'primary', 25);

// Get events with custom filters
const filteredEvents = await calendar.getEvents('primary', {
  q: 'important',
  timeMin: new Date().toISOString(),
  singleEvents: true,
  orderBy: 'startTime'
});

Updating & Managing Events

// Update event details
await calendar.updateEvent('primary', 'eventId123', {
  summary: 'Updated: Team Meeting',
  description: 'Updated description',
  start: { dateTime: '2024-01-15T10:30:00Z' }, // Changed time
  end: { dateTime: '2024-01-15T11:30:00Z' }
});

// Move event to different calendar
await calendar.events.moveEvent({
  destination: 'work@example.com'
}, { calendarId: 'primary', eventId: 'eventId123' });

// Delete event
await calendar.deleteEvent('primary', 'eventId123');

Calendar Availability & Scheduling

Free/Busy Information

// Check if time slot is busy
const isBusy = await calendar.isTimeSlotBusy('primary',
  new Date('2024-01-15T14:00:00Z'),
  new Date('2024-01-15T15:00:00Z')
);

// Get detailed free/busy info
const freeBusy = await calendar.getFreeBusy({
  timeMin: new Date('2024-01-15T00:00:00Z').toISOString(),
  timeMax: new Date('2024-01-15T23:59:59Z').toISOString(),
  items: [
    { id: 'primary' },
    { id: 'work@example.com' }
  ]
});

Event Instances (Recurring Events)

// Get instances of recurring event
const instances = await calendar.events.getEventInstances({
  calendarId: 'primary',
  eventId: 'recurringEventId'
});

Calendar Customization

Colors & Appearance

// Get available colors
const colors = await calendar.getColors();
console.log('Event colors:', colors.event);
console.log('Calendar colors:', colors.calendar);

Sharing & Permissions (ACL)

// List calendar permissions
const permissions = await calendar.acl.listAcl({ calendarId: 'primary' });

// Share calendar with someone
await calendar.acl.insertAclRule({
  role: 'writer', // 'owner', 'writer', 'reader', 'freeBusyReader'
  scope: {
    type: 'user',
    value: 'colleague@example.com'
  }
}, { calendarId: 'primary' });

// Update permissions
await calendar.acl.updateAclRule({
  role: 'reader'
}, { calendarId: 'primary', ruleId: 'ruleId123' });

// Remove access
await calendar.acl.deleteAclRule({
  calendarId: 'primary',
  ruleId: 'ruleId123'
});

Calendar Settings

// Get user's calendar settings
const settings = await calendar.settings.listSettings();

// Get specific setting
const timeZoneSetting = await calendar.settings.getSetting({
  setting: 'timezone'
});

// Watch for setting changes
await calendar.settings.watchSettings({
  id: 'unique-id',
  type: 'web_hook',
  address: 'https://your-domain.com/webhook'
});

Event Reminders & Notifications

// Create event with custom reminders
const eventWithReminders = await calendar.createEvent('primary', {
  summary: 'Important Meeting',
  start: { dateTime: '2024-01-15T10:00:00Z' },
  end: { dateTime: '2024-01-15T11:00:00Z' },
  reminders: {
    useDefault: false,
    overrides: [
      { method: 'email', minutes: 60 * 24 }, // 1 day before
      { method: 'popup', minutes: 30 },       // 30 minutes before
      { method: 'popup', minutes: 5 }         // 5 minutes before
    ]
  }
});

📋 Quick Reference

CategoryKey Methods
CalendarsgetCalendars(), getCalendar(), getTodaysEvents()
EventscreateEvent(), updateEvent(), getEvent(), deleteEvent()
SearchsearchEvents(), getEventsInDateRange(), getUpcomingEvents()
Quick AddquickAddEvent(), getAllCalendarEvents()
SchedulingisTimeSlotBusy(), getFreeBusy()
ManagementgetColors(), acl.listAcl(), settings.listSettings()
Low-Levelevents.insertEvent(), calendars.insertCalendar(), calendarList.*

🔄 Real-time Updates

Webhooks & Watching

// Watch for event changes
await calendar.events.watchEvents({
  id: 'unique-channel-id',
  type: 'web_hook',
  address: 'https://your-domain.com/webhook'
}, { calendarId: 'primary' });

// Watch for calendar changes
await calendar.calendarList.watchSettings({
  id: 'calendar-watch-123',
  type: 'web_hook',
  address: 'https://your-domain.com/webhook'
});