@catalisa/calendar-outlook-sdk

TypeScript SDK for Microsoft Outlook Calendar Integration API.

Documentation / Documentação

• Documentação em Português - Documentação completa com exemplos detalhados
• Admin Panel Integration Guide (English) - Complete guide for external integrations
• Guia de Integração Admin (Português) - Guia completo para integrações externas

Installation

npm install @catalisa/calendar-outlook-sdk

Setup

import { MSCalendarClient } from '@catalisa/calendar-outlook-sdk';

const client = new MSCalendarClient({
  baseURL: 'https://your-api.com',
  token: 'your-jwt-token',
  onUnauthorized: () => console.log('Token expired'),
});

// Update token dynamically
client.setToken('new-token');

// Get login URL
const loginUrl = client.getLoginUrl();

API Reference

Authentication

auth.me() - Get current user

const user = await client.auth.me();
// { id, email, displayName, accountType: 'personal' | 'business' }

auth.logout() - End session

await client.auth.logout();

auth.exchangeToken(appToken) - Exchange App Token for Access Token

// For external integrations using App Tokens
const client = new MSCalendarClient({ baseURL: 'https://your-api.com' });

const result = await client.auth.exchangeToken('cat_your-app-token');
// { accessToken, expiresIn: 3600, tokenType: 'Bearer' }
// Client is automatically authenticated after exchange

App Token Management

Manage long-lived tokens for external integrations.

tokens.create(data) - Create new App Token

const token = await client.tokens.create({
  name: 'My Integration',
  scopes: ['calendar:read', 'calendar:write', 'slots:read'], // optional
  expiresIn: '30d',  // '30d' | '90d' | '1y' | 'never'
});
// { id, name, scopes, expiresAt, token: 'cat_xxx...' }
// ⚠️ The plain token is only returned once!

tokens.list() - List all App Tokens

const { tokens } = await client.tokens.list();
// tokens: [{ id, name, scopes, expiresAt, lastUsedAt, createdAt, isRevoked }]

tokens.get(id) - Get single App Token

const token = await client.tokens.get('token-id');
// { id, name, scopes, expiresAt, lastUsedAt, createdAt, isRevoked }

tokens.revoke(id) - Revoke App Token

await client.tokens.revoke('token-id');

Calendar Events

calendar.list(query?) - List events

const { events, total, hasMore } = await client.calendar.list({
  startDate: '2024-01-01',  // optional
  endDate: '2024-01-31',    // optional
  limit: 50,                // default: 50
  skip: 0,                  // default: 0
});

calendar.get(id) - Get single event

const event = await client.calendar.get('event-id');
// { id, subject, body, start, end, location, attendees, isOnlineMeeting, onlineMeetingUrl }

calendar.create(data) - Create event

const event = await client.calendar.create({
  subject: 'Meeting',
  body: 'Description',                                              // optional
  start: { dateTime: '2024-01-20T14:00:00', timeZone: 'UTC' },
  end: { dateTime: '2024-01-20T15:00:00', timeZone: 'UTC' },
  location: 'Room 101',                                             // optional
  attendees: [{ email: '[email protected]', name: 'Name', type: 'required' }], // optional
  isOnlineMeeting: true,                                            // optional - creates Teams link
});

calendar.update(id, data) - Update event

const event = await client.calendar.update('event-id', {
  subject: 'Updated Title',
  location: 'Room 202',
});

calendar.delete(id) - Delete event

await client.calendar.delete('event-id');

Finding Available Slots

calendar.findSlots(query) - Find free time slots

const { slots, meta } = await client.calendar.findSlots({
  startDate: '2024-01-15',        // required
  endDate: '2024-01-22',          // required
  duration: 30,                   // required (minutes)
  quantity: 5,                    // default: 5
  algorithm: 'nextAvailable',     // 'nextAvailable' | 'spread' | 'randomize' | 'consecutive'
  weekdaysOnly: false,            // default: false
  periodStart: '09:00',           // optional (HH:mm)
  periodEnd: '17:00',             // optional (HH:mm)
  timeZone: 'UTC',                // default: 'UTC'
});

// slots: [{ start, end, timeZone }]
// meta: { totalAvailable, returned, searchedCalendars }

Algorithms:

• nextAvailable - Earliest slots first
• spread - Distributed across days
• randomize - Random selection
• consecutive - Back-to-back slots

Types

import type {
  // User
  UserDto,
  // Events
  EventDto,
  CreateEventDto,
  UpdateEventDto,
  ListEventsQueryDto,
  ListEventsResponseDto,
  // Slots
  SlotDto,
  FindSlotsQueryDto,
  FindSlotsResponseDto,
  DateTimeDto,
  AttendeeDto,
  SlotAlgorithm,
  // App Tokens
  CreateAppTokenDto,
  AppTokenDto,
  AppTokenWithSecretDto,
  ListAppTokensResponseDto,
  ExchangeTokenResponseDto,
  AppTokenScope,
} from '@catalisa/calendar-outlook-sdk';

Error Handling

try {
  await client.calendar.get('invalid-id');
} catch (error) {
  if (error.response?.status === 404) {
    console.log('Not found');
  }
}

Testing

Unit Tests

pnpm test

E2E Tests (CLI)

Requires a running API and valid JWT token.

# Set your token
export TOKEN="your-jwt-token"

# Run all tests
pnpm test:e2e

# Run specific suite
pnpm test:e2e -- auth
pnpm test:e2e -- calendar
pnpm test:e2e -- slots
pnpm test:e2e -- tokens
pnpm test:e2e -- logout

Browser Tests (Playwright)

Interactive tests requiring Microsoft OAuth login.

# Install browsers (first time)
npx playwright install chromium

# Popup authentication
pnpm test:browser:popup

# Redirect authentication
pnpm test:browser:redirect

# Token authentication (headless)
pnpm test:browser:token

License

MIT