@dgcode/channels

channel helpers / middleware for Google push notifications

Install

$ npm install @dgcode/channels

Features

This library offers syntactic sugar for Google channel creation and destruction methods, mainly powered by the @dgcode/auth and googleapis libraries.

The following channel-focused methods are implemented:

• AdminDirectory > Users > watch
• AdminDirectory > Users.aliases > watch
• Gmail > Users > watch
• Calendar > ACL > watch
• Calendar > CalendarList > watch
• Calendar > Events > watch
• Calendar > Settings > watch
• stop-channel methods for all of the above

Usage

The example below sets up an environment to detect push notifications for user updates in the Admin Directory:

import express = require('express');
import { Channels } from '@dgcode/channels';

const channels = new Channels('users');

// TODO set your own address here
channels.setUrl('https://www.someexample.com/notifications/{event});

// OPTIONAL: use a fixed channel ID to always use for this channel environment
channels.setChannelId('my-unique-channel-id');

// RECOMMENDED: use an app-specific required token to "certify" push requests
channels.setToken('my-required-token');

channels.on('create', channel => {
  const { primaryEmail } = channel.getBody();
  console.log('User %s has been created', primaryEmail);
});

channels.on('update', channel => {
  const { primaryEmail } = channel.getBody();
  console.log('User %s has been updated', primaryEmail);
});

const app = express();
app.use(express.json()); // required to populate `req.body`
app.use(channels.middleware());
app.listen();

Note the above code by itself is not enough to set up the whole notification cycle; the notifications still need to be setup manually following Google's guide to create push channels to your authorized domains.

Such process is facilitated though by the API (re-using the same configured channels instance):

async function ensureUsersChannelWatching() {

  const channel = await channels.watch();
  console.log('New channel generated: %s', JSON.stringify(channel.toData(), null, 2));

}

Watched resource kinds

For the moment three major kinds of resources are supported:

• AdminDirectory Users
• Gmail Users
• Calendars

The way your channels interact with them is based on the KEY parameter you provide on construction, as in new Channels('KEY'). The valid key values to interact with Google channels are:

• 'users' (AdminDirectory Users)
• 'users.aliases' (AdminDirectory Users Aliases)
• 'users.gmail' (Gmail Users)
• 'calendar.acl' (Calendar ACL)
• 'calendar.list' (Calendar List)
• 'calendar.events' (Calendar Events)
• 'calendar.settings' (Calendar Settings)

Gmail notifications

TODO More documentation to come

Typings

TypeScript type definitions are directly bundled with this package.

License

MIT