@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/dist/index.d.cts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { M as Message, R as ReplyToMessageInput, S as SendMessageInput, C as Config, a as CredentialSource, b as Credentials, c as SendMessageOutput, G as GetMessageInput, d as GmailOperations, e as GmailConnection } from './connection-D8OV_Hfe.cjs';
2
2
  export { f as ConnectorID, g as GetMessageInputSchema, h as GoogleOAuthAuthMethodID, i as MessageSchema, P as ProviderID, j as ReplyToMessageInputSchema, k as SendMessageInputSchema, l as SendMessageOutputSchema, W as WorkspaceDomainDelegationAuthMethodID } from './connection-D8OV_Hfe.cjs';
3
3
  import * as _superdurable_connectors_sdk from '@superdurable/connectors-sdk';
4
- import { QueryDefinition, MutationDefinition, CredentialRefreshDriver, Call, FailureKind, CredentialRefreshState, CredentialRefreshResult, Mutation, MutationAttempt, Query, QueryAttempt, Failure, ReceiptDraft, QueryStepConfig, QueryResult, MutationStepConfig, MutationResult, QueryStep, MutationStep } from '@superdurable/connectors-sdk';
4
+ import { QueryDefinition, MutationDefinition, CredentialRefreshDriver, Call, FailureKind, CredentialRefreshState, CredentialRefreshResult, Mutation, MutationAttempt, Query, QueryAttempt, TriggerLogger, Failure, ReceiptDraft, QueryStepConfig, QueryResult, MutationStepConfig, MutationResult, QueryStep, MutationStep, ConnectionRef, TriggerContext, TriggerTarget, ConnectorConfigurationUI, TriggerDefinition, TriggerBindingDefinition, TriggerRunner } from '@superdurable/connectors-sdk';
5
5
  import { z } from 'zod';
6
6
  import { ProviderRequest, ProviderResponse, AddressPolicy } from '@superdurable/connectors-sdk/providerhttp';
7
7
  import { LoadedProject } from '@superdurable/connectors-sdk/projectconfig';
@@ -99,12 +99,17 @@ interface GmailClientSettings {
99
99
  /** Maximum complete response bytes. */ readonly maxResponseBytes: number;
100
100
  /** Maximum encoded MIME message bytes. */ readonly maxMessageBytes: number;
101
101
  /** Address policy for the configured endpoint. */ readonly addressPolicy: AddressPolicy;
102
+ /** Delay between Trigger polls in milliseconds. */ readonly pollIntervalMs: number;
103
+ /** Recent inbox messages inspected per Trigger poll. */ readonly pollPageSize: number;
102
104
  }
103
105
  /** Apply and validate the Gmail manifest's transport defaults. */
104
106
  declare function gmailClientSettings(config?: Config): GmailClientSettings;
105
107
  /** Failure after credential lookup or credential validation. */
106
108
  declare class GmailCredentialError extends Error {
107
- 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);
108
113
  }
109
114
  /** Credential-safe HTTP client shared by all three operations. */
