@decaf-ts/integrations 0.11.0 → 0.12.0

package/lib/types/blob/s3/S3CompatibleBlobStoreService.d.cts

@@ -3,10 +3,9 @@
  * @summary S3-compatible blob store base implementation.
  * @description Shared CRUD implementation backed by the AWS SDK v3 S3Client, used by
  * the S3, MinIO, and Cloudflare R2 provider services. Deliberately left undecorated:
- * `@service(...)` on a class whose parent is itself `@service(...)`-decorated breaks
- * that subclass's inherited field initializers (e.g. `Context` ends up `undefined`).
- * Each concrete provider below extends this class directly and carries its own
- * `@service("blob-<provider>")` decorator instead of stacking on top of one another.
+ * concrete providers are plain classes that consumers construct and boot
+ * explicitly (no injectable registration, no `Service.boot` auto-boot), and
+ * each extends this base directly instead of stacking on top of one another.
  */
 import { S3Client } from "@aws-sdk/client-s3";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
@@ -16,12 +15,9 @@ import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListR
  * @description Base implementation for S3-compatible blob stores
  * @summary Implements the full blob CRUD API on top of the AWS SDK v3
  * `S3Client` and is shared by the S3, MinIO, and Cloudflare R2 provider
- * services. Deliberately left undecorated: `@service(...)` on a class whose
- * parent is itself `@service(...)`-decorated breaks that subclass's inherited
- * field initializers (e.g. `Context` ends up `undefined`). Each concrete
- * provider extends this class directly and carries its own
- * `@service("blob-<provider>")` decorator instead of stacking on top of one
- * another.
+ * services. Deliberately left undecorated: concrete providers are plain
+ * classes that consumers construct and boot explicitly, so no injectable
+ * registration or `Service.boot` auto-boot applies here.
  * @class S3CompatibleBlobStoreService
  * @memberOf module:integrations/blob/s3/base-service
  */
@@ -29,11 +25,11 @@ export declare abstract class S3CompatibleBlobStoreService extends BlobStoreServ
     /**
      * @description Initializes the S3 client from config or environment
      * @summary Resolves the config via `getConfigFromArgs` (explicit config,
-     * then the provider's environment slice). When no config resolves during a
-     * context-bearing auto-boot of an unconfigured provider (e.g. an optional
-     * `blob-minio`/`blob-r2` registered alongside `blob-s3`), returns
-     * `skipInitialization()` so `Service.boot` does not throw; an explicit
-     * `initialize()` with no resolvable config still throws a
+     * then the provider's environment slice). When no config resolves and the
+     * arguments carry a decaf `Context` (e.g. an unconfigured optional
+     * `blob-minio`/`blob-r2` provider next to `blob-s3`), returns
+     * `skipInitialization()` so the context-bearing boot does not throw; an
+     * explicit `initialize()` with no resolvable config still throws a
      * `ValidationError`. Requires a `bucket`, builds the `S3Client` (with
      * optional static credentials), stores config and client, and optionally
      * creates the bucket when `autoCreateBucket` is set.

package/lib/types/blob/s3/S3CompatibleBlobStoreService.d.mts

@@ -3,10 +3,9 @@
  * @summary S3-compatible blob store base implementation.
  * @description Shared CRUD implementation backed by the AWS SDK v3 S3Client, used by
  * the S3, MinIO, and Cloudflare R2 provider services. Deliberately left undecorated:
- * `@service(...)` on a class whose parent is itself `@service(...)`-decorated breaks
- * that subclass's inherited field initializers (e.g. `Context` ends up `undefined`).
- * Each concrete provider below extends this class directly and carries its own
- * `@service("blob-<provider>")` decorator instead of stacking on top of one another.
+ * concrete providers are plain classes that consumers construct and boot
+ * explicitly (no injectable registration, no `Service.boot` auto-boot), and
+ * each extends this base directly instead of stacking on top of one another.
  */
 import { S3Client } from "@aws-sdk/client-s3";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
@@ -16,12 +15,9 @@ import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListR
  * @description Base implementation for S3-compatible blob stores
  * @summary Implements the full blob CRUD API on top of the AWS SDK v3
  * `S3Client` and is shared by the S3, MinIO, and Cloudflare R2 provider
