Add Google Calendar reminders to Slashwork

Poll Google Calendar API every 60s, post "starting soon" reminders to
Slashwork groups or chats. Per-user config maps a calendar ID to a target.
Uses service account auth (JSON key via env var), dedicated Slashwork token,
in-memory dedup, and is entirely optional (gated on GOOGLE_SERVICE_ACCOUNT_KEY).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: hubyrod

.env.example

@@ -6,3 +6,10 @@ SLASHWORK_AUTH_TOKEN=your_application_auth_token
 GITHUB_WEBHOOK_SECRET=your_github_webhook_secret
 
 PORT=3000
+
+# Google Calendar reminders (optional — omit to disable)
+# Service account JSON key (paste the full JSON content)
+GOOGLE_SERVICE_ACCOUNT_KEY={"type":"service_account","client_email":"...","private_key":"..."}
+# Slashwork auth token for posting calendar reminders
+SLASHWORK_AUTH_TOKEN_GOOGLE_CALENDAR=your_calendar_auth_token
+# Per-user calendar → group mapping is configured in config.ts

.gitignore

@@ -31,6 +31,11 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 # IntelliJ based IDEs
 .idea
 
+# Google service account keys
+*.json
+!package.json
+!tsconfig.json
+
 # Finder (MacOS) folder config
 .DS_Store
 

config.ts

@@ -17,6 +17,18 @@ const config: SkiphooksConfig = {
       authToken: process.env.SLASHWORK_AUTH_TOKEN_SKJS!,
     },
   },
