@mobiscroll/connect-sdk

Node.js client for Mobiscroll Connect, the calendar connectivity layer for scheduling products — Google Calendar, Microsoft Outlook, Apple Calendar and CalDAV through one API. Backend only — works with your own UI.

npm · Documentation · Changelog · Source

@mobiscroll/connect-sdk provides a typed client for:

• OAuth authorization and token exchange
• Listing connected calendars
• Listing, creating, updating, and deleting calendar events
• Subscribing to and unsubscribing from calendar webhook notifications
• Working with Google Calendar, Microsoft Outlook, Apple Calendar and CalDAV

Installation

npm install @mobiscroll/connect-sdk

or

yarn add @mobiscroll/connect-sdk

Requirements

• Node.js 20+

Quick start

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

const client = new MobiscrollConnectClient({
	clientId: process.env.MOBISCROLL_CLIENT_ID!,
	clientSecret: process.env.MOBISCROLL_CLIENT_SECRET!,
	redirectUri: process.env.MOBISCROLL_REDIRECT_URI!,
});

Authentication flow

1) Generate authorization URL

const url = client.auth.generateAuthUrl({
	userId: 'user-123',
	state: 'optional-state',
	scope: 'read-write',
	providers: 'google,microsoft,apple,caldav',
	lng: 'es', // optional: Connect page language, see https://mobiscroll.com/docs/connect/localization#supported-languages
});

// Redirect the user to `url`

2) Exchange authorization code for tokens

const tokens = await client.auth.getToken(codeFromCallback);
client.setCredentials(tokens);

3) Listen for automatic token refresh updates

client.on('tokens', (updatedTokens) => {
	// Persist updated tokens in your storage
	console.log(updatedTokens);
});

API usage

List calendars

const calendars = await client.calendars.list();

List events

const result = await client.events.list({
	start: new Date(),
	end: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
	pageSize: 50,
});

console.log(result.events);

Create event

const created = await client.events.create({
	provider: 'google',
	calendarId: 'primary',
	title: 'Team sync',
	start: new Date('2026-03-20T09:00:00Z'),
	end: new Date('2026-03-20T09:30:00Z'),
});

Update event

const updated = await client.events.update({
	provider: 'google',
	eventId: created.id,
	calendarId: created.calendarId,
	title: 'Team sync (updated)',
});

Delete event

await client.events.delete({
	provider: 'google',
	calendarId: created.calendarId,
	eventId: created.id,
});

Subscribe to webhook notifications

const subscription = await client.webhooks.subscribeWebhook({
	provider: 'google',
	calendarId: 'primary',
});

console.log(subscription.channelId);

Unsubscribe from webhook notifications

await client.webhooks.unsubscribeWebhook({
	provider: 'google',
	channelId: subscription.channelId,
	resourceId: subscription.subscription.resourceId,
});

Connection management

const status = await client.auth.getConnectionStatus();
console.log(status.connections);

// An account can connect without granting calendar access — Google's consent screen
// lets the user untick that permission. Such accounts list no calendars until the
// user reconnects and allows it.
const needsCalendarAccess = status.connections.google.filter((account) => account.calendarPermissionGranted === false);

await client.auth.disconnect({ provider: 'google', account: '[email protected]' });

Error handling

The SDK exposes typed errors:

• AuthenticationError
• ValidationError
• NotFoundError
• RateLimitError
• ServerError
• NetworkError
• MobiscrollConnectError

Example:

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

try {
	await client.events.list();
} catch (error) {
	if (error instanceof AuthenticationError) {
		// Handle auth failure
	} else if (error instanceof ValidationError) {
		// Handle invalid request data
	}
}

Exports

The package exports:

• MobiscrollConnectClient
• ApiClient
• All public TypeScript types from types.ts

Notes

The current client default base URL is:

https://connect.mobiscroll.com/api