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

package/docs/reference/interfaces/IEmailProtocolConnector.md

@@ -0,0 +1,154 @@
+# Interface: IEmailProtocolConnector\<TState, TAuthState\>
+
+Interface describing an email protocol connector that handles message retrieval.
+
+## Extends
+
+- `IComponent`
+
+## Type Parameters
+
+### TState
+
+`TState` = `unknown`
+
+### TAuthState
+
+`TAuthState` *extends* [`IEmailProtocolConnectorAuthState`](IEmailProtocolConnectorAuthState.md) = [`IEmailProtocolConnectorAuthState`](IEmailProtocolConnectorAuthState.md)
+
+## Methods
+
+### 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
+
+`TState`
+
+The current connector state for the instance.
+
+##### authCallback
+
+[`IEmailProtocolConnectorAuthCallback`](../type-aliases/IEmailProtocolConnectorAuthCallback.md)\<`TAuthState`\>
+
+Callback invoked when authentication fails during a poll cycle.
+
+##### retrievalCallback
+
+[`IEmailProtocolConnectorRetrievalCallback`](../type-aliases/IEmailProtocolConnectorRetrievalCallback.md)
+
+Callback invoked with retrieved messages after each poll cycle.
+
+##### options
+
+[`IEmailProtocolConnectorOptions`](IEmailProtocolConnectorOptions.md)
+
+Options supplied by the owning component.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the polling loop has been started.
+
+***
+
+### retrieveStop() {#retrievestop}
+
+> **retrieveStop**(): `Promise`\<`void`\>
+
+Stop the internal polling loop.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the polling loop has been stopped.
+
+***
+
+### initiateAuth()? {#initiateauth}
+
+> `optional` **initiateAuth**(`instanceId`, `state`, `options`): `Promise`\<`TAuthState` \| `undefined`\>
+
+Start an authentication flow for a mailbox before it is polled for the first time.
+Only implemented by connectors whose credentials are issued by an external flow, such as
+an OAuth consent redirect, so the caller can hand the flow straight to the operator who
+created the mailbox rather than waiting for the first poll to report it.
+
+#### Parameters
+
+##### instanceId
+
+`string`
+
+The identifier of the mailbox instance being authenticated.
+
+##### state
+
+`TState`
+
+The current connector state for the instance, which may already hold credentials.
+
+##### options
+
+[`IEmailProtocolConnectorOptions`](IEmailProtocolConnectorOptions.md)
+
+Options supplied by the owning component, carrying the callback URI the flow
+must return to and the state which correlates it back to the mailbox.
+
+#### Returns
+
+`Promise`\<`TAuthState` \| `undefined`\>
+
+The auth state carrying the URL to open for the user, or undefined when the
+mailbox is already able to authenticate itself.
+
+***
+
+### completeAuth()? {#completeauth}
+
+> `optional` **completeAuth**(`instanceId`, `authPayload`, `options`): `Promise`\<`void`\>
+
+Complete an authentication flow the connector reported through its auth callback.
+Only implemented by connectors whose credentials are issued by an external flow, such as
+an OAuth consent redirect. The outcome is reported back through the auth callback the
+connector was given by retrieve, so nothing is returned here.
+
+#### Parameters
+
+##### instanceId
+
+`string`
+
+The identifier of the mailbox instance being authenticated.
+
+##### authPayload
+
+`unknown`
+
+The protocol-specific data handed to the redirect, such as an OAuth code.
+
+##### options
+
+[`IEmailProtocolConnectorOptions`](IEmailProtocolConnectorOptions.md)
+
+Options supplied by the owning component, carrying the same callback URI the
+flow was started with.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the flow has been completed.

package/docs/reference/interfaces/IEmailProtocolConnectorAuthState.md

@@ -0,0 +1,14 @@
+# Interface: IEmailProtocolConnectorAuthState
+
+The state a protocol connector produces when a mailbox has to be authenticated by an
+external flow. Connectors which carry more through the flow extend this with their own
+properties, but the URL is named here so callers can open it without knowing the protocol.
+
+## Properties
+
+### authUrl? {#authurl}
+
+> `optional` **authUrl?**: `string`
+
+The URL to open for the user to authenticate the mailbox, such as an OAuth consent URL.
+Absent when the connector has no URL to send the user to.

