Ruby SDK

The Mobiscroll Connect Ruby SDK provides a convenient way to integrate Mobiscroll Connect in Ruby backend applications. It requires Ruby 3.1 or higher and is built on Faraday, so it works in any Ruby application (plain Rack, Sinatra, Rails, Hanami, etc.).

RubyGemsmobiscroll-connect

Source Changelog Report an issue

Setup

Install the gem with Bundler:

Bundler
gem

Add to your Gemfile:

gem 'mobiscroll-connect', '~> 1.0'

Then run:

bundle install

gem install mobiscroll-connect

Then require it:

require 'mobiscroll-connect'

Client Initialization

To use the SDK, initialize Mobiscroll::Connect::Client with your client credentials.

Class: Mobiscroll::Connect::Client

constructorClient

Constructor keyword arguments.

client_idString

Your Client ID obtained from the Mobiscroll Connect dashboard.

client_secretString

Your Client Secret obtained from the Mobiscroll Connect dashboard.

redirect_uriString

Your application's redirect URI that matches the one configured in the Mobiscroll Connect dashboard.

base_urlString

Override the API base URL. Defaults to https://connect.mobiscroll.com/api.

timeoutInteger

HTTP timeout in seconds. Defaults to 30.

Usage:

require 'mobiscroll-connect'

client = Mobiscroll::Connect::Client.new(
  client_id:     ENV['MOBISCROLL_CLIENT_ID'],
  client_secret: ENV['MOBISCROLL_CLIENT_SECRET'],
  redirect_uri:  'https://yourapp.com/oauth/callback'
)

For a custom base URL or HTTP timeout:

client = Mobiscroll::Connect::Client.new(
  client_id:     ENV['MOBISCROLL_CLIENT_ID'],
  client_secret: ENV['MOBISCROLL_CLIENT_SECRET'],
  redirect_uri:  'https://yourapp.com/oauth/callback',
  base_url:      'https://connect.mobiscroll.com/api',
  timeout:       60
)

Methods

set_credentials

Stores a token pair the SDK will use on subsequent requests. Typically called after client.auth.get_token or when restoring credentials from persistent storage.

Method: client.set_credentials(tokens)

tokensTokenResponse

The token response returned by client.auth.get_token(code).

on_tokens_refreshed

Registers a callback to be invoked whenever the SDK automatically refreshes the access token. Use this to persist the updated tokens so they survive future requests.

Method: client.on_tokens_refreshed { |tokens| ... }

blockProc

A block that receives the updated TokenResponse after a successful automatic token refresh.

credentials

Returns the currently stored credentials, or nil if none.

Method: client.credentials

Returns: TokenResponse or nil

Token Refresh

The Ruby SDK handles token refresh automatically. When any API call returns a 401 Unauthorized response and the client has a refresh_token stored, the SDK silently exchanges it for a new access token and retries the original request — with no action required from your application. Concurrent calls that hit the same expired token deduplicate into a single refresh via a Monitor and condition variable.

When the refresh succeeds, the SDK invokes your on_tokens_refreshed callback with the updated TokenResponse. You must register this callback and persist the new tokens, otherwise they will be lost between process restarts.

client.on_tokens_refreshed do |tokens|
  # Persist tokens in your database or session store
  # so the new access_token and refresh_token survive future requests
  session[:access_token]  = tokens.access_token
  session[:refresh_token] = tokens.refresh_token if tokens.refresh_token
end

If the refresh token itself is invalid or has been revoked, the SDK raises Mobiscroll::Connect::AuthenticationError and the user must re-authorize.

Error Handling

All SDK errors are subclasses of Mobiscroll::Connect::Error. Rescue the specific subclass to handle each case:

Error class	HTTP Status	Extra attribute
`AuthenticationError`	401, 403	— (raised after refresh + retry has been exhausted)
`CalendarPermissionError`	403	`accounts` — the accounts that must reconnect
`ValidationError`	400, 422	`details`
`NotFoundError`	404	—
`RateLimitError`	429	`retry_after` (seconds)
`ServerError`	5xx	`status_code`
`NetworkError`	—	`cause` (wraps the underlying Faraday error)

