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
| Category | Key Methods |
|---|---|
| Calendars | getCalendars(), getCalendar(), getTodaysEvents() |
| Events | createEvent(), updateEvent(), getEvent(), deleteEvent() |
| Search | searchEvents(), getEventsInDateRange(), getUpcomingEvents() |
| Quick Add | quickAddEvent(), getAllCalendarEvents() |
| Scheduling | isTimeSlotBusy(), getFreeBusy() |
| Management | getColors(), acl.listAcl(), settings.listSettings() |
| Low-Level | events.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'
});