@rapidmx/restapi 0.1.0

package/dist/lib/util/MailSendUtils.js

@@ -0,0 +1,36 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import * as crypto from "crypto";
+import { ApiError } from "@rapidrest/core";
+import { ApiErrors } from "@rapidrest/service-core";
+import { resolveDeliveryVerdict } from "../scan/ScanPipeline.js";
+/**
+ * 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 async function scanAndRelay(raw, envelopeFrom, envelopeTo, scanPipeline, mailTransport, blobStore) {
+    const scanResult = await scanPipeline.run(raw, { from: envelopeFrom, to: envelopeTo });
+    const verdict = resolveDeliveryVerdict(scanResult);
+    if (verdict !== "deliver") {
+        throw new ApiError(ApiErrors.INVALID_REQUEST, 422, "This message could not be sent because it failed spam/malware scanning.");
+    }
+    const transportResult = await mailTransport.send({ raw, envelopeFrom, envelopeTo });
+    if (transportResult.accepted.length === 0) {
+        throw new ApiError(ApiErrors.INTERNAL_ERROR, 502, "The mail transport rejected this message.");
+    }
+    let sanitizedHtmlBlobKey;
+    if (scanResult.sanitizedHtml !== undefined) {
+        sanitizedHtmlBlobKey = `sanitized/${crypto.randomUUID()}`;
+        await blobStore.put(sanitizedHtmlBlobKey, Buffer.from(scanResult.sanitizedHtml, "utf-8"), { contentType: "text/html" });
+    }
+    return { sanitizedHtmlBlobKey };
+}
+//# sourceMappingURL=MailSendUtils.js.map

package/dist/lib/util/MailSendUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MailSendUtils.js","sourceRoot":"","sources":["../../../src/util/MailSendUtils.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAE,sBAAsB,EAAgB,MAAM,yBAAyB,CAAC;AAS/E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAC9B,GAAW,EACX,YAAoB,EACpB,UAAoB,EACpB,YAA0B,EAC1B,aAAkB,EAClB,SAAoB;IAEpB,MAAM,UAAU,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;IACvF,MAAM,OAAO,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IACnD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,eAAe,EAAE,GAAG,EAAE,yEAAyE,CAAC,CAAC;IAClI,CAAC;IAED,MAAM,eAAe,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAC;IACpF,IAAI,eAAe,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,cAAc,EAAE,GAAG,EAAE,2CAA2C,CAAC,CAAC;IACnG,CAAC;IAED,IAAI,oBAAwC,CAAC;IAC7C,IAAI,UAAU,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACzC,oBAAoB,GAAG,aAAa,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;QAC1D,MAAM,SAAS,CAAC,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IAC5H,CAAC;IAED,OAAO,EAAE,oBAAoB,EAAE,CAAC;AACpC,CAAC"}

package/dist/lib/util/MailboxScopeUtils.js

@@ -0,0 +1,23 @@
+/**
+ * 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 async function resolveCallerMailboxUid(mailboxRepo, user) {
+    if (!user) {
+        return undefined;
+    }
+    const mailboxes = await mailboxRepo.find({ ownerUserUid: user.uid }, { ignoreACL: true, limit: 1 });
+    return mailboxes[0]?.uid;
+}
+//# sourceMappingURL=MailboxScopeUtils.js.map

package/dist/lib/util/MailboxScopeUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MailboxScopeUtils.js","sourceRoot":"","sources":["../../../src/util/MailboxScopeUtils.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CACzC,WAAyB,EACzB,IAAc;IAEd,IAAI,CAAC,IAAI,EAAE,CAAC;QACR,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,SAAS,GAAQ,MAAM,WAAW,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IACzG,OAAO,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;AAC7B,CAAC"}

package/dist/lib/util/OptionalDeps.js

@@ -0,0 +1,23 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiError } from "@rapidrest/core";
+import { ApiErrors } from "@rapidrest/service-core";
+/**
+ * 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 async function importOptional(packageName) {
+    try {
+        return (await import(packageName));
+    }
+    catch (err) {
+        throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, `This feature requires the optional peer dependency '${packageName}'. Install it with: yarn add ${packageName}`);
+    }
+}
+//# sourceMappingURL=OptionalDeps.js.map

package/dist/lib/util/OptionalDeps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OptionalDeps.js","sourceRoot":"","sources":["../../../src/util/OptionalDeps.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAU,WAAmB;IAC7D,IAAI,CAAC;QACD,OAAO,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,CAAM,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAChB,MAAM,IAAI,QAAQ,CACd,SAAS,CAAC,cAAc,EACxB,GAAG,EACH,uDAAuD,WAAW,gCAAgC,WAAW,EAAE,CAClH,CAAC;IACN,CAAC;AACL,CAAC"}

package/dist/lib/util/RecoverableRepoUtils.js

@@ -0,0 +1,42 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { MongoRepository, 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 class RecoverableRepoUtils extends RepoUtils {
+    async delete(uid, options) {
+        await super.delete(uid, options);
+        if (options.purge || !this.repo) {
+            return;
+        }
+        const dateModified = new Date();
+        if (this.repo instanceof MongoRepository) {
+            await this.repo.updateMany({ uid }, { $set: { dateModified }, $inc: { version: 1 } });
+        }
+        else {
+            await this.repo.update({ uid }, { dateModified });
+            await this.repo.increment({ uid }, "version", 1);
+        }
+    }
+}
+//# sourceMappingURL=RecoverableRepoUtils.js.map

package/dist/lib/util/RecoverableRepoUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecoverableRepoUtils.js","sourceRoot":"","sources":["../../../src/util/RecoverableRepoUtils.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,EAAE,eAAe,EAAiD,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,oBAAsD,SAAQ,SAAY;IAC5E,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,OAA0B;QACvD,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAEjC,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAC9B,OAAO;QACX,CAAC;QAED,MAAM,YAAY,GAAS,IAAI,IAAI,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,IAAI,YAAY,eAAe,EAAE,CAAC;YACvC,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,GAAG,EAAS,EAAE,EAAE,IAAI,EAAE,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAS,CAAC,CAAC;QACxG,CAAC;aAAM,CAAC;YACJ,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,EAAS,EAAE,EAAE,YAAY,EAAS,CAAC,CAAC;YAChE,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAS,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;CACJ"}

package/dist/lib/util/index.js

@@ -0,0 +1,17 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * 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";
+//# sourceMappingURL=index.js.map

package/dist/lib/util/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/util/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAE/E;;;;;;;GAOG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC"}

package/dist/types/blob/BlobStore.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The options available when storing a new blob via `BlobStore.put()`.
+ */
+export interface BlobPutOptions {
+    /** The MIME content type of the data being stored, if known. */
+    contentType?: string;
+}
+/** A byte range to retrieve via `BlobStore.getStream()`. `end` is inclusive; omit for "to end of blob". */
+export interface BlobRange {
+    start: number;
+    end?: number;
+}
+/**
+ * Provides storage for binary content too large or unstructured to live inline on an entity record — raw MIME
+ * message sources, rendered message bodies, attachment content, extracted attachment text, and contact photos
+ * are all stored here, referenced from the owning entity by a `blobKey`. No entity in this library ever stores
+ * binary content directly in a Mongo/SQL column.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface BlobStore {
+    /**
+     * Stores `data` under `key`, replacing any existing blob at that key.
+     */
+    put(key: string, data: Buffer | NodeJS.ReadableStream, options?: BlobPutOptions): Promise<void>;
+    /**
+     * Retrieves the full content stored under `key`.
+     *
+     * @throws if no blob exists at `key`.
+     */
+    get(key: string): Promise<Buffer>;
+    /**
+     * Retrieves a readable stream of the content stored under `key`, optionally limited to `range`. Used to
+     * serve large attachments (e.g. MAPI/EAS `ItemOperations` fetch, webmail download) without buffering the
+     * entire blob into memory.
+     *
+     * @throws if no blob exists at `key`.
+     */
+    getStream(key: string, range?: BlobRange): Promise<NodeJS.ReadableStream>;
+    /**
+     * Removes the blob stored under `key`. A no-op if no blob exists at `key`.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Determines whether a blob exists at `key`.
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Returns the size, in bytes, of the blob stored under `key`.
+     *
+     * @throws if no blob exists at `key`.
+     */
+    size(key: string): Promise<number>;
+}

