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

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

@@ -0,0 +1,46 @@
+import type { IError } from "@3sixty/core";
+/**
+ * Interface describing a mailbox configuration.
+ */
+export interface IMailbox<TConfig = unknown, TState = unknown, TAuthState = unknown> {
+    /**
+     * The unique identifier for the mailbox.
+     */
+    id: string;
+    /**
+     * The display name for the mailbox.
+     */
+    name: string;
+    /**
+     * The connector type identifying which connector handles this mailbox.
+     */
+    connectorType: string;
+    /**
+     * The connector-owned configuration for this mailbox.
+     */
+    config?: TConfig;
+    /**
+     * The connector-owned runtime state for this mailbox.
+     */
+    state?: TState;
+    /**
+     * Whether this mailbox is active and should be polled.
+     */
+    enabled: boolean;
+    /**
+     * Whether this mailbox is awaiting re-authentication.
+     */
+    requiresAuth?: boolean;
+    /**
+     * Optional protocol-specific state produced during the auth flow, such as an OAuth URL or code.
+     */
+    authState?: TAuthState;
+    /**
+     * The last error returned by the authentication callback; cleared on successful authentication.
+     */
+    authError?: IError;
+    /**
+     * The last error returned by the retrieval callback; cleared on successful retrieval.
+     */
+    retrievalError?: IError;
+}

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

@@ -0,0 +1,71 @@
+import type { IComponent } from "@3sixty/core";
+import type { IMailbox } from "./IMailbox.js";
+import type { IMailboxConfigField } from "./IMailboxConfigField.js";
+import type { IMailboxCreateResult } from "./IMailboxCreateResult.js";
+import type { IMailboxUpdateResult } from "./IMailboxUpdateResult.js";
+/**
+ * Interface describing the mailbox management component.
+ */
+export interface IMailboxComponent extends IComponent {
+    /**
+     * 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.
+     * @param mailbox The mailbox configuration to create.
+     * @returns The identifier assigned to the new mailbox, with the URL to open when the mailbox
+     * must be authenticated before it can be polled.
+     */
+    createMailbox(mailbox: Pick<IMailbox, "name" | "connectorType" | "config" | "enabled">): Promise<IMailboxCreateResult>;
+    /**
+     * 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.
+     * @param mailbox The updated mailbox configuration.
+     * @returns The URL to open when the mailbox must be authenticated before it can be polled.
+     */
+    updateMailbox(mailbox: IMailbox): Promise<IMailboxUpdateResult>;
+    /**
+     * Remove a mailbox and stop polling for it.
+     * @param id The identifier of the mailbox to remove.
+     * @returns A promise that resolves when the mailbox has been removed.
+     */
+    removeMailbox(id: string): Promise<void>;
+    /**
+     * Retrieve a mailbox by its identifier.
+     * @param id The identifier of the mailbox to retrieve.
+     * @returns The mailbox.
+     */
+    getMailbox(id: string): Promise<IMailbox>;
+    /**
+     * List all mailboxes with optional cursor-based pagination.
+     * @param cursor An optional cursor for paginated results.
+     * @param limit An optional maximum number of results to return.
+     * @returns A page of mailboxes and an optional cursor for the next page.
+     */
+    listMailboxes(cursor?: string, limit?: number): Promise<{
+        mailboxes: IMailbox[];
+        cursor?: string;
+    }>;
+    /**
+     * 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.
+     * @param authPayload The data handed to the callback URI, carrying the correlating state.
+     * @returns 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.
+     */
+    completeAuth(authPayload: unknown): Promise<void>;
+    /**
+     * Get the configuration schema for a connector type.
+     * @param connectorType The connector type to get the schema for.
+     * @returns The configuration field definitions for the connector.
+     * @throws NotFoundError if no schema is registered for the connector type.
+     */
+    getSchema(connectorType: string): Promise<IMailboxConfigField[]>;
+}

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