package/docs/reference/interfaces/IEmailProtocolConnectorOptions.md

@@ -0,0 +1,25 @@
+# Interface: IEmailProtocolConnectorOptions
+
+Options supplied to a protocol connector by the component which owns it.
+
+## Properties
+
+### callbackUri? {#callbackuri}
+
+> `optional` **callbackUri?**: `string`
+
+The fixed URI an external authentication flow returns to, which correlates the response
+back to the mailbox it belongs to. Connectors which start such a flow must send the
+external service to this URI rather than one of their own.
+Absent when the owning component has no public origin recorded for the mailbox, which
+leaves a connector able to poll with the credentials it has but unable to start a flow.
+
+***
+
+### correlationState {#correlationstate}
+
+> **correlationState**: `string`
+
+The opaque value a connector must carry through an external authentication flow so the
+response returns to the owning component identifying both the partition and the mailbox.
+It is passed back verbatim, so the component needs no search to correlate the callback.

package/docs/reference/interfaces/IMailStorageComponent.md

@@ -0,0 +1,119 @@
+# Interface: IMailStorageComponent
+
+Interface describing the mail storage component for persisting and querying received emails.
+
+## Extends
+
+- `IComponent`
+
+## Methods
+
+### store() {#store}
+
+> **store**(`mailboxId`, `email`): `Promise`\<`string`\>
+
+Store an email received from a mailbox.
+
+#### Parameters
+
+##### mailboxId
+
+`string`
+
+The identifier of the mailbox that received the email.
+
+##### email
+
+[`IEmail`](IEmail.md)
+
+The email to store.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The identifier assigned to the stored email.
+
+***
+
+### get() {#get}
+
+> **get**(`id`): `Promise`\<[`IStoredEmail`](IStoredEmail.md)\>
+
+Retrieve a stored email by its identifier.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The identifier of the stored email.
+
+#### Returns
+
+`Promise`\<[`IStoredEmail`](IStoredEmail.md)\>
+
+The stored email.
+
+***
+
+### remove() {#remove}
+
+> **remove**(`id`): `Promise`\<`void`\>
+
+Remove a stored email by its identifier.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The identifier of the stored email to remove.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the email has been removed.
+
+***
+
+### query() {#query}
+
+> **query**(`sinceEpoch`, `mailboxId?`, `cursor?`, `limit?`): `Promise`\<\{ `emails`: [`IStoredEmail`](IStoredEmail.md)[]; `cursor?`: `string`; \}\>
+
+Query stored emails received at or after a given epoch.
+
+#### Parameters
+
+##### sinceEpoch
+
+`string`
+
+The ISO 8601 timestamp to filter emails received at or after.
+
+##### mailboxId?
+
+`string`
+
+An optional mailbox identifier to restrict results to.
+
+##### cursor?
+
+`string`
+
+An optional cursor for paginated results.
+
+##### limit?
+
+`number`
+
+An optional maximum number of results to return.
+
+#### Returns
+
+`Promise`\<\{ `emails`: [`IStoredEmail`](IStoredEmail.md)[]; `cursor?`: `string`; \}\>
+
+A page of stored emails and an optional cursor for the next page.

package/docs/reference/interfaces/IMailStorageGetRequest.md

@@ -0,0 +1,17 @@
+# Interface: IMailStorageGetRequest
+
+Request to retrieve a stored email by ID.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters.
+
+#### id
+
+> **id**: `string`
+
+The identifier of the stored email to retrieve.

package/docs/reference/interfaces/IMailStorageGetResponse.md

@@ -0,0 +1,11 @@
+# Interface: IMailStorageGetResponse
+
+Response from retrieving a stored email.
+
+## Properties
+
+### body {#body}
+
+> **body**: [`IStoredEmail`](IStoredEmail.md)
+
+The retrieved stored email.

