> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar

> Virtualize Google Calendar calendars and events from Node or the browser.

`GCalVFS` mounts every calendar an account can see: each calendar becomes a
folder of days, and each event a `.gcal.json` file holding the Calendar API's
JSON. Set up the credentials as in [Google Workspace setup](https://docs.mirage.strukto.ai/home/setup/google.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { GCalVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const gcal = new GCalVFS({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  refreshToken: process.env.GOOGLE_REFRESH_TOKEN!,
})
const ws = new Workspace({ '/gcal': gcal }, { mode: MountMode.READ })

const result = await ws.shell("ls /gcal && grep -lw standup /gcal/primary/2026-11-*/*.gcal.json")
console.log(result.stdoutText)
await ws.close()
```

`bucketDays: 7` or `30` makes each folder 7 or 30 days, `timeZone` sets
the zone days are cut in, and `startTime` and `endTime` limit the mount to a
time range. A `MountMode.WRITE` mount also allows `rm`.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**accessToken** `string | function`

OAuth access token, or a function (sync or async) that returns one. Takes precedence over `clientId` and `refreshToken`.

**clientId** `string`

Google OAuth client ID. Required with `refreshToken` when `accessToken` is unset; mirage then mints and renews access tokens itself.

**clientSecret** `string`

Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.

**refreshToken** `string`

User's OAuth refresh token. Required with `clientId` when `accessToken` is unset.

**refreshFn** `function`

Function that exchanges the refresh token for `{ accessToken, expiresIn }` instead of Google's token endpoint, so the client secret can stay on a backend. Still needs `clientId` and `refreshToken`.

**apiBase** `string`

One base URL that replaces every Google API host and the OAuth token endpoint, such as a test server. Unset uses Google's hosts.

**startTime** `string`

Start of the mount's time scope, inclusive: an RFC 3339 timestamp with an explicit timezone and at most millisecond precision. Unset leaves the start open.

**endTime** `string`

End of the mount's time scope, exclusive, in the same format as `startTime`, which it must follow. Unset leaves the end open.

**timeZone** `string`

IANA time zone the mount buckets every calendar's days in. Unset uses the primary calendar's zone.

**bucketDays** `1 | 7 | 30` (default: 1)

Days each date directory under a calendar holds: `1` names it by its day, `7` and `30` by its first and last day (`<first>--<last>`).

**minAccessRole** `string`

List only calendars where the account has at least this access role: `freeBusyReader`, `reader`, `writer` or `owner`. Unset lists every calendar.

**today** `string`

Day (`YYYY-MM-DD`) the default listing's 90-day future horizon is measured from, for tests and snapshots. Unset uses the current date in the mount's time zone.

Fields marked secret are redacted in snapshots.

## Authentication

Credentials come from the first of:

1. `accessToken`, a token or a function, sync or async, that returns one.
2. `clientId` and `refreshToken`, with `clientSecret` unless the client uses
   PKCE. Mirage trades the refresh token for access tokens on its own, or
   hands it to `refreshFn` when set, so the secret can stay on a backend.

The mount needs the Google Calendar API with the
`https://www.googleapis.com/auth/calendar` scope, or `calendar.readonly` for a
read-only mount. `rm` needs the `owner` or `writer` role on the event's
calendar; otherwise it fails with `Permission denied`.

## Layout

```text theme={null}
/gcal/
  primary/
    calendar.json
    2026-11-16/
      7kq2m9__0900-0930_Team_Standup.gcal.json
  Engineering__team@group.calendar.google.com/
    2026-11-16/
      ...
```

* The primary calendar is `primary`; every other one ends in
  `__<calendar-id>`.
* An event file is named `<event-id>__<HHMM-HHMM>_<title>.gcal.json`. The
  times are clamped to that day, so an event running through it reads
  `0000-2400`, and an event over several days appears under each.
* An event file holds the unmodified Calendar API payload: attendees,
  description, location, and start and end with their offsets.
* `calendar.json` holds the calendar's access role and the zone its days are
  cut in.

## Behavior

* **Time range:** `ls` of a calendar lists days from all its history through
  90 days ahead. A date glob such as `ls /gcal/primary/2027-03-*` lists its
  own range, past that horizon. `startTime` and `endTime` (RFC 3339 with a
  timezone) limit every listing, path, glob and read; dates outside them are
  absent.
* **Days:** a well-formed date inside the range is a folder even when it holds
  no events. One zone covers the whole mount, the primary calendar's unless
  `timeZone` is set, so every calendar's `2026-11-16/` covers the same hours.
* **Calendars listed:** `minAccessRole` (`freeBusyReader`, `reader`,
  `writer` or `owner`) hides calendars where the account has less access.