110
115
  declare class GmailHTTPClient {
@@ -128,6 +133,11 @@ declare function gmailRetryAfterMs(headers: Record<string, string | string[] | u
128
133
  /** Read the safe Gmail request correlation ID. */
129
134
  declare function gmailRequestID(headers: Record<string, string | string[] | undefined>): string;
130
135
 
136
+ /** One message reference in an inbox listing, newest first as Gmail lists it. */
137
+ interface GmailMessageReference {
138
+ /** Gmail message ID; empty when Gmail omitted it. */ id: string;
139
+ /** Gmail thread ID; empty when Gmail omitted it. */ threadId: string;
140
+ }
131
141
  /** Provider identity returned by a Gmail send or Sent Mail lookup. */
132
142
  interface SentMessageIdentity {
133
143
  /** Gmail message ID. */ id: string;
@@ -146,6 +156,14 @@ declare class GmailProvider {
146
156
  constructor(http: GmailHTTPClient);
147
157
  /** Read one full or metadata message, returning the raw response on refusal or malformed JSON. */
148
158
  readMessage(call: Call, credentials: Credentials, messageId: string, format: 'full' | 'metadata' | 'minimal', signal?: AbortSignal): Promise<GmailReadResult>;
159
+ /**
160
+ * List the newest inbox page that matches searchQuery, as the Go Trigger poller does. It rejects with
161
+ * an error that names no query value when Gmail does not answer 2xx with a usable listing.
162
+ */
163
+ listInboxMessages(call: Call, credentials: Credentials, searchQuery: string, pageSize: number, signal?: AbortSignal): Promise<{
164
+ messages: GmailMessageReference[];
165
+ credentials: Credentials;
166
+ }>;
149
167
  /** Search Sent Mail once for the run-specific RFC Message-ID. */
150
168
  findSentMessage(call: Call, credentials: Credentials, messageIdAddress: string, signal?: AbortSignal): Promise<SentMessageIdentity | undefined>;
151
169
  /** Post one encoded Gmail messages.send request without redirects or transport replay. */
@@ -174,7 +192,7 @@ declare class SendMessageOperation implements Mutation<SendMessageInput, SendMes
174
192
  /** Inject the provider sender used by each Dex attempt. */
175
193
  constructor(sender: GmailSender);
176
194
  /** Return the immutable manifest operation definition. */
177
- definition(): _superdurable_connectors_sdk.QueryDefinition;
195
+ definition(): _superdurable_connectors_sdk.MutationDefinition;
178
196
  /** Use the stable connector Call ID as the send correlation key. */
179
197
  idempotencyKey(callId: string, input: SendMessageInput): string;
180
198
  /** Classify a send using Dex's public current-attempt deadline. */
@@ -186,7 +204,7 @@ declare class ReplyToMessageOperation implements Mutation<ReplyToMessageInput, S
186
204
  /** Inject the provider sender used by each Dex attempt. */
187
205
  constructor(sender: GmailSender);
188
206
  /** Return the immutable manifest operation definition. */
189
- definition(): _superdurable_connectors_sdk.QueryDefinition;
207
+ definition(): _superdurable_connectors_sdk.MutationDefinition;
190
208
  /** Use the stable connector Call ID as the reply correlation key. */
191
209
  idempotencyKey(callId: string, input: ReplyToMessageInput): string;
192
210
  /** Classify a reply using Dex's public current-attempt deadline. */
@@ -211,12 +229,25 @@ interface GmailClientOptions {
211
229
  transport?: GmailTransport;
212
230
  /** Observation clock for receipts. */
213
231
  now?: () => Date;
232
+ /**
233
+ * Receives the Trigger pollers' records: failed polls, ignored and skipped messages, delivery retries,
234
+ * and the durable inboxes that newProjectMessageTriggerRunner creates. Omitted uses
235
+ * defaultTriggerLogger. Records carry message and thread IDs, never senders, subjects, snippets,
236
+ * bodies, or tokens.
237
+ */
238
+ logger?: TriggerLogger;
214
239
  }
215
240
  /** Gmail connection with operation-specific provider interfaces. */
216
241
  declare class GmailClient implements GmailOperations {
217
242
  #private;
243
+ /** Trigger record destination. */ readonly triggerLogger: TriggerLogger;
218
244
  /** Validate settings and inject a host-owned credential source. */
219
245
  constructor(config: Config, credentials: CredentialSource, options?: GmailClientOptions);
246
+ /** @internal The authenticated transport and provider methods that the Trigger pollers share. */
247
+ triggerTransport(): {
248
+ http: GmailHTTPClient;
249
+ provider: GmailProvider;
250
+ };
220
251
  /** Return the getMessage Query bound to this connection. */
221
252
  getMessage(): GetMessageOperation;
222
253
  /** Return the sendMessage Mutation bound to this connection. */
@@ -280,4 +311,180 @@ declare function newSendMessageStep<StepInput>(configuration: SendMessageStepCon
280
311
  /** Build a Gmail reply Step with its typed connection. */
281
312
  declare function newReplyToMessageStep<StepInput>(configuration: ReplyToMessageStepConfig<StepInput>): MutationStep<StepInput, ReplyToMessageInput, SendMessageOutput>;
282
313
 
283
- export { Config, CredentialSource, Credentials, GetMessageBranch, GetMessageDefinition, GetMessageInput, GetMessageOperation, type GetMessageStepConfig, GmailClient, type GmailClientOptions, type GmailClientSettings, GmailConnection, GmailCredentialError, GmailCredentialRefreshDriver, GmailHTTPClient, type GmailMessagePart, type GmailMessageResource, GmailMessageResourceSchema, GmailOperations, GmailProvider, type GmailReadResult, type GmailTransport, Message, ReplyToMessageBranch, ReplyToMessageDefinition, ReplyToMessageInput, ReplyToMessageOperation, type ReplyToMessageStepConfig, SendMessageBranch, SendMessageDefinition, SendMessageInput, SendMessageOperation, SendMessageOutput, type SendMessageStepConfig, type SentMessageIdentity, buildMIMEMessage, buildReplyMIMEMessage, decodeGmailMessage, emptyMessage, gmailClientSettings, gmailFailure, gmailRequestID, gmailRetryAfterMs, newGetMessageStep, newProjectConnection, newProjectGmailClient, newReplyToMessageStep, newSendMessageStep, parseMailbox, parseSentResponse, receiptFor, replyRecipient, rfcMessageIDAddress, statusFailureKind, validateSendInput };
314
+ /** One poller's source and the target it delivers to. */
315
+ interface MessageTriggerRoute {
316
+ source: MessagePollingTriggerSource;
317
+ target: TriggerTarget<MessageEvent>;
318
+ }
319
+ /** One inbox list call, delivered later by MessagePollingTriggerSource.deliver. */
320
+ interface MessageListing {
321
+ credentials: Credentials;
322
+ messages: GmailMessageReference[];
323
+ }
324
+ /**
325
+ * Polls one Gmail binding: it lists the newest inbox page, reads each new message's metadata, and
326
+ * delivers matching roots or replies oldest first, as the Go connector's poller does. The delivered set
327
+ * covers the last listed page in memory; a restart rescans the page, and the Flow start request ID and
328
+ * the application's RPC absorb the duplicates.
329
+ */
330
+ declare class MessagePollingTriggerSource {
331
+ #private;
332
+ /** Bind one binding's query and matcher; an empty bindingName omits the binding log attribute. */
333
+ constructor(client: GmailClient, connection: ConnectionRef, triggerName: string, bindingName: string, searchQuery: string, matcher: MessageMatcher, requiresReply: boolean);
334
+ /** Scan, then wait one poll interval, until the context ends. */
335
+ run(context: TriggerContext, target: TriggerTarget<MessageEvent>): Promise<void>;
336
+ /** List the inbox and deliver the listed messages. */
337
+ scan(context: TriggerContext, target: TriggerTarget<MessageEvent>): Promise<void>;
338
+ /** Read the newest inbox page that matches the source's search query. */
339
+ list(context: TriggerContext): Promise<MessageListing>;
340
+ /**
341
+ * Hand target the event that failed on an earlier poll, if any, then every new matching message in
342
+ * listing, oldest first. It stops at the first failure, so the next poll retries that event before any
343
+ * later message, even after newer mail pushes it off the listed page.
344
+ */
345
+ deliver(context: TriggerContext, target: TriggerTarget<MessageEvent>, listing: MessageListing): Promise<void>;
346
+ }
347
+
348
+ /** Filters received Gmail messages by sender and text. */
349
+ declare const MessageMatcherSchema: z.ZodObject<{
350
+ messageContains: z.ZodOptional<z.ZodString>;
351
+ senderEmails: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
352
+ }, z.core.$strict>;
353
+ /** Sender and text filter of one Gmail message Trigger binding. */
354
+ type MessageMatcher = z.infer<typeof MessageMatcherSchema>;
355
+ /** Configuration of messageReceived: an optional Gmail search query and the root-message matcher. */
356
+ declare const MessageReceivedTriggerConfigurationSchema: z.ZodObject<{
357
+ searchQuery: z.ZodOptional<z.ZodString>;
358
+ messageMatcher: z.ZodOptional<z.ZodObject<{
359
+ messageContains: z.ZodOptional<z.ZodString>;
360
+ senderEmails: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
361
+ }, z.core.$strict>>;
362
+ }, z.core.$strict>;
363
+ /** Search query and root-message matcher of one messageReceived binding. */
364
+ type MessageReceivedTriggerConfiguration = z.infer<typeof MessageReceivedTriggerConfigurationSchema>;
365
+ /** Configuration of replyReceived: an optional Gmail search query and the reply matcher. */
366
+ declare const ReplyReceivedTriggerConfigurationSchema: z.ZodObject<{
367
+ searchQuery: z.ZodOptional<z.ZodString>;
368
+ replyMatcher: z.ZodOptional<z.ZodObject<{
369
+ messageContains: z.ZodOptional<z.ZodString>;
370
+ senderEmails: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
371
+ }, z.core.$strict>>;
372
+ }, z.core.$strict>;
373
+ /** Search query and reply matcher of one replyReceived binding. */
374
+ type ReplyReceivedTriggerConfiguration = z.infer<typeof ReplyReceivedTriggerConfigurationSchema>;
375
+ /** The metadata-only payload of both Gmail Triggers; field names and order match the Go connector. */
376
+ declare const MessageEventSchema: z.ZodObject<{
377
+ primaryEmail: z.ZodString;
378
+ messageId: z.ZodString;
379
+ threadId: z.ZodString;
380
+ from: z.ZodString;
381
+ subject: z.ZodString;
382
+ snippet: z.ZodOptional<z.ZodString>;
383
+ receivedAt: z.ZodString;
384
+ isReply: z.ZodBoolean;
385
+ }, z.core.$strip>;
386
+ /** One received Gmail message. */
387
+ type MessageEvent = z.infer<typeof MessageEventSchema>;
388
+ /** Manifest definition of messageReceived. */
389
+ declare const MessageReceivedTriggerDefinition: TriggerDefinition;
390
+ /** Manifest definition of replyReceived. */
391
+ declare const ReplyReceivedTriggerDefinition: TriggerDefinition;
392
+ /** Gmail search query input UI unit. */ declare const UIUnitSearchQueryInput = "searchQueryInput";
393
+ /** Search query input output port. */ declare const UISearchQueryInputPortQuery = "query";
394
+ /** Email address list input UI unit. */ declare const UIUnitEmailListInput = "emailListInput";
395
+ /** Email list input output port. */ declare const UIEmailListInputPortEmails = "emails";
396
+ /** Plain text input UI unit. */ declare const UIUnitTextInput = "textInput";
397
+ /** Text input output port. */ declare const UITextInputPortText = "text";
398
+ /** One static application binding of a Gmail message Trigger. */
399
+ interface GmailTriggerBindingConfig {
400
+ /** Static connection name. */ connectionName: string;
401
+ /** Static binding name. */ bindingName: string;
402
+ /** Connector Studio configuration units for the binding. */ configurationUI: ConnectorConfigurationUI;
403
+ }
404
+ /** Declare a static messageReceived binding for Flow Definition tooling and Dex Web. */
405
+ declare function defineMessageReceivedTriggerBinding(config: GmailTriggerBindingConfig): TriggerBindingDefinition;
406
+ /** Declare a static replyReceived binding for Flow Definition tooling and Dex Web. */
407
+ declare function defineReplyReceivedTriggerBinding(config: GmailTriggerBindingConfig): TriggerBindingDefinition;
408
+ /** Configuration of one standalone Gmail message Trigger. */
409
+ interface GmailMessageTriggerConfig<Configuration> {
410
+ /** Gmail connection bound to a GmailClient. */ connection: GmailConnection;
411
+ /** Static connection name; must equal the connection's name. */ connectionName: string;
412
+ /** Static binding name. */ bindingName: string;
413
+ /** Search query and matcher. */ configuration: Configuration;
414
+ /** Routes accepted events into the application. */ target: TriggerTarget<MessageEvent>;
415
+ }
416
+ /**
417
+ * Create one messageReceived Trigger that polls on its own. Prefer one MessageTriggerRunner per
418
+ * connection, which delivers every root before any reply.
419
+ */
420
+ declare function newMessageReceivedTrigger(config: GmailMessageTriggerConfig<MessageReceivedTriggerConfiguration>): TriggerRunner;
421
+ /**
422
+ * Create one replyReceived Trigger that polls on its own. Prefer one MessageTriggerRunner per
423
+ * connection, which delivers every root before any reply.
424
+ */
425
+ declare function newReplyReceivedTrigger(config: GmailMessageTriggerConfig<ReplyReceivedTriggerConfiguration>): TriggerRunner;
426
+ /** One root-message binding and its application target. */
427
+ interface MessageReceivedTriggerRoute {
428
+ /** Configured binding name. */ bindingName: string;
429
+ /** Search query and root-message matcher. */ configuration: MessageReceivedTriggerConfiguration;
430
+ /** Routes accepted events into the application. */ target: TriggerTarget<MessageEvent>;
431
+ }
432
+ /** One reply binding and its application target. */
433
+ interface ReplyReceivedTriggerRoute {
434
+ /** Configured binding name. */ bindingName: string;
435
+ /** Search query and reply matcher. */ configuration: ReplyReceivedTriggerConfiguration;
436
+ /** Routes accepted events into the application. */ target: TriggerTarget<MessageEvent>;
437
+ }
438
+ /** Gmail message Triggers that share one ordered poller. */
439
+ interface MessageTriggerRunnerConfig {
440
+ /** Gmail connection bound to a GmailClient. */ connection: GmailConnection;
441
+ /** Root-message bindings. */ messageReceivedRoutes?: readonly MessageReceivedTriggerRoute[];
442
+ /** Reply bindings. */ replyReceivedRoutes?: readonly ReplyReceivedTriggerRoute[];
443
+ }
444
+ /** One root-message binding saved in the project configuration and its application target. */
445
+ interface ProjectMessageReceivedTriggerRoute {
446
+ bindingName: string; /** Application target. */
447
+ target: TriggerTarget<MessageEvent>;
448
+ }
449
+ /** One reply binding saved in the project configuration and its application target. */
450
+ interface ProjectReplyReceivedTriggerRoute {
451
+ bindingName: string; /** Application target. */
452
+ target: TriggerTarget<MessageEvent>;
453
+ }
454
+ /** Gmail message Trigger bindings selected from the project configuration. */
455
+ interface ProjectMessageTriggerRunnerConfig {
456
+ /** Root-message bindings. */ messageReceivedRoutes?: readonly ProjectMessageReceivedTriggerRoute[];
457
+ /** Reply bindings. */ replyReceivedRoutes?: readonly ProjectReplyReceivedTriggerRoute[];
458
+ }
459
+ /** Polls every configured Gmail route of one connection and delivers root messages before replies. */
460
+ declare class MessageTriggerRunner {
461
+ #private;
462
+ /** @internal Use newMessageTriggerRunner or newProjectMessageTriggerRunner. */
463
+ constructor(rootRoutes: readonly MessageTriggerRoute[], replyRoutes: readonly MessageTriggerRoute[], pollIntervalMs: number);
464
+ /**
465
+ * Replay each route's durable inbox in order, roots first, then poll until the context ends. Each poll
466
+ * lists every reply route before any root route, then delivers every root before any reply, and ends
467
+ * at the first failure. Every later poll retries the failed event before that route's listed messages,
468
+ * even after Gmail stops listing it. Gmail receives a thread's root before any reply to it, so the
469
+ * root of every listed reply is in the later root listing and reaches Dex first.
470
+ *
471
+ * It logs through the client's logger: WARN "gmail poll failed; retrying" with the consecutive failed
472
+ * polls as attempt and the poll interval as delay_ms when a list or read fails, WARN "trigger delivery
473
+ * failed; retrying" with the attempt number when a target fails, INFO "trigger delivered after retry"
474
+ * when a later poll delivers that message, DEBUG "trigger event ignored" with its reason, and the
475
+ * durable inbox records. It rejects with TriggerDeliveryAbortedError once the context ends, and when
476
+ * an inbox replay fails.
477
+ */
478
+ run(context: TriggerContext): Promise<void>;
479
+ }
480
+ /** Create one ordered runner for every configured Gmail message Trigger route of a connection; throws on invalid wiring. */
481
+ declare function newMessageTriggerRunner(config: MessageTriggerRunnerConfig): MessageTriggerRunner;
482
+ /**
483
+ * Open connectionName from the loaded project, load the selected bindings' saved configuration, and
484
+ * create one durable, ordered runner. Each route keeps acknowledged events in its binding's project
485
+ * Trigger inbox until its target consumes them, so a restarted or replaced replica replays them. A
486
+ * route whose binding is not configured throws. The options' logger also applies to those inboxes.
487
+ */
488
+ declare function newProjectMessageTriggerRunner(project: LoadedProject, connectionName: string, config: ProjectMessageTriggerRunnerConfig, options?: GmailClientOptions): MessageTriggerRunner;
489
+
490
+ export { Config, CredentialSource, Credentials, GetMessageBranch, GetMessageDefinition, GetMessageInput, GetMessageOperation, type GetMessageStepConfig, GmailClient, type GmailClientOptions, type GmailClientSettings, GmailConnection, GmailCredentialError, GmailCredentialRefreshDriver, GmailHTTPClient, type GmailMessagePart, type GmailMessageReference, type GmailMessageResource, GmailMessageResourceSchema, type GmailMessageTriggerConfig, GmailOperations, GmailProvider, type GmailReadResult, type GmailTransport, type GmailTriggerBindingConfig, Message, type MessageEvent, MessageEventSchema, type MessageMatcher, MessageMatcherSchema, type MessageReceivedTriggerConfiguration, MessageReceivedTriggerConfigurationSchema, MessageReceivedTriggerDefinition, type MessageReceivedTriggerRoute, MessageTriggerRunner, type MessageTriggerRunnerConfig, type ProjectMessageReceivedTriggerRoute, type ProjectMessageTriggerRunnerConfig, type ProjectReplyReceivedTriggerRoute, type ReplyReceivedTriggerConfiguration, ReplyReceivedTriggerConfigurationSchema, ReplyReceivedTriggerDefinition, type ReplyReceivedTriggerRoute, ReplyToMessageBranch, ReplyToMessageDefinition, ReplyToMessageInput, ReplyToMessageOperation, type ReplyToMessageStepConfig, SendMessageBranch, SendMessageDefinition, SendMessageInput, SendMessageOperation, SendMessageOutput, type SendMessageStepConfig, type SentMessageIdentity, UIEmailListInputPortEmails, UISearchQueryInputPortQuery, UITextInputPortText, UIUnitEmailListInput, UIUnitSearchQueryInput, UIUnitTextInput, buildMIMEMessage, buildReplyMIMEMessage, decodeGmailMessage, defineMessageReceivedTriggerBinding, defineReplyReceivedTriggerBinding, emptyMessage, gmailClientSettings, gmailFailure, gmailRequestID, gmailRetryAfterMs, newGetMessageStep, newMessageReceivedTrigger, newMessageTriggerRunner, newProjectConnection, newProjectGmailClient, newProjectMessageTriggerRunner, newReplyReceivedTrigger, newReplyToMessageStep, newSendMessageStep, parseMailbox, parseSentResponse, receiptFor, replyRecipient, rfcMessageIDAddress, statusFailureKind, validateSendInput };
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { M as Message, R as ReplyToMessageInput, S as SendMessageInput, C as Config, a as CredentialSource, b as Credentials, c as SendMessageOutput, G as GetMessageInput, d as GmailOperations, e as GmailConnection } from './connection-D8OV_Hfe.js';
2
2
  export { f as ConnectorID, g as GetMessageInputSchema, h as GoogleOAuthAuthMethodID, i as MessageSchema, P as ProviderID, j as ReplyToMessageInputSchema, k as SendMessageInputSchema, l as SendMessageOutputSchema, W as WorkspaceDomainDelegationAuthMethodID } from './connection-D8OV_Hfe.js';
3
3
  import * as _superdurable_connectors_sdk from '@superdurable/connectors-sdk';
4
- import { QueryDefinition, MutationDefinition, CredentialRefreshDriver, Call, FailureKind, CredentialRefreshState, CredentialRefreshResult, Mutation, MutationAttempt, Query, QueryAttempt, Failure, ReceiptDraft, QueryStepConfig, QueryResult, MutationStepConfig, MutationResult, QueryStep, MutationStep } from '@superdurable/connectors-sdk';
4
+ import { QueryDefinition, MutationDefinition, CredentialRefreshDriver, Call, FailureKind, CredentialRefreshState, CredentialRefreshResult, Mutation, MutationAttempt, Query, QueryAttempt, TriggerLogger, Failure, ReceiptDraft, QueryStepConfig, QueryResult, MutationStepConfig, MutationResult, QueryStep, MutationStep, ConnectionRef, TriggerContext, TriggerTarget, ConnectorConfigurationUI, TriggerDefinition, TriggerBindingDefinition, TriggerRunner } from '@superdurable/connectors-sdk';
5
5
  import { z } from 'zod';
6
6
  import { ProviderRequest, ProviderResponse, AddressPolicy } from '@superdurable/connectors-sdk/providerhttp';
7
7
  import { LoadedProject } from '@superdurable/connectors-sdk/projectconfig';
@@ -99,12 +99,17 @@ interface GmailClientSettings {
99
99
  /** Maximum complete response bytes. */ readonly maxResponseBytes: number;
100
100
  /** Maximum encoded MIME message bytes. */ readonly maxMessageBytes: number;
101
101
  /** Address policy for the configured endpoint. */ readonly addressPolicy: AddressPolicy;
102
+ /** Delay between Trigger polls in milliseconds. */ readonly pollIntervalMs: number;
103
+ /** Recent inbox messages inspected per Trigger poll. */ readonly pollPageSize: number;
102
104
  }
103
105
  /** Apply and validate the Gmail manifest's transport defaults. */
104
106
  declare function gmailClientSettings(config?: Config): GmailClientSettings;
105
107
  /** Failure after credential lookup or credential validation. */
106
108
  declare class GmailCredentialError extends Error {
107
- 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);
108
113
  }
109
114
  /** Credential-safe HTTP client shared by all three operations. */
110
115
  declare class GmailHTTPClient {
@@ -128,6 +133,11 @@ declare function gmailRetryAfterMs(headers: Record<string, string | string[] | u
128
133
  /** Read the safe Gmail request correlation ID. */
129
134
  declare function gmailRequestID(headers: Record<string, string | string[] | undefined>): string;
130
135
 
136
+ /** One message reference in an inbox listing, newest first as Gmail lists it. */
137
+ interface GmailMessageReference {
138
+ /** Gmail message ID; empty when Gmail omitted it. */ id: string;
139
+ /** Gmail thread ID; empty when Gmail omitted it. */ threadId: string;
140
+ }
131
141
  /** Provider identity returned by a Gmail send or Sent Mail lookup. */
132
142
  interface SentMessageIdentity {
133
143
  /** Gmail message ID. */ id: string;
@@ -146,6 +156,14 @@ declare class GmailProvider {
146
156
  constructor(http: GmailHTTPClient);
147
157
  /** Read one full or metadata message, returning the raw response on refusal or malformed JSON. */
148
158
  readMessage(call: Call, credentials: Credentials, messageId: string, format: 'full' | 'metadata' | 'minimal', signal?: AbortSignal): Promise<GmailReadResult>;
159
+ /**
160
+ * List the newest inbox page that matches searchQuery, as the Go Trigger poller does. It rejects with
161
+ * an error that names no query value when Gmail does not answer 2xx with a usable listing.
162
+ */
163
+ listInboxMessages(call: Call, credentials: Credentials, searchQuery: string, pageSize: number, signal?: AbortSignal): Promise<{
164
+ messages: GmailMessageReference[];
165
+ credentials: Credentials;
166
+ }>;
149
167
  /** Search Sent Mail once for the run-specific RFC Message-ID. */
150
168
  findSentMessage(call: Call, credentials: Credentials, messageIdAddress: string, signal?: AbortSignal): Promise<SentMessageIdentity | undefined>;
151
169
  /** Post one encoded Gmail messages.send request without redirects or transport replay. */
@@ -174,7 +192,7 @@ declare class SendMessageOperation implements Mutation<SendMessageInput, SendMes
174
192
  /** Inject the provider sender used by each Dex attempt. */
175
193
  constructor(sender: GmailSender);
176
194
  /** Return the immutable manifest operation definition. */
177
- definition(): _superdurable_connectors_sdk.QueryDefinition;
195
+ definition(): _superdurable_connectors_sdk.MutationDefinition;
178
196
  /** Use the stable connector Call ID as the send correlation key. */
179
197
  idempotencyKey(callId: string, input: SendMessageInput): string;
180
198
  /** Classify a send using Dex's public current-attempt deadline. */
@@ -186,7 +204,7 @@ declare class ReplyToMessageOperation implements Mutation<ReplyToMessageInput, S
186
204
  /** Inject the provider sender used by each Dex attempt. */
187
205
  constructor(sender: GmailSender);
188
206
  /** Return the immutable manifest operation definition. */
189
- definition(): _superdurable_connectors_sdk.QueryDefinition;
207
+ definition(): _superdurable_connectors_sdk.MutationDefinition;
190
208
  /** Use the stable connector Call ID as the reply correlation key. */
191
209
  idempotencyKey(callId: string, input: ReplyToMessageInput): string;
192
210
  /** Classify a reply using Dex's public current-attempt deadline. */
@@ -211,12 +229,25 @@ interface GmailClientOptions {
211
229
  transport?: GmailTransport;
212
230
  /** Observation clock for receipts. */
213
231
  now?: () => Date;
232
+ /**
233
+ * Receives the Trigger pollers' records: failed polls, ignored and skipped messages, delivery retries,
234
+ * and the durable inboxes that newProjectMessageTriggerRunner creates. Omitted uses
235
+ * defaultTriggerLogger. Records carry message and thread IDs, never senders, subjects, snippets,
236
+ * bodies, or tokens.
237
+ */
238
+ logger?: TriggerLogger;
214
239
  }
215
240
  /** Gmail connection with operation-specific provider interfaces. */
216
241
  declare class GmailClient implements GmailOperations {
217
242
  #private;
243
+ /** Trigger record destination. */ readonly triggerLogger: TriggerLogger;
218
244
  /** Validate settings and inject a host-owned credential source. */
219
245
  constructor(config: Config, credentials: CredentialSource, options?: GmailClientOptions);
246
+ /** @internal The authenticated transport and provider methods that the Trigger pollers share. */
247
+ triggerTransport(): {
248
+ http: GmailHTTPClient;
249
+ provider: GmailProvider;
250
+ };
220
251
  /** Return the getMessage Query bound to this connection. */
221
252
  getMessage(): GetMessageOperation;
222
253
  /** Return the sendMessage Mutation bound to this connection. */
@@ -280,4 +311,180 @@ declare function newSendMessageStep<StepInput>(configuration: SendMessageStepCon
280
311
  /** Build a Gmail reply Step with its typed connection. */
281
312
  declare function newReplyToMessageStep<StepInput>(configuration: ReplyToMessageStepConfig<StepInput>): MutationStep<StepInput, ReplyToMessageInput, SendMessageOutput>;
282
313
 
283
- export { Config, CredentialSource, Credentials, GetMessageBranch, GetMessageDefinition, GetMessageInput, GetMessageOperation, type GetMessageStepConfig, GmailClient, type GmailClientOptions, type GmailClientSettings, GmailConnection, GmailCredentialError, GmailCredentialRefreshDriver, GmailHTTPClient, type GmailMessagePart, type GmailMessageResource, GmailMessageResourceSchema, GmailOperations, GmailProvider, type GmailReadResult, type GmailTransport, Message, ReplyToMessageBranch, ReplyToMessageDefinition, ReplyToMessageInput, ReplyToMessageOperation, type ReplyToMessageStepConfig, SendMessageBranch, SendMessageDefinition, SendMessageInput, SendMessageOperation, SendMessageOutput, type SendMessageStepConfig, type SentMessageIdentity, buildMIMEMessage, buildReplyMIMEMessage, decodeGmailMessage, emptyMessage, gmailClientSettings, gmailFailure, gmailRequestID, gmailRetryAfterMs, newGetMessageStep, newProjectConnection, newProjectGmailClient, newReplyToMessageStep, newSendMessageStep, parseMailbox, parseSentResponse, receiptFor, replyRecipient, rfcMessageIDAddress, statusFailureKind, validateSendInput };
314
+ /** One poller's source and the target it delivers to. */
315
+ interface MessageTriggerRoute {
316
+ source: MessagePollingTriggerSource;
317
+ target: TriggerTarget<MessageEvent>;
318
+ }
319
+ /** One inbox list call, delivered later by MessagePollingTriggerSource.deliver. */
320
+ interface MessageListing {
321
+ credentials: Credentials;
322
+ messages: GmailMessageReference[];
323
+ }
324
+ /**
325
+ * Polls one Gmail binding: it lists the newest inbox page, reads each new message's metadata, and
326
+ * delivers matching roots or replies oldest first, as the Go connector's poller does. The delivered set
327
+ * covers the last listed page in memory; a restart rescans the page, and the Flow start request ID and
328
+ * the application's RPC absorb the duplicates.
329
+ */
330
+ declare class MessagePollingTriggerSource {
331
+ #private;
332
+ /** Bind one binding's query and matcher; an empty bindingName omits the binding log attribute. */
333
+ constructor(client: GmailClient, connection: ConnectionRef, triggerName: string, bindingName: string, searchQuery: string, matcher: MessageMatcher, requiresReply: boolean);
334
+ /** Scan, then wait one poll interval, until the context ends. */
335
+ run(context: TriggerContext, target: TriggerTarget<MessageEvent>): Promise<void>;
336
+ /** List the inbox and deliver the listed messages. */
337
+ scan(context: TriggerContext, target: TriggerTarget<MessageEvent>): Promise<void>;
338
+ /** Read the newest inbox page that matches the source's search query. */
339
+ list(context: TriggerContext): Promise<MessageListing>;
340
+ /**
341
+ * Hand target the event that failed on an earlier poll, if any, then every new matching message in
342
+ * listing, oldest first. It stops at the first failure, so the next poll retries that event before any
343
+ * later message, even after newer mail pushes it off the listed page.
344
+ */
345
+ deliver(context: TriggerContext, target: TriggerTarget<MessageEvent>, listing: MessageListing): Promise<void>;
346
+ }
347
+
348
+ /** Filters received Gmail messages by sender and text. */
349
+ declare const MessageMatcherSchema: z.ZodObject<{
350
+ messageContains: z.ZodOptional<z.ZodString>;
351
+ senderEmails: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
352
+ }, z.core.$strict>;
353
+ /** Sender and text filter of one Gmail message Trigger binding. */
354
+ type MessageMatcher = z.infer<typeof MessageMatcherSchema>;
355
+ /** Configuration of messageReceived: an optional Gmail search query and the root-message matcher. */
356
+ declare const MessageReceivedTriggerConfigurationSchema: z.ZodObject<{
357
+ searchQuery: z.ZodOptional<z.ZodString>;
358
+ messageMatcher: z.ZodOptional<z.ZodObject<{
359
+ messageContains: z.ZodOptional<z.ZodString>;
360
+ senderEmails: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
361
+ }, z.core.$strict>>;
362
+ }, z.core.$strict>;
363
+ /** Search query and root-message matcher of one messageReceived binding. */
364
+ type MessageReceivedTriggerConfiguration = z.infer<typeof MessageReceivedTriggerConfigurationSchema>;
365
+ /** Configuration of replyReceived: an optional Gmail search query and the reply matcher. */
366
+ declare const ReplyReceivedTriggerConfigurationSchema: z.ZodObject<{
367
+ searchQuery: z.ZodOptional<z.ZodString>;
368
+ replyMatcher: z.ZodOptional<z.ZodObject<{
369
+ messageContains: z.ZodOptional<z.ZodString>;
370
+ senderEmails: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
371
+ }, z.core.$strict>>;
372
+ }, z.core.$strict>;
373
+ /** Search query and reply matcher of one replyReceived binding. */
374
+ type ReplyReceivedTriggerConfiguration = z.infer<typeof ReplyReceivedTriggerConfigurationSchema>;
375
+ /** The metadata-only payload of both Gmail Triggers; field names and order match the Go connector. */
376
+ declare const MessageEventSchema: z.ZodObject<{
377
+ primaryEmail: z.ZodString;
378
+ messageId: z.ZodString;
379
+ threadId: z.ZodString;
380
+ from: z.ZodString;
381
+ subject: z.ZodString;
382
+ snippet: z.ZodOptional<z.ZodString>;
383
+ receivedAt: z.ZodString;
384
+ isReply: z.ZodBoolean;
385
+ }, z.core.$strip>;
386
+ /** One received Gmail message. */
387
+ type MessageEvent = z.infer<typeof MessageEventSchema>;
388
+ /** Manifest definition of messageReceived. */
389
+ declare const MessageReceivedTriggerDefinition: TriggerDefinition;
390
+ /** Manifest definition of replyReceived. */
391
+ declare const ReplyReceivedTriggerDefinition: TriggerDefinition;
392
+ /** Gmail search query input UI unit. */ declare const UIUnitSearchQueryInput = "searchQueryInput";
393
+ /** Search query input output port. */ declare const UISearchQueryInputPortQuery = "query";
394
+ /** Email address list input UI unit. */ declare const UIUnitEmailListInput = "emailListInput";
395
+ /** Email list input output port. */ declare const UIEmailListInputPortEmails = "emails";
396
+ /** Plain text input UI unit. */ declare const UIUnitTextInput = "textInput";
397
+ /** Text input output port. */ declare const UITextInputPortText = "text";
398
+ /** One static application binding of a Gmail message Trigger. */
399
+ interface GmailTriggerBindingConfig {
400
+ /** Static connection name. */ connectionName: string;
401
+ /** Static binding name. */ bindingName: string;
402
+ /** Connector Studio configuration units for the binding. */ configurationUI: ConnectorConfigurationUI;
403
+ }
404
+ /** Declare a static messageReceived binding for Flow Definition tooling and Dex Web. */
405
+ declare function defineMessageReceivedTriggerBinding(config: GmailTriggerBindingConfig): TriggerBindingDefinition;
406
+ /** Declare a static replyReceived binding for Flow Definition tooling and Dex Web. */
407
+ declare function defineReplyReceivedTriggerBinding(config: GmailTriggerBindingConfig): TriggerBindingDefinition;
408
+ /** Configuration of one standalone Gmail message Trigger. */
409
+ interface GmailMessageTriggerConfig<Configuration> {
410
+ /** Gmail connection bound to a GmailClient. */ connection: GmailConnection;
411
+ /** Static connection name; must equal the connection's name. */ connectionName: string;
412
+ /** Static binding name. */ bindingName: string;
413
+ /** Search query and matcher. */ configuration: Configuration;
414
+ /** Routes accepted events into the application. */ target: TriggerTarget<MessageEvent>;
415
+ }
416
+ /**
417
+ * Create one messageReceived Trigger that polls on its own. Prefer one MessageTriggerRunner per
418
+ * connection, which delivers every root before any reply.
419
+ */
420
+ declare function newMessageReceivedTrigger(config: GmailMessageTriggerConfig<MessageReceivedTriggerConfiguration>): TriggerRunner;
421
+ /**
422
+ * Create one replyReceived Trigger that polls on its own. Prefer one MessageTriggerRunner per
423
+ * connection, which delivers every root before any reply.
424
+ */
425
+ declare function newReplyReceivedTrigger(config: GmailMessageTriggerConfig<ReplyReceivedTriggerConfiguration>): TriggerRunner;
426
+ /** One root-message binding and its application target. */
427
+ interface MessageReceivedTriggerRoute {
428
+ /** Configured binding name. */ bindingName: string;
429
+ /** Search query and root-message matcher. */ configuration: MessageReceivedTriggerConfiguration;
430
+ /** Routes accepted events into the application. */ target: TriggerTarget<MessageEvent>;
431
+ }
432
+ /** One reply binding and its application target. */
433
+ interface ReplyReceivedTriggerRoute {
434
+ /** Configured binding name. */ bindingName: string;
435
+ /** Search query and reply matcher. */ configuration: ReplyReceivedTriggerConfiguration;
436
+ /** Routes accepted events into the application. */ target: TriggerTarget<MessageEvent>;
437
+ }
438
+ /** Gmail message Triggers that share one ordered poller. */
439
+ interface MessageTriggerRunnerConfig {
440
+ /** Gmail connection bound to a GmailClient. */ connection: GmailConnection;
441
+ /** Root-message bindings. */ messageReceivedRoutes?: readonly MessageReceivedTriggerRoute[];
442
+ /** Reply bindings. */ replyReceivedRoutes?: readonly ReplyReceivedTriggerRoute[];
443
+ }
444
+ /** One root-message binding saved in the project configuration and its application target. */
445
+ interface ProjectMessageReceivedTriggerRoute {
446
+ bindingName: string; /** Application target. */
447
+ target: TriggerTarget<MessageEvent>;
448
+ }
449
+ /** One reply binding saved in the project configuration and its application target. */
450
+ interface ProjectReplyReceivedTriggerRoute {
451
+ bindingName: string; /** Application target. */
452
+ target: TriggerTarget<MessageEvent>;
453
+ }
454
+ /** Gmail message Trigger bindings selected from the project configuration. */
455
+ interface ProjectMessageTriggerRunnerConfig {
456
+ /** Root-message bindings. */ messageReceivedRoutes?: readonly ProjectMessageReceivedTriggerRoute[];
457
+ /** Reply bindings. */ replyReceivedRoutes?: readonly ProjectReplyReceivedTriggerRoute[];
458
+ }
459
+ /** Polls every configured Gmail route of one connection and delivers root messages before replies. */
460
+ declare class MessageTriggerRunner {
461
+ #private;
462
+ /** @internal Use newMessageTriggerRunner or newProjectMessageTriggerRunner. */
463
+ constructor(rootRoutes: readonly MessageTriggerRoute[], replyRoutes: readonly MessageTriggerRoute[], pollIntervalMs: number);
464
+ /**
465
+ * Replay each route's durable inbox in order, roots first, then poll until the context ends. Each poll
466
+ * lists every reply route before any root route, then delivers every root before any reply, and ends
467
+ * at the first failure. Every later poll retries the failed event before that route's listed messages,
468
+ * even after Gmail stops listing it. Gmail receives a thread's root before any reply to it, so the
469
+ * root of every listed reply is in the later root listing and reaches Dex first.
470
+ *
471
+ * It logs through the client's logger: WARN "gmail poll failed; retrying" with the consecutive failed
472
+ * polls as attempt and the poll interval as delay_ms when a list or read fails, WARN "trigger delivery
473
+ * failed; retrying" with the attempt number when a target fails, INFO "trigger delivered after retry"
474
+ * when a later poll delivers that message, DEBUG "trigger event ignored" with its reason, and the
475
+ * durable inbox records. It rejects with TriggerDeliveryAbortedError once the context ends, and when
476
+ * an inbox replay fails.
477
+ */
478
+ run(context: TriggerContext): Promise<void>;
479
+ }
480
+ /** Create one ordered runner for every configured Gmail message Trigger route of a connection; throws on invalid wiring. */
481
+ declare function newMessageTriggerRunner(config: MessageTriggerRunnerConfig): MessageTriggerRunner;
482
+ /**
483
+ * Open connectionName from the loaded project, load the selected bindings' saved configuration, and
484
+ * create one durable, ordered runner. Each route keeps acknowledged events in its binding's project
485
+ * Trigger inbox until its target consumes them, so a restarted or replaced replica replays them. A
486
+ * route whose binding is not configured throws. The options' logger also applies to those inboxes.
487
+ */
488
+ declare function newProjectMessageTriggerRunner(project: LoadedProject, connectionName: string, config: ProjectMessageTriggerRunnerConfig, options?: GmailClientOptions): MessageTriggerRunner;
489
+
490
+ export { Config, CredentialSource, Credentials, GetMessageBranch, GetMessageDefinition, GetMessageInput, GetMessageOperation, type GetMessageStepConfig, GmailClient, type GmailClientOptions, type GmailClientSettings, GmailConnection, GmailCredentialError, GmailCredentialRefreshDriver, GmailHTTPClient, type GmailMessagePart, type GmailMessageReference, type GmailMessageResource, GmailMessageResourceSchema, type GmailMessageTriggerConfig, GmailOperations, GmailProvider, type GmailReadResult, type GmailTransport, type GmailTriggerBindingConfig, Message, type MessageEvent, MessageEventSchema, type MessageMatcher, MessageMatcherSchema, type MessageReceivedTriggerConfiguration, MessageReceivedTriggerConfigurationSchema, MessageReceivedTriggerDefinition, type MessageReceivedTriggerRoute, MessageTriggerRunner, type MessageTriggerRunnerConfig, type ProjectMessageReceivedTriggerRoute, type ProjectMessageTriggerRunnerConfig, type ProjectReplyReceivedTriggerRoute, type ReplyReceivedTriggerConfiguration, ReplyReceivedTriggerConfigurationSchema, ReplyReceivedTriggerDefinition, type ReplyReceivedTriggerRoute, ReplyToMessageBranch, ReplyToMessageDefinition, ReplyToMessageInput, ReplyToMessageOperation, type ReplyToMessageStepConfig, SendMessageBranch, SendMessageDefinition, SendMessageInput, SendMessageOperation, SendMessageOutput, type SendMessageStepConfig, type SentMessageIdentity, UIEmailListInputPortEmails, UISearchQueryInputPortQuery, UITextInputPortText, UIUnitEmailListInput, UIUnitSearchQueryInput, UIUnitTextInput, buildMIMEMessage, buildReplyMIMEMessage, decodeGmailMessage, defineMessageReceivedTriggerBinding, defineReplyReceivedTriggerBinding, emptyMessage, gmailClientSettings, gmailFailure, gmailRequestID, gmailRetryAfterMs, newGetMessageStep, newMessageReceivedTrigger, newMessageTriggerRunner, newProjectConnection, newProjectGmailClient, newProjectMessageTriggerRunner, newReplyReceivedTrigger, newReplyToMessageStep, newSendMessageStep, parseMailbox, parseSentResponse, receiptFor, replyRecipient, rfcMessageIDAddress, statusFailureKind, validateSendInput };