Calendar Types

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sam-ayo/recall_sdk/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Core Types

​

CalendarPlatform

type CalendarPlatform = "google_calendar" | "microsoft_outlook";

• google_calendar: Google Calendar integration
• microsoft_outlook: Microsoft Outlook Calendar integration

​

CalendarStatus

type CalendarStatus = "connecting" | "connected" | "disconnected";

• connecting: Calendar is in the process of establishing connection
• connected: Calendar is successfully connected and syncing
• disconnected: Calendar connection is inactive or has been terminated

​

Request Parameters

​

CreateCalendarParams

interface CreateCalendarParams {
  oauth_client_id: string;
  oauth_client_secret: string;
  oauth_refresh_token: string;
  platform: CalendarPlatform;
  oauth_email?: string;
}

• oauth_client_id (required): OAuth 2.0 client ID from the calendar platform
• oauth_client_secret (required): OAuth 2.0 client secret from the calendar platform
• oauth_refresh_token (required): OAuth 2.0 refresh token for maintaining access
• platform (required): Calendar platform type (Google Calendar or Microsoft Outlook)
• oauth_email: Email address associated with the calendar account

​

UpdateCalendarParams

interface UpdateCalendarParams extends BaseCalendarParams, OauthParams {
  platform?: CalendarPlatform;
  oauth_email?: string;
}

• id (required): Calendar integration identifier (inherited from BaseCalendarParams)
• oauth_client_id: Updated OAuth client ID
• oauth_client_secret: Updated OAuth client secret
• oauth_refresh_token: Updated OAuth refresh token
• platform: Updated calendar platform
• oauth_email: Updated email address

​

BaseCalendarParams

interface BaseCalendarParams {
  id: string;
}

• id: Unique identifier for the calendar integration

​

ListCalendarParams

interface ListCalendarParams {
  created_at__gte?: Date;
  cursor?: string;
  email?: string;
  platform?: CalendarPlatform;
  status?: CalendarStatus;
}

• created_at__gte: Filter calendars created on or after this date (greater than or equal)
• cursor: Pagination cursor for fetching the next page of results
• email: Filter calendars by associated email address
• platform: Filter by calendar platform (Google Calendar or Microsoft Outlook)
• status: Filter by connection status

​

Response Types

​

CreateCalendarResponse

interface CreateCalendarResponse extends OauthParams {
  platform: CalendarPlatform;
  oauth_email: string;
}

• platform: The calendar platform that was connected
• oauth_email: Email address associated with the calendar
• oauth_client_id: Client ID used (may be masked for security)
• oauth_client_secret: Client secret used (may be masked for security)
• oauth_refresh_token: Refresh token (may be masked for security)

​

Internal Types

​

OauthParams

interface OauthParams {
  oauth_client_id?: string;
  oauth_client_secret?: string;
  oauth_refresh_token?: string;
}

• oauth_client_id: OAuth client identifier
• oauth_client_secret: OAuth client secret key
• oauth_refresh_token: Token for refreshing access credentials

​

Example Usage

​

Creating a Google Calendar Integration

import { RecallAI } from '@recall-ai/sdk';
import type { CreateCalendarParams } from '@recall-ai/sdk';

const recall = new RecallAI({ apiKey: 'your-api-key' });

const params: CreateCalendarParams = {
  oauth_client_id: 'your-google-client-id',
  oauth_client_secret: 'your-google-client-secret',
  oauth_refresh_token: 'your-refresh-token',
  platform: 'google_calendar',
  oauth_email: '[email protected]'
};

const calendar = await recall.calendar.create(params);
console.log('Calendar connected:', calendar.oauth_email);

​

Creating a Microsoft Outlook Integration

import type { CreateCalendarParams } from '@recall-ai/sdk';

const params: CreateCalendarParams = {
  oauth_client_id: 'your-microsoft-client-id',
  oauth_client_secret: 'your-microsoft-client-secret',
  oauth_refresh_token: 'your-refresh-token',
  platform: 'microsoft_outlook',
  oauth_email: '[email protected]'
};

const calendar = await recall.calendar.create(params);

​

Listing Calendar Integrations

import type { ListCalendarParams, CalendarStatus } from '@recall-ai/sdk';

const filters: ListCalendarParams = {
  platform: 'google_calendar',
  status: 'connected',
  created_at__gte: new Date('2024-01-01')
};

const calendars = await recall.calendar.list(filters);
console.log(`Found ${calendars.length} connected Google Calendars`);

​

Updating a Calendar Integration

import type { UpdateCalendarParams } from '@recall-ai/sdk';

const params: UpdateCalendarParams = {
  id: 'calendar-123',
  oauth_refresh_token: 'new-refresh-token',
  oauth_email: '[email protected]'
};

const updated = await recall.calendar.update(params);

​

Filtering by Status

import type { ListCalendarParams } from '@recall-ai/sdk';

// Find all disconnected calendars that need attention
const disconnected: ListCalendarParams = {
  status: 'disconnected'
};

const needsReauth = await recall.calendar.list(disconnected);

for (const cal of needsReauth) {
  console.log(`Calendar ${cal.oauth_email} needs reauthentication`);
}

​

Filtering by Email and Platform

import type { ListCalendarParams } from '@recall-ai/sdk';

const filters: ListCalendarParams = {
  email: '[email protected]',
  platform: 'microsoft_outlook'
};

const calendars = await recall.calendar.list(filters);

​

OAuth Setup

​

Google Calendar

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API
4. Create OAuth 2.0 credentials (Web application)
5. Configure authorized redirect URIs
6. Obtain the client ID and client secret
7. Use the OAuth flow to get a refresh token

​

Microsoft Outlook

1. Go to Azure Portal
2. Register a new application in Azure AD
3. Add Microsoft Graph API permissions for Calendar
4. Create a client secret
5. Configure redirect URIs
6. Use the OAuth 2.0 authorization code flow to get a refresh token

​

Security Considerations

• Never expose OAuth credentials in client-side code or public repositories
• Store client secrets and refresh tokens securely (e.g., environment variables, secrets manager)
• Implement proper error handling for expired or invalid tokens
• Use HTTPS for all OAuth redirect URIs
• Regularly rotate OAuth credentials per your security policy
• Monitor calendar connection status and alert on disconnections

​

Pagination

let cursor: string | undefined;
const allCalendars = [];

do {
  const params: ListCalendarParams = { cursor };
  const response = await recall.calendar.list(params);
  
  allCalendars.push(...response.results);
  cursor = response.next_cursor;
} while (cursor);

console.log(`Retrieved ${allCalendars.length} total calendars`);