@3sixty/mailbox-connector-gmail 0.0.0-stage → 0.20.0-next.0

package/docs/reference/classes/GmailEmailConnector.md

@@ -0,0 +1,218 @@
+# Class: GmailEmailConnector
+
+Gmail email protocol connector. Monitors a mailbox for new messages using the Gmail API.
+
+## Implements
+
+- `IEmailProtocolConnector`\<[`IGmailEmailConnectorState`](../interfaces/IGmailEmailConnectorState.md)\>
+
+## Constructors
+
+### Constructor
+
+> **new GmailEmailConnector**(`options`): `GmailEmailConnector`
+
+Create a new instance of GmailEmailConnector.
+
+#### Parameters
+
+##### options
+
+[`IGmailEmailConnectorConstructorOptions`](../interfaces/IGmailEmailConnectorConstructorOptions.md)
+
+The options for the connector.
+
+#### Returns
+
+`GmailEmailConnector`
+
+#### Throws
+
+GeneralError if neither a service account key nor an OAuth client is supplied.
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+The class name.
+
+***
+
+### NAMESPACE {#namespace}
+
+> `readonly` `static` **NAMESPACE**: `string` = `"gmail"`
+
+The protocol namespace identifier.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Get the class name.
+
+#### Returns
+
+`string`
+
+The class name.
+
+#### Implementation of
+
+`IEmailProtocolConnector.className`
+
+***
+
+### retrieve() {#retrieve}
+
+> **retrieve**(`instanceId`, `state`, `authCallback`, `retrievalCallback`, `options`): `Promise`\<`void`\>
+
+Start the internal polling loop for the given instance.
+
+#### Parameters
+
+##### instanceId
+
+`string`
+
+The identifier of the mailbox instance being polled.
+
+##### state
+
+[`IGmailEmailConnectorState`](../interfaces/IGmailEmailConnectorState.md)
+
+The current connector state for the instance.
+
+##### authCallback
+
+`IEmailProtocolConnectorAuthCallback`
+
+Callback invoked when authentication fails during a poll cycle.
+
+##### retrievalCallback
+
+`IEmailProtocolConnectorRetrievalCallback`
+
+Callback invoked with retrieved messages after each poll cycle.
+
+##### options
+
+`IEmailProtocolConnectorOptions`
+
+Options supplied by the owning component, carrying the consent callback URI.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the polling loop has been started.
+
+#### Implementation of
+
+`IEmailProtocolConnector.retrieve`
+
+***
+
+### initiateAuth() {#initiateauth}
+
+> **initiateAuth**(`instanceId`, `state`, `options`): `Promise`\<`IEmailProtocolConnectorAuthState` \| `undefined`\>
+
+Start the consent flow for a mailbox which has no refresh token yet.
+
+#### Parameters
+
+##### instanceId
+
+`string`
+
+The identifier of the mailbox instance being authenticated.
+
+##### state
+
+[`IGmailEmailConnectorState`](../interfaces/IGmailEmailConnectorState.md)
+
+The current connector state for the instance.
+
+##### options
+
+`IEmailProtocolConnectorOptions`
+
+Options supplied by the owning component, carrying the consent callback URI
+and the state which correlates the consent response back to the mailbox.
+
+#### Returns
+
+`Promise`\<`IEmailProtocolConnectorAuthState` \| `undefined`\>
+
+The auth state carrying the consent URL to open, or undefined when the mailbox can
+already authenticate itself from a service account key or a refresh token in its state.
+
+#### Implementation of
+
+`IEmailProtocolConnector.initiateAuth`
+
+***
+
+### completeAuth() {#completeauth}
+
+> **completeAuth**(`instanceId`, `authPayload`, `options`): `Promise`\<`void`\>
+
+Complete the consent flow with the authorisation code handed to the redirect URI.
+The issued credentials are applied to this connector instance so the next poll uses them,
+and the refresh token is placed in the state reported through the auth callback given by
+retrieve, so the owning component vaults it and lifts the authentication halt.
+
+#### Parameters
+
+##### instanceId
+
+`string`
+
+The identifier of the mailbox instance being authenticated.
+
+##### authPayload
+
+`unknown`
+
+The redirect query, carrying the authorisation code as its code property.
+
+##### options
+
+`IEmailProtocolConnectorOptions`
+
+Options supplied by the owning component, carrying the consent callback URI.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the flow has been completed.
+
+#### Throws
+
+GeneralError if the authorisation code could not be exchanged for tokens.
+
+#### Implementation of
+
+`IEmailProtocolConnector.completeAuth`
+
+***
+
+### retrieveStop() {#retrievestop}
+
+> **retrieveStop**(): `Promise`\<`void`\>
+
+Stop the polling loop for this connector.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the polling loop has been stopped.
+
+#### Implementation of
+
+`IEmailProtocolConnector.retrieveStop`

