@rapidmx/mapi-plugin 1.0.0-beta.3

package/dist/types/mongo/MapiNspiRouteMongo.d.ts

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

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

@@ -0,0 +1,2 @@
+export * from "./MapiEmsmdbRouteMongo.js";
+export * from "./MapiNspiRouteMongo.js";

package/dist/types/mongo.d.ts

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

package/dist/types/nspi/NspiBindHandler.d.ts

@@ -0,0 +1,22 @@
+import type { JWTUser } from "@rapidrest/core";
+import type { HttpResponse, RepoUtils } from "@rapidrest/service-core";
+/**
+ * `Bind`/`Unbind` request types (`[MS-OXCMAPIHTTP]` §2.2.5.1/§2.2.5.2, backed by `[MS-OXNSPI]`'s own `NspiBind`/
+ * `NspiUnbind` methods): establishes/tears down an NSPI Session Context, the address-book endpoint's own
+ * analog of EMSMDB's `Connect`/`Disconnect`.
+ *
+ * **No real session state is created or tracked** - a deliberate, documented simplification, not an oversight:
+ * every subsequent NSPI operation in this pragmatic subset (`GetMatches`) is independently `@Auth(["jwt"])`-
+ * protected and re-resolves the caller's own mailbox from that same JWT, exactly the way `RopLogon`/every ROP
+ * handler already does for EMSMDB - the real spec's `MapiContext`-equivalent session cookie exists mainly for
+ * multi-server-farm request affinity, not additional authentication, so this pragmatic subset mints an opaque,
+ * unvalidated cookie value purely for wire-format conformance and never checks it again. `HasState`/`State`
+ * (an optional `STAT` scoping the bind to one address-book container) is accepted but not decoded at all -
+ * this pragmatic subset has exactly one "container" (a mailbox's own `Contact` list) regardless.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare function handleNspiBind(res: HttpResponse, user: JWTUser, mailboxRepo: RepoUtils<any>): Promise<void>;
+/** `Unbind` never fails and has nothing to tear down - see `handleNspiBind`'s own doc comment for why no real
+ * session exists to release. */
+export declare function handleNspiUnbind(res: HttpResponse): void;

package/dist/types/nspi/NspiCodec.d.ts

@@ -0,0 +1,59 @@
+import { BufferReader, BufferWriter } from "../codec/BufferCursor.js";
+import { type PropertyTag, type PropertyValueData } from "../codec/PropertyValue.js";
+/**
+ * Shared wire-format helpers for the NSPI-over-HTTP address-book endpoint (`[MS-OXCMAPIHTTP]` §2.2.5,
+ * `[MS-OXNSPI]`) - a genuinely different transport shape from EMSMDB's ROP buffers: each `X-RequestType` value
+ * (`Bind`/`Unbind`/`GetMatches`/...) has its own flat request/response body, not a multiplexed ROP stream, so
+ * there is no generic framing codec to share the way `RopBuffer.ts` does for EMSMDB - just these small
+ * structures every NSPI operation body embeds.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+/** `STAT` (`[MS-OXNSPI]` §2.2.8, confirmed this session): 9 `DWORD`-sized fields (36 bytes total, `Delta`
+ * signed, every other field unsigned) describing an address-book container's paging/locale state. This
+ * pragmatic subset never persists a `STAT` across calls (see `NspiGetMatchesHandler.ts`'s own doc comment for
+ * why) - `readStat`/`writeStat` exist purely to keep the surrounding request/response body's own field
+ * offsets correct, not to drive any real positioning logic. */
+export interface Stat {
+    sortType: number;
+    containerId: number;
+    currentRec: number;
+    delta: number;
+    numPos: number;
+    totalRecs: number;
+    codePage: number;
+    templateLocale: number;
+    sortLocale: number;
+}
+export declare function readStat(reader: BufferReader): Stat;
+export declare function writeStat(writer: BufferWriter, stat: Stat): void;
+/** A blank `STAT` (`SortType`/`ContainerID`/... all zero) - what this pragmatic subset always echoes back
+ * (in `Bind`'s optional acknowledgement and `GetMatches`' response) regardless of the caller's own request
+ * `STAT`, since no real per-container/locale state is tracked. */
+export declare const BLANK_STAT: Stat;
+/** `LargePropertyTagArray` (`[MS-OXCMAPIHTTP]` §2.2.1.8): a 4-byte count followed by that many `PropertyTag`
+ * structures (`[MS-OXCDATA]` §2.9 - the same `PropertyType`-then-`PropertyId` encoding `PropertyValue.ts`'s own
+ * `readPropertyTag`/`writePropertyTag` already implement). */
+export declare function readLargePropertyTagArray(reader: BufferReader): PropertyTag[];
+export declare function writeLargePropertyTagArray(writer: BufferWriter, tags: PropertyTag[]): void;
+/** Writes one `AddressBookPropertyRow` (`[MS-OXCMAPIHTTP]` §2.2.1.7) - always `Flags=0x00` (every column
+ * value present without error), the exact `StandardPropertyRow`-equivalent choice `RopQueryRowsHandler`/
+ * `RopGetPropertiesSpecificHandler` already make for EMSMDB's own row encoding. */
+export declare function writeAddressBookPropertyRow(writer: BufferWriter, columns: PropertyTag[], values: PropertyValueData[]): void;
+/** Decodes a `Restriction` (`[MS-OXCDATA]` §2.12)'s leading `RestrictType` byte and, only for a
+ * `ContentRestriction`/`RES_CONTENT` (`0x03`) - the shape a real client's own GAL "search as you type" sends -
+ * extracts the plain string search term from its `TaggedValue` field.
+ *
+ * **Throws for any other restriction type** (`AND`/`OR`/`PropertyRestriction`/...) rather than degrading
+ * gracefully - unlike this pragmatic subset's usual "return a default instead of failing" stance elsewhere,
+ * a restriction's own byte length is type-dependent (12 different packet formats, several recursively nested),
+ * so once an unrecognized `RestrictType` is seen there is no safe way to know how many bytes to skip to reach
+ * the request body's own subsequent fields (`RowCount`/`Columns`/...) - silently returning `undefined` here
+ * would leave the reader mid-structure and corrupt every field decoded afterward. Throwing is the honest,
+ * safe choice for an input this narrow codec was never meant to parse, not a design gap.
+ *
+ * `FuzzyLevelLow`/`FuzzyLevelHigh` (exact/substring/prefix matching, case sensitivity) and the restriction's
+ * own target `PropertyTag` are decoded to advance the reader correctly but not honored - this pragmatic
+ * subset always does a case-insensitive substring match against its own fixed Contact field set regardless of
+ * which property or fuzzy level the client's restriction actually named. */
+export declare function extractContentRestrictionSearchTerm(reader: BufferReader): string;