begin
  client.events.list(
    start: '2025-10-01T00:00:00Z',
    end:   '2025-10-31T23:59:59Z'
  )
rescue Mobiscroll::Connect::AuthenticationError
  # Token expired and refresh failed — re-authorize the user
rescue Mobiscroll::Connect::ValidationError => e
  puts "Validation failed: #{e.details}"
rescue Mobiscroll::Connect::RateLimitError => e
  sleep(e.retry_after)
rescue Mobiscroll::Connect::Error => e
  # Catch-all for any other SDK error
  puts "SDK error: #{e.message} (#{e.code})"
end

Auth API

The client.auth resource handles the OAuth authorization flow, including generating authorization URLs, exchanging codes for tokens, managing connection status, and disconnecting providers.

Each account returned by get_connection_status reports granted_scopes and calendar_permission_granted. A false flag means the account connected but withheld calendar access on the provider's consent screen, so it can list no calendars until the user reconnects — see Partial consent. Each account also reports syncState: reauth_required means the provider has since rejected the stored credentials and the account has stopped syncing — a different question from calendarPermissionGranted, which only records what was agreed at connect time. See Connection health.

When no connected account has calendar access, calendar and event calls raise CalendarPermissionError — accounts names the accounts that must reconnect. It subclasses AuthenticationError, so existing handlers keep working.

To localize the Connect pages, pass an optional lng to generate_auth_url, e.g. generate_auth_url(user_id: ..., lng: 'es'). When omitted, the UI falls back to the browser's Accept-Language header, then English; Arabic, Hebrew and Persian render right-to-left. See Supported languages for the languages Connect supports.

🔐 OAuth API Reference

auth.generate_auth_url

Builds the URL that starts the authorization flow. Redirect the user to it: once they connect their calendars, Connect redirects them back to your redirect URI with an authorization code. The URL is built locally, without an API request. See GET /authorize.

Method: client.auth.generate_auth_url(user_id:, scope: nil, state: nil, lng: nil)

Returns: String

user_idString

Your identifier for the user. scope, state and lng are optional keyword arguments.

Usage:

# Generate the authorization URL
auth_url = client.auth.generate_auth_url(
  user_id: 'user-456',
  # Optional parameters:
  # scope: 'read-write',
  # state: 'xyz789',
  # lng: 'es' # localize the Connect pages
)

# Redirect the user to auth_url
# redirect auth_url

auth.get_token

Exchanges the authorization code from your redirect URI for an access token and a refresh token. The client stores the returned tokens and uses them for the calls that follow. See POST /token.

Method: client.auth.get_token(code)

Returns: Mobiscroll::Connect::TokenResponse

codeString

The authorization code received on your redirect URI.

Usage:

# Exchange authorization code for access token
# The client is automatically authenticated with the new token
tokens = client.auth.get_token(code)

# Persist tokens server-side keyed by your user
session[:access_token]  = tokens.access_token
session[:refresh_token] = tokens.refresh_token

Calendars API

The client.calendars resource allows you to list available calendars from all connected providers (Google, Outlook, etc.). It corresponds to the /calendars endpoints.

📅 Calendars API Reference

calendars.list

Lists the calendars of every account the user has connected. See GET /calendars.

Method: client.calendars.list

Returns: Array<Mobiscroll::Connect::Calendar>

Usage:

calendars = client.calendars.list

Events API

The client.events resource provides methods to create, read, update, and delete calendar events across all connected accounts. It corresponds to the /events endpoints.

📅 Events API Reference

events.list

Lists events from the user's calendars, one page at a time. When the response contains a next_page_token, pass it to the next call to get the following page. See GET /events.

Method: client.events.list(start: nil, end: nil, calendar_ids: nil, page_size: nil, next_page_token: nil, single_events: nil)