package/docs/reference/functions/initSchema.md

@@ -0,0 +1,12 @@
+# Function: initSchema()
+
+> **initSchema**(): `void`
+
+Initialise the connector schemas for the Gmail connector.
+The connector constructor calls this as well, so registering here is only needed to make the
+schemas available before any connector instance has been built, such as for a mailbox which
+is stored but not currently polled.
+
+## Returns
+
+`void`

package/docs/reference/index.md

@@ -0,0 +1,20 @@
+# @3sixty/mailbox-connector-gmail
+
+## Classes
+
+- [GmailEmailConnector](classes/GmailEmailConnector.md)
+
+## Interfaces
+
+- [IGmailEmailConnectorConfig](interfaces/IGmailEmailConnectorConfig.md)
+- [IGmailEmailConnectorConstructorOptions](interfaces/IGmailEmailConnectorConstructorOptions.md)
+- [IGmailEmailConnectorState](interfaces/IGmailEmailConnectorState.md)
+
+## Variables
+
+- [GmailEmailConnectorConfigSchema](variables/GmailEmailConnectorConfigSchema.md)
+- [GmailEmailConnectorStateSchema](variables/GmailEmailConnectorStateSchema.md)
+
+## Functions
+
+- [initSchema](functions/initSchema.md)

package/docs/reference/interfaces/IGmailEmailConnectorConfig.md

@@ -0,0 +1,110 @@
+# Interface: IGmailEmailConnectorConfig
+
+Configuration for the Gmail email connector.
+
+## Properties
+
+### emailAddress {#emailaddress}
+
+> **emailAddress**: `string`
+
+The address of the mailbox to monitor, for example "user@example.com".
+Used as the Gmail API user identifier, and as the impersonated subject
+when a service account key is supplied.
+
+***
+
+### clientId? {#clientid}
+
+> `optional` **clientId?**: `string`
+
+The OAuth 2.0 client identifier from the Google Cloud project.
+Required unless serviceAccountKey is supplied.
+
+***
+
+### clientSecret? {#clientsecret}
+
+> `optional` **clientSecret?**: `string`
+
+The OAuth 2.0 client secret from the Google Cloud project. Stored securely in the vault.
+Required unless serviceAccountKey is supplied.
+
+***
+
+### serviceAccountKey? {#serviceaccountkey}
+
+> `optional` **serviceAccountKey?**: `string`
+
+The JSON service account key used for domain-wide delegation, as a string.
+Stored securely in the vault. When supplied this takes precedence over the
+authorisation code credentials and the mailbox is accessed by impersonating emailAddress.
+
+***
+
+### labelIds? {#labelids}
+
+> `optional` **labelIds?**: `string`[]
+
+The identifiers of the labels to monitor for new messages.
+A message carrying any of them is delivered, so the mailbox sync walks one label at a time
+because the Gmail message list requires a message to carry every label it is given.
+
+#### Default
+
+```ts
+["INBOX"]
+```
+
+***
+
+### maxMessagesPerPoll? {#maxmessagesperpoll}
+
+> `optional` **maxMessagesPerPoll?**: `number`
+
+The maximum number of messages to retrieve during a single poll of the initial sync.
+Later polls continue from where the previous one finished.
+
+#### Default
+
+```ts
+50
+```
+
+***
+
+### maxDeliveredIdHistory? {#maxdeliveredidhistory}
+
+> `optional` **maxDeliveredIdHistory?**: `number`
+
+The number of delivered message identifiers retained in the connector state.
+These guard against a message being delivered twice when a poll cycle is replayed.
+
+#### Default
+
+```ts
+200
+```
+
+***
+
+### pollingIntervalMinutes? {#pollingintervalminutes}
+
+> `optional` **pollingIntervalMinutes?**: `number`
+
+How often to poll for new messages, in minutes.
+
+#### Default
+
+```ts
+2
+```
+
+***
+
+### mutexTimeoutMs? {#mutextimeoutms}
+
+> `optional` **mutexTimeoutMs?**: `number`
+
+Maximum time in milliseconds to wait for the poll mutex before skipping the tick.
+When not set, the mutex waits based on the system default.

