@superdurable/connector-google-gmail 0.2.1 → 0.3.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/README.md +14 -2
- package/dex-connector.json +27 -3
- package/dist/{chunk-KVNIQW5Y.js → chunk-PW3NTBVH.js} +466 -23
- package/dist/index.cjs +468 -22
- package/dist/index.d.cts +218 -6
- package/dist/index.d.ts +218 -6
- package/dist/index.js +39 -1
- package/dist/mock/index.cjs +75 -2
- package/dist/mock/index.js +1 -1
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -6,12 +6,12 @@ Install the connector in a Dex application:
|
|
|
6
6
|
npm install @superdurable/connector-google-gmail @superdurable/dex
|
|
7
7
|
```
|
|
8
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).
|
|
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). From 0.3.0 it also provides the `messageReceived` and `replyReceived` Triggers and their shared, ordered runner, at parity with the Go connector.
|
|
10
10
|
|
|
11
11
|
The checked-in `src/generated/` contracts come from `connector.yaml` and the
|
|
12
12
|
Go operation structs. Run `go run ./cmd/connectorctl generate --lang typescript connectors/google/gmail/connector.yaml` from the repository root after either source changes. `src/models.ts` keeps credential requirements specific to Google OAuth and Workspace delegation, plus the public non-null send recipient arrays. `src/steps.ts` delegates to generated factories while requiring `GmailConnection` at compile time; `src/mock/index.ts` re-exports matching generated scenarios and validates send scenarios against the public result type. `src/project.ts` keeps the refresh codec and public connection constructor.
|
|
13
13
|
|
|
14
|
-
Version 0.
|
|
14
|
+
Version 0.3.0 requires Connector SDK 0.11.0. Generated private and shared
|
|
15
15
|
credential decoders validate project material, and the refresh driver reads
|
|
16
16
|
generated manifest grants with Gmail-specific delegation checks. Each token
|
|
17
17
|
exchange honors the declared `tokenExchangeTimeout`, as the Go driver does.
|
|
@@ -29,6 +29,18 @@ For administrator-managed Workspace delegation, use [Google Cloud service accoun
|
|
|
29
29
|
|
|
30
30
|
`sendMessage` and `replyToMessage` use synchronous Execute and claim a Dex heartbeat checkpoint before POST. They 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 a failure proven to precede dispatch can permit another POST. A 503 may have been processed, so like any 5xx it keeps the claim and later attempts only read back. An accepted 2xx never resends merely because its response body is unusable.
|
|
31
31
|
|
|
32
|
+
## Triggers
|
|
33
|
+
|
|
34
|
+
`messageReceived` receives a matching message that begins a Gmail thread and `replyReceived` a matching reply in an existing thread. Both poll the newest inbox page (`pollPageSize` messages, `labelIds=INBOX`, plus the binding's optional Gmail `searchQuery`) every `pollInterval`, read each new message's metadata, and emit a metadata-only `MessageEvent` (`primaryEmail`, `messageId`, `threadId`, `from`, `subject`, `snippet`, `receivedAt`, `isReply`) whose event ID is the Gmail message ID. The binding's `messageMatcher` or `replyMatcher` requires a case-insensitive `messageContains` substring of the subject or snippet and an optional `senderEmails` allowlist.
|
|
35
|
+
|
|
36
|
+
- `newProjectMessageTriggerRunner(project, connectionName, { messageReceivedRoutes, replyReceivedRoutes }, options)` loads each binding's saved configuration and wraps its target in the binding's durable project inbox, so a restarted or replaced replica replays acknowledged events first. Wire targets with `newDexFlowTriggerTarget` and `newDexRPCTriggerTarget` from `@superdurable/connectors-sdk`. `newMessageTriggerRunner` takes configurations directly.
|
|
37
|
+
- Each poll lists every reply route before any root route, then delivers every root before any reply, so a root starts its Flow before its replies reach it. Delivery stops at the first failure; every later poll retries that event first, even after newer mail pushes it off the page. An undeliverable event is consumed.
|
|
38
|
+
- The delivered set covers the last listed page in memory, as in Go. A restart rescans the current page; the Flow start request ID and the RPC target's stable request ID absorb the duplicates.
|
|
39
|
+
- Records go to the client options' `logger` (default `defaultTriggerLogger`): WARN `gmail poll failed; retrying` with `attempt` and `delay_ms`, WARN `trigger delivery failed; retrying`, INFO `trigger delivered after retry`, WARN `trigger event skipped: undeliverable`, and DEBUG `trigger event ignored` with `reason` `not_a_reply`, `not_a_root`, or `matcher_mismatch`. Records carry message and thread IDs and error types, never senders, subjects, snippets, search queries, bodies, or tokens.
|
|
40
|
+
- `defineMessageReceivedTriggerBinding` and `defineReplyReceivedTriggerBinding` declare static bindings and their configuration units (`searchQueryInput`, `textInput`, `emailListInput`) for Dex Web. `newMessageReceivedTrigger` and `newReplyReceivedTrigger` poll one binding on their own and do not order roots before replies.
|
|
41
|
+
|
|
42
|
+
The [thread reply example](examples/thread-reply/README.md) starts a Flow from a root message, receives its reply through a typed RPC, and replies in the thread. The pollers and the example are tested against a local stand-in for the Gmail API and a real Dex server. Live Gmail polling has not been verified for this package.
|
|
43
|
+
|
|
32
44
|
## Run the example
|
|
33
45
|
|
|
34
46
|
[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):
|
package/dex-connector.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"package": {
|
|
5
5
|
"ecosystem": "npm",
|
|
6
6
|
"name": "@superdurable/connector-google-gmail",
|
|
7
|
-
"version": "0.
|
|
7
|
+
"version": "0.3.0"
|
|
8
8
|
},
|
|
9
9
|
"factories": [
|
|
10
10
|
{
|
|
@@ -82,7 +82,9 @@
|
|
|
82
82
|
"branches": {
|
|
83
83
|
"defect": "unknown",
|
|
84
84
|
"providerRejected": "rejected"
|
|
85
|
-
}
|
|
85
|
+
},
|
|
86
|
+
"repeatOnUnknown": "limited",
|
|
87
|
+
"maxSends": 3
|
|
86
88
|
},
|
|
87
89
|
"fields": {
|
|
88
90
|
"stepType": "stepType",
|
|
@@ -155,7 +157,9 @@
|
|
|
155
157
|
"defect": "unknown",
|
|
156
158
|
"invalidResponse": "rejected",
|
|
157
159
|
"providerRejected": "rejected"
|
|
158
|
-
}
|
|
160
|
+
},
|
|
161
|
+
"repeatOnUnknown": "limited",
|
|
162
|
+
"maxSends": 3
|
|
159
163
|
},
|
|
160
164
|
"fields": {
|
|
161
165
|
"stepType": "stepType",
|
|
@@ -208,6 +212,26 @@
|
|
|
208
212
|
],
|
|
209
213
|
"type": "object"
|
|
210
214
|
}
|
|
215
|
+
},
|
|
216
|
+
{
|
|
217
|
+
"name": "defineMessageReceivedTriggerBinding",
|
|
218
|
+
"kind": "trigger",
|
|
219
|
+
"triggerName": "messageReceived",
|
|
220
|
+
"fields": {
|
|
221
|
+
"connectionName": "connectionName",
|
|
222
|
+
"bindingName": "bindingName",
|
|
223
|
+
"configurationUI": "configurationUI"
|
|
224
|
+
}
|
|
225
|
+
},
|
|
226
|
+
{
|
|
227
|
+
"name": "defineReplyReceivedTriggerBinding",
|
|
228
|
+
"kind": "trigger",
|
|
229
|
+
"triggerName": "replyReceived",
|
|
230
|
+
"fields": {
|
|
231
|
+
"connectionName": "connectionName",
|
|
232
|
+
"bindingName": "bindingName",
|
|
233
|
+
"configurationUI": "configurationUI"
|
|
234
|
+
}
|
|
211
235
|
}
|
|
212
236
|
]
|
|
213
237
|
}
|