@rapidmx/mapi-plugin 1.0.0-beta.10

package/dist/types/rop/RopSubmitMessageHandler.d.ts

@@ -0,0 +1,80 @@
+import type { BufferReader, BufferWriter } from "../codec/BufferCursor.js";
+import { type RopContext, type RopHandler } from "./RopHandler.js";
+export { isPlainEmailAddress, parseAddressList } from "./AddressList.js";
+/**
+ * `RopSubmitMessage` (`[MS-OXOMSG]`/`[MS-OXCROPS]`): sends a composed message - the actual trigger point for
+ * this pragmatic subset's compose/send pipeline, since `RopSaveChangesMessage` itself does no real persistence
+ * (see its own doc comment). Builds a raw MIME buffer from whatever `RopSetProperties`/`RopWriteStream` calls
+ * accumulated on the draft handle (`Subject`, the `PidTagBody` stream or an inline `PidTagBody` property, and
+ * addressing - see below), via `nodemailer`'s `MailComposer` (already a dependency, used elsewhere in this
+ * library only to *send*, not build, MIME - this is its first use purely as a RFC 5322 serializer), then calls
+ * the exact same `scanAndRelay()` scan-then-relay pipeline `BaseMessageRoute.send()`/EAS's `ComposeMailCommand`
+ * already share, and persists a Sent Items copy (mirroring `ComposeMailCommand`'s own always-committed Sent
+ * Items behavior for MAPI submission specifically, since - unlike EAS's optional `SaveInSentItems` - a MAPI
+ * `RopSubmitMessage` call has no "don't keep a copy" option to honor).
+ *
+ * **Known, deliberate limitation - no `RopModifyRecipients` support**: real recipient rows (`[MS-OXCMSG]`
+ * §2.2.3.2, each with its own `PidTagEmailAddress`/`PidTagRecipientType`) are a substantial structure this
+ * pragmatic subset's ROP coverage doesn't include. Instead, addressing is read from `PidTagDisplayTo`/
+ * `DisplayCc`/`DisplayBcc` - the same semicolon-separated "cached recipient display string" properties real
+ * Outlook *also* always sets via `RopSetProperties` alongside `RopModifyRecipients` (as a display-only
+ * convenience cache). Entries are separated by `;` and parsed with nodemailer's `addressparser`, so both bare
+ * addresses and resolved `Name <address>` forms work. A client that resolved a name against an address book may
+ * write the display name alone; that is looked up among the caller's own contacts (see `resolveRecipientList`), and
+ * a name matching no single contact fails the submit with `MAPI_E_NOT_FOUND`. It is still **not** a substitute for
+ * real recipient rows (there is no recipient table to fall back on), so the whole send is refused rather than sent to
+ * fewer people than the user addressed. A malformed recipient fails with `MAPI_E_INVALID_PARAMETER`.
+ *
+ * `SubmitFlags` (`PreprocessOnly`, ...) is decoded to advance past it correctly but not honored - this
+ * pragmatic subset has no transport-agent preprocessing distinction to vary by flag.
+ *
+ * **`PidTagDeferredSendTime`** ("Do not deliver before"), if set to a future time via `RopSetProperties`,
+ * parks the message in Outbox with `Message.scheduledSendTime` set instead of relaying immediately - mirroring
+ * `BaseMessageRoute.send()`'s own identical branch - for `ScheduledSendJob` to relay later via this same
+ * `scanAndRelay()` pipeline. **`PidTagReadReceiptRequested`**, if `true`, attaches a real
+ * `Disposition-Notification-To` header (see `util/ReceiptUtils.ts`) and is recorded on the persisted message's
+ * own `requestReceipt` field - honored only when the client explicitly sets it, not this mailbox's
+ * `alwaysRequestReceiptInternal`/`External` defaults (those apply to the REST/webmail compose path only).
+ *
+ * **Once per draft.** A mail or meeting-response draft is marked `submitted` as soon as a submit gets past the handle
+ * check, whatever the outcome, and a submitted draft can't be submitted again (`MAPI_E_INVALID_OBJECT`) or changed by
+ * `RopSetProperties`/`RopWriteStream`; its write-stream chunks are deleted once read. Each `Execute` runs at most
+ * `MAX_SUBMITS_PER_EXECUTE` submits, and a message may have at most `MAX_RECIPIENTS_PER_MESSAGE` recipients
+ * (`MAPI_E_TOO_BIG`), counted before any display name is looked up.
+ *
+ * **Calendar branches**: a draft whose `PidTagMessageClass` starts with `"IPM.Appointment"` is routed to
+ * `submitAppointment()` instead of the mail path below - see that method's own doc comment. One starting with
+ * `"IPM.Schedule.Meeting.Resp."` (an attendee's own accept/decline/tentative response to a meeting this server
+ * previously invited them to) is routed to `MeetingMessageClassHandler.submitMeetingResponse()` instead - see
+ * that function's own doc comment.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class RopSubmitMessageHandler implements RopHandler {
+    readonly ropId = 50;
+    handle(reader: BufferReader, writer: BufferWriter, context: RopContext): Promise<void>;
+    /**
+     * Submits a Calendar item. The appointment itself is already persisted (`RopSaveChangesMessageHandler` writes the
+     * real `CalendarEvent` row at Save time, unlike a mail draft, which stays purely in-session until Submit), so there
+     * is nothing left to store and nothing is sent from here.
+     *
+     * **Invites are restapi's `MeetingSchedulingJob`'s job.** That job sends an iTIP `REQUEST` for every
+     * organizer-owned event whose `inviteSequenceSent` differs from its `sequence`, claiming each revision with a
+     * versioned update before sending and building the invite with restapi's own `buildEventIcs` (so a recurring
+     * meeting's invite carries its `RRULE` and exceptions). Saving stamps `inviteSequenceSent = sequence`, so a meeting
+     * that is only saved ("Save & Close", or "save changes but don't send") invites no one. Submitting clears the stamp
+     * (`inviteSequenceSent: null`) with a versioned update, which makes the job send the current revision exactly once.
+     * - A revision that is already waiting for the job (submitted and not yet sent, or never stamped) is left alone, so
+     * submitting it again before the job runs doesn't cause a second invite.
+     * - The update is versioned (`asEntity`). The job only ever claims a waiting revision, so a conflict here comes from
+     * some other edit (an attendee's reply updating the row, a REST edit); the row is read again and the check repeated,
+     * up to `MAX_INVITE_REQUEST_ATTEMPTS` times, after which the ROP fails (`MAPI_E_CALL_FAILED`).
+     * - Submitting a revision the job has already sent sends it again: the client asked to send.
+     *
+     * Only the organizer's own copy may be submitted (an attendee's copy of someone else's meeting answers
+     * `MAPI_E_INVALID_OBJECT`, as before, and nothing is changed).
+     */
+    private submitAppointment;
+}
+/** How many times `requestInvites` re-reads a row whose versioned update lost to another edit before giving up. */
+export declare const MAX_INVITE_REQUEST_ATTEMPTS = 3;

