fancy-gmail 0.2.0__tar.gz → 0.3.0__tar.gz

{fancy_gmail-0.2.0 → fancy_gmail-0.3.0}/CHANGELOG.md

@@ -7,6 +7,40 @@ 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.3.0] — 2026-08-24
+
+### Added
+
+- **The README now says how to SET THIS CONNECTOR UP**, in the package itself.
+
+Until now it explained what the four packages are, what they cost and why the
+repo is generated — and said nothing about credentials, scopes, sandboxes or
+operations. Somebody who installed it could not learn from it which credentials
+a connection needs, where a human GETS them, which scopes to request, or what
+the connector can actually do. All of that was already in the definition; the
+one document a consumer reads was the one that omitted everything actionable.
+
+The new **Setting it up** section carries:
+
+- every credential, with the text saying where the value comes from, whether it
+  is **per installation** or **per connected account**, and whether it is secret;
+- the OAuth authorize and token URLs and the exact scopes, verbatim;
+- the access-token lifetime, and where refresh tokens ROTATE, the two things a
+  host must not do — retry a failed refresh, or refresh concurrently — because a
+  replay revokes the entire grant and nothing in the failure says why;
+- the estate in this provider's own terms, including the cases where a
+  successful-looking run reaches nobody, or reaches the real one;
+- every action and trigger with its method, path, inputs, and whether it is safe
+  to replay;
+- a trigger's provider-side setup, which nobody can derive from anything else.
+
+It is **generated from `provider/manifest.json`**, so it cannot drift from what
+the packages do — which is the point at a few hundred providers, where a
+hand-written setup section is a few hundred documents going quietly stale.
+
+No code changed. This release exists because a registry and an installing agent
+read the PUBLISHED artifact, and the artifact carried the old README.
+
 ## [0.2.0] — 2026-08-24
 
 ### Changed
@@ -92,3 +126,4 @@ which is why `refreshToken` is required rather than optional.
 
 [0.1.0]: https://github.com/Fancy-Friends/gmail/releases/tag/v0.1.0
 [0.2.0]: https://github.com/Fancy-Friends/gmail/releases/tag/v0.2.0
+[0.3.0]: https://github.com/Fancy-Friends/gmail/releases/tag/v0.3.0

fancy_gmail-0.3.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: fancy-gmail
+Version: 0.3.0
+Summary: Gmail for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK.
+Project-URL: Homepage, https://github.com/Fancy-Friends/gmail
+Project-URL: Issues, https://github.com/Fancy-Friends/gmail/issues
+Project-URL: Source, https://github.com/Fancy-Friends/gmail
+Author: Particle Academy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,connector,email,fancy-flow,gmail,particle-academy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Gmail
+
+Gmail 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-ui` | `npm install @particle-academy/gmail-ui` |
+| Node | `@particle-academy/gmail-js` | `npm install @particle-academy/gmail-js` |
+| PHP 8.4+ | `particle-academy/gmail-php` | `composer require particle-academy/gmail-php` |
+| Python 3.11+ | `fancy-gmail` | `pip install fancy-gmail` |
+
+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 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 connection holds 4 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. |
+
+### Authorising
+
+Gmail 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.send`
+- **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 has no test estate, and somebody checked.** Everything this connector does is real. Use the faker to build against it.
+
+> Gmail has no sandbox. A send is a real email to a real address -- point this at your own inbox before pointing it at anybody else's. The faker is the only way to develop against it without delivering mail.
+
+## What it can do
+
+### Actions
+
+#### `message_send` — Gmail message
+
+Send an email from a connected Gmail account.
+
+`POST /gmail/v1/users/{userId}/messages/send` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `userId` | yes | Whose mailbox to send from. `me` is the connected account and is almost always what you want. |
+| `to` | yes | Recipient address. Several can be given, comma separated, exactly as an email client accepts them. |
+| `cc` | no | Copied recipients, comma separated. Left empty the header is omitted entirely rather than sent blank. |
+| `subject` | yes | Subject |
+| `body` | yes | The plain-text body. It is sent as text/plain; UTF-8, so accented characters and emoji survive. |
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Gmail has a sandbox. Set a
+node's mode to `fake` and it returns the shape Gmail 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`; 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.