package/dist/types/blob/LocalFsBlobStore.d.ts

@@ -0,0 +1,23 @@
+import { BlobPutOptions, BlobRange, BlobStore } from "./BlobStore.js";
+/**
+ * A `BlobStore` implementation backed by the local filesystem. Suitable for single-instance deployments or
+ * where `key`'s underlying directory is itself a shared/replicated mount (e.g. NFS). Larger deployments should
+ * prefer `S3BlobStore` instead.
+ *
+ * Keys are sharded two levels deep by the first four characters of their MD5 hash (e.g. key `abc123` is stored
+ * at `<root>/ab/c1/abc123`) to avoid placing an unbounded number of files in a single directory.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class LocalFsBlobStore implements BlobStore {
+    private root;
+    private resolvePath;
+    put(key: string, data: Buffer | NodeJS.ReadableStream, _options?: BlobPutOptions): Promise<void>;
+    get(key: string): Promise<Buffer>;
+    getStream(key: string, range?: BlobRange): Promise<NodeJS.ReadableStream>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    size(key: string): Promise<number>;
+}
+/** Coerces a `Buffer | NodeJS.ReadableStream` into a `Buffer`, for adapters that only accept whole buffers. */
+export declare function toBuffer(data: Buffer | NodeJS.ReadableStream): Promise<Buffer>;

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