package/dist/types/nspi/NspiGetMatchesHandler.d.ts

@@ -0,0 +1,24 @@
+import type { HttpRequest, HttpResponse, RepoUtils } from "@rapidrest/service-core";
+/**
+ * `GetMatches` request type (`[MS-OXCMAPIHTTP]` §2.2.5.5, backed by `[MS-OXNSPI]`'s own `NspiGetMatches`
+ * method): searches the GAL (this library's `Contact` records, the same source of truth EAS's own `Search`
+ * command already uses) for entries matching the client's restriction, returning up to `RowCount` matches as
+ * `AddressBookPropertyRow`s. This is the real operation behind a client's own address-book "search as you
+ * type" UI - the closest real NSPI equivalent to this plan's own "minimal prefix/substring lookups" scope.
+ *
+ * `HasState`/`State` (an input `STAT` scoping the search and reporting position) and `HasMinimalIds`/
+ * `MinimalIds` (an "Explicit Table" restricting the search to a caller-supplied candidate set) are decoded to
+ * advance the reader correctly but not honored - this pragmatic subset always searches the caller's entire
+ * Contact list fresh on every call (no real per-container/table state, see `NspiBindHandler.ts`'s own doc
+ * comment for the same reasoning applied to `Bind`). `HasFilter`'s `Filter` is decoded via
+ * `NspiCodec.extractContentRestrictionSearchTerm` - see that function's own doc comment for why an
+ * unsupported restriction type throws rather than degrading. `HasPropertyName` (an alternate open-by-named-
+ * property addressing mode) is decoded to advance the reader correctly but never itself used to select a
+ * search field.
+ *
+ * The response's own `State` is always `BLANK_STAT` (with `TotalRecs` set to the real match count) - no real
+ * per-container `STAT` is tracked, matching this pragmatic subset's stated scope.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare function handleNspiGetMatches(req: HttpRequest, res: HttpResponse, mailboxUid: string, contactRepo: RepoUtils<any>): Promise<void>;

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

@@ -0,0 +1,29 @@
+import type { RepoUtils } from "@rapidrest/service-core";
+import { Attendee, BusyStatus, RecurrenceRule } from "@rapidmx/restapi";
+/**
+ * The `RopGetContentsTable`/`RopOpenMessage` analog of `MessageTarget.ts`, for a `Folder` of type `CALENDAR`:
+ * resolves a `"calendarEvent:<uid>"` row/handle target into the display data a calendar-item row or an opened
+ * appointment's properties need. A `CalendarEvent` is addressed by MID exactly the same way a `Message` is -
+ * `MessageTarget.assignOrGetMid`/`session.messageIds` are reused as-is (see that file's own doc comment; the
+ * mechanism is already generic over the target-string prefix, not message-specific despite its file location),
+ * so this file adds no MID-registry code of its own.
+ */
+export interface CalendarEventTargetInfo {
+    title: string;
+    location?: string;
+    startDate: Date;
+    endDate: Date;
+    timezone: string;
+    busyStatus: BusyStatus;
+    recurrenceRule?: RecurrenceRule;
+    reminderMinutesBeforeStart?: number;
+    organizerAddress: string;
+    attendees: Attendee[];
+}
+/** Degrades to empty-looking values for a `"calendarEvent:<uid>"` target whose real `CalendarEvent` has since
+ * vanished (soft-deleted or otherwise) - the same "don't fail the whole ROP over one stale row" principle
+ * `MessageTarget.resolveMessageInfo`/`FolderTarget.resolveFolderInfo` already apply. */
+export declare function resolveCalendarEventInfo(target: string, calendarEventRepo: RepoUtils<any>): Promise<CalendarEventTargetInfo>;
+/** Resolves the calendar events directly in `folderUid`, as `"calendarEvent:<uid>"` target strings, for
+ * `RopGetContentsTable` against a `CALENDAR`-type folder. */
+export declare function resolveFolderCalendarEvents(folderUid: string, calendarEventRepo: RepoUtils<any>): Promise<string[]>;

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