package/docs/reference/interfaces/IMailStorageListRequest.md

@@ -0,0 +1,35 @@
+# Interface: IMailStorageListRequest
+
+Request to query stored emails.
+
+## Properties
+
+### query {#query}
+
+> **query**: `object`
+
+The query parameters.
+
+#### since
+
+> **since**: `string`
+
+Return only emails received at or after this ISO 8601 timestamp.
+
+#### mailboxId?
+
+> `optional` **mailboxId?**: `string`
+
+Filter emails by mailbox identifier.
+
+#### cursor?
+
+> `optional` **cursor?**: `string`
+
+The cursor for paginated results.
+
+#### limit?
+
+> `optional` **limit?**: `string`
+
+The maximum number of results to return.

package/docs/reference/interfaces/IMailStorageListResponse.md

@@ -0,0 +1,23 @@
+# Interface: IMailStorageListResponse
+
+Response from querying stored emails.
+
+## Properties
+
+### body {#body}
+
+> **body**: `object`
+
+The result body.
+
+#### emails
+
+> **emails**: [`IStoredEmail`](IStoredEmail.md)[]
+
+The list of stored emails.
+
+#### cursor?
+
+> `optional` **cursor?**: `string`
+
+The cursor for the next page of results.

package/docs/reference/interfaces/IMailStorageRemoveRequest.md

@@ -0,0 +1,17 @@
+# Interface: IMailStorageRemoveRequest
+
+Request to remove a stored email.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters.
+
+#### id
+
+> **id**: `string`
+
+The identifier of the stored email to remove.

package/docs/reference/interfaces/IMailbox.md

@@ -0,0 +1,97 @@
+# Interface: IMailbox\<TConfig, TState, TAuthState\>
+
+Interface describing a mailbox configuration.
+
+## Type Parameters
+
+### TConfig
+
+`TConfig` = `unknown`
+
+### TState
+
+`TState` = `unknown`
+
+### TAuthState
+
+`TAuthState` = `unknown`
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The unique identifier for the mailbox.
+
+***
+
+### name {#name}
+
+> **name**: `string`
+
+The display name for the mailbox.
+
+***
+
+### connectorType {#connectortype}
+
+> **connectorType**: `string`
+
+The connector type identifying which connector handles this mailbox.
+
+***
+
+### config? {#config}
+
+> `optional` **config?**: `TConfig`
+
+The connector-owned configuration for this mailbox.
+
+***
+
+### state? {#state}
+
+> `optional` **state?**: `TState`
+
+The connector-owned runtime state for this mailbox.
+
+***
+
+### enabled {#enabled}
+
+> **enabled**: `boolean`
+
+Whether this mailbox is active and should be polled.
+
+***
+
+### requiresAuth? {#requiresauth}
+
+> `optional` **requiresAuth?**: `boolean`
+
+Whether this mailbox is awaiting re-authentication.
+
+***
+
+### authState? {#authstate}
+
+> `optional` **authState?**: `TAuthState`
+
+Optional protocol-specific state produced during the auth flow, such as an OAuth URL or code.
+
+***
+
+### authError? {#autherror}
+
+> `optional` **authError?**: `IError`
+
+The last error returned by the authentication callback; cleared on successful authentication.
+
+***
+
+### retrievalError? {#retrievalerror}
+
+> `optional` **retrievalError?**: `IError`
+
+The last error returned by the retrieval callback; cleared on successful retrieval.

package/docs/reference/interfaces/IMailboxCompleteAuthRequest.md

@@ -0,0 +1,22 @@
+# Interface: IMailboxCompleteAuthRequest
+
+Request to complete an authentication flow, sent by the external provider redirecting the
+browser to the fixed callback route.
+
+## Properties
+
+### query {#query}
+
+> **query**: `object`
+
+The query parameters the provider appends to the callback URI.
+
+#### Index Signature
+
+\[`propertyKey`: `string`\]: `string`
+
+#### state
+
+> **state**: `string`
+
+The correlating state the connector placed in the external flow.