fancy-gmail-inbox 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fancy_gmail_inbox-0.1.0/.gitignore +24 -0
- fancy_gmail_inbox-0.1.0/CHANGELOG.md +40 -0
- fancy_gmail_inbox-0.1.0/LICENSE +21 -0
- fancy_gmail_inbox-0.1.0/PKG-INFO +160 -0
- fancy_gmail_inbox-0.1.0/README.md +138 -0
- fancy_gmail_inbox-0.1.0/art/fancified.svg +26 -0
- fancy_gmail_inbox-0.1.0/pyproject.toml +87 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/__init__.py +43 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/_fake.py +170 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/_runtime.py +524 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/actions/__init__.py +20 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/actions/label_list.py +80 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/actions/message_get.py +90 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/actions/message_list.py +106 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/actions/thread_get.py +87 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/faker.py +242 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/py.typed +0 -0
- fancy_gmail_inbox-0.1.0/src/fancy_gmail_inbox/service.py +71 -0
- fancy_gmail_inbox-0.1.0/tests/test_faker.py +227 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
node_modules/
|
|
2
|
+
dist/
|
|
3
|
+
vendor/
|
|
4
|
+
.venv/
|
|
5
|
+
__pycache__/
|
|
6
|
+
*.egg-info/
|
|
7
|
+
.pytest_cache/
|
|
8
|
+
.ruff_cache/
|
|
9
|
+
.mypy_cache/
|
|
10
|
+
|
|
11
|
+
# Lockfiles are NOT source of a generated repo.
|
|
12
|
+
#
|
|
13
|
+
# The generator cannot emit one -- a lockfile is the result of a network
|
|
14
|
+
# resolve -- and "a provider repo must be generated and re-generatable" is the
|
|
15
|
+
# constraint the whole estate rests on. At a few hundred repos, a committed
|
|
16
|
+
# lockfile each is a few hundred files nothing can regenerate and a few hundred
|
|
17
|
+
# Dependabot surfaces.
|
|
18
|
+
#
|
|
19
|
+
# The trade is real and worth stating: CI resolves fresh on every run, so an
|
|
20
|
+
# upstream release inside the declared range can break a build with no change
|
|
21
|
+
# here. That is early warning rather than a surprise at publish time, and the
|
|
22
|
+
# ranges are deliberately narrow (>=X <2.0, never a caret on a 0.x).
|
|
23
|
+
composer.lock
|
|
24
|
+
package-lock.json
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Changelog — Gmail Inbox
|
|
2
|
+
|
|
3
|
+
All four packages — `@particle-academy/gmail-inbox-ui`, `@particle-academy/gmail-inbox-js`,
|
|
4
|
+
`particle-academy/gmail-inbox-php` and `fancy-gmail-inbox` — are released together
|
|
5
|
+
under one version. They are generated from one `provider/` definition, so a
|
|
6
|
+
change to it changes all four, and separate version lines would only record
|
|
7
|
+
which of the four somebody remembered to bump.
|
|
8
|
+
|
|
9
|
+
**Write entries HERE**, in the weaver envelope at `providers/gmail-inbox/CHANGELOG.md`,
|
|
10
|
+
then regenerate. This file is the one thing in a release that cannot be
|
|
11
|
+
derived — somebody has to write what changed — but writing it in the
|
|
12
|
+
provider repo would be a hand-edit that `.weaver.json` flags and the next
|
|
13
|
+
sync destroys.
|
|
14
|
+
|
|
15
|
+
## [0.1.0] — 2026-10-01
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- **First release.** `message_list` (search, label filter, pagination),
|
|
20
|
+
`message_get`, `thread_get`, `label_list`. OAuth2 with `gmail.readonly`.
|
|
21
|
+
- **A SEPARATE connector from `gmail`, by design, not a scope widening of
|
|
22
|
+
it.** `gmail.readonly` is a RESTRICTED Google OAuth scope requiring an
|
|
23
|
+
annual CASA security assessment on the app that requests it, and
|
|
24
|
+
Google's verification is per OAUTH CLIENT — attaching it to `gmail`'s
|
|
25
|
+
own client would have put the recurring assessment on every existing
|
|
26
|
+
send-only consumer. A second connector, a second OAuth client, puts it
|
|
27
|
+
only where it is actually needed. Part of the owner's Google Workspace
|
|
28
|
+
commission (Tynn #19) — Fancy's own compliance audit found this before
|
|
29
|
+
any code was written, and the split was decided before this connector
|
|
30
|
+
existed.
|
|
31
|
+
- `message_get` and `thread_get` publish `payload.headers` (From, To,
|
|
32
|
+
Subject, Date, unparsed) and Gmail's own `snippet` preview, but do NOT
|
|
33
|
+
decode the MIME body tree — `payload.parts` can nest arbitrarily for a
|
|
34
|
+
multipart message, and flattening it to plain text/HTML is real parsing
|
|
35
|
+
work this connector does not do yet. The raw `payload` is still
|
|
36
|
+
published for a host that wants to decode it. Noted rather than
|
|
37
|
+
rushed, the same shape as Drive's deferred file upload.
|
|
38
|
+
- Gmail has no sandbox — every read reaches the connected account's real
|
|
39
|
+
mailbox. The faker is the only way to develop against it without doing
|
|
40
|
+
that.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Particle Academy
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: fancy-gmail-inbox
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Gmail Inbox for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK.
|
|
5
|
+
Project-URL: Homepage, https://github.com/Fancy-Friends/gmail-inbox
|
|
6
|
+
Project-URL: Issues, https://github.com/Fancy-Friends/gmail-inbox/issues
|
|
7
|
+
Project-URL: Source, https://github.com/Fancy-Friends/gmail-inbox
|
|
8
|
+
Author: Particle Academy
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: api,connector,email,fancy-flow,gmail_inbox,particle-academy
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# Gmail Inbox
|
|
24
|
+
|
|
25
|
+
[](https://particle.academy)
|
|
26
|
+
|
|
27
|
+
Gmail Inbox for [fancy-flow][flow] — as **four imported, versioned packages**, one
|
|
28
|
+
per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs
|
|
29
|
+
change.
|
|
30
|
+
|
|
31
|
+
[flow]: https://github.com/Particle-Academy/fancy-flow
|
|
32
|
+
|
|
33
|
+
| Runtime | Package | Install |
|
|
34
|
+
|---|---|---|
|
|
35
|
+
| Authoring surface (every host) | `@particle-academy/gmail-inbox-ui` | `npm install @particle-academy/gmail-inbox-ui` |
|
|
36
|
+
| Node | `@particle-academy/gmail-inbox-js` | `npm install @particle-academy/gmail-inbox-js` |
|
|
37
|
+
| PHP 8.4+ | `particle-academy/gmail-inbox-php` | `composer require particle-academy/gmail-inbox-php` |
|
|
38
|
+
| Python 3.11+ | `fancy-gmail-inbox` | `pip install fancy-gmail-inbox` |
|
|
39
|
+
|
|
40
|
+
The `ui` package is the editor surface and is React on every host — a PHP or
|
|
41
|
+
Python project installs it *and* its own runtime package, and never the `js` one.
|
|
42
|
+
|
|
43
|
+
## What it costs you
|
|
44
|
+
|
|
45
|
+
One dependency: `@particle-academy/fancy-connector-core` (or
|
|
46
|
+
`particle-academy/fancy-connector-core` on Composer), which the `js` and `php`
|
|
47
|
+
packages pull in themselves. The Python package has **zero** runtime
|
|
48
|
+
dependencies.
|
|
49
|
+
|
|
50
|
+
**No Gmail Inbox SDK.** Plain HTTP, deliberately: a vendor SDK is third-party code
|
|
51
|
+
subject to the kit's full approval bar, and one per provider is hundreds of
|
|
52
|
+
dependencies nobody is tracking.
|
|
53
|
+
|
|
54
|
+
## Setting it up
|
|
55
|
+
|
|
56
|
+
Everything below is generated from `provider/manifest.json`, so it cannot disagree with what the packages do.
|
|
57
|
+
|
|
58
|
+
### Credentials
|
|
59
|
+
|
|
60
|
+
A Gmail Inbox connection holds 4 values.
|
|
61
|
+
|
|
62
|
+
**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.
|
|
63
|
+
|
|
64
|
+
| Field | Scope | Secret | Where it comes from |
|
|
65
|
+
|---|---|---|---|
|
|
66
|
+
| **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. |
|
|
67
|
+
| **OAuth client secret** | per installation | **secret** | The client secret for the same OAuth app. One value for the whole installation. |
|
|
68
|
+
| **Access token** | per connected account | **secret** | Per connected Google account, and it expires after ONE HOUR. The host refreshes it with the refresh token. |
|
|
69
|
+
| **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. |
|
|
70
|
+
|
|
71
|
+
### Authorising
|
|
72
|
+
|
|
73
|
+
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.
|
|
74
|
+
|
|
75
|
+
- **Authorize URL** — https://accounts.google.com/o/oauth2/v2/auth
|
|
76
|
+
- **Token URL** — https://oauth2.googleapis.com/token
|
|
77
|
+
- **Scopes** — `https://www.googleapis.com/auth/gmail.readonly`
|
|
78
|
+
- **Access token lifetime** — 3600 seconds (1 hours). A host that never refreshes works all afternoon and is broken by morning.
|
|
79
|
+
|
|
80
|
+
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.
|
|
81
|
+
|
|
82
|
+
### The estate
|
|
83
|
+
|
|
84
|
+
**Gmail Inbox has no test estate, and somebody checked.** Everything this connector does is real. Use the faker to build against it.
|
|
85
|
+
|
|
86
|
+
> 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.
|
|
87
|
+
|
|
88
|
+
## What it can do
|
|
89
|
+
|
|
90
|
+
### Actions
|
|
91
|
+
|
|
92
|
+
#### `label_list` — List Gmail labels
|
|
93
|
+
|
|
94
|
+
List every label on the mailbox, system and user-created.
|
|
95
|
+
|
|
96
|
+
`GET /gmail/v1/users/{userId}/labels` · reads only — safe to replay
|
|
97
|
+
|
|
98
|
+
| Input | Required | What it is |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| `userId` | yes | Mailbox |
|
|
101
|
+
|
|
102
|
+
#### `message_get` — Gmail message
|
|
103
|
+
|
|
104
|
+
Read one message's headers and preview. The body's plain/HTML text is NOT decoded -- see the raw payload for that.
|
|
105
|
+
|
|
106
|
+
`GET /gmail/v1/users/{userId}/messages/{id}` · reads only — safe to replay
|
|
107
|
+
|
|
108
|
+
| Input | Required | What it is |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| `userId` | yes | Mailbox |
|
|
111
|
+
| `id` | yes | From message_list, or another node's output. |
|
|
112
|
+
|
|
113
|
+
#### `message_list` — List Gmail messages
|
|
114
|
+
|
|
115
|
+
List message ids matching a search, newest first.
|
|
116
|
+
|
|
117
|
+
`GET /gmail/v1/users/{userId}/messages` · reads only — safe to replay
|
|
118
|
+
|
|
119
|
+
| Input | Required | What it is |
|
|
120
|
+
|---|---|---|
|
|
121
|
+
| `userId` | yes | `me` is the connected account and is almost always what you want. |
|
|
122
|
+
| `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. |
|
|
123
|
+
| `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. |
|
|
124
|
+
| `includeSpamTrash` | no | Include spam and trash |
|
|
125
|
+
| `maxResults` | no | Gmail's own maximum is 500. |
|
|
126
|
+
| `pageToken` | no | From a previous page's nextPageToken. |
|
|
127
|
+
|
|
128
|
+
#### `thread_get` — Gmail thread
|
|
129
|
+
|
|
130
|
+
Read every message in a conversation thread, oldest first.
|
|
131
|
+
|
|
132
|
+
`GET /gmail/v1/users/{userId}/threads/{id}` · reads only — safe to replay
|
|
133
|
+
|
|
134
|
+
| Input | Required | What it is |
|
|
135
|
+
|---|---|---|
|
|
136
|
+
| `userId` | yes | Mailbox |
|
|
137
|
+
| `id` | yes | A message's threadId, from message_list or message_get. |
|
|
138
|
+
|
|
139
|
+
## Run it before you have credentials
|
|
140
|
+
|
|
141
|
+
Every operation ships a **faker**, whether or not Gmail Inbox has a sandbox. Set a
|
|
142
|
+
node's mode to `fake` and it returns the shape Gmail Inbox actually publishes — the
|
|
143
|
+
same field names, deterministically — so you can wire the downstream nodes before
|
|
144
|
+
touching an account, a key, or a network.
|
|
145
|
+
|
|
146
|
+
## This repository is generated
|
|
147
|
+
|
|
148
|
+
`provider/` is the source. Everything under `packages/` is emitted from it and
|
|
149
|
+
**must not be hand-edited** — CI regenerates and diffs on every push, and the
|
|
150
|
+
next protocol sync destroys anything it finds. See [`AGENTS.md`](AGENTS.md).
|
|
151
|
+
|
|
152
|
+
## Two namespaces, which do not match on purpose
|
|
153
|
+
|
|
154
|
+
The repo is `github.com/Fancy-Friends/gmail-inbox`; the packages publish under
|
|
155
|
+
`particle-academy`. Nothing derives one from the other — the names come from
|
|
156
|
+
weaver's `friends.json` and nowhere else.
|
|
157
|
+
|
|
158
|
+
## Licence
|
|
159
|
+
|
|
160
|
+
MIT.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# Gmail Inbox
|
|
2
|
+
|
|
3
|
+
[](https://particle.academy)
|
|
4
|
+
|
|
5
|
+
Gmail Inbox for [fancy-flow][flow] — as **four imported, versioned packages**, one
|
|
6
|
+
per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs
|
|
7
|
+
change.
|
|
8
|
+
|
|
9
|
+
[flow]: https://github.com/Particle-Academy/fancy-flow
|
|
10
|
+
|
|
11
|
+
| Runtime | Package | Install |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| Authoring surface (every host) | `@particle-academy/gmail-inbox-ui` | `npm install @particle-academy/gmail-inbox-ui` |
|
|
14
|
+
| Node | `@particle-academy/gmail-inbox-js` | `npm install @particle-academy/gmail-inbox-js` |
|
|
15
|
+
| PHP 8.4+ | `particle-academy/gmail-inbox-php` | `composer require particle-academy/gmail-inbox-php` |
|
|
16
|
+
| Python 3.11+ | `fancy-gmail-inbox` | `pip install fancy-gmail-inbox` |
|
|
17
|
+
|
|
18
|
+
The `ui` package is the editor surface and is React on every host — a PHP or
|
|
19
|
+
Python project installs it *and* its own runtime package, and never the `js` one.
|
|
20
|
+
|
|
21
|
+
## What it costs you
|
|
22
|
+
|
|
23
|
+
One dependency: `@particle-academy/fancy-connector-core` (or
|
|
24
|
+
`particle-academy/fancy-connector-core` on Composer), which the `js` and `php`
|
|
25
|
+
packages pull in themselves. The Python package has **zero** runtime
|
|
26
|
+
dependencies.
|
|
27
|
+
|
|
28
|
+
**No Gmail Inbox SDK.** Plain HTTP, deliberately: a vendor SDK is third-party code
|
|
29
|
+
subject to the kit's full approval bar, and one per provider is hundreds of
|
|
30
|
+
dependencies nobody is tracking.
|
|
31
|
+
|
|
32
|
+
## Setting it up
|
|
33
|
+
|
|
34
|
+
Everything below is generated from `provider/manifest.json`, so it cannot disagree with what the packages do.
|
|
35
|
+
|
|
36
|
+
### Credentials
|
|
37
|
+
|
|
38
|
+
A Gmail Inbox connection holds 4 values.
|
|
39
|
+
|
|
40
|
+
**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.
|
|
41
|
+
|
|
42
|
+
| Field | Scope | Secret | Where it comes from |
|
|
43
|
+
|---|---|---|---|
|
|
44
|
+
| **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. |
|
|
45
|
+
| **OAuth client secret** | per installation | **secret** | The client secret for the same OAuth app. One value for the whole installation. |
|
|
46
|
+
| **Access token** | per connected account | **secret** | Per connected Google account, and it expires after ONE HOUR. The host refreshes it with the refresh token. |
|
|
47
|
+
| **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. |
|
|
48
|
+
|
|
49
|
+
### Authorising
|
|
50
|
+
|
|
51
|
+
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.
|
|
52
|
+
|
|
53
|
+
- **Authorize URL** — https://accounts.google.com/o/oauth2/v2/auth
|
|
54
|
+
- **Token URL** — https://oauth2.googleapis.com/token
|
|
55
|
+
- **Scopes** — `https://www.googleapis.com/auth/gmail.readonly`
|
|
56
|
+
- **Access token lifetime** — 3600 seconds (1 hours). A host that never refreshes works all afternoon and is broken by morning.
|
|
57
|
+
|
|
58
|
+
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.
|
|
59
|
+
|
|
60
|
+
### The estate
|
|
61
|
+
|
|
62
|
+
**Gmail Inbox has no test estate, and somebody checked.** Everything this connector does is real. Use the faker to build against it.
|
|
63
|
+
|
|
64
|
+
> 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.
|
|
65
|
+
|
|
66
|
+
## What it can do
|
|
67
|
+
|
|
68
|
+
### Actions
|
|
69
|
+
|
|
70
|
+
#### `label_list` — List Gmail labels
|
|
71
|
+
|
|
72
|
+
List every label on the mailbox, system and user-created.
|
|
73
|
+
|
|
74
|
+
`GET /gmail/v1/users/{userId}/labels` · reads only — safe to replay
|
|
75
|
+
|
|
76
|
+
| Input | Required | What it is |
|
|
77
|
+
|---|---|---|
|
|
78
|
+
| `userId` | yes | Mailbox |
|
|
79
|
+
|
|
80
|
+
#### `message_get` — Gmail message
|
|
81
|
+
|
|
82
|
+
Read one message's headers and preview. The body's plain/HTML text is NOT decoded -- see the raw payload for that.
|
|
83
|
+
|
|
84
|
+
`GET /gmail/v1/users/{userId}/messages/{id}` · reads only — safe to replay
|
|
85
|
+
|
|
86
|
+
| Input | Required | What it is |
|
|
87
|
+
|---|---|---|
|
|
88
|
+
| `userId` | yes | Mailbox |
|
|
89
|
+
| `id` | yes | From message_list, or another node's output. |
|
|
90
|
+
|
|
91
|
+
#### `message_list` — List Gmail messages
|
|
92
|
+
|
|
93
|
+
List message ids matching a search, newest first.
|
|
94
|
+
|
|
95
|
+
`GET /gmail/v1/users/{userId}/messages` · reads only — safe to replay
|
|
96
|
+
|
|
97
|
+
| Input | Required | What it is |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| `userId` | yes | `me` is the connected account and is almost always what you want. |
|
|
100
|
+
| `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. |
|
|
101
|
+
| `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. |
|
|
102
|
+
| `includeSpamTrash` | no | Include spam and trash |
|
|
103
|
+
| `maxResults` | no | Gmail's own maximum is 500. |
|
|
104
|
+
| `pageToken` | no | From a previous page's nextPageToken. |
|
|
105
|
+
|
|
106
|
+
#### `thread_get` — Gmail thread
|
|
107
|
+
|
|
108
|
+
Read every message in a conversation thread, oldest first.
|
|
109
|
+
|
|
110
|
+
`GET /gmail/v1/users/{userId}/threads/{id}` · reads only — safe to replay
|
|
111
|
+
|
|
112
|
+
| Input | Required | What it is |
|
|
113
|
+
|---|---|---|
|
|
114
|
+
| `userId` | yes | Mailbox |
|
|
115
|
+
| `id` | yes | A message's threadId, from message_list or message_get. |
|
|
116
|
+
|
|
117
|
+
## Run it before you have credentials
|
|
118
|
+
|
|
119
|
+
Every operation ships a **faker**, whether or not Gmail Inbox has a sandbox. Set a
|
|
120
|
+
node's mode to `fake` and it returns the shape Gmail Inbox actually publishes — the
|
|
121
|
+
same field names, deterministically — so you can wire the downstream nodes before
|
|
122
|
+
touching an account, a key, or a network.
|
|
123
|
+
|
|
124
|
+
## This repository is generated
|
|
125
|
+
|
|
126
|
+
`provider/` is the source. Everything under `packages/` is emitted from it and
|
|
127
|
+
**must not be hand-edited** — CI regenerates and diffs on every push, and the
|
|
128
|
+
next protocol sync destroys anything it finds. See [`AGENTS.md`](AGENTS.md).
|
|
129
|
+
|
|
130
|
+
## Two namespaces, which do not match on purpose
|
|
131
|
+
|
|
132
|
+
The repo is `github.com/Fancy-Friends/gmail-inbox`; the packages publish under
|
|
133
|
+
`particle-academy`. Nothing derives one from the other — the names come from
|
|
134
|
+
weaver's `friends.json` and nowhere else.
|
|
135
|
+
|
|
136
|
+
## Licence
|
|
137
|
+
|
|
138
|
+
MIT.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="128" height="28" role="img" aria-label="Fancified — built with Fancy UI">
|
|
2
|
+
<title>Fancified · built with Fancy UI</title>
|
|
3
|
+
<defs>
|
|
4
|
+
<linearGradient id="fcdBg" x1="0" y1="0" x2="1" y2="1">
|
|
5
|
+
<stop offset="0" stop-color="#6d28d9"/>
|
|
6
|
+
<stop offset=".5" stop-color="#9333ea"/>
|
|
7
|
+
<stop offset="1" stop-color="#d946ef"/>
|
|
8
|
+
</linearGradient>
|
|
9
|
+
<linearGradient id="fcdGloss" x1="0" y1="0" x2="0" y2="1">
|
|
10
|
+
<stop offset="0" stop-color="#ffffff" stop-opacity=".30"/>
|
|
11
|
+
<stop offset=".55" stop-color="#ffffff" stop-opacity="0"/>
|
|
12
|
+
</linearGradient>
|
|
13
|
+
<clipPath id="fcdClip"><rect width="128" height="28" rx="7"/></clipPath>
|
|
14
|
+
</defs>
|
|
15
|
+
<g clip-path="url(#fcdClip)">
|
|
16
|
+
<rect width="128" height="28" fill="url(#fcdBg)"/>
|
|
17
|
+
<rect width="34" height="28" fill="#3b0764" fill-opacity=".5"/>
|
|
18
|
+
<rect width="128" height="13" fill="url(#fcdGloss)"/>
|
|
19
|
+
<g fill="#fff">
|
|
20
|
+
<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"/>
|
|
21
|
+
<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"/>
|
|
22
|
+
</g>
|
|
23
|
+
<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>
|
|
24
|
+
</g>
|
|
25
|
+
<rect x=".5" y=".5" width="127" height="27" rx="6.5" fill="none" stroke="#ffffff" stroke-opacity=".22"/>
|
|
26
|
+
</svg>
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "fancy-gmail-inbox"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Gmail Inbox for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
# 3.11 matches fancy-flow-py's floor: 3.10 reaches end of life on 2026-10-31,
|
|
11
|
+
# and a floor that dies before the package's second release is not a floor.
|
|
12
|
+
requires-python = ">=3.11"
|
|
13
|
+
license = "MIT"
|
|
14
|
+
license-files = ["LICENSE"]
|
|
15
|
+
authors = [{ name = "Particle Academy" }]
|
|
16
|
+
keywords = ["gmail_inbox", "email", "connector", "api", "fancy-flow", "particle-academy"]
|
|
17
|
+
classifiers = [
|
|
18
|
+
"Development Status :: 3 - Alpha",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Topic :: Software Development :: Libraries",
|
|
25
|
+
"Typing :: Typed",
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
# ZERO runtime dependencies, and that is a design constraint rather than an
|
|
29
|
+
# accident. There is no Python twin of fancy-connector-core to depend on, and a
|
|
30
|
+
# vendor SDK is third-party code subject to the kit's full approval bar — one
|
|
31
|
+
# SDK per provider is hundreds of dependencies nobody is tracking. The HTTP is
|
|
32
|
+
# stdlib `urllib`; the HMAC is stdlib `hmac`.
|
|
33
|
+
dependencies = []
|
|
34
|
+
|
|
35
|
+
[project.urls]
|
|
36
|
+
Homepage = "https://github.com/Fancy-Friends/gmail-inbox"
|
|
37
|
+
Issues = "https://github.com/Fancy-Friends/gmail-inbox/issues"
|
|
38
|
+
Source = "https://github.com/Fancy-Friends/gmail-inbox"
|
|
39
|
+
|
|
40
|
+
[dependency-groups]
|
|
41
|
+
# Not optional. A package with no way to run its tests reports green by doing
|
|
42
|
+
# nothing, which is the one defect that hides itself.
|
|
43
|
+
test = ["pytest>=8.0"]
|
|
44
|
+
lint = ["ruff>=0.16"]
|
|
45
|
+
typecheck = ["mypy>=1.11"]
|
|
46
|
+
dev = [{ include-group = "test" }, { include-group = "lint" }, { include-group = "typecheck" }]
|
|
47
|
+
|
|
48
|
+
[tool.hatch.build.targets.wheel]
|
|
49
|
+
packages = ["src/fancy_gmail_inbox"]
|
|
50
|
+
|
|
51
|
+
[tool.hatch.build.targets.sdist]
|
|
52
|
+
include = ["/src", "/tests", "/art", "/README.md", "/CHANGELOG.md", "/LICENSE"]
|
|
53
|
+
|
|
54
|
+
[tool.pytest.ini_options]
|
|
55
|
+
testpaths = ["tests"]
|
|
56
|
+
# importlib mode pairs with src-layout: the working tree is never on sys.path,
|
|
57
|
+
# so the tests exercise the INSTALLED package. Under the default mode a missing
|
|
58
|
+
# py.typed or an unshipped file passes locally and breaks for every user.
|
|
59
|
+
addopts = "--import-mode=importlib -ra"
|
|
60
|
+
|
|
61
|
+
[tool.ruff]
|
|
62
|
+
line-length = 100
|
|
63
|
+
src = ["src", "tests"]
|
|
64
|
+
target-version = "py311"
|
|
65
|
+
|
|
66
|
+
[tool.ruff.lint]
|
|
67
|
+
# `S` — flake8-bandit — is ON, and it is the one addition worth arguing for: this
|
|
68
|
+
# package handles a credential, builds an HMAC, and opens a URL. Security lint
|
|
69
|
+
# belongs on exactly this code.
|
|
70
|
+
#
|
|
71
|
+
# It also makes the two `# noqa: S310` in _runtime.py MEANINGFUL. Without `S`
|
|
72
|
+
# selected, ruff reports them as unused directives (RUF100) and the obvious fix
|
|
73
|
+
# is to delete them — which quietly removes a security annotation because a
|
|
74
|
+
# linter was not looking for it.
|
|
75
|
+
select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "N", "C4", "PT", "S"]
|
|
76
|
+
|
|
77
|
+
[tool.ruff.lint.per-file-ignores]
|
|
78
|
+
# pytest's whole idiom is bare `assert`. S101 would fail every test file.
|
|
79
|
+
"tests/*" = ["S101"]
|
|
80
|
+
|
|
81
|
+
[tool.mypy]
|
|
82
|
+
python_version = "3.11"
|
|
83
|
+
packages = ["fancy_gmail_inbox"]
|
|
84
|
+
mypy_path = "src"
|
|
85
|
+
strict = true
|
|
86
|
+
disallow_any_expr = false
|
|
87
|
+
disallow_any_explicit = false
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# GENERATED FILE — do not edit.
|
|
2
|
+
#
|
|
3
|
+
# Emitted from provider/manifest.json by weaver's generator.
|
|
4
|
+
# A hand-edit here is destroyed by the next protocol sync, which is worse than
|
|
5
|
+
# being rejected, because it works until it silently does not. Fix
|
|
6
|
+
# provider/manifest.json (or weaver's template/) and regenerate:
|
|
7
|
+
#
|
|
8
|
+
# npm run provider -- gmail_inbox
|
|
9
|
+
|
|
10
|
+
"""Gmail Inbox for Python.
|
|
11
|
+
|
|
12
|
+
The service descriptor, its faker, its delivery contract, and one function
|
|
13
|
+
per operation — plain HTTP on the stdlib, no vendor SDK and no runtime
|
|
14
|
+
dependency.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from ._fake import FakeValues
|
|
20
|
+
from .actions.label_list import label_list
|
|
21
|
+
from .actions.message_get import message_get
|
|
22
|
+
from .actions.message_list import message_list
|
|
23
|
+
from .actions.thread_get import thread_get
|
|
24
|
+
from .faker import respond
|
|
25
|
+
from .service import BASE_URLS, CONNECTOR_API_VERSION, REQUIRES, SANDBOX, SERVICE, TITLE, descriptor
|
|
26
|
+
|
|
27
|
+
__version__ = "0.1.0"
|
|
28
|
+
|
|
29
|
+
__all__ = [
|
|
30
|
+
"BASE_URLS",
|
|
31
|
+
"CONNECTOR_API_VERSION",
|
|
32
|
+
"REQUIRES",
|
|
33
|
+
"SANDBOX",
|
|
34
|
+
"SERVICE",
|
|
35
|
+
"TITLE",
|
|
36
|
+
"FakeValues",
|
|
37
|
+
"descriptor",
|
|
38
|
+
"label_list",
|
|
39
|
+
"message_get",
|
|
40
|
+
"message_list",
|
|
41
|
+
"respond",
|
|
42
|
+
"thread_get",
|
|
43
|
+
]
|