+  ...(process.env.GOOGLE_SERVICE_ACCOUNT_KEY
+    ? {
+        calendar: {
+          serviceAccountKey: process.env.GOOGLE_SERVICE_ACCOUNT_KEY,
+          authToken: process.env.SLASHWORK_AUTH_TOKEN_GOOGLE_CALENDAR!,
+          users: [
+            // Add one entry per user: their calendar → a Slashwork group or chat
+            // { name: "Alice", calendarId: "alice@example.com", targetId: "g_..." },
+          ],
+        },
+      }
+    : {}),
   routes: {
     skipper: {
       group: "skipper",

src/calendar/auth.ts

@@ -0,0 +1,108 @@
+import { createSign } from "node:crypto";
+
+interface ServiceAccountKey {
+  client_email: string;
+  private_key: string;
+  token_uri: string;
+}
+
+interface CachedToken {
+  accessToken: string;
+  expiresAt: number;
+}
+
+let cachedToken: CachedToken | null = null;
+
+function base64url(input: string | Buffer): string {
+  const buf = typeof input === "string" ? Buffer.from(input) : input;
+  return buf.toString("base64url");
+}
+
+function createJwt(key: ServiceAccountKey): string {
+  const now = Math.floor(Date.now() / 1000);
+  const header = { alg: "RS256", typ: "JWT" };
+  const payload = {
+    iss: key.client_email,
+    scope: "https://www.googleapis.com/auth/calendar.readonly",
+    aud: key.token_uri,
+    iat: now,
+    exp: now + 3600,
+  };
+
+  const segments = [
+    base64url(JSON.stringify(header)),
+    base64url(JSON.stringify(payload)),
+  ];
+  const signingInput = segments.join(".");
+
+  const sign = createSign("RSA-SHA256");
+  sign.update(signingInput);
+  const signature = sign.sign(key.private_key);
+
+  return `${signingInput}.${base64url(signature)}`;
+}
+
+export function parseServiceAccountKey(
+  jsonString: string,
+): ServiceAccountKey {
+  const content = JSON.parse(jsonString);
+  if (!content.client_email || !content.private_key) {
+    throw new Error(
+      "Service account key missing client_email or private_key",
+    );
+  }
+  return {
+    client_email: content.client_email,
+    private_key: content.private_key,
+    token_uri: content.token_uri || "https://oauth2.googleapis.com/token",
+  };
+}
+
+export async function getAccessToken(serviceAccountKey: string): Promise<string> {
+  // Return cached token if still valid (with 5 min buffer)
+  if (cachedToken && cachedToken.expiresAt > Date.now() + 5 * 60 * 1000) {
+    return cachedToken.accessToken;
+  }
+
+  const key = parseServiceAccountKey(serviceAccountKey);
+  const jwt = createJwt(key);
+
+  const response = await fetch(key.token_uri, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion: jwt,
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      `Google OAuth token exchange failed: ${response.status} - ${body}`,
+    );
+  }
+
+  const result = (await response.json()) as {
+    access_token: string;
+    expires_in: number;
+  };
+
+  cachedToken = {
+    accessToken: result.access_token,
+    expiresAt: Date.now() + result.expires_in * 1000,
+  };
+
+  return cachedToken.accessToken;
+}
+
+export async function validateCalendarAuth(
+  serviceAccountKey: string,
+): Promise<void> {
+  await getAccessToken(serviceAccountKey);
+}
+
+/** Reset cached token (for tests). */
+export function _resetTokenCache(): void {
+  cachedToken = null;
+}

src/calendar/calendar.test.ts

@@ -0,0 +1,168 @@
+import { test, expect } from "bun:test";
+import { formatCalendarReminder, isAllDayEvent, isCancelledEvent } from "./format.ts";
+import type { CalendarEvent } from "./types.ts";
+
+function makeEvent(overrides: Partial<CalendarEvent> = {}): CalendarEvent {
+  return {
+    id: "event-1",
+    status: "confirmed",
+    summary: "Team Standup",
+    htmlLink: "https://calendar.google.com/event?eid=abc123",
+    start: { dateTime: "2026-03-03T10:00:00-05:00" },
+    end: { dateTime: "2026-03-03T10:30:00-05:00" },
+    ...overrides,
+  };
+}
+
+// formatCalendarReminder tests
+
+test("formatCalendarReminder: includes all fields", () => {
+  const event = makeEvent({
+    location: "Conference Room A",
+    hangoutLink: "https://meet.google.com/abc-defg-hij",
+    description: "Daily sync to discuss progress",
+  });
+
+  const { markdown } = formatCalendarReminder(event, "Engineering", 5);
+
+  expect(markdown).toContain("Team Standup");
+  expect(markdown).toContain("in 5 min");
+  expect(markdown).toContain("Engineering");
+  expect(markdown).toContain("Conference Room A");
+  expect(markdown).toContain("https://meet.google.com/abc-defg-hij");
+  expect(markdown).toContain("Join video call");
+  expect(markdown).toContain("Daily sync to discuss progress");
+  expect(markdown).toContain("https://calendar.google.com/event?eid=abc123");
+});
+
+test("formatCalendarReminder: handles missing optional fields", () => {
+  const event = makeEvent({
+    summary: undefined,
+    htmlLink: undefined,
+    location: undefined,
+    hangoutLink: undefined,
+    description: undefined,
+  });
+
+  const { markdown } = formatCalendarReminder(event, "Work", 3);
+
+  expect(markdown).toContain("(No title)");
+  expect(markdown).toContain("in 3 min");
+  expect(markdown).toContain("Work");
+  expect(markdown).not.toContain("Location");
+  expect(markdown).not.toContain("Join video call");
+});
+
+test("formatCalendarReminder: truncates long description", () => {
+  const event = makeEvent({
+    description: "x".repeat(300),
+  });
+
+  const { markdown } = formatCalendarReminder(event, "Cal", 2);
+
+  expect(markdown).toContain("…");
+  // Should be truncated to ~200 chars + ellipsis
+  const descLine = markdown.split("\n").find((l) => l.startsWith(">"));
+  expect(descLine).toBeDefined();
+  expect(descLine!.length).toBeLessThan(210);
+});
+
+test("formatCalendarReminder: strips HTML from description", () => {
+  const event = makeEvent({
+    description: "<b>Important:</b> Bring <a href='#'>docs</a>",
+  });
+
+  const { markdown } = formatCalendarReminder(event, "Cal", 4);
+
+  expect(markdown).toContain("Important:");
+  expect(markdown).toContain("Bring");
+  expect(markdown).toContain("docs");
+  expect(markdown).not.toContain("<b>");
+  expect(markdown).not.toContain("<a");
+});
+
+test("formatCalendarReminder: shows 'starting now' for <=1 min", () => {
+  const event = makeEvent();
+
+  const { markdown } = formatCalendarReminder(event, "Cal", 0.5);
+
+  expect(markdown).toContain("starting now");
+  expect(markdown).not.toContain("in 0");
+});
+
+test("formatCalendarReminder: uses conferenceData when no hangoutLink", () => {
+  const event = makeEvent({
+    hangoutLink: undefined,
+    conferenceData: {
+      entryPoints: [
+        { entryPointType: "phone", uri: "tel:+1234567890" },
+        { entryPointType: "video", uri: "https://zoom.us/j/123456" },
+      ],
+    },
+  });
+
+  const { markdown } = formatCalendarReminder(event, "Cal", 3);
+
+  expect(markdown).toContain("https://zoom.us/j/123456");
+  expect(markdown).toContain("Join video call");
+});
+
+// isAllDayEvent tests
+
+test("isAllDayEvent: returns true for date-only events", () => {
+  const event = makeEvent({
+    start: { date: "2026-03-03" },
+    end: { date: "2026-03-04" },
+  });
+
+  expect(isAllDayEvent(event)).toBe(true);
+});
+
+test("isAllDayEvent: returns false for timed events", () => {
+  const event = makeEvent();
+
+  expect(isAllDayEvent(event)).toBe(false);
+});
+
+// isCancelledEvent tests
+
+test("isCancelledEvent: returns true for cancelled status", () => {
+  const event = makeEvent({ status: "cancelled" });
+
+  expect(isCancelledEvent(event)).toBe(true);
+});
+
+test("isCancelledEvent: returns false for confirmed status", () => {
+  const event = makeEvent({ status: "confirmed" });
+
+  expect(isCancelledEvent(event)).toBe(false);
+});
+
+// Dedup key logic (tested via Set behavior)
+
+test("dedup: same event ID + start time is deduplicated", () => {
+  const remindedKeys = new Set<string>();
+  const key1 = "cal1:event-1:2026-03-03T10:00:00Z";
+  const key2 = "cal1:event-1:2026-03-03T10:00:00Z";
+
+  remindedKeys.add(key1);
+  expect(remindedKeys.has(key2)).toBe(true);
+});
+
+test("dedup: different event IDs are not deduplicated", () => {
+  const remindedKeys = new Set<string>();
+  const key1 = "cal1:event-1:2026-03-03T10:00:00Z";
+  const key2 = "cal1:event-2:2026-03-03T10:00:00Z";
+
+  remindedKeys.add(key1);
+  expect(remindedKeys.has(key2)).toBe(false);
+});
+
+test("dedup: same event at different times is not deduplicated", () => {
+  const remindedKeys = new Set<string>();
+  const key1 = "cal1:event-1:2026-03-03T10:00:00Z";
+  const key2 = "cal1:event-1:2026-03-04T10:00:00Z";
+
+  remindedKeys.add(key1);
+  expect(remindedKeys.has(key2)).toBe(false);
+});

src/calendar/fetch-events.ts

@@ -0,0 +1,29 @@
+import type { CalendarEvent, CalendarEventsResponse } from "./types.ts";
+
+export async function fetchUpcomingEvents(
+  accessToken: string,
+  calendarId: string,
+  timeMin: Date,
+  timeMax: Date,
+): Promise<CalendarEvent[]> {
+  const params = new URLSearchParams({
+    timeMin: timeMin.toISOString(),
+    timeMax: timeMax.toISOString(),
+    singleEvents: "true",
+    orderBy: "startTime",
+    maxResults: "50",
+  });
+
+  const url = `https://www.googleapis.com/calendar/v3/calendars/${encodeURIComponent(calendarId)}/events?${params}`;
+
+  const response = await fetch(url, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!response.ok) {
+    return [];
+  }
+
+  const data = (await response.json()) as CalendarEventsResponse;
+  return data.items ?? [];
+}