fancy_gmail-0.3.0/README.md

@@ -0,0 +1,103 @@
+# Gmail
+
+Gmail 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-ui` | `npm install @particle-academy/gmail-ui` |
+| Node | `@particle-academy/gmail-js` | `npm install @particle-academy/gmail-js` |
+| PHP 8.4+ | `particle-academy/gmail-php` | `composer require particle-academy/gmail-php` |
+| Python 3.11+ | `fancy-gmail` | `pip install fancy-gmail` |
+
+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 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 connection holds 4 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. |
+
+### Authorising
+
+Gmail 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.send`
+- **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 has no test estate, and somebody checked.** Everything this connector does is real. Use the faker to build against it.
+
+> Gmail has no sandbox. A send is a real email to a real address -- point this at your own inbox before pointing it at anybody else's. The faker is the only way to develop against it without delivering mail.
+
+## What it can do
+
+### Actions
+
+#### `message_send` — Gmail message
+
+Send an email from a connected Gmail account.
+
+`POST /gmail/v1/users/{userId}/messages/send` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `userId` | yes | Whose mailbox to send from. `me` is the connected account and is almost always what you want. |
+| `to` | yes | Recipient address. Several can be given, comma separated, exactly as an email client accepts them. |
+| `cc` | no | Copied recipients, comma separated. Left empty the header is omitted entirely rather than sent blank. |
+| `subject` | yes | Subject |
+| `body` | yes | The plain-text body. It is sent as text/plain; UTF-8, so accented characters and emoji survive. |
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Gmail has a sandbox. Set a
+node's mode to `fake` and it returns the shape Gmail 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`; 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.

{fancy_gmail-0.2.0 → fancy_gmail-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fancy-gmail"
-version = "0.2.0"
+version = "0.3.0"
 description = "Gmail for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK."
 readme = "README.md"
 # 3.11 matches fancy-flow-py's floor: 3.10 reaches end of life on 2026-10-31,

{fancy_gmail-0.2.0 → fancy_gmail-0.3.0}/src/fancy_gmail/__init__.py

@@ -21,7 +21,7 @@ from .actions.message_send import message_send
 from .faker import respond
 from .service import BASE_URLS, CONNECTOR_API_VERSION, REQUIRES, SANDBOX, SERVICE, TITLE, descriptor
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "BASE_URLS",

fancy_gmail-0.2.0/PKG-INFO

@@ -1,73 +0,0 @@
-Metadata-Version: 2.5
-Name: fancy-gmail
-Version: 0.2.0
-Summary: Gmail for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK.
-Project-URL: Homepage, https://github.com/Fancy-Friends/gmail
-Project-URL: Issues, https://github.com/Fancy-Friends/gmail/issues
-Project-URL: Source, https://github.com/Fancy-Friends/gmail
-Author: Particle Academy
-License-Expression: MIT
-License-File: LICENSE
-Keywords: api,connector,email,fancy-flow,gmail,particle-academy
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# Gmail
-
-Gmail 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-ui` | `npm install @particle-academy/gmail-ui` |
-| Node | `@particle-academy/gmail-js` | `npm install @particle-academy/gmail-js` |
-| PHP 8.4+ | `particle-academy/gmail-php` | `composer require particle-academy/gmail-php` |
-| Python 3.11+ | `fancy-gmail` | `pip install fancy-gmail` |
-
-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 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.
-
-## Run it before you have credentials
-
-Every operation ships a **faker**, whether or not Gmail has a sandbox. Set a
-node's mode to `fake` and it returns the shape Gmail 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`; 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.

fancy_gmail-0.2.0/README.md

@@ -1,51 +0,0 @@
-# Gmail
-
-Gmail 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-ui` | `npm install @particle-academy/gmail-ui` |
-| Node | `@particle-academy/gmail-js` | `npm install @particle-academy/gmail-js` |
-| PHP 8.4+ | `particle-academy/gmail-php` | `composer require particle-academy/gmail-php` |
-| Python 3.11+ | `fancy-gmail` | `pip install fancy-gmail` |
-
-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 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.
-
-## Run it before you have credentials
-
-Every operation ships a **faker**, whether or not Gmail has a sandbox. Set a
-node's mode to `fake` and it returns the shape Gmail 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`; 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.