@@ -0,0 +1,2 @@
+export * from "./BlobStore.js";
+export * from "./LocalFsBlobStore.js";

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./models/index.js";
+export * from "./routes/index.js";
+export * from "./jobs/index.js";
+export * from "./transport/index.js";
+export * from "./blob/index.js";
+export * from "./push/index.js";
+export * from "./util/index.js";

package/dist/types/jobs/AttachmentExtractionJob.d.ts

@@ -0,0 +1,34 @@
+import { BackgroundService } from "@rapidrest/service-core";
+import { Attachment, Message } from "../models/types.js";
+/**
+ * Runs `ExtractorRegistry` (PDF/DOCX/plain-text/HTML text extraction) over `Attachment` records that haven't
+ * been processed yet (`extractedTextBlobKey` unset), as a background job — never inline on ingestion, since
+ * extraction can be slow and must not block SMTP-ACK or webmail send/save-draft latency (see the architecture
+ * plan's rationale for this).
+ *
+ * Every eligible attachment gets `extractedTextBlobKey` set exactly once, even when nothing extractable was
+ * found (an empty-content blob) — this is what marks an attachment as "already attempted" so an unsupported
+ * MIME type (e.g. an image) isn't re-selected by this job forever. When extraction *does* produce non-empty
+ * text for an attachment whose parent `Message` was already search-indexed, this job clears that message's
+ * `searchIndexedAt` back to `undefined` so `SearchIndexJob` re-indexes it with the newly available text.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class AttachmentExtractionJob<A extends Attachment, M extends Message> extends BackgroundService {
+    protected abstract attachmentClass: any;
+    protected abstract messageClass: any;
+    private _objectFactory?;
+    private attachmentRepo?;
+    private messageRepo?;
+    private blobStore?;
+    private extractorRegistry;
+    private scheduleExpr;
+    private batchSize;
+    private logger;
+    get schedule(): string | undefined;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void> | void;
+    run(): Promise<void>;
+    private processAttachment;
+}

package/dist/types/jobs/CalendarReminderJob.d.ts

@@ -0,0 +1,37 @@
+import { BackgroundService } from "@rapidrest/service-core";
+import { CalendarEvent } from "../models/types.js";
+/**
+ * Polls upcoming `CalendarEvent` records and dispatches a `"reminder"` push notification once each event's
+ * configured `reminderMinutesBeforeStart` fire time falls within this job's own polling window.
+ *
+ * `CalendarEvent` has no persisted "reminder already sent" flag, and adding one is out of scope here, so this
+ * job takes the simplest correct-enough approach: the query only prunes past events (`startDate` lower-bounded
+ * at `now`, via `ModelUtils.buildSearchQuery`'s single-sided `gte(...)` operator, which - unlike its two-sided
+ * `range(...)` operator - has confirmed correct Date coercion on both backends), and everything else (the
+ * upper lookahead bound, and the actual reminder-fire-time arithmetic) is computed/filtered in-process.
+ *
+ * KNOWN LIMITATION: without a persisted "reminder already sent" flag (e.g. a future `CalendarEvent.
+ * reminderSentAt`), a reminder could in principle fire more than once if this job's own polling window ever
+ * overlaps across runs (e.g. after a restart, or a run that took longer than `windowSeconds`). This is a
+ * deliberate simplification, not an oversight - flagged here for a future follow-up.
+ *
+ * Concrete entity classes are supplied by the Mongo/SQL subclasses (`CalendarReminderJobMongo`/
+ * `CalendarReminderJobSQL`), following the same generic pattern `ScanQueueJob` uses.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class CalendarReminderJob<CE extends CalendarEvent> extends BackgroundService {
+    protected abstract calendarEventClass: any;
+    private _objectFactory?;
+    private calendarEventRepo?;
+    private notificationUtils?;
+    private scheduleExpr;
+    private batchSize;
+    private windowSeconds;
+    private logger;
+    get schedule(): string | undefined;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void> | void;
+    run(): Promise<void>;
+}

package/dist/types/jobs/EasDeviceStateCleanupJob.d.ts

@@ -0,0 +1,26 @@
+import { BackgroundService } from "@rapidrest/service-core";
+import { DeviceSyncState } from "../models/types.js";
+/**
+ * Prunes `DeviceSyncState` rows for EAS devices that haven't synced in more than `device_ttl_days` days (or
+ * that have never successfully synced at all), keeping the collection from growing unbounded with abandoned
+ * device pairings.
+ *
+ * Concrete entity classes are supplied by the Mongo/SQL subclasses (`EasDeviceStateCleanupJobMongo`/
+ * `EasDeviceStateCleanupJobSQL`), following the same generic pattern `ScanQueueJob` uses.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class EasDeviceStateCleanupJob<D extends DeviceSyncState> extends BackgroundService {
+    protected abstract deviceSyncStateClass: any;
+    private _objectFactory?;
+    private deviceSyncStateRepo?;
+    private scheduleExpr;
+    private batchSize;
+    private deviceTtlDays;
+    private logger;
+    get schedule(): string | undefined;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void> | void;
+    run(): Promise<void>;
+}

package/dist/types/jobs/ExternalShareExpirationJob.d.ts

@@ -0,0 +1,34 @@
+import { BackgroundService } from "@rapidrest/service-core";
+import { CalendarShareLink } from "../models/types.js";
+/**
+ * Garbage-collects expired `CalendarShareLink` rows (anonymous external calendar-sharing links whose
+ * `expiresAt` has passed), also revoking the `ACLRecord` each link's `token` was granted on its shared
+ * folder's `AccessControlList` (see `BaseCalendarShareLinkRoute`, which grants/upserts that same record on
+ * create/update — this job is the other half of keeping it in sync, for links that expire rather than being
+ * explicitly deleted via the API).
+ *
+ * Concrete entity classes are supplied by the Mongo/SQL subclasses (`ExternalShareExpirationJobMongo`/
+ * `ExternalShareExpirationJobSQL`), following the same generic pattern `ScanQueueJob` uses.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class ExternalShareExpirationJob<S extends CalendarShareLink> extends BackgroundService {
+    protected abstract calendarShareLinkClass: any;
+    private _objectFactory?;
+    private calendarShareLinkRepo?;
+    private aclUtils?;
+    private scheduleExpr;
+    private batchSize;
+    private logger;
+    get schedule(): string | undefined;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void> | void;
+    run(): Promise<void>;
+    /** Removes any ACL record for `token` from `folderUid`'s ACL - see `BaseCalendarShareLinkRoute`'s identical
+     * helper for the full rationale (kept as a separate copy here rather than a shared import, since this job
+     * has no other dependency on the routes layer and the logic is a few lines). A no-op if the folder has no
+     * ACL document or no matching record - failing open here keeps a missing/corrupt folder ACL from turning a
+     * routine expiration sweep into a failed job run for every OTHER link in the same batch. */
+    private revokeShareTokenAccess;
+}

