@rapidmx/restapi 0.1.0

package/dist/types/scan/AvScanProvider.d.ts

@@ -0,0 +1,22 @@
+import { AvVerdict } from "../models/types.js";
+/** The outcome of an `AvScanProvider.scanBuffer()` call. */
+export interface AvScanResult {
+    verdict: AvVerdict;
+    /** The name of the malware signature matched, if `verdict` is `INFECTED`. */
+    signatureName?: string;
+}
+/**
+ * Scans a buffer of content (a full raw MIME message, a decoded attachment, or an HTML body) for malicious
+ * content by delegating to an existing anti-virus engine (ClamAV) rather than implementing detection in this
+ * library. See `ClamAvScanProvider` for the default adapter. Selected via the `scan:av:provider` config key.
+ *
+ * Called on more than just file attachments — the full raw message and HTML bodies are scanned too, which is
+ * what covers embedded/malicious HTML (e.g. an exploit payload in an inline `<script>`), not just attachments.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface AvScanProvider {
+    /** A short, unique name for this provider implementation (e.g. `"clamav"`). */
+    readonly name: string;
+    scanBuffer(content: Buffer, filename?: string): Promise<AvScanResult>;
+}

package/dist/types/scan/ClamAvScanProvider.d.ts

@@ -0,0 +1,17 @@
+import { AvScanProvider, AvScanResult } from "./AvScanProvider.js";
+/**
+ * `AvScanProvider` adapter for ClamAV, talking to `clamd` via the INSTREAM protocol (a length-prefixed chunk
+ * stream over a TCP or Unix socket) — chosen over shelling out to the `clamscan` CLI so scanning doesn't incur
+ * a process-spawn per call and works transparently against a remote `clamd` instance.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class ClamAvScanProvider implements AvScanProvider {
+    readonly name: string;
+    private host;
+    private port;
+    private timeoutMs;
+    private logger;
+    scanBuffer(content: Buffer, filename?: string): Promise<AvScanResult>;
+    private instream;
+}

package/dist/types/scan/RspamdSpamScanProvider.d.ts

@@ -0,0 +1,16 @@
+import { ScanEnvelope, SpamScanProvider, SpamScanResult } from "./SpamScanProvider.js";
+/**
+ * `SpamScanProvider` adapter for rspamd, talking to its HTTP controller `checkv2` endpoint. Chosen over
+ * SpamAssassin's `spamc`/`spamd` line protocol for HTTP-native integration matching this library's HTTP-first
+ * design — a `SpamAssassinScanProvider` implementing the same interface via `spamc` is a straightforward
+ * drop-in alternative for a deployment that already runs SpamAssassin instead.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class RspamdSpamScanProvider implements SpamScanProvider {
+    readonly name: string;
+    private url;
+    private timeoutMs;
+    private logger;
+    scoreMessage(raw: Buffer, envelope: ScanEnvelope): Promise<SpamScanResult>;
+}

package/dist/types/scan/ScanPipeline.d.ts

@@ -0,0 +1,53 @@
+import { AvScanResult } from "./AvScanProvider.js";
+import { ScanEnvelope, SpamScanResult } from "./SpamScanProvider.js";
+/** The per-attachment AV outcome, keyed by the attachment's position in the parsed message. */
+export interface ScanPipelineAttachmentResult {
+    filename?: string;
+    contentType: string;
+    content: Buffer;
+    contentId?: string;
+    isInline: boolean;
+    av: AvScanResult;
+}
+/** The combined outcome of running the full SPAM/AV pipeline against one raw message. */
+export interface ScanPipelineResult {
+    spam: SpamScanResult;
+    /** The overall AV verdict for the message: the worst of the raw-message-level and every attachment's scan. */
+    av: AvScanResult;
+    attachments: ScanPipelineAttachmentResult[];
+    /** The message's HTML body with `<script>`/active content stripped, if it had one. */
+    sanitizedHtml?: string;
+}
+/**
+ * Orchestrates SPAM scoring, AV scanning, and HTML sanitization for a single raw RFC 5322 message — the
+ * ingestion-time gate that every inbound message (via `MailIngestRoute`) and outbound send (via the webmail/
+ * EAS/MAPI "send" routes) passes through before delivery/relay. AV scanning covers the full raw message buffer
+ * *and* each decoded attachment (not just attachments), which is what catches embedded/malicious HTML.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class ScanPipeline {
+    private spamScanProvider?;
+    private avScanProvider?;
+    private allowedTags?;
+    private logger;
+    run(raw: Buffer, envelope: ScanEnvelope): Promise<ScanPipelineResult>;
+    private scanAttachments;
+    /**
+     * Strips `<script>` tags and other active/executable content from an HTML body. Defense in depth alongside
+     * clamd's own HTML/JS signature detection (run against the raw message above) and whatever sandboxing the
+     * eventual client renderer applies.
+     */
+    private sanitize;
+}
+/**
+ * Combines a spam verdict and an AV verdict into where the message should be routed on ingestion.
+ *
+ * `AvVerdict.ERROR` and `SpamVerdict.SUSPECT` are the providers' own documented fail-closed outcomes for a
+ * scan-engine outage (see `ClamAvScanProvider.scanBuffer()`/`RspamdSpamScanProvider.scoreMessage()`) - treating
+ * them as equivalent to a clean/normal verdict here would silently deliver every message straight to the
+ * inbox, completely unscanned, for the entire duration of an AV/spam engine outage. `ERROR` quarantines
+ * (matching AV's own "treat like infected" intent); `SUSPECT` routes to Junk for human review rather than
+ * blind inbox delivery.
+ */
+export declare function resolveDeliveryVerdict(result: ScanPipelineResult): "deliver" | "junk" | "quarantine";

