@rapidmx/mapi-plugin 1.0.0-beta.10

package/dist/types/codec/TypedString.d.ts

@@ -0,0 +1,17 @@
+import type { BufferReader, BufferWriter } from "./BufferCursor.js";
+/**
+ * `TypedString` (`[MS-OXCDATA]` §2.11.7): a leading `StringType` byte followed by an optional string in the
+ * format that byte names - used by `RopOpenMessage`'s success response (`SubjectPrefix`/`NormalizedSubject`).
+ * `writeTypedString` never produces the "reduced Unicode" (`0x03`) form - that's purely a wire-size
+ * optimization real Exchange applies when every character happens to fit in one byte, not something a peer is
+ * ever required to send, so this codec always writes plain UTF-16LE (`0x04`) for non-empty strings. `undefined`
+ * writes as "no string" (`0x00`), matching a field the spec allows to be entirely absent (e.g. no subject
+ * prefix at all, as opposed to an empty one).
+ */
+export declare function writeTypedString(writer: BufferWriter, value: string | undefined): void;
+/** Reads a `TypedString`, supporting every `StringType` value a peer could legally send (`0x00`-`0x04`) even
+ * though `writeTypedString` only ever produces `0x00`/`0x01`/`0x04` itself - this side of the codec is only
+ * ever exercised in this library's own round-trip tests, since a real MAPI/HTTP client never sends a
+ * `TypedString` value to the server. Returns `undefined` for `StringType = 0x00` ("no string"), matching
+ * `writeTypedString`'s own `undefined` input. */
+export declare function readTypedString(reader: BufferReader): string | undefined;