package/docs/reference/interfaces/IGmailEmailConnectorConstructorOptions.md

@@ -0,0 +1,33 @@
+# Interface: IGmailEmailConnectorConstructorOptions
+
+Constructor options for the Gmail email connector.
+
+## Properties
+
+### taskSchedulerComponentType? {#taskschedulercomponenttype}
+
+> `optional` **taskSchedulerComponentType?**: `string`
+
+The component type for the task scheduler used to manage polling intervals.
+
+#### Default
+
+```ts
+"task-scheduler"
+```
+
+***
+
+### loggingComponentType? {#loggingcomponenttype}
+
+> `optional` **loggingComponentType?**: `string`
+
+The component type for logging.
+
+***
+
+### config {#config}
+
+> **config**: [`IGmailEmailConnectorConfig`](IGmailEmailConnectorConfig.md)
+
+The configuration for the Gmail connector.

package/docs/reference/interfaces/IGmailEmailConnectorState.md

@@ -0,0 +1,63 @@
+# Interface: IGmailEmailConnectorState
+
+Runtime state persisted between poll cycles for a Gmail connector.
+
+## Properties
+
+### refreshToken? {#refreshtoken}
+
+> `optional` **refreshToken?**: `string`
+
+The OAuth 2.0 refresh token the consent flow issued for the mailbox, declared secure in the
+connector state schema so the owning component vaults it rather than persisting it here.
+Unset until consent has been given, while the connector supplies a consent URL instead of
+polling, and never set for a mailbox authenticated by a service account key.
+
+***
+
+### historyId? {#historyid}
+
+> `optional` **historyId?**: `string`
+
+The mailbox history identifier processing has reached.
+Later polls ask the Gmail history API for the changes which follow it.
+
+***
+
+### syncPageTokens? {#syncpagetokens}
+
+> `optional` **syncPageTokens?**: `object`
+
+The page tokens for the next page of the initial mailbox sync, keyed by label identifier.
+Only set while initialSyncComplete is false and more pages remain for that label.
+
+#### Index Signature
+
+\[`labelId`: `string`\]: `string`
+
+***
+
+### syncCompletedLabelIds? {#synccompletedlabelids}
+
+> `optional` **syncCompletedLabelIds?**: `string`[]
+
+The labels whose existing messages have all been walked during the initial sync.
+
+***
+
+### initialSyncComplete? {#initialsynccomplete}
+
+> `optional` **initialSyncComplete?**: `boolean`
+
+Whether the initial sync of the existing mailbox contents has finished.
+Until it has, polling walks the message list rather than the history API.
+
+***
+
+### deliveredMessageIds? {#deliveredmessageids}
+
+> `optional` **deliveredMessageIds?**: `string`[]
+
+The identifiers of the most recently delivered messages, oldest first.
+Gmail message identifiers are permanent, so this prevents a message being
+delivered twice when a poll cycle is replayed after a persistence failure.

package/docs/reference/variables/GmailEmailConnectorConfigSchema.md

