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

package/dist/es/models/api/IMailboxCompleteAuthRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxCompleteAuthRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxCompleteAuthRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Request to complete an authentication flow, sent by the external provider redirecting the\n * browser to the fixed callback route.\n */\nexport interface IMailboxCompleteAuthRequest {\n\t/**\n\t * The query parameters the provider appends to the callback URI.\n\t */\n\tquery: {\n\t\t[propertyKey: string]: string;\n\n\t\t/**\n\t\t * The correlating state the connector placed in the external flow.\n\t\t */\n\t\tstate: string;\n\t};\n}\n"]}

package/dist/es/models/api/IMailboxConnectorSchemaRequest.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IMailboxConnectorSchemaRequest.js.map

package/dist/es/models/api/IMailboxConnectorSchemaRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxConnectorSchemaRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxConnectorSchemaRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Request to retrieve the configuration schema for a connector.\n */\nexport interface IMailboxConnectorSchemaRequest {\n\t/**\n\t * The path parameters.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The connector type identifier.\n\t\t */\n\t\tconnectorType: string;\n\t};\n}\n"]}

package/dist/es/models/api/IMailboxConnectorSchemaResponse.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMailboxConnectorSchemaResponse.js.map

package/dist/es/models/api/IMailboxConnectorSchemaResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxConnectorSchemaResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxConnectorSchemaResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMailboxConfigField } from \"../IMailboxConfigField.js\";\n\n/**\n * Response from retrieving a connector configuration schema.\n */\nexport interface IMailboxConnectorSchemaResponse {\n\t/**\n\t * The schema fields for the connector.\n\t */\n\tbody: IMailboxConfigField[];\n}\n"]}

package/dist/es/models/api/IMailboxCreateRequest.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMailboxCreateRequest.js.map

package/dist/es/models/api/IMailboxCreateRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxCreateRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxCreateRequest.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMailbox } from \"../IMailbox.js\";\n\n/**\n * Request to create a new mailbox.\n */\nexport interface IMailboxCreateRequest {\n\t/**\n\t * The mailbox to create.\n\t */\n\tbody: Pick<IMailbox, \"name\" | \"connectorType\" | \"config\" | \"enabled\">;\n}\n"]}

package/dist/es/models/api/IMailboxCreateResponse.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMailboxCreateResponse.js.map

package/dist/es/models/api/IMailboxCreateResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxCreateResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxCreateResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { HeaderTypes, HttpStatusCode } from \"@3sixty/web\";\n\n/**\n * Response to creating a new mailbox.\n */\nexport interface IMailboxCreateResponse {\n\t/**\n\t * Response status code.\n\t */\n\tstatusCode: typeof HttpStatusCode.created;\n\n\t/**\n\t * Additional response headers.\n\t */\n\theaders: {\n\t\t/**\n\t\t * The location where the mailbox was created.\n\t\t */\n\t\t[HeaderTypes.Location]: string;\n\t};\n\n\t/**\n\t * The body of the response.\n\t */\n\tbody: {\n\t\t/**\n\t\t * The URL to open for the user when the mailbox must complete an external authentication\n\t\t * flow, such as an OAuth consent URL, before it can be polled.\n\t\t */\n\t\tauthUrl?: string;\n\t};\n}\n"]}

package/dist/es/models/api/IMailboxGetRequest.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IMailboxGetRequest.js.map

package/dist/es/models/api/IMailboxGetRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxGetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxGetRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Request to retrieve a mailbox by ID.\n */\nexport interface IMailboxGetRequest {\n\t/**\n\t * The path parameters.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The identifier of the mailbox to retrieve.\n\t\t */\n\t\tid: string;\n\t};\n}\n"]}

package/dist/es/models/api/IMailboxGetResponse.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMailboxGetResponse.js.map

package/dist/es/models/api/IMailboxGetResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxGetResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxGetResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMailbox } from \"../IMailbox.js\";\n\n/**\n * Response from retrieving a mailbox.\n */\nexport interface IMailboxGetResponse {\n\t/**\n\t * The retrieved mailbox.\n\t */\n\tbody: IMailbox;\n}\n"]}