- * services. Deliberately left undecorated: `@service(...)` on a class whose
- * parent is itself `@service(...)`-decorated breaks that subclass's inherited
- * field initializers (e.g. `Context` ends up `undefined`). Each concrete
- * provider extends this class directly and carries its own
- * `@service("blob-<provider>")` decorator instead of stacking on top of one
- * another.
+ * services. Deliberately left undecorated: concrete providers are plain
+ * classes that consumers construct and boot explicitly, so no injectable
+ * registration or `Service.boot` auto-boot applies here.
  * @class S3CompatibleBlobStoreService
  * @memberOf module:integrations/blob/s3/base-service
  */
@@ -29,11 +25,11 @@ export declare abstract class S3CompatibleBlobStoreService extends BlobStoreServ
     /**
      * @description Initializes the S3 client from config or environment
      * @summary Resolves the config via `getConfigFromArgs` (explicit config,
-     * then the provider's environment slice). When no config resolves during a
-     * context-bearing auto-boot of an unconfigured provider (e.g. an optional
-     * `blob-minio`/`blob-r2` registered alongside `blob-s3`), returns
-     * `skipInitialization()` so `Service.boot` does not throw; an explicit
-     * `initialize()` with no resolvable config still throws a
+     * then the provider's environment slice). When no config resolves and the
+     * arguments carry a decaf `Context` (e.g. an unconfigured optional
+     * `blob-minio`/`blob-r2` provider next to `blob-s3`), returns
+     * `skipInitialization()` so the context-bearing boot does not throw; an
+     * explicit `initialize()` with no resolvable config still throws a
      * `ValidationError`. Requires a `bucket`, builds the `S3Client` (with
      * optional static credentials), stores config and client, and optionally
      * creates the bucket when `autoCreateBucket` is set.

package/lib/types/comms/email/EmailService.d.cts

@@ -0,0 +1,184 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+import { type EmailMessageInput } from "./mime.d.cts";
+/**
+ * @description Delivery provider selected for a send
+ * @summary `smtp` delivers through the built-in raw-MIME client; `graph`
+ * posts to the Microsoft Graph `sendMail` endpoint.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export type EmailProvider = "smtp" | "graph";
+/**
+ * @description Configuration for the Email service
+ * @summary Extends {@link HttpApiServiceConfig} with the SMTP connection
+ * settings and the Microsoft Graph token/base URL. Every field falls back to
+ * the `comms.email` environment slice when omitted. A `host` selects the SMTP
+ * provider; a `token` (without `host`) selects Graph.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailServiceConfig extends HttpApiServiceConfig {
+    provider?: EmailProvider;
+    host?: string;
+    port?: number;
+    secure?: boolean;
+    username?: string;
+    password?: string;
+    /**
+     * Explicitly allow SMTP `AUTH LOGIN` over a plaintext session. Defaults to
+     * `false`: credentials are only sent after implicit TLS or a STARTTLS upgrade.
+     */
+    allowPlaintextAuth?: boolean;
+    from?: string;
+    graphBaseUrl?: string;
+    token?: string;
+}
+/**
+ * @description Result of a successful email send
+ * @summary Carries the generated RFC 5322 `Message-ID`, the resolved sender,
+ * the flattened recipient list, and the provider that delivered it.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailSendResult {
+    /** @description Generated `Message-ID` (also present in the raw MIME headers) */
+    messageId: string;
+    /** @description Sender address used for delivery */
+    from: string;
+    /** @description All To/Cc/Bcc recipients, in that order */
+    recipients: string[];
+    /** @description Provider that performed the delivery */
+    provider: EmailProvider;
+}
+/**
+ * @description Filter for inbox reads
+ * @summary Applies to both {@link EmailService.listInbox} (Graph) and
+ * {@link EmailService.listImapMessages} (IMAP): mailbox path, page size, a
+ * lower received-date bound, and a subject filter.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailInboxQuery {
+    /** @description Mailbox path to read (default `me` on Graph, `INBOX` on IMAP) */
+    mailbox?: string;
+    /** @description Maximum messages returned (default 25) */
+    limit?: number;
+    /** @description Only messages received after this date (Graph `$filter`); must be an ISO 8601 date or timestamp */
+    since?: string;
+    /** @description Subject `contains` filter (Graph only) */
+    subject?: string;
+}
+/**
+ * @description Multi-provider email send/inbox service
+ * @summary Resolves the delivery provider from config (`provider`, or inferred
+ * from the presence of `host` vs `token`), builds RFC 5322 MIME with
+ * UTF-8-encoded headers via {@link buildEmail}, then delivers through SMTP or
+ * posts to Graph. Inbox reads go through Graph `messages` (with `$top`,
+ * `$filter`, `$orderby`) or the optional `imapflow` package.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export declare class EmailService extends HttpApiService<EmailServiceConfig> {
+    protected readonly serviceName = "Email";
+    /**
+     * @description Default Microsoft Graph base URL used when no override is configured
+     * @returns The Graph v1.0 endpoint URL
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Authorization headers for Graph requests
+     * @param config - Resolved service config
+     * @returns A bearer-token `Authorization` header map, empty when no `token` is configured
+     */
+    protected authHeaders(config: EmailServiceConfig): Record<string, string>;
+    /**
+     * @description Pins the SMTP plaintext-AUTH default on top of the base initialization
+     * @summary Runs the {@link HttpApiService} initialization (explicit config
+     * merged over the `comms.email` environment slice) and then defaults an
+     * unresolved `allowPlaintextAuth` to `false`, so credentials are only sent
+     * over a TLS-protected session unless the config explicitly opts in. This
+     * closes the F1 residual where an environment-only `allowPlaintextAuth`
+     * opt-in would otherwise reach a boot whose explicit config omits the key
+     * (defense in depth on top of {@link bootWithoutEnvironment}, which disables
+     * the environment slice entirely on the node path).
+     * @param {...any[]} args - An optional `Partial<EmailServiceConfig>`, optionally followed by a decaf `Context`.
+     * @returns {Promise<{config: EmailServiceConfig, client: AxiosInstance}>} The merged configuration, with `allowPlaintextAuth` defaulted to `false` when unset, and the configured Axios instance.
+     */
+    initialize(...args: any[]): Promise<{
+        config: EmailServiceConfig;
+        client: import("axios").AxiosInstance;
+    }>;
+    /**
+     * @description Builds service config from the `comms.email` environment slice
+     * @returns A partial config when either an SMTP `host` or a Graph `token` is present, otherwise `undefined`
+     */
+    protected configFromEnvironment(): Partial<EmailServiceConfig> | undefined;
+    /**
+     * @description Selects the delivery provider
+     * @summary Prefers an explicit `provider`, then infers `smtp` from a
+     * configured `host` and `graph` from a configured `token`.
+     * @param config - Resolved service config
+     * @returns The resolved provider
+     * @throws {InternalError} when neither an SMTP host nor a Graph token is configured
+     */
+    protected resolveProvider(config: EmailServiceConfig): EmailProvider;
+    /**
+     * @description Resolves the fallback sender address
+     * @summary Uses `from`, then `username`, then the `From` header override.
+     * @param config - Resolved service config
+     * @returns The resolved sender address
+     * @throws {InternalError} when no sender address can be resolved
+     */
+    protected resolveFrom(config: EmailServiceConfig): string;
+    /**
+     * @description Sends an email through the resolved provider
+     * @summary Builds the raw MIME message (honouring `input.from`, else the
+     * resolved config sender), then delivers via SMTP or Graph. SMTP config
+     * passes `allowPlaintextAuth` through unchanged, so the plaintext-AUTH
+     * opt-out is inherited from the service config.
+     * @param input - Message input (recipients, subject, text/html body, attachments)
+     * @returns The send result with the generated `Message-ID` and provider
+     * @throws {BadRequestError} when an address, attachment filename, or content type fails validation (via {@link buildEmail})
+     * @throws {InternalError} when the provider cannot be resolved, the SMTP host is missing, plaintext AUTH is refused, or SMTP delivery fails
+     */
+    send(input: EmailMessageInput): Promise<EmailSendResult>;
+    /**
+     * @description Posts a raw MIME message to the Microsoft Graph `sendMail` endpoint
+     * @summary Sends the base64-encoded raw message to
+     * `/users/<from>/sendMail` (or `/me/sendMail` when no sender is resolved)
+     * with the configured `graphBaseUrl`/`baseUrl`.
+     * @param raw - Raw RFC 5322 message text
+     * @param from - Sender mailbox (UPN) for the Graph path
+     * @throws {Error} Graph error mapped through {@link httpError}
+     */
+    protected sendViaGraph(raw: string, from: string): Promise<void>;
+    /**
+     * @description Lists messages from a Graph mailbox
+     * @summary Queries `<mailbox>/messages` with `$top`, an optional
+     * subject/since `$filter`, and `receivedDateTime desc` ordering. The mailbox
+     * is URL-encoded as a single path segment, quotes in the subject are escaped
+     * for the OData string literal, and `since` must be an ISO 8601 date.
+     * @param query - Inbox filter (mailbox, limit, since, subject)
+     * @returns The raw Graph message records
+     * @throws {BadRequestError} when `since` is not an ISO 8601 date
+     * @throws {InternalError} when no `token` is configured; Graph errors mapped through {@link httpError}
+     */
+    listInbox(query?: EmailInboxQuery): Promise<Array<Record<string, unknown>>>;
+    /**
+     * @description Lists messages directly over IMAP
+     * @summary Dynamically imports the optional `imapflow` package, connects to
+     * `host` (default port 993, implicit TLS), and fetches the newest messages
+     * from `INBOX`.
+     *
+     * R2 direct-library-wrap justification: IMAP is a stateful protocol
+     * (mailbox locks, sequence/UID state, IDLE) whose correct implementation is
+     * large and security-sensitive. `imapflow` is the maintained n8n-vetted
+     * client for exactly this surface, so wrapping it is deliberate; a local
+     * reimplementation would add risk without changing the node contract. The
+     * package stays optional so SMTP/Graph-only consumers do not install it.
+     * @param query - Inbox filter (limit only is honoured by IMAP)
+     * @returns The fetched IMAP message records
+     * @throws {InternalError} when `imapflow` is not installed, no `host` is configured, or the IMAP session fails
+     */
+    listImapMessages(query?: EmailInboxQuery): Promise<Array<Record<string, unknown>>>;
+}

