Calenderify NPM

Calendar Integration Package

A simple library for scheduling and retrieving calendar events with just one login.

Key Features

🔐 Single sign-on authentication with providers
🔄 Automatic refresh token management with background jobs
📅 Comprehensive event management (create, retrieve, query)
🌍 Built-in timezone support
📚 Multiple calendar support (Currently only Google)
🏗️ Extensible architecture for additional providers

Installation

npm install calendar-integration-package

Importing the Package

ESM (Recommended)

import { CalendarService } from 'calendar-integration-package';

CommonJS

const { CalendarService } = require('calendar-integration-package');

Example Usage

// Initialize the service
const calendarService = new CalendarService(
  'google',
  {
    client_id: 'your_client_id',
    client_secret: 'your_client_secret',
    redirect_uri: 'your_redirect_uri'
  },
  'your_database_connection_string'
);

// Get OAuth URL and establish connection
const authUrl = calendarService.connect();

// Handle OAuth callback
const credentials = await calendarService.access(authCode, userId);

// Create a calendar event
const eventId = await calendarService.createEvent(
  'user123',
  'Team Meeting',
  '2024-01-15T10:00:00Z',
  '2024-01-15T11:00:00Z',
  'America/New_York',
  'Monthly team sync',
  [{ email: 'team@example.com' }]
);

Initialization

CalendarService Constructor

Creates a new instance of the calendar service.

new CalendarService(provider: string, credentials: ICredentials, connectionString: string)

Parameters:

provider: Calendar provider name (currently supports 'google')
credentials: OAuth credentials object containing:
- client_id: OAuth client ID
- client_secret: OAuth client secret
- redirect_uri: OAuth redirect URI
connectionString: Database connection string for token storage

Authentication

connect()

Returns the OAuth URL for calendar provider authentication.

calendarService.connect(): string

Returns: Authentication URL string that you need to open and login one time for that account that you are going to schedule

access()

Handles OAuth callback and saves credentials.

calendarService.access(code: string, user_id: string): Promise<ICredentials>

Parameters:

code: OAuth authorization code
- user_id: Unique identifier of your user that you need to provide and use for further operations

Returns: Promise resolving to credentials object

Event Management

getEventsInRange()

Retrieves events within a specified date range.

calendarService.getEventsInRange(
  userId: string,
  startDate: string,
  endDate: string,
  timezone?: string,
  calendarId?: string
): Promise<Slot[]>

Parameters:

userId: User identifier
startDate: Start date in ISO format
endDate: End date in ISO format
timezone: Optional timezone (default: UTC)
calendarId: Optional specific calendar ID

Returns: Promise resolving to array of event slots

createEvent()

Creates a new calendar event.

calendarService.createEvent(
  userId: string,
  summary: string,
  start: string,
  end: string,
  timezone: string,
  description?: string,
  attendees?: { email: string }[],
  calendarId?: string
): Promise<string>

Parameters:

userId: User identifier
summary: Event title
start: Start time in ISO format
end: End time in ISO format
timezone: Event timezone
description: Optional event description
attendees: Optional array of attendee email objects
calendarId: Optional specific calendar ID

Returns: Promise resolving to created event ID

Token Management

refreshAccessToken()

Manually refresh access token for a user.

calendarService.refreshAccessToken(userId: string): Promise<ICredentials>

Parameters:

userId: User identifier

Returns: Promise resolving to updated credentials

Background Jobs

startJob()

Starts the background job for automatic token refresh.

calendarService.startJob(): void

stopJob()

Stops the background token refresh job.

calendarService.stopJob(): void

Error Handling

The package throws specific errors that you should handle in your application:

try {
  await calendarService.createEvent(/* ... */);
} catch (error) {
  if (error.code === 'INVALID_CREDENTIALS') {
    // Handle invalid credentials
  } else if (error.code === 'API_ERROR') {
    // Handle API errors
  } else if (error.code === 'DATABASE_ERROR') {
    // Handle database connection issues
  } else {
    // Handle other errors
  }
}