Archival Notice

This repository will be archived as Niles no longer dependent on node-google-calendar

node-google-calendar

Simple node module that supports Google Calendar API

This module does server to server authentication with Google APIs without any users being involved. When using Google APIs from the server (or any non-browser based application), authentication is performed through a Service Account, which is a special account representing your application.

Find out more about preparations needed to setting up the service account, grant calendar access, auth key to google and the configurations needed to start using node-google-calendar.

Getting Started

First, install the npm package with: npm i node-google-calendar --save.

Provide in a settings.js config file with serviceAcctId, calendarIds, timezone & keyfile location.
Check out preparations needed if you have trouble supplying these configurations. Sample config file here.

Your config file should look something like this:

const KEYFILE = '<yourpem.pem>';
const SERVICE_ACCT_ID = '<service_account>@<project_name>.iam.gserviceaccount.com';
const CALENDAR_ID = {
  'primary': '<main-calendar-id>@gmail.com',
  'calendar-1': '[email protected]',
  'calendar-2': '[email protected]'
};
const TIMEZONE = 'UTC+08:00';

module.exports.keyFile = KEYFILE;           //or if using json keys - module.exports.key = key;
module.exports.serviceAcctId = SERVICE_ACCT_ID;
module.exports.calendarId = CALENDAR_ID;
module.exports.timezone = TIMEZONE;

To use, require this module in your application and pass in the necessary config file.

  const CONFIG = require('./config/Settings');
  const CalendarAPI = require('node-google-calendar');
  let cal = new CalendarAPI(CONFIG);  

You should now be able to query your specified calendar and try out the following examples.

APIs

Most Google Calendar APIs v3 are now supported! This includes APIs in resource types of Calendars, CalendarList, Acl, Events, FreeBusy, Settings, Colors & Channels. You can refer to Google's documentation on what parameters to supply, and choose to include or exclude the parameters that you need.

Some examples are as follows:

CalendarList Examples

CalendarList.list - Returns a promise of a CalendarList of calendar entries and their metadata that the service account has visibility to.

let params = {
  showHidden: true
};

cal.CalendarList.list(params)
  .then(resp => {
	console.log(resp);
  }).catch(err => {
	console.log(err.message);
  });

Acl Examples

Acl.insert - Granting a user owner permission of to a calendar. Calendar entry should be automatically added to user's CalendarList after success. (Appear on calendarlist on left side of Google Calendar's WebUI)

let params = {
	scope: {
		type: 'user',
		value: '[email protected]'
	},
	role: 'owner'
};

cal.Acl.insert(calendarId, params)
  .then(resp => {
	console.log(resp);
  }).catch(err => {
	console.log(err.message);
  });

Events Examples

Events.list - To get a promise of all single events in calendar within a time period.

let params = {
	timeMin: '2017-05-20T06:00:00+08:00',
	timeMax: '2017-05-25T22:00:00+08:00',
	q: 'query term',
	singleEvents: true,
	orderBy: 'startTime'
}; 	//Optional query parameters referencing google APIs

cal.Events.list(calendarId, params)
  .then(json => {
	//Success
	console.log('List of events on calendar within time-range:');
	console.log(json);
  }).catch(err => {
	//Error
	console.log('Error: listSingleEvents -' + err.message);
  });

Events.insert - Insert an event on a specified calendar. Returns promise of details of new event.

let params = {
	'start': { 'dateTime': '2017-05-20T07:00:00+08:00' },
	'end': { 'dateTime': '2017-05-20T08:00:00+08:00' },
	'location': 'Coffeeshop',
	'summary': 'Breakfast',
	'status': 'confirmed',
	'description': '',
	'colorId': 1
};

cal.Events.insert(calendarId, params)
  .then(resp => {
	console.log('inserted event:');
	console.log(resp);
  })
  .catch(err => {
	console.log('Error: insertEvent-' + err.message);
  });

Events.delete - Deletes an Event on a specified Calendar with EventId. Returns promise of results.

let params = {
	sendNotifications: true
};

cal.Events.delete(calendarId, eventId, params)
  .then(results => {
	console.log('delete Event:' + JSON.stringify(results));
  }).catch(err => {
        console.log('Error deleteEvent:' + JSON.stringify(err.message));
  });

Events.patch - Specify part of an existing event to modify. Returns promise of results. Must specify the eventId (the "id" of an event) and any fields you'd like to modify. All other fields remain untouched.

cal.Events.patch(calendarId, eventId, {
       summary: "updated summary",
       ...
       ...
     })
     .then(results => {
       console.log("patched Event:" + JSON.stringify(results));
     })
     .catch(err => {
       console.log("Error patchedEvent:" + JSON.stringify(err.message));
     });
   })

FreeBusy Examples

FreeBusy.query - Checks if queried calendar slot is busy during selected period. Returns promise of list of events at specified slot.

let params = {
	"timeMin": '2017-05-20T08:00:00+08:00',
	"timeMax": '2017-05-20T09:00:00+08:00',
	"items": [{ "id": calendarId }]
};

cal.FreeBusy.query(calendarId, params)
  .then(resp => {
  	console.log('List of busy timings with events within defined time range: ');
        console.log(resp);
  })
  .catch(err => {
	console.log('Error: checkBusy -' + err.message);
  });

Settings Examples

Settings.list - List user settings

let params = {};
cal.Settings.list(params)
  .then(resp => {
	console.log('List settings: ');
	console.log(resp);
  })
  .catch(err => {
	console.log('Error: listSettings -' + err.message);
  });

More code examples of the various APIs here.