package/dist/es/models/api/IMailboxListRequest.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IMailboxListRequest.js.map

package/dist/es/models/api/IMailboxListRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxListRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxListRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Request to list mailboxes with optional pagination.\n */\nexport interface IMailboxListRequest {\n\t/**\n\t * The query parameters.\n\t */\n\tquery?: {\n\t\t/**\n\t\t * The cursor for paginated results.\n\t\t */\n\t\tcursor?: string;\n\n\t\t/**\n\t\t * The maximum number of results to return.\n\t\t */\n\t\tlimit?: string;\n\t};\n}\n"]}

package/dist/es/models/api/IMailboxListResponse.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMailboxListResponse.js.map

package/dist/es/models/api/IMailboxListResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxListResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxListResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMailbox } from \"../IMailbox.js\";\n\n/**\n * Response from listing mailboxes.\n */\nexport interface IMailboxListResponse {\n\t/**\n\t * The result body.\n\t */\n\tbody: {\n\t\t/**\n\t\t * The list of mailboxes.\n\t\t */\n\t\tmailboxes: IMailbox[];\n\n\t\t/**\n\t\t * The cursor for the next page of results.\n\t\t */\n\t\tcursor?: string;\n\t};\n}\n"]}

package/dist/es/models/api/IMailboxRemoveRequest.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IMailboxRemoveRequest.js.map

package/dist/es/models/api/IMailboxRemoveRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxRemoveRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxRemoveRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Request to remove a mailbox.\n */\nexport interface IMailboxRemoveRequest {\n\t/**\n\t * The path parameters.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The identifier of the mailbox to remove.\n\t\t */\n\t\tid: string;\n\t};\n}\n"]}

package/dist/es/models/api/IMailboxUpdateRequest.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMailboxUpdateRequest.js.map

package/dist/es/models/api/IMailboxUpdateRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxUpdateRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxUpdateRequest.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMailbox } from \"../IMailbox.js\";\n\n/**\n * Request to update an existing mailbox.\n */\nexport interface IMailboxUpdateRequest {\n\t/**\n\t * The path parameters.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The identifier of the mailbox to update.\n\t\t */\n\t\tid: string;\n\t};\n\n\t/**\n\t * The updated mailbox configuration.\n\t */\n\tbody: IMailbox;\n}\n"]}

package/dist/es/models/api/IMailboxUpdateResponse.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMailboxUpdateResponse.js.map

package/dist/es/models/api/IMailboxUpdateResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMailboxUpdateResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IMailboxUpdateResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { HttpStatusCode } from \"@3sixty/web\";\n\n/**\n * Response to updating a mailbox.\n */\nexport interface IMailboxUpdateResponse {\n\t/**\n\t * Response status code.\n\t */\n\tstatusCode: typeof HttpStatusCode.ok;\n\n\t/**\n\t * The body of the response.\n\t */\n\tbody: {\n\t\t/**\n\t\t * The URL to open for the user when the updated mailbox must complete an external\n\t\t * authentication flow, such as an OAuth consent URL, before it can be polled.\n\t\t */\n\t\tauthUrl?: string;\n\t};\n}\n"]}

package/dist/es/models/mailboxMetricIds.js

@@ -0,0 +1,13 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Metric IDs for the mailbox service.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const MailboxMetricIds = {
+    /**
+     * Number of emails received across all mailboxes.
+     */
+    EmailsReceived: "mailbox_emails_received"
+};
+//# sourceMappingURL=mailboxMetricIds.js.map

package/dist/es/models/mailboxMetricIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailboxMetricIds.js","sourceRoot":"","sources":["../../../src/models/mailboxMetricIds.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC/B;;OAEG;IACH,cAAc,EAAE,yBAAyB;CAChC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Metric IDs for the mailbox service.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const MailboxMetricIds = {\n\t/**\n\t * Number of emails received across all mailboxes.\n\t */\n\tEmailsReceived: \"mailbox_emails_received\"\n} as const;\n\n/**\n * Union type of all mailbox service metric ID string values.\n */\nexport type MailboxMetricIds = (typeof MailboxMetricIds)[keyof typeof MailboxMetricIds];\n"]}

