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

package/docs/reference/interfaces/IMailboxComponent.md

@@ -0,0 +1,191 @@
+# Interface: IMailboxComponent
+
+Interface describing the mailbox management component.
+
+## Extends
+
+- `IComponent`
+
+## Methods
+
+### createMailbox() {#createmailbox}
+
+> **createMailbox**(`mailbox`): `Promise`\<[`IMailboxCreateResult`](IMailboxCreateResult.md)\>
+
+Create a new mailbox and begin polling for it.
+Connectors whose credentials are issued by an external flow are asked to start it here, so
+the URL the user has to open is returned to the caller which created the mailbox instead of
+only surfacing once the first poll has run.
+
+#### Parameters
+
+##### mailbox
+
+`Pick`\<[`IMailbox`](IMailbox.md), `"name"` \| `"connectorType"` \| `"config"` \| `"enabled"`\>
+
+The mailbox configuration to create.
+
+#### Returns
+
+`Promise`\<[`IMailboxCreateResult`](IMailboxCreateResult.md)\>
+
+The identifier assigned to the new mailbox, with the URL to open when the mailbox
+must be authenticated before it can be polled.
+
+***
+
+### updateMailbox() {#updatemailbox}
+
+> **updateMailbox**(`mailbox`): `Promise`\<[`IMailboxUpdateResult`](IMailboxUpdateResult.md)\>
+
+Update an existing mailbox.
+An update replaces the credentials the mailbox authenticates with, so a connector whose
+credentials are issued by an external flow is asked to start a new one, and the URL the
+user has to open is returned the same way it is when the mailbox is created.
+
+#### Parameters
+
+##### mailbox
+
+[`IMailbox`](IMailbox.md)
+
+The updated mailbox configuration.
+
+#### Returns
+
+`Promise`\<[`IMailboxUpdateResult`](IMailboxUpdateResult.md)\>
+
+The URL to open when the mailbox must be authenticated before it can be polled.
+
+***
+
+### removeMailbox() {#removemailbox}
+
+> **removeMailbox**(`id`): `Promise`\<`void`\>
+
+Remove a mailbox and stop polling for it.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The identifier of the mailbox to remove.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the mailbox has been removed.
+
+***
+
+### getMailbox() {#getmailbox}
+
+> **getMailbox**(`id`): `Promise`\<[`IMailbox`](IMailbox.md)\<`unknown`, `unknown`, `unknown`\>\>
+
+Retrieve a mailbox by its identifier.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The identifier of the mailbox to retrieve.
+
+#### Returns
+
+`Promise`\<[`IMailbox`](IMailbox.md)\<`unknown`, `unknown`, `unknown`\>\>
+
+The mailbox.
+
+***
+
+### listMailboxes() {#listmailboxes}
+
+> **listMailboxes**(`cursor?`, `limit?`): `Promise`\<\{ `mailboxes`: [`IMailbox`](IMailbox.md)\<`unknown`, `unknown`, `unknown`\>[]; `cursor?`: `string`; \}\>
+
+List all mailboxes with optional cursor-based pagination.
+
+#### Parameters
+
+##### cursor?
+
+`string`
+
+An optional cursor for paginated results.
+
+##### limit?
+
+`number`
+
+An optional maximum number of results to return.
+
+#### Returns
+
+`Promise`\<\{ `mailboxes`: [`IMailbox`](IMailbox.md)\<`unknown`, `unknown`, `unknown`\>[]; `cursor?`: `string`; \}\>
+
+A page of mailboxes and an optional cursor for the next page.
+
+***
+
+### completeAuth() {#completeauth}
+
+> **completeAuth**(`authPayload`): `Promise`\<`void`\>
+
+Complete an authentication flow for a mailbox awaiting authentication.
+The mailbox is correlated from the payload's state property, which the connector placed in
+the external flow when it produced its auth state, and which names the partition as well as
+the mailbox. The connector exchanges the payload for its credentials, which are stored on
+the mailbox state, and polling restarts.
+
+#### Parameters
+
+##### authPayload
+
+`unknown`
+
+The data handed to the callback URI, carrying the correlating state.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the mailbox has been authenticated.
+
+#### Throws
+
+NotFoundError if the correlated mailbox does not exist.
+
+#### Throws
+
+GeneralError if the mailbox is not awaiting authentication, or its connector has no
+authentication flow.
+
+***
+
+### getSchema() {#getschema}
+
+> **getSchema**(`connectorType`): `Promise`\<[`IMailboxConfigField`](IMailboxConfigField.md)[]\>
+
+Get the configuration schema for a connector type.
+
+#### Parameters
+
+##### connectorType
+
+`string`
+
+The connector type to get the schema for.
+
+#### Returns
+
+`Promise`\<[`IMailboxConfigField`](IMailboxConfigField.md)[]\>
+
+The configuration field definitions for the connector.
+
+#### Throws
+
+NotFoundError if no schema is registered for the connector type.

package/docs/reference/interfaces/IMailboxConfigField.md

@@ -0,0 +1,51 @@
+# Interface: IMailboxConfigField
+
+Interface describing a single configuration field for a protocol connector.
+
+## Properties
+
+### labelKey {#labelkey}
+
+> **labelKey**: `string`
+
+The i18n key for the field label shown in the UI.
+
+***
+
+### propertyKey {#propertykey}
+
+> **propertyKey**: `string`
+
+The key of the property within the connector config object.
+
+***
+
+### type {#type}
+
+> **type**: `EntitySchemaPropertyType`
+
+The entity schema property type for this field.
+
+***
+
+### isSecure? {#issecure}
+
+> `optional` **isSecure?**: `boolean`
+
+Whether this field holds a sensitive value that should be stored in the vault.
+
+***
+
+### itemType? {#itemtype}
+
+> `optional` **itemType?**: `EntitySchemaPropertyType`
+
+The element type when `type` is `Array`.
+
+***
+
+### defaultValue? {#defaultvalue}
+
+> `optional` **defaultValue?**: `unknown`
+
+An optional default value for the field.

