@particle-academy/gmail-inbox-js 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog — Gmail Inbox
+
+All four packages — `@particle-academy/gmail-inbox-ui`, `@particle-academy/gmail-inbox-js`,
+`particle-academy/gmail-inbox-php` and `fancy-gmail-inbox` — are released together
+under one version. They are generated from one `provider/` definition, so a
+change to it changes all four, and separate version lines would only record
+which of the four somebody remembered to bump.
+
+**Write entries HERE**, in the weaver envelope at `providers/gmail-inbox/CHANGELOG.md`,
+then regenerate. This file is the one thing in a release that cannot be
+derived — somebody has to write what changed — but writing it in the
+provider repo would be a hand-edit that `.weaver.json` flags and the next
+sync destroys.
+
+## [0.2.0] — 2026-11-08
+
+### Added
+
+- **`message_received`: a trigger for new Gmail mail, still read-only**
+  (`gmail.readonly` is the only scope). `mailbox_watch` makes Gmail publish
+  mailbox changes to a Cloud Pub/Sub topic in YOUR app's own Google Cloud
+  project, and a push subscription delivers each change to your host.
+  - **Every push is verified before anything reads it.** It carries a
+    Google-signed token in `Authorization`, checked for Google's issuer, the
+    subscription's audience (`pushAudience`), and the push service account
+    with `email_verified` true (`pushServiceAccount`). The service-account
+    check is what refuses a stranger's subscription aimed at your URL.
+  - **Routing.** The Pub/Sub envelope is unwrapped, then the push is routed by
+    `emailAddress`, only after verification. One topic serves every mailbox.
+  - **What arrives.** A push carries only the mailbox's NEW position, so the
+    trigger reads `history.list` from the cursor YOUR HOST stored. It reads
+    every page and publishes the changes under `history` with `cursor: {used,
+    next}`. Your host persists `cursor.next` when a run succeeds.
+  - **Received mail only, by default:** `labelId: INBOX` and `historyTypes:
+    messageAdded`, so no sent mail or drafts. Widen either in the trigger's
+    config.
+  - **A lapsed cursor** (Gmail's 404) or more than 20 pages fails by name, as
+    `cursor-expired` or `cursor-overflow`. Each carries a bounded resync query
+    (`newer_than:7d`; `resyncWindowDays` sets it, default 7). Watch again
+    first, then list with that query. The mailbox is never fully re-pulled.
+  - **The watch is a lease:** Gmail's `expiration` is in epoch milliseconds,
+    renewed by watching again, a day early. Google requires at least once
+    every 7 days and recommends daily.
+  - **Read state is never changed.**
+
+  New actions: `mailbox_watch`, `mailbox_stop` and `history_list`. New
+  credentials: `pushAudience` and `pushServiceAccount`, needed only for the
+  trigger. Requires fancy-connector-core 0.14.0.
+
+## [0.1.0] — 2026-10-01
+
+### Added
+
+- **First release.** `message_list` (search, label filter, pagination),
+  `message_get`, `thread_get`, `label_list`. OAuth2 with `gmail.readonly`.
+- **A SEPARATE connector from `gmail`, by design, not a scope widening of
+  it.** `gmail.readonly` is a RESTRICTED Google OAuth scope requiring an
+  annual CASA security assessment on the app that requests it, and
+  Google's verification is per OAUTH CLIENT — attaching it to `gmail`'s
+  own client would have put the recurring assessment on every existing
+  send-only consumer. A second connector, a second OAuth client, puts it
+  only where it is actually needed. Part of the owner's Google Workspace
+  commission (Tynn #19) — Fancy's own compliance audit found this before
+  any code was written, and the split was decided before this connector
+  existed.
+- `message_get` and `thread_get` publish `payload.headers` (From, To,
+  Subject, Date, unparsed) and Gmail's own `snippet` preview, but do NOT
+  decode the MIME body tree — `payload.parts` can nest arbitrarily for a
+  multipart message, and flattening it to plain text/HTML is real parsing
+  work this connector does not do yet. The raw `payload` is still
+  published for a host that wants to decode it. Noted rather than
+  rushed, the same shape as Drive's deferred file upload.
+- Gmail has no sandbox — every read reaches the connected account's real
+  mailbox. The faker is the only way to develop against it without doing
+  that.

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,190 @@
-# @particle-academy/gmail-inbox-js
+# Gmail Inbox
 
-**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/gmail-inbox by its `publish.yml` workflow with provenance, and this version is deprecated the moment it lands.
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
+Gmail Inbox 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/gmail-inbox-ui` | `npm install @particle-academy/gmail-inbox-ui` |
+| Node | `@particle-academy/gmail-inbox-js` | `npm install @particle-academy/gmail-inbox-js` |
+| PHP 8.4+ | `particle-academy/gmail-inbox-php` | `composer require particle-academy/gmail-inbox-php` |
+| Python 3.11+ | `fancy-gmail-inbox` | `pip install fancy-gmail-inbox` |
+
+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 Gmail Inbox 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 Gmail Inbox connection holds 6 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 | A DIFFERENT OAuth app than `gmail`'s, from Google Cloud Console -> APIs & Services -> Credentials. This one requests a restricted scope and carries Google's annual CASA assessment; `gmail`'s does not. Do not reuse the same client for both. |
+| **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. |
+| **Push audience** *(optional)* | per installation | not secret | The audience set on the Pub/Sub PUSH subscription (normally the endpoint URL your host mounts for message_received). Every push's Google-signed token must name it; an unchecked audience accepts any token Google signs for anyone. Needed only for the message_received trigger. |
+| **Push service account** *(optional)* | per installation | not secret | The service account the push subscription authenticates as (its email). Every push's token must be for exactly this account: a stranger's subscription aimed at your URL carries a token Google signed correctly, and only this check refuses it. Needed only for message_received. |
+
+### Authorising
+
+Gmail Inbox 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/gmail.readonly`
+- **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
+
+**Gmail Inbox has no test estate, and somebody checked.** Everything this connector does is real. Use the faker to build against it.
+
+> Gmail has no sandbox. Every read reaches the connected account's real mail. The faker is the only way to develop against it without touching a real mailbox.
+
+## What it can do
+
+### Actions
+
+#### `history_list` — List Gmail mailbox history
+
+List what changed in a mailbox since a history id: messages added or deleted, labels added or removed.
+
+`GET /gmail/v1/users/{userId}/history` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `userId` | yes | `me` is the connected account and is almost always what you want. |
+| `startHistoryId` | yes | Changes AFTER this id. Take it from a watch, a message, or a previous list's historyId. Out of Gmail's range (typically older than a week) it answers 404. |
+| `historyTypes` | no | Blank: every kind. messageAdded is new mail (and sent mail and drafts, unless a label narrows it). |
+| `labelId` | no | Only messages with this label, e.g. INBOX for received mail. |
+| `maxResults` | no | Gmail's own maximum is 500. |
+| `pageToken` | no | From a previous page's nextPageToken. |
+
+#### `label_list` — List Gmail labels
+
+List every label on the mailbox, system and user-created.
+
+`GET /gmail/v1/users/{userId}/labels` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `userId` | yes | Mailbox |
+
+#### `mailbox_stop` — Stop watching a Gmail mailbox
+
+Turn off push notifications for a mailbox.
+
+`POST /gmail/v1/users/{userId}/stop` · idempotent — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `userId` | yes | `me` is the connected account and is almost always what you want. |
+
+#### `mailbox_watch` — Watch a Gmail mailbox
+
+Start (or renew) push notifications for a mailbox to a Cloud Pub/Sub topic.
+
+`POST /gmail/v1/users/{userId}/watch` · idempotent — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `userId` | yes | `me` is the connected account and is almost always what you want. |
+| `topicName` | yes | The full topic name, in YOUR app's own Google Cloud project: Google requires its project id to match the project whose OAuth client makes this call. One topic serves every mailbox. |
+| `labelIds` | no | Comma-separated label ids to restrict notifications to (e.g. INBOX). Blank: every change is pushed. |
+| `labelFilterBehavior` | no | Whether the labels above are the ONLY ones notified (include) or the ones NOT notified (exclude). |
+
+#### `message_get` — Gmail message
+
+Read one message's headers and preview. The body's plain/HTML text is NOT decoded -- see the raw payload for that.
+
+`GET /gmail/v1/users/{userId}/messages/{id}` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `userId` | yes | Mailbox |
+| `id` | yes | From message_list, or another node's output. |
+
+#### `message_list` — List Gmail messages
+
+List message ids matching a search, newest first.
+
+`GET /gmail/v1/users/{userId}/messages` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `userId` | yes | `me` is the connected account and is almost always what you want. |
+| `q` | no | Gmail's own search syntax, exactly as typed into the Gmail search box -- e.g. "from:ada@example.test has:attachment newer_than:7d". Leave blank to list everything. |
+| `labelId` | no | Only messages with this label -- e.g. INBOX, or a label_list id. Gmail's own query parameter accepts several, repeated; this connector offers one for now -- combine more in the search field above instead, using Gmail's own label: search operator. |
+| `includeSpamTrash` | no | Include spam and trash |
+| `maxResults` | no | Gmail's own maximum is 500. |
+| `pageToken` | no | From a previous page's nextPageToken. |
+
+#### `thread_get` — Gmail thread
+
+Read every message in a conversation thread, oldest first.
+
+`GET /gmail/v1/users/{userId}/threads/{id}` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `userId` | yes | Mailbox |
+| `id` | yes | A message's threadId, from message_list or message_get. |
+
+### Triggers
+
+#### `message_received` — Gmail message received
+
+Start when new mail arrives in a watched mailbox, with every new message since the last run.
+
+A SUBSCRIPTION: Gmail Inbox 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 `mailbox_watch` response (`expiration`); 86400 seconds before it, the host renews it (`mailbox_watch`). A lease that lapses is re-listed AND re-subscribed, because notifications during the gap are gone. Every delivery: the signature is verified before anything runs. The delivery only names what arrived, so the run's first step reads it: `history_list` with , published under `history`. A failed read fails the run.
+
+**You have to set this up with the provider first:**
+
+In YOUR app's Google Cloud project (the one owning the OAuth client): create a Pub/Sub topic, grant publish on it to gmail-api-push@system.gserviceaccount.com, and create a PUSH subscription to the route your host mounts for this trigger, with authentication on (a service account you choose; the endpoint URL as the audience). Put that audience and service account on the connection as pushAudience and pushServiceAccount, and fetch Google's signing keys for verification. Then call mailbox_watch with the topic for each mailbox and store its historyId as the trigger's cursor (startHistoryId); renew the watch daily. ONE topic serves every mailbox: route each push by its emailAddress, and only after the token verifies, to a mailbox you watched; drop an unmapped address with a 2xx. Persist cursor.next when a run succeeds. On cursor-expired or cursor-overflow, watch again for a fresh historyId FIRST, then list with message_list using the resyncQuery, and match it against the mail you already handled. This trigger never changes read state.
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Gmail Inbox has a sandbox. Set a
+node's mode to `fake` and it returns the shape Gmail Inbox 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/gmail-inbox`; 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>