* **Free/busy calendars:** Google returns no titles for a calendar shared as
  free/busy only, so its events read as `busy`.
* **Delete:** on a `write` mount, `rm` on an event file deletes the event for
  every attendee. Creating, editing and moving events go through the
  [`gws calendar`](https://docs.mirage.strukto.ai/typescript/cli/gws) CLI, which takes the calendar and event
  ids the tree shows. A written event must carry an explicit UTC offset or
  time zone.

## Browser

The same `GCalVFS` comes from `@struktoai/mirage-browser`. In a page, an
`accessToken` function fetches a fresh token from a backend, so the client
secret never reaches the browser.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { GCalVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const gcal = new GCalVFS({
  accessToken: async () => (await fetch('/api/google-token')).text(),
})
const ws = new Workspace({ '/gcal': gcal }, { mode: MountMode.READ })
```

* `/api/google-token` stands for a backend endpoint that returns an access
  token.
* A PKCE OAuth client needs no secret: `clientId` and `refreshToken` alone
  mount it.
* `refreshFn` sends each refresh to a backend instead of Google's token
  endpoint.

## Integration

Google Calendar answers these commands through its own API, so fewer files
are read. See [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -r` and `rg` with `-w`: Calendar's event search names the event files
  to read, together with the text the listing keeps, so no match is missed.
  Every file is read when the search fails or finds nothing, and files other
  than events (`calendar.json`) are always read. `walkLimit: -1` in the
  mount's `"@all"` [command limit](https://docs.mirage.strukto.ai/home/limits.md#command-output) turns the search
  off and reads every file.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Google Calendar mounted at
`/<path>`. `<mode>` is the mount's mode: `read`, `write` or `exec`. The
commands shown are those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `gcal`, `<mode>` |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   primary/
>     calendar.json
>     2026-08-11/
>       <eventId>__0900-1030_Team_Standup.gcal.json
>   Engineering__team@group.calendar.google.com/
>     2026-08-11/
>       ...
> ```
>
> * Calendars are `primary` and `<Name>__<calendarId>`; `calendar.json`
>   holds the calendar's `accessRole` and `bucketTimeZone`, the zone every
>   bucket is cut in.
> * A bucket is one local day. A file is
>   `<eventId>__<HHMM-HHMM>_<Title>.gcal.json`, times clamped to the day; a
>   multi-day event appears under each day.
> * `cat` an event for the raw Calendar API JSON (attendees, description,
>   location, start and end with offsets).
> * A listing runs through today +90 days unless `end_time` is set; a date
>   glob such as `2027-03-*` reaches past that.
> * On a `write` path, `rm` an event file deletes it for every attendee.
>   Other changes go through the `gws calendar` CLI, with explicit offsets
>   or a `timeZone`.
>
> Time scope: `start_time=unbounded` (inclusive), `end_time=unbounded` (exclusive); explicit paths and globs cannot escape it.
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest), and `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gcal` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Not supported: `>`, `>>`, `tee`, `tee -a`, `touch` of a new file, `cp`, `cp -r`, `mkdir`, `mv`, `rm -r`, `rmdir`, `truncate`, `sed -i`. Without `-w`, `grep -r` and `rg` read every file. `gcal` answers only for `*/*/*.gcal.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `gcal`, `<mode>` |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   primary/
>     calendar.json
>     2026-08-11/
>       <eventId>__0900-1030_Team_Standup.gcal.json
>   Engineering__team@group.calendar.google.com/
>     2026-08-11/
>       ...
> ```
>
> - Calendars are `primary` and `<Name>__<calendarId>`; `calendar.json`
>   holds the calendar's `accessRole` and `bucketTimeZone`, the zone every
>   bucket is cut in.
> - A bucket is one local day. A file is
>   `<eventId>__<HHMM-HHMM>_<Title>.gcal.json`, times clamped to the day; a
>   multi-day event appears under each day.
> - `cat` an event for the raw Calendar API JSON (attendees, description,
>   location, start and end with offsets).
> - A listing runs through today +90 days unless `end_time` is set; a date
>   glob such as `2027-03-*` reaches past that.
> - On a `write` path, `rm` an event file deletes it for every attendee.
>   Other changes go through the `gws calendar` CLI, with explicit offsets
>   or a `timeZone`.
>
> Time scope: `start_time=unbounded` (inclusive), `end_time=unbounded` (exclusive); explicit paths and globs cannot escape it.
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest), and `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gcal` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Not supported: `>`, `>>`, `tee`, `tee -a`, `touch` of a new file, `cp`, `cp -r`, `mkdir`, `mv`, `rm -r`, `rmdir`, `truncate`, `sed -i`. Without `-w`, `grep -r` and `rg` read every file. `gcal` answers only for `*/*/*.gcal.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.