package/dist/es/models/mailboxMetrics.js

@@ -0,0 +1,16 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { MetricType } from "@3sixty/telemetry-models";
+import { MailboxMetricIds } from "./mailboxMetricIds.js";
+/**
+ * Metrics registered by the mailbox service.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const MailboxMetrics = [
+    {
+        id: MailboxMetricIds.EmailsReceived,
+        label: "Emails received",
+        type: MetricType.Counter
+    }
+];
+//# sourceMappingURL=mailboxMetrics.js.map

package/dist/es/models/mailboxMetrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailboxMetrics.js","sourceRoot":"","sources":["../../../src/models/mailboxMetrics.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAyB,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,cAAc,GAAuB;IACjD;QACC,EAAE,EAAE,gBAAgB,CAAC,cAAc;QACnC,KAAK,EAAE,iBAAiB;QACxB,IAAI,EAAE,UAAU,CAAC,OAAO;KACxB;CACD,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { type ITelemetryMetric, MetricType } from \"@3sixty/telemetry-models\";\nimport { MailboxMetricIds } from \"./mailboxMetricIds.js\";\n\n/**\n * Metrics registered by the mailbox service.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const MailboxMetrics: ITelemetryMetric[] = [\n\t{\n\t\tid: MailboxMetricIds.EmailsReceived,\n\t\tlabel: \"Emails received\",\n\t\ttype: MetricType.Counter\n\t}\n];\n"]}

package/dist/es/utils/mailHelper.js

@@ -0,0 +1,92 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Converter, Is } from "@3sixty/core";
+import PostalMime from "postal-mime";
+/**
+ * Shared utilities for parsing raw RFC822 email messages and mapping postal-mime address objects.
+ */
+export class MailHelper {
+    /**
+     * Map a postal-mime address object to an IEmailAddress, or return undefined when no address is present.
+     * @param address The postal-mime address to map.
+     * @param address.name The display name of the email address.
+     * @param address.address The email address string.
+     * @returns The mapped address, or undefined.
+     */
+    static mapAddress(address) {
+        if (Is.stringValue(address?.address)) {
+            return { name: address?.name, address: address?.address };
+        }
+        return undefined;
+    }
+    /**
+     * Map an array of postal-mime address objects to IEmailAddress[], or return undefined when the input is empty.
+     * @param addresses The postal-mime addresses to map.
+     * @returns The mapped addresses, or undefined.
+     */
+    static mapAddresses(addresses) {
+        const mapped = (addresses ?? [])
+            .filter(addr => Is.stringValue(addr.address))
+            .map(addr => ({ name: addr.name, address: addr.address }));
+        return mapped.length > 0 ? mapped : undefined;
+    }
+    /**
+     * Parse a raw RFC822 email string into an IEmail object using postal-mime.
+     * @param raw The raw email string.
+     * @param flags Optional IMAP flags associated with the message.
+     * @returns The parsed email, or undefined if the input is empty.
+     */
+    static async parseEmail(raw, flags) {
+        if (!Is.stringValue(raw)) {
+            return undefined;
+        }
+        const parsed = await PostalMime.parse(raw);
+        const attachments = parsed.attachments.length > 0
+            ? parsed.attachments.map(a => ({
+                filename: a.filename ?? undefined,
+                contentType: a.mimeType,
+                data: MailHelper.attachmentToBase64(a.content)
+            }))
+            : undefined;
+        return {
+            headers: parsed.headers.map(h => ({
+                key: h.key,
+                originalKey: h.originalKey,
+                value: h.value
+            })),
+            messageId: parsed.messageId,
+            from: MailHelper.mapAddress(parsed.from),
+            sender: MailHelper.mapAddress(parsed.sender),
+            to: MailHelper.mapAddresses(parsed.to),
+            cc: MailHelper.mapAddresses(parsed.cc),
+            bcc: MailHelper.mapAddresses(parsed.bcc),
+            replyTo: MailHelper.mapAddresses(parsed.replyTo),
+            deliveredTo: parsed.deliveredTo,
+            returnPath: parsed.returnPath,
+            inReplyTo: parsed.inReplyTo,
+            references: parsed.references,
+            subject: parsed.subject,
+            date: parsed.date,
+            textContent: parsed.text,
+            htmlContent: parsed.html,
+            attachments,
+            flags
+        };
+    }
+    /**
+     * Convert postal-mime attachment content to a base64 string.
+     * Handles string (text), Uint8Array, and ArrayBuffer inputs.
+     * @param content The attachment content.
+     * @returns The base64-encoded content.
+     */
+    static attachmentToBase64(content) {
+        if (Is.stringValue(content)) {
+            return Converter.bytesToBase64(Converter.utf8ToBytes(content));
+        }
+        if (Is.uint8Array(content)) {
+            return Converter.bytesToBase64(content);
+        }
+        return Converter.bytesToBase64(new Uint8Array(content));
+    }
+}
+//# sourceMappingURL=mailHelper.js.map