package/dist/types/scan/SpamScanProvider.d.ts

@@ -0,0 +1,29 @@
+import { SpamVerdict } from "../models/types.js";
+/** The envelope information a `SpamScanProvider` needs alongside the raw message content. */
+export interface ScanEnvelope {
+    from: string;
+    to: string[];
+    /** The originating IP address of the SMTP client that submitted the message, if known. */
+    remoteIp?: string;
+    /** The HELO/EHLO hostname presented by the originating SMTP client, if known. */
+    helo?: string;
+}
+/** The outcome of a `SpamScanProvider.scoreMessage()` call. */
+export interface SpamScanResult {
+    score: number;
+    verdict: SpamVerdict;
+    /** The symbolic names (e.g. rspamd symbols, SpamAssassin rule names) that contributed to the score. */
+    symbols: string[];
+}
+/**
+ * Scores a raw RFC 5322 message for spam likelihood by delegating to an existing, battle-tested spam-filtering
+ * engine (rspamd, SpamAssassin) rather than implementing detection heuristics in this library. See
+ * `RspamdSpamScanProvider` for the default adapter. Selected via the `scan:spam:provider` config key.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface SpamScanProvider {
+    /** A short, unique name for this provider implementation (e.g. `"rspamd"`, `"spamassassin"`). */
+    readonly name: string;
+    scoreMessage(raw: Buffer, envelope: ScanEnvelope): Promise<SpamScanResult>;
+}

package/dist/types/scan/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./SpamScanProvider.js";
+export * from "./AvScanProvider.js";
+export * from "./RspamdSpamScanProvider.js";
+export * from "./ClamAvScanProvider.js";
+export * from "./ScanPipeline.js";

package/dist/types/search/MongoTextSearchProvider.d.ts