Returns: Mobiscroll::Connect::EventsListResponse

calendar_idsHash

Calendar IDs grouped by provider, for example { Mobiscroll::Connect::Provider::GOOGLE => ['work@company.com'] }. All keyword arguments are optional.

Usage:

# Fetch initial events with date range filter
response = client.events.list(
  page_size: 50,
  start:     '2025-10-01T00:00:00Z',
  end:       '2025-10-31T23:59:59Z'
)

# Load more events using next_page_token
next_response = client.events.list(
  page_size:       50,
  next_page_token: response.next_page_token
)

# Filter by specific calendars
filtered = client.events.list(
  page_size:    25,
  calendar_ids: {
    Mobiscroll::Connect::Provider::GOOGLE => ['personal@gmail.com', 'work@company.com']
  }
)

# Get recurring event series masters (not expanded)
masters = client.events.list(
  page_size:     50,
  single_events: false
)

events.create

Creates an event in the given calendar. Pass a Mobiscroll::Connect::RecurrenceRule as recurrence to create a recurring series. See POST /event.

Method: client.events.create(provider:, calendar_id:, title:, start:, end:, **opts)

Returns: Mobiscroll::Connect::CalendarEvent

optsHash

Optional event fields as keyword arguments, such as description, location, all_day and recurrence. Unrecognized keywords are ignored without an error, so check the spelling.

Usage:

# Create a simple event
event = client.events.create(
  provider:    Mobiscroll::Connect::Provider::GOOGLE,
  calendar_id: 'primary',
  title:       'Team Meeting',
  description: 'Discuss project updates',
  start:       '2025-11-01T10:00:00Z',
  end:         '2025-11-01T11:00:00Z',
  location:    'Conference Room A'
)

# Create a recurring event
recurring_event = client.events.create(
  provider:    Mobiscroll::Connect::Provider::MICROSOFT,
  calendar_id: 'AAMkAGVmMDEz...',
  title:       'Weekly Standup',
  start:       '2025-11-01T09:00:00Z',
  end:         '2025-11-01T09:30:00Z',
  all_day:     false,
  recurrence:  Mobiscroll::Connect::RecurrenceRule.new(
    frequency: 'WEEKLY',
    interval:  1,
    count:     10,
    by_day:    %w[MO WE FR]
  )
)

# Create an all-day event
all_day_event = client.events.create(
  provider:    Mobiscroll::Connect::Provider::APPLE,
  calendar_id: 'https://caldav.icloud.com/.../calendars/...',
  title:       'Conference',
  start:       '2025-11-15T00:00:00Z',
  end:         '2025-11-16T00:00:00Z',
  all_day:     true,
  description: 'Annual tech conference'
)

events.update

Updates an existing event. For an occurrence of a recurring series, set recurring_event_id, and use update_mode to choose which occurrences change: this, following or all. See PUT /event.

Method: client.events.update(provider:, calendar_id:, event_id:, **opts)

Returns: Mobiscroll::Connect::CalendarEvent

optsHash

The fields you want to change as keyword arguments, plus recurring_event_id and update_mode for recurring events. Unrecognized keywords are ignored without an error.

Usage:

# Update a simple event
updated_event = client.events.update(
  provider:    Mobiscroll::Connect::Provider::GOOGLE,
  calendar_id: 'primary',
  event_id:    'event123abc',
  title:       'Updated Team Meeting',
  start:       '2025-11-01T14:00:00Z',
  end:         '2025-11-01T15:00:00Z'
)

# Update a single instance of a recurring event
updated_instance = client.events.update(
  provider:           Mobiscroll::Connect::Provider::MICROSOFT,
  event_id:           'instance456',
  recurring_event_id: 'series123',
  calendar_id:        'AAMkAGVmMDEz...',
  update_mode:        'this',
  title:              'Standup - Special Topic Today',
  start:              '2025-11-01T09:00:00Z',
  end:                '2025-11-01T10:00:00Z'
)