package/dist/es/utils/mailHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailHelper.js","sourceRoot":"","sources":["../../../src/utils/mailHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Converter, Is } from \"@3sixty/core\";\nimport PostalMime from \"postal-mime\";\nimport type { IEmail } from \"../models/IEmail.js\";\nimport type { IEmailAddress } from \"../models/IEmailAddress.js\";\n\n/**\n * Shared utilities for parsing raw RFC822 email messages and mapping postal-mime address objects.\n */\nexport class MailHelper {\n\t/**\n\t * Map a postal-mime address object to an IEmailAddress, or return undefined when no address is present.\n\t * @param address The postal-mime address to map.\n\t * @param address.name The display name of the email address.\n\t * @param address.address The email address string.\n\t * @returns The mapped address, or undefined.\n\t */\n\tpublic static mapAddress(\n\t\taddress?: { name: string; address?: string } | undefined\n\t): IEmailAddress | undefined {\n\t\tif (Is.stringValue(address?.address)) {\n\t\t\treturn { name: address?.name, address: address?.address };\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Map an array of postal-mime address objects to IEmailAddress[], or return undefined when the input is empty.\n\t * @param addresses The postal-mime addresses to map.\n\t * @returns The mapped addresses, or undefined.\n\t */\n\tpublic static mapAddresses(\n\t\taddresses: { name: string; address?: string }[] | undefined\n\t): IEmailAddress[] | undefined {\n\t\tconst mapped = (addresses ?? [])\n\t\t\t.filter(addr => Is.stringValue(addr.address))\n\t\t\t.map(addr => ({ name: addr.name, address: addr.address as string }));\n\t\treturn mapped.length > 0 ? mapped : undefined;\n\t}\n\n\t/**\n\t * Parse a raw RFC822 email string into an IEmail object using postal-mime.\n\t * @param raw The raw email string.\n\t * @param flags Optional IMAP flags associated with the message.\n\t * @returns The parsed email, or undefined if the input is empty.\n\t */\n\tpublic static async parseEmail(raw: string, flags?: string[]): Promise<IEmail | undefined> {\n\t\tif (!Is.stringValue(raw)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst parsed = await PostalMime.parse(raw);\n\n\t\tconst attachments =\n\t\t\tparsed.attachments.length > 0\n\t\t\t\t? parsed.attachments.map(a => ({\n\t\t\t\t\t\tfilename: a.filename ?? undefined,\n\t\t\t\t\t\tcontentType: a.mimeType,\n\t\t\t\t\t\tdata: MailHelper.attachmentToBase64(a.content)\n\t\t\t\t\t}))\n\t\t\t\t: undefined;\n\n\t\treturn {\n\t\t\theaders: parsed.headers.map(h => ({\n\t\t\t\tkey: h.key,\n\t\t\t\toriginalKey: h.originalKey,\n\t\t\t\tvalue: h.value\n\t\t\t})),\n\t\t\tmessageId: parsed.messageId,\n\t\t\tfrom: MailHelper.mapAddress(parsed.from),\n\t\t\tsender: MailHelper.mapAddress(parsed.sender),\n\t\t\tto: MailHelper.mapAddresses(parsed.to),\n\t\t\tcc: MailHelper.mapAddresses(parsed.cc),\n\t\t\tbcc: MailHelper.mapAddresses(parsed.bcc),\n\t\t\treplyTo: MailHelper.mapAddresses(parsed.replyTo),\n\t\t\tdeliveredTo: parsed.deliveredTo,\n\t\t\treturnPath: parsed.returnPath,\n\t\t\tinReplyTo: parsed.inReplyTo,\n\t\t\treferences: parsed.references,\n\t\t\tsubject: parsed.subject,\n\t\t\tdate: parsed.date,\n\t\t\ttextContent: parsed.text,\n\t\t\thtmlContent: parsed.html,\n\t\t\tattachments,\n\t\t\tflags\n\t\t};\n\t}\n\n\t/**\n\t * Convert postal-mime attachment content to a base64 string.\n\t * Handles string (text), Uint8Array, and ArrayBuffer inputs.\n\t * @param content The attachment content.\n\t * @returns The base64-encoded content.\n\t */\n\tpublic static attachmentToBase64(content: string | ArrayBuffer | Uint8Array): string {\n\t\tif (Is.stringValue(content)) {\n\t\t\treturn Converter.bytesToBase64(Converter.utf8ToBytes(content));\n\t\t}\n\t\tif (Is.uint8Array(content)) {\n\t\t\treturn Converter.bytesToBase64(content);\n\t\t}\n\t\treturn Converter.bytesToBase64(new Uint8Array(content));\n\t}\n}\n"]}