@@ -0,0 +1,22 @@
+import { SearchDocument, SearchEntityType, SearchProvider, SearchQuery, SearchResultPage } from "./SearchProvider.js";
+/**
+ * `SearchProvider` backed by MongoDB's native `$text` index — the embedded default for a Mongo-backed
+ * deployment that hasn't opted into a dedicated search engine. Documents are stored in a collection separate
+ * from the entities they're derived from (`mail_search_index`), keyed by `<entityType>:<entityUid>`.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class MongoTextSearchProvider implements SearchProvider {
+    readonly name: string;
+    private connectionManager?;
+    private datasourceName;
+    private logger;
+    private collection?;
+    private init;
+    private docId;
+    private toStoredDoc;
+    index(doc: SearchDocument): Promise<void>;
+    bulkIndex(docs: SearchDocument[]): Promise<void>;
+    remove(entityType: SearchEntityType, entityUid: string): Promise<void>;
+    search(query: SearchQuery): Promise<SearchResultPage>;
+}

package/dist/types/search/OpenSearchProvider.d.ts

@@ -0,0 +1,24 @@
+import { SearchDocument, SearchEntityType, SearchProvider, SearchQuery, SearchResultPage } from "./SearchProvider.js";
+/**
+ * `SearchProvider` adapter for a dedicated OpenSearch cluster, via the optional peer dependency
+ * `@opensearch-project/opensearch` — the recommended provider for larger deployments where the embedded
+ * Mongo/Postgres default's relevance ranking and indexing throughput become a bottleneck. Selected via the
+ * `search:provider: "opensearch"` config key.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class OpenSearchProvider implements SearchProvider {
+    readonly name: string;
+    private url;
+    private index_;
+    private username?;
+    private password?;
+    private logger;
+    private client?;
+    private init;
+    private docId;
+    index(doc: SearchDocument): Promise<void>;
+    bulkIndex(docs: SearchDocument[]): Promise<void>;
+    remove(entityType: SearchEntityType, entityUid: string): Promise<void>;
+    search(query: SearchQuery): Promise<SearchResultPage>;
+}

package/dist/types/search/PostgresFullTextSearchProvider.d.ts

@@ -0,0 +1,21 @@
+import { SearchDocument, SearchEntityType, SearchProvider, SearchQuery, SearchResultPage } from "./SearchProvider.js";
+/**
+ * `SearchProvider` backed by Postgres's native full-text search (`tsvector`/`to_tsquery` with a GIN index) —
+ * the embedded default for a SQL-backed deployment that hasn't opted into a dedicated search engine. Documents
+ * are stored in a dedicated table separate from the entities they're derived from, keyed by
+ * `(entity_type, entity_uid)`.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class PostgresFullTextSearchProvider implements SearchProvider {
+    readonly name: string;
+    private connectionManager?;
+    private datasourceName;
+    private logger;
+    private dataSource?;
+    private init;
+    index(doc: SearchDocument): Promise<void>;
+    bulkIndex(docs: SearchDocument[]): Promise<void>;
+    remove(entityType: SearchEntityType, entityUid: string): Promise<void>;
+    search(query: SearchQuery): Promise<SearchResultPage>;
+}

package/dist/types/search/SearchProvider.d.ts

@@ -0,0 +1,62 @@
+/** The kind of entity a `SearchDocument` represents. */
+export type SearchEntityType = "message" | "contact" | "calendarEvent" | "note" | "task";
+/**
+ * A flattened, provider-agnostic representation of one searchable entity, built from a `Message`/`Contact`/
+ * `CalendarEvent`/`Note`/`Task` record (plus, for a message, its attachments' extracted text) and handed to a
+ * `SearchProvider` for indexing.
+ */
+export interface SearchDocument {
+    entityType: SearchEntityType;
+    entityUid: string;
+    mailboxUid: string;
+    subject?: string;
+    body?: string;
+    attachmentText?: string[];
+    participants?: string[];
+    dateForSort?: Date;
+}
+/** A search query issued against `BaseSearchRoute` / `SearchProvider.search()`. */
+export interface SearchQuery {
+    mailboxUid: string;
+    text: string;
+    entityTypes?: SearchEntityType[];
+    limit?: number;
+    cursor?: string;
+}
+/** A single ranked hit returned by `SearchProvider.search()`. */
+export interface SearchResult {
+    entityType: SearchEntityType;
+    entityUid: string;
+    score: number;
+    /** A short, provider-generated snippet highlighting the matched text, if supported. */
+    snippet?: string;
+}
+/** The page of results returned by `SearchProvider.search()`. */
+export interface SearchResultPage {
+    results: SearchResult[];
+    /** Opaque cursor to pass back as `SearchQuery.cursor` to retrieve the next page, if more results exist. */
+    nextCursor?: string;
+}
+/**
+ * Provides full-text indexing and search over mail/contacts/calendar/notes/tasks content, independent of the
+ * chosen persistence backend (Mongo/SQL have no native cross-entity relevance-ranked search of their own).
+ * Implementations are selected via the `search:provider` config key and are never queried through `RepoUtils`.
+ *
+ * Index updates are eventually consistent with respect to the primary datastore — see `SearchIndexState` and
+ * `SearchIndexJob` — so a just-created entity may briefly be readable via its own CRUD route before it becomes
+ * findable via search.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface SearchProvider {
+    /** A short, unique name for this provider implementation (e.g. `"mongo"`, `"postgres"`, `"opensearch"`). */
+    readonly name: string;
+    /** Indexes (or re-indexes) a single document. */
+    index(doc: SearchDocument): Promise<void>;
+    /** Indexes (or re-indexes) a batch of documents in one call, for efficient backfill/reconciliation. */
+    bulkIndex(docs: SearchDocument[]): Promise<void>;
+    /** Removes a previously indexed document. A no-op if it was never indexed. */
+    remove(entityType: SearchEntityType, entityUid: string): Promise<void>;
+    /** Executes a search query, returning ranked results across the requested entity types. */
+    search(query: SearchQuery): Promise<SearchResultPage>;
+}