@@ -0,0 +1,30 @@
+import type { EntitySchemaPropertyType } from "@3sixty/entity";
+/**
+ * Interface describing a single configuration field for a protocol connector.
+ */
+export interface IMailboxConfigField {
+    /**
+     * The i18n key for the field label shown in the UI.
+     */
+    labelKey: string;
+    /**
+     * The key of the property within the connector config object.
+     */
+    propertyKey: string;
+    /**
+     * The entity schema property type for this field.
+     */
+    type: EntitySchemaPropertyType;
+    /**
+     * Whether this field holds a sensitive value that should be stored in the vault.
+     */
+    isSecure?: boolean;
+    /**
+     * The element type when `type` is `Array`.
+     */
+    itemType?: EntitySchemaPropertyType;
+    /**
+     * An optional default value for the field.
+     */
+    defaultValue?: unknown;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * The outcome of creating a mailbox.
+ */
+export interface IMailboxCreateResult {
+    /**
+     * The identifier assigned to the new mailbox.
+     */
+    id: 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.
+     */
+    authUrl?: string;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * The outcome of updating a mailbox.
+ */
+export interface IMailboxUpdateResult {
+    /**
+     * 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.
+     */
+    authUrl?: string;
+}

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

@@ -0,0 +1,18 @@
+import type { IEmail } from "./IEmail.js";
+/**
+ * Interface describing an email message persisted by the mail storage component.
+ */
+export interface IStoredEmail extends IEmail {
+    /**
+     * The storage entity identifier.
+     */
+    id: string;
+    /**
+     * The identifier of the mailbox that received the message.
+     */
+    mailboxId: string;
+    /**
+     * The ISO 8601 timestamp when the message was stored.
+     */
+    receivedAt: string;
+}

package/dist/types/models/api/IMailStorageGetRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Request to retrieve a stored email by ID.
+ */
+export interface IMailStorageGetRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The identifier of the stored email to retrieve.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/IMailStorageGetResponse.d.ts

@@ -0,0 +1,10 @@
+import type { IStoredEmail } from "../IStoredEmail.js";
+/**
+ * Response from retrieving a stored email.
+ */
+export interface IMailStorageGetResponse {
+    /**
+     * The retrieved stored email.
+     */
+    body: IStoredEmail;
+}

package/dist/types/models/api/IMailStorageListRequest.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Request to query stored emails.
+ */
+export interface IMailStorageListRequest {
+    /**
+     * The query parameters.
+     */
+    query: {
+        /**
+         * Return only emails received at or after this ISO 8601 timestamp.
+         */
+        since: string;
+        /**
+         * Filter emails by mailbox identifier.
+         */
+        mailboxId?: string;
+        /**
+         * The cursor for paginated results.
+         */
+        cursor?: string;
+        /**
+         * The maximum number of results to return.
+         */
+        limit?: string;
+    };
+}

package/dist/types/models/api/IMailStorageListResponse.d.ts

@@ -0,0 +1,19 @@
+import type { IStoredEmail } from "../IStoredEmail.js";
+/**
+ * Response from querying stored emails.
+ */
+export interface IMailStorageListResponse {
+    /**
+     * The result body.
+     */
+    body: {
+        /**
+         * The list of stored emails.
+         */
+        emails: IStoredEmail[];
+        /**
+         * The cursor for the next page of results.
+         */
+        cursor?: string;
+    };
+}

package/dist/types/models/api/IMailStorageRemoveRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Request to remove a stored email.
+ */
+export interface IMailStorageRemoveRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The identifier of the stored email to remove.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/IMailboxCompleteAuthRequest.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Request to complete an authentication flow, sent by the external provider redirecting the
+ * browser to the fixed callback route.
+ */
+export interface IMailboxCompleteAuthRequest {
+    /**
+     * The query parameters the provider appends to the callback URI.
+     */
+    query: {
+        [propertyKey: string]: string;
+        /**
+         * The correlating state the connector placed in the external flow.
+         */
+        state: string;
+    };
+}

package/dist/types/models/api/IMailboxConnectorSchemaRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Request to retrieve the configuration schema for a connector.
+ */
+export interface IMailboxConnectorSchemaRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The connector type identifier.
+         */
+        connectorType: string;
+    };
+}

package/dist/types/models/api/IMailboxConnectorSchemaResponse.d.ts

@@ -0,0 +1,10 @@
+import type { IMailboxConfigField } from "../IMailboxConfigField.js";
+/**
+ * Response from retrieving a connector configuration schema.
+ */
+export interface IMailboxConnectorSchemaResponse {
+    /**
+     * The schema fields for the connector.
+     */
+    body: IMailboxConfigField[];
+}

package/dist/types/models/api/IMailboxCreateRequest.d.ts

@@ -0,0 +1,10 @@
+import type { IMailbox } from "../IMailbox.js";
+/**
+ * Request to create a new mailbox.
+ */
+export interface IMailboxCreateRequest {
+    /**
+     * The mailbox to create.
+     */
+    body: Pick<IMailbox, "name" | "connectorType" | "config" | "enabled">;
+}