package/dist/types/factories/emailConsumerFactory.d.ts

@@ -0,0 +1,6 @@
+import { Factory } from "@3sixty/core";
+import type { IEmailConsumer } from "../models/IEmailConsumer.js";
+/**
+ * Factory for creating email consumer instances.
+ */
+export declare const EmailConsumerFactory: Factory<IEmailConsumer>;

package/dist/types/factories/emailProtocolConnectorConfigSchemaFactory.d.ts

@@ -0,0 +1,6 @@
+import { Factory } from "@3sixty/core";
+import type { IMailboxConfigField } from "../models/IMailboxConfigField.js";
+/**
+ * Factory for retrieving email protocol connector configuration field definitions.
+ */
+export declare const EmailProtocolConnectorConfigSchemaFactory: Factory<IMailboxConfigField[]>;

package/dist/types/factories/emailProtocolConnectorFactory.d.ts

@@ -0,0 +1,6 @@
+import { Factory } from "@3sixty/core";
+import type { IEmailProtocolConnector } from "../models/IEmailProtocolConnector.js";
+/**
+ * Factory for creating email protocol connectors.
+ */
+export declare const EmailProtocolConnectorFactory: Factory<IEmailProtocolConnector<unknown, import("../index.js").IEmailProtocolConnectorAuthState>>;

package/dist/types/factories/emailProtocolConnectorStateSchemaFactory.d.ts

@@ -0,0 +1,8 @@
+import { Factory } from "@3sixty/core";
+import type { IMailboxConfigField } from "../models/IMailboxConfigField.js";
+/**
+ * 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.
+ */
+export declare const EmailProtocolConnectorStateSchemaFactory: Factory<IMailboxConfigField[]>;

package/dist/types/index.d.ts

