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.

Setup

Install the package using your preferred package manager:

npm

npm install @mobiscroll/connect-sdk

yarn

yarn add @mobiscroll/connect-sdk

pnpm

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

API

The client exposes the following 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, and managing connection status. It corresponds to the /authorize, /token, and /connection-status endpoints.

To localize the Connect pages, pass an optional lng (en, es, fr, ar) to generateAuthUrl, e.g. generateAuthUrl({ userId, 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