@superdurable/connector-google-gmail 0.2.2 → 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 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.
@@ -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):
@@ -4,7 +4,7 @@
4
4
  "package": {
5
5
  "ecosystem": "npm",
6
6
  "name": "@superdurable/connector-google-gmail",
7
- "version": "0.2.2"
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
  }
@@ -206,7 +206,9 @@ var SendMessageDefinition = {
206
206
  { id: "providerRejected", description: "Gmail conclusively rejected the message.", optional: true },
207
207
  { id: "defect", description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
208
208
  ],
209
- stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 5, totalDurationMs: 12e4 } }
209
+ stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 5, totalDurationMs: 12e4 } },
210
+ repeatOnUnknown: "limited",
211
+ maxSends: 3
210
212
  };
211
213
  var ReplyToMessageBranch = {
212
214
  Sent: "sent",
@@ -226,7 +228,9 @@ var ReplyToMessageDefinition = {
226
228
  { id: "invalidResponse", description: "Gmail returned an invalid or oversized source message response before sending the reply.", optional: true },
227
229
  { id: "defect", description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
228
230
  ],
229
- stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 5, totalDurationMs: 12e4 } }
231
+ stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 5, totalDurationMs: 12e4 } },
232
+ repeatOnUnknown: "limited",
233
+ maxSends: 3
230
234
  };
231
235
 
232
236
  // src/message.ts
@@ -268,7 +272,8 @@ function decodeGmailMessage(resource) {
268
272
  ...textBodies.length ? { textBody: textBodies.join("\n") } : {},
269
273
  ...htmlBodies.length ? { htmlBody: htmlBodies.join("\n") } : {},
270
274
  ...resource.snippet ? { snippet: resource.snippet } : {},
271
- receivedAt: receivedAt.toISOString().replace(".000Z", "Z"),
275
+ // Go's time.Time JSON (RFC 3339 with trailing fractional zeros removed), such as .12Z for 120 ms.
276
+ receivedAt: receivedAt.toISOString().replace(/\.(\d*?)0*Z$/, (_match, digits) => digits ? `.${digits}Z` : "Z"),
272
277
  ...resource.labelIds?.length ? { labelIds: resource.labelIds } : {}
273
278
  };
274
279
  }
@@ -419,9 +424,11 @@ function gmailClientSettings(config = {}) {
419
424
  if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1 || !Number.isSafeInteger(maxMessageBytes) || maxMessageBytes < 1) {
420
425
  throw new TypeError("Gmail response and message limits must be positive integers");
421
426
  }
422
- if (config.pollIntervalMs !== void 0 && (!Number.isSafeInteger(config.pollIntervalMs) || config.pollIntervalMs < 1e3)) throw new TypeError("Gmail poll interval is invalid");
423
- if (config.pollPageSize !== void 0 && (!Number.isSafeInteger(config.pollPageSize) || config.pollPageSize < 1 || config.pollPageSize > 100)) throw new TypeError("Gmail poll page size is invalid");
424
- return Object.freeze({ endpoint, maxResponseBytes, maxMessageBytes, addressPolicy: endpoint.startsWith("http://") ? "privateNetworkHTTP" : "publicHTTPS" });
427
+ const pollIntervalMs = config.pollIntervalMs ?? 1e4;
428
+ const pollPageSize = config.pollPageSize ?? 25;
429
+ if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 1e3) throw new TypeError("Gmail poll interval is invalid");
430
+ if (!Number.isSafeInteger(pollPageSize) || pollPageSize < 1 || pollPageSize > 100) throw new TypeError("Gmail poll page size is invalid");
431
+ return Object.freeze({ endpoint, maxResponseBytes, maxMessageBytes, addressPolicy: endpoint.startsWith("http://") ? "privateNetworkHTTP" : "publicHTTPS", pollIntervalMs, pollPageSize });
425
432
  }
