@superdurable/connector-google-gmail 0.3.0 → 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
@@ -27,7 +27,7 @@ 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
31
 
32
32
  ## Triggers
33
33
 
@@ -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.3.0"
7
+ "version": "0.4.0"
8
8
  },
9
9
  "factories": [
10
10
  {
@@ -206,7 +206,7 @@ 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: 7, totalDurationMs: 3e5 } },
210
210
  repeatOnUnknown: "limited",
211
211
  maxSends: 3
212
212
  };
@@ -228,7 +228,7 @@ var ReplyToMessageDefinition = {
228
228
  { id: "invalidResponse", description: "Gmail returned an invalid or oversized source message response before sending the reply.", optional: true },
229
229
  { id: "defect", description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
230
230
  ],
231
- 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: 7, totalDurationMs: 3e5 } },
232
232
  repeatOnUnknown: "limited",
233
233
  maxSends: 3
234
234
  };
@@ -410,7 +410,7 @@ function encodeSubject(value) {
410
410
  }
411
411
 
412
412
  // src/http.ts
413
- import { resolveCredential, resolveCredentialAfterRejection } from "@superdurable/connectors-sdk";
413
+ import { ReauthorizationRequiredError, resolveCredential, resolveCredentialAfterRejection } from "@superdurable/connectors-sdk";
414
414
  import {
415
415
  BodyTooLargeError,
416
416
  isHeaderSafeCredential,
@@ -431,9 +431,13 @@ function gmailClientSettings(config = {}) {
431
431
  return Object.freeze({ endpoint, maxResponseBytes, maxMessageBytes, addressPolicy: endpoint.startsWith("http://") ? "privateNetworkHTTP" : "publicHTTPS", pollIntervalMs, pollPageSize });
432
432
  }
433
433
  var GmailCredentialError = class extends Error {
434
- constructor() {
434
+ /** True when only reconnection can repair the failure: reauthorization or invalid material. */
435
+ isPermanent;
436
+ /** Create a secret-safe credential failure; omitted permanence means permanent. */
437
+ constructor(isPermanent = true) {
435
438
  super("connection credentials are unavailable");
436
439
  this.name = "GmailCredentialError";
440
+ this.isPermanent = isPermanent;
437
441
  }
438
442
  };
439
443
  var GmailHTTPClient = class {
@@ -455,13 +459,18 @@ var GmailHTTPClient = class {
455
459
  }
456
460
  /** Resolve a private token at call time; never put it in a receipt or Flow value. */
457
461
  async resolveCredentials(call, signal) {
462
+ let credentials;
463
+ try {
464
+ credentials = await resolveCredential(this.#credentials, call, this.#refreshDriver, signal);
465
+ } catch (error) {
466
+ throw new GmailCredentialError(error instanceof ReauthorizationRequiredError);
467
+ }
458
468
  try {
459
- const credentials = await resolveCredential(this.#credentials, call, this.#refreshDriver, signal);
460
469
  validateCredentials(credentials);
461
- return credentials;
462
470
  } catch {
463
471
  throw new GmailCredentialError();
464
472
  }
473
+ return credentials;
465
474
  }
466
475
  /** Send one authenticated request, refreshing at most once after a 401. */
467
476
  async request(call, credentials, method, pathAndQuery, body, signal) {
@@ -615,7 +624,7 @@ function parseSentResponse(response) {
615
624
  }
616
625
 
617
626
  // src/refresh.ts
618
- import { ReauthorizationRequiredError } from "@superdurable/connectors-sdk";
627
+ import { ReauthorizationRequiredError as ReauthorizationRequiredError2 } from "@superdurable/connectors-sdk";
619
628
  import { isRefreshRequired, ManifestCredentialRefreshDriver } from "@superdurable/connectors-sdk/oauthtoken";
620
629
 
621
630
  // src/generated/refresh.ts
@@ -799,7 +808,7 @@ var GmailCredentialRefreshDriver = class {
799
808
  if (method !== WorkspaceDomainDelegationAuthMethodID) return this.#manifestDriver.refresh(state, signal);
800
809
  this.#validateServiceAccountKey(credentials.serviceAccountKey?.reveal() ?? "");
801
810
  const delegatedUser = (credentials.delegatedUser ?? "").trim();
802
- if (!delegatedUser || !delegatedUser.includes("@")) throw new ReauthorizationRequiredError();
811
+ if (!delegatedUser || !delegatedUser.includes("@")) throw new ReauthorizationRequiredError2();
803
812
  const result = await this.#manifestDriver.refresh({ ...state, credentials: { ...credentials, delegatedUser } }, signal);
804
813
  return { ...result, credentials: { ...result.credentials, delegatedUser: credentials.delegatedUser } };
805
814
  }
@@ -810,20 +819,21 @@ var GmailCredentialRefreshDriver = class {
810
819
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new TypeError();
811
820
  key = parsed;
812
821
  } catch {
813
- throw new ReauthorizationRequiredError();
822
+ throw new ReauthorizationRequiredError2();
814
823
  }
815
- if (typeof key.client_email !== "string" || !key.client_email || typeof key.private_key !== "string" || !key.private_key || typeof key.token_uri !== "string" || !key.token_uri) throw new ReauthorizationRequiredError();
824
+ if (typeof key.client_email !== "string" || !key.client_email || typeof key.private_key !== "string" || !key.private_key || typeof key.token_uri !== "string" || !key.token_uri) throw new ReauthorizationRequiredError2();
816
825
  try {
817
826
  const endpoint = new URL(key.token_uri);
818
827
  if (endpoint.protocol !== "https:" || !endpoint.hostname) throw new TypeError();
819
828
  } catch {
820
- throw new ReauthorizationRequiredError();
829
+ throw new ReauthorizationRequiredError2();
821
830
  }
822
831
  }
823
832
  };
824
833
 
825
834
  // src/send.ts
826
835
  import {
836
+ definitionMaxSends,
827
837
  newMutationBranch,
828
838
  newMutationRetry,
829
839
  zeroReceipt
@@ -938,7 +948,7 @@ var GmailSender = class {
938
948
  if (call.context.attempt < 1) return defect("sendMessage", "LOCAL_DEFECT", "Dex Execute attempt number is invalid");
939
949
  const messageIdAddress = this.#messageID(call);
940
950
  if (!messageIdAddress) return defect("sendMessage", "LOCAL_DEFECT", MissingRunIDMessage);
941
- const fence = newFence(call, SendMessageDefinition.stepDefaults.executeMethodTimeoutMs ?? 3e4);
951
+ const fence = newFence(call, SendMessageDefinition.stepDefaults.executeMethodTimeoutMs ?? 3e4, { maxSends: definitionMaxSends(SendMessageDefinition) });
942
952
  if (fence.decide().kind === "failClosed") return defect("sendMessage", "LOCAL_DEFECT", "Dex send checkpoint is unreadable");
943
953
  const budget = new GmailSendAttemptBudget(call.context.cancellationSignal, dexDeadline);
944
954
  if (!budget.sendSignal()) {
@@ -948,8 +958,8 @@ var GmailSender = class {
948
958
  let credentials;
949
959
  try {
950
960
  credentials = await this.#http.resolveCredentials(call, budget.attemptSignal());
951
- } catch {
952
- return defect("sendMessage", "AUTHENTICATION", "connection credentials are unavailable");
961
+ } catch (error) {
962
+ return unavailableCredentials(fence, "sendMessage", error);
953
963
  }
954
964
  let recipients;
955
965
  try {
@@ -972,7 +982,7 @@ var GmailSender = class {
972
982
  if (call.context.attempt < 1) return defect("replyToMessage", "LOCAL_DEFECT", "Dex Execute attempt number is invalid");
973
983
  const messageIdAddress = this.#messageID(call);
974
984
  if (!messageIdAddress) return defect("replyToMessage", "LOCAL_DEFECT", MissingRunIDMessage);
975
- const fence = newFence(call, ReplyToMessageDefinition.stepDefaults.executeMethodTimeoutMs ?? 3e4);
985
+ const fence = newFence(call, ReplyToMessageDefinition.stepDefaults.executeMethodTimeoutMs ?? 3e4, { maxSends: definitionMaxSends(ReplyToMessageDefinition) });
976
986
  if (fence.decide().kind === "failClosed") return defect("replyToMessage", "LOCAL_DEFECT", "Dex send checkpoint is unreadable");
977
987
  const budget = new GmailSendAttemptBudget(call.context.cancellationSignal, dexDeadline);
978
988
  if (!budget.sendSignal()) {
@@ -982,12 +992,12 @@ var GmailSender = class {
982
992
  let credentials;
983
993
  try {
984
994
  credentials = await this.#http.resolveCredentials(call, budget.attemptSignal());
985
- } catch {
986
- return defect("replyToMessage", "AUTHENTICATION", "connection credentials are unavailable");
995
+ } catch (error) {
996
+ return unavailableCredentials(fence, "replyToMessage", error);
987
997
  }
988
998
  if (!ReplyToMessageInputSchema.safeParse(input).success || !input.messageId.trim() || !input.textBody.trim()) return defect("replyToMessage", "VALIDATION", "message ID and text body are required");
989
999
  const priorProviderId = fence.decide().marker?.providerId;
990
- if (fence.decide().kind === "readBackRequired" && priorProviderId) {
1000
+ if (isReadBackDecision(fence) && priorProviderId) {
991
1001
  return this.#sentMessage(
992
1002
  call,
993
1003
  budget,
@@ -1003,8 +1013,10 @@ var GmailSender = class {
1003
1013
  const found = await this.#provider.findSentMessage(call, credentials, messageIdAddress, budget.preSendSignal());
1004
1014
  if (found) return this.#sentMessage(call, budget, credentials, ReplyToMessageOutcomes, { raw: new Uint8Array(), recipients: [], requestedThreadId: "", hasPreSendSearch: true, messageIdAddress }, found, this.#receipt(call));
1005
1015
  } catch {
1006
- await recordPreSendRetry(fence);
1007
- return newMutationRetry(failure("replyToMessage", "AVAILABILITY", "Gmail sent-mail search did not answer before the reply"));
1016
+ if (fence.decide().kind !== "readBackThenResendAllowed") {
1017
+ await recordPreSendRetry(fence);
1018
+ return newMutationRetry(failure("replyToMessage", "AVAILABILITY", "Gmail sent-mail search did not answer before the reply"));
1019
+ }
1008
1020
  }
1009
1021
  if (fence.decide().kind === "readBackRequired") return newMutationRetry(failure("replyToMessage", "AVAILABILITY", "Gmail reply outcome is unknown; the sent-mail search found no message"));
1010
1022
  }
@@ -1015,13 +1027,13 @@ var GmailSender = class {
1015
1027
  if (error instanceof GmailCredentialError) return defect("replyToMessage", "AUTHENTICATION", "connection credentials are unavailable");
1016
1028
  const status = error instanceof BodyTooLargeError2 ? error.status ?? 0 : 0;
1017
1029
  const headers = error instanceof BodyTooLargeError2 ? error.headers ?? {} : {};
1018
- const result = classifySourceFailure(status, headers, this.#receipt(call));
1030
+ const result = classifySourceFailure(fence, status, headers, this.#receipt(call));
1019
1031
  if (result.kind === "retry") await recordPreSendRetry(fence);
1020
1032
  return result;
1021
1033
  }
1022
1034
  credentials = source.credentials;
1023
1035
  if (!source.resource) {
1024
- const result = classifySourceFailure(source.response.status, source.response.headers, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId));
1036
+ const result = classifySourceFailure(fence, source.response.status, source.response.headers, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId));
1025
1037
  if (result.kind === "retry") await recordPreSendRetry(fence);
1026
1038
  return result;
1027
1039
  }
@@ -1029,16 +1041,16 @@ var GmailSender = class {
1029
1041
  try {
1030
1042
  message = decodeGmailMessage(source.resource);
1031
1043
  } catch {
1032
- return newMutationBranch(ReplyToMessageBranch.InvalidResponse, emptySend(), this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "source message lacks reply metadata"));
1044
+ return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "source message lacks reply metadata"));
1033
1045
  }
1034
- if (!message.threadId || !message.rfcMessageId) return newMutationBranch(ReplyToMessageBranch.InvalidResponse, emptySend(), this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "source message lacks reply metadata"));
1046
+ if (!message.threadId || !message.rfcMessageId) return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "source message lacks reply metadata"));
1035
1047
  let recipient;
1036
1048
  try {
1037
1049
  recipient = replyRecipient(message);
1038
1050
  } catch {
1039
- return newMutationBranch(ReplyToMessageBranch.InvalidResponse, emptySend(), this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "Gmail returned an invalid source sender"));
1051
+ return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "Gmail returned an invalid source sender"));
1040
1052
  }
1041
- if (/[\r\n]/.test(message.subject + message.rfcMessageId + (message.references ?? ""))) return newMutationBranch(ReplyToMessageBranch.InvalidResponse, emptySend(), this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "Gmail returned invalid source reply headers"));
1053
+ if (/[\r\n]/.test(message.subject + message.rfcMessageId + (message.references ?? ""))) return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "Gmail returned invalid source reply headers"));
1042
1054
  let raw;
1043
1055
  try {
1044
1056
  raw = buildReplyMIMEMessage(call.id, call.idempotencyKey ?? call.id, messageIdAddress, credentials.primaryEmail, message, input);
@@ -1050,7 +1062,7 @@ var GmailSender = class {
1050
1062
  }
1051
1063
  async #sendAndConfirm(call, fence, budget, credentials, operation, message) {
1052
1064
  const priorProviderId = fence.decide().marker?.providerId;
1053
- if (fence.decide().kind === "readBackRequired" && priorProviderId) {
1065
+ if (isReadBackDecision(fence) && priorProviderId) {
1054
1066
  return this.#sentMessage(
1055
1067
  call,
1056
1068
  budget,
@@ -1066,8 +1078,10 @@ var GmailSender = class {
1066
1078
  const found = await this.#provider.findSentMessage(call, credentials, message.messageIdAddress, budget.preSendSignal());
1067
1079
  if (found) return this.#sentMessage(call, budget, credentials, operation, message, found, this.#receipt(call));
1068
1080
  } catch {
1069
- await recordPreSendRetry(fence);
1070
- return newMutationRetry(failure(operation.operationId, "AVAILABILITY", `Gmail sent-mail search did not answer before the ${operation.requestName}`));
1081
+ if (fence.decide().kind !== "readBackThenResendAllowed") {
1082
+ await recordPreSendRetry(fence);
1083
+ return newMutationRetry(failure(operation.operationId, "AVAILABILITY", `Gmail sent-mail search did not answer before the ${operation.requestName}`));
1084
+ }
1071
1085
  }
1072
1086
  }
1073
1087
  if (fence.decide().kind === "readBackRequired") return newMutationRetry(failure(operation.operationId, "AVAILABILITY", `Gmail ${operation.requestName} outcome is unknown; the sent-mail search found no message`));
@@ -1108,7 +1122,7 @@ var GmailSender = class {
1108
1122
  } catch {
1109
1123
  }
1110
1124
  }
1111
- return newMutationBranch(operation.providerRejectedBranch, emptySend(), receipt, failure(operation.operationId, statusFailureKind(status), operation.rejectionMessage));
1125
+ return rejectUnlessEarlierSendIsUnconfirmed(fence, operation.providerRejectedBranch, receipt, failure(operation.operationId, statusFailureKind(status), operation.rejectionMessage));
1112
1126
  }
1113
1127
  if (!sentResponse) {
1114
1128
  const lookup = await this.#pollSentMessage(call, budget, credentials, message);
@@ -1172,6 +1186,10 @@ var GmailSender = class {
1172
1186
  function failure(operation, kind, message) {
1173
1187
  return { kind, provider: "gmail", operation, message };
1174
1188
  }
1189
+ function isReadBackDecision(fence) {
1190
+ const kind = fence.decide().kind;
1191
+ return kind === "readBackRequired" || kind === "readBackThenResendAllowed";
1192
+ }
1175
1193
  async function recordPreSendRetry(fence) {
1176
1194
  if (fence.decide().kind !== "sendAllowed") return;
1177
1195
  try {
@@ -1204,10 +1222,19 @@ function retryAfterRefusal(operation, kind, message, headers) {
1204
1222
  return newMutationRetry(failure(operation, "PROTOCOL", "Gmail returned an invalid Retry-After header"));
1205
1223
  }
1206
1224
  }
1207
- function classifySourceFailure(status, headers, receipt) {
1225
+ function unavailableCredentials(fence, operation, error) {
1226
+ const isPermanent = !(error instanceof GmailCredentialError) || error.isPermanent;
1227
+ if (!isPermanent && (fence.decide().priorSendUpperBound ?? 0) > 0) return newMutationRetry(failure(operation, "AUTHENTICATION", "Gmail credentials are temporarily unavailable; an earlier send may still be delivered"));
1228
+ return defect(operation, "AUTHENTICATION", "connection credentials are unavailable");
1229
+ }
1230
+ function rejectUnlessEarlierSendIsUnconfirmed(fence, branch, receipt, rejection) {
1231
+ if ((fence.decide().priorSendUpperBound ?? 0) > 0) return newMutationRetry({ ...rejection, message: `${rejection.message}; an earlier send may still be delivered` });
1232
+ return newMutationBranch(branch, emptySend(), receipt, rejection);
1233
+ }
1234
+ function classifySourceFailure(fence, status, headers, receipt) {
1208
1235
  if (status === 0 || status === 429 || status >= 500) return retryAfterRefusal("replyToMessage", "AVAILABILITY", "Gmail source message is temporarily unavailable", headers);
1209
- if (status >= 200 && status < 300) return newMutationBranch(ReplyToMessageBranch.InvalidResponse, emptySend(), receipt, failure("replyToMessage", "PROTOCOL", "Gmail returned an invalid source message response"));
1210
- return newMutationBranch(ReplyToMessageBranch.ProviderRejected, emptySend(), receipt, failure("replyToMessage", statusFailureKind(status), "Gmail rejected the source message lookup"));
1236
+ if (status >= 200 && status < 300) return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, receipt, failure("replyToMessage", "PROTOCOL", "Gmail returned an invalid source message response"));
1237
+ return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.ProviderRejected, receipt, failure("replyToMessage", statusFailureKind(status), "Gmail rejected the source message lookup"));
1211
1238
  }
1212
1239
 
1213
1240
  // src/client.ts
package/dist/index.cjs CHANGED
@@ -295,7 +295,7 @@ var SendMessageDefinition = {
295
295
  { id: "providerRejected", description: "Gmail conclusively rejected the message.", optional: true },
296
296
  { id: "defect", description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
297
297
  ],
298
- stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 5, totalDurationMs: 12e4 } },
298
+ stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 7, totalDurationMs: 3e5 } },
299
299
  repeatOnUnknown: "limited",
300
300
  maxSends: 3
301
301
  };
