Node.js SDK

The Mobiscroll Connect Node.js SDK provides a convenient way to interact with the Mobiscroll Connect API from your Node.js applications.

npm@mobiscroll/connect-sdk

Source Changelog Report an issue

Setup

Install the package using your preferred package manager:

npm
yarn
pnpm

npm install @mobiscroll/connect-sdk

yarn add @mobiscroll/connect-sdk

pnpm add @mobiscroll/connect-sdk

Client Initialization

To use the SDK, you need to initialize the MobiscrollConnectClient with your client credentials.

Class: MobiscrollConnectClient

configMobiscrollConnectConfig

Configuration object.

clientIdstring

Your Client ID obtained from the Mobiscroll Connect dashboard.

clientSecretstring

Your Client Secret obtained from the Mobiscroll Connect dashboard.

redirectUristring

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

Usage:

import { MobiscrollConnectClient } from "@mobiscroll/connect-sdk";

const client = new MobiscrollConnectClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  redirectUri: "YOUR_REDIRECT_URI",
});

Methods

setCredentials

Sets the access token for the client. This is required before making any API calls that require authentication (which is most of them).

Method: client.setCredentials(tokens)

tokensTokenResponse

The tokens object received from the auth.getToken method.

on

Registers an event listener for client events.

Method: client.on(event, listener)

eventstring

The name of the event to listen for.

listenerfunction

The callback function to execute when the event is triggered.

getConfig

Returns the current configuration of the client.

Method: client.getConfig()

Returns: MobiscrollConnectConfig

Token Refresh

The Node.js SDK handles token refresh automatically. When any API call returns a 401 Unauthorized response and the client has a refresh_token stored, the SDK will silently exchange it for a new access token and retry the original request — with no action required from your application.

When the refresh succeeds, the SDK emits a tokens event with the updated TokenResponse. You must listen for this event and persist the new tokens, otherwise they will be lost when the process exits.

client.on('tokens', (updatedTokens) => {
  // Persist updatedTokens in your database or session store
  // so the new access_token and refresh_token survive future requests
});

If the refresh token itself is invalid or has been revoked, the SDK throws an AuthenticationError and the user must re-authorize.

Error Handling

All SDK methods throw errors that extend MobiscrollConnectError. You can catch the base class or any specific subclass.

Error class	HTTP status	`error.code`
`AuthenticationError`	401, 403	`AUTHENTICATION_ERROR`
`CalendarPermissionError`	403	`CALENDAR_PERMISSION_REQUIRED`
`ValidationError`	400, 422	`VALIDATION_ERROR`
`NotFoundError`	404	`NOT_FOUND_ERROR`
`RateLimitError`	429	`RATE_LIMIT_ERROR`
`ServerError`	5xx	`SERVER_ERROR`
`NetworkError`	—	`NETWORK_ERROR`

ValidationError exposes a details property with field-level validation errors. RateLimitError exposes retryAfter (seconds) and ServerError exposes status (the actual HTTP status code).

import {
  AuthenticationError,
  ValidationError,
  RateLimitError,
  MobiscrollConnectError,
} from '@mobiscroll/connect-sdk';

