@particle-academy/google-calendar-js 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to `@particle-academy/google-calendar-ui`,
+`@particle-academy/google-calendar-js`, `particle-academy/google-calendar-php`
+and `fancy-google-calendar`.
+
+The four packages share one version, because they are generated from one
+`provider/` definition and a version that meant something different in each
+would be a version nobody could reason about.
+
+## [0.2.0] — 2026-09-30
+
+### Added
+
+- **`event_create`**, **`event_update`** and **`event_delete`** — write
+  support, the first this connector has had. `event_update` uses PATCH
+  (`events.patch`), not PUT (`events.update`): PUT requires resending the
+  whole event or Google clears every field left out, which is a trap for
+  a caller that only wants to change one thing. No scope change —
+  `calendar.events` already covers create/update/delete.
+- Deliberately NOT included: attendees and recurrence. Both need an
+  array-of-objects (attendees) or array-of-strings (recurrence) config
+  shape nothing in this estate's vocabulary has needed before now; same
+  bar as everything in `vocabulary-deferred.md` — a second real need,
+  not a first guess. All-day (date-only) events are out of scope for the
+  same reason: they need `start.date`/`end.date` instead of
+  `start.dateTime`/`end.dateTime`, a variant this config shape cannot
+  express yet.
+
+## [0.1.0] — 2026-09-15
+
+### Added
+
+- **First release.** Actions `event_get`, `event_list` (full or incremental
+  with a `syncToken`; a `410` means list in full again), `channel_watch` and
+  `channel_stop`; the `events_changed` trigger, the first in the estate with
+  `delivery: "subscription"`. Google cannot renew a channel, so the trigger's
+  lease names `channel_watch` again as its renew, 86400 seconds before the
+  week-long channel expires. Deliveries carry an EMPTY body and are verified
+  by the channel token Google echoes in `X-Goog-Channel-Token`.
+- Requires `fancy-connector-core` ≥ 0.8.0 in js and php — the release that
+  carries `LeaseDeclaration` and the shared-token verification scheme.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,210 @@
-# @particle-academy/google-calendar-js
+# Google Calendar
 