# Update all future occurrences
updated_future = client.events.update(
  provider:    Mobiscroll::Connect::Provider::APPLE,
  event_id:    'recurring-event-id',
  calendar_id: 'https://caldav.icloud.com/.../calendars/...',
  update_mode: 'following',
  location:    'New Conference Room B'
)

events.delete

Deletes an event. For an occurrence of a recurring series, set recurring_event_id, and use delete_mode to choose which occurrences are deleted: this, following or all. See DELETE /event.

Method: client.events.delete(provider:, calendar_id:, event_id:, recurring_event_id: nil, delete_mode: nil)

Returns: nil

Parameters: See Request Body for the full field list.

Usage:

# Delete a simple event
client.events.delete(
  provider:    Mobiscroll::Connect::Provider::GOOGLE,
  calendar_id: 'primary',
  event_id:    'event123abc'
)

# Delete a single instance of a recurring event
client.events.delete(
  provider:           Mobiscroll::Connect::Provider::MICROSOFT,
  calendar_id:        'AAMkAGVmMDEz...',
  event_id:           'instance456',
  recurring_event_id: 'series123',
  delete_mode:        'this'
)

# Delete entire recurring series
client.events.delete(
  provider:    Mobiscroll::Connect::Provider::APPLE,
  calendar_id: 'https://caldav.icloud.com/.../calendars/...',
  event_id:    'recurring-event-id',
  delete_mode: 'all'
)

Webhooks API

The client.webhooks resource lets you subscribe a calendar to change notifications and unsubscribe an existing channel. It corresponds to the /subscribe-webhook and /unsubscribe-webhook endpoints. Connect subscribes and renews channels automatically when a calendar is connected — this resource is for managing a specific channel explicitly.

🔔 Webhooks API Reference

Subscribes a calendar to change notifications. channel_id is optional and generated by the server when omitted. expiration is an optional Unix timestamp in milliseconds. See POST /subscribe-webhook.

Method: client.webhooks.subscribe_webhook(provider:, calendar_id:, channel_id: nil, expiration: nil)

Returns: Mobiscroll::Connect::SubscribeWebhookResponse

Parameters: See Request Parameters for the full field list.

Usage:

subscription = client.webhooks.subscribe_webhook(
  provider:    Mobiscroll::Connect::Provider::GOOGLE,
  calendar_id: 'work@company.com',
  channel_id:  'my-channel-123'
)

webhooks.unsubscribe_webhook

Removes an existing webhook subscription. resource_id is the provider resource ID returned by subscribe_webhook, where the provider uses one. See POST /unsubscribe-webhook.

Method: client.webhooks.unsubscribe_webhook(provider:, channel_id:, resource_id: nil)

Returns: Mobiscroll::Connect::UnsubscribeWebhookResponse

Parameters: See Request Parameters for the full field list.

Usage:

client.webhooks.unsubscribe_webhook(
  provider:    Mobiscroll::Connect::Provider::GOOGLE,
  channel_id:  'my-channel-123',
  resource_id: 'resource-abc'
)

Setup​

Client Initialization​

Methods​

set_credentials​

on_tokens_refreshed​

credentials​

Token Refresh​

Error Handling​

Auth API​

🔐 OAuth API Reference

auth.generate_auth_url​

auth.get_token​

Calendars API​

📅 Calendars API Reference

calendars.list​

Events API​

📅 Events API Reference

events.list​

events.create​

events.update​

events.delete​

Webhooks API​

🔔 Webhooks API Reference

webhooks.subscribe_webhook​

webhooks.unsubscribe_webhook​

Setup

Client Initialization

Methods

set_credentials

on_tokens_refreshed

credentials

Token Refresh

Error Handling

Auth API

auth.generate_auth_url

auth.get_token

Calendars API

calendars.list

Events API

events.list

events.create

events.update

events.delete

Webhooks API

webhooks.subscribe_webhook

webhooks.unsubscribe_webhook