package/dist/types/search/extraction/DocxTextExtractor.d.ts

@@ -0,0 +1,14 @@
+import { TextExtractor } from "./TextExtractor.js";
+/**
+ * Extracts text from Word (`.docx`) attachment content via the optional peer dependency `mammoth`.
+ *
+ * Excel/PowerPoint (`.xlsx`/`.pptx`) are deliberately out of scope for the initial pragmatic subset — their
+ * text is largely tabular/slide-fragmented and extracts poorly with a generic converter. Revisit with a
+ * dedicated extractor if search relevance over spreadsheet/slide attachments becomes a real requirement.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class DocxTextExtractor implements TextExtractor {
+    readonly mimeTypes: string[];
+    extract(content: Buffer): Promise<string>;
+}

package/dist/types/search/extraction/ExtractorRegistry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Dispatches attachment content to the `TextExtractor` registered for its MIME type, applying a size cap and
+ * timeout so a single huge or pathological attachment cannot stall `AttachmentExtractionJob` indefinitely.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class ExtractorRegistry {
+    private maxBytes;
+    private timeoutMs;
+    private logger;
+    private extractors;
+    private byMimeType;
+    /**
+     * Extracts text from `content` if a `TextExtractor` is registered for `mimeType` and `content` is within
+     * the configured size cap, otherwise returns `undefined` without error (an unsupported/oversized
+     * attachment simply isn't indexed by content — its filename is still searchable via the entity itself).
+     */
+    extract(mimeType: string, content: Buffer): Promise<string | undefined>;
+}

package/dist/types/search/extraction/HtmlTextExtractor.d.ts

@@ -0,0 +1,11 @@
+import { TextExtractor } from "./TextExtractor.js";
+/**
+ * Strips markup from HTML attachment/body content, keeping only its rendered text — used both for attachment
+ * text extraction and to derive `Message.bodyPreview` from an HTML body.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class HtmlTextExtractor implements TextExtractor {
+    readonly mimeTypes: string[];
+    extract(content: Buffer): Promise<string>;
+}

package/dist/types/search/extraction/PdfTextExtractor.d.ts

@@ -0,0 +1,10 @@
+import { TextExtractor } from "./TextExtractor.js";
+/**
+ * Extracts text from PDF attachment content via the optional peer dependency `pdf-parse`.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class PdfTextExtractor implements TextExtractor {
+    readonly mimeTypes: string[];
+    extract(content: Buffer): Promise<string>;
+}

package/dist/types/search/extraction/PlainTextExtractor.d.ts

@@ -0,0 +1,10 @@
+import { TextExtractor } from "./TextExtractor.js";
+/**
+ * Passes plain-text attachment content through unchanged (decoded as UTF-8).
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class PlainTextExtractor implements TextExtractor {
+    readonly mimeTypes: string[];
+    extract(content: Buffer): Promise<string>;
+}

package/dist/types/search/extraction/TextExtractor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Extracts plain text content from a single attachment's binary content, for full-text search indexing (see
+ * `SearchProvider`). Dispatched by MIME type via `ExtractorRegistry`. Runs as part of `AttachmentExtractionJob`
+ * (a background job), never inline on message ingestion — extraction can be slow and must not block SMTP-ACK
+ * or webmail send/save-draft latency.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface TextExtractor {
+    /** The MIME types this extractor handles, e.g. `["application/pdf"]`. */
+    readonly mimeTypes: string[];
+    /**
+     * Extracts plain text from `content`. Returns an empty string if no extractable text is found. Throws only
+     * for content that cannot be parsed at all (e.g. corrupt file) — an empty result is not an error.
+     */
+    extract(content: Buffer): Promise<string>;
+}