package/dist/types/rop/RopWriteStreamHandler.d.ts

@@ -0,0 +1,31 @@
+import type { BufferReader, BufferWriter } from "../codec/BufferCursor.js";
+import type { MapiObjectHandle } from "../MapiSessionManager.js";
+import { type RopContext, type RopHandler } from "./RopHandler.js";
+/** The largest body a write stream accumulates. */
+export declare const MAX_WRITE_STREAM_BYTES: number;
+/** How long a write stream's chunks are kept after its last write - the session's own idle lifetime. */
+export declare const WRITE_STREAM_TTL_SECONDS: number;
+export { writeStreamKey } from "./HandleDataCache.js";
+/**
+ * `RopWriteStream` (`[MS-OXCPRPT]`/`[MS-OXCROPS]`): writes bytes to a stream opened in `ReadWrite`/`Create`
+ * mode (`RopOpenStreamHandler`'s write-mode branch - the only kind of writable stream this pragmatic subset
+ * ever produces, always a `RopCreateMessage` draft's `PidTagBody`). Each write is stored as a chunk keyed by its
+ * offset in the `HandleDataStore` (Redis when configured), not in the session: only `writeSize` is session state.
+ * Keying by offset makes a retried write (after a request whose session save lost a conflict) replace its chunk
+ * instead of appending it twice. Up to `MAX_WRITE_STREAM_BYTES`; a write past that fails with `MAPI_E_TOO_BIG` and
+ * nothing is stored, as it is when the session's or user's handle data quota (`handleDataOwners`) is used up. A stream
+ * whose draft has already been submitted takes no more writes. `RopSubmitMessageHandler` reassembles the body (`readWriteStream`) once composing is complete.
+ *
+ * Like `RopReadStream`, `[MS-OXCROPS]` documents only one combined response-buffer shape for this ROP (no
+ * separate Success/Failure pages) - `WrittenSize` is always present, `0` standing in for the failure case.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class RopWriteStreamHandler implements RopHandler {
+    readonly ropId = 45;
+    readonly failureTailBytes = 2;
+    handle(reader: BufferReader, writer: BufferWriter, context: RopContext): Promise<void>;
+}
+/** The bytes written so far to the write stream `stream` at `handleIndex`, or `undefined` when they can no longer be
+ * reassembled (a chunk expired or was evicted). */
+export declare function readWriteStream(context: RopContext, handleIndex: number, stream: MapiObjectHandle): Promise<Buffer | undefined>;