@@ -0,0 +1,37 @@
+import { AttendeeResponseStatus, BusyStatus } from "@rapidmx/restapi";
+/**
+ * The Calendar named-property identity table (`(PropertySet GUID, LID)` pairs) this pragmatic subset supports,
+ * per `[MS-OXPROPS]` - each pinned against its own MS-OXPROPS page (not invented), shared by `PropertyResolvers.ts`
+ * (the read side: `calendarEventValueFor`) and `RopSaveChangesMessageHandler.ts` (the write side: decoding a
+ * draft's accumulated `RopSetProperties` values back into a real `CalendarEvent`) so both directions of this
+ * mapping stay in exactly one place. See the architecture plan's "Calendar support" section for the full table.
+ */
+export declare const PSETID_APPOINTMENT = "00062002-0000-0000-c000-000000000046";
+export declare const PSETID_COMMON = "00062008-0000-0000-c000-000000000046";
+export declare const PSETID_MEETING = "6ed8da90-450b-101b-98da-00aa003f1305";
+export declare const LID_LOCATION = 33288;
+export declare const LID_APPOINTMENT_START_WHOLE = 33293;
+export declare const LID_APPOINTMENT_END_WHOLE = 33294;
+export declare const LID_BUSY_STATUS = 33285;
+export declare const LID_RECURRING = 33315;
+export declare const LID_REMINDER_SET = 34051;
+export declare const LID_REMINDER_DELTA = 34049;
+export declare const LID_RESPONSE_STATUS = 33304;
+export declare const LID_APPOINTMENT_RECUR = 33302;
+export declare const LID_TIME_ZONE_STRUCT = 33331;
+/** `PidLidGlobalObjectId` (`PSETID_Meeting`) - see `GlobalObjectId.ts` for the BLOB it carries and
+ * `MeetingMessageClassHandler.ts` for how a meeting response's own copy of it is correlated back to the
+ * original `CalendarEvent`. */
+export declare const LID_GLOBAL_OBJECT_ID = 3;
+/** `PidLidBusyStatus`'s wire values (`[MS-OXOCAL]` §2.2.1.2, confirmed this session) - a different numbering
+ * than `CalendarSyncAdapter`'s own `BUSY_STATUS_CODES` table for the unrelated MS-ASCAL `BusyStatus` field.
+ * `olWorkingElsewhere` (0x00000004) has no equivalent in this library's own `BusyStatus` enum - never produced,
+ * and decoded (via `BUSY_STATUS_FROM_CODE`) with a fallback to `BUSY`, a documented, harmless approximation. */
+export declare const BUSY_STATUS_CODES: Record<BusyStatus, number>;
+export declare const BUSY_STATUS_FROM_CODE: Record<number, BusyStatus>;
+/** `PidLidResponseStatus`'s wire values (`[MS-OXOCAL]` §2.2.1.11, confirmed this session) for the caller's own
+ * attendee record. `respOrganized` (0x00000001) is returned when the caller *is* the organizer - not a value
+ * `AttendeeResponseStatus` itself has a case for, since that enum only models an attendee's own response. */
+export declare const RESPONSE_STATUS_CODES: Record<AttendeeResponseStatus, number>;
+export declare const RESPONSE_STATUS_ORGANIZED = 1;
+export declare const RESPONSE_STATUS_NONE = 0;

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

@@ -0,0 +1,29 @@
+import type { RepoUtils } from "@rapidrest/service-core";
+/**
+ * The `RopGetContentsTable`/`RopOpenMessage` analog of `MessageTarget.ts`, for a `Folder` of type `CONTACTS`:
+ * resolves a `"contact:<uid>"` row/handle target into the display data a contact-item row or an opened
+ * address-card's properties need. A `Contact` is addressed by MID exactly the same way a `Message`/
+ * `CalendarEvent` is - `MessageTarget.assignOrGetMid`/`session.messageIds` are reused as-is (see that file's own
+ * doc comment), so this file adds no MID-registry code of its own.
+ *
+ * Read-only in this pragmatic subset - a client editing/creating a Contact via MAPI (`RopSetProperties`/
+ * `RopSaveChangesMessage` against a `"contact:"` handle) is a documented gap, the same "browse only" limitation
+ * this codebase already accepts for Tasks (`TaskTarget.ts`); NSPI's own `Bind`/`Unbind`/`GetMatches` already
+ * covers the "search the GAL" case this data also backs.
+ */
+export interface ContactTargetInfo {
+    displayName: string;
+    givenName?: string;
+    surname?: string;
+    email?: string;
+    businessPhone?: string;
+    companyName?: string;
+    jobTitle?: string;
+}
+/** Degrades to empty-looking values for a `"contact:<uid>"` target whose real `Contact` has since vanished
+ * (soft-deleted or otherwise) - the same "don't fail the whole ROP over one stale row" principle
+ * `MessageTarget.resolveMessageInfo`/`CalendarEventTarget.resolveCalendarEventInfo` already apply. */
+export declare function resolveContactInfo(target: string, contactRepo: RepoUtils<any>): Promise<ContactTargetInfo>;
+/** Resolves the contacts directly in `folderUid`, as `"contact:<uid>"` target strings, for
+ * `RopGetContentsTable` against a `CONTACTS`-type folder. */
+export declare function resolveFolderContacts(folderUid: string, contactRepo: RepoUtils<any>): Promise<string[]>;

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

@@ -0,0 +1,18 @@
+import { PropertyType } from "../codec/PropertyValue.js";
+import type { MapiObjectHandle } from "../MapiSessionManager.js";
+import type { RopContext } from "./RopHandler.js";
+interface PropertyColumn {
+    propertyId: number;
+    propertyType: PropertyType;
+}
+/**
+ * Builds the complete FastTransfer stream for `handle` (a `"folder"` or `"message"` Server object). `columns`,
+ * when given (a `RopFastTransferSourceCopyProperties` explicit include list), replaces every default column set
+ * uniformly at both folder- and message-level; `excludePropertyIds` (a `RopFastTransferSourceCopyTo` exclude
+ * list) is only ever applied to this pragmatic subset's own default columns, per the same reasoning.
+ */
+export declare function buildFastTransferStream(handle: MapiObjectHandle, context: RopContext, options?: {
+    columns?: PropertyColumn[];
+    excludePropertyIds?: ReadonlySet<number>;
+}): Promise<Buffer>;
+export {};

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