package/dist/types/search/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./SearchProvider.js";
+export * from "./MongoTextSearchProvider.js";
+export * from "./PostgresFullTextSearchProvider.js";
+export * from "./OpenSearchProvider.js";
+export * from "./extraction/TextExtractor.js";
+export * from "./extraction/PlainTextExtractor.js";
+export * from "./extraction/HtmlTextExtractor.js";
+export * from "./extraction/PdfTextExtractor.js";
+export * from "./extraction/DocxTextExtractor.js";
+export * from "./extraction/ExtractorRegistry.js";

package/dist/types/sql.d.ts

@@ -0,0 +1,3 @@
+export * from "./models/sql.js";
+export * from "./routes/sql.js";
+export * from "./jobs/sql.js";

package/dist/types/transport/MTAIngestAdapter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Documents the HTTP contract an MTA (Postfix, Haraka, ...) integrates against to hand accepted internet mail
+ * to this library. This is not a pluggable interface implemented in code — it is the fixed shape that
+ * `BaseMailIngestRoute` (see `routes/mongo/MailIngestRouteMongo.ts` / `routes/sql/MailIngestRouteSQL.ts`)
+ * exposes, documented here as the integration target for whichever MTA a deployment chooses.
+ *
+ * Both endpoints are internal-only: bound to loopback/an internal network in the server's HTTP configuration,
+ * and additionally gated by a shared bearer secret (`mail:transport:ingest:secret`) checked against the
+ * `Authorization` header — never exposed to the public internet.
+ *
+ * ### `GET /internal/mta/resolve?rcpt=<address>`
+ * Called by the MTA's recipient-validation hook (e.g. Postfix `recipient_lookup` via a `tcp_table`/socketmap,
+ * or an LMTP handshake) before accepting a message for `rcpt`, so a message for a nonexistent mailbox is
+ * rejected at the SMTP conversation stage rather than accepted and later bounced (avoiding backscatter).
+ * Responds `200` if a `Mailbox` exists for `rcpt` (as a primary or alias address), `404` otherwise.
+ *
+ * ### `POST /internal/mta/deliver`
+ * Called by the MTA's content-filter/pipe once it has accepted a message. The request body is the raw,
+ * unparsed RFC 5322 message; envelope-from/envelope-to are carried as `X-Envelope-From`/`X-Envelope-To`
+ * headers. The handler does only the minimum synchronous work — persist the raw bytes to the `BlobStore` and
+ * create an `IngestQueueEntry` — then returns `202` immediately, deferring parsing/scanning/delivery to
+ * `ScanQueueJob`. This bounds SMTP-transaction latency and lets the MTA's own queue (not this library's) own
+ * retry/backpressure semantics.
+ */
+export declare const MTA_INGEST_CONTRACT_DOC = "See MTAIngestAdapter.ts for the GET /internal/mta/resolve and POST /internal/mta/deliver contract.";

package/dist/types/transport/MailTransport.d.ts

@@ -0,0 +1,29 @@
+/** A fully composed message ready to be relayed to the internet. */
+export interface OutboundMessage {
+    /** The complete, fully composed RFC 5322 MIME source, including headers. */
+    raw: Buffer;
+    envelopeFrom: string;
+    envelopeTo: string[];
+}
+/** The outcome of a `MailTransport.send()` call. */
+export interface TransportResult {
+    accepted: string[];
+    rejected: string[];
+    /** The `Message-ID` the relaying MTA recorded for this transaction, if reported. */
+    messageId?: string;
+}
+/**
+ * Hands a fully composed outbound message to the local MTA (Postfix) for internet delivery — DKIM signing,
+ * SPF/DMARC alignment, retry/queueing, and everything else needed to speak SMTP to the rest of the internet is
+ * the MTA's responsibility, not this library's. See `PostfixSendmailTransport` for the default adapter.
+ *
+ * This library never opens an outbound SMTP connection itself; every "send" action in the webmail REST API,
+ * EAS, and MAPI layers ultimately calls a `MailTransport` implementation.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface MailTransport {
+    /** A short, unique name for this transport implementation (e.g. `"postfix-sendmail"`). */
+    readonly name: string;
+    send(message: OutboundMessage): Promise<TransportResult>;
+}

package/dist/types/transport/PostfixSendmailTransport.d.ts