package/dist/types/rop/TaskNamedProperties.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The Task named-property identity table (`(PropertySet GUID, LID)` pairs) this pragmatic subset supports, per
+ * `[MS-OXPROPS]`/`[MS-OXOTASK]` - the exact `CalendarNamedProperties.ts` precedent, adapted for `PSETID_Task`,
+ * shared by `PropertyResolvers.ts` (the read side: `taskValueFor`). Read-only in this pass - see
+ * `TaskTarget.ts`'s own doc comment for why there's no write-side (`RopSetProperties`/`RopSaveChangesMessage`)
+ * counterpart yet.
+ */
+export declare const PSETID_TASK = "00062003-0000-0000-c000-000000000046";
+/** `PidLidTaskStatus` (`PT_LONG`) - `[MS-OXOTASK]` §2.2.2.1.5's own `olTaskNotStarted`(0)/`olTaskInProgress`(1)/
+ * `olTaskComplete`(2)/`olTaskWaiting`(3)/`olTaskDeferred`(4) values. This data model's `Task.completed` is a
+ * plain boolean with no in-progress/waiting/deferred distinction, so only `olTaskNotStarted`/`olTaskComplete`
+ * are ever produced - a documented, harmless approximation, the same category as `CalendarNamedProperties.ts`'s
+ * own `olWorkingElsewhere` gap. */
+export declare const LID_TASK_STATUS = 33025;
+export declare const TASK_STATUS_NOT_STARTED = 0;
+export declare const TASK_STATUS_COMPLETE = 2;
+/** `PidLidPercentComplete` (`PT_R8`, `[MS-OXOTASK]` §2.2.2.1.6) - `0.0`-`1.0`. No partial-progress tracking in
+ * this data model either, so this is always `1.0` (complete) or `0.0` (not started), mirroring
+ * `LID_TASK_STATUS`'s own two-value approximation. */
+export declare const LID_PERCENT_COMPLETE = 33026;
+/** `PidLidTaskDueDate` (`PT_SYSTIME`, `[MS-OXOTASK]` §2.2.2.2.4). */
+export declare const LID_TASK_DUE_DATE = 33029;
+/** `PidLidTaskComplete` (`PT_BOOLEAN`, `[MS-OXOTASK]` §2.2.2.1.9) - maps directly to `Task.completed`. */
+export declare const LID_TASK_COMPLETE = 33052;

package/dist/types/rop/TaskTarget.d.ts