-**0.0.0 claims the name and ships nothing.** It exists so a Trusted Publisher can be attached to the package; the first real release is published from https://github.com/Fancy-Friends/google-calendar by its `publish.yml` workflow with provenance, and this version is deprecated the moment it lands.
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
+Google Calendar for [fancy-flow][flow] — as **four imported, versioned packages**, one
+per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs
+change.
+
+[flow]: https://github.com/Particle-Academy/fancy-flow
+
+| Runtime | Package | Install |
+|---|---|---|
+| Authoring surface (every host) | `@particle-academy/google-calendar-ui` | `npm install @particle-academy/google-calendar-ui` |
+| Node | `@particle-academy/google-calendar-js` | `npm install @particle-academy/google-calendar-js` |
+| PHP 8.4+ | `particle-academy/google-calendar-php` | `composer require particle-academy/google-calendar-php` |
+| Python 3.11+ | `fancy-google-calendar` | `pip install fancy-google-calendar` |
+
+The `ui` package is the editor surface and is React on every host — a PHP or
+Python project installs it *and* its own runtime package, and never the `js` one.
+
+## What it costs you
+
+One dependency: `@particle-academy/fancy-connector-core` (or
+`particle-academy/fancy-connector-core` on Composer), which the `js` and `php`
+packages pull in themselves. The Python package has **zero** runtime
+dependencies.
+
+**No Google Calendar SDK.** Plain HTTP, deliberately: a vendor SDK is third-party code
+subject to the kit's full approval bar, and one per provider is hundreds of
+dependencies nobody is tracking.
+
+## Setting it up
+
+Everything below is generated from `provider/manifest.json`, so it cannot disagree with what the packages do.
+
+### Credentials
+
+A Google Calendar connection holds 5 values.
+
+**Two kinds of value, and mixing them up matters.** A `provider` credential is ONE value for the whole installation — an OAuth app's client secret serves every connected account. An `account` credential is one per connected account. A host that stores the second where it stores the first lets one account's credentials reach another's.
+
+| Field | Scope | Secret | Where it comes from |
+|---|---|---|---|
+| **OAuth client ID** | per installation | not secret | From Google Cloud Console -> APIs & Services -> Credentials. ONE value for the whole installation, not per connected account. |
+| **OAuth client secret** | per installation | **secret** | The client secret for the same OAuth app. One value for the whole installation. |
+| **Access token** | per connected account | **secret** | Per connected Google account, and it expires after ONE HOUR. The host refreshes it with the refresh token. |
+| **Refresh token** | per connected account | **secret** | Per connected Google account. Google issues one only when the consent request asks for offline access; without it the connection dies within the hour. |
+| **Channel token** | per connected account | **secret** | A secret the host chooses per connected account and sends as `token` on every events.watch. Google echoes it back in the X-Goog-Channel-Token header of every notification, and that echo is the ONLY thing that authenticates a delivery -- Google does not sign them. Up to 256 characters. |
+
+### Authorising
+
+Google Calendar uses OAuth2 (authorization_code). The package DECLARES the exchange; the HOST performs it — a consent screen needs a browser, a redirect URI and somewhere to persist the result, and all three belong to the host.
+
+- **Authorize URL** — https://accounts.google.com/o/oauth2/v2/auth
+- **Token URL** — https://oauth2.googleapis.com/token
+- **Scopes** — `https://www.googleapis.com/auth/calendar.events`
+- **Access token lifetime** — 3600 seconds (1 hours). A host that never refreshes works all afternoon and is broken by morning.
+
+The refresh tokens do **not** rotate: the same one is reusable, so a refresh may safely be retried and may run concurrently. Stated rather than assumed, because the opposite — a provider that spends the token and revokes the grant on a replay — looks identical until it happens.
+
+### The estate
+
+**Google Calendar has no test estate, and somebody checked.** Everything this connector does is real. Use the faker to build against it.
+
+> Google has no sandbox for Calendar. A test calendar is a real one in a real account, so every watch and every read is real -- point this at a scratch calendar, not a production one. The faker is the only way to develop against it without touching an account.
+
+## What it can do
+
+### Actions
+
+#### `channel_stop` — Google Calendar stop watching
+
+Close a push-notification channel. The host's subscription machinery calls this before re-creating a channel and when a trigger is removed.
+
+`POST /calendar/v3/channels/stop` · idempotent — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `channelId` | yes | The channel's id, as sent to channel_watch. |
+| `resourceId` | yes | The resourceId channel_watch answered with. Both are needed; Google refuses a stop with only one. |
+
+#### `channel_watch` — Google Calendar watch
+
+Open a push-notification channel on a calendar's events. The host's subscription machinery calls this; it is not a node most workflows need.
+
+`POST /calendar/v3/calendars/{calendarId}/events/watch` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `calendarId` | yes | `primary` for the connected account's own calendar, or a calendar's id. |
+| `channelId` | yes | A UUID the host mints for THIS channel. Google requires it to be unique; it comes back in every notification as X-Goog-Channel-ID and is what channel_stop needs. |
+| `address` | yes | The HTTPS URL the host mounts for this trigger. Google POSTs notifications here with an EMPTY body and the facts in X-Goog-* headers. |
+| `token` | yes | The connection's channelToken. The host fills this from the connection -- never type a value here. Google echoes it in X-Goog-Channel-Token, and that echo is how a delivery is verified. |
+| `ttlSeconds` | yes | How long Google keeps the channel alive. Google's default is 604800 (one week), and the discovery document types it as a STRING inside `params`. |
+
+#### `event_create` — Create Google Calendar event
+
+Create a timed event on a Google Calendar.
+
+`POST /calendar/v3/calendars/{calendarId}/events` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `calendarId` | yes | `primary` for the connected account's own calendar, or a calendar's id. |
+| `summary` | yes | Title |
+| `description` | no | Can contain HTML. |
+| `location` | no | Free-form text. |
+| `startDateTime` | yes | RFC 3339, e.g. 2026-10-01T14:00:00Z. Include an offset, or pair with a time zone below. |
+| `startTimeZone` | no | IANA name, e.g. America/New_York. Optional when the start time already carries an offset. |
+| `endDateTime` | yes | RFC 3339. Exclusive -- the event ends at, not through, this instant. |
+| `endTimeZone` | no | End time zone |
+| `status` | no | "cancelled" is not offered here -- that is event_delete's job, not a status this action should be able to set on create. |
+| `visibility` | no | Visibility |
+| `transparency` | no | opaque blocks time on the calendar (Busy); transparent does not (Available). |
+| `colorId` | no | An id from the colors endpoint's event section. Leave blank for the calendar's default. |
+
+#### `event_delete` — Delete Google Calendar event
+
+Remove an event from a Google Calendar.
+
+`DELETE /calendar/v3/calendars/{calendarId}/events/{eventId}` · idempotent — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `calendarId` | yes | Calendar ID |
+| `eventId` | yes | From event_create's data.id, or event_list/event_get. |
+
+#### `event_get` — Google Calendar event
+
+Read one event from a Google Calendar.
+
+`GET /calendar/v3/calendars/{calendarId}/events/{eventId}` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `calendarId` | yes | `primary` for the connected account's own calendar, or a calendar's id (usually an email address). |
+| `eventId` | yes | The event's id, as published by another node or by a notification's follow-up list. |
+
+#### `event_list` — Google Calendar events
+
+List events from a Google Calendar, in full or incrementally with a sync token.
+
+`GET /calendar/v3/calendars/{calendarId}/events` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `calendarId` | yes | `primary` for the connected account's own calendar, or a calendar's id. |
+| `syncToken` | no | From a previous list's nextSyncToken. With one set, Google returns ONLY what changed since -- including deletions, as cancelled events. Leave blank for a full list. |
+| `timeMin` | no | RFC 3339 lower bound on an event's END time, e.g. 2026-09-15T00:00:00Z. Not allowed together with a sync token. |
+| `timeMax` | no | RFC 3339 upper bound on an event's START time. Not allowed together with a sync token. |
+| `maxResults` | no | Events per page. Google's default is 250 and its maximum 2500; a nextPageToken means there are more. |
+| `pageToken` | no | From a previous page's nextPageToken. |
+| `singleEvents` | no | Return each occurrence of a recurring event as its own item, rather than the series once. |
+
+#### `event_update` — Update Google Calendar event
+
+Change one or more fields of an existing event. Only the fields provided are touched.
+
+`PATCH /calendar/v3/calendars/{calendarId}/events/{eventId}` · idempotent — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `calendarId` | yes | Calendar ID |
+| `eventId` | yes | From event_create's data.id, or event_list/event_get. |
+| `summary` | no | Title |
+| `description` | no | Description |
+| `location` | no | Location |
+| `startDateTime` | no | RFC 3339. Leave blank to leave the start time unchanged. |
+| `startTimeZone` | no | Start time zone |
+| `endDateTime` | no | RFC 3339. Leave blank to leave the end time unchanged. |
+| `endTimeZone` | no | End time zone |
+| `status` | no | Setting cancelled here has the same effect as event_delete -- offered because PATCH is also Google's documented way to cancel one instance of a recurring event, which event_delete (which removes the whole resource) cannot target. |
+| `visibility` | no | Visibility |
+| `transparency` | no | Show me as |
+| `colorId` | no | Color ID |
+
+### Triggers
+
+#### `events_changed` — Google Calendar change
+
+Start a run when something changes on a watched Google Calendar.
+
+A SUBSCRIPTION: Google Calendar delivers to your endpoint only while a subscription it issued is alive, at most 168 hours at a time. Its expiry is read from the `channel_watch` response (`expiration`); 86400 seconds before it, Google Calendar cannot renew one, so the host stops it (`channel_stop`) and creates it again (`channel_watch`). A lease that lapses is re-listed AND re-subscribed, because notifications during the gap are gone. Every delivery: the token Google Calendar echoes back is compared with the connection's `channelToken` before anything runs.
+
+**You have to set this up with the provider first:**
+
+The host mints a UUID, calls channel_watch with it, its own URL for this trigger and the connection's channelToken, and stores the returned id, resourceId and expiration. Google cannot renew a channel: 86400 seconds before it expires the host calls channel_stop and then channel_watch again. A channel that lapsed is re-listed FIRST (event_list with the stored syncToken; a 410 means list in full) and then re-created, because notifications during the gap are gone. Google delivers with an EMPTY body: the host verifies X-Goog-Channel-Token against the connection's channelToken and injects the X-Goog-* headers as the event, camel-cased as below. The first message on a new channel is `sync` and carries no change.
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Google Calendar has a sandbox. Set a
+node's mode to `fake` and it returns the shape Google Calendar actually publishes — the
+same field names, deterministically — so you can wire the downstream nodes before
+touching an account, a key, or a network.
+
+## This repository is generated
+
+`provider/` is the source. Everything under `packages/` is emitted from it and
+**must not be hand-edited** — CI regenerates and diffs on every push, and the
+next protocol sync destroys anything it finds. See [`AGENTS.md`](AGENTS.md).
+
+## Two namespaces, which do not match on purpose
+
+The repo is `github.com/Fancy-Friends/google-calendar`; the packages publish under
+`particle-academy`. Nothing derives one from the other — the names come from
+weaver's `friends.json` and nowhere else.
+
+## Licence
+
+MIT.