@@ -0,0 +1,63 @@
+import type { RepoUtils } from "@rapidrest/service-core";
+import { Folder } from "@rapidmx/restapi";
+import type { MapiSessionContext } from "../MapiSessionManager.js";
+export interface FolderTargetInfo {
+    displayName: string;
+    unreadCount: number;
+    totalCount: number;
+    hasChildren: boolean;
+}
+/** An optional, purely request-scoped (never persisted to the session) memo for `resolveFolderChildren`'s own
+ * full-mailbox `folderRepo.find({ mailboxUid })` fetch - see that function's own doc comment for why this
+ * matters. Deliberately just a plain object a caller creates fresh per ROP-handler invocation and threads
+ * through every `resolveFolderInfo`/`resolvePropertyValues` call in that same batch, not session state - unlike
+ * the FID/MID/named-property registries, there's no cross-request reuse to gain here (a mailbox's folder list
+ * can change between requests), only cross-*row* reuse within one table page. */
+export interface FolderResolutionCache {
+    allFolders?: Folder[];
+}
+/** Resolves a target string into the display data a folder-table row needs. A `"folder:<uid>"` target whose
+ * `Folder` has since been deleted (soft-deleted or otherwise vanished) degrades to empty-looking values rather
+ * than throwing - the row simply won't be interesting to a client, not a reason to fail the whole ROP. */
+export declare function resolveFolderInfo(mailboxUid: string, target: string, folderRepo: RepoUtils<any>, cache?: FolderResolutionCache): Promise<FolderTargetInfo>;
+/**
+ * Resolves the direct children of `target`, as an array of the same target-string format, for
+ * `RopGetHierarchyTable`. Only `"virtual:root"`/`"virtual:ipmSubtree"` (this mailbox's top-level real
+ * folders - both collapse to the same "top of the visible tree" concept in this pragmatic subset, see
+ * `RopLogonHandler`'s own doc comment) and a real folder (its own real children) have any children at all;
+ * every other virtual folder (Deferred Action, Spooler Queue, ...) is permanently empty, since this data
+ * model has no concept of nesting anything under them.
+ *
+ * Filters an already-fetched full folder list in application code rather than querying by
+ * `parentFolderUid: undefined` directly - query-DSL semantics for "field is unset" aren't reliably consistent
+ * across backends (the exact kind of gap this project's own testing philosophy has caught before, e.g. `$or`
+ * being Mongo-only), so filtering a fetched array sidesteps the question entirely rather than risking it.
+ * The comparison itself uses `== null` (matching both `null` and `undefined`), not `=== undefined` - a
+ * top-level folder's unset `parentFolderUid` round-trips as genuine `undefined` from Mongo but as `null` from
+ * a SQL `nullable` column, a real, previously-confirmed cross-backend discrepancy in this codebase (caught by
+ * this exact test against a real SQLite-backed server, not assumed).
+ *
+ * **`cache`**: without it, this fetches every folder in the mailbox on every call - fine for the single call
+ * `RopGetHierarchyTableHandler` makes to build a table, but `resolveFolderInfo` also calls this once per row
+ * just to compute `hasChildren`, and a table page can hold many rows. A caller resolving a whole page (
+ * `RopQueryRowsHandler`/`RopGetPropertiesSpecificHandler`) passes one shared cache object through every call in
+ * that batch so the full list is fetched at most once per batch instead of once per row - see
+ * `FolderResolutionCache`'s own doc comment for why this isn't session state.
+ */
+export declare function resolveFolderChildren(mailboxUid: string, target: string, folderRepo: RepoUtils<any>, cache?: FolderResolutionCache): Promise<string[]>;
+/**
+ * Returns `target`'s existing FID if `RopLogon` or an earlier `RopGetHierarchyTable` row already assigned
+ * one, otherwise assigns and remembers the next free small integer FID. This is what lets a client
+ * `RopOpenFolder` a child folder it only ever learned about via a `RopQueryRows` row's `PidTagFolderId`
+ * column - without this, only the 13 `RopLogon`-time special folders could ever be opened.
+ *
+ * Backed by `session.folderTargetIds` (target -> FID) and `session.nextFolderId`, an O(1) reverse index/counter
+ * pair rather than a linear scan of `session.folderIds` plus a `Math.max(...spread)` over its keys - both real
+ * costs, not just theoretical ones: `folderTargetIds` only ever grows for a session's lifetime as a client
+ * browses more of a mailbox's folder tree, so the old scan-per-lookup approach was quadratic across a session
+ * that opens many folders, and `Math.max` spreading an unbounded array as call arguments risked a stack
+ * overflow past V8's argument-count limit on a mailbox with enough folders. `RopLogonHandler` keeps
+ * `folderTargetIds`/`nextFolderId` in sync with `folderIds` for the 13 special folders it assigns directly,
+ * rather than going through this function, since it assigns all 13 as one batch up front.
+ */
+export declare function assignOrGetFid(session: MapiSessionContext, target: string): number;

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