@@ -0,0 +1,24 @@
+import type { RepoUtils } from "@rapidrest/service-core";
+import type { RepoSort } from "./RepoPaging.js";
+/**
+ * The `RopGetContentsTable`/`RopOpenMessage` analog of `MessageTarget.ts`, for a `Folder` of type `TASKS`:
+ * resolves a `"task:<uid>"` row/handle target into the display data a task-item row or an opened task's
+ * properties need. A `Task` is addressed by MID exactly the same way a `Message`/`CalendarEvent`/`Contact` is -
+ * `MessageTarget.assignOrGetMid`/`session.messageIds` are reused as-is, so this file adds no MID-registry code
+ * of its own.
+ *
+ * Read-only in this pragmatic subset - a client checking off a task (`RopSetProperties`/`RopSaveChangesMessage`
+ * against a `"task:"` handle) is a documented gap, same as Contacts (see `ContactTarget.ts`'s own note); the
+ * REST API's own `PUT`/`PATCH` `/tasks/:id` remains the way to mutate a `Task` today.
+ */
+export interface TaskTargetInfo {
+    title: string;
+    completed: boolean;
+    dueDate?: Date;
+}
+/** Degrades to empty-looking values for a `"task:<uid>"` target whose real `Task` has since vanished
+ * (soft-deleted or otherwise) - the same "don't fail the whole ROP over one stale row" principle
+ * `MessageTarget.resolveMessageInfo`/`ContactTarget.resolveContactInfo` already apply. */
+export declare function resolveTaskInfo(target: string, taskRepo: RepoUtils<any>): Promise<TaskTargetInfo>;
+/** The order a `TASKS` folder's contents table lists tasks in (see `ContentsTable.ts`). */
+export declare const TASK_SORT: RepoSort;

package/dist/types/rop/TransportSend.d.ts

@@ -0,0 +1,10 @@
+import type { MailTransport, OutboundMessage, TransportResult } from "@rapidmx/restapi";
+/**
+ * Sends `message` and throws unless the transport accepted it for at least one recipient and rejected none.
+ *
+ * The same rule as restapi's own `sendOrThrow()` (`transport/TransportResultUtils.ts`), which isn't exported from
+ * the `@rapidmx/restapi` package root, so it can't be imported here; keep the two in sync. Every bundled transport
+ * reports a failed relay through `TransportResult.rejected` rather than throwing, so a bare `send()` would treat a
+ * rejected message as sent.
+ */
+export declare function sendOrThrow(transport: MailTransport, message: OutboundMessage): Promise<TransportResult>;

package/dist/types/sql/MapiEmsmdbRouteSQL.d.ts

