A reusable TypeScript library for managing Microsoft Graph calendar availability and bookings, with built-in support for Singapore timezone.
- 📅 Fetch calendar availability for users
- 🔍 Check team member availability
- 📊 Get consolidated team availability
- ✅ Book meetings with automatic Teams meeting links
- 🌏 Singapore timezone support (configurable)
- 🔐 Secure app-only authentication using MSAL
- 📝 Full TypeScript support
- 🛠️ Diagnostic tools for setup verification
npm install msteams-azimnpm install moment @azure/msal-node @microsoft/microsoft-graph-clientBefore using this library, you need to set up an Azure AD app registration:
- Create an App Registration in Azure Portal
- Add API Permissions:
Calendars.Read(Application)Calendars.ReadWrite(Application)User.Read.All(Application) - Optional but recommended
- Grant Admin Consent for your organization
- Create a Client Secret and note the value
- Get your credentials:
- Application (client) ID
- Directory (tenant) ID
- Client secret value
import { MSGraphService } from 'msteams-azim';
// Initialize the service
const graphService = new MSGraphService({
clientId: process.env.MICROSOFT_CLIENT_ID!,
clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
tenantId: process.env.MICROSOFT_TENANT_ID!,
timeZone: 'Singapore Standard Time', // Optional, defaults to Singapore
verbose: true // Enable logging
});
// Test the connection
const isConnected = await graphService.testGraphAccess();
console.log('Connected:', isConnected);// Get availability for a single user
const availability = await graphService.getCalendarAvailability(
'user@example.com',
'2024-01-01', // Start date
'2024-01-07' // End date
);
console.log(availability);
/*
[
{
date: '2024-01-02',
available: true,
timeSlots: ['09:00', '10:00', '11:00', '14:00', '15:00', '16:00']
},
{
date: '2024-01-03',
available: true,
timeSlots: ['09:00', '13:00', '14:00', '15:00', '16:00', '17:00']
}
]
*/// Get raw schedule data with all events from Microsoft Graph
const schedule = await graphService.getCalendarSchedule(
'user@example.com',
'2024-01-01',
'2024-01-07'
);
// Access schedule items (calendar events)
const events = schedule.value[0].scheduleItems;
events.forEach(event => {
console.log(`Event: ${event.subject}`);
console.log(`Start: ${event.start.dateTime}`);
console.log(`End: ${event.end.dateTime}`);
console.log(`Status: ${event.status}`);
});
// Access availability view (0=Free, 1=Tentative, 2=Busy, 3=OOF, 4=WorkingElsewhere)
const availabilityView = schedule.value[0].availabilityView;
console.log('Availability view:', availabilityView);
// Access working hours if configured
const workingHours = schedule.value[0].workingHours;
if (workingHours) {
console.log('Working hours:', workingHours);
}// Set team members
graphService.setTeamMembers([
{ id: '1', email: 'member1@example.com', name: 'John Doe' },
{ id: '2', email: 'member2@example.com', name: 'Jane Smith' }
]);
// Get availability for all team members
const teamAvailability = await graphService.getTeamAvailability(
'2024-01-01',
'2024-01-07'
);
console.log(teamAvailability);
/*
{
'member1@example.com': [
{ date: '2024-01-02', available: true, timeSlots: [...] }
],
'member2@example.com': [
{ date: '2024-01-02', available: true, timeSlots: [...] }
]
}
*/// Get combined availability (shows slots where ANY team member is available)
const consolidated = await graphService.getConsolidatedAvailability(
'2024-01-01',
'2024-01-07'
);
console.log(consolidated);
/*
[
{
date: '2024-01-02',
available: true,
timeSlots: ['09:00', '10:00', '11:00', '13:00', '14:00', '15:00', '16:00']
}
]
*/const booking = await graphService.bookMeeting({
date: '2024-01-02',
time: '14:00',
duration: 60, // minutes
teamMemberEmail: 'consultant@example.com',
leadEmail: 'client@company.com',
leadName: 'Client Name',
subject: 'Initial Consultation',
description: 'Discussion about project requirements'
});
console.log('Meeting booked:', booking.id);
console.log('Teams link:', booking.onlineMeeting.joinUrl);const graphService = new MSGraphService({
clientId: process.env.MICROSOFT_CLIENT_ID!,
clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
tenantId: process.env.MICROSOFT_TENANT_ID!,
timeZone: 'Tokyo Standard Time', // Change timezone
workingHours: {
start: 8, // 8 AM
end: 18, // 6 PM
interval: 30 // 30-minute slots
}
});Microsoft Graph uses Windows timezone names (not IANA codes like "Asia/Singapore").
Common timezones:
"Singapore Standard Time"- Singapore, Malaysia, Philippines"Tokyo Standard Time"- Tokyo, Osaka"China Standard Time"- Beijing, Hong Kong"India Standard Time"- Mumbai, Delhi"GMT Standard Time"- London, Dublin"Eastern Standard Time"- New York, Toronto"Pacific Standard Time"- Los Angeles, Vancouver"Central Europe Standard Time"- Berlin, Paris, Rome
📚 Full timezone list: Microsoft Windows Timezone Reference
- ✅ Correct:
"Singapore Standard Time" - ❌ Wrong:
"Asia/Singapore"
// Run diagnostic to check configuration and permissions
await graphService.diagnoseSetup();interface MSGraphConfig {
clientId: string; // Azure AD Application (client) ID
clientSecret: string; // Azure AD Client secret value
tenantId: string; // Azure AD Directory (tenant) ID
timeZone?: string; // Default: "Singapore Standard Time"
workingHours?: {
start: number; // Default: 9 (9 AM)
end: number; // Default: 17 (5 PM)
interval: number; // Default: 60 (minutes)
};
verbose?: boolean; // Enable logging, default: false
}Tests Microsoft Graph API connectivity.
getCalendarAvailability(userEmail: string, startDate: string, endDate: string): Promise<CalendarAvailability[]>
Get calendar availability for a specific user.
Get raw calendar schedule data from Microsoft Graph including all events and availability view.
Get availability for all configured team members.
Get consolidated availability showing slots where any team member is available.
Book a meeting and create a calendar event with Teams meeting link.
Set the list of team members to track.
Enable or disable verbose logging.
Run diagnostics to verify configuration and permissions.
interface CalendarAvailability {
date: string;
available: boolean;
timeSlots: string[];
}
interface TeamMember {
id: string;
email: string;
name: string;
available?: boolean;
}
interface BookingRequest {
date: string;
time: string;
duration: number;
teamMemberEmail: string;
leadEmail: string;
leadName: string;
subject: string;
description?: string;
}
interface TeamAvailability {
[memberEmail: string]: CalendarAvailability[];
}Create a .env file:
MICROSOFT_CLIENT_ID=your-client-id
MICROSOFT_CLIENT_SECRET=your-client-secret
MICROSOFT_TENANT_ID=your-tenant-idThe library includes comprehensive error handling:
try {
const availability = await graphService.getCalendarAvailability(
'user@example.com',
'2024-01-01',
'2024-01-07'
);
} catch (error) {
if (error.statusCode === 403) {
console.error('Permission denied - check API permissions');
} else if (error.statusCode === 404) {
console.error('User not found');
} else {
console.error('Error:', error.message);
}
}import { MSGraphService } from 'msteams-azim';
import * as dotenv from 'dotenv';
dotenv.config();
async function main() {
// Initialize service
const graphService = new MSGraphService({
clientId: process.env.MICROSOFT_CLIENT_ID!,
clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
tenantId: process.env.MICROSOFT_TENANT_ID!,
verbose: true
});
// Set team members
graphService.setTeamMembers([
{ id: '1', email: 'consultant@example.com', name: 'Senior Consultant' }
]);
// Get availability for next week
const startDate = new Date();
startDate.setDate(startDate.getDate() + 1);
const endDate = new Date(startDate);
endDate.setDate(endDate.getDate() + 7);
const availability = await graphService.getConsolidatedAvailability(
startDate.toISOString().split('T')[0],
endDate.toISOString().split('T')[0]
);
console.log('Available slots:', availability);
// Book first available slot
if (availability[0]?.available && availability[0].timeSlots.length > 0) {
const booking = await graphService.bookMeeting({
date: availability[0].date,
time: availability[0].timeSlots[0],
duration: 60,
teamMemberEmail: 'consultant@example.com',
leadEmail: 'client@company.com',
leadName: 'John Client',
subject: 'Consultation Meeting',
description: 'Initial consultation call'
});
console.log('Meeting booked successfully!');
console.log('Join URL:', booking.onlineMeeting?.joinUrl);
}
}
main().catch(console.error);- Verify API permissions in Azure Portal
- Ensure admin consent is granted
- Check that the app registration is active
- Verify client secret hasn't expired
- Verify the email address exists in your Microsoft 365 tenant
- Check that the user has a valid license
- Ensure the email format is correct
- Verify all three credentials (clientId, clientSecret, tenantId)
- Ensure the client secret is the VALUE, not the ID
- Check that the app registration is in the correct tenant
Run diagnostics:
await graphService.diagnoseSetup();MIT
For issues and questions, please open an issue on GitHub.
Contributions are welcome! Please feel free to submit a Pull Request.