package/dist/types/jobs/MailboxQuotaRecalcJob.d.ts

@@ -0,0 +1,44 @@
+import { BackgroundService } from "@rapidrest/service-core";
+import { Attachment, Mailbox, Message } from "../models/types.js";
+/**
+ * Periodically recomputes `Mailbox.usedBytes` from the mailbox's actual stored content (message body blobs plus
+ * attachment content) and corrects any drift from the incremental updates other code paths (ingest, delete,
+ * etc.) are expected to apply on their own. This job is a safety net against drift, not the primary mechanism
+ * for keeping `usedBytes` accurate — it runs cheaply and idempotently, and only writes when the recomputed value
+ * actually differs from what's stored.
+ *
+ * Concrete entity classes are supplied by the Mongo/SQL subclasses (`MailboxQuotaRecalcJobMongo`/
+ * `MailboxQuotaRecalcJobSQL`), following the same multi-entity-type generic pattern `ScanQueueJob` uses.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class MailboxQuotaRecalcJob<MB extends Mailbox, M extends Message, A extends Attachment> extends BackgroundService {
+    protected abstract mailboxClass: any;
+    protected abstract messageClass: any;
+    protected abstract attachmentClass: any;
+    private _objectFactory?;
+    private mailboxRepo?;
+    private messageRepo?;
+    private attachmentRepo?;
+    private blobStore?;
+    private scheduleExpr;
+    private batchSize;
+    private logger;
+    get schedule(): string | undefined;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void> | void;
+    run(): Promise<void>;
+    /**
+     * Fetches every page of `repo.find(criteria, ...)` results, not just the first. `RepoUtils.find()` caps at
+     * 100 rows per call by default (and SQL ignores `options.limit`/`options.page` entirely unless `limit`/
+     * `page` are *also* baked into the criteria object itself - see the comments on `run()`'s own `find()` call
+     * above for the full explanation) - a bare, unpaginated `find()` call here would silently recompute
+     * `usedBytes` from only the first ~100 messages/attachments, permanently understating usage for any mailbox
+     * larger than that. Confirmed as a real bug (not just a SQL-only quirk) by real-database testing: the
+     * previous unpaginated call truncated identically on both backends, since 100 is `RepoUtils.find()`'s own
+     * unconditional default, independent of which backend is in use.
+     */
+    private findAllPages;
+    private recalcMailbox;
+}

