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

or

pnpm i google-calendar-subscriptions

or

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: '[email protected]'
  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: "[email protected]",
//   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 [email protected]: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.

Releases

See changelog and releases.

License

MIT