package/lib/types/comms/email/EmailService.d.mts

@@ -0,0 +1,184 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+import { type EmailMessageInput } from "./mime.d.mts";
+/**
+ * @description Delivery provider selected for a send
+ * @summary `smtp` delivers through the built-in raw-MIME client; `graph`
+ * posts to the Microsoft Graph `sendMail` endpoint.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export type EmailProvider = "smtp" | "graph";
+/**
+ * @description Configuration for the Email service
+ * @summary Extends {@link HttpApiServiceConfig} with the SMTP connection
+ * settings and the Microsoft Graph token/base URL. Every field falls back to
+ * the `comms.email` environment slice when omitted. A `host` selects the SMTP
+ * provider; a `token` (without `host`) selects Graph.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailServiceConfig extends HttpApiServiceConfig {
+    provider?: EmailProvider;
+    host?: string;
+    port?: number;
+    secure?: boolean;
+    username?: string;
+    password?: string;
+    /**
+     * Explicitly allow SMTP `AUTH LOGIN` over a plaintext session. Defaults to
+     * `false`: credentials are only sent after implicit TLS or a STARTTLS upgrade.
+     */
+    allowPlaintextAuth?: boolean;
+    from?: string;
+    graphBaseUrl?: string;
+    token?: string;
+}
+/**
+ * @description Result of a successful email send
+ * @summary Carries the generated RFC 5322 `Message-ID`, the resolved sender,
+ * the flattened recipient list, and the provider that delivered it.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailSendResult {
+    /** @description Generated `Message-ID` (also present in the raw MIME headers) */
+    messageId: string;
+    /** @description Sender address used for delivery */
+    from: string;
+    /** @description All To/Cc/Bcc recipients, in that order */
+    recipients: string[];
+    /** @description Provider that performed the delivery */
+    provider: EmailProvider;
+}
+/**
+ * @description Filter for inbox reads
+ * @summary Applies to both {@link EmailService.listInbox} (Graph) and
+ * {@link EmailService.listImapMessages} (IMAP): mailbox path, page size, a
+ * lower received-date bound, and a subject filter.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailInboxQuery {
+    /** @description Mailbox path to read (default `me` on Graph, `INBOX` on IMAP) */
+    mailbox?: string;
+    /** @description Maximum messages returned (default 25) */
+    limit?: number;
+    /** @description Only messages received after this date (Graph `$filter`); must be an ISO 8601 date or timestamp */
+    since?: string;
+    /** @description Subject `contains` filter (Graph only) */
+    subject?: string;
+}
+/**
+ * @description Multi-provider email send/inbox service
+ * @summary Resolves the delivery provider from config (`provider`, or inferred
+ * from the presence of `host` vs `token`), builds RFC 5322 MIME with
+ * UTF-8-encoded headers via {@link buildEmail}, then delivers through SMTP or
+ * posts to Graph. Inbox reads go through Graph `messages` (with `$top`,
+ * `$filter`, `$orderby`) or the optional `imapflow` package.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export declare class EmailService extends HttpApiService<EmailServiceConfig> {
+    protected readonly serviceName = "Email";
+    /**
+     * @description Default Microsoft Graph base URL used when no override is configured
+     * @returns The Graph v1.0 endpoint URL
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Authorization headers for Graph requests
+     * @param config - Resolved service config
+     * @returns A bearer-token `Authorization` header map, empty when no `token` is configured
+     */
+    protected authHeaders(config: EmailServiceConfig): Record<string, string>;
+    /**
+     * @description Pins the SMTP plaintext-AUTH default on top of the base initialization
+     * @summary Runs the {@link HttpApiService} initialization (explicit config
+     * merged over the `comms.email` environment slice) and then defaults an
+     * unresolved `allowPlaintextAuth` to `false`, so credentials are only sent
+     * over a TLS-protected session unless the config explicitly opts in. This
+     * closes the F1 residual where an environment-only `allowPlaintextAuth`
+     * opt-in would otherwise reach a boot whose explicit config omits the key
+     * (defense in depth on top of {@link bootWithoutEnvironment}, which disables
+     * the environment slice entirely on the node path).
+     * @param {...any[]} args - An optional `Partial<EmailServiceConfig>`, optionally followed by a decaf `Context`.
+     * @returns {Promise<{config: EmailServiceConfig, client: AxiosInstance}>} The merged configuration, with `allowPlaintextAuth` defaulted to `false` when unset, and the configured Axios instance.
+     */
+    initialize(...args: any[]): Promise<{
+        config: EmailServiceConfig;
+        client: import("axios").AxiosInstance;
+    }>;
+    /**
+     * @description Builds service config from the `comms.email` environment slice
+     * @returns A partial config when either an SMTP `host` or a Graph `token` is present, otherwise `undefined`
+     */
+    protected configFromEnvironment(): Partial<EmailServiceConfig> | undefined;
+    /**
+     * @description Selects the delivery provider
+     * @summary Prefers an explicit `provider`, then infers `smtp` from a
+     * configured `host` and `graph` from a configured `token`.
+     * @param config - Resolved service config
+     * @returns The resolved provider
+     * @throws {InternalError} when neither an SMTP host nor a Graph token is configured
+     */
+    protected resolveProvider(config: EmailServiceConfig): EmailProvider;
+    /**
+     * @description Resolves the fallback sender address
+     * @summary Uses `from`, then `username`, then the `From` header override.
+     * @param config - Resolved service config
+     * @returns The resolved sender address
+     * @throws {InternalError} when no sender address can be resolved
+     */
+    protected resolveFrom(config: EmailServiceConfig): string;
+    /**
+     * @description Sends an email through the resolved provider
+     * @summary Builds the raw MIME message (honouring `input.from`, else the
+     * resolved config sender), then delivers via SMTP or Graph. SMTP config
+     * passes `allowPlaintextAuth` through unchanged, so the plaintext-AUTH
+     * opt-out is inherited from the service config.
+     * @param input - Message input (recipients, subject, text/html body, attachments)
+     * @returns The send result with the generated `Message-ID` and provider
+     * @throws {BadRequestError} when an address, attachment filename, or content type fails validation (via {@link buildEmail})
+     * @throws {InternalError} when the provider cannot be resolved, the SMTP host is missing, plaintext AUTH is refused, or SMTP delivery fails
+     */
+    send(input: EmailMessageInput): Promise<EmailSendResult>;
+    /**
+     * @description Posts a raw MIME message to the Microsoft Graph `sendMail` endpoint
+     * @summary Sends the base64-encoded raw message to
+     * `/users/<from>/sendMail` (or `/me/sendMail` when no sender is resolved)
+     * with the configured `graphBaseUrl`/`baseUrl`.
+     * @param raw - Raw RFC 5322 message text
+     * @param from - Sender mailbox (UPN) for the Graph path
+     * @throws {Error} Graph error mapped through {@link httpError}
+     */
+    protected sendViaGraph(raw: string, from: string): Promise<void>;
+    /**
+     * @description Lists messages from a Graph mailbox
+     * @summary Queries `<mailbox>/messages` with `$top`, an optional
+     * subject/since `$filter`, and `receivedDateTime desc` ordering. The mailbox
+     * is URL-encoded as a single path segment, quotes in the subject are escaped
+     * for the OData string literal, and `since` must be an ISO 8601 date.
+     * @param query - Inbox filter (mailbox, limit, since, subject)
+     * @returns The raw Graph message records
+     * @throws {BadRequestError} when `since` is not an ISO 8601 date
+     * @throws {InternalError} when no `token` is configured; Graph errors mapped through {@link httpError}
+     */
+    listInbox(query?: EmailInboxQuery): Promise<Array<Record<string, unknown>>>;
+    /**
+     * @description Lists messages directly over IMAP
+     * @summary Dynamically imports the optional `imapflow` package, connects to
+     * `host` (default port 993, implicit TLS), and fetches the newest messages
+     * from `INBOX`.
+     *
+     * R2 direct-library-wrap justification: IMAP is a stateful protocol
+     * (mailbox locks, sequence/UID state, IDLE) whose correct implementation is
+     * large and security-sensitive. `imapflow` is the maintained n8n-vetted
+     * client for exactly this surface, so wrapping it is deliberate; a local
+     * reimplementation would add risk without changing the node contract. The
+     * package stays optional so SMTP/Graph-only consumers do not install it.
+     * @param query - Inbox filter (limit only is honoured by IMAP)
+     * @returns The fetched IMAP message records
+     * @throws {InternalError} when `imapflow` is not installed, no `host` is configured, or the IMAP session fails
+     */
+    listImapMessages(query?: EmailInboxQuery): Promise<Array<Record<string, unknown>>>;
+}

