@render-lab/tasks-gcal

⚠️ Experimental: proof of concept. This package is part of the Render Tasks POC and is published for testing only. It is not fully tested or production ready. Task names, inputs, outputs, and behavior can change or break in any release. Pin exact versions and expect breaking changes.

Durable Google Calendar tasks for Render Workflows. A brand package: the task surface follows Google Calendar's own object model.

Tasks

| Task | Input | Result | | --- | --- | --- | | gcal.createEvent | { calendarId?, summary, start, end, description?, attendees? } | CalEvent | | gcal.suggestTime | { calendarId?, durationMinutes, withinDays? } | { start, end } | | gcal.respond | { calendarId?, eventId, response } | { eventId, response } | | gcal.listEvents | { calendarId?, timeMin?, timeMax?, limit? } | CalEvent[] | | gcal.getEvent | { calendarId?, eventId } | CalEvent | | gcal.updateEvent | { calendarId?, eventId, summary?, start?, end?, description?, attendees? } | CalEvent | | gcal.deleteEvent | { calendarId?, eventId } | { eventId, deleted } | | gcal.findFreeBusy | { timeMin, timeMax, calendarIds? } | FreeBusyCalendar[] | | gcal.quickAdd | { calendarId?, text } | CalEvent |

suggestTime lists events in the next withinDays (default 7) and returns the first free slot via the pure, exported firstFreeSlot(busy, durationMinutes, fromIso, untilIso) helper. updateEvent is a partial (PATCH) update — only the fields you pass are changed. findFreeBusy flattens Google's keyed { calendars: { <id>: { busy } } } response to a plain [{ calendarId, busy }] array; calendarIds defaults to the single default calendar. quickAdd creates an event from a natural-language phrase (e.g. "Lunch with Sam tomorrow at noon"). Times are ISO 8601.

Every task exports both the wrapped task and a raw *Impl (deps-injectable) per ADR-0004. Retries are baked in (GCAL_RETRY); the API's own retries are not used (ADR-0005).

Env contract

Read lazily at first use, never at import (ADR-0007):

| Variable | Required | Purpose | | --- | --- | --- | | GOOGLE_ACCESS_TOKEN | yes | Pre-issued OAuth access token (Bearer). | | GCAL_CALENDAR_ID | no | Default calendar; falls back to "primary". |

OAuth token acquisition (the OAuth dance / refresh) is out of scope for this POC: the tasks expect a valid access token to be provided in the environment.