package/art/fancified.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="28" role="img" aria-label="Fancified — built with Fancy UI">
+  <title>Fancified · built with Fancy UI</title>
+  <defs>
+    <linearGradient id="fcdBg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#6d28d9"/>
+      <stop offset=".5" stop-color="#9333ea"/>
+      <stop offset="1" stop-color="#d946ef"/>
+    </linearGradient>
+    <linearGradient id="fcdGloss" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#ffffff" stop-opacity=".30"/>
+      <stop offset=".55" stop-color="#ffffff" stop-opacity="0"/>
+    </linearGradient>
+    <clipPath id="fcdClip"><rect width="128" height="28" rx="7"/></clipPath>
+  </defs>
+  <g clip-path="url(#fcdClip)">
+    <rect width="128" height="28" fill="url(#fcdBg)"/>
+    <rect width="34" height="28" fill="#3b0764" fill-opacity=".5"/>
+    <rect width="128" height="13" fill="url(#fcdGloss)"/>
+    <g fill="#fff">
+      <path transform="translate(17 14)" d="M0 -7 C.6 -2.2 2.2 -.6 7 0 C2.2 .6 .6 2.2 0 7 C-.6 2.2 -2.2 .6 -7 0 C-2.2 -.6 -.6 -2.2 0 -7 Z"/>
+      <path transform="translate(25.5 7.5) scale(.34)" fill-opacity=".85" d="M0 -7 C.6 -2.2 2.2 -.6 7 0 C2.2 .6 .6 2.2 0 7 C-.6 2.2 -2.2 .6 -7 0 C-2.2 -.6 -.6 -2.2 0 -7 Z"/>
+    </g>
+    <text x="81" y="18.5" fill="#ffffff" text-anchor="middle" font-family="'Segoe UI',Verdana,'DejaVu Sans',sans-serif" font-size="12" font-weight="700" letter-spacing=".3">Fancified</text>
+  </g>
+  <rect x=".5" y=".5" width="127" height="27" rx="6.5" fill="none" stroke="#ffffff" stroke-opacity=".22"/>
+</svg>