426
433
  var GmailCredentialError = class extends Error {
427
434
  constructor() {
@@ -530,6 +537,7 @@ function validateCredentials(credentials) {
530
537
  import { z as z4 } from "zod";
531
538
  var SentMessageSchema = z4.object({ id: z4.string().optional(), threadId: z4.string().optional() });
532
539
  var SentSearchSchema = z4.object({ messages: z4.array(SentMessageSchema).nullish() });
540
+ var MessageListSchema = z4.object({ messages: z4.array(z4.object({ id: z4.string().nullish(), threadId: z4.string().nullish() })).nullish() });
533
541
  var GmailProvider = class {
534
542
  #http;
535
543
  /** Bind the shared authenticated transport. */
@@ -554,6 +562,23 @@ var GmailProvider = class {
554
562
  return result;
555
563
  }
556
564
  }
565
+ /**
566
+ * List the newest inbox page that matches searchQuery, as the Go Trigger poller does. It rejects with
567
+ * an error that names no query value when Gmail does not answer 2xx with a usable listing.
568
+ */
569
+ async listInboxMessages(call, credentials, searchQuery, pageSize, signal) {
570
+ const query = new URLSearchParams({ labelIds: "INBOX", maxResults: String(pageSize) });
571
+ if (searchQuery.trim()) query.set("q", searchQuery);
572
+ const result = await this.#http.request(call, credentials, "GET", `/users/me/messages?${query.toString()}`, void 0, signal);
573
+ if (result.response.status < 200 || result.response.status >= 300) throw new Error("Gmail message list is unavailable");
574
+ let parsed;
575
+ try {
576
+ parsed = MessageListSchema.parse(JSON.parse(Buffer.from(result.response.body).toString("utf8")));
577
+ } catch {
578
+ throw new Error("Gmail message list is invalid");
579
+ }
580
+ return { messages: (parsed.messages ?? []).map((message) => ({ id: message.id ?? "", threadId: message.threadId ?? "" })), credentials: result.credentials };
581
+ }
557
582
  /** Search Sent Mail once for the run-specific RFC Message-ID. */
558
583
  async findSentMessage(call, credentials, messageIdAddress, signal) {
559
584
  const query = new URLSearchParams();
@@ -1187,6 +1212,7 @@ function classifySourceFailure(status, headers, receipt) {
1187
1212
 
1188
1213
  // src/client.ts
1189
1214
  import {
1215
+ defaultTriggerLogger,
1190
1216
  newQueryBranch,
1191
1217
  newQueryRetry,
1192
1218
  zeroReceipt as zeroReceipt2
@@ -1197,12 +1223,19 @@ var GmailClient = class {
1197
1223
  #provider;
1198
1224
  #sender;
1199
1225
  #now;
1226
+ /** Trigger record destination. */
1227
+ triggerLogger;
1200
1228
  /** Validate settings and inject a host-owned credential source. */
1201
1229
  constructor(config, credentials, options = {}) {
1202
1230
  this.#http = new GmailHTTPClient(config, credentials, options.refreshDriver ?? new GmailCredentialRefreshDriver(), options.transport);
1203
1231
  this.#provider = new GmailProvider(this.#http);
1204
1232
  this.#now = options.now ?? (() => /* @__PURE__ */ new Date());
1205
1233
  this.#sender = new GmailSender(this.#http, this.#provider, this.#now);
1234
+ this.triggerLogger = options.logger ?? defaultTriggerLogger;
1235
+ }
1236
+ /** @internal The authenticated transport and provider methods that the Trigger pollers share. */
1237
+ triggerTransport() {
1238
+ return { http: this.#http, provider: this.#provider };
1206
1239
  }
1207
1240
  /** Return the getMessage Query bound to this connection. */
1208
1241
  getMessage() {
@@ -1469,6 +1502,389 @@ function newReplyToMessageStep2(configuration) {
1469
1502
  return newReplyToMessageStep(configuration);
1470
1503
  }
1471
1504
 
1505
+ // src/trigger.ts
1506
+ import {
1507
+ mustTriggerBindingDefinition,
1508
+ newTrigger
1509
+ } from "@superdurable/connectors-sdk";
1510
+ import { decodeTriggerConfiguration, newDurableTriggerTarget, parseTriggerPayloadJSON } from "@superdurable/connectors-sdk/projectconfig";
1511
+ import { z as z6 } from "zod";
1512
+
1513
+ // src/trigger_source.ts
1514
+ import { createHash as createHash2 } from "crypto";
1515
+ import {
1516
+ TriggerDeliveryAbortedError,
1517
+ createTriggerCall,
1518
+ isTriggerUndeliverable,
1519
+ logTriggerRecord,
1520
+ prepareTriggerDelivery,
1521
+ throwIfTriggerAborted,
1522
+ triggerAttempt,
1523
+ triggerErrorAttributes,
1524
+ waitForTriggerDelay,
1525
+ withTriggerLogAttributes,
1526
+ withTriggerLoggerAttributes
1527
+ } from "@superdurable/connectors-sdk";
1528
+ var GmailPollError = class extends Error {
1529
+ constructor(message, cause) {
1530
+ super(message, cause === void 0 ? void 0 : { cause });
1531
+ this.name = "GmailPollError";
1532
+ }
1533
+ };
1534
+ var uuidNamespaceURL = Buffer.from("6ba7b8119dad11d180b400c04fd430c8", "hex");
1535
+ var MessagePollingTriggerSource = class {
1536
+ #client;
1537
+ #connection;
1538
+ #searchQuery;
1539
+ #matcher;
1540
+ #requiresReply;
1541
+ #logger;
1542
+ #triggerName;
1543
+ #delivered = /* @__PURE__ */ new Set();
1544
+ // Every later poll delivers this event before any listed message, until the target consumes it.
1545
+ #retry;
1546
+ #pollFailures = 0;
1547
+ /** Bind one binding's query and matcher; an empty bindingName omits the binding log attribute. */
1548
+ constructor(client, connection, triggerName, bindingName, searchQuery, matcher, requiresReply) {
1549
+ this.#client = client;
1550
+ this.#connection = connection;
1551
+ this.#triggerName = triggerName;
1552
+ this.#searchQuery = searchQuery;
1553
+ this.#matcher = matcher;
1554
+ this.#requiresReply = requiresReply;
1555
+ this.#logger = withTriggerLoggerAttributes(client.triggerLogger, { connector: ConnectorID, connection: connection.name, trigger: triggerName, ...bindingName ? { binding: bindingName } : {} });
1556
+ }
1557
+ /** Scan, then wait one poll interval, until the context ends. */
1558
+ async run(context, target) {
1559
+ await runMessageTriggerRoutes(context, () => this.scan(context, target), this.#pollIntervalMs());
1560
+ }
1561
+ /** List the inbox and deliver the listed messages. */
1562
+ async scan(context, target) {
1563
+ await this.deliver(context, target, await this.list(context));
1564
+ }
1565
+ /** Read the newest inbox page that matches the source's search query. */
1566
+ async list(context) {
1567
+ const { http, provider } = this.#client.triggerTransport();
1568
+ const call = this.#credentialCall(context.signal);
1569
+ let credentials;
1570
+ try {
1571
+ credentials = await http.resolveCredentials(call, context.signal);
1572
+ } catch (error) {
1573
+ throw this.#pollFailed(context, new GmailPollError("Gmail Trigger credentials are unavailable", error));
1574
+ }
1575
+ try {
1576
+ const listed = await provider.listInboxMessages(call, credentials, this.#searchQuery, http.settings().pollPageSize, context.signal);
1577
+ return { credentials: listed.credentials, messages: listed.messages };
1578
+ } catch (error) {
1579
+ throw this.#pollFailed(context, new GmailPollError("Gmail message list is unavailable", error));
1580
+ }
1581
+ }
1582
+ /**
1583
+ * Hand target the event that failed on an earlier poll, if any, then every new matching message in
1584
+ * listing, oldest first. It stops at the first failure, so the next poll retries that event before any
1585
+ * later message, even after newer mail pushes it off the listed page.
1586
+ */
1587
+ async deliver(context, target, listing) {
1588
+ if (this.#retry) await this.#handle(context, target, this.#retry.event);
1589
+ const { provider } = this.#client.triggerTransport();
1590
+ let credentials = listing.credentials;
1591
+ const current = /* @__PURE__ */ new Set();
1592
+ for (let index = listing.messages.length - 1; index >= 0; index--) {
1593
+ const reference = listing.messages[index];
1594
+ if (!reference.id) continue;
1595
+ current.add(reference.id);
1596
+ if (this.#delivered.has(reference.id)) continue;
1597
+ const messageAttributes = { thread_id: reference.threadId, event_id: reference.id };
1598
+ let message;
1599
+ try {
1600
+ const read = await provider.readMessage(this.#credentialCall(context.signal), credentials, reference.id, "metadata", context.signal);
1601
+ credentials = read.credentials;
1602
+ if (!read.resource) throw new GmailPollError("Gmail message lookup failed");
1603
+ message = decodeGmailMessage(read.resource);
1604
+ } catch (error) {
1605
+ throw this.#pollFailed(context, error instanceof GmailPollError ? error : new GmailPollError("Gmail message lookup failed", error), messageAttributes);
1606
+ }
1607
+ const isReply = (message.inReplyTo ?? "").trim() !== "" || (message.references ?? "").trim() !== "";
1608
+ const reason = this.#ignoreReason(isReply, message);
1609
+ if (reason) {
1610
+ this.#log(context, "debug", "trigger event ignored", { ...messageAttributes, reason });
1611
+ continue;
1612
+ }
1613
+ const event = {
1614
+ id: message.messageId,
1615
+ occurredAt: new Date(message.receivedAt),
1616
+ payload: {
1617
+ primaryEmail: credentials.primaryEmail,
1618
+ messageId: message.messageId,
1619
+ threadId: message.threadId,
1620
+ from: message.from,
1621
+ subject: message.subject,
1622
+ ...message.snippet ? { snippet: message.snippet } : {},
1623
+ receivedAt: message.receivedAt,
1624
+ isReply
1625
+ }
1626
+ };
1627
+ try {
1628
+ await prepareTriggerDelivery(context, target, event);
1629
+ } catch (error) {
1630
+ throw this.#pollFailed(context, new GmailPollError("Gmail Trigger delivery could not be recorded", error), messageAttributes);
1631
+ }
1632
+ await this.#handle(context, target, event);
1633
+ }
1634
+ this.#delivered = current;
1635
+ this.#pollFailures = 0;
1636
+ }
1637
+ #pollIntervalMs() {
1638
+ return this.#client.triggerTransport().http.settings().pollIntervalMs;
1639
+ }
1640
+ /**
1641
+ * Make one delivery attempt and log its outcome. It resolves when target consumes the event, and
1642
+ * otherwise keeps the event as the source's retry and rethrows. A durable inbox or a newTrigger runner
1643
+ * logs the undeliverable events it consumes itself, so the source then logs no recovery.
1644
+ */
1645
+ async #handle(context, target, event) {
1646
+ const failures = this.#retry?.event.id === event.id ? this.#retry.failures : 0;
1647
+ const threadAttributes = { thread_id: event.payload.threadId };
1648
+ const messageAttributes = { ...threadAttributes, event_id: event.id };
1649
+ const attempt = triggerAttempt(withTriggerLogAttributes(context, threadAttributes));
1650
+ try {
1651
+ await target.handleTrigger(attempt.context, event);
1652
+ if (failures > 0 && !attempt.wasSkipped()) this.#log(context, "info", "trigger delivered after retry", { ...messageAttributes, attempts: failures + 1 });
1653
+ } catch (error) {
1654
+ if (isTriggerUndeliverable(error)) {
1655
+ this.#log(context, "warn", "trigger event skipped: undeliverable", { ...messageAttributes, ...triggerErrorAttributes(error) });
1656
+ } else if (context.signal.aborted) {
1657
+ throw error;
1658
+ } else {
1659
+ this.#pollFailures = 0;
1660
+ this.#retry = { event, failures: failures + 1 };
1661
+ this.#log(context, "warn", "trigger delivery failed; retrying", { ...messageAttributes, attempt: failures + 1, delay_ms: this.#pollIntervalMs(), ...triggerErrorAttributes(error) });
1662
+ throw error;
1663
+ }
1664
+ }
1665
+ this.#retry = void 0;
1666
+ this.#delivered.add(event.id);
1667
+ }
1668
+ /** Explain why the source does not deliver a listed message, or return '' when it matches. */
1669
+ #ignoreReason(isReply, message) {
1670
+ if (this.#requiresReply && !isReply) return "not_a_reply";
1671
+ if (!this.#requiresReply && isReply) return "not_a_root";
1672
+ if (!messageMatcherMatches(this.#matcher, message)) return "matcher_mismatch";
1673
+ return "";
1674
+ }
1675
+ /** Log a poll that ended early and return error; the next poll, one interval later, retries. */
1676
+ #pollFailed(context, error, attributes = {}) {
1677
+ if (context.signal.aborted) return new TriggerDeliveryAbortedError();
1678
+ this.#pollFailures++;
1679
+ const causeAttributes = error.cause === void 0 ? {} : { error_cause_type: triggerErrorAttributes(error.cause).error_type ?? "Error" };
1680
+ this.#log(context, "warn", "gmail poll failed; retrying", { ...attributes, attempt: this.#pollFailures, delay_ms: this.#pollIntervalMs(), error: error.message, ...causeAttributes });
1681
+ return error;
1682
+ }
1683
+ #log(context, level, message, attributes) {
1684
+ logTriggerRecord(this.#logger, context, level, message, attributes);
1685
+ }
1686
+ /** The Go connector's stable credential call: a version 5 UUID of the connection and Trigger. */
1687
+ #credentialCall(signal) {
1688
+ const identity = ["https://superdurable.dev/dex-connectors/trigger-credential/v1", this.#connection.provider, this.#connection.name, this.#triggerName].join("/");
1689
+ return createTriggerCall(this.#connection, { connectorId: ConnectorID, operationId: this.#triggerName }, nameBasedUUID(identity), signal);
1690
+ }
1691
+ };
1692
+ function messageMatcherMatches(matcher, message) {
1693
+ if (matcher.messageContains) {
1694
+ const haystack = `${message.subject}
1695
+ ${message.snippet ?? ""}`.toLowerCase();
1696
+ if (!haystack.includes(matcher.messageContains.toLowerCase())) return false;
1697
+ }
1698
+ const senders = matcher.senderEmails ?? [];
1699
+ if (senders.length === 0) return true;
1700
+ const sender = parseMailbox(message.from)?.address.toLowerCase();
1701
+ if (!sender) return false;
1702
+ return senders.some((allowed) => parseMailbox(allowed)?.address.toLowerCase() === sender);
1703
+ }
1704
+ async function runMessageTriggerRoutes(context, poll, intervalMs) {
1705
+ for (; ; ) {
1706
+ throwIfTriggerAborted(context.signal);
1707
+ try {
1708
+ await poll();
1709
+ } catch {
1710
+ throwIfTriggerAborted(context.signal);
1711
+ }
1712
+ await waitForTriggerDelay(context.signal, intervalMs);
1713
+ }
1714
+ }
1715
+ async function pollMessageTriggerRoutes(context, rootRoutes, replyRoutes) {
1716
+ const replyListings = [];
1717
+ for (const route of replyRoutes) replyListings.push(await route.source.list(context));
1718
+ for (const route of rootRoutes) await route.source.scan(context, route.target);
1719
+ for (const [index, route] of replyRoutes.entries()) await route.source.deliver(context, route.target, replyListings[index]);
1720
+ }
1721
+ async function replayMessageTriggerRoutes(context, routes) {
1722
+ for (const route of routes) {
1723
+ if (!route.target.replayTriggerDeliveries) continue;
1724
+ try {
1725
+ await route.target.replayTriggerDeliveries(context);
1726
+ } catch (error) {
1727
+ if (error instanceof TriggerDeliveryAbortedError) throw error;
1728
+ throw new Error(`replay Gmail Trigger deliveries: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
1729
+ }
1730
+ }
1731
+ }
1732
+ function nameBasedUUID(name) {
1733
+ const bytes = createHash2("sha1").update(uuidNamespaceURL).update(name, "utf8").digest().subarray(0, 16);
1734
+ bytes[6] = bytes[6] & 15 | 80;
1735
+ bytes[8] = bytes[8] & 63 | 128;
1736
+ const hex = bytes.toString("hex");
1737
+ return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
1738
+ }
1739
+
1740
+ // src/trigger.ts
1741
+ var MessageMatcherSchema = z6.strictObject({
1742
+ /** Case-insensitive substring of the subject or snippet, required when non-empty. */
1743
+ messageContains: z6.string().optional(),
1744
+ /** Sender addresses allowed to match when non-empty; compared case-insensitively. */
1745
+ senderEmails: z6.array(z6.string()).nullable().optional()
1746
+ });
1747
+ var MessageReceivedTriggerConfigurationSchema = z6.strictObject({ searchQuery: z6.string().optional(), messageMatcher: MessageMatcherSchema.optional() }).superRefine((configuration, context) => validateMessageMatcher(configuration.messageMatcher, context));
1748
+ var ReplyReceivedTriggerConfigurationSchema = z6.strictObject({ searchQuery: z6.string().optional(), replyMatcher: MessageMatcherSchema.optional() }).superRefine((configuration, context) => validateMessageMatcher(configuration.replyMatcher, context));
1749
+ var MessageEventSchema = z6.object({
1750
+ /** Mailbox that received the message. */
1751
+ primaryEmail: z6.string(),
1752
+ /** Gmail message ID. */
1753
+ messageId: z6.string(),
1754
+ /** Gmail thread ID. */
1755
+ threadId: z6.string(),
1756
+ /** Sender header. */
1757
+ from: z6.string(),
1758
+ /** Decoded subject. */
1759
+ subject: z6.string(),
1760
+ /** Gmail snippet, omitted when empty. */
1761
+ snippet: z6.string().optional(),
1762
+ /** Receive time as RFC 3339 UTC. */
1763
+ receivedAt: z6.string(),
1764
+ /** Whether the message has In-Reply-To or References headers. */
1765
+ isReply: z6.boolean()
1766
+ });
1767
+ var MessageReceivedTriggerDefinition = { trigger: { connectorId: ConnectorID, triggerName: "messageReceived" }, description: "Receive a matching message that begins a Gmail thread." };
1768
+ var ReplyReceivedTriggerDefinition = { trigger: { connectorId: ConnectorID, triggerName: "replyReceived" }, description: "Receive a matching reply in an existing Gmail thread." };
1769
+ var UIUnitSearchQueryInput = "searchQueryInput";
1770
+ var UISearchQueryInputPortQuery = "query";
1771
+ var UIUnitEmailListInput = "emailListInput";
1772
+ var UIEmailListInputPortEmails = "emails";
1773
+ var UIUnitTextInput = "textInput";
1774
+ var UITextInputPortText = "text";
1775
+ function defineMessageReceivedTriggerBinding(config) {
1776
+ return mustTriggerBindingDefinition({ definition: MessageReceivedTriggerDefinition, ...config });
1777
+ }
1778
+ function defineReplyReceivedTriggerBinding(config) {
1779
+ return mustTriggerBindingDefinition({ definition: ReplyReceivedTriggerDefinition, ...config });
1780
+ }
1781
+ function newMessageReceivedTrigger(config) {
1782
+ const configuration = MessageReceivedTriggerConfigurationSchema.parse(config.configuration);
1783
+ return newStandaloneTrigger(config, MessageReceivedTriggerDefinition, configuration.searchQuery ?? "", configuration.messageMatcher ?? {}, false);
1784
+ }
1785
+ function newReplyReceivedTrigger(config) {
1786
+ const configuration = ReplyReceivedTriggerConfigurationSchema.parse(config.configuration);
1787
+ return newStandaloneTrigger(config, ReplyReceivedTriggerDefinition, configuration.searchQuery ?? "", configuration.replyMatcher ?? {}, true);
1788
+ }
1789
+ function newStandaloneTrigger(config, definition, searchQuery, matcher, requiresReply) {
1790
+ const client = gmailClientOf(config.connection);
1791
+ if (config.connectionName !== config.connection.reference.name) throw new TypeError(`gmail connector trigger connectionName "${config.connectionName}" must equal its connection's name "${config.connection.reference.name}"`);
1792
+ const source = new MessagePollingTriggerSource(client, config.connection.reference, definition.trigger.triggerName, "", searchQuery, matcher, requiresReply);
1793
+ const triggerSource = { run: (context, target) => source.run(context, target) };
1794
+ return newTrigger({ definition, binding: { connection: config.connection.reference, trigger: definition.trigger, name: config.bindingName }, source: triggerSource, target: config.target, logger: client.triggerLogger });
1795
+ }
1796
+ var MessageTriggerRunner = class {
1797
+ #rootRoutes;
1798
+ #replyRoutes;
1799
+ #pollIntervalMs;
1800
+ /** @internal Use newMessageTriggerRunner or newProjectMessageTriggerRunner. */
1801
+ constructor(rootRoutes, replyRoutes, pollIntervalMs) {
1802
+ this.#rootRoutes = rootRoutes;
1803
+ this.#replyRoutes = replyRoutes;
1804
+ this.#pollIntervalMs = pollIntervalMs;
1805
+ }
1806
+ /**
1807
+ * Replay each route's durable inbox in order, roots first, then poll until the context ends. Each poll
1808
+ * lists every reply route before any root route, then delivers every root before any reply, and ends
1809
+ * at the first failure. Every later poll retries the failed event before that route's listed messages,
1810
+ * even after Gmail stops listing it. Gmail receives a thread's root before any reply to it, so the
1811
+ * root of every listed reply is in the later root listing and reaches Dex first.
1812
+ *
1813
+ * It logs through the client's logger: WARN "gmail poll failed; retrying" with the consecutive failed
1814
+ * polls as attempt and the poll interval as delay_ms when a list or read fails, WARN "trigger delivery
1815
+ * failed; retrying" with the attempt number when a target fails, INFO "trigger delivered after retry"
1816
+ * when a later poll delivers that message, DEBUG "trigger event ignored" with its reason, and the
1817
+ * durable inbox records. It rejects with TriggerDeliveryAbortedError once the context ends, and when
1818
+ * an inbox replay fails.
1819
+ */
1820
+ async run(context) {
1821
+ await replayMessageTriggerRoutes(context, [...this.#rootRoutes, ...this.#replyRoutes]);
1822
+ await runMessageTriggerRoutes(context, () => pollMessageTriggerRoutes(context, this.#rootRoutes, this.#replyRoutes), this.#pollIntervalMs);
1823
+ }
1824
+ };
1825
+ function newMessageTriggerRunner(config) {
1826
+ const client = gmailClientOf(config.connection);
1827
+ const bindingKeys = /* @__PURE__ */ new Set();
1828
+ const route = (triggerName, bindingName, target, searchQuery, matcher, requiresReply) => {
1829
+ const trimmedBindingName = bindingName?.trim();
1830
+ if (!trimmedBindingName || !target) throw new TypeError("Gmail message Trigger binding name and target are required");
1831
+ const bindingKey = `${triggerName}\0${trimmedBindingName}`;
1832
+ if (bindingKeys.has(bindingKey)) throw new TypeError(`Gmail message Trigger binding name "${trimmedBindingName}" is duplicated`);
1833
+ bindingKeys.add(bindingKey);
1834
+ return { source: new MessagePollingTriggerSource(client, config.connection.reference, triggerName, bindingName, searchQuery ?? "", matcher ?? {}, requiresReply), target };
1835
+ };
1836
+ const rootRoutes = (config.messageReceivedRoutes ?? []).map((root) => {
1837
+ const configuration = MessageReceivedTriggerConfigurationSchema.parse(root.configuration);
1838
+ return route("messageReceived", root.bindingName, root.target, configuration.searchQuery, configuration.messageMatcher, false);
1839
+ });
1840
+ const replyRoutes = (config.replyReceivedRoutes ?? []).map((reply) => {
1841
+ const configuration = ReplyReceivedTriggerConfigurationSchema.parse(reply.configuration);
1842
+ return route("replyReceived", reply.bindingName, reply.target, configuration.searchQuery, configuration.replyMatcher, true);
1843
+ });
1844
+ if (rootRoutes.length + replyRoutes.length === 0) throw new TypeError("Gmail message Trigger routes are required");
1845
+ return new MessageTriggerRunner(rootRoutes, replyRoutes, client.triggerTransport().http.settings().pollIntervalMs);
1846
+ }
1847
+ function newProjectMessageTriggerRunner(project, connectionName, config, options = {}) {
1848
+ const connection = newProjectConnection(project, connectionName, options);
1849
+ const client = gmailClientOf(connection);
1850
+ const durable = (triggerName, bindingName, target, schema) => {
1851
+ const key = { connectorId: ConnectorID, connectionName, triggerName, bindingName };
1852
+ let configuration;
1853
+ try {
1854
+ configuration = decodeTriggerConfiguration(project.configuration, key, schema);
1855
+ } catch (error) {
1856
+ throw new Error(`gmail ${triggerName} binding "${bindingName}" configuration: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
1857
+ }
1858
+ const durableTarget = newDurableTriggerTarget(project.triggerInbox(key), key, target, { logger: client.triggerLogger, decodePayload: (_payloadJSON, payloadBytes) => MessageEventSchema.parse(parseTriggerPayloadJSON(payloadBytes)) });
1859
+ return { bindingName, configuration, target: durableTarget };
1860
+ };
1861
+ return newMessageTriggerRunner({
1862
+ connection,
1863
+ messageReceivedRoutes: (config.messageReceivedRoutes ?? []).map((route) => durable("messageReceived", route.bindingName, route.target, MessageReceivedTriggerConfigurationSchema)),
1864
+ replyReceivedRoutes: (config.replyReceivedRoutes ?? []).map((route) => durable("replyReceived", route.bindingName, route.target, ReplyReceivedTriggerConfigurationSchema))
1865
+ });
1866
+ }
1867
+ function gmailClientOf(connection) {
1868
+ if (!(connection?.operations instanceof GmailClient)) throw new TypeError("Gmail Triggers require a connection bound to a GmailClient");
1869
+ return connection.operations;
1870
+ }
1871
+ function validateMessageMatcher(matcher, context) {
1872
+ const seen = /* @__PURE__ */ new Set();
1873
+ for (const sender of matcher?.senderEmails ?? []) {
1874
+ const address = parseMailbox(sender)?.address;
1875
+ if (!address) {
1876
+ context.addIssue({ code: "custom", message: "Gmail sender email is invalid" });
1877
+ return;
1878
+ }
1879
+ const canonical = address.toLowerCase();
1880
+ if (seen.has(canonical)) {
1881
+ context.addIssue({ code: "custom", message: "Gmail sender emails must be unique" });
1882
+ return;
1883
+ }
1884
+ seen.add(canonical);
1885
+ }
1886
+ }
1887
+
1472
1888
  export {
1473
1889
  GetMessageInputSchema,
1474
1890
  MessageSchema,
@@ -1517,5 +1933,24 @@ export {
1517
1933
  newProjectGmailClient,
1518
1934
  newGetMessageStep2 as newGetMessageStep,
1519
1935
  newSendMessageStep2 as newSendMessageStep,
1520
- newReplyToMessageStep2 as newReplyToMessageStep
1936
+ newReplyToMessageStep2 as newReplyToMessageStep,
1937
+ MessageMatcherSchema,
1938
+ MessageReceivedTriggerConfigurationSchema,
1939
+ ReplyReceivedTriggerConfigurationSchema,
1940
+ MessageEventSchema,
1941
+ MessageReceivedTriggerDefinition,
1942
+ ReplyReceivedTriggerDefinition,
1943
+ UIUnitSearchQueryInput,
1944
+ UISearchQueryInputPortQuery,
1945
+ UIUnitEmailListInput,
1946
+ UIEmailListInputPortEmails,
1947
+ UIUnitTextInput,
1948
+ UITextInputPortText,
1949
+ defineMessageReceivedTriggerBinding,
1950
+ defineReplyReceivedTriggerBinding,
1951
+ newMessageReceivedTrigger,
1952
+ newReplyReceivedTrigger,
1953
+ MessageTriggerRunner,
1954
+ newMessageTriggerRunner,
1955
+ newProjectMessageTriggerRunner
1521
1956
  };