Types

All types returned by the Recal SDK are fully typed for TypeScript. Below are the core types you'll work with.

User

The user entity represents a person who can connect their calendars to Recal.

Key Features:

• Custom IDs: Map to your database (e.g., user_${yourDbId})
• Multi-Org Support: Users can belong to multiple organizations
• OAuth Connections: Users connect Google, Microsoft calendars

Organization

Organizations group users together for B2B multi-tenancy or team collaboration.

Key Features:

• Unique Slug: Custom identifier for your database mapping
• Team Management: Add/remove members dynamically
• Data Isolation: Each organization's data is completely separate

OAuth Connection

OAuth connections represent a user's authenticated link to a calendar provider.

Key Features:

• Provider Support: Google Calendar, Microsoft Outlook
• Token Management: Automatic refresh token handling
• Scope Control: write (event access), read (read-only), or free-busy (availability only)
• Status Tracking: alive field indicates connection health

Event

Calendar events unified across all providers.

Key Features:

• Unified Format: Same structure regardless of provider
• Meta ID: Optional custom identifier for your database
• Attendees: Email-based participant tracking
• Meeting Links: Automatic Google Meet/Teams integration
• ISO Timestamps: All dates in ISO 8601 format

Attendee

Represents a participant in a calendar event.

Calendar

Represents a calendar from a connected provider.

CreateEvent

Payload for creating a new event.

UpdateEvent

Payload for updating an existing event. All fields are optional.

TimeRange

Represents a time range with start and end timestamps.

Enums and Unions

Provider

Calendar provider types supported by Recal.

type Provider = 'google' | 'microsoft'

CalendarAccessRole

User's access level for a calendar.

type CalendarAccessRole = 'owner' | 'writer' | 'reader' | 'freeBusyReader'

• owner: Full control over the calendar
• writer: Can create and modify events
• reader: Read-only access to events
• freeBusyReader: Can only see free/busy information

DayOfWeek

Days of the week for scheduling.

type DayOfWeek =
  | 'monday'
  | 'tuesday'
  | 'wednesday'
  | 'thursday'
  | 'friday'
  | 'saturday'
  | 'sunday'

OAuthAccessType

OAuth access type for token management.

type OAuthAccessType = 'online' | 'offline'

• offline: Returns both access and refresh tokens (recommended for server apps)
• online: Returns only access tokens

OAuthScope

OAuth permission scopes for calendar access.

type OAuthScope = 'write' | 'read' | 'free-busy'

• write: Read/write access to events (also accepts deprecated edit)
• read: Read-only access to calendars and events
• free-busy: Read-only access to availability information

AttendeeResponseStatus

Attendee response status for event invitations.

type AttendeeResponseStatus =
  | 'needsAction'  // No response yet
  | 'accepted'     // Accepted invitation
  | 'tentative'    // Maybe attending
  | 'declined'     // Declined invitation

Usage Example

import { Recal, type CreateEvent, type Provider } from 'recal-sdk'

const recal = new Recal({ token: process.env.RECAL_TOKEN })

const eventData: CreateEvent = {
    subject: 'Team Meeting',
    start: '2024-01-15T10:00:00Z',
    end: '2024-01-15T11:00:00Z',
    attendees: [
        { email: 'team@example.com' }
    ],
    meeting: true
}

const provider: Provider = 'google'

const event = await recal.events.createEvent(
    'user_123',
    provider,
    'primary',
    eventData
)

Next Steps