package/dist/types/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * MAPI-over-HTTP protocol compatibility (Phase 3 of this library's roadmap): a hand-built ROP (Remote
+ * Operation) codec and buffer-framing layer (`[MS-OXCROPS]`), JWT-secured EMSMDB transport (`BaseMapiEmsmdbRoute`,
+ * reusing the framework's existing `@Auth(["jwt"])` strategy - no MAPI-specific auth code of its own), and a
+ * minimal NSPI address-book endpoint (`BaseMapiNspiRoute`) for GAL "search as you type" lookups.
+ *
+ * This module exports only the backend-agnostic surface: the wire-format codecs, the abstract route base
+ * classes, `MapiSessionManager`, the ROP dispatcher, and every ROP/NSPI handler class (each takes a generic
+ * `RopContext`/repo argument, not a concrete entity class, so none of them are backend-specific). The concrete
+ * Mongo/SQL classes a deployment actually instantiates (`MapiEmsmdbRouteMongo`/`SQL`,
+ * `MapiNspiRouteMongo`/`SQL`) are exported from this package's `./mongo`/`./sql` subpaths instead, alongside
+ * every other entity/route/job this library defines - see `src/eas/index.ts`'s identical doc comment for the
+ * same convention.
+ *
+ * A deployment mounts both MAPI endpoints with a trivial one-line subclass each, the same pattern
+ * `src/eas/index.ts`'s doc comment describes for `BaseEasRoute`:
+ * ```ts
+ * import { MapiEmsmdbRouteMongo, MapiNspiRouteMongo } from "@rapidrest/mail/mongo";
+ * import { RouteDecorators } from "@rapidrest/service-core";
+ * const { Route } = RouteDecorators;
+ *
+ * @Route("/mapi/emsmdb")
+ * export class MyMapiEmsmdbRoute extends MapiEmsmdbRouteMongo {}
+ *
+ * @Route("/mapi/nspi")
+ * export class MyMapiNspiRoute extends MapiNspiRouteMongo {}
+ * ```
+ * Real Outlook desktop locates both URLs via `@rapidrest/mail/autodiscover`'s Outlook/EXCH response
+ * (`BaseAutodiscoverRoute`'s `mapiUrl` property) - see that module's own doc comment.
+ *
+ * **Documented gaps in this pragmatic subset** (see the architecture plan's "MAPI over HTTP (Phase 3)" section
+ * for the full reasoning behind each):
+ * - Incremental sync (`RopFastTransferSourceCopyTo`/`CopyProperties`/`GetBuffer`) always builds a full,
+ *   non-differential dump, not real IDSET-based ICS (`[MS-OXCFXICS]`) - a real client still works correctly
+ *   against this, just less efficiently than byte-perfect ICS.
+ * - Calendar/meetings: no counter-proposals, meeting-forwarding, delegate scheduling, or resource-booking
+ *   auto-accept; no DST-aware timezones (fixed-offset approximation only); no recurrence exceptions/modified
+ *   instances; no Hijri/`MonthEnd` recurrence patterns.
+ * - No `RopModifyRecipients` - attendees/recipients are always added via the same `PidTagDisplayTo`/`Cc`
+ *   pragmatic path used for ordinary mail.
+ * - No public-folder support, no delegate/shared-mailbox access, no rules/permissions/search-folder ROPs, no
+ *   client-certificate enrollment.
+ * - Calendar named properties (location/recurrence/timezone/etc.) are excluded from FastTransfer streams -
+ *   only the columns in `FastTransferStream.ts`'s `DEFAULT_*_COLUMNS` tables are included.
+ * - NSPI is limited to `Bind`/`Unbind`/`GetMatches` only - no row/name lookups beyond a single content-
+ *   restriction search, no directory replication.
+ */
+export * from "./codec/BufferCursor.js";
+export * from "./codec/MapiGuid.js";
+export * from "./codec/TypedString.js";
+export * from "./codec/PropertyValue.js";
+export * from "./codec/RopBuffer.js";
+export * from "./codec/AppointmentRecurrence.js";
+export * from "./codec/MapiTimeZone.js";
+export * from "./codec/GlobalObjectId.js";
+export * from "./RopDispatcher.js";
+export * from "./MapiSessionManager.js";
+export * from "./BaseMapiEmsmdbRoute.js";
+export * from "./BaseMapiNspiRoute.js";
+export * from "./rop/RopHandler.js";
+export * from "./rop/FolderTarget.js";
+export * from "./rop/MessageTarget.js";
+export * from "./rop/CalendarEventTarget.js";
+export * from "./rop/MessageBodyStream.js";
+export * from "./rop/PropertyResolvers.js";
+export * from "./rop/NamedPropertyRegistry.js";
+export * from "./rop/CalendarNamedProperties.js";
+export * from "./rop/FastTransferStream.js";
+export * from "./rop/MeetingMessageClassHandler.js";
+export * from "./rop/RopLogonHandler.js";
+export * from "./rop/RopReleaseHandler.js";
+export * from "./rop/RopOpenFolderHandler.js";
+export * from "./rop/RopGetHierarchyTableHandler.js";
+export * from "./rop/RopSetColumnsHandler.js";
+export * from "./rop/RopQueryRowsHandler.js";
+export * from "./rop/RopGetContentsTableHandler.js";
+export * from "./rop/RopOpenMessageHandler.js";
+export * from "./rop/RopGetPropertiesSpecificHandler.js";
+export * from "./rop/RopOpenStreamHandler.js";
+export * from "./rop/RopReadStreamHandler.js";
+export * from "./rop/RopCreateMessageHandler.js";
+export * from "./rop/RopSetPropertiesHandler.js";
+export * from "./rop/RopWriteStreamHandler.js";
+export * from "./rop/RopSaveChangesMessageHandler.js";
+export * from "./rop/RopSubmitMessageHandler.js";
+export * from "./rop/RopGetPropertyIdsFromNamesHandler.js";
+export * from "./rop/RopDeleteMessagesHandler.js";
+export * from "./rop/RopDeleteFolderHandler.js";
+export * from "./rop/RopFastTransferSourceCopyToHandler.js";
+export * from "./rop/RopFastTransferSourceCopyPropertiesHandler.js";
+export * from "./rop/RopFastTransferSourceGetBufferHandler.js";
+export * from "./nspi/NspiCodec.js";
+export * from "./nspi/NspiBindHandler.js";
+export * from "./nspi/NspiGetMatchesHandler.js";

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

@@ -0,0 +1,20 @@
+import { MailboxMongo } from "@rapidmx/restapi/mongo";
+import { BaseMapiEmsmdbRoute } from "../BaseMapiEmsmdbRoute.js";
+/**
+ * Mongo-backed concrete `BaseMapiEmsmdbRoute`, mounted at `/mapi/emsmdb`. 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 MapiEmsmdbRouteMongo extends BaseMapiEmsmdbRoute<MailboxMongo> {
+    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/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,26 @@
+import type { HttpRequest, HttpResponse, RepoUtils } from "@rapidrest/service-core";
+/** The most rows one `GetMatches` lookup asks the repo for per query - `RepoUtils.find()`'s own page cap. */
+export declare const MAX_MATCH_ROWS = 1000;
+/**
+ * `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/AddressList.d.ts

@@ -0,0 +1,48 @@
+import type { RopContext } from "./RopHandler.js";
+/** Splits a `PidTagDisplayTo`/`Cc`/`Bcc`-style string on the semicolons Outlook separates recipients with,
+ * trimming and dropping empty entries. Commas are not separators: a resolved recipient's display name commonly
+ * contains one (`Doe, Jane <jane@example.com>`). */
+export declare function splitAddressList(value: string | undefined): string[];
+/** `true` for a plain SMTP address (see `PLAIN_EMAIL_ADDRESS`) no longer than RFC 5321's 254 characters. These
+ * strings reach MIME headers, the SMTP envelope and iCalendar `mailto:` lines, where a CR/LF would inject content. */
+export declare function isPlainEmailAddress(value: string): boolean;
+/** One entry of a display string: an address with an optional display name, a display name alone (`address`
+ * undefined, still to be resolved), or something that can't be used (`invalid`). */
+export interface RecipientEntry {
+    name: string;
+    address?: string;
+    invalid?: boolean;
+}
+/**
+ * Parses one `;`-separated entry with nodemailer's `addressparser`: `jane@example.com`, `Jane <jane@example.com>`,
+ * `"Doe, Jane" <jane@example.com>` or a bare display name `Jane Doe`. An entry holding several addresses yields one
+ * recipient each. Any address that isn't a plain SMTP address marks the entry invalid.
+ */
+export declare function parseRecipientEntry(entry: string): RecipientEntry[];
+/** Every entry of a `PidTagDisplayTo`/`Cc`/`Bcc`-style string - see `parseRecipientEntry`. */
+export declare function parseRecipientList(value: string | undefined): RecipientEntry[];
+/** The plain addresses in a `PidTagDisplayTo`/`Cc`/`Bcc`-style string, including those written as
+ * `Name <address>`, skipping display names without an address and anything invalid. */
+export declare function parseAddressList(value: string | undefined): string[];
+/** A recipient ready to send to. */
+export interface ResolvedRecipient {
+    name: string;
+    address: string;
+}
+/** The outcome of `resolveRecipientList`: the usable recipients, and the entries that were display names with no
+ * single matching contact (`unresolved`) or not usable at all (`invalid`). */
+export interface RecipientResolution {
+    recipients: ResolvedRecipient[];
+    unresolved: string[];
+    invalid: string[];
+}
+/** The most recipients (To, Cc and Bcc together) one submitted message or meeting may have - the same limit
+ * `@rapidmx/activesync`'s `ComposeMailCommand` enforces (`MAX_COMPOSE_RECIPIENTS`). */
+export declare const MAX_RECIPIENTS_PER_MESSAGE = 500;
+/**
+ * Resolves a display string into addresses. An entry carrying an address is used as is; a bare display name (Outlook
+ * writes names, not addresses, into `PidTagDisplayTo` once it has resolved a recipient against an address book) is
+ * looked up among the caller's own contacts by exact display name and used when exactly one contact matches, with
+ * that contact's first valid email address.
+ */
+export declare function resolveRecipientList(value: string | undefined, context: Pick<RopContext, "mailboxUid" | "contactRepo" | "budget">): Promise<RecipientResolution>;

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

@@ -0,0 +1,33 @@
+import type { RepoUtils } from "@rapidrest/service-core";
+import { Attendee, BusyStatus, RecurrenceRule } from "@rapidmx/restapi";
+import type { ExecuteBudget } from "./ExecuteBudget.js";
+import { type RepoSort } from "./RepoPaging.js";
+/**
+ * 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>;
+/** The order a calendar folder's events are listed in: latest start first, ties broken by `uid`. */
+export declare const CALENDAR_EVENT_SORT: RepoSort;
+/** Resolves the calendar events directly in `folderUid`, latest first and capped at `MAX_COLLECTION_ROWS`, as
+ * `"calendarEvent:<uid>"` target strings. */
+export declare function resolveFolderCalendarEvents(folderUid: string, calendarEventRepo: RepoUtils<any>, budget?: ExecuteBudget): 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";
+import type { RepoSort } from "./RepoPaging.js";
+/**
+ * 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>;
+/** The order a `CONTACTS` folder's contents table lists contacts in (see `ContentsTable.ts`). */
+export declare const CONTACT_SORT: RepoSort;

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

@@ -0,0 +1,16 @@
+import type { MapiObjectHandle } from "../MapiSessionManager.js";
+import type { RopContext } from "./RopHandler.js";
+export type ContentsKind = NonNullable<MapiObjectHandle["contentsKind"]>;
+/** Which repo a folder's items live in, decided by the folder's own `type`: a `Contact`/`Task`/`CalendarEvent` is
+ * its own entity, never a `Message` row. */
+export declare function resolveContentsKind(folderUid: string, context: RopContext): Promise<ContentsKind>;
+/**
+ * The `"<kind>:<uid>"` row targets at positions `[start, start + count)` of a contents table (a `"folder:<uid>"`
+ * table with `contentsKind` set), read straight from the database in a fixed, stable order. A context without the
+ * matching optional repo yields no rows.
+ *
+ * Reading a window per `RopQueryRows` instead of snapshotting every row at `RopGetContentsTable` time keeps session
+ * state small and makes no folder too large to page through. The trade-off is that a message added or removed
+ * between two `RopQueryRows` calls can shift the rows that follow.
+ */
+export declare function resolveContentsWindow(context: RopContext, table: MapiObjectHandle, start: number, count: number): Promise<string[]>;

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

@@ -0,0 +1,48 @@
+/** The most rows (items or folders) whose properties one `Execute` resolves, across all of its ROPs. */
+export declare const MAX_ROWS_RESOLVED_PER_EXECUTE = 20000;
+/** The most bytes one `Execute` builds or parses (FastTransfer streams and message bodies), across all of its ROPs. */
+export declare const MAX_BYTES_BUILT_PER_EXECUTE: number;
+/** The most database queries (paged reads, table lookups, deletes) one `Execute` runs through the budgeted paths. */
+export declare const MAX_QUERIES_PER_EXECUTE = 20000;
+/** The most rows one `Execute` reads back from paged queries (folder lists, folder walks, item lists). */
+export declare const MAX_ROWS_FETCHED_PER_EXECUTE = 100000;
+/** The most `RopSubmitMessage`s one `Execute` runs. Each one can relay mail, so a request can't repeat it 1024 times. */
+export declare const MAX_SUBMITS_PER_EXECUTE = 16;
+/** Thrown when an `Execute` has used up its `ExecuteBudget`. The ROP that hit it fails; see `RopDispatcher`. */
+export declare class WorkBudgetExceededError extends Error {
+    constructor(what: string);
+}
+/**
+ * The work one `Execute` may do. Limits on ROP count and per-ROP sizes alone still let one request chain many
+ * expensive ROPs (a dozen 10000-row FastTransfer dumps, the same large body parsed by several streams, or a thousand
+ * hierarchy tables or folder walks), so rows resolved, bytes built, queries run, rows fetched and submits are counted
+ * across the whole request. Every charge happens before the work it pays for. Also dedupes message body parses within
+ * the request (`bodies`).
+ */
+export declare class ExecuteBudget {
+    rowsRemaining: number;
+    bytesRemaining: number;
+    queriesRemaining: number;
+    fetchedRowsRemaining: number;
+    submitsRemaining: number;
+    /** Message uid -> its decoded body, so opening the same body twice in one request parses it once. */
+    readonly bodies: Map<string, Promise<Buffer<ArrayBufferLike>>>;
+    constructor(maxRows?: number, maxBytes?: number, limits?: {
+        maxQueries?: number;
+        maxFetchedRows?: number;
+        maxSubmits?: number;
+    });
+    /** Uses `count` rows of the budget, throwing `WorkBudgetExceededError` once it is exhausted. */
+    chargeRows(count?: number): void;
+    /** Uses `count` bytes of the budget, throwing `WorkBudgetExceededError` once it is exhausted. */
+    chargeBytes(count: number): void;
+    /** Throws `WorkBudgetExceededError` when no bytes are left, so work that can't be sized up front (fetching a blob)
+     * isn't started at all. */
+    assertBytesLeft(): void;
+    /** Uses `count` queries of the budget. Called before running them. */
+    chargeQueries(count?: number): void;
+    /** Uses `count` fetched rows of the budget. */
+    chargeFetchedRows(count: number): void;
+    /** Uses one submit of the budget. */
+    chargeSubmit(): void;
+}

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

@@ -0,0 +1,57 @@
+import { PropertyType } from "../codec/PropertyValue.js";
+import { type MapiObjectHandle } from "../MapiSessionManager.js";
+import { type RopContext } from "./RopHandler.js";
+interface PropertyColumn {
+    propertyId: number;
+    propertyType: PropertyType;
+}
+/** The largest FastTransfer stream built for one handle; a larger source fails with `MAPI_E_TOO_BIG`. */
+export declare const MAX_FAST_TRANSFER_BYTES: number;
+/** How long a built stream is kept for paging out. A client pages a stream out right after opening it; one that
+ * leaves it longer than this has to open the transfer again. */
+export declare const FAST_TRANSFER_TTL_SECONDS: number;
+/** Thrown while building a stream that has grown past its byte limit. */
+export declare class FastTransferTooBigError extends Error {
+    constructor();
+}
+/**
+ * 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.
+ *
+ * The size is checked after every item, so a huge folder stops being built as soon as it passes `maxBytes`
+ * (`FastTransferTooBigError`) instead of being fully built first. Every item resolved and the finished stream's bytes
+ * count against the request's `ExecuteBudget` when there is one.
+ */
+export declare function buildFastTransferStream(handle: MapiObjectHandle, context: RopContext, options?: {
+    columns?: PropertyColumn[];
+    excludePropertyIds?: ReadonlySet<number>;
+    maxBytes?: number;
+}): Promise<Buffer>;
+/** Why `loadFastTransferBuffer` has no stream: `"tooBig"` when a rebuild passed `MAX_FAST_TRANSFER_BYTES`, `"lost"`
+ * when the stored stream is gone part-way through paging. */
+export type FastTransferLoadFailure = "tooBig" | "lost";
+/**
+ * The built stream for the `"fastTransfer"` handle at `handleIndex`, from the shared `HandleDataStore` (Redis when
+ * configured, so any replica can page it out).
+ *
+ * When the stream is gone (expired, evicted, or built by a replica without shared storage), it is rebuilt only if
+ * nothing has been paged out yet. Part-way through, a rebuild could differ from what the client already has (items
+ * added or changed since), and continuing at the old offset would hand it bytes from a different stream, so that
+ * case reports `"lost"` and the client restarts the transfer. A rebuild is held to `MAX_FAST_TRANSFER_BYTES` like
+ * the original build, and storing it to the session's and user's handle data quota (`handleDataOwners`); either
+ * failing reports `"tooBig"`.
+ */
+export declare function loadFastTransferBuffer(context: RopContext, handleIndex: number, transfer: MapiObjectHandle): Promise<Buffer | FastTransferLoadFailure>;
+/**
+ * Shared by `RopFastTransferSourceCopyTo`/`CopyProperties`: builds the stream for `source`, and on success stores a
+ * `"fastTransfer"` handle at `outputHandleIndex` with the stream in the `HandleDataStore`. Returns `false`, storing
+ * nothing, when the stream exceeds `MAX_FAST_TRANSFER_BYTES` or the session's or user's handle data quota
+ * (`handleDataOwners`) has no room for it.
+ */
+export declare function openFastTransferHandle(context: RopContext, outputHandleIndex: number, source: MapiObjectHandle, options: {
+    columns?: PropertyColumn[];
+    excludePropertyIds?: number[];
+}): Promise<boolean>;
+export {};

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

@@ -0,0 +1,64 @@
+import type { RepoUtils } from "@rapidrest/service-core";
+import { Folder } from "@rapidmx/restapi";
+import type { MapiSessionContext } from "../MapiSessionManager.js";
+import type { ExecuteBudget } from "./ExecuteBudget.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, budget?: ExecuteBudget): 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, budget?: ExecuteBudget): 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;