@@ -0,0 +1,36 @@
+import type { RopContext } from "./RopHandler.js";
+/**
+ * Handles a submitted `"IPM.Schedule.Meeting.Resp.{Pos,Neg,Tent}"` message - an attendee's own response to a
+ * meeting invite this server previously sent (`RopSubmitMessageHandler.submitAppointment`). Delegated to from
+ * `RopSubmitMessageHandler` for that message-class prefix, instead of the ordinary mail or Appointment paths.
+ *
+ * Correlates the response back to the original `CalendarEvent` via `PidLidGlobalObjectId` (echoed by a real
+ * client from the invite it's responding to - see `GlobalObjectId.ts`'s own doc comment for why this requires
+ * no separate correlation table) and updates the caller's own `Attendee.responseStatus` in place, reusing the
+ * exact same matching-by-mailbox-address logic `MeetingResponseCommand` (EAS's own `MeetingResponse` handler)
+ * already implements - this is a from-scratch reimplementation of that small algorithm rather than a
+ * cross-import, since EAS and MAPI are independent protocol verticals in this codebase with no dependency
+ * between them.
+ *
+ * Every failure mode here (no `PidLidGlobalObjectId` set, no matching `CalendarEvent`, no resolvable mailbox,
+ * caller isn't actually an attendee, unrecognized message-class suffix) is a silent no-op rather than an error
+ * response - the same "don't fail the whole ROP over a stale/unresolvable reference" principle this pragmatic
+ * subset applies throughout (e.g. `MessageTarget.resolveMessageInfo`'s own doc comment). A response that can't
+ * be correlated or applied is simply dropped, not a reason to reject the client's `RopSubmitMessage` call.
+ *
+ * **The one query in this package that isn't `mailboxUid`-scoped, and why that's unavoidable here**: unlike
+ * every other `ignoreACL: true` repo call in this codebase (all transitively scoped to the caller's own
+ * mailbox via a session FID/MID registry that itself only ever gets populated from mailbox-scoped queries),
+ * `calendarEventRepo.find({ icalUid })` below deliberately searches *every* mailbox on this server - the
+ * `CalendarEvent` being responded to belongs to the meeting's *organizer*, who is very often a different
+ * mailbox than the attendee submitting this response, and the caller's own session has no way to know which
+ * mailbox that is. Safety instead comes from two independent properties: `icalUid` is a server-generated
+ * `crypto.randomUUID()` (see `RopSaveChangesMessageHandler.saveAppointment`), for all practical purposes
+ * globally unique, so this can't be used to enumerate or collide with another organizer's events; and the
+ * actual authorization gate is the attendee-membership check a few lines down (`callerAddresses.has(...)`),
+ * derived entirely from *this* caller's own resolved mailbox record, not from anything the client supplied -
+ * a crafted `PidLidGlobalObjectId` can at best name a real `icalUid` it doesn't already know the value of
+ * (astronomically unlikely against a random UUID) and still can't mutate an event unless the caller's own
+ * mailbox is genuinely a listed attendee on it.
+ */
+export declare function submitMeetingResponse(messageClass: string, draftProperties: Record<string, string>, context: RopContext): Promise<void>;

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

@@ -0,0 +1,26 @@
+import type { RepoUtils } from "@rapidrest/service-core";
+import { type BlobStore } from "@rapidmx/restapi";
+/** `PidTagBody` (`[MS-OXPROPS]`): property ID `0x1000`, `PtypString`. The only streamable property this
+ * pragmatic subset supports via `RopOpenStream`/`RopReadStream` - `PidTagHtml`/`PidTagRtfCompressed` are a
+ * documented gap (see `RopOpenStreamHandler`'s own doc comment). */
+export declare const PID_TAG_BODY = 4096;
+/**
+ * Resolves a `"message:<uid>"` target's plain-text body as the exact byte sequence `RopReadStream` must serve
+ * for a streamed `PtypString` property - confirmed via `[MS-OXCPRPT]`'s `RopOpenStream` page ("a string of
+ * Unicode characters in UTF-16LE format encoding with terminating null character"), the identical encoding
+ * `writePropertyValue()` already uses for an inline `PtypString` value, so this reuses
+ * `BufferWriter.writeNullTerminatedUtf16LE` rather than reimplementing it.
+ *
+ * Always derived from the message's raw MIME source (`bodyBlobKey`, via `mailparser` - the same fallback path
+ * `ItemOperationsCommand.fetchMessage()` already uses for EAS's own plain-text body delivery) rather than
+ * `sanitizedHtmlBlobKey` - `PidTagBody` is specifically the plain-text body per `[MS-OXPROPS]`, unlike EAS's
+ * `Body` element, which can carry either format tagged by its own `Type` field.
+ *
+ * Recomputed on every call rather than cached anywhere (including on the `"stream"` handle itself) -
+ * `MapiSessionContext` is serialized through `RedisCache`'s JSON round trip for multi-instance deployments, so
+ * a raw `Buffer` stored there wouldn't survive it (the same class of gap this codebase already documented for
+ * `Date` fields, see `MapiSessionContext`'s own doc comment). A documented, pragmatic trade-off: a large body
+ * read across several `RopReadStream` calls re-parses the MIME source each time rather than once - correct,
+ * not byte-perfect-efficient.
+ */
+export declare function resolveMessageBodyBytes(target: string, messageRepo: RepoUtils<any>, blobStore: BlobStore): Promise<Buffer>;

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