package/dist/types/jobs/MeetingSchedulingJob.d.ts

@@ -0,0 +1,32 @@
+import { BackgroundService } from "@rapidrest/service-core";
+import { CalendarEvent } from "../models/types.js";
+/**
+ * Scheduled placeholder for outbound iTIP meeting-request processing: an organizer creates/updates a
+ * `CalendarEvent` with attendees, and an iTIP `REQUEST` email needs to go out to each attendee.
+ *
+ * TODO: Full iTIP send/response processing is deferred pending (1) an `IcsUtils` helper for composing RFC 5546
+ * iTIP messages/ICS payloads, which does not exist in this codebase yet, and (2) a persisted `CalendarEvent`
+ * invite-tracking field (there is currently no way to tell "attendees were already invited" apart from
+ * "attendees were just added and haven't been invited yet"). Inventing either of those here would just have to
+ * be redone once the real implementations land. This job currently exists purely as a scheduled placeholder so
+ * the surrounding plumbing (config, DI, `jobs/index.ts` registration) is already in place when that follow-up
+ * work is ready - `run()` only finds and logs candidate events, it does not compose or send anything.
+ *
+ * Concrete entity classes are supplied by the Mongo/SQL subclasses (`MeetingSchedulingJobMongo`/
+ * `MeetingSchedulingJobSQL`), following the same generic pattern `ScanQueueJob` uses.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class MeetingSchedulingJob<CE extends CalendarEvent> extends BackgroundService {
+    protected abstract calendarEventClass: any;
+    private _objectFactory?;
+    private calendarEventRepo?;
+    private scheduleExpr;
+    private batchSize;
+    private logger;
+    get schedule(): string | undefined;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void> | void;
+    run(): Promise<void>;
+}

package/dist/types/jobs/QuarantineRetentionJob.d.ts

@@ -0,0 +1,27 @@
+import { BackgroundService } from "@rapidrest/service-core";
+import { QuarantineEntry } from "../models/types.js";
+/**
+ * Purges `QuarantineEntry` rows (and, once `BlobStore` deletion is wired in here, their `rawBlobKey` payload)
+ * once they've sat in quarantine longer than `retention_days`, whether or not they were ever released. A
+ * released entry is retained for the same window as an unreleased one — this job doesn't distinguish between
+ * them, since both represent quarantine history an operator may want to review for that same window.
+ *
+ * Concrete entity classes are supplied by the Mongo/SQL subclasses (`QuarantineRetentionJobMongo`/
+ * `QuarantineRetentionJobSQL`), following the same generic pattern `ScanQueueJob` uses.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class QuarantineRetentionJob<Q extends QuarantineEntry> extends BackgroundService {
+    protected abstract quarantineEntryClass: any;
+    private _objectFactory?;
+    private quarantineEntryRepo?;
+    private scheduleExpr;
+    private batchSize;
+    private retentionDays;
+    private logger;
+    get schedule(): string | undefined;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void> | void;
+    run(): Promise<void>;
+}

package/dist/types/jobs/ScanQueueJob.d.ts

@@ -0,0 +1,41 @@
+import { BackgroundService } from "@rapidrest/service-core";
+import { Attachment, Folder, IngestQueueEntry, Message, QuarantineEntry, ScanResult } from "../models/types.js";
+/**
+ * Drains `IngestQueueEntry` rows staged by `BaseMailIngestRoute`: runs the `ScanPipeline` against each one's
+ * raw message, then either delivers it to the mailbox's Inbox, files it in Junk, or holds it in
+ * `QuarantineEntry` — depending on `resolveDeliveryVerdict()`. No client protocol (webmail/EAS/MAPI) ever sees
+ * a message before this job has processed it.
+ *
+ * Concrete entity classes are supplied by the Mongo/SQL subclasses (`ScanQueueJobMongo`/`ScanQueueJobSQL`),
+ * following the same multi-entity-type generic pattern `DefaultAccounts` uses.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class ScanQueueJob<Q extends IngestQueueEntry, F extends Folder, M extends Message, A extends Attachment, QE extends QuarantineEntry, SR extends ScanResult> extends BackgroundService {
+    protected abstract ingestQueueClass: any;
+    protected abstract folderClass: any;
+    protected abstract messageClass: any;
+    protected abstract attachmentClass: any;
+    protected abstract quarantineEntryClass: any;
+    protected abstract scanResultClass: any;
+    private _objectFactory?;
+    private ingestQueueRepo?;
+    private folderRepo?;
+    private messageRepo?;
+    private attachmentRepo?;
+    private quarantineEntryRepo?;
+    private scanResultRepo?;
+    private blobStore?;
+    private scanPipeline?;
+    /** Publishes a live-update notification (see `push/MailPushRoute.ts`) once a message is delivered. */
+    private notificationUtils?;
+    private scheduleExpr;
+    private batchSize;
+    private logger;
+    get schedule(): string | undefined;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void> | void;
+    run(): Promise<void>;
+    private processEntry;
+}