@@ -0,0 +1,5 @@
+# Variable: GmailEmailConnectorConfigSchema
+
+> `const` **GmailEmailConnectorConfigSchema**: `IMailboxConfigField`[]
+
+The configuration field schema for Gmail connectors.

package/docs/reference/variables/GmailEmailConnectorStateSchema.md

@@ -0,0 +1,7 @@
+# Variable: GmailEmailConnectorStateSchema
+
+> `const` **GmailEmailConnectorStateSchema**: `IMailboxConfigField`[]
+
+The runtime state field schema for Gmail connectors.
+The refresh token is issued by the consent flow rather than configured, so it travels in the
+connector state and is marked secure to keep it in the vault.

package/locales/en.json

@@ -0,0 +1,41 @@
+{
+	"error": {
+		"gmailEmailConnector": {
+			"pollFailed": "Poll failed",
+			"authCodeExchangeFailed": "The authorization code could not be exchanged for tokens",
+			"noRefreshTokenIssued": "The consent flow did not issue a refresh token",
+			"authFlowNotStarted": "The connector has no authentication flow in progress to complete",
+			"consentAccountMismatch": "The consent was given by an account other than {emailAddress}",
+			"missingOAuthCredentials": "The clientId and clientSecret are required when no serviceAccountKey is supplied",
+			"invalidServiceAccountKey": "The serviceAccountKey is not a valid service account JSON key"
+		}
+	},
+	"info": {
+		"gmailEmailConnector": {
+			"emailReceived": "Email received \"{subject}\""
+		}
+	},
+	"warn": {
+		"gmailEmailConnector": {
+			"consentRequired": "Mailbox requires OAuth consent before it can be polled",
+			"historyExpired": "Mailbox history expired, restarting the mailbox sync"
+		}
+	},
+	"gmailEmailConnectorConfigSchema": {
+		"emailAddress": "Email Address",
+		"clientId": "OAuth Client ID",
+		"clientSecret": "OAuth Client Secret",
+		"serviceAccountKey": "Service Account Key",
+		"labelIds": "Label IDs",
+		"maxMessagesPerPoll": "Maximum Messages Per Poll",
+		"pollingIntervalMinutes": "Polling Interval (Minutes)"
+	},
+	"gmailEmailConnectorStateSchema": {
+		"refreshToken": "OAuth Refresh Token",
+		"historyId": "Mailbox History ID",
+		"syncPageTokens": "Sync Page Tokens",
+		"syncCompletedLabelIds": "Synced Label IDs",
+		"initialSyncComplete": "Initial Sync Complete",
+		"deliveredMessageIds": "Delivered Message IDs"
+	}
+}

package/package.json

@@ -1,6 +1,58 @@
 {
-  "name": "@3sixty/mailbox-connector-gmail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@3sixty/mailbox-connector-gmail",
+	"version": "0.20.0-next.0",
+	"description": "Gmail connector for email mailbox ingestion.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/3sixtyglobal/messaging.git",
+		"directory": "packages/mailbox-connector-gmail"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=24.0.0"
+	},
+	"dependencies": {
+		"@3sixty/background-task-models": "next",
+		"@3sixty/core": "next",
+		"@3sixty/entity": "next",
+		"@3sixty/logging-models": "next",
+		"@3sixty/mailbox-models": "0.20.0-next.0",
+		"@3sixty/nameof": "next",
+		"googleapis": "181.0.0"
+	},
+	"main": "./dist/es/index.js",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/es/index.js",
+			"default": "./dist/es/index.js"
+		}
+	},
+	"files": [
+		"dist/es",
+		"dist/types",
+		"locales",
+		"docs"
+	],
+	"keywords": [
+		"twin",
+		"trade",
+		"iota",
+		"framework",
+		"blockchain",
+		"messaging",
+		"mailbox",
+		"email",
+		"gmail",
+		"google",
+		"oauth",
+		"connector"
+	],
+	"bugs": {
+		"url": "git+https://github.com/3sixtyglobal/messaging/issues"
+	},
+	"homepage": "https://3sixty.global"
+}