nodejs

Google API Service Accounts With NodeJS

For a recent project I needed update to a single shared Google calendar. I decided to go with a Google service account to manage this. I’m going to post here how I did it.

What is a Service Account

A service account is used by an application as opposed to a real living person. It allows your application to make authorized API calls directly. A service account is identified by its email address, which is unique to the account.

  • Service accounts can not be logged into with browsers.
  • Authorization is done with a public-private RSA key.
  • Service accounts are not part of your Google domain. They do not share global resources like a live user.

Create a Service Account

At the very top choose the project drop down. This will open up the project window where you can select an ongoing project or create a new one. Each service account is located in a project. After you create a service account, you cannot move it to a different project.

In the Google Developers console (link) under the leftmost APIs & Services menu you will find the credentials option. At the top of the screen click the Create Credentials option. You will have a choice as to which type of credential you would like to create. Select service account. Most, though not all, API’s should work with service accounts.

Service Account Authentication

There are a number of ways to authenticate an application using a service account (link). If you are deployed on Google cloud you can use an attached service account. You can use a Workload Identity with Kubernetes pods. There is also the Workloads Identity Federation that works with other service providers. Here we will be using a service account key which allows us to deploy on our own cloud provider.

Create a Public-Private key.

Click on your service account name to bring up the management menu. There is a number of menus near the top of the screen; select keys. Press the add keys dropdown menu and select create new key. Use json unless you have a reason to do otherwise. Remember not to add this key to your git repository or put it anywhere the public can see it.

Create and Share a Calendar

Create a calendar in Google Calendars and look at it’s settings (3 little dots next to the name). Find “share the calendar with specific people” and add the email address of your service account. Give your service account the role “make changes to events”. Since the service account isn’t a real user, you don’t get a confirmation email, and the calendar won’t immediately show up using the Google Calendar API list method.

Find the calendar id under the integrate calendar heading on the settings page. It should look like an email address. Save this, we will be using it in a bit.

Getting Started

Install the google api package.

npm install googleapis

View the Google APIs documentation on github.

https://github.com/googleapis/google-api-nodejs-client

In the Google console, you will find “APIs and Services > Enabled APIs and Services” add the Calendar API to your project.

Code Pre-requisites

The following are three preliminary steps we need to preform before accessing the calendar API. After this we can start accessing the API methods. I will implement them in a class structure just to keep things clean.

  • Import the google api library
  • Create a new authentication object.
  • Obtain an instance of the calendar interface.
import { google } from "googleapis";
constructor() {
    const auth = new google.auth.GoogleAuth({
        keyFilename: GoogleCalendar.KEY_FILENAME,
        scopes: GoogleCalendar.SCOPES,
    });

    this.calendar = google.calendar({
        version: "v3",
        auth: auth,
    });
}

API Methods

Now that the environment is setup we will now go through a few of the available API calls. For a full list of see the Calendar API Documentation.

List

The list method allows you to view available calendars. It is found in the calendar.calendarList implementation. This is also where you find the create, get, and delete calendar methods. This is one of the simpler API calls.

list() {
    return new Promise((resolve, reject) => {
        this.calendar.calendarList.list((err, res) => {
            if (err) reject(err);
            if (res) resolve(res.data);
        });
    });
}

Insert

Newly added calendars won’t show up in the list until you have inserted them. We use the calendar identifier we saved above. In this case we also pass in an options object, containing a resource object, which in turn has the calendar id we want to add.

insert(id) {
    return new Promise((resolve, reject) => {
        const options = {
            resource: {
                id: id,
            },
        };

        this.calendar.calendarList.insert(options, (err, res) => {
            if (err) reject(err);
            if (res) resolve(res.data);
        });
    });
}

Delete

When you look at the API documentation for delete you notice that calendar id is in the url. This implies that we use a calendarId field in our options object. The resource field, as used above, goes in the body. This is something to watch out for when interpreting HTTP calls to NodeJS API calls.

remove(id) {
    return new Promise((resolve, reject) => {
        const options = {
            calendarId: id,
        };

        this.calendar.calendarList.delete(options, (err, res) => {
            if (err) reject(err);
            if (res) resolve(res.data);
        });
    });
}

Add Event

To add an event we access the events property of the calendar API. In this case we include both the calendar id in the URL as well as body properties.