@@ -0,0 +1,20 @@
+import { MailboxSQL } from "@rapidmx/restapi/sql";
+import { BaseMapiEmsmdbRoute } from "../BaseMapiEmsmdbRoute.js";
+/**
+ * SQL-backed concrete `BaseMapiEmsmdbRoute`, mounted at `/mapi/emsmdb`. Exported from this plugin's
+ * `./sql` entry point, so the server host mounts it without a wrapper class of its
+ * own.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class MapiEmsmdbRouteSQL extends BaseMapiEmsmdbRoute<MailboxSQL> {
+    protected mailboxClass: any;
+    protected folderClass: any;
+    protected messageClass: any;
+    protected calendarEventClass: any;
+    protected contactClass: any;
+    protected taskClass: any;
+    protected labelClass: any;
+    protected auditLogClass: any;
+    protected ropHandlerClasses: any[];
+}

package/dist/types/sql/MapiNspiRouteSQL.d.ts

@@ -0,0 +1,13 @@
+import { MailboxSQL } from "@rapidmx/restapi/sql";
+import { BaseMapiNspiRoute } from "../BaseMapiNspiRoute.js";
+/**
+ * SQL-backed concrete `BaseMapiNspiRoute`, mounted at `/mapi/nspi`. Exported from this plugin's
+ * `./sql` entry point, so the server host mounts it without a wrapper class of its
+ * own.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class MapiNspiRouteSQL extends BaseMapiNspiRoute<MailboxSQL> {
+    protected mailboxClass: any;
+    protected contactClass: any;
+}

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

@@ -0,0 +1,2 @@
+export * from "./MapiEmsmdbRouteSQL.js";
+export * from "./MapiNspiRouteSQL.js";

package/dist/types/sql.d.ts

@@ -0,0 +1 @@
+export * from "./sql/index.js";

package/package.json

@@ -0,0 +1,104 @@
+{
+    "name": "@rapidmx/mapi-plugin",
+    "version": "1.0.0-beta.10",
+    "description": "A RapidMX plugin that provides MAPI over HTTP protocol support.",
+    "repository": "https://github.com/rapidmx/mapi-plugin.git",
+    "author": "RapidREST <rapidrests@gmail.com>",
+    "license": "MPL-2.0",
+    "contributors": [
+        "Jean-Philippe Steinmetz"
+    ],
+    "scripts": {
+        "build": "yarn lint && rimraf dist && tsc",
+        "lint": "eslint ./src ./test",
+        "local-audit": "yarn install && yarn npm audit -A -R \"$@\"",
+        "checkup": "yarn dlx @yarnpkg/doctor \"$@\"",
+        "dependency-check": "yarn dlx depcheck \"$@\"",
+        "report-coverage": "cat ./coverage/lcov.info | coveralls",
+        "test": "vitest run",
+        "test:prod": "npm run lint && vitest run --coverage",
+        "test:watch": "vitest",
+        "release": "npx @rapidrest/cli release",
+        "prepublish": "yarn build"
+    },
+    "peerDependencies": {
+        "@rapidmx/restapi": "0.x",
+        "@rapidrest/core": "5.x",
+        "@rapidrest/service-core": "2.x"
+    },
+    "dependencies": {
+        "mailparser": "^3.9.23",
+        "nodemailer": "^10.0.1"
+    },
+    "devDependencies": {
+        "@rapidmx/restapi": "^0.22.1",
+        "@rapidrest/core": "^6.0.0",
+        "@rapidrest/service-core": "^2.3.0",
+        "@swc/core": "^1.16.2",
+        "@types/mailparser": "^3.4.6",
+        "@types/nconf": "^0.10.7",
+        "@types/node": "^26.5.0",
+        "@types/nodemailer": "^8.0.1",
+        "@typescript-eslint/eslint-plugin": "^8.70.0",
+        "@typescript-eslint/parser": "^8.70.0",
+        "@vitest/coverage-v8": "^5.0.0",
+        "better-sqlite3": "^13.0.3",
+        "eslint": "^10.10.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-import": "^2.32.0",
+        "eslint-plugin-jsdoc": "^64.3.6",
+        "globals": "^17.12.0",
+        "lodash-es": "^4.18.1",
+        "mongodb": "^7.6.0",
+        "mongodb-memory-server": "^11.2.0",
+        "nconf": "^0.13.0",
+        "openapi3-ts": "^4.6.1",
+        "prom-client": "^15.1.3",
+        "redis": "^6.2.1",
+        "reflect-metadata": "^0.2.2",
+        "rimraf": "^6.1.3",
+        "ts-node": "^10.9.2",
+        "tsx": "^4.23.13",
+        "typeorm": "^1.1.1",
+        "typescript": "^6.0.3",
+        "unplugin-swc": "^1.6.0",
+        "vite": "^8.2.2",
+        "vitest": "^5.0.0",
+        "winston": "^3.19.0"
+    },
+    "packageManager": "yarn@4.5.3",
+    "engines": {
+        "node": ">=24.0.0"
+    },
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org/"
+    },
+    "type": "module",
+    "main": "dist/lib/index.js",
+    "exports": {
+        ".": {
+            "import": "./dist/lib/index.js",
+            "types": "./dist/types/index.d.ts"
+        },
+        "./mongo": {
+            "import": "./dist/lib/mongo.js",
+            "types": "./dist/types/mongo.d.ts"
+        },
+        "./sql": {
+            "import": "./dist/lib/sql.js",
+            "types": "./dist/types/sql.d.ts"
+        }
+    },
+    "typings": "dist/types/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "rapidmx": {
+        "plugin": {
+            "apiVersion": 1,
+            "displayName": "MAPI over HTTP",
+            "description": "Lets Outlook for Windows connect with the MAPI/HTTP protocol (served at /mapi/emsmdb and /mapi/nspi).",
+            "settings": []
+        }
+    }
+}