@@ -0,0 +1,15 @@
+import { MailTransport, OutboundMessage, TransportResult } from "./MailTransport.js";
+/**
+ * `MailTransport` adapter that hands a fully composed message to the local Postfix (or any other locally
+ * installed MTA) via the `sendmail(1)` command-line interface — the simplest integration that works with
+ * essentially any Unix MTA, and lets Postfix (with an OpenDKIM milter) apply DKIM signing on the way out
+ * exactly as it would for mail submitted by any other local process.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class PostfixSendmailTransport implements MailTransport {
+    readonly name: string;
+    private sendmailPath;
+    private logger;
+    send(message: OutboundMessage): Promise<TransportResult>;
+}

package/dist/types/transport/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./MailTransport.js";
+export * from "./PostfixSendmailTransport.js";
+export * from "./MTAIngestAdapter.js";

package/dist/types/util/FolderUtils.d.ts

@@ -0,0 +1,15 @@
+import type { JWTUser } from "@rapidrest/core";
+import { RepoUtils } from "@rapidrest/service-core";
+import { Folder, FolderType } from "../models/types.js";
+/**
+ * Finds the given mailbox's well-known folder of `type` (e.g. its Inbox, Junk, Sent Items), creating it — with
+ * the platform's conventional display name — if it does not already exist. Every well-known folder is
+ * provisioned lazily this way rather than all at once when a `Mailbox` is created, so a mailbox that never
+ * receives a piece of spam, for example, never has an empty Junk folder to show for it.
+ *
+ * @param folderRepo A `RepoUtils` bound to the caller's concrete `Folder` entity class (Mongo or SQL).
+ * @param folderClass The concrete `Folder` entity class `folderRepo` is bound to, used to construct a new row.
+ * @param mailboxUid The mailbox to find or create the folder within.
+ * @param type The well-known folder type to find or create. Must not be `FolderType.USER`.
+ */
+export declare function findOrCreateWellKnownFolder<F extends Folder>(folderRepo: RepoUtils<F>, folderClass: any, mailboxUid: string, type: Exclude<FolderType, FolderType.USER>, user?: JWTUser): Promise<F>;

package/dist/types/util/MailSendUtils.d.ts

@@ -0,0 +1,19 @@
+import { BlobStore } from "../blob/BlobStore.js";
+import { ScanPipeline } from "../scan/ScanPipeline.js";
+/** The outcome of `scanAndRelay()` a caller needs to finish persisting a sent message. */
+export interface ScanAndRelayResult {
+    /** The blob key `scanResult.sanitizedHtml` (if any) was stored under - see the identical reasoning in
+     * `ScanQueueJob.processEntry()`'s own doc comment on why this must never be folded into the raw body key. */
+    sanitizedHtmlBlobKey?: string;
+}
+/**
+ * Runs `raw` through `ScanPipeline` and, if it passes, relays it via `mailTransport` - the scan-then-relay core
+ * shared by every "send a composed message" entry point in this library (`BaseMessageRoute.send()`'s REST
+ * endpoint and the EAS `SendMail`/`SmartForward`/`SmartReply` commands via `sendComposedMime()` below), so this
+ * gate is defined exactly once rather than duplicated per protocol.
+ *
+ * Throws `ApiError` (422) if the scan pipeline's verdict is anything other than "deliver", or (502) if the
+ * transport itself rejects the message outright - both cases callers should let propagate as the request's
+ * own failure, not attempt to recover from.
+ */
+export declare function scanAndRelay(raw: Buffer, envelopeFrom: string, envelopeTo: string[], scanPipeline: ScanPipeline, mailTransport: any, blobStore: BlobStore): Promise<ScanAndRelayResult>;

package/dist/types/util/MailboxScopeUtils.d.ts

