CogniPrep tracks application deadlines, and a deadline is only useful in the calendar the candidate actually looks at. We publish one ICS feed per account. The hard part was never generating the file. It was the handoff: getting a URL into Apple Calendar, Google Calendar and Outlook, each of which wants something different.

The whole handoff is 47 lines with no imports.

Five strings from one

export function calendarSubscriptionLinks(feedUrl: string): CalendarSubscriptionLinks { const webcal = feedUrl.replace(/^https?:\/\//, 'webcal://'); return { url: feedUrl, webcal, google: `https://calendar.google.com/calendar/render?cid=${encodeURIComponent(webcal)}`, outlook: outlookAddFromWeb('outlook.live.com', webcal), office365: outlookAddFromWeb('outlook.office.com', webcal), }; } 

That is the entire module's logic. Everything interesting about it is why each line is shaped the way it is.

webcal:// is a scheme swap, not a different URL. Four of the five links are the same resource; webcal is the http(s) URL with the scheme replaced. Apple Calendar on iPhone and Mac registers that scheme and opens its subscribe dialog, and so do most desktop calendar apps. One tap, no account with us or anyone else. The regex is anchored at the start, which matters more than it looks: a feed URL that happens to contain the string http later on would otherwise be corrupted.

Google's add-by-URL is a render call with a cid parameter, and cid gets the webcal form rather than the https form. Google accepts either, but the webcal scheme is the one its own UI emits, so it is the one less likely to change behaviour.

Outlook wants a page, not a scheme. There is no outlook:// equivalent. What exists is a web page that opens "Subscribe from web" pre-filled:

function outlookAddFromWeb(host: string, webcal: string): string { return `https://${host}/calendar/0/addfromweb/?url=${encodeURIComponent(webcal)}&name=${encodeURIComponent(CALENDAR_NAME)}`; } 

Two things about that. The name parameter is what Outlook will call the subscribed calendar in the user's sidebar forever, so it is a product decision disguised as a query string. And the path is not documented by Microsoft. The module says exactly that:

 *  - Outlook on the web has an `addfromweb` page that opens "Subscribe from *  web" with the URL and name filled in. Microsoft does not document it, but *  it is what the common add-to-calendar widgets use, and it has been stable *  for years. 

I would normally refuse to ship an undocumented endpoint. The argument for this one is that the failure is visible and harmless: if the page ever moves, the user lands on Outlook's calendar with nothing filled in, and the dialog offers a copyable URL right beside the button for precisely that case. An undocumented link whose failure mode is "you paste a URL instead" is a different risk class from an undocumented API your backend depends on.

Two Outlook hosts, not one. outlook.live.com is personal accounts, outlook.office.com is work or school. There is no host that serves both, and guessing wrong gives a sign-in page for the wrong identity. So the UI asks, with two buttons labelled "Outlook.com" and "Work or school account". Users of a Microsoft 365 tenant are used to that question; users who have never met it get the obvious button first.

Google gets a second path, and it is the recommended one

The same dialog offers a direct Google connection through OAuth as well as the cid link, and the component comment explains why one vendor gets two:

 * Google gets a direct connection, because a subscribed URL in Google Calendar * can take a day or more to pick up a change. Everything else, Apple Calendar * and Outlook included, subscribes to the private feed URL, which needs no * account with anyone. 

This is the part worth knowing if you are about to build a feed. A pulled ICS subscription refreshes on the client's schedule, not yours. The format has a refresh hint, and Apple and Outlook broadly respect it. Google does not: in practice a subscribed URL can lag by many hours or a day. For "my deadline moved to tomorrow", a day is useless.

So the one calendar with a real API gets writes pushed to it, and everybody else gets the feed. That means two sync models in one feature, which is more code than one, and the reason is a single vendor's refresh behaviour. No amount of correct ICS fixes it.

The feed does not exist until you ask

One detail I liked more than the links themselves. The feed is created lazily, the first time the dialog opens:

if (feed) return; sendJson('/api/calendar/feed', 'POST', { action: 'create' }) 

A candidate who never opens the calendar dialog never has a live feed URL at all. That is the cheapest possible answer to "what is the attack surface of a private, unauthenticated feed URL": for most accounts, there isn't one, because it was never minted.

Small things that are the difference between working and almost working

  • Both query parameters go through encodeURIComponent. The URL contains characters that must not survive into a query string raw, and the calendar name is interpolated too, so a future rename containing a space cannot break the link.
  • The copyable plain URL is offered as a first-class option, not a fallback for the technically inclined. Every calendar app that is not one of the big three takes a URL, and so does Outlook if its page ever moves.
  • Clipboard writes fail, so the failure path says something actionable: "Select the link and copy it by hand."
  • Each button records which route the user took. After a week you know whether anyone clicks the work-or-school button, which is the only way to find out whether splitting Outlook in two was worth it.
  • Two tests pin all five strings exactly, including the double-encoded webcal inside Google's cid. These are pure string builders, so the tests are the cheapest kind to write and the only thing standing between you and a silent typo in an undocumented path.

What I would steal from this

If you are adding "add to calendar" to anything:

  1. Build the webcal:// form by swapping the scheme on your real URL, anchored at the start. Do not maintain a second URL.
  2. Give Google both options and default to the API if you have one, because the subscription refresh is not under your control.
  3. Ask which Outlook. Do not guess.
  4. Always show the raw URL. It is the only link that cannot break.

See it

The dates the feed carries are public before any account exists. CogniPrep publishes the editorial deadline tables that the tracker is built around:

The tracker page itself describes what happens to a date once it is yours.

To check the link-building for yourself, no account needed: take any public ICS URL, swap https:// for webcal://, and paste the result into https://calendar.google.com/calendar/render?cid= with the URL percent-encoded. Google's confirmation dialog opens with the calendar named and ready to add. Then try the same encoded URL on https://outlook.live.com/calendar/0/addfromweb/?url=...&name=Test. That is the whole module, reproduced by hand.