package/lib/types/comms/email/index.d.cts

@@ -0,0 +1,11 @@
+/**
+ * @module integrations/comms/email
+ * @summary Email service (SMTP + Microsoft Graph send, Graph/IMAP inbox reads).
+ * @description Re-exports the {@link EmailService} and its config/result
+ * types, the raw MIME builder, and the nodemailer-backed {@link SmtpClient}
+ * with its {@link SmtpConfig}
+ * (also available directly from the `./smtp` subpath).
+ */
+export * from "./EmailService.d.cts";
+export * from "./mime.d.cts";
+export * from "./smtp.d.cts";

package/lib/types/comms/email/index.d.mts

@@ -0,0 +1,11 @@
+/**
+ * @module integrations/comms/email
+ * @summary Email service (SMTP + Microsoft Graph send, Graph/IMAP inbox reads).
+ * @description Re-exports the {@link EmailService} and its config/result
+ * types, the raw MIME builder, and the nodemailer-backed {@link SmtpClient}
+ * with its {@link SmtpConfig}
+ * (also available directly from the `./smtp` subpath).
+ */
+export * from "./EmailService.d.mts";
+export * from "./mime.d.mts";
+export * from "./smtp.d.mts";

package/lib/types/comms/email/mime.d.cts

@@ -0,0 +1,84 @@
+/**
+ * @description A message attachment
+ * @summary Content is base64 text by default; with `encoding: "utf8"` the
+ * builder base64-encodes the UTF-8 content itself.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/mime
+ */
+export interface EmailAttachment {
+    filename: string;
+    content: string;
+    encoding?: "base64" | "utf8";
+    contentType?: string;
+}
+/**
+ * @description Input for building a raw MIME message
+ * @summary Carries the sender, recipients (single address, comma-separated
+ * string, or array), subject, optional text and HTML bodies, `Reply-To`, and
+ * attachments.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/mime
+ */
+export interface EmailMessageInput {
+    from: string;
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    replyTo?: string;
+    attachments?: EmailAttachment[];
+}
+/**
+ * @description The built MIME message ready for delivery
+ * @summary Carries the raw RFC 5322 text, the resolved sender, the flattened
+ * recipient list (To/Cc/Bcc), and the generated `Message-ID`.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/mime
+ */
+export interface BuiltEmail {
+    raw: string;
+    from: string;
+    recipients: string[];
+    messageId: string;
+}
+/**
+ * Validates a mailbox address against the allowlist and returns it trimmed.
+ *
+ * @param value - Candidate address.
+ * @param field - Human-readable field name used in the error message.
+ * @returns The trimmed, validated mailbox address.
+ * @throws {BadRequestError} when the address contains control characters or is not a bare mailbox.
+ */
+export declare function assertEmailAddress(value: string, field?: string): string;
+/**
+ * @description Encodes a MIME header value safely
+ * @summary Pure-ASCII values pass through; anything else becomes an RFC 2047
+ * `=?UTF-8?B?...?=` encoded word.
+ * @param value - Raw header value
+ * @returns The header value safe for raw message transport
+ */
+export declare function encodeHeader(value: string): string;
+/**
+ * @description Normalizes a recipient input into an allowlisted address list
+ * @summary Splits comma-separated strings, trims entries, drops empties, and
+ * validates every remaining entry as a bare mailbox address. Values carrying
+ * CR/LF, NUL, or other control characters are rejected outright so workflow
+ * input can never inject MIME headers or SMTP envelope commands.
+ * @param value - Single address, comma-separated string, array, or `undefined`
+ * @returns The trimmed, validated list of addresses
+ * @throws {BadRequestError} when an entry is not a valid mailbox address
+ */
+export declare function parseAddressList(value: string | string[] | undefined): string[];
+/**
+ * @description Builds the complete raw MIME message
+ * @summary Generates the `Message-ID`, resolves recipients (throwing when
+ * none remain), emits the standard headers, and assembles the body entity
+ * (alternative text/HTML parts, plus attachments when present).
+ * @param input - Message input
+ * @returns The built message with raw text, sender, recipients, and `Message-ID`
+ * @throws {BadRequestError} when the message has no recipient or any address,
+ *   attachment filename, or content type fails validation
+ */
+export declare function buildEmail(input: EmailMessageInput): BuiltEmail;