@@ -317,7 +317,7 @@ var ReplyToMessageDefinition = {
317
317
  { id: "invalidResponse", description: "Gmail returned an invalid or oversized source message response before sending the reply.", optional: true },
318
318
  { id: "defect", description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
319
319
  ],
320
- stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 5, totalDurationMs: 12e4 } },
320
+ stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 7, totalDurationMs: 3e5 } },
321
321
  repeatOnUnknown: "limited",
322
322
  maxSends: 3
323
323
  };
@@ -515,9 +515,13 @@ function gmailClientSettings(config = {}) {
515
515
  return Object.freeze({ endpoint, maxResponseBytes, maxMessageBytes, addressPolicy: endpoint.startsWith("http://") ? "privateNetworkHTTP" : "publicHTTPS", pollIntervalMs, pollPageSize });
516
516
  }
517
517
  var GmailCredentialError = class extends Error {
518
- constructor() {
518
+ /** True when only reconnection can repair the failure: reauthorization or invalid material. */
519
+ isPermanent;
520
+ /** Create a secret-safe credential failure; omitted permanence means permanent. */
521
+ constructor(isPermanent = true) {
519
522
  super("connection credentials are unavailable");
520
523
  this.name = "GmailCredentialError";
524
+ this.isPermanent = isPermanent;
521
525
  }
522
526
  };
523
527
  var GmailHTTPClient = class {
@@ -539,13 +543,18 @@ var GmailHTTPClient = class {
539
543
  }
540
544
  /** Resolve a private token at call time; never put it in a receipt or Flow value. */
541
545
  async resolveCredentials(call, signal) {
546
+ let credentials;
547
+ try {
548
+ credentials = await (0, import_connectors_sdk2.resolveCredential)(this.#credentials, call, this.#refreshDriver, signal);
549
+ } catch (error) {
550
+ throw new GmailCredentialError(error instanceof import_connectors_sdk2.ReauthorizationRequiredError);
551
+ }
542
552
  try {
543
- const credentials = await (0, import_connectors_sdk2.resolveCredential)(this.#credentials, call, this.#refreshDriver, signal);
544
553
  validateCredentials(credentials);
545
- return credentials;
546
554
  } catch {
547
555
  throw new GmailCredentialError();
548
556
  }
557
+ return credentials;
549
558
  }
550
559
  /** Send one authenticated request, refreshing at most once after a 401. */
551
560
  async request(call, credentials, method, pathAndQuery, body, signal) {
@@ -1018,7 +1027,7 @@ var GmailSender = class {
1018
1027
  if (call.context.attempt < 1) return defect("sendMessage", "LOCAL_DEFECT", "Dex Execute attempt number is invalid");
1019
1028
  const messageIdAddress = this.#messageID(call);
1020
1029
  if (!messageIdAddress) return defect("sendMessage", "LOCAL_DEFECT", MissingRunIDMessage);
1021
- const fence = (0, import_singledispatch.newFence)(call, SendMessageDefinition.stepDefaults.executeMethodTimeoutMs ?? 3e4);
1030
+ const fence = (0, import_singledispatch.newFence)(call, SendMessageDefinition.stepDefaults.executeMethodTimeoutMs ?? 3e4, { maxSends: (0, import_connectors_sdk4.definitionMaxSends)(SendMessageDefinition) });
1022
1031
  if (fence.decide().kind === "failClosed") return defect("sendMessage", "LOCAL_DEFECT", "Dex send checkpoint is unreadable");
1023
1032
  const budget = new GmailSendAttemptBudget(call.context.cancellationSignal, dexDeadline);
1024
1033
  if (!budget.sendSignal()) {
@@ -1028,8 +1037,8 @@ var GmailSender = class {
1028
1037
  let credentials;
1029
1038
  try {
1030
1039
  credentials = await this.#http.resolveCredentials(call, budget.attemptSignal());
1031
- } catch {
1032
- return defect("sendMessage", "AUTHENTICATION", "connection credentials are unavailable");
1040
+ } catch (error) {
1041
+ return unavailableCredentials(fence, "sendMessage", error);
1033
1042
  }
1034
1043
  let recipients;
1035
1044
  try {
@@ -1052,7 +1061,7 @@ var GmailSender = class {
1052
1061
  if (call.context.attempt < 1) return defect("replyToMessage", "LOCAL_DEFECT", "Dex Execute attempt number is invalid");
1053
1062
  const messageIdAddress = this.#messageID(call);
1054
1063
  if (!messageIdAddress) return defect("replyToMessage", "LOCAL_DEFECT", MissingRunIDMessage);
1055
- const fence = (0, import_singledispatch.newFence)(call, ReplyToMessageDefinition.stepDefaults.executeMethodTimeoutMs ?? 3e4);
1064
+ const fence = (0, import_singledispatch.newFence)(call, ReplyToMessageDefinition.stepDefaults.executeMethodTimeoutMs ?? 3e4, { maxSends: (0, import_connectors_sdk4.definitionMaxSends)(ReplyToMessageDefinition) });
1056
1065
  if (fence.decide().kind === "failClosed") return defect("replyToMessage", "LOCAL_DEFECT", "Dex send checkpoint is unreadable");
1057
1066
  const budget = new GmailSendAttemptBudget(call.context.cancellationSignal, dexDeadline);
1058
1067
  if (!budget.sendSignal()) {
@@ -1062,12 +1071,12 @@ var GmailSender = class {
1062
1071
  let credentials;
1063
1072
  try {
1064
1073
  credentials = await this.#http.resolveCredentials(call, budget.attemptSignal());
1065
- } catch {
1066
- return defect("replyToMessage", "AUTHENTICATION", "connection credentials are unavailable");
1074
+ } catch (error) {
1075
+ return unavailableCredentials(fence, "replyToMessage", error);
1067
1076
  }
1068
1077
  if (!ReplyToMessageInputSchema.safeParse(input).success || !input.messageId.trim() || !input.textBody.trim()) return defect("replyToMessage", "VALIDATION", "message ID and text body are required");
1069
1078
  const priorProviderId = fence.decide().marker?.providerId;
1070
- if (fence.decide().kind === "readBackRequired" && priorProviderId) {
1079
+ if (isReadBackDecision(fence) && priorProviderId) {
1071
1080
  return this.#sentMessage(
1072
1081
  call,
1073
1082
  budget,
@@ -1083,8 +1092,10 @@ var GmailSender = class {
1083
1092
  const found = await this.#provider.findSentMessage(call, credentials, messageIdAddress, budget.preSendSignal());
1084
1093
  if (found) return this.#sentMessage(call, budget, credentials, ReplyToMessageOutcomes, { raw: new Uint8Array(), recipients: [], requestedThreadId: "", hasPreSendSearch: true, messageIdAddress }, found, this.#receipt(call));
1085
1094
  } catch {
1086
- await recordPreSendRetry(fence);
1087
- return (0, import_connectors_sdk4.newMutationRetry)(failure("replyToMessage", "AVAILABILITY", "Gmail sent-mail search did not answer before the reply"));
1095
+ if (fence.decide().kind !== "readBackThenResendAllowed") {
1096
+ await recordPreSendRetry(fence);
1097
+ return (0, import_connectors_sdk4.newMutationRetry)(failure("replyToMessage", "AVAILABILITY", "Gmail sent-mail search did not answer before the reply"));
1098
+ }
1088
1099
  }
1089
1100
  if (fence.decide().kind === "readBackRequired") return (0, import_connectors_sdk4.newMutationRetry)(failure("replyToMessage", "AVAILABILITY", "Gmail reply outcome is unknown; the sent-mail search found no message"));
1090
1101
  }
@@ -1095,13 +1106,13 @@ var GmailSender = class {
1095
1106
  if (error instanceof GmailCredentialError) return defect("replyToMessage", "AUTHENTICATION", "connection credentials are unavailable");
1096
1107
  const status = error instanceof import_providerhttp2.BodyTooLargeError ? error.status ?? 0 : 0;
1097
1108
  const headers = error instanceof import_providerhttp2.BodyTooLargeError ? error.headers ?? {} : {};
1098
- const result = classifySourceFailure(status, headers, this.#receipt(call));
1109
+ const result = classifySourceFailure(fence, status, headers, this.#receipt(call));
1099
1110
  if (result.kind === "retry") await recordPreSendRetry(fence);
1100
1111
  return result;
1101
1112
  }
1102
1113
  credentials = source.credentials;
1103
1114
  if (!source.resource) {
1104
- const result = classifySourceFailure(source.response.status, source.response.headers, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId));
1115
+ const result = classifySourceFailure(fence, source.response.status, source.response.headers, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId));
1105
1116
  if (result.kind === "retry") await recordPreSendRetry(fence);
1106
1117
  return result;
1107
1118
  }
@@ -1109,16 +1120,16 @@ var GmailSender = class {
1109
1120
  try {
1110
1121
  message = decodeGmailMessage(source.resource);
1111
1122
  } catch {
1112
- return (0, import_connectors_sdk4.newMutationBranch)(ReplyToMessageBranch.InvalidResponse, emptySend(), this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "source message lacks reply metadata"));
1123
+ return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "source message lacks reply metadata"));
1113
1124
  }
1114
- if (!message.threadId || !message.rfcMessageId) return (0, import_connectors_sdk4.newMutationBranch)(ReplyToMessageBranch.InvalidResponse, emptySend(), this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "source message lacks reply metadata"));
1125
+ if (!message.threadId || !message.rfcMessageId) return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "source message lacks reply metadata"));
1115
1126
  let recipient;
1116
1127
  try {
1117
1128
  recipient = replyRecipient(message);
1118
1129
  } catch {
1119
- return (0, import_connectors_sdk4.newMutationBranch)(ReplyToMessageBranch.InvalidResponse, emptySend(), this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "Gmail returned an invalid source sender"));
1130
+ return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "Gmail returned an invalid source sender"));
1120
1131
  }
1121
- if (/[\r\n]/.test(message.subject + message.rfcMessageId + (message.references ?? ""))) return (0, import_connectors_sdk4.newMutationBranch)(ReplyToMessageBranch.InvalidResponse, emptySend(), this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "Gmail returned invalid source reply headers"));
1132
+ if (/[\r\n]/.test(message.subject + message.rfcMessageId + (message.references ?? ""))) return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, this.#receipt(call, gmailRequestID(source.response.headers), input.messageId), failure("replyToMessage", "PROTOCOL", "Gmail returned invalid source reply headers"));
1122
1133
  let raw;
1123
1134
  try {
1124
1135
  raw = buildReplyMIMEMessage(call.id, call.idempotencyKey ?? call.id, messageIdAddress, credentials.primaryEmail, message, input);
@@ -1130,7 +1141,7 @@ var GmailSender = class {
1130
1141
  }
1131
1142
  async #sendAndConfirm(call, fence, budget, credentials, operation, message) {
1132
1143
  const priorProviderId = fence.decide().marker?.providerId;
1133
- if (fence.decide().kind === "readBackRequired" && priorProviderId) {
1144
+ if (isReadBackDecision(fence) && priorProviderId) {
1134
1145
  return this.#sentMessage(
1135
1146
  call,
1136
1147
  budget,
@@ -1146,8 +1157,10 @@ var GmailSender = class {
1146
1157
  const found = await this.#provider.findSentMessage(call, credentials, message.messageIdAddress, budget.preSendSignal());
1147
1158
  if (found) return this.#sentMessage(call, budget, credentials, operation, message, found, this.#receipt(call));
1148
1159
  } catch {
1149
- await recordPreSendRetry(fence);
1150
- return (0, import_connectors_sdk4.newMutationRetry)(failure(operation.operationId, "AVAILABILITY", `Gmail sent-mail search did not answer before the ${operation.requestName}`));
1160
+ if (fence.decide().kind !== "readBackThenResendAllowed") {
1161
+ await recordPreSendRetry(fence);
1162
+ return (0, import_connectors_sdk4.newMutationRetry)(failure(operation.operationId, "AVAILABILITY", `Gmail sent-mail search did not answer before the ${operation.requestName}`));
1163
+ }
1151
1164
  }
1152
1165
  }
1153
1166
  if (fence.decide().kind === "readBackRequired") return (0, import_connectors_sdk4.newMutationRetry)(failure(operation.operationId, "AVAILABILITY", `Gmail ${operation.requestName} outcome is unknown; the sent-mail search found no message`));
@@ -1188,7 +1201,7 @@ var GmailSender = class {
1188
1201
  } catch {
1189
1202
  }
1190
1203
  }
1191
- return (0, import_connectors_sdk4.newMutationBranch)(operation.providerRejectedBranch, emptySend(), receipt, failure(operation.operationId, statusFailureKind(status), operation.rejectionMessage));
1204
+ return rejectUnlessEarlierSendIsUnconfirmed(fence, operation.providerRejectedBranch, receipt, failure(operation.operationId, statusFailureKind(status), operation.rejectionMessage));
1192
1205
  }
1193
1206
  if (!sentResponse) {
1194
1207
  const lookup = await this.#pollSentMessage(call, budget, credentials, message);
@@ -1252,6 +1265,10 @@ var GmailSender = class {
1252
1265
  function failure(operation, kind, message) {
1253
1266
  return { kind, provider: "gmail", operation, message };
1254
1267
  }
1268
+ function isReadBackDecision(fence) {
1269
+ const kind = fence.decide().kind;
1270
+ return kind === "readBackRequired" || kind === "readBackThenResendAllowed";
1271
+ }
1255
1272
  async function recordPreSendRetry(fence) {
1256
1273
  if (fence.decide().kind !== "sendAllowed") return;
1257
1274
  try {
@@ -1284,10 +1301,19 @@ function retryAfterRefusal(operation, kind, message, headers) {
1284
1301
  return (0, import_connectors_sdk4.newMutationRetry)(failure(operation, "PROTOCOL", "Gmail returned an invalid Retry-After header"));
1285
1302
  }
1286
1303
  }
1287
- function classifySourceFailure(status, headers, receipt) {
1304
+ function unavailableCredentials(fence, operation, error) {
1305
+ const isPermanent = !(error instanceof GmailCredentialError) || error.isPermanent;
1306
+ if (!isPermanent && (fence.decide().priorSendUpperBound ?? 0) > 0) return (0, import_connectors_sdk4.newMutationRetry)(failure(operation, "AUTHENTICATION", "Gmail credentials are temporarily unavailable; an earlier send may still be delivered"));
1307
+ return defect(operation, "AUTHENTICATION", "connection credentials are unavailable");
1308
+ }
1309
+ function rejectUnlessEarlierSendIsUnconfirmed(fence, branch, receipt, rejection) {
1310
+ if ((fence.decide().priorSendUpperBound ?? 0) > 0) return (0, import_connectors_sdk4.newMutationRetry)({ ...rejection, message: `${rejection.message}; an earlier send may still be delivered` });
1311
+ return (0, import_connectors_sdk4.newMutationBranch)(branch, emptySend(), receipt, rejection);
1312
+ }
1313
+ function classifySourceFailure(fence, status, headers, receipt) {
1288
1314
  if (status === 0 || status === 429 || status >= 500) return retryAfterRefusal("replyToMessage", "AVAILABILITY", "Gmail source message is temporarily unavailable", headers);
1289
- if (status >= 200 && status < 300) return (0, import_connectors_sdk4.newMutationBranch)(ReplyToMessageBranch.InvalidResponse, emptySend(), receipt, failure("replyToMessage", "PROTOCOL", "Gmail returned an invalid source message response"));
1290
- return (0, import_connectors_sdk4.newMutationBranch)(ReplyToMessageBranch.ProviderRejected, emptySend(), receipt, failure("replyToMessage", statusFailureKind(status), "Gmail rejected the source message lookup"));
1315
+ if (status >= 200 && status < 300) return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.InvalidResponse, receipt, failure("replyToMessage", "PROTOCOL", "Gmail returned an invalid source message response"));
1316
+ return rejectUnlessEarlierSendIsUnconfirmed(fence, ReplyToMessageBranch.ProviderRejected, receipt, failure("replyToMessage", statusFailureKind(status), "Gmail rejected the source message lookup"));
1291
1317
  }
1292
1318
 
1293
1319
  // src/client.ts
package/dist/index.d.cts CHANGED
@@ -106,7 +106,10 @@ interface GmailClientSettings {
106
106
  declare function gmailClientSettings(config?: Config): GmailClientSettings;
107
107
  /** Failure after credential lookup or credential validation. */
108
108
  declare class GmailCredentialError extends Error {
109
- constructor();
109
+ /** True when only reconnection can repair the failure: reauthorization or invalid material. */
110
+ readonly isPermanent: boolean;
111
+ /** Create a secret-safe credential failure; omitted permanence means permanent. */
112
+ constructor(isPermanent?: boolean);
110
113
  }
111
114
  /** Credential-safe HTTP client shared by all three operations. */
112
115
  declare class GmailHTTPClient {
package/dist/index.d.ts CHANGED
@@ -106,7 +106,10 @@ interface GmailClientSettings {
106
106
  declare function gmailClientSettings(config?: Config): GmailClientSettings;
107
107
  /** Failure after credential lookup or credential validation. */
108
108
  declare class GmailCredentialError extends Error {
109
- constructor();
109
+ /** True when only reconnection can repair the failure: reauthorization or invalid material. */
110
+ readonly isPermanent: boolean;
111
+ /** Create a secret-safe credential failure; omitted permanence means permanent. */
112
+ constructor(isPermanent?: boolean);
110
113
  }
111
114
  /** Credential-safe HTTP client shared by all three operations. */
112
115
  declare class GmailHTTPClient {
package/dist/index.js CHANGED
@@ -63,7 +63,7 @@ import {
63
63
  rfcMessageIDAddress,
64
64
  statusFailureKind,
65
65
  validateSendInput
66
- } from "./chunk-PW3NTBVH.js";
66
+ } from "./chunk-ALVG4HS2.js";
67
67
  export {
68
68
  ConnectorID,
69
69
  GetMessageBranch,
@@ -178,7 +178,7 @@ var SendMessageDefinition = {
178
178
  { id: "providerRejected", description: "Gmail conclusively rejected the message.", optional: true },
179
179
  { id: "defect", description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
180
180
  ],
181
- stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 5, totalDurationMs: 12e4 } },
181
+ stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 7, totalDurationMs: 3e5 } },
182
182
  repeatOnUnknown: "limited",
183
183
  maxSends: 3
184
184
  };
@@ -200,7 +200,7 @@ var ReplyToMessageDefinition = {
200
200
  { id: "invalidResponse", description: "Gmail returned an invalid or oversized source message response before sending the reply.", optional: true },
201
201
  { id: "defect", description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
202
202
  ],
203
- stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 5, totalDurationMs: 12e4 } },
203
+ stepDefaults: { executeMethodTimeoutMs: 3e4, executeDurability: "sync", executeRetry: { initialIntervalMs: 1e3, backoffCoefficient: 2, maximumIntervalMs: 3e4, maximumAttempts: 7, totalDurationMs: 3e5 } },
204
204
  repeatOnUnknown: "limited",
205
205
  maxSends: 3
206
206
  };
@@ -10,7 +10,7 @@ import {
10
10
  SendMessageInputSchema,
11
11
  SendMessageOutputSchema,
12
12
  SendMessageOutputSchema2
13
- } from "../chunk-PW3NTBVH.js";
13
+ } from "../chunk-ALVG4HS2.js";
14
14
 
15
15
  // src/mock/index.ts
16
16
  import { branchCase as branchCase2, newMutation as newMutation2, newQuery as newQuery2, retryCase as retryCase2, uncertainCase } from "@superdurable/connectors-sdk/connectormock";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@superdurable/connector-google-gmail",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "license": "MIT",
5
5
  "description": "Dex Gmail connector for TypeScript",
6
6
  "repository": {