@superdurable/connector-google-gmail 0.0.0-stage → 0.1.0
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.
- package/LICENSE +21 -0
- package/README.md +36 -2
- package/dex-connector.json +110 -0
- package/dist/chunk-C6LCJ6ZY.js +1214 -0
- package/dist/connection-ce8JHjE8.d.cts +99 -0
- package/dist/connection-ce8JHjE8.d.ts +99 -0
- package/dist/index.cjs +1265 -0
- package/dist/index.d.cts +275 -0
- package/dist/index.d.ts +275 -0
- package/dist/index.js +94 -0
- package/dist/mock/index.cjs +402 -0
- package/dist/mock/index.d.cts +71 -0
- package/dist/mock/index.d.ts +71 -0
- package/dist/mock/index.js +173 -0
- package/package.json +70 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Super Durable
|
|
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.
|
package/README.md
CHANGED
|
@@ -1,3 +1,37 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Gmail connector for TypeScript
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Install the connector in a Dex application:
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install @superdurable/connector-google-gmail @superdurable/dex
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
This package provides typed `getMessage`, `sendMessage`, and `replyToMessage` operations. Its operation identities, branches, retry policy, authorization fields, and mock cases mirror [the manifest](https://github.com/superdurable/dex-connectors-library/blob/main/connectors/google/gmail/connector.yaml). Gmail Triggers and the thread-reply Trigger runner currently belong to the Go connector.
|
|
10
|
+
|
|
11
|
+
Send and reply recipients are validated as mailboxes and returned in canonical header form, such as `<ada@example.com>` or `"Ada" <ada@example.com>`.
|
|
12
|
+
|
|
13
|
+
## Configure a connection
|
|
14
|
+
|
|
15
|
+
In Dex Web **Connections**, create a Google Gmail connection with the static name used by the application's `ConnectionName` constant. The application loads project settings through the Connector SDK and resolves credentials during each Step attempt. Refreshes update encrypted project storage or Dex Web's private local `connections.json`; tokens and service-account keys must never be put in Flow input or persisted state.
|
|
16
|
+
|
|
17
|
+
For personal Gmail or ordinary Workspace accounts, select **Google OAuth**. In [Google Cloud Credentials](https://console.cloud.google.com/apis/credentials), create a Web application, enable the Gmail API, and add the exact redirect URI shown by Dex Web. Configure the consent audience, test users when the app is in Testing, and the scopes shown by Dex Web. Paste the client ID and client secret into the connection form; Dex Web derives the verified primary email and stores the access and refresh tokens after consent.
|
|
18
|
+
|
|
19
|
+
For administrator-managed Workspace delegation, use [Google Cloud service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) to create a service account and download its JSON key. In [Workspace domain-wide delegation](https://admin.google.com/ac/owl/domainwidedelegation), authorize that account's OAuth client ID for the Gmail readonly and send scopes. Put the JSON key and one managed mailbox in the connection form. The connector mints short-lived delegated tokens and uses that mailbox as the sender.
|
|
20
|
+
|
|
21
|
+
`sendMessage` and `replyToMessage` claim a Dex heartbeat checkpoint before POST and search Sent Mail under a run-specific RFC `Message-ID` after an ambiguous send. A confirmed match returns `sent`; a miss retries read-back within the manifest budget without another POST. A conclusive 429 or 503 can permit another attempt after its own read-back; delayed Sent Mail indexing after a 503 can still cause duplicate delivery. An accepted 2xx never resends merely because its response body is unusable.
|
|
22
|
+
|
|
23
|
+
## Run the example
|
|
24
|
+
|
|
25
|
+
[The Gmail Flow examples](https://github.com/superdurable/dex-connectors-library/tree/main/connectors/google/gmail/typescript/examples/gmail-flow) contain one Flow per operation, one Worker, a read starter, and a real Dex integration test. Their static connection name is `gmail-inbox`. The Worker setup below is from the [runnable entrypoint](https://github.com/superdurable/dex-connectors-library/blob/main/connectors/google/gmail/typescript/examples/gmail-flow/main.ts):
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
const project = await loadFromEnvironment();
|
|
29
|
+
const connection = newProjectConnection(project, ConnectionName);
|
|
30
|
+
const registry = new Registry([new GmailReadFlow(connection), new GmailSendFlow(connection), new GmailReplyFlow(connection)]);
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Run `npm run example:worker` after configuring the named connection, then `npm run example:start -- GMAIL_MESSAGE_ID` to start a read. `npm run test:integration` exercises read, send, reply, retry, optional branch failure, and the send checkpoint with a fake provider on a real Dex server. No live Google authorization or delivery has been tested.
|
|
34
|
+
|
|
35
|
+
Dex CLI v1.28.0 rendered all three example Flows as valid FDG 2.0 graphs with no diagnostics. The published package includes the manifest-derived `dex-connector.json` marker, which supplies connector identity, named branches, and Dex Web connection configuration metadata.
|
|
36
|
+
|
|
37
|
+
Flows that route from a local Step into a connector Step need Dex CLI v1.28.1 for strict FDG visualization ([issue #362](https://github.com/superdurable/dex-connectors-library/issues/362)). The three examples here start at connector Steps and pass with v1.28.0.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
{
|
|
2
|
+
"connectorId": "gmail",
|
|
3
|
+
"releaseTag": "connectors/google/gmail/v0.24.1",
|
|
4
|
+
"package": {
|
|
5
|
+
"ecosystem": "npm",
|
|
6
|
+
"name": "@superdurable/connector-google-gmail",
|
|
7
|
+
"version": "0.1.0"
|
|
8
|
+
},
|
|
9
|
+
"factories": [
|
|
10
|
+
{
|
|
11
|
+
"name": "newGetMessageStep",
|
|
12
|
+
"kind": "query",
|
|
13
|
+
"operationId": "getMessage",
|
|
14
|
+
"fields": {
|
|
15
|
+
"stepType": "stepType",
|
|
16
|
+
"annotations": "annotations",
|
|
17
|
+
"connectionName": "connectionName",
|
|
18
|
+
"resultAttribute": "resultAttribute"
|
|
19
|
+
},
|
|
20
|
+
"branches": [
|
|
21
|
+
{
|
|
22
|
+
"id": "read",
|
|
23
|
+
"field": "read",
|
|
24
|
+
"optional": false
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"id": "notFound",
|
|
28
|
+
"field": "notFound",
|
|
29
|
+
"optional": true
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
"id": "providerRejected",
|
|
33
|
+
"field": "providerRejected",
|
|
34
|
+
"optional": true
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
"id": "invalidResponse",
|
|
38
|
+
"field": "invalidResponse",
|
|
39
|
+
"optional": true
|
|
40
|
+
},
|
|
41
|
+
{
|
|
42
|
+
"id": "defect",
|
|
43
|
+
"field": "defect",
|
|
44
|
+
"optional": true
|
|
45
|
+
}
|
|
46
|
+
]
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
"name": "newSendMessageStep",
|
|
50
|
+
"kind": "mutation",
|
|
51
|
+
"operationId": "sendMessage",
|
|
52
|
+
"fields": {
|
|
53
|
+
"stepType": "stepType",
|
|
54
|
+
"annotations": "annotations",
|
|
55
|
+
"connectionName": "connectionName",
|
|
56
|
+
"resultAttribute": "resultAttribute"
|
|
57
|
+
},
|
|
58
|
+
"branches": [
|
|
59
|
+
{
|
|
60
|
+
"id": "sent",
|
|
61
|
+
"field": "sent",
|
|
62
|
+
"optional": false
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
"id": "providerRejected",
|
|
66
|
+
"field": "providerRejected",
|
|
67
|
+
"optional": true
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
"id": "defect",
|
|
71
|
+
"field": "defect",
|
|
72
|
+
"optional": true
|
|
73
|
+
}
|
|
74
|
+
]
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"name": "newReplyToMessageStep",
|
|
78
|
+
"kind": "mutation",
|
|
79
|
+
"operationId": "replyToMessage",
|
|
80
|
+
"fields": {
|
|
81
|
+
"stepType": "stepType",
|
|
82
|
+
"annotations": "annotations",
|
|
83
|
+
"connectionName": "connectionName",
|
|
84
|
+
"resultAttribute": "resultAttribute"
|
|
85
|
+
},
|
|
86
|
+
"branches": [
|
|
87
|
+
{
|
|
88
|
+
"id": "sent",
|
|
89
|
+
"field": "sent",
|
|
90
|
+
"optional": false
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
"id": "providerRejected",
|
|
94
|
+
"field": "providerRejected",
|
|
95
|
+
"optional": true
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
"id": "invalidResponse",
|
|
99
|
+
"field": "invalidResponse",
|
|
100
|
+
"optional": true
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
"id": "defect",
|
|
104
|
+
"field": "defect",
|
|
105
|
+
"optional": true
|
|
106
|
+
}
|
|
107
|
+
]
|
|
108
|
+
}
|
|
109
|
+
]
|
|
110
|
+
}
|