package/lib/types/comms/email/mime.d.mts

@@ -0,0 +1,84 @@
+/**
+ * @description A message attachment
+ * @summary Content is base64 text by default; with `encoding: "utf8"` the
+ * builder base64-encodes the UTF-8 content itself.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/mime
+ */
+export interface EmailAttachment {
+    filename: string;
+    content: string;
+    encoding?: "base64" | "utf8";
+    contentType?: string;
+}
+/**
+ * @description Input for building a raw MIME message
+ * @summary Carries the sender, recipients (single address, comma-separated
+ * string, or array), subject, optional text and HTML bodies, `Reply-To`, and
+ * attachments.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/mime
+ */
+export interface EmailMessageInput {
+    from: string;
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    replyTo?: string;
+    attachments?: EmailAttachment[];
+}
+/**
+ * @description The built MIME message ready for delivery
+ * @summary Carries the raw RFC 5322 text, the resolved sender, the flattened
+ * recipient list (To/Cc/Bcc), and the generated `Message-ID`.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/mime
+ */
+export interface BuiltEmail {
+    raw: string;
+    from: string;
+    recipients: string[];
+    messageId: string;
+}
+/**
+ * Validates a mailbox address against the allowlist and returns it trimmed.
+ *
+ * @param value - Candidate address.
+ * @param field - Human-readable field name used in the error message.
+ * @returns The trimmed, validated mailbox address.
+ * @throws {BadRequestError} when the address contains control characters or is not a bare mailbox.
+ */
+export declare function assertEmailAddress(value: string, field?: string): string;
+/**
+ * @description Encodes a MIME header value safely
+ * @summary Pure-ASCII values pass through; anything else becomes an RFC 2047
+ * `=?UTF-8?B?...?=` encoded word.
+ * @param value - Raw header value
+ * @returns The header value safe for raw message transport
+ */
+export declare function encodeHeader(value: string): string;
+/**
+ * @description Normalizes a recipient input into an allowlisted address list
+ * @summary Splits comma-separated strings, trims entries, drops empties, and
+ * validates every remaining entry as a bare mailbox address. Values carrying
+ * CR/LF, NUL, or other control characters are rejected outright so workflow
+ * input can never inject MIME headers or SMTP envelope commands.
+ * @param value - Single address, comma-separated string, array, or `undefined`
+ * @returns The trimmed, validated list of addresses
+ * @throws {BadRequestError} when an entry is not a valid mailbox address
+ */
+export declare function parseAddressList(value: string | string[] | undefined): string[];
+/**
+ * @description Builds the complete raw MIME message
+ * @summary Generates the `Message-ID`, resolves recipients (throwing when
+ * none remain), emits the standard headers, and assembles the body entity
+ * (alternative text/HTML parts, plus attachments when present).
+ * @param input - Message input
+ * @returns The built message with raw text, sender, recipients, and `Message-ID`
+ * @throws {BadRequestError} when the message has no recipient or any address,
+ *   attachment filename, or content type fails validation
+ */
+export declare function buildEmail(input: EmailMessageInput): BuiltEmail;