@@ -0,0 +1,38 @@
+import type { RepoUtils } from "@rapidrest/service-core";
+import type { MapiSessionContext } from "../MapiSessionManager.js";
+/**
+ * The `RopGetContentsTable` analog of `FolderTarget.ts`: resolves a `"message:<uid>"` row target (see
+ * `RopGetContentsTableHandler`'s own doc comment for why contents-table rows use this prefix instead of
+ * `FolderTarget.ts`'s `"folder:"`/`"virtual:"`) into the display data a message-table row needs.
+ */
+export interface MessageTargetInfo {
+    subject: string;
+    read: boolean;
+    hasAttachments: boolean;
+    receivedDate: Date;
+    /** `Label.uid`s applied to this message (Gmail-style, independent of folder placement) - resolved to
+     * display names for `PidNameKeywords` (Outlook Categories) by `PropertyResolvers.ts`, which is where the
+     * `labelRepo` needed to translate a uid into a name lives. */
+    labelUids: string[];
+}
+/** Degrades to empty-looking values for a `"message:<uid>"` target whose real `Message` has since vanished
+ * (soft-deleted or otherwise), the same "don't fail the whole ROP over one stale row" principle
+ * `FolderTarget.resolveFolderInfo` already applies. */
+export declare function resolveMessageInfo(target: string, messageRepo: RepoUtils<any>): Promise<MessageTargetInfo>;
+/** Resolves the messages directly in `folderUid`, as `"message:<uid>"` target strings, for
+ * `RopGetContentsTable`. */
+export declare function resolveFolderMessages(folderUid: string, messageRepo: RepoUtils<any>): Promise<string[]>;
+/**
+ * Returns `target`'s existing MID if an earlier `RopQueryRows` row already assigned one, otherwise assigns and
+ * remembers the next free small integer MID. The exact `FolderTarget.assignOrGetFid` pattern, adapted for
+ * messages: this is what lets a client `RopOpenMessage` a message it only ever learned about via a
+ * `RopQueryRows` row's `PidTagMid` column.
+ *
+ * Backed by `session.messageTargetIds` (target -> MID) and `session.nextMessageId`, an O(1) reverse index/
+ * counter pair rather than a linear scan of `session.messageIds` plus a `Math.max(...spread)` over its keys -
+ * see `FolderTarget.assignOrGetFid`'s own doc comment for why both of those were real costs (not just
+ * theoretical ones) at real mailbox/session scale: `messageIds` only ever grows for a session's lifetime as a
+ * client pages through a mailbox, so a linear-scan lookup repeated once per row is quadratic over a session
+ * that pages through many messages.
+ */
+export declare function assignOrGetMid(session: MapiSessionContext, target: string): number;

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

@@ -0,0 +1,46 @@
+import type { MapiSessionContext } from "../MapiSessionManager.js";
+/** A `PropertyName` (`[MS-OXCDATA]` §2.6.1): identifies a named property by a property-set `guid` plus either a
+ * numeric `lid` (`kind: "lid"`) or a string `name` (`kind: "name"`) - never both. `guid` is the textual form
+ * `MapiGuid.ts`'s `encodeGuid`/`decodeGuid` already produce/consume (the wire `PropertyName` structure's own
+ * `GUID` field is a `FlatUID` - confirmed, per its own spec page, to be byte-identical to the same little-endian
+ * `Data1`/`Data2`/`Data3`+as-is-`Data4` layout `MapiGuid.ts` already implements, so no second GUID codec is
+ * needed here). */
+export interface PropertyName {
+    guid: string;
+    kind: "lid" | "name";
+    lid?: number;
+    name?: string;
+}
+/**
+ * Returns `propertyName`'s existing numeric property ID if an earlier `RopGetPropertyIdsFromNames` call in
+ * this session already assigned one, otherwise assigns and remembers the next free ID starting at
+ * `FIRST_NAMED_PROPERTY_ID`. This pragmatic subset always behaves as if the request's own `Flags` field
+ * requested "assign a new ID if unmapped" (`0x02`) - real Exchange's alternative (`0x00`, "only return
+ * already-mapped IDs") exists to let a client probe without committing a mailbox-wide registration; since this
+ * registry is already only ever session-scoped (not a real persisted per-mailbox mapping table), there is no
+ * meaningful difference between "probe" and "assign" here.
+ *
+ * Backed by `session.namedProperties`/`namedPropertyIds` (a forward and reverse map, kept in sync) and
+ * `session.nextNamedPropertyId`, an O(1) lookup/assignment pair rather than a linear scan plus a
+ * `Math.max(...spread)` over `Object.values(session.namedProperties)` - both real costs at scale: the spread
+ * form risks a `RangeError: Maximum call stack size exceeded` once a session has registered enough distinct
+ * names to exceed V8's function-argument-count limit, and the registry only ever grows for a session's
+ * lifetime, so a linear scan repeated once per property per row is quadratic over a session that resolves many
+ * named properties.
+ *
+ * Once `nextNamedPropertyId` would exceed `LAST_NAMED_PROPERTY_ID` (32,768 distinct names already registered
+ * this session - the entire `0x8000`-`0xFFFF` numeric ID space this pragmatic subset has to hand out), a *new*
+ * name can no longer be assigned a real ID; this returns `0x0000` for it instead of throwing, the exact value
+ * `[MS-OXCPRPT]`'s own `RopGetPropertyIdsFromNames` processing rules already use for "this `PropertyName`
+ * could not be resolved" (the same value this pragmatic subset already produces for a `Kind = 0xFF` entry) -
+ * not a new failure mode, just the same one applied to a different unmappable case. A name already registered
+ * before the registry filled up keeps returning its real, previously-assigned ID.
+ */
+export declare function assignOrGetNamedPropertyId(session: MapiSessionContext, propertyName: PropertyName): number;
+/** The reverse lookup `RopSetProperties`/`RopGetPropertiesSpecific`/`RopQueryRows` use to recognize an incoming
+ * property ID `>= 0x8000` as one of this session's own mapped named properties - an O(1) lookup against
+ * `session.namedPropertyIds` (kept in sync by `assignOrGetNamedPropertyId`) rather than a linear scan of
+ * `session.namedProperties` with a `JSON.parse` per candidate - see that function's own doc comment for why
+ * this matters at scale, particularly since this is called once per named-property column per row from
+ * `RopQueryRows`. */
+export declare function resolveNamedProperty(session: MapiSessionContext, propertyId: number): PropertyName | undefined;

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

