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

package/docs/examples.md

@@ -0,0 +1,145 @@
+# Mailbox Models Examples
+
+Factories, callback types, and utilities shared by mailbox connectors, services, and consumers.
+
+## MailHelper
+
+```typescript
+import { MailHelper } from '@3sixty/mailbox-models';
+import type { IEmail } from '@3sixty/mailbox-models';
+
+// Parse a raw RFC 2822 email string, with optional IMAP flags
+const raw =
+  'From: Alice <alice@example.com>\r\n' +
+  'To: Bob <bob@example.com>\r\n' +
+  'Subject: Hello\r\n' +
+  'Date: Mon, 01 Sep 2026 08:00:00 +0000\r\n' +
+  '\r\n' +
+  'Hi Bob, just checking in.';
+
+const email: IEmail | undefined = await MailHelper.parseEmail(raw, ['\\Seen']);
+console.log(email?.subject); // "Hello"
+console.log(email?.from); // { name: "Alice", address: "alice@example.com" }
+console.log(email?.flags); // ["\\Seen"]
+```
+
+```typescript
+import { MailHelper } from '@3sixty/mailbox-models';
+import type { IEmailAddress } from '@3sixty/mailbox-models';
+
+// Map a single address-like object; returns undefined when no address string is present
+const address: IEmailAddress | undefined = MailHelper.mapAddress({
+  name: 'Alice',
+  address: 'alice@example.com'
+});
+console.log(address); // { name: "Alice", address: "alice@example.com" }
+
+const missing = MailHelper.mapAddress({ name: 'No Address' });
+console.log(missing); // undefined
+
+// Map an array, filtering out any entry that lacks an address string
+const addresses: IEmailAddress[] | undefined = MailHelper.mapAddresses([
+  { name: 'Alice', address: 'alice@example.com' },
+  { name: 'Bob', address: 'bob@example.com' },
+  { name: 'Ghost' }
+]);
+console.log(addresses?.length); // 2
+```
+
+## EmailProtocolConnectorFactory
+
+```typescript
+import {
+  EmailProtocolConnectorFactory,
+  EmailProtocolConnectorConfigSchemaFactory
+} from '@3sixty/mailbox-models';
+import type { IEmailProtocolConnector, IMailboxConfigField } from '@3sixty/mailbox-models';
+import { EntitySchemaPropertyType } from '@3sixty/entity';
+
+// Register a connector implementation under a protocol namespace
+EmailProtocolConnectorFactory.register('pop3', () => {
+  return {} as IEmailProtocolConnector;
+});
+
+// Register its config field schema so the service can identify secure fields for vault storage
+const configSchema: IMailboxConfigField[] = [
+  {
+    labelKey: 'pop3.host',
+    propertyKey: 'host',
+    type: EntitySchemaPropertyType.String
+  },
+  {
+    labelKey: 'pop3.password',
+    propertyKey: 'password',
+    type: EntitySchemaPropertyType.String,
+    isSecure: true
+  }
+];
+EmailProtocolConnectorConfigSchemaFactory.register('pop3', () => configSchema);
+
+const connector = EmailProtocolConnectorFactory.get('pop3');
+const schema = EmailProtocolConnectorConfigSchemaFactory.get('pop3');
+console.log(schema.find(f => f.isSecure)?.propertyKey); // "password"
+```
+
+## EmailConsumerFactory
+
+```typescript
+import { EmailConsumerFactory } from '@3sixty/mailbox-models';
+import type { IEmailConsumer } from '@3sixty/mailbox-models';
+
+class NotificationConsumer implements IEmailConsumer {
+  public className(): string {
+    return 'NotificationConsumer';
+  }
+
+  public async onNewMessages(): Promise<void> {
+    // react to newly stored messages
+  }
+}
+
+// Register a consumer so the mailbox service notifies it after each retrieval cycle
+EmailConsumerFactory.register('notifications', () => new NotificationConsumer());
+
+const consumer = EmailConsumerFactory.get('notifications');
+console.log(consumer.className()); // "NotificationConsumer"
+```
+
+## IEmailProtocolConnectorAuthCallback
+
+```typescript
+import type {
+  IEmailProtocolConnectorAuthCallback,
+  IEmailProtocolConnectorRetrievalCallback
+} from '@3sixty/mailbox-models';
+
+// Called when the connector detects an authentication failure
+const authCallback: IEmailProtocolConnectorAuthCallback = async (
+  mailboxId,
+  requiresAuth,
+  updatedState,
+  error,
+  authState
+) => {
+  if (requiresAuth) {
+    console.log(`Mailbox ${mailboxId} needs re-authentication`);
+  }
+};
+
+// Called after each batch of messages is retrieved (or on error)
+const retrievalCallback: IEmailProtocolConnectorRetrievalCallback = async (
+  mailboxId,
+  messages,
+  updatedState,
+  error
+) => {
+  console.log(messages.length); // number of messages in this batch
+  for (const message of messages) {
+    console.log(message.subject); // e.g. "Weekly report"
+    console.log(message.from?.address); // e.g. "alice@example.com"
+  }
+  if (error !== undefined) {
+    console.log(error.message); // description of the retrieval problem
+  }
+};
+```