@@ -0,0 +1,19 @@
+import type { JWTUser } from "@rapidrest/core";
+import { RepoUtils } from "@rapidrest/service-core";
+import { Mailbox } from "../models/types.js";
+/**
+ * Resolves the `Mailbox` owned by `user` (a mailbox's `ownerUserUid` field, not an ACL lookup — this runs with
+ * `ignoreACL: true` deliberately, since it's used to derive the *scope* of what a query is allowed to touch,
+ * not to check permission on an already-identified record). Returns `undefined` if `user` is unauthenticated
+ * or owns no mailbox.
+ *
+ * See the doc comment on `findOrCreateWellKnownFolder`'s callers / `BaseMailboxScopedRoute` for why this
+ * exists: per-record ACLs in this platform inherit from their class-level ACL whenever no record-specific
+ * grant matches the caller, so a class-level grant broad enough to let any authenticated user list/read *some*
+ * records of a type also lets them list/read records they don't personally own, once class-level `LIST`/`READ`
+ * are opened up at all. The class-level ACL for every mailbox-owned entity in this library therefore denies
+ * `LIST`/`READ`/`COUNT`/`EXISTS` to `.*` entirely (see each entity's `@Protect` policy), and routes that need
+ * to list/count a caller's own records do so by explicitly scoping the query to their own mailbox and passing
+ * `ignoreACL: true` for that specific, safely-bounded query — the same pattern this function supports.
+ */
+export declare function resolveCallerMailboxUid<M extends Mailbox>(mailboxRepo: RepoUtils<M>, user?: JWTUser): Promise<string | undefined>;

package/dist/types/util/OptionalDeps.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Dynamically imports an optional peer dependency, throwing a helpful `ApiError` naming the package and its
+ * install command if it is not installed. Mirrors `@rapidrest/auth`'s `importArgon2()`/`importOTPLib()`
+ * convention so every optional adapter in this library (PDF/DOCX text extraction, OpenSearch) fails the same,
+ * actionable way rather than with a raw `MODULE_NOT_FOUND` error.
+ *
+ * @param packageName The npm package name to import.
+ */
+export declare function importOptional<T = any>(packageName: string): Promise<T>;

package/dist/types/util/RecoverableRepoUtils.d.ts

@@ -0,0 +1,24 @@
+import { RecoverableBaseEntity, type RepoDeleteOptions, RepoUtils } from "@rapidrest/service-core";
+/**
+ * Extends `RepoUtils` to close a gap in service-core's own soft-delete path: `RepoUtils.delete()`'s
+ * soft-delete branch (for a `RecoverableBaseEntity` subclass, when `purge` isn't requested) sets only
+ * `deleted: true` — unlike `update()`, it does not bump `dateModified`/`version` (confirmed by reading its
+ * source). EAS `Sync`'s per-folder watermark query (`find({dateModified: gt(lastSyncWatermark)})`, see
+ * `eas/EasSyncKeyUtils.ts`) needs a soft-deleted row to surface exactly the way an ordinary field change
+ * would, or a deletion would never be reported to a device that already synced the item.
+ *
+ * Stays entirely local to `@rapidrest/mail` (no service-core change): calls `super.delete()` unchanged for
+ * everything else (permission checks, ACL cleanup, cache invalidation, notifications, rollback hooks) and
+ * only adds one small follow-up write for the two fields service-core's own branch leaves alone. Wired in via
+ * the `repoUtilsClass` extension point every concrete Mongo/SQL route already declares (`ModelRoute.ts`'s
+ * `this._objectFactory.newInstance(this.repoUtilsClass || RepoUtils, ...)`), and by any job that builds a
+ * `RepoUtils` directly for one of the same entity classes.
+ *
+ * `RepoUtils.truncate()` has no soft-delete branch at all (it always hard-deletes, recoverable or not) — a
+ * bulk folder-empty is a documented, out-of-scope-for-this-override gap, not something this class fixes.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class RecoverableRepoUtils<T extends RecoverableBaseEntity> extends RepoUtils<T> {
+    delete(uid: string, options: RepoDeleteOptions): Promise<void>;
+}

package/dist/types/util/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public, backend-agnostic REST-layer helpers shared across this library's own routes and useful to any
+ * downstream protocol package (`@rapidmx/activesync`, `@rapidmx/mapi`, `@rapidmx/autodiscover`) that needs to
+ * resolve a caller's mailbox, walk a folder tree, send a composed message through the scan/relay pipeline, or
+ * soft-delete a `RecoverableBaseEntity` with a correctly bumped watermark. `OptionalDeps.ts`'s
+ * `importOptional()` is deliberately not re-exported here - it's an internal helper for this library's own
+ * optional peer dependencies (PDF/DOCX extraction, OpenSearch), not something a protocol package needs.
+ */
+export * from "./FolderUtils.js";
+export * from "./MailSendUtils.js";
+export * from "./MailboxScopeUtils.js";
+export * from "./RecoverableRepoUtils.js";