@@ -0,0 +1,60 @@
+import { PropertyType, PropertyValueData } from "../codec/PropertyValue.js";
+import type { MapiSessionContext } from "../MapiSessionManager.js";
+import { CalendarEventTargetInfo } from "./CalendarEventTarget.js";
+import { ContactTargetInfo } from "./ContactTarget.js";
+import { FolderResolutionCache, FolderTargetInfo } from "./FolderTarget.js";
+import { MessageTargetInfo } from "./MessageTarget.js";
+import type { RopContext } from "./RopHandler.js";
+import { TaskTargetInfo } from "./TaskTarget.js";
+/** A type-appropriate zero/empty value for a requested property this handler has no real data for - keeps
+ * `StandardPropertyRow` encoding valid (a real value of the right type, per `writePropertyValue`'s
+ * expectations) without needing to model every property a client could ever ask for. Shared by
+ * `RopQueryRowsHandler` (table rows) and `RopGetPropertiesSpecificHandler` (single-object property fetch). */
+export declare function defaultValueForType(propertyType: PropertyType): PropertyValueData;
+/** Resolves one requested property's value for a `"folder:<uid>"`/`"virtual:<name>"` target. */
+export declare function folderValueFor(session: MapiSessionContext, propertyId: number, propertyType: PropertyType, target: string, info: FolderTargetInfo): PropertyValueData;
+/** Resolves one requested property's value for a `"message:<uid>"` target. `labelNames` is this message's own
+ * `labelUids` already resolved to display names (see `resolvePropertyValues`'s own doc comment) - a plain
+ * parameter rather than a repo lookup here, since this function (like every other `xxxValueFor`) is
+ * synchronous and can't do its own async DB access. */
+export declare function messageValueFor(session: MapiSessionContext, propertyId: number, propertyType: PropertyType, target: string, info: MessageTargetInfo, labelNames?: string[]): PropertyValueData;
+/** Resolves one requested property's value for a `"calendarEvent:<uid>"` target. Almost every Appointment
+ * property is a *named* property (`PidLid*`, no fixed numeric ID) rather than a plain `PidTag*` - a property ID
+ * `>= 0x8000` is resolved back to its `(PropertySet GUID, LID)` identity via `resolveNamedProperty` before this
+ * can dispatch on it (see `NamedPropertyRegistry.ts`'s own doc comment and the architecture plan's "Calendar
+ * support" section for the full named-property table this switch implements). */
+export declare function calendarEventValueFor(session: MapiSessionContext, propertyId: number, propertyType: PropertyType, target: string, info: CalendarEventTargetInfo, callerAddress: string): PropertyValueData;
+/** Resolves one requested property's value for a `"contact:<uid>"` target - a `Folder` of type `CONTACTS`'s
+ * content-table rows/opened items. Every field here is a plain fixed `PidTag` (`[MS-OXOCNTC]`), unlike Calendar/
+ * Task's named-property tables, since Contact's own well-known fields all have real numeric IDs. */
+export declare function contactValueFor(session: MapiSessionContext, propertyId: number, propertyType: PropertyType, target: string, info: ContactTargetInfo): PropertyValueData;
+/** Resolves one requested property's value for a `"task:<uid>"` target - a `Folder` of type `TASKS`'s
+ * content-table rows/opened items. Almost every Task-specific property is a *named* property (`PidLid*`) under
+ * `PSETID_Task`, resolved back to its `(PropertySet GUID, LID)` identity via `resolveNamedProperty` exactly the
+ * same way `calendarEventValueFor` handles `PSETID_Appointment`/`PSETID_Common` - see `TaskNamedProperties.ts`'s
+ * own doc comment for the LID table this switch implements. */
+export declare function taskValueFor(session: MapiSessionContext, propertyId: number, propertyType: PropertyType, target: string, info: TaskTargetInfo): PropertyValueData;
+/** An optional, purely request-scoped (never persisted) memo shared across every `resolvePropertyValues` call
+ * within one ROP handler invocation - e.g. one `RopQueryRows` call resolving many table rows, or the (rarer)
+ * case of `RopGetPropertiesSpecific` resolving many columns for one object. Without it, both `allFolders` (via
+ * `resolveFolderInfo`'s own `hasChildren` computation) and `callerAddress` (the calendar organizer/attendee
+ * lookup below) would be re-fetched from the repo on every single row even though they can only ever have one
+ * value for the whole batch (this mailbox's folder list, this mailbox's own primary address) - a real,
+ * measurable cost for a hierarchy/calendar table with many rows, not just a theoretical one. A caller that
+ * resolves only a single target (`RopGetPropertiesSpecificHandler`) can simply omit this - resolving without a
+ * cache is still correct, just not deduplicated across calls it doesn't make anyway. */
+export interface ResolutionCache extends FolderResolutionCache {
+    callerAddress?: string;
+    /** `Label.uid` -> `Label.name`, for the whole mailbox - built at most once per call the same way
+     * `allFolders`/`callerAddress` are, the first time a message row actually has a non-empty `labelUids` to
+     * resolve (most messages have none, so this stays unbuilt for a page with no labeled messages at all). */
+    labelNamesByUid?: Map<string, string>;
+}
+/** Resolves every column in `columns` for a single `target` (a `"folder:"`/`"virtual:"`/`"message:"`/
+ * `"calendarEvent:"`/`"contact:"`/`"task:"` target string), in order - the shared implementation behind both
+ * `RopQueryRowsHandler` (one call per table row) and `RopGetPropertiesSpecificHandler` (one call for the single
+ * object a handle refers to). */
+export declare function resolvePropertyValues(target: string, columns: {
+    propertyId: number;
+    propertyType: PropertyType;
+}[], context: Pick<RopContext, "mailboxUid" | "session" | "folderRepo" | "messageRepo" | "calendarEventRepo" | "mailboxRepo" | "contactRepo" | "taskRepo" | "labelRepo">, cache?: ResolutionCache): Promise<PropertyValueData[]>;

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

