Aurinko.API.Calendar (Aurinko v0.2.1)

Copy Markdown View Source

Aurinko Calendar API — calendars, events, sync, and free/busy scheduling.

Supports Google Calendar, Outlook/Office 365, iCloud Calendar, and MS Exchange.

Sync Model

Calendar sync is per-calendar. Use primary as the calendar ID for the user's primary calendar.

# Start sync for primary calendar
{:ok, sync} = Aurinko.Calendar.start_sync(token, "primary",
  time_min: ~U[2024-01-01 00:00:00Z],
  time_max: ~U[2024-12-31 23:59:59Z]
)

# Load updated events
{:ok, page} = Aurinko.Calendar.sync_updated(token, "primary", sync.sync_updated_token)

Summary

Functions

create_event(token, calendar_id, params, opts \\ [])

Create a new calendar event.

delete_event(token, calendar_id, event_id, opts \\ [])

Delete a calendar event.

free_busy(token, calendar_id, params)

Check free/busy availability for a calendar in a given time range.

get_calendar(token, calendar_id)

Get a specific calendar by ID. Use "primary" for the user's primary calendar.

get_event(token, calendar_id, event_id)

Get a specific event by ID.

list_calendars(token, opts \\ [])

List all calendars accessible by the authenticated account.

list_events(token, calendar_id, opts \\ [])

List events in a calendar within a time range.

start_sync(token, calendar_id, opts \\ [])

Start or resume a calendar sync for a given calendar.

sync_deleted(token, calendar_id, delta_token, opts \\ [])

Fetch deleted event IDs since the last sync.

sync_updated(token, calendar_id, delta_token, opts \\ [])

Fetch updated (new/modified) calendar events since the last sync.

update_event(token, calendar_id, event_id, params, opts \\ [])

Update an existing calendar event.

Functions

create_event(token, calendar_id, params, opts \\ [])

@spec create_event(String.t(), String.t(), map(), keyword()) ::
  {:ok, Aurinko.Types.CalendarEvent.t()} | {:error, Aurinko.Error.t()}

Create a new calendar event.

Parameters

  • :subject — Event title (required)
  • :start — Start time map with :date_time and :timezone (required)
  • :end — End time map with :date_time and :timezone (required)
  • :body — Event description
  • :location — Event location string
  • :attendees — List of attendee maps with :email and optional :name
  • :is_all_day — Boolean

Options

  • :notify_attendees — Whether to send invitations (default: true)
  • :body_type — "html" or "text"
  • :return_record — Return full event record (default: true)

Examples

{:ok, event} = Aurinko.Calendar.create_event(token, "primary", %{
  subject: "Team Meeting",
  start: %{date_time: ~U[2024-06-01 14:00:00Z], timezone: "UTC"},
  end: %{date_time: ~U[2024-06-01 15:00:00Z], timezone: "UTC"},
  attendees: [%{email: "[email protected]"}],
  location: "Conference Room A"
})

delete_event(token, calendar_id, event_id, opts \\ [])

@spec delete_event(String.t(), String.t(), String.t(), keyword()) ::
  :ok | {:error, Aurinko.Error.t()}

Delete a calendar event.

Options

  • :notify_attendees — Whether to notify attendees of cancellation (default: true)

free_busy(token, calendar_id, params)

@spec free_busy(String.t(), String.t(), map()) ::
  {:ok, map()} | {:error, Aurinko.Error.t()}

Check free/busy availability for a calendar in a given time range.

Parameters

  • :time_min — Start of range (DateTime, required)
  • :time_max — End of range (DateTime, required)

get_calendar(token, calendar_id)

@spec get_calendar(String.t(), String.t()) ::
  {:ok, Aurinko.Types.Calendar.t()} | {:error, Aurinko.Error.t()}

Get a specific calendar by ID. Use "primary" for the user's primary calendar.

get_event(token, calendar_id, event_id)

@spec get_event(String.t(), String.t(), String.t()) ::
  {:ok, Aurinko.Types.CalendarEvent.t()} | {:error, Aurinko.Error.t()}

Get a specific event by ID.

list_calendars(token, opts \\ [])

@spec list_calendars(
  String.t(),
  keyword()
) :: {:ok, [Aurinko.Types.Calendar.t()]} | {:error, Aurinko.Error.t()}

List all calendars accessible by the authenticated account.

list_events(token, calendar_id, opts \\ [])

@spec list_events(String.t(), String.t(), keyword()) ::
  {:ok, Aurinko.Types.Pagination.t()} | {:error, Aurinko.Error.t()}

List events in a calendar within a time range.

Options

  • :time_min — Start of time range (DateTime)
  • :time_max — End of time range (DateTime)
  • :limit — Max results (default: 20)
  • :page_token — Pagination token

start_sync(token, calendar_id, opts \\ [])

@spec start_sync(String.t(), String.t(), keyword()) ::
  {:ok, Aurinko.Types.SyncResult.t()} | {:error, Aurinko.Error.t()}

Start or resume a calendar sync for a given calendar.

Options

  • :time_min — Start of sync range (DateTime)
  • :time_max — End of sync range (DateTime)
  • :await_ready — Block until ready (default: false)

sync_deleted(token, calendar_id, delta_token, opts \\ [])

@spec sync_deleted(String.t(), String.t(), String.t(), keyword()) ::
  {:ok, Aurinko.Types.Pagination.t()} | {:error, Aurinko.Error.t()}

Fetch deleted event IDs since the last sync.

sync_updated(token, calendar_id, delta_token, opts \\ [])

@spec sync_updated(String.t(), String.t(), String.t(), keyword()) ::
  {:ok, Aurinko.Types.Pagination.t()} | {:error, Aurinko.Error.t()}

Fetch updated (new/modified) calendar events since the last sync.

update_event(token, calendar_id, event_id, params, opts \\ [])

@spec update_event(String.t(), String.t(), String.t(), map(), keyword()) ::
  {:ok, Aurinko.Types.CalendarEvent.t()} | {:error, Aurinko.Error.t()}

Update an existing calendar event.

Options

  • :notify_attendees — Whether to notify attendees of changes (default: true)