@superdurable/connector-google-gmail 0.2.2 → 0.4.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 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). Gmail Triggers and the thread-reply Trigger runner currently belong to the Go connector.
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.2.2 requires Connector SDK 0.9.0. Generated private and shared
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.
@@ -27,7 +27,19 @@ For personal Gmail or ordinary Workspace accounts, select **Google OAuth**. In [
27
27
 
28
28
  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.
29
29
 
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.
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`. Both operations declare `repeatOnUnknown: limited` with `maxSends: 3`, and the Fence takes the definition's cap or the Step's `maxSends`. After a claimed send whose outcome stayed unknown, a Sent Mail miss or failed search resends with the same `Message-ID` while fewer than that many sends may have taken effect; at the cap a miss retries read-back without another POST until the seven-attempt, five-minute budget fails the Flow. A saved Gmail message ID and a definite 4xx are never resent. A definite 4xx, or a rejected or unusable reply source read, selects its branch only when no earlier send is possible; otherwise it returns Retry, because the earlier send may still be delivered. 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. An accepted 2xx never resends merely because its response body is unusable.
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.
31
43
 
32
44
  ## Run the example
33
45
 
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "connectorId": "gmail",
3
- "releaseTag": "connectors/google/gmail/go/v0.26.0",
3
+ "releaseTag": "connectors/google/gmail/go/v0.27.0",
4
4
  "package": {
5
5
  "ecosystem": "npm",
6
6
  "name": "@superdurable/connector-google-gmail",
7
- "version": "0.2.2"
7
+ "version": "0.4.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
  }