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.).

Setup

Install the gem with Bundler:

Bundler

Add to your Gemfile:

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

Then run:

bundle install

gem

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)
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

API

The client exposes resources that map directly to the API endpoints.

Auth

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

To localize the Connect pages, pass an optional lng (en, es, fr, ar) 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 renders right-to-left.

🔐 OAuth API Reference

Calendars

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

Events

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