@@ -0,0 +1,41 @@
+export * from "./factories/emailConsumerFactory.js";
+export * from "./factories/emailProtocolConnectorFactory.js";
+export * from "./factories/emailProtocolConnectorConfigSchemaFactory.js";
+export * from "./factories/emailProtocolConnectorStateSchemaFactory.js";
+export * from "./models/api/IMailboxCompleteAuthRequest.js";
+export * from "./models/api/IMailboxConnectorSchemaRequest.js";
+export * from "./models/api/IMailboxConnectorSchemaResponse.js";
+export * from "./models/api/IMailboxCreateRequest.js";
+export * from "./models/api/IMailboxCreateResponse.js";
+export * from "./models/api/IMailboxGetRequest.js";
+export * from "./models/api/IMailboxGetResponse.js";
+export * from "./models/api/IMailboxListRequest.js";
+export * from "./models/api/IMailboxListResponse.js";
+export * from "./models/api/IMailboxRemoveRequest.js";
+export * from "./models/api/IMailboxUpdateRequest.js";
+export * from "./models/api/IMailboxUpdateResponse.js";
+export * from "./models/api/IMailStorageGetRequest.js";
+export * from "./models/api/IMailStorageGetResponse.js";
+export * from "./models/api/IMailStorageListRequest.js";
+export * from "./models/api/IMailStorageListResponse.js";
+export * from "./models/api/IMailStorageRemoveRequest.js";
+export * from "./models/IEmail.js";
+export * from "./models/IEmailAddress.js";
+export * from "./models/IEmailAttachment.js";
+export * from "./models/IEmailHeader.js";
+export * from "./models/IEmailConsumer.js";
+export * from "./models/IEmailProtocolConnector.js";
+export * from "./models/IEmailProtocolConnectorAuthCallback.js";
+export * from "./models/IEmailProtocolConnectorAuthState.js";
+export * from "./models/IEmailProtocolConnectorOptions.js";
+export * from "./models/IEmailProtocolConnectorRetrievalCallback.js";
+export * from "./models/IMailbox.js";
+export * from "./models/IMailboxCreateResult.js";
+export * from "./models/IMailboxUpdateResult.js";
+export * from "./models/IMailboxComponent.js";
+export * from "./models/IMailboxConfigField.js";
+export * from "./models/IMailStorageComponent.js";
+export * from "./models/IStoredEmail.js";
+export * from "./models/mailboxMetricIds.js";
+export * from "./models/mailboxMetrics.js";
+export * from "./utils/mailHelper.js";

package/dist/types/models/IEmail.d.ts

@@ -0,0 +1,80 @@
+import type { IEmailAddress } from "./IEmailAddress.js";
+import type { IEmailAttachment } from "./IEmailAttachment.js";
+import type { IEmailHeader } from "./IEmailHeader.js";
+/**
+ * Interface describing a normalised email message at the connector boundary.
+ */
+export interface IEmail {
+    /**
+     * The parsed message headers.
+     */
+    headers?: IEmailHeader[];
+    /**
+     * The unique message identifier.
+     */
+    messageId?: string;
+    /**
+     * The sender address (From header).
+     */
+    from?: IEmailAddress;
+    /**
+     * The Sender header address, when different from From.
+     */
+    sender?: IEmailAddress;
+    /**
+     * The primary recipient addresses.
+     */
+    to?: IEmailAddress[];
+    /**
+     * The carbon-copy recipient addresses.
+     */
+    cc?: IEmailAddress[];
+    /**
+     * The blind carbon-copy recipient addresses.
+     */
+    bcc?: IEmailAddress[];
+    /**
+     * The reply-to addresses.
+     */
+    replyTo?: IEmailAddress[];
+    /**
+     * The final delivery address from the Delivered-To header.
+     */
+    deliveredTo?: string;
+    /**
+     * The Return-Path address.
+     */
+    returnPath?: string;
+    /**
+     * The Message-ID this message is a reply to.
+     */
+    inReplyTo?: string;
+    /**
+     * The space-separated list of related message identifiers.
+     */
+    references?: string;
+    /**
+     * The message subject.
+     */
+    subject?: string;
+    /**
+     * The message date as an ISO 8601 string.
+     */
+    date?: string;
+    /**
+     * The plain-text body of the message.
+     */
+    textContent?: string;
+    /**
+     * The HTML body of the message.
+     */
+    htmlContent?: string;
+    /**
+     * The attachments included with the message.
+     */
+    attachments?: IEmailAttachment[];
+    /**
+     * Protocol-level flags on the message, for example \\Seen.
+     */
+    flags?: string[];
+}

