Google-calendar-subscriptions NPM

Google Calendar Subscriptions

Google Calendar Subscriptions is an npm module that extends the Google Calendar client with types and methods to define, manipulate and synchronize calendar subscriptions.

Why? 🤔

Calendar subscriptions are a great tool, but:

The information they provide is sometimes limited and not formatted as we wish
They are static and cannot be modified or enriched with additional data
The user does not own subscription calendars, which cannot be managed or shared
Synchronizations can't be controlled manually and happen at predefined intervals (usually 24 hours)

In combination with CI tools like GitHub Actions, this module aims to solve these problems by providing a simple way to define, create and sync calendar subscriptions.

Installation

npm i google-calendar-subscriptions

pnpm i google-calendar-subscriptions

yarn add google-calendar-subscriptions

Usage

Authenticate to the client using a service account.

import { auth, calendar } from 'google-calendar-subscriptions'

const client = calendar({
  version: 'v3',
  auth: new auth.GoogleAuth({
    credentials: {
      client_email: '<service-account-email>',
      private_key: '<service-account-key>'
    },
    scopes: ['https://www.googleapis.com/auth/calendar']
  })
})

Define a subscription following its schema:

const newSubscription = {
  summary: 'My Subscription',
  id: 'my-subscription',
  owner: 'john.doe@gmail.com'
  subscriptionUrl: 'https://example.com/events.ics',
  fn: events => events.map(event => ({
    ...event,
    summary: event.summary.toUpperCase(),
  }))
}

Create a calendar linked to the subscription using insert:

const subscription = await client.subscriptions.insert({ requestBody: newSubscription })

// The subscription will contain the ID of the newly created calendar.
console.log(subscription)
// Output:
// {
//   calendarId: "*************@group.calendar.google.com",
//   fn: "<stringified-function>",
//   id: "my-subscription",
//   owner: "john.doe@gmail.com",
//   summary: "My Subscription",
//   url: "https://example.com/events.ics"
// }

You can now start syncing the subscription using sync:

await client.subscriptions.sync({ requestBody: subscription })

Subscription functions can be either synchronous or asynchronous:

const newAsyncSubscription = {
  subscriptionUrl: 'https://example.com/events.ics',
  fn: async events => {
    const { data } = await fetch(`https://example.com/resource`)
    
    return events.map(event => {
      // use fetched data to modify events...
    })
  },
}

const asyncSubscription = await client.subscriptions.create({ requestBody: newAsyncSubscription })

Multiple subscriptions can also be synced at once, and calendars can be cleared before syncing:

await client.subscriptions.sync({ 
  requestBody: [subscription, asyncSubscription],
  options: { 
    clear: true,
  }
})

Authentication

Head over to your Google Cloud console, create a new project and enable the Google Calendar API.

Create a new service account and grant it owner permissions. Finally, select Manage keys and create a new JSON key:

A file will be downloaded to your computer. Use the client_email and private_key values to authenticate to the client.

CI

GitHub Actions :octocat:

A GitHub Action to sync subscriptions programmatically is under development and will be released soon!

API

The following API extends and overrides the original definitions of the Google Calendar client.

`calendar_v3`

Namespace of the Google Calendar client with additional subscription definitions.

`auth`

AuthPlus instance exported from the original client.

`calendar(options)`

Function returning a Calendar instance with subscription functionalities.

`Calendar.subscriptions.insert(params, options)`

Function creating and syncing a new subscription.

`Calendar.subscriptions.sync(params, options)`

Function synchronizing the specified subscriptions.

Types

See calendar.d.ts.

Development

Clone the repository using Git or the GitHub CLI:

git clone git@github.com:gabrielecanepa/google-calendar-subscriptions.git
# or
gh repo clone gabrielecanepa/google-calendar-subscriptions

Install the dependencies with your preferred package manager and activate the Husky hooks:

pnpm i
# or
npm i
# or
yarn

To run the tests, rename .env.example to .env and fill it with your credentials. Some sample calendars to be used as TEST_SUBSCRIPTION_URLS are available here.