Permas Calendar Service

A microservice for managing calendar events with support for integration with external calendar providers like Google Calendar, iCal feeds, and Microsoft Outlook.

Features

• Event management (create, read, update, delete)
• Calendar views (month, week, day)
• External calendar integration (Google Calendar, iCal, Microsoft Outlook)
• RESTful API
• TypeScript client for frontend integration

Installation

# Install dependencies
npm install

# Build the service
npm run build

# Start the service
npm start

Environment Variables

Create a .env file in the root directory with the following variables:

PORT=3001
MONGODB_URI=mongodb://localhost:27017/rssc-calendar
CORS_ORIGIN=http://localhost:3000

# Google OAuth2 Configuration
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:3001/api/calendar/auth/google/callback

# Microsoft Graph API Configuration
MICROSOFT_GRAPH_CLIENT_ID=your_client_id_here
MICROSOFT_GRAPH_CLIENT_SECRET=your_client_secret_here
MICROSOFT_GRAPH_REDIRECT_URI=http://localhost:3001/api/calendar/auth/microsoft/callback

# iCal Feed Configuration
# Comma-separated list of iCal feed URLs to automatically sync
ICAL_FEEDS=https://calendar.google.com/calendar/ical/example%40gmail.com/public/basic.ics,https://example.com/events.ics

# Default calendar sync interval (in minutes)
CALENDAR_SYNC_INTERVAL=30

Configuring iCal Feeds

The ICAL_FEEDS environment variable allows you to specify one or more iCal feed URLs that the service will automatically sync at the interval specified by CALENDAR_SYNC_INTERVAL.

To obtain an iCal feed URL:

1. From Google Calendar:

   • Go to Settings > [Calendar Name] > Integrate calendar
   • Copy the "Secret address in iCal format" URL

2. From Microsoft Outlook:

   • Go to Settings > Calendar > Shared Calendars
   • Publish the calendar and copy the ICS link

3. From Apple Calendar:

   • Right-click on a calendar and select "Share Calendar"
   • Choose "Public Calendar" and copy the URL

Multiple feeds can be specified by separating them with commas.

API Endpoints

Events

• GET /api/calendar/month/:year/:month - Get events for a specific month
• GET /api/calendar/week?date=ISO_DATE - Get events for a specific week
• GET /api/calendar/day?date=ISO_DATE - Get events for a specific day
• GET /api/calendar/upcoming?limit=10 - Get upcoming events
• POST /api/calendar - Create a new event
• PUT /api/calendar/:id - Update an event
• DELETE /api/calendar/:id - Delete an event
• GET /api/calendar/type/:type - Get events by type
• GET /api/calendar/tags?tags=tag1,tag2 - Get events by tags
• GET /api/calendar/search?query=search_term - Search events

External Calendar Integration

• GET /api/calendar/auth/google/url - Get Google OAuth2 URL
• GET /api/calendar/auth/google/callback - Handle Google OAuth2 callback
• GET /api/calendar/auth/microsoft/url - Get Microsoft OAuth2 URL
• GET /api/calendar/auth/microsoft/callback - Handle Microsoft OAuth2 callback
• POST /api/calendar/sync/google - Sync with Google Calendar
• POST /api/calendar/sync/ical - Sync with iCal feed
• POST /api/calendar/sync/outlook - Sync with Microsoft Outlook Calendar
• GET /api/calendar/sync/status - Get sync status

Using the Client

In your frontend application, you can use the provided client:

import { CalendarClient, CalendarEvent } from 'permas-calendar-service';

const calendarClient = CalendarClient.getInstance();

// Get events for current month
const now = new Date();
const events = await calendarClient.getEventsForMonth(now.getFullYear(), now.getMonth());

// Create a new event
const newEvent = await calendarClient.createEvent({
  title: 'Community Meeting',
  date: new Date(2023, 11, 15, 18, 0),
  type: 'meeting',
  description: 'Monthly community meeting',
  location: 'Community Center'
});

// Integrate with Google Calendar
const googleAuthUrl = await calendarClient.getGoogleAuthUrl();
// Redirect user to googleAuthUrl for authorization

// After receiving the access token from the callback
await calendarClient.syncGoogleCalendar('primary', accessToken);

Programmatic Usage

If you want to use this service as a package in your own Node.js application:

const { CalendarClient, CalendarEvent } = require('permas-calendar-service');
const { CalendarSyncService } = require('permas-calendar-service/dist/services/calendarSyncService');

// Initialize the client
const calendarClient = CalendarClient.getInstance();

// Set configuration through environment variables
process.env.ICAL_FEEDS = 'https://mycalendar.com/feed.ics';
process.env.CALENDAR_SYNC_INTERVAL = '60'; // 60 minutes

// Or manage feeds programmatically
const syncService = CalendarSyncService.getInstance();

// Add a feed dynamically
syncService.addFeed('https://example.com/another-calendar.ics');

// Remove a feed
syncService.removeFeed('https://example.com/another-calendar.ics');

// Trigger a manual sync
await syncService.syncAllICalFeeds();

// Now you can use the client to interact with the calendar service

Configuring in Your Application

For the most flexibility when using this as a package, we recommend:

1. Making iCal feeds configurable in your application's admin panel
2. Storing the feed URLs in your database
3. Loading them on application startup and adding them programmatically

Example implementation:

// On application startup
async function initializeCalendarService() {
  const syncService = CalendarSyncService.getInstance();
  
  // Get feeds from your database
  const savedFeeds = await YourDatabase.getCalendarFeeds();
  
  // Add each feed to the sync service
  savedFeeds.forEach(feed => {
    syncService.addFeed(feed.url);
  });
  
  // Start automatic sync
  const interval = process.env.CALENDAR_SYNC_INTERVAL || 30;
  setInterval(() => {
    syncService.syncAllICalFeeds()
      .catch(err => console.error('Failed to sync calendar feeds:', err));
  }, interval * 60 * 1000);
}

Docker Deployment

This service can be deployed using Docker:

# Build and start the service with MongoDB
docker-compose up -d

Development

# Run in development mode with hot reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

License

ISC