package/dist/types/models/IEmailAddress.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Interface describing an email address with an optional display name.
+ */
+export interface IEmailAddress {
+    /**
+     * The display name for the address.
+     */
+    name?: string;
+    /**
+     * The email address.
+     */
+    address: string;
+}

package/dist/types/models/IEmailAttachment.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface describing an email attachment.
+ */
+export interface IEmailAttachment {
+    /**
+     * The filename of the attachment.
+     */
+    filename?: string;
+    /**
+     * The MIME content type of the attachment.
+     */
+    contentType: string;
+    /**
+     * The attachment data encoded as a base64 string.
+     */
+    data: string;
+}

package/dist/types/models/IEmailConsumer.d.ts

@@ -0,0 +1,11 @@
+import type { IComponent } from "@3sixty/core";
+/**
+ * Interface describing a consumer that is notified when new emails are available.
+ */
+export interface IEmailConsumer extends IComponent {
+    /**
+     * Called when new emails have been stored, prompting the consumer to query for them.
+     * @returns A promise that resolves when the consumer has processed the notification.
+     */
+    onNewMessages(): Promise<void>;
+}

package/dist/types/models/IEmailHeader.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface describing a single parsed email header.
+ */
+export interface IEmailHeader {
+    /**
+     * The lowercase header name.
+     */
+    key: string;
+    /**
+     * The original header name preserving case.
+     */
+    originalKey: string;
+    /**
+     * The header value.
+     */
+    value: string;
+}

package/dist/types/models/IEmailProtocolConnector.d.ts

@@ -0,0 +1,50 @@
+import type { IComponent } from "@3sixty/core";
+import type { IEmailProtocolConnectorAuthCallback } from "./IEmailProtocolConnectorAuthCallback.js";
+import type { IEmailProtocolConnectorAuthState } from "./IEmailProtocolConnectorAuthState.js";
+import type { IEmailProtocolConnectorOptions } from "./IEmailProtocolConnectorOptions.js";
+import type { IEmailProtocolConnectorRetrievalCallback } from "./IEmailProtocolConnectorRetrievalCallback.js";
+/**
+ * Interface describing an email protocol connector that handles message retrieval.
+ */
+export interface IEmailProtocolConnector<TState = unknown, TAuthState extends IEmailProtocolConnectorAuthState = IEmailProtocolConnectorAuthState> extends IComponent {
+    /**
+     * Start the internal polling loop for the given instance.
+     * @param instanceId The identifier of the mailbox instance being polled.
+     * @param state The current connector state for the instance.
+     * @param authCallback Callback invoked when authentication fails during a poll cycle.
+     * @param retrievalCallback Callback invoked with retrieved messages after each poll cycle.
+     * @param options Options supplied by the owning component.
+     * @returns A promise that resolves when the polling loop has been started.
+     */
+    retrieve(instanceId: string, state: TState, authCallback: IEmailProtocolConnectorAuthCallback<TAuthState>, retrievalCallback: IEmailProtocolConnectorRetrievalCallback, options: IEmailProtocolConnectorOptions): Promise<void>;
+    /**
+     * Stop the internal polling loop.
+     * @returns A promise that resolves when the polling loop has been stopped.
+     */
+    retrieveStop(): Promise<void>;
+    /**
+     * 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.
+     * @param instanceId The identifier of the mailbox instance being authenticated.
+     * @param state The current connector state for the instance, which may already hold credentials.
+     * @param options 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 The auth state carrying the URL to open for the user, or undefined when the
+     * mailbox is already able to authenticate itself.
+     */
+    initiateAuth?(instanceId: string, state: TState, options: IEmailProtocolConnectorOptions): Promise<TAuthState | undefined>;
+    /**
+     * 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.
+     * @param instanceId The identifier of the mailbox instance being authenticated.
+     * @param authPayload The protocol-specific data handed to the redirect, such as an OAuth code.
+     * @param options Options supplied by the owning component, carrying the same callback URI the
+     * flow was started with.
+     * @returns A promise that resolves when the flow has been completed.
+     */
+    completeAuth?(instanceId: string, authPayload: unknown, options: IEmailProtocolConnectorOptions): Promise<void>;
+}