try {
  const response = await client.events.list({ start: '2024-01-01' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Token expired and refresh failed — re-authorize the user
  } else if (error instanceof ValidationError) {
    console.log(error.details);
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof MobiscrollConnectError) {
    // Catch-all for any other SDK error
  }
}

Auth API

The client.auth resource handles the OAuth authorization flow, including generating authorization URLs, exchanging codes for tokens, and managing connection status. It corresponds to the /authorize, /token, and /connection-status endpoints.

Each account returned by getConnectionStatus reports grantedScopes and calendarPermissionGranted. 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 generateAuthUrl, e.g. generateAuthUrl({ userId, 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.generateAuthUrl

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.generateAuthUrl(params)

Returns: string

paramsAuthorizeParams

userId is required: your identifier for the user. scope, state and lng are optional.

Usage:

// Generate the authorization URL
const authUrl = client.auth.generateAuthUrl({
  userId: 'user-456',
  // Optional parameters
  // state: 'xyz789',
  // scope: 'read-write',
  // lng: 'es', // localize the Connect pages
});

// Redirect the user to authUrl
// res.redirect(authUrl);

auth.getToken

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.getToken(code)

Returns: Promise<TokenResponse>

codestring

The authorization code received on your redirect URI.

Usage:

// Exchange authorization code for access token
// The client uses the configured clientId and clientSecret
const tokenResponse = await client.auth.getToken(code);

// The client is automatically authenticated with the new token
// Persist tokenResponse to restore it later with client.setCredentials()

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: Promise<Calendar[]>

Usage:

const calendars = await 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 nextPageToken, pass it to the next call to get the following page. See GET /events.

Method: client.events.list(params?)

Returns: Promise<EventsListResponse>

paramsEventListParams

All fields are optional: start, end, calendarIds (calendar IDs grouped by provider), pageSize, nextPageToken and singleEvents.

Usage:

// Fetch initial events with date range filter
const response = await client.events.list({
  pageSize: 50,
  start: '2025-10-01T00:00:00Z',
  end: '2025-10-31T23:59:59Z'
});
console.log(response.events);

// Load more events using nextPageToken
const nextResponse = await client.events.list({
  pageSize: 50,
  nextPageToken: response.nextPageToken
});

// Filter by specific calendars
const filteredEvents = await client.events.list({
  pageSize: 25,
  calendarIds: { google: ['personal@gmail.com', 'work@company.com'] }
});

// Get recurring event series masters (not expanded)
const masters = await client.events.list({
  pageSize: 50,
  singleEvents: false
});

events.create

Creates an event in the given calendar. Set recurrence to create a recurring series. See POST /event.

Method: client.events.create(params)

Returns: Promise<EventResponse>

paramsCreateEventData

provider, calendarId, title, start and end are required. Optional fields include description, location, allDay and recurrence.

Usage:

// Create a simple event
const event = await client.events.create({
  provider: 'google',
  calendarId: '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
const recurringEvent = await client.events.create({
  provider: 'microsoft',
  calendarId: 'AAMkAGVmMDEz...',
  title: 'Weekly Standup',
  start: '2025-11-01T09:00:00Z',
  end: '2025-11-01T09:30:00Z',
  allDay: false,
  recurrence: {
    frequency: 'WEEKLY',
    interval: 1,
    count: 10,
    byDay: ['MO', 'WE', 'FR']
  }
});

// Create an all-day event
const allDayEvent = await client.events.create({
  provider: 'apple',
  calendarId: 'https://caldav.icloud.com/.../calendars/...',
  title: 'Conference',
  start: '2025-11-15T00:00:00Z',
  end: '2025-11-16T00:00:00Z',
  allDay: true,
  description: 'Annual tech conference'
});

events.update

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

Method: client.events.update(params)

Returns: Promise<EventResponse>

paramsUpdateEventData

provider, calendarId and eventId are required. Pass only the event fields you want to change, plus recurringEventId and updateMode for recurring events.

Usage:

// Update a simple event
const updatedEvent = await client.events.update({
  provider: 'google',
  calendarId: 'primary',
  eventId: '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
const updatedInstance = await client.events.update({
  provider: 'microsoft',
  eventId: 'instance456',
  recurringEventId: 'series123',
  calendarId: 'AAMkAGVmMDEz...',
  updateMode: 'this',
  title: 'Standup - Special Topic Today',
  start: '2025-11-01T09:00:00Z',
  end: '2025-11-01T10:00:00Z'
});

// Update all future occurrences
const updatedFuture = await client.events.update({
  provider: 'apple',
  eventId: 'recurring-event-id',
  calendarId: 'https://caldav.icloud.com/.../calendars/...',
  updateMode: 'following',
  location: 'New Conference Room B'
});

events.delete

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

Method: client.events.delete(params)

Returns: Promise<void>

paramsDeleteEventParams

provider, calendarId and eventId are required. recurringEventId and deleteMode are optional.

Usage:

// Delete a simple event
await client.events.delete({
  provider: 'google',
  calendarId: 'primary',
  eventId: 'event123abc'
});

// Delete a single instance of a recurring event
await client.events.delete({
  provider: 'microsoft',
  calendarId: 'AAMkAGVmMDEz...',
  eventId: 'instance456',
  recurringEventId: 'series123',
  deleteMode: 'this'
});

// Delete entire recurring series
await client.events.delete({
  provider: 'apple',
  calendarId: 'https://caldav.icloud.com/.../calendars/...',
  eventId: 'recurring-event-id',
  deleteMode: '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. See POST /subscribe-webhook.

Method: client.webhooks.subscribeWebhook(params)

Returns: Promise<SubscribeWebhookResponse>

paramsSubscribeWebhookParams

provider and calendarId are required. channelId is optional and generated by the server when omitted. expiration is an optional Unix timestamp in milliseconds.

Usage:

const subscription = await client.webhooks.subscribeWebhook({
  provider: 'google',
  calendarId: 'work@company.com',
  channelId: 'my-channel-123'
});

webhooks.unsubscribeWebhook

Removes an existing webhook subscription. See POST /unsubscribe-webhook.

Method: client.webhooks.unsubscribeWebhook(params)

Returns: Promise<UnsubscribeWebhookResponse>

paramsUnsubscribeWebhookParams

provider and channelId are required. resourceId is the provider resource ID returned by subscribeWebhook, where the provider uses one.

Usage:

await client.webhooks.unsubscribeWebhook({
  provider: 'google',
  channelId: 'my-channel-123',
  resourceId: 'resource-abc'
});

Setup​

Client Initialization​

Methods​

setCredentials​

on​

getConfig​

Token Refresh​

Error Handling​

Auth API​

🔐 OAuth API Reference

auth.generateAuthUrl​

auth.getToken​

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.subscribeWebhook​

webhooks.unsubscribeWebhook​

Setup

Client Initialization

Methods

setCredentials

on

getConfig

Token Refresh

Error Handling

Auth API

auth.generateAuthUrl

auth.getToken

Calendars API

calendars.list

Events API

events.list

events.create

events.update

events.delete

Webhooks API

webhooks.subscribeWebhook

webhooks.unsubscribeWebhook