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

package/docs/reference/interfaces/IStoredEmail.md

@@ -0,0 +1,247 @@
+# Interface: IStoredEmail
+
+Interface describing an email message persisted by the mail storage component.
+
+## Extends
+
+- [`IEmail`](IEmail.md)
+
+## Properties
+
+### headers? {#headers}
+
+> `optional` **headers?**: [`IEmailHeader`](IEmailHeader.md)[]
+
+The parsed message headers.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`headers`](IEmail.md#headers)
+
+***
+
+### messageId? {#messageid}
+
+> `optional` **messageId?**: `string`
+
+The unique message identifier.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`messageId`](IEmail.md#messageid)
+
+***
+
+### from? {#from}
+
+> `optional` **from?**: [`IEmailAddress`](IEmailAddress.md)
+
+The sender address (From header).
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`from`](IEmail.md#from)
+
+***
+
+### sender? {#sender}
+
+> `optional` **sender?**: [`IEmailAddress`](IEmailAddress.md)
+
+The Sender header address, when different from From.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`sender`](IEmail.md#sender)
+
+***
+
+### to? {#to}
+
+> `optional` **to?**: [`IEmailAddress`](IEmailAddress.md)[]
+
+The primary recipient addresses.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`to`](IEmail.md#to)
+
+***
+
+### cc? {#cc}
+
+> `optional` **cc?**: [`IEmailAddress`](IEmailAddress.md)[]
+
+The carbon-copy recipient addresses.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`cc`](IEmail.md#cc)
+
+***
+
+### bcc? {#bcc}
+
+> `optional` **bcc?**: [`IEmailAddress`](IEmailAddress.md)[]
+
+The blind carbon-copy recipient addresses.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`bcc`](IEmail.md#bcc)
+
+***
+
+### replyTo? {#replyto}
+
+> `optional` **replyTo?**: [`IEmailAddress`](IEmailAddress.md)[]
+
+The reply-to addresses.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`replyTo`](IEmail.md#replyto)
+
+***
+
+### deliveredTo? {#deliveredto}
+
+> `optional` **deliveredTo?**: `string`
+
+The final delivery address from the Delivered-To header.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`deliveredTo`](IEmail.md#deliveredto)
+
+***
+
+### returnPath? {#returnpath}
+
+> `optional` **returnPath?**: `string`
+
+The Return-Path address.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`returnPath`](IEmail.md#returnpath)
+
+***
+
+### inReplyTo? {#inreplyto}
+
+> `optional` **inReplyTo?**: `string`
+
+The Message-ID this message is a reply to.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`inReplyTo`](IEmail.md#inreplyto)
+
+***
+
+### references? {#references}
+
+> `optional` **references?**: `string`
+
+The space-separated list of related message identifiers.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`references`](IEmail.md#references)
+
+***
+
+### subject? {#subject}
+
+> `optional` **subject?**: `string`
+
+The message subject.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`subject`](IEmail.md#subject)
+
+***
+
+### date? {#date}
+
+> `optional` **date?**: `string`
+
+The message date as an ISO 8601 string.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`date`](IEmail.md#date)
+
+***
+
+### textContent? {#textcontent}
+
+> `optional` **textContent?**: `string`
+
+The plain-text body of the message.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`textContent`](IEmail.md#textcontent)
+
+***
+
+### htmlContent? {#htmlcontent}
+
+> `optional` **htmlContent?**: `string`
+
+The HTML body of the message.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`htmlContent`](IEmail.md#htmlcontent)
+
+***
+
+### attachments? {#attachments}
+
+> `optional` **attachments?**: [`IEmailAttachment`](IEmailAttachment.md)[]
+
+The attachments included with the message.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`attachments`](IEmail.md#attachments)
+
+***
+
+### flags? {#flags}
+
+> `optional` **flags?**: `string`[]
+
+Protocol-level flags on the message, for example \\Seen.
+
+#### Inherited from
+
+[`IEmail`](IEmail.md).[`flags`](IEmail.md#flags)
+
+***
+
+### id {#id}
+
+> **id**: `string`
+
+The storage entity identifier.
+
+***
+
+### mailboxId {#mailboxid}
+
+> **mailboxId**: `string`
+
+The identifier of the mailbox that received the message.
+
+***
+
+### receivedAt {#receivedat}
+
+> **receivedAt**: `string`
+
+The ISO 8601 timestamp when the message was stored.

package/docs/reference/type-aliases/IEmailProtocolConnectorAuthCallback.md

@@ -0,0 +1,48 @@
+# Type Alias: IEmailProtocolConnectorAuthCallback\<TAuthState\>
+
+> **IEmailProtocolConnectorAuthCallback**\<`TAuthState`\> = (`mailboxId`, `updatedState`, `requiresAuth`, `authState?`, `authError?`) => `Promise`\<`void`\>
+
+Callback invoked by a protocol connector to report the outcome of an authentication attempt.
+
+## Type Parameters
+
+### TAuthState
+
+`TAuthState` *extends* [`IEmailProtocolConnectorAuthState`](../interfaces/IEmailProtocolConnectorAuthState.md) = [`IEmailProtocolConnectorAuthState`](../interfaces/IEmailProtocolConnectorAuthState.md)
+
+## Parameters
+
+### mailboxId
+
+`string`
+
+The identifier of the mailbox this authentication attempt belongs to.
+
+### updatedState
+
+`unknown` \| `undefined`
+
+Optional connector state to persist on the mailbox entity, carrying any
+credentials the flow issued in the properties the connector state schema marks as secure.
+
+### requiresAuth
+
+`boolean`
+
+True if authentication failed due to invalid or expired credentials.
+
+### authState?
+
+`TAuthState`
+
+Optional state produced during the auth flow, carrying the URL to open.
+
+### authError?
+
+`IError`
+
+Optional structured error covering all failure types (auth, connection, timeout, etc.).
+
+## Returns
+
+`Promise`\<`void`\>

package/docs/reference/type-aliases/IEmailProtocolConnectorRetrievalCallback.md

@@ -0,0 +1,35 @@
+# Type Alias: IEmailProtocolConnectorRetrievalCallback
+
+> **IEmailProtocolConnectorRetrievalCallback** = (`mailboxId`, `message`, `updatedState`, `retrievalError?`) => `Promise`\<`boolean`\>
+
+Callback invoked by a protocol connector to persist a single retrieved message.
+
+## Parameters
+
+### mailboxId
+
+`string`
+
+The identifier of the mailbox this retrieval belongs to.
+
+### message
+
+[`IEmail`](../interfaces/IEmail.md) \| `undefined`
+
+The message to persist.
+
+### updatedState
+
+`unknown`
+
+The connector state to persist on the mailbox entity after this message.
+
+### retrievalError?
+
+`IError`
+
+## Returns
+
+`Promise`\<`boolean`\>
+
+True if the message was persisted successfully; false causes the connector to exit the polling loop.

package/docs/reference/type-aliases/MailboxMetricIds.md

@@ -0,0 +1,5 @@
+# Type Alias: MailboxMetricIds
+
+> **MailboxMetricIds** = *typeof* [`MailboxMetricIds`](../variables/MailboxMetricIds.md)\[keyof *typeof* [`MailboxMetricIds`](../variables/MailboxMetricIds.md)\]
+
+Union type of all mailbox service metric ID string values.

package/docs/reference/variables/EmailConsumerFactory.md

@@ -0,0 +1,5 @@
+# Variable: EmailConsumerFactory
+
+> `const` **EmailConsumerFactory**: `Factory`\<[`IEmailConsumer`](../interfaces/IEmailConsumer.md)\>
+
+Factory for creating email consumer instances.

package/docs/reference/variables/EmailProtocolConnectorConfigSchemaFactory.md

@@ -0,0 +1,5 @@
+# Variable: EmailProtocolConnectorConfigSchemaFactory
+
+> `const` **EmailProtocolConnectorConfigSchemaFactory**: `Factory`\<[`IMailboxConfigField`](../interfaces/IMailboxConfigField.md)[]\>
+
+Factory for retrieving email protocol connector configuration field definitions.

package/docs/reference/variables/EmailProtocolConnectorFactory.md

@@ -0,0 +1,5 @@
+# Variable: EmailProtocolConnectorFactory
+
+> `const` **EmailProtocolConnectorFactory**: `Factory`\<[`IEmailProtocolConnector`](../interfaces/IEmailProtocolConnector.md)\<`unknown`, [`IEmailProtocolConnectorAuthState`](../interfaces/IEmailProtocolConnectorAuthState.md)\>\>
+
+Factory for creating email protocol connectors.

package/docs/reference/variables/EmailProtocolConnectorStateSchemaFactory.md

@@ -0,0 +1,7 @@
+# Variable: EmailProtocolConnectorStateSchemaFactory
+
+> `const` **EmailProtocolConnectorStateSchemaFactory**: `Factory`\<[`IMailboxConfigField`](../interfaces/IMailboxConfigField.md)[]\>
+
+Factory for retrieving email protocol connector state field definitions.
+Only the properties a connector holds in its runtime state need registering here, and the ones
+marked secure are stored in the vault instead of alongside the rest of the state.

package/docs/reference/variables/MailboxMetricIds.md

@@ -0,0 +1,13 @@
+# Variable: MailboxMetricIds
+
+> `const` **MailboxMetricIds**: `object`
+
+Metric IDs for the mailbox service.
+
+## Type Declaration
+
+### EmailsReceived {#emailsreceived}
+
+> `readonly` **EmailsReceived**: `"mailbox_emails_received"` = `"mailbox_emails_received"`
+
+Number of emails received across all mailboxes.

package/docs/reference/variables/MailboxMetrics.md

@@ -0,0 +1,5 @@
+# Variable: MailboxMetrics
+
+> `const` **MailboxMetrics**: `ITelemetryMetric`[]
+
+Metrics registered by the mailbox service.

package/locales/en.json

@@ -0,0 +1 @@
+{}

package/package.json

@@ -1,6 +1,55 @@
 {
-  "name": "@3sixty/mailbox-models",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@3sixty/mailbox-models",
+	"version": "0.20.0-next.0",
+	"description": "Defines the shared models and factory helpers for email mailbox ingestion.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/3sixtyglobal/messaging.git",
+		"directory": "packages/mailbox-models"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=24.0.0"
+	},
+	"dependencies": {
+		"@3sixty/core": "next",
+		"@3sixty/entity": "next",
+		"@3sixty/nameof": "next",
+		"@3sixty/telemetry-models": "next",
+		"@3sixty/web": "next",
+		"postal-mime": "3.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",
+		"ingestion",
+		"models"
+	],
+	"bugs": {
+		"url": "git+https://github.com/3sixtyglobal/messaging/issues"
+	},
+	"homepage": "https://3sixty.global"
+}