addEvent(id, start, end, summary){
    return new Promise((resolve, reject) => {
        const options = {
            calendarId: id,
            resource: {
                start: {
                    date: "2022-05-21",
                },
                end: {
                    date: "2022-05-23",
                },
                summary: summary,
            },                
        };

        this.calendar.events.insert(options, (err, res) => {
            if (err) reject(err);
            if (res) resolve(res.data);
        });
    });        
}

References

Google Event Object

Google Calendar Create Event

NodeJS Code Coverage With C8

Code coverage allows you to determine how well unit-tests cover your codebase. The standard code coverage suite for JavaScript is the NYC interface for Istanbul. However, this package doesn’t play well with NodeJS modules. Instead we are going to use the C8 package. C8 uses functionality native to NodeJS to create output that is compatible with Istanbul reporters.

Installation

npm i --save-dev c8

Execution

You can run c8 on any source file by simply passing in the appropriate node command.

$ npx c8 node src/index.js
-----------|---------|----------|---------|---------|-------------------
File       | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-----------|---------|----------|---------|---------|-------------------
All files  |   88.23 |      100 |      50 |   88.23 |
 MooYou.js |   84.61 |      100 |      50 |   84.61 | 9-10
 index.js  |     100 |      100 |     100 |     100 |
-----------|---------|----------|---------|---------|-------------------

You can also easily run it with your Mocha test files.

$ npx c8 mocha
  MooYou Class Test
    #who
      ✔ returns 'you'


  1 passing (3ms)

-----------|---------|----------|---------|---------|-------------------
File       | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-----------|---------|----------|---------|---------|-------------------
All files  |   84.61 |      100 |      50 |   84.61 |
 MooYou.js |   84.61 |      100 |      50 |   84.61 | 9-10
-----------|---------|----------|---------|---------|-------------------

Configuration

C8 can be configured from the command line, in your package.json file, or in a configuration file in your project directory. In particular you can instruct C8 to report one files as opposed to just those in your tests (npx c8 --all mocha). You can also specify which files to include and/or ignore. See the configuration documentation for specific details.

Generating Reports

By default the coverage data will be located in the coverage/tmp directory. You can change this directory with the --temp-directory flag. Don’t forget to add this to your .gitignore file.

Run npx c8 report to regenerate reports after c8 has already been run. Use the -r flag to specify which reporter to use, and the -o flag to specify where to output the report. By default generated reports can be found in the coverage/ dirctory.

Vanilla C8 command with HTML report:

npx c8 -r html mocha

Generate C8 report after the fact:

npx c8 -r html report

Two-part C8 command with custom directories and HTML report:

npx c8 --temp-directory .c8 mocha
npx c8 report --temp-directory .c8 -o html_coverage -r html

In Code Markup

You can add comments into your source code that tells c8 to ignore certain portions of code.

Ignoring all lines until told to stop.

/* c8 ignore start */
function foo() {
  ...
}
/* c8 ignore stop */

Ignore next line.

/* c8 ignore next */

External References

https://www.npmjs.com/package/c8

https://github.com/bcoe/c8

Updating NPM Packages

Updating NPM Packages

  1. Navigate to the root directory of your project and ensure it contains a package.json file:
    • cd /path/to/project
  2. In your project root directory, run the outdated command to view outdated packages:
    • npm outdated
  3. In your project root directory, run the update command:
    • npm update

package.json

The way the wanted version is set in the package.json file may affect how updates are decided.

Version numbers are declared as a [major, minor, patch] tuple.

Caret Ranges ^1.2.3

Allows changes that do not modify the left-most non-zero element of the version specification. So 1.3.1 will update to 1.3.2 or 1.4.0. Though, 0.3.0 will update to 0.3.1 but not update to 0.4.0.

Version will update if:

  • ^1.2.3 : 1.2.3 < version < 2.0.0
  • ^0.3.0 : 0.3.0 < version < 0.4.0

X-Ranges

Allows ‘X’, ‘x’, or ‘*’ to stand in for a number in the version specification.

Version will update if:

  • “” : any version
    • same as “*” or “x.x.x”
  • 1.x.x : 1.0.0 < version < 2.0.0
    • same as “1”
  • 1.2.x : 1.2.0 < version < 1.3.0
    • same as “1.2”