@@ -0,0 +1,23 @@
+import type { BufferReader, BufferWriter } from "../codec/BufferCursor.js";
+import type { RopContext, RopHandler } from "./RopHandler.js";
+/**
+ * `RopCreateMessage` (`[MS-OXCMSG]`/`[MS-OXCROPS]`): begins composing a new message in a folder, producing a
+ * new `"message"` Server object handle later ROPs (`RopSetProperties`, `RopOpenStream`, `RopSaveChangesMessage`)
+ * reference by `InputHandleIndex`. Unlike `RopOpenMessage`'s handle (an already-real, already-saved message),
+ * this handle's `entityUid` is deliberately left `""` - there is no real backing `Message` row, and won't be
+ * one until `RopSubmitMessage` actually sends it (this pragmatic subset has no separate Drafts-folder
+ * persistence step; see `RopSaveChangesMessageHandler`'s own doc comment). `draftFolderUid` remembers the
+ * target folder for that eventual send, and `draftProperties` starts empty, filled in by later
+ * `RopSetProperties`/`RopWriteStream` calls.
+ *
+ * `CodePageId` is decoded to advance past it correctly but not otherwise acted on (this pragmatic subset always
+ * encodes strings as UTF-16LE/UTF-8 directly, the same treatment `RopOpenMessageHandler` gives it).
+ * `AssociatedFlag` (FAI messages - hidden configuration/rules objects, not real mail) is decoded but not
+ * honored - this pragmatic subset's compose/send path only ever produces ordinary mail messages.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class RopCreateMessageHandler implements RopHandler {
+    readonly ropId = 6;
+    handle(reader: BufferReader, writer: BufferWriter, context: RopContext): void;
+}

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

@@ -0,0 +1,38 @@
+import type { BufferReader, BufferWriter } from "../codec/BufferCursor.js";
+import type { RopContext, RopHandler } from "./RopHandler.js";
+/**
+ * `RopDeleteFolder` (`[MS-OXCFOLD]`/`[MS-OXCROPS]`, RopId `0x1D`): deletes a folder by `FolderId`. Reuses
+ * `RecoverableRepoUtils.delete()` exactly as-built in Phase 2 for `Folder`/`Message`/`CalendarEvent` - see
+ * `RopDeleteMessagesHandler.ts`'s own doc comment for why that matters (EAS's watermark-based incremental
+ * delete detection depends on it).
+ *
+ * **Real spec semantics honored, not simplified away**: per `[MS-OXCFOLD]`, `RopDeleteFolder` only operates on
+ * an empty folder by default - `DEL_MESSAGES` must be set to also delete the folder's own messages/calendar
+ * events/contacts/tasks, and `DEL_FOLDERS` to also delete (recursively) its subfolders; a non-empty folder
+ * deleted without the matching flag fails rather than silently cascading. `DELETE_HARD_DELETE` maps directly
+ * onto `RepoDeleteOptions.purge` - real, exact semantic overlap with this library's own soft-delete model, not
+ * a coincidence this codec papers over.
+ *
+ * **Contacts/Tasks folders**: emptiness is checked against `contactRepo`/`taskRepo` alongside `messageRepo`/
+ * `calendarEventRepo`, and both are included in the delete cascade - a `CONTACTS`/`TASKS` folder's real content
+ * lives in those repos (see `ContactTarget.ts`/`TaskTarget.ts`), not `messageRepo`, so checking only the latter
+ * would let a non-empty Contacts/Tasks folder be deleted without `DEL_MESSAGES` and orphan its rows. Guarded
+ * with `context.contactRepo`/`taskRepo` presence checks the same way `RopGetContentsTableHandler` does, since
+ * `RopContext`'s doc comment documents both as optional.
+ *
+ * The request's own `InputHandleIndex` (nominally the *parent* folder of the one being deleted) is validated to
+ * be a real, open folder handle but not cross-checked against the target folder's actual `parentFolderUid` -
+ * the same pragmatic simplification `RopOpenMessageHandler`'s own doc comment documents for its analogous
+ * `FolderId` field.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class RopDeleteFolderHandler implements RopHandler {
+    readonly ropId = 29;
+    handle(reader: BufferReader, writer: BufferWriter, context: RopContext): Promise<void>;
+    /** Cascades a `DEL_FOLDERS` delete into `folderUid`'s own messages/calendar events/subfolders before
+     * deleting it - this data model's folder hierarchy is a plain parent-pointer tree (never a graph), so
+     * unbounded recursion here needs no cycle protection, the same assumption `FolderTarget.resolveFolderChildren`
+     * already makes. */
+    private deleteFolderRecursive;
+}