package/dist/types/jobs/SearchIndexJob.d.ts

@@ -0,0 +1,37 @@
+import { BackgroundService } from "@rapidrest/service-core";
+import { Attachment, Message } from "../models/types.js";
+/**
+ * Reconciles `SearchProvider`'s index against `Message` records that haven't been indexed yet
+ * (`Message.searchIndexedAt` is unset). This is what decouples "committed to the primary datastore" from
+ * "visible in search" (see `SearchProvider`'s doc comment) — a just-ingested or just-sent message is readable
+ * via the standard REST API immediately, and becomes findable via search within one run of this job.
+ *
+ * Scoped to `Message` search for the initial pragmatic subset, since full-text search over subject/body/
+ * attachments was the explicit requirement driving this subsystem; indexing Contacts/CalendarEvents/Notes/
+ * Tasks is a natural extension (the `SearchProvider`/`SearchDocument` interfaces already support it) but is
+ * deliberately left for a later pass rather than built speculatively here.
+ *
+ * `AttachmentExtractionJob` clears `searchIndexedAt` back to `undefined` on a message whose attachment text
+ * extraction completes *after* this job already indexed it once, so it gets picked up again with the newly
+ * available attachment text.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class SearchIndexJob<M extends Message, A extends Attachment> extends BackgroundService {
+    protected abstract messageClass: any;
+    protected abstract attachmentClass: any;
+    private _objectFactory?;
+    private messageRepo?;
+    private attachmentRepo?;
+    private blobStore?;
+    private searchProvider?;
+    private scheduleExpr;
+    private batchSize;
+    private logger;
+    get schedule(): string | undefined;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void> | void;
+    run(): Promise<void>;
+    private buildDocument;
+}

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

@@ -0,0 +1,9 @@
+export * from "./AttachmentExtractionJob.js";
+export * from "./CalendarReminderJob.js";
+export * from "./EasDeviceStateCleanupJob.js";
+export * from "./ExternalShareExpirationJob.js";
+export * from "./MailboxQuotaRecalcJob.js";
+export * from "./MeetingSchedulingJob.js";
+export * from "./QuarantineRetentionJob.js";
+export * from "./ScanQueueJob.js";
+export * from "./SearchIndexJob.js";

package/dist/types/jobs/mongo/AttachmentExtractionJobMongo.d.ts

@@ -0,0 +1,6 @@
+import { AttachmentExtractionJob } from "../AttachmentExtractionJob.js";
+import { AttachmentMongo, MessageMongo } from "../../mongo.js";
+export declare class AttachmentExtractionJobMongo extends AttachmentExtractionJob<AttachmentMongo, MessageMongo> {
+    protected attachmentClass: any;
+    protected messageClass: any;
+}

package/dist/types/jobs/mongo/CalendarReminderJobMongo.d.ts

@@ -0,0 +1,5 @@
+import { CalendarReminderJob } from "../CalendarReminderJob.js";
+import { CalendarEventMongo } from "../../mongo.js";
+export declare class CalendarReminderJobMongo extends CalendarReminderJob<CalendarEventMongo> {
+    protected calendarEventClass: any;
+}

package/dist/types/jobs/mongo/EasDeviceStateCleanupJobMongo.d.ts

@@ -0,0 +1,5 @@
+import { EasDeviceStateCleanupJob } from "../EasDeviceStateCleanupJob.js";
+import { DeviceSyncStateMongo } from "../../mongo.js";
+export declare class EasDeviceStateCleanupJobMongo extends EasDeviceStateCleanupJob<DeviceSyncStateMongo> {
+    protected deviceSyncStateClass: any;
+}

package/dist/types/jobs/mongo/ExternalShareExpirationJobMongo.d.ts

@@ -0,0 +1,5 @@
+import { ExternalShareExpirationJob } from "../ExternalShareExpirationJob.js";
+import { CalendarShareLinkMongo } from "../../mongo.js";
+export declare class ExternalShareExpirationJobMongo extends ExternalShareExpirationJob<CalendarShareLinkMongo> {
+    protected calendarShareLinkClass: any;
+}