package/docs/reference/classes/MailHelper.md

@@ -0,0 +1,118 @@
+# Class: MailHelper
+
+Shared utilities for parsing raw RFC822 email messages and mapping postal-mime address objects.
+
+## Constructors
+
+### Constructor
+
+> **new MailHelper**(): `MailHelper`
+
+#### Returns
+
+`MailHelper`
+
+## Methods
+
+### mapAddress() {#mapaddress}
+
+> `static` **mapAddress**(`address?`): [`IEmailAddress`](../interfaces/IEmailAddress.md) \| `undefined`
+
+Map a postal-mime address object to an IEmailAddress, or return undefined when no address is present.
+
+#### Parameters
+
+##### address?
+
+The postal-mime address to map.
+
+###### name
+
+`string`
+
+The display name of the email address.
+
+###### address?
+
+`string`
+
+The email address string.
+
+#### Returns
+
+[`IEmailAddress`](../interfaces/IEmailAddress.md) \| `undefined`
+
+The mapped address, or undefined.
+
+***
+
+### mapAddresses() {#mapaddresses}
+
+> `static` **mapAddresses**(`addresses`): [`IEmailAddress`](../interfaces/IEmailAddress.md)[] \| `undefined`
+
+Map an array of postal-mime address objects to IEmailAddress[], or return undefined when the input is empty.
+
+#### Parameters
+
+##### addresses
+
+`object`[] \| `undefined`
+
+The postal-mime addresses to map.
+
+#### Returns
+
+[`IEmailAddress`](../interfaces/IEmailAddress.md)[] \| `undefined`
+
+The mapped addresses, or undefined.
+
+***
+
+### parseEmail() {#parseemail}
+
+> `static` **parseEmail**(`raw`, `flags?`): `Promise`\<[`IEmail`](../interfaces/IEmail.md) \| `undefined`\>
+
+Parse a raw RFC822 email string into an IEmail object using postal-mime.
+
+#### Parameters
+
+##### raw
+
+`string`
+
+The raw email string.
+
+##### flags?
+
+`string`[]
+
+Optional IMAP flags associated with the message.
+
+#### Returns
+
+`Promise`\<[`IEmail`](../interfaces/IEmail.md) \| `undefined`\>
+
+The parsed email, or undefined if the input is empty.
+
+***
+
+### attachmentToBase64() {#attachmenttobase64}
+
+> `static` **attachmentToBase64**(`content`): `string`
+
+Convert postal-mime attachment content to a base64 string.
+Handles string (text), Uint8Array, and ArrayBuffer inputs.
+
+#### Parameters
+
+##### content
+
+`string` \| `ArrayBuffer` \| `Uint8Array`\<`ArrayBufferLike`\>
+
+The attachment content.
+
+#### Returns
+
+`string`
+
+The base64-encoded content.

package/docs/reference/index.md