package/dist/types/models/api/IMailboxCreateResponse.d.ts

@@ -0,0 +1,29 @@
+import type { HeaderTypes, HttpStatusCode } from "@3sixty/web";
+/**
+ * Response to creating a new mailbox.
+ */
+export interface IMailboxCreateResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.created;
+    /**
+     * Additional response headers.
+     */
+    headers: {
+        /**
+         * The location where the mailbox was created.
+         */
+        [HeaderTypes.Location]: string;
+    };
+    /**
+     * The body of the response.
+     */
+    body: {
+        /**
+         * 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.
+         */
+        authUrl?: string;
+    };
+}

package/dist/types/models/api/IMailboxGetRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Request to retrieve a mailbox by ID.
+ */
+export interface IMailboxGetRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The identifier of the mailbox to retrieve.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/IMailboxGetResponse.d.ts

@@ -0,0 +1,10 @@
+import type { IMailbox } from "../IMailbox.js";
+/**
+ * Response from retrieving a mailbox.
+ */
+export interface IMailboxGetResponse {
+    /**
+     * The retrieved mailbox.
+     */
+    body: IMailbox;
+}

package/dist/types/models/api/IMailboxListRequest.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Request to list mailboxes with optional pagination.
+ */
+export interface IMailboxListRequest {
+    /**
+     * The query parameters.
+     */
+    query?: {
+        /**
+         * The cursor for paginated results.
+         */
+        cursor?: string;
+        /**
+         * The maximum number of results to return.
+         */
+        limit?: string;
+    };
+}

package/dist/types/models/api/IMailboxListResponse.d.ts

@@ -0,0 +1,19 @@
+import type { IMailbox } from "../IMailbox.js";
+/**
+ * Response from listing mailboxes.
+ */
+export interface IMailboxListResponse {
+    /**
+     * The result body.
+     */
+    body: {
+        /**
+         * The list of mailboxes.
+         */
+        mailboxes: IMailbox[];
+        /**
+         * The cursor for the next page of results.
+         */
+        cursor?: string;
+    };
+}

package/dist/types/models/api/IMailboxRemoveRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Request to remove a mailbox.
+ */
+export interface IMailboxRemoveRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The identifier of the mailbox to remove.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/IMailboxUpdateRequest.d.ts

@@ -0,0 +1,19 @@
+import type { IMailbox } from "../IMailbox.js";
+/**
+ * Request to update an existing mailbox.
+ */
+export interface IMailboxUpdateRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The identifier of the mailbox to update.
+         */
+        id: string;
+    };
+    /**
+     * The updated mailbox configuration.
+     */
+    body: IMailbox;
+}

package/dist/types/models/api/IMailboxUpdateResponse.d.ts

@@ -0,0 +1,20 @@
+import type { HttpStatusCode } from "@3sixty/web";
+/**
+ * Response to updating a mailbox.
+ */
+export interface IMailboxUpdateResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.ok;
+    /**
+     * The body of the response.
+     */
+    body: {
+        /**
+         * 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.
+         */
+        authUrl?: string;
+    };
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Metric IDs for the mailbox service.
+ */
+export declare const MailboxMetricIds: {
+    /**
+     * Number of emails received across all mailboxes.
+     */
+    readonly EmailsReceived: "mailbox_emails_received";
+};
+/**
+ * Union type of all mailbox service metric ID string values.
+ */
+export type MailboxMetricIds = (typeof MailboxMetricIds)[keyof typeof MailboxMetricIds];

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

@@ -0,0 +1,5 @@
+import { type ITelemetryMetric } from "@3sixty/telemetry-models";
+/**
+ * Metrics registered by the mailbox service.
+ */
+export declare const MailboxMetrics: ITelemetryMetric[];

package/dist/types/utils/mailHelper.d.ts

@@ -0,0 +1,41 @@
+import type { IEmail } from "../models/IEmail.js";
+import type { IEmailAddress } from "../models/IEmailAddress.js";
+/**
+ * Shared utilities for parsing raw RFC822 email messages and mapping postal-mime address objects.
+ */
+export declare 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?: {
+        name: string;
+        address?: string;
+    } | undefined): IEmailAddress | 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: {
+        name: string;
+        address?: string;
+    }[] | undefined): IEmailAddress[] | 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 parseEmail(raw: string, flags?: string[]): Promise<IEmail | undefined>;
+    /**
+     * 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: string | ArrayBuffer | Uint8Array): string;
+}