package/docs/reference/interfaces/IMailboxConnectorSchemaRequest.md

@@ -0,0 +1,17 @@
+# Interface: IMailboxConnectorSchemaRequest
+
+Request to retrieve the configuration schema for a connector.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters.
+
+#### connectorType
+
+> **connectorType**: `string`
+
+The connector type identifier.

package/docs/reference/interfaces/IMailboxConnectorSchemaResponse.md

@@ -0,0 +1,11 @@
+# Interface: IMailboxConnectorSchemaResponse
+
+Response from retrieving a connector configuration schema.
+
+## Properties
+
+### body {#body}
+
+> **body**: [`IMailboxConfigField`](IMailboxConfigField.md)[]
+
+The schema fields for the connector.

package/docs/reference/interfaces/IMailboxCreateRequest.md

@@ -0,0 +1,11 @@
+# Interface: IMailboxCreateRequest
+
+Request to create a new mailbox.
+
+## Properties
+
+### body {#body}
+
+> **body**: `Pick`\<[`IMailbox`](IMailbox.md), `"name"` \| `"connectorType"` \| `"config"` \| `"enabled"`\>
+
+The mailbox to create.

package/docs/reference/interfaces/IMailboxCreateResponse.md

@@ -0,0 +1,40 @@
+# Interface: IMailboxCreateResponse
+
+Response to creating a new mailbox.
+
+## Properties
+
+### statusCode {#statuscode}
+
+> **statusCode**: `201`
+
+Response status code.
+
+***
+
+### headers {#headers}
+
+> **headers**: `object`
+
+Additional response headers.
+
+#### location
+
+> **location**: `string`
+
+The location where the mailbox was created.
+
+***
+
+### body {#body}
+
+> **body**: `object`
+
+The body of the response.
+
+#### authUrl?
+
+> `optional` **authUrl?**: `string`
+
+The URL to open for the user when the mailbox must complete an external authentication
+flow, such as an OAuth consent URL, before it can be polled.

package/docs/reference/interfaces/IMailboxCreateResult.md

@@ -0,0 +1,21 @@
+# Interface: IMailboxCreateResult
+
+The outcome of creating a mailbox.
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The identifier assigned to the new mailbox.
+
+***
+
+### authUrl? {#authurl}
+
+> `optional` **authUrl?**: `string`
+
+The URL to open for the user when the mailbox cannot be polled until an external
+authentication flow has completed, such as an OAuth consent URL. Absent when the supplied
+configuration is already sufficient to poll the mailbox.

package/docs/reference/interfaces/IMailboxGetRequest.md

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

package/docs/reference/interfaces/IMailboxGetResponse.md

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

package/docs/reference/interfaces/IMailboxListRequest.md

@@ -0,0 +1,23 @@
+# Interface: IMailboxListRequest
+
+Request to list mailboxes with optional pagination.
+
+## Properties
+
+### query? {#query}
+
+> `optional` **query?**: `object`
+
+The query parameters.
+
+#### cursor?
+
+> `optional` **cursor?**: `string`
+
+The cursor for paginated results.
+
+#### limit?
+
+> `optional` **limit?**: `string`
+
+The maximum number of results to return.

package/docs/reference/interfaces/IMailboxListResponse.md

@@ -0,0 +1,23 @@
+# Interface: IMailboxListResponse
+
+Response from listing mailboxes.
+
+## Properties
+
+### body {#body}
+
+> **body**: `object`
+
+The result body.
+
+#### mailboxes
+
+> **mailboxes**: [`IMailbox`](IMailbox.md)\<`unknown`, `unknown`, `unknown`\>[]
+
+The list of mailboxes.
+
+#### cursor?
+
+> `optional` **cursor?**: `string`
+
+The cursor for the next page of results.

package/docs/reference/interfaces/IMailboxRemoveRequest.md

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

package/docs/reference/interfaces/IMailboxUpdateRequest.md

@@ -0,0 +1,25 @@
+# Interface: IMailboxUpdateRequest
+
+Request to update an existing mailbox.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters.
+
+#### id
+
+> **id**: `string`
+
+The identifier of the mailbox to update.
+
+***
+
+### body {#body}
+
+> **body**: [`IMailbox`](IMailbox.md)
+
+The updated mailbox configuration.

package/docs/reference/interfaces/IMailboxUpdateResponse.md

@@ -0,0 +1,26 @@
+# Interface: IMailboxUpdateResponse
+
+Response to updating a mailbox.
+
+## Properties
+
+### statusCode {#statuscode}
+
+> **statusCode**: `200`
+
+Response status code.
+
+***
+
+### body {#body}
+
+> **body**: `object`
+
+The body of the response.
+
+#### authUrl?
+
+> `optional` **authUrl?**: `string`
+
+The URL to open for the user when the updated mailbox must complete an external
+authentication flow, such as an OAuth consent URL, before it can be polled.

package/docs/reference/interfaces/IMailboxUpdateResult.md

@@ -0,0 +1,13 @@
+# Interface: IMailboxUpdateResult
+
+The outcome of updating a mailbox.
+
+## Properties
+
+### authUrl? {#authurl}
+
+> `optional` **authUrl?**: `string`
+
+The URL to open for the user when the updated mailbox cannot be polled until an external
+authentication flow has completed, such as an OAuth consent URL. Absent when the updated
+configuration is already sufficient to poll the mailbox.