@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

``bash
npm install @catalisa/calendar-outlook-sdk
`

Setup

`typescript
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

$3

#### auth.me() - Get current user

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

#### auth.logout() - End session

`typescript
await client.auth.logout();
`

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

`typescript
// 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
`

---

$3

Manage long-lived tokens for external integrations.

#### tokens.create(data) - Create new App Token

`typescript
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

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

#### tokens.get(id) - Get single App Token

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

#### tokens.revoke(id) - Revoke App Token

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

---

$3

#### calendar.list(query?) - List events

`typescript
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

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

#### calendar.create(data) - Create event

`typescript
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: 'a@b.com', name: 'Name', type: 'required' }], // optional
isOnlineMeeting: true, // optional - creates Teams link
});
`

#### calendar.update(id, data) - Update event

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

#### calendar.delete(id) - Delete event

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

---

$3

#### calendar.findSlots(query) - Find free time slots

`typescript
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

`typescript
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

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

---

Testing

$3

`bash
pnpm test
`

$3

Requires a running API and valid JWT token.

`bash


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
`

$3

Interactive tests requiring Microsoft OAuth login.

`bash


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