package/dist/types/models/IEmailProtocolConnectorAuthCallback.d.ts

@@ -0,0 +1,12 @@
+import type { IError } from "@3sixty/core";
+import type { IEmailProtocolConnectorAuthState } from "./IEmailProtocolConnectorAuthState.js";
+/**
+ * Callback invoked by a protocol connector to report the outcome of an authentication attempt.
+ * @param mailboxId The identifier of the mailbox this authentication attempt belongs to.
+ * @param updatedState 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.
+ * @param requiresAuth True if authentication failed due to invalid or expired credentials.
+ * @param authState Optional state produced during the auth flow, carrying the URL to open.
+ * @param authError Optional structured error covering all failure types (auth, connection, timeout, etc.).
+ */
+export type IEmailProtocolConnectorAuthCallback<TAuthState extends IEmailProtocolConnectorAuthState = IEmailProtocolConnectorAuthState> = (mailboxId: string, updatedState: unknown | undefined, requiresAuth: boolean, authState?: TAuthState, authError?: IError) => Promise<void>;

package/dist/types/models/IEmailProtocolConnectorAuthState.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export interface IEmailProtocolConnectorAuthState {
+    /**
+     * 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.
+     */
+    authUrl?: string;
+}

package/dist/types/models/IEmailProtocolConnectorOptions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Options supplied to a protocol connector by the component which owns it.
+ */
+export interface IEmailProtocolConnectorOptions {
+    /**
+     * 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.
+     */
+    callbackUri?: 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.
+     */
+    correlationState: string;
+}

package/dist/types/models/IEmailProtocolConnectorRetrievalCallback.d.ts

@@ -0,0 +1,10 @@
+import type { IError } from "@3sixty/core";
+import type { IEmail } from "./IEmail.js";
+/**
+ * Callback invoked by a protocol connector to persist a single retrieved message.
+ * @param mailboxId The identifier of the mailbox this retrieval belongs to.
+ * @param message The message to persist.
+ * @param updatedState The connector state to persist on the mailbox entity after this message.
+ * @returns True if the message was persisted successfully; false causes the connector to exit the polling loop.
+ */
+export type IEmailProtocolConnectorRetrievalCallback = (mailboxId: string, message: IEmail | undefined, updatedState: unknown, retrievalError?: IError) => Promise<boolean>;

package/dist/types/models/IMailStorageComponent.d.ts

@@ -0,0 +1,39 @@
+import type { IComponent } from "@3sixty/core";
+import type { IEmail } from "./IEmail.js";
+import type { IStoredEmail } from "./IStoredEmail.js";
+/**
+ * Interface describing the mail storage component for persisting and querying received emails.
+ */
+export interface IMailStorageComponent extends IComponent {
+    /**
+     * Store an email received from a mailbox.
+     * @param mailboxId The identifier of the mailbox that received the email.
+     * @param email The email to store.
+     * @returns The identifier assigned to the stored email.
+     */
+    store(mailboxId: string, email: IEmail): Promise<string>;
+    /**
+     * Retrieve a stored email by its identifier.
+     * @param id The identifier of the stored email.
+     * @returns The stored email.
+     */
+    get(id: string): Promise<IStoredEmail>;
+    /**
+     * Remove a stored email by its identifier.
+     * @param id The identifier of the stored email to remove.
+     * @returns A promise that resolves when the email has been removed.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Query stored emails received at or after a given epoch.
+     * @param sinceEpoch The ISO 8601 timestamp to filter emails received at or after.
+     * @param mailboxId An optional mailbox identifier to restrict results to.
+     * @param cursor An optional cursor for paginated results.
+     * @param limit An optional maximum number of results to return.
+     * @returns A page of stored emails and an optional cursor for the next page.
+     */
+    query(sinceEpoch: string, mailboxId?: string, cursor?: string, limit?: number): Promise<{
+        emails: IStoredEmail[];
+        cursor?: string;
+    }>;
+}