TypeScript library to manage Outlook calendar events using the Microsoft Graph API.
Before using this library, you must register an application in the Azure Portal to authenticate with Microsoft Entra ID (formerly Azure AD) and grant the necessary permissions to access the Microsoft Graph API.
- Register your app: Follow the official Microsoft documentation to register an application and configure permissions.
-
Required permissions:
- For calendar operations, your app typically needs
Calendars.ReadWrite
application permissions. - Grant admin consent for these permissions in the Azure Portal.
- For calendar operations, your app typically needs
-
Obtain credentials: After registration, you will need the
clientId
,clientSecret
, andtenantId
for your app.
More resources:
- Register an application with the Microsoft identity platform
- Microsoft Graph permissions reference
- Authentication providers for Microsoft Graph SDKs
- Create calendar events for Outlook users
- Cancel existing events
- Update existing events
- Robust parameter validation and error handling
- 100% tested with Vitest and mocks (no real API calls)
npm install outlook-events-client
import { OutlookEventsClient } from 'outlook-events-client';
const client = new OutlookEventsClient({
clientId: 'YOUR_CLIENT_ID',
clientSecret: 'YOUR_CLIENT_SECRET',
tenantId: 'YOUR_TENANT_ID',
});
// Create an event
const event = {
subject: 'Team Meeting',
body: { contentType: 'HTML', content: '<p>Agenda...</p>' },
start: { dateTime: '2025-06-01T10:00:00', timeZone: 'UTC' },
end: { dateTime: '2025-06-01T11:00:00', timeZone: 'UTC' },
location: { displayName: 'Room 1' },
attendees: [
{ emailAddress: { address: 'user@example.com', name: 'User' }, type: 'required' }
]
};
await client.createEvent(event, 'user@domain.com');
// Cancel an event
await client.cancelEvent('eventId', 'user@domain.com', 'Cancellation reason');
// Update an event
await client.updateEvent('eventId', 'user@domain.com', { subject: 'New subject' });
Creates a client instance.
-
options
:{ clientId: string; clientSecret: string; tenantId: string; }
Creates a calendar event for the specified user.
-
event
: Object with event data (see example and types insrc/interfaces/outlook-event.ts
). -
userPrincipalName
: User's email or UPN. - Errors: Throws if parameters are invalid or the API fails.
Cancels an existing event.
-
eventId
: Event ID. -
userPrincipalName
: User's email or UPN. -
comment
: Cancellation reason. - Errors: Throws if parameters are invalid or the API fails.
Updates an existing event.
-
eventId
: Event ID. -
userPrincipalName
: User's email or UPN. -
eventPatch
: Object with fields to update. - Errors: Throws if parameters are invalid or the API fails.
- Always validate parameters before calling methods.
- Handle errors using try/catch.
- Use mocks in tests to avoid real API calls.
- Check type documentation in
src/interfaces/
to properly build event objects.
The library includes unit tests with Vitest. To run them:
npm run test
MIT