@@ -0,0 +1,55 @@
+# @3sixty/mailbox-models
+
+## Classes
+
+- [MailHelper](classes/MailHelper.md)
+
+## Interfaces
+
+- [IEmail](interfaces/IEmail.md)
+- [IEmailAddress](interfaces/IEmailAddress.md)
+- [IEmailAttachment](interfaces/IEmailAttachment.md)
+- [IEmailConsumer](interfaces/IEmailConsumer.md)
+- [IEmailHeader](interfaces/IEmailHeader.md)
+- [IEmailProtocolConnector](interfaces/IEmailProtocolConnector.md)
+- [IEmailProtocolConnectorAuthState](interfaces/IEmailProtocolConnectorAuthState.md)
+- [IEmailProtocolConnectorOptions](interfaces/IEmailProtocolConnectorOptions.md)
+- [IMailStorageComponent](interfaces/IMailStorageComponent.md)
+- [IMailbox](interfaces/IMailbox.md)
+- [IMailboxComponent](interfaces/IMailboxComponent.md)
+- [IMailboxConfigField](interfaces/IMailboxConfigField.md)
+- [IMailboxCreateResult](interfaces/IMailboxCreateResult.md)
+- [IMailboxUpdateResult](interfaces/IMailboxUpdateResult.md)
+- [IStoredEmail](interfaces/IStoredEmail.md)
+- [IMailStorageGetRequest](interfaces/IMailStorageGetRequest.md)
+- [IMailStorageGetResponse](interfaces/IMailStorageGetResponse.md)
+- [IMailStorageListRequest](interfaces/IMailStorageListRequest.md)
+- [IMailStorageListResponse](interfaces/IMailStorageListResponse.md)
+- [IMailStorageRemoveRequest](interfaces/IMailStorageRemoveRequest.md)
+- [IMailboxCompleteAuthRequest](interfaces/IMailboxCompleteAuthRequest.md)
+- [IMailboxConnectorSchemaRequest](interfaces/IMailboxConnectorSchemaRequest.md)
+- [IMailboxConnectorSchemaResponse](interfaces/IMailboxConnectorSchemaResponse.md)
+- [IMailboxCreateRequest](interfaces/IMailboxCreateRequest.md)
+- [IMailboxCreateResponse](interfaces/IMailboxCreateResponse.md)
+- [IMailboxGetRequest](interfaces/IMailboxGetRequest.md)
+- [IMailboxGetResponse](interfaces/IMailboxGetResponse.md)
+- [IMailboxListRequest](interfaces/IMailboxListRequest.md)
+- [IMailboxListResponse](interfaces/IMailboxListResponse.md)
+- [IMailboxRemoveRequest](interfaces/IMailboxRemoveRequest.md)
+- [IMailboxUpdateRequest](interfaces/IMailboxUpdateRequest.md)
+- [IMailboxUpdateResponse](interfaces/IMailboxUpdateResponse.md)
+
+## Type Aliases
+
+- [IEmailProtocolConnectorAuthCallback](type-aliases/IEmailProtocolConnectorAuthCallback.md)
+- [IEmailProtocolConnectorRetrievalCallback](type-aliases/IEmailProtocolConnectorRetrievalCallback.md)
+- [MailboxMetricIds](type-aliases/MailboxMetricIds.md)
+
+## Variables
+
+- [EmailConsumerFactory](variables/EmailConsumerFactory.md)
+- [EmailProtocolConnectorConfigSchemaFactory](variables/EmailProtocolConnectorConfigSchemaFactory.md)
+- [EmailProtocolConnectorFactory](variables/EmailProtocolConnectorFactory.md)
+- [EmailProtocolConnectorStateSchemaFactory](variables/EmailProtocolConnectorStateSchemaFactory.md)
+- [MailboxMetricIds](variables/MailboxMetricIds.md)
+- [MailboxMetrics](variables/MailboxMetrics.md)

package/docs/reference/interfaces/IEmail.md

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

package/docs/reference/interfaces/IEmailAddress.md

@@ -0,0 +1,19 @@
+# Interface: IEmailAddress
+
+Interface describing an email address with an optional display name.
+
+## Properties
+
+### name? {#name}
+
+> `optional` **name?**: `string`
+
+The display name for the address.
+
+***
+
+### address {#address}
+
+> **address**: `string`
+
+The email address.

package/docs/reference/interfaces/IEmailAttachment.md

@@ -0,0 +1,27 @@
+# Interface: IEmailAttachment
+
+Interface describing an email attachment.
+
+## Properties
+
+### filename? {#filename}
+
+> `optional` **filename?**: `string`
+
+The filename of the attachment.
+
+***
+
+### contentType {#contenttype}
+
+> **contentType**: `string`
+
+The MIME content type of the attachment.
+
+***
+
+### data {#data}
+
+> **data**: `string`
+
+The attachment data encoded as a base64 string.

package/docs/reference/interfaces/IEmailConsumer.md

@@ -0,0 +1,21 @@
+# Interface: IEmailConsumer
+
+Interface describing a consumer that is notified when new emails are available.
+
+## Extends
+
+- `IComponent`
+
+## Methods
+
+### onNewMessages() {#onnewmessages}
+
+> **onNewMessages**(): `Promise`\<`void`\>
+
+Called when new emails have been stored, prompting the consumer to query for them.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the consumer has processed the notification.

package/docs/reference/interfaces/IEmailHeader.md

@@ -0,0 +1,27 @@
+# Interface: IEmailHeader
+
+Interface describing a single parsed email header.
+
+## Properties
+
+### key {#key}
+
+> **key**: `string`
+
+The lowercase header name.
+
+***
+
+### originalKey {#originalkey}
+
+> **originalKey**: `string`
+
+The original header name preserving case.
+
+***
+
+### value {#value}
+
+> **value**: `string`
+
+The header value.