@rapidmx/activesync 1.0.0-beta.0

package/dist/types/EasSyncKeyUtils.d.ts

@@ -0,0 +1,89 @@
+import type { RecoverableBaseEntity, RepoUtils } from "@rapidrest/service-core";
+import type { DeviceSyncState } from "@rapidmx/restapi";
+/**
+ * A parsed EAS `SyncKey`. The wire value is opaque to the client per spec, so this library encodes it as
+ * `"<generation>:<watermarkIso>"` (e.g. `"3:2026-09-04T12:00:00.000Z"`) - a monotonic generation counter (bumped
+ * once per successful sync round, satisfying the spec's "the server MUST return a different SyncKey every
+ * time" requirement) paired with the `dateModified` watermark that generation was issued at.
+ */
+export interface SyncKey {
+    generation: number;
+    watermark: Date;
+}
+/** Formats a `SyncKey` back into its wire string form. */
+export declare function formatSyncKey(key: SyncKey): string;
+/** Parses a stored/previously-issued `SyncKey` string. Returns `undefined` for a malformed value - callers
+ * only ever parse a key this library itself minted and stored (never a raw, unvalidated client value; see
+ * `resolveSyncKey`'s doc comment), so `undefined` here signals corrupted persisted state, not client input. */
+export declare function parseSyncKey(value: string): SyncKey | undefined;
+export type SyncKeyResolution = {
+    kind: "initial";
+} | {
+    kind: "valid";
+    key: SyncKey;
+} | {
+    kind: "invalid";
+};
+/**
+ * Resolves an incoming client `SyncKey` string against the value this library itself previously issued and
+ * stored (`storedValue`, e.g. `DeviceSyncState.folderSyncKeys[folderUid]`) — deliberately a plain string
+ * equality check, not a re-parse-and-compare of the client's value, so a client that echoes back anything
+ * other than the exact opaque string it was handed is treated as `"invalid"` even if it happens to parse.
+ *
+ * - `"0"` (or empty/missing) from the client is always `"initial"` regardless of `storedValue` — an EAS
+ * client legitimately sends this to (re)start a collection from scratch (first-ever sync, or recovering
+ * from an `"invalid"` response elsewhere), and the spec requires the server honor it unconditionally.
+ * - Otherwise, a match against `storedValue` is `"valid"`; anything else (including `storedValue` being
+ * unset, i.e. the server has no record of ever issuing a key for this scope) is `"invalid"` — forcing the
+ * client back to `"0"`, per spec, rather than guessing at recovery.
+ */
+export declare function resolveSyncKey(clientValue: string | undefined, storedValue: string | undefined): SyncKeyResolution;
+/**
+ * Applies `patch` to `deviceSyncState` and persists it - the one correct way any EAS command handler (or
+ * `BaseEasRoute` itself) should ever write to a `DeviceSyncState`, replacing the inline
+ * `deviceSyncStateRepo.update(...)` calls `ProvisionCommand`/`FolderSyncCommand`/`SyncCommand` used to each
+ * repeat individually.
+ *
+ * This exists because `RepoUtils.update()` does **not** mutate the `existing` object passed to it - confirmed
+ * by reading its implementation directly - it only returns a freshly-fetched instance reflecting the write,
+ * leaving the caller's in-memory copy (including its optimistic-concurrency `version`) stale. A single write
+ * per request is harmless (nothing re-reads the stale copy), but a *second* write to the same `deviceSyncState`
+ * later in the same request - e.g. `BaseEasRoute.dispatch()`'s own trailing `lastSyncAt` update, or a second
+ * collection's SyncKey in a multi-collection `Sync` - would build its own patch's `version` off that stale
+ * value. `RepoUtils.update()` filters its underlying write by exactly that `version`, so the write silently
+ * matches zero rows instead of throwing - a silent no-op, not a visible error. Copying `update()`'s own
+ * returned result back onto `deviceSyncState` (last line below) keeps every field, including `version`, current
+ * for whatever writes this same request still has left to make.
+ */
+export declare function persistDeviceSyncState(deviceSyncState: DeviceSyncState, deviceSyncStateRepo: RepoUtils<any>, patch: Record<string, unknown>): Promise<void>;
+/** One page of enumerated changes for a `RecoverableBaseEntity` collection scoped by a single field (e.g.
+ * `folderUid` for `Message`/`CalendarEvent`/.../`mailboxUid` for `Folder`), since the last sync at `watermark`. */
+export interface ChangeSet<T extends RecoverableBaseEntity> {
+    adds: T[];
+    changes: T[];
+    deletes: T[];
+    /** The new watermark to persist as this generation's cursor - the latest `dateModified` actually included
+     * in this page, never simply "now" (which would silently skip any row modified after this page was read
+     * but before the caller finishes processing it). Equal to the input `watermark` when nothing changed. */
+    newWatermark: Date;
+    /** `true` when more changed rows exist beyond `windowSize` - the caller should set the response's
+     * `MoreAvailable` flag so the client immediately re-syncs for the rest, rather than waiting a full poll
+     * interval. */
+    moreAvailable: boolean;
+}
+/**
+ * Enumerates `Add`/`Change`/`Delete`s for one scoped collection since `watermark`, for `FolderSyncCommand` and
+ * (eventually) `SyncCommand`'s shared cursor mechanism. Requires `T` to be `RecoverableBaseEntity` (soft
+ * delete) — see `RecoverableRepoUtils`'s own doc comment for why a plain hard-deleted entity can't support
+ * this at all (nothing left to enumerate once a row is actually gone).
+ *
+ * `RepoUtils.find()` does **not** support an `includeDeleted` option - confirmed by reading its source: unlike
+ * `count()`/`findOne()`, it never strips `ModelUtils.buildSearchQuery()`'s default `deleted: false` exclusion
+ * back out. Rather than the (harmless-looking but silently no-op) `includeDeleted: true` this function used to
+ * pass, deleted rows are fetched via a **second** `find()` call with an explicit, literal `deleted: true` in
+ * the query object itself - `buildSearchQuery()`'s exclusion only applies when the caller's query has no
+ * `"deleted"` key at all, so supplying one directly (rather than relying on an option `find()` doesn't honor)
+ * reliably selects exactly the soft-deleted rows instead. The two result sets are then merged and re-windowed
+ * together so `windowSize`/`MoreAvailable` still describe the combined stream, not each half independently.
+ */
+export declare function computeChanges<T extends RecoverableBaseEntity>(repo: RepoUtils<T>, scopeField: string, scopeUid: string, watermark: Date, windowSize: number): Promise<ChangeSet<T>>;

package/dist/types/adapters/CalendarSyncAdapter.d.ts

@@ -0,0 +1,52 @@
+import { type WbxmlElement } from "../codec/WbxmlElement.js";
+import type { EasCollectionSyncAdapter } from "./EasCollectionSyncAdapter.js";
+import { type CalendarEvent } from "@rapidmx/restapi";
+/**
+ * Maps `CalendarEvent` to/from the EAS `Sync` `Calendar` collection class (MS-ASCAL).
+ *
+ * **Pragmatic subset, deliberately not the full MS-ASCAL semantics**:
+ * - `TimeZone` is not emitted - the real element is a base64-encoded binary Win32 `TIME_ZONE_INFORMATION`
+ * structure, not a plain IANA string; `CalendarEvent.timezone` (an IANA identifier) can't be losslessly
+ * re-encoded into that format without a full IANA-to-Windows zone mapping table, and a real device would
+ * rather see no `TimeZone` element (falling back to its own default) than a malformed one.
+ * - `Sensitivity` is always reported `0` (Normal) - this library's `CalendarEvent` has no privacy dimension of
+ * its own to source a real value from.
+ * - Recurrence patterns keyed by an ordinal weekday (MS-ASCAL `Type` 3/6, e.g. "the 2nd Tuesday of the month")
+ * are not emitted - see `RECURRENCE_TYPE_CODES`'s own doc comment.
+ * - Recurrence exceptions (individually modified/cancelled occurrences of a recurring series) are not synced -
+ * deferred, matching this library's "pragmatic subset" precedent elsewhere (e.g. `FolderSyncCommand`'s SyncKey
+ * replay-protection gap).
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class CalendarSyncAdapter implements EasCollectionSyncAdapter<CalendarEvent> {
+    readonly collectionClass = "Calendar";
+    toApplicationData(event: CalendarEvent): WbxmlElement;
+    private recurrenceElement;
+    /**
+     * Reverse of `toApplicationData`. `timezone`/`status`/`sequence`/`icalUid` have no wire representation at
+     * all (see this class's own "pragmatic subset" doc comment for `timezone`; the other three are purely
+     * server-managed identifiers/state a client was never sent in the first place) and are never included in
+     * the returned partial - `newEntityDefaults()` below supplies `icalUid`/`sequence` for a brand new event
+     * (`status`/`timezone` are left at the model's own constructor defaults), and `applyChange` leaves all four
+     * untouched by construction (merging onto `existing`).
+     *
+     * `OrganizerEmail` is required for a new event (there is nowhere else to default it from - this adapter
+     * has no mailbox context of its own) - a real calendar client always sends it regardless, since it already
+     * knows its own account's address. Omitting it on an `Add` throws, which `SyncCommand.applyAdd` turns into
+     * Status `6` ("client has sent a malformed or invalid item"), the spec's own designated code for exactly
+     * this case.
+     *
+     * `Attendees`/`Recurrence` are ghosted as a whole element, like `ContactsSyncAdapter`'s arrays: present at
+     * all -> rebuilt entirely from what's there; absent -> left untouched on a `Change`.
+     */
+    fromApplicationData(el: WbxmlElement): Partial<CalendarEvent>;
+    /** `icalUid`/`sequence` have no wire representation on `Add` (see `fromApplicationData`'s own doc comment)
+     * - without this, every Sync-created event would fall back to `CalendarEventMongo`/`CalendarEventSQL`'s own
+     * constructor default of `icalUid: ""`, violating RFC 5545's uniqueness expectation for `UID`. Mirrors
+     * MAPI's identical `RopSaveChangesMessageHandler` pattern (`${crypto.randomUUID()}@mapi`), `@eas` suffix
+     * instead. */
+    newEntityDefaults(): Partial<CalendarEvent>;
+    private attendeeFromElement;
+    private recurrenceRuleFromElement;
+}

package/dist/types/adapters/ContactsSyncAdapter.d.ts

@@ -0,0 +1,33 @@
+import { type WbxmlElement } from "../codec/WbxmlElement.js";
+import type { EasCollectionSyncAdapter } from "./EasCollectionSyncAdapter.js";
+import { type Contact } from "@rapidmx/restapi";
+/**
+ * Maps `Contact` to/from the EAS `Sync` `Contacts` collection class (MS-ASCONTACTS/MS-ASCNTC2). Contacts are
+ * also this library's GAL source (see the architecture note on `Contact` itself), but that's `SearchCommand`'s
+ * concern, not this adapter's.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class ContactsSyncAdapter implements EasCollectionSyncAdapter<Contact> {
+    readonly collectionClass = "Contacts";
+    toApplicationData(contact: Contact): WbxmlElement;
+    private addressElements;
+    /**
+     * Reverse of `toApplicationData`. Scalar fields (`FileAs`/`FirstName`/.../`JobTitle`, and the `Body`
+     * `notes`) are properly ghosted - a field's own tag missing from `el` leaves that `Contact` field
+     * untouched. `emails`/`phones`/`addresses` are ghosted only as a **whole group**, not per slot: if *none*
+     * of a group's tags are present the group is left untouched, but if *any* one is, the entire group is
+     * rebuilt from just what's present in `el` (a real client's own Contacts edit UI typically resends every
+     * field it manages anyway, so this only under-preserves data for a client that deliberately sends a
+     * single-slot partial update within one of these groups - a documented simplification, not silent data
+     * loss for the common case). Emails lose their original `type` on any round trip through a `Change`
+     * (rebuilt as `ContactAddressKind.OTHER`) since EAS's own `Email1/2/3Address` tags carry no kind at all,
+     * matching `toApplicationData`'s own already-documented encode-side loss of the same information.
+     * `categories` is ghosted as its own whole group (same rule as `emails`/`phones`/`addresses`): an absent
+     * `Categories` element leaves `Contact.categories` untouched, while a present one - even `<Categories/>`
+     * with no `Category` children - rebuilds it from scratch (an empty array clears it).
+     */
+    fromApplicationData(el: WbxmlElement): Partial<Contact>;
+    private addressTags;
+    private parseAddress;
+}

package/dist/types/adapters/EasCollectionSyncAdapter.d.ts

@@ -0,0 +1,52 @@
+import type { RecoverableBaseEntity } from "@rapidrest/service-core";
+import type { Mailbox } from "@rapidmx/restapi";
+import type { WbxmlElement } from "../codec/WbxmlElement.js";
+/**
+ * Maps one application entity type (`Message`/`Contact`/`CalendarEvent`/`Task`) to and from the EAS `Sync`
+ * command's per-collection wire representation. `SyncCommand` itself only knows the generic Add/Change/Delete
+ * cursor mechanics (shared with `FolderSyncCommand` via `EasSyncKeyUtils`) - everything entity-specific (which
+ * fields go in `ApplicationData`, on which code pages) lives in one adapter per collection type, keyed by the
+ * MS-ASCMD `Class` value (`"Email"`, `"Contacts"`, `"Calendar"`, `"Tasks"`) it answers to.
+ *
+ * `fromApplicationData` is deliberately optional: `SyncCommand` uses its absence as the capability check,
+ * answering Status `6` for `Add`/`Change` on a collection whose adapter doesn't implement it, rather than
+ * needing a separate flag that could drift out of sync with which adapters actually implement it. Every
+ * adapter today (`Email`, `Contacts`, `Calendar`, `Tasks`) implements it.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface EasCollectionSyncAdapter<T extends RecoverableBaseEntity> {
+    /** The MS-ASCMD `Class` value this adapter handles, e.g. `"Email"`. */
+    readonly collectionClass: string;
+    /** Builds the `<ApplicationData>` element for one `Add`/`Change` command reporting `item`. */
+    toApplicationData(item: T): WbxmlElement;
+    /**
+     * Parses one client-originated `Add`/`Change` command's `<ApplicationData>` element (`el`) into a partial
+     * entity update. Only fields actually present in `el` are included in the result - an omitted field means
+     * "unchanged" (MS-ASCMD's own "ghosted property" rule - see `SyncCommand`'s doc comment), never "clear this
+     * field" - which is what lets the same method serve both `Add` (the partial is merged onto a fresh
+     * `{mailboxUid, folderUid}` baseline) and `Change` (the partial is merged onto `existing`).
+     *
+     * May return a `Promise` - `EmailSyncAdapter` needs this for a Draft `Add`/`Change`'s body, which must be
+     * written to `BlobStore` before the resulting `bodyBlobKey` is known; every other adapter today returns a
+     * plain object, which `await`s through unchanged.
+     *
+     * @param el The command's `<ApplicationData>` element.
+     * @param existing The item being changed, for a `Change` command; `undefined` for `Add`. Adapters that
+     * need to know the item's current field values to correctly interpret a partial update - `EmailSyncAdapter`
+     * uses this to reuse an existing Draft's `bodyBlobKey` on `Change` rather than minting a new one.
+     */
+    fromApplicationData?(el: WbxmlElement, existing?: T): Partial<T> | Promise<Partial<T>>;
+    /**
+     * Supplies default field values for a brand-new entity created via a client-originated `Add`, applied
+     * *before* `fromApplicationData`'s own partial is merged on top (so anything the client actually sent
+     * always wins). For defaults a fresh entity needs regardless of what the client sent - `CalendarSyncAdapter`
+     * uses this for `icalUid`/`sequence`, since EAS's own `Add` command has no wire representation for either
+     * (a device doesn't know or send an iCalendar UID) but a stored default of `""` for every Sync-created
+     * event (this model's own fallback, see `CalendarEventMongo`'s constructor) would violate RFC 5545's own
+     * uniqueness expectation for `UID`. `EmailSyncAdapter` uses `mailbox` to populate a new Draft's `from`.
+     * Optional; only implemented where a collection actually needs it - most adapters have no such gap (and
+     * ignore the `mailbox` parameter entirely).
+     */
+    newEntityDefaults?(mailbox: Mailbox): Partial<T>;
+}

package/dist/types/adapters/EmailSyncAdapter.d.ts

@@ -0,0 +1,53 @@
+import { type WbxmlElement } from "../codec/WbxmlElement.js";
+import type { EasCollectionSyncAdapter } from "./EasCollectionSyncAdapter.js";
+import { type Mailbox, type Message } from "@rapidmx/restapi";
+/**
+ * Maps `Message` to/from the EAS `Sync` `Email` collection class (MS-ASEMAIL). Only a plain-text preview of the
+ * body is included here (`Message.bodyPreview`, always already loaded on the entity, `Truncated: 1`) rather
+ * than the full sanitized HTML body from the `BlobStore` - a real device fetches the full body on demand via
+ * `ItemOperations`' `Fetch` (see the architecture plan's command table), the same two-step "list, then fetch
+ * body" flow every real EAS client already implements for exactly this reason (bodies can be large; a sync
+ * window's Add/Change list shouldn't have to pull every one of them from blob storage up front).
+ *
+ * Also handles client-originated `Add`/`Change` for Drafts (`SyncCommand`'s own doc comment covers why this is
+ * the only `Email` write EAS itself allows) - a plain-text-only pragmatic subset: no HTML body, no attachments
+ * (mirrors `ComposeMailCommand`'s own already-documented attachment gap). `To`/`Cc`/`Bcc` (the latter MS-ASEMAIL2's
+ * own `Bcc` tag) are ghosted independently per recipient type, not as one combined group - a `Change` touching
+ * only one of them leaves the others untouched, carried over from `existing.recipients`.
+ *
+ * Emits MS-ASEMAIL2's `Email2:ConversationId` (read-only - no `fromApplicationData` handling, since EAS itself
+ * never lets a client set it) whenever `Message.conversationId` is populated, so a device's threaded-view UI can
+ * group messages the same way `BaseMessageRoute.conversations()` does server-side. See `encodeConversationId`'s
+ * own doc comment for the wire encoding, and `ItemOperationsCommand`'s `Move` handling for the one place this
+ * gets decoded back.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class EmailSyncAdapter implements EasCollectionSyncAdapter<Message> {
+    readonly collectionClass = "Email";
+    private blobStore?;
+    toApplicationData(message: Message): WbxmlElement;
+    /**
+     * `Message.bodyBlobKey` is documented (see the `Message` interface itself) as holding raw MIME "unmodified
+     * from ingestion/send" - `ItemOperationsCommand.fetchMessage` parses it with `simpleParser` unconditionally
+     * for every message, Draft or not. A Draft's plain-text body is therefore wrapped in a minimal valid
+     * RFC 5322 message here (via `buildPlainTextMime`) rather than stored as bare text, so that contract holds
+     * for every consumer, not just this write path - a Draft created/edited via `Sync` must `Fetch` correctly
+     * the same way any other message does.
+     */
+    fromApplicationData(el: WbxmlElement, existing?: Message): Promise<Partial<Message>>;
+    /** Defaults for a brand-new Draft created via a client-originated `Add` - `from` is the caller's own
+     * mailbox address, per `ComposeMailCommand`'s identical `{ address, type: RecipientType.TO }` shape
+     * convention for a `from` field (the `Recipient` struct's `type` is only meaningful for real recipients;
+     * it's reused here as a harmless placeholder). */
+    newEntityDefaults(mailbox: Mailbox): Partial<Message>;
+}
+/** Encodes `Message.conversationId` (an internal string uid) into the opaque binary blob MS-ASEMAIL2's
+ * `Email2:ConversationId` carries on the wire. The spec never mandates any particular binary format for this
+ * value - a real Exchange server mints a GUID, but a client only ever compares/echoes it byte-for-byte, never
+ * interprets it - so encoding the uid's own UTF-8 bytes directly (rather than hashing into a 16-byte GUID
+ * shape) is a valid, simpler choice that `decodeConversationId` can invert exactly, which `ItemOperationsCommand`
+ * relies on to resolve an `ItemOperations` `Move`'s `ConversationId` back into this same uid. */
+export declare function encodeConversationId(conversationId: string): Buffer;
+/** Reverse of `encodeConversationId`. */
+export declare function decodeConversationId(opaque: Buffer): string;

package/dist/types/adapters/TasksSyncAdapter.d.ts

@@ -0,0 +1,32 @@
+import { type WbxmlElement } from "../codec/WbxmlElement.js";
+import type { EasCollectionSyncAdapter } from "./EasCollectionSyncAdapter.js";
+import { type Task } from "@rapidmx/restapi";
+/**
+ * Maps `Task` to/from the EAS `Sync` `Tasks` collection class (MS-ASTASK).
+ *
+ * **Pragmatic subset**: only the `Utc*` (UTC Compact DateTime) variant of each date field is emitted, not the
+ * paired local-time variant MS-ASTASK also defines (`DueDate`/`StartDate` alongside `UtcDueDate`/
+ * `UtcStartDate`) - this library doesn't track a per-task timezone to correctly localize the non-UTC variant,
+ * and a real device already treats the `Utc*` field as authoritative. Recurring tasks are not synced (a task's
+ * `Recurrence` element mirrors Calendar's, itself already a pragmatic subset there - deferred further here).
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class TasksSyncAdapter implements EasCollectionSyncAdapter<Task> {
+    readonly collectionClass = "Tasks";
+    toApplicationData(task: Task): WbxmlElement;
+    /**
+     * Reverse of `toApplicationData`. `DateCompleted` is never parsed back - it's `task.dateModified` echoed
+     * out, not an independent field this library's own `Task` model has room to store separately, so a client
+     * setting `Complete` is enough on its own. `ReminderSet="0"` (with no `ReminderTime`) is treated as an
+     * explicit "clear the reminder" signal (`reminderDate: null` in the returned partial, which - unlike
+     * simply omitting the key - does override an existing reminder when merged onto `existing` for a `Change`)
+     * since MS-ASTASK gives no other way to express removing a reminder; `UtcDueDate` has no equivalent
+     * explicit-clear signal and so can only be set, never cleared, via `Sync` - a real, narrower gap than
+     * `reminderDate`'s, documented here rather than silently accepted. `null`, not `undefined`: TypeORM's
+     * `UpdateQueryBuilder` silently drops any `undefined`-valued key from the generated SQL `SET` clause
+     * (confirmed by reading its source), so `undefined` here would leave a stale `reminderDate` in place on
+     * the SQL backend while correctly clearing it on Mongo - `null` clears it on both.
+     */
+    fromApplicationData(el: WbxmlElement): Partial<Task>;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * WBXML code page index -> namespace name, per MS-ASWBXML §2.1.2.1 ("List of Code Pages"). A code page is
+ * WBXML's mechanism for reusing the single-byte tag-token space across many XML namespaces: a `SWITCH_PAGE`
+ * global token changes which of these tables subsequent tag bytes are looked up against.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare enum WbxmlCodePage {
+    AirSync = 0,
+    Contacts = 1,
+    Email = 2,
+    AirNotification = 3,
+    Calendar = 4,
+    Move = 5,
+    ItemEstimate = 6,
+    FolderHierarchy = 7,
+    MeetingResponse = 8,
+    Tasks = 9,
+    ResolveRecipients = 10,
+    ValidateCert = 11,
+    Contacts2 = 12,
+    Ping = 13,
+    Provision = 14,
+    Search = 15,
+    Gal = 16,
+    AirSyncBase = 17,
+    Settings = 18,
+    DocumentLibrary = 19,
+    ItemOperations = 20,
+    ComposeMail = 21,
+    Email2 = 22,
+    Notes = 23,
+    RightsManagement = 24,
+    Find = 25
+}
+/** Resolves a decoded tag byte's low 6 bits back into its tag name for the given code page. Falls back to a
+ * synthetic `"Unknown0x.."` name (rather than throwing) for a page/code this table doesn't recognize - a
+ * still-decodable, debuggable placeholder for a deferred code page or a future protocol version's new field,
+ * rather than failing the entire document over one unrecognized tag. */
+export declare function tagNameForCode(page: number, code: number): string;
+/** Resolves a tag name to its token byte (low 6 bits, before the content-flag bit is applied) for the given
+ * code page. Unlike `tagNameForCode()`, this throws on an unknown pair - encoding a tag this table has no
+ * token for is always a genuine programming error (an unregistered/deferred field), never legitimate input to
+ * tolerate. */
+export declare function codeForTagName(page: number, tag: string): number;

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

@@ -0,0 +1,33 @@
+import type { WbxmlElement } from "./WbxmlElement.js";
+/**
+ * Decodes a WBXML byte stream (an EAS request/response body) back into a `WbxmlElement` tree — the exact
+ * inverse of `WbxmlEncoder`. Reads the fixed EAS document header, skips its (always-empty, in real
+ * ActiveSync traffic) string table, then parses the single root element.
+ *
+ * The `publicid` header field is read via the same generic `mb_u_int32` reader used everywhere else, which is
+ * only a partial implementation of the full WBXML spec for that field (a raw leading `0x00` byte would
+ * signal "public identifier is a string-table reference" under the full spec, a form real ActiveSync traffic
+ * never uses) — safe here since every real EAS document sends the literal well-known value `1` ("unknown or
+ * missing"), which decodes identically either way.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class WbxmlDecoder {
+    private buf;
+    private pos;
+    private currentPage;
+    private depth;
+    decode(data: Buffer): WbxmlElement;
+    private readByte;
+    /** Decodes a WBXML `mb_u_int32`: base-128 digits, most significant group first, every byte but the last
+     * carrying the 0x80 continuation bit. Mirrors `WbxmlEncoder.writeMbUint()`. */
+    private readMbUint;
+    private readCString;
+    private readTagElement;
+    /** Reads a mixed sequence of child tag elements / an inline string / opaque binary content, up to (and
+     * consuming) the terminating `END` token — the body of one "has content" element. Also handles a
+     * `SWITCH_PAGE` appearing between sibling children, which applies to every subsequent sibling until
+     * either the next switch or the end of this content block (switching page is a standing instruction, not
+     * scoped to a single following tag). */
+    private readContentUntilEnd;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * A minimal, tagged-tree representation of one WBXML element, decoupled from the wire format's binary token
+ * encoding — `WbxmlEncoder`/`WbxmlDecoder` are the only code that ever deals in raw bytes; every EAS command
+ * handler works against this tree.
+ *
+ * Deliberately does not model WBXML attributes: MS-ASWBXML's own algorithm description confirms ActiveSync
+ * never uses the attribute mechanism (every element's data is carried as child elements or inline text), so
+ * there is nothing for an `attrs` field to represent here.
+ *
+ * A given element is expected to carry exactly one of `children` (nested elements - the common case for a
+ * structural container like `Sync`/`Collection`), `text` (a single inline string value - the common case for
+ * a leaf field like `SyncKey`/`ServerId`), or `opaque` (raw binary content - used only for `ItemOperations`
+ * `Data` and similar binary payloads). Real ActiveSync XML is data-oriented, not document-oriented, so this
+ * library never needs to represent mixed content (an element with both nested tags and inline text).
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface WbxmlElement {
+    /** The `WbxmlCodePage` this element's tag belongs to. */
+    page: number;
+    /** The tag name, as registered in `WbxmlCodePages.ts` for `page`. */
+    tag: string;
+    /** Nested elements, in document order. Empty for a leaf/empty element. */
+    children: WbxmlElement[];
+    /** Inline string content (WBXML `STR_I`), for a leaf element carrying a single text value. */
+    text?: string;
+    /** Raw binary content (WBXML `OPAQUE`), for a leaf element carrying binary data. */
+    opaque?: Buffer;
+}
+/** Constructs a structural element with nested children (e.g. `<Collection>...</Collection>`). */
+export declare function element(page: number, tag: string, children?: WbxmlElement[]): WbxmlElement;
+/** Constructs a leaf element carrying a single inline string value (e.g. `<SyncKey>1</SyncKey>`). */
+export declare function textElement(page: number, tag: string, text: string): WbxmlElement;
+/** Constructs a leaf element carrying raw binary content (e.g. `<Data>...</Data>` in `ItemOperations`). */
+export declare function opaqueElement(page: number, tag: string, opaque: Buffer): WbxmlElement;
+/** Finds the first direct child of `parent` with the given tag name, or `undefined` if none exists. Does not
+ * search recursively — WBXML/EAS field lookups are always relative to a specific known parent element. */
+export declare function findChild(parent: WbxmlElement, tag: string): WbxmlElement | undefined;
+/** Finds every direct child of `parent` with the given tag name (e.g. every `Collection` under
+ * `Collections`). */
+export declare function findChildren(parent: WbxmlElement, tag: string): WbxmlElement[];
+/** Shorthand for `findChild(parent, tag)?.text`, the common case of reading a leaf field's string value. */
+export declare function childText(parent: WbxmlElement, tag: string): string | undefined;

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

@@ -0,0 +1,20 @@
+import type { WbxmlElement } from "./WbxmlElement.js";
+/**
+ * Encodes a `WbxmlElement` tree into a WBXML byte stream, per MS-ASWBXML's encoding algorithm. Emits the
+ * fixed EAS document header (`version=1.3, publicid=unknown, charset=UTF-8, empty string table`) followed by
+ * the token stream for the given root element, switching code pages only when the page actually changes from
+ * whatever was last active (starting from `AirSync`, page 0, the implicit default per spec).
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class WbxmlEncoder {
+    private bytes;
+    private currentPage;
+    encode(root: WbxmlElement): Buffer;
+    private writeElement;
+    private writeStrI;
+    private writeOpaque;
+    /** Encodes `value` as a WBXML multi-byte unsigned integer (`mb_u_int32`): base-128 digits, most
+     * significant group first, every byte but the last carrying the 0x80 continuation bit. */
+    private writeMbUint;
+}

package/dist/types/commands/ComposeMailCommand.d.ts

@@ -0,0 +1,50 @@
+import { type Message, RecoverableRepoUtils } from "@rapidmx/restapi";
+import { type WbxmlElement } from "../codec/WbxmlElement.js";
+import type { EasCommandContext, EasCommandHandler } from "../EasCommandHandler.js";
+/**
+ * Shared implementation for EAS `SendMail`, `SmartForward`, and `SmartReply` (MS-ASCMD `ComposeMail` namespace)
+ * — all three submit a client-composed raw MIME body directly (`<Mime>`, opaque WBXML content) rather than
+ * referencing a pre-existing draft `Message`, unlike the webmail REST API's `POST /messages/:id/send` (see
+ * `BaseMessageRoute.send()`, which this class's `scanAndRelay()` call shares its scan-then-relay core with via
+ * `MailSendUtils.ts`).
+ *
+ * **Pragmatic subset, deliberately not the full MS-ASCMD semantics**:
+ * - `SmartForward`/`SmartReply`'s `<Source>` (the message being forwarded/replied to) is used only to thread
+ * the outgoing message (`inReplyTo`/`references`) and to flip the original's `Answered`/`Forwarded` flag - the
+ * real spec has the *server* splice the original message's full content into the outgoing MIME so the client
+ * never has to download-then-reupload it; this pragmatic subset instead expects the client's own `<Mime>` to
+ * already be the complete outgoing message (which is what every mainstream client's own compose UI naturally
+ * produces once it has fetched the original for display), matching this library's "pragmatic subset, not full
+ * fidelity" precedent elsewhere (e.g. `FolderSyncCommand`'s SyncKey replay-protection gap).
+ * - `ReplaceMime`/`AccountId`/`InstanceId` are not read - single-account, non-recurring-meeting compose only.
+ * - Attachments present in the composed MIME are relayed correctly (`scanAndRelay()`'s `ScanPipeline` handles
+ * the full raw message) but are not additionally persisted as `Attachment` records on the saved Sent Items
+ * copy - `Message.hasAttachments` is still set correctly from the parsed MIME, just not each attachment's own
+ * row (deferred, matching `ItemOperationsCommand`'s own future `Fetch`-of-Sent-Items scope).
+ *
+ * `folderClass`/`messageClass` are supplied by the Mongo/SQL concrete subclasses, and `markOriginal()` by the
+ * `SmartForwardCommand`/`SmartReplyCommand` subclasses (a no-op here, since plain `SendMailCommand` never has a
+ * `<Source>` to act on).
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class ComposeMailCommand implements EasCommandHandler {
+    abstract readonly command: string;
+    protected abstract folderClass: any;
+    protected abstract messageClass: any;
+    private _objectFactory?;
+    protected folderRepo?: RecoverableRepoUtils<any>;
+    protected messageRepo?: RecoverableRepoUtils<any>;
+    private blobStore?;
+    private mailTransport?;
+    private scanPipeline?;
+    private aclUtils?;
+    init(): Promise<void>;
+    /** Called once the outgoing message has been sent, only when the request carried a `<Source>` (i.e. this
+     * is a `SmartForward`/`SmartReply`, never a plain `SendMail`) - flips the referenced original message's own
+     * `Answered`/`Forwarded` flag. A no-op here; overridden by the two subclasses that need it. */
+    protected markOriginal(_ctx: EasCommandContext, _original: Message & {
+        uid: string;
+    }): Promise<void>;
+    handle(ctx: EasCommandContext): Promise<WbxmlElement | undefined>;
+}

package/dist/types/commands/FolderSyncCommand.d.ts

@@ -0,0 +1,25 @@
+import { type WbxmlElement } from "../codec/WbxmlElement.js";
+import type { EasCommandContext, EasCommandHandler } from "../EasCommandHandler.js";
+import { Folder } from "@rapidmx/restapi";
+/**
+ * Handles EAS `FolderSync`: enumerates `Add`/`Update`/`Delete`s for the caller's mailbox's `Folder` hierarchy
+ * since the device's last `FolderSync`, using the shared watermark-based cursor mechanism in
+ * `EasSyncKeyUtils.ts` (scoped by `mailboxUid` over the `Folder` collection, rather than `folderUid` over a
+ * per-folder item collection the way `SyncCommand` will be).
+ *
+ * `folderClass` is supplied by the Mongo/SQL concrete subclasses, following the exact one-line-per-backend
+ * pattern used throughout this library's other routes/jobs.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class FolderSyncCommand<F extends Folder> implements EasCommandHandler {
+    readonly command = "FolderSync";
+    protected abstract folderClass: any;
+    private windowSize;
+    private _objectFactory?;
+    private folderRepo?;
+    init(): Promise<void>;
+    handle(ctx: EasCommandContext): Promise<WbxmlElement | undefined>;
+    private folderToChangeElement;
+    private persistSyncKey;
+}

package/dist/types/commands/GetItemEstimateCommand.d.ts

@@ -0,0 +1,43 @@
+import { type WbxmlElement } from "../codec/WbxmlElement.js";
+import type { EasCommandContext, EasCommandHandler } from "../EasCommandHandler.js";
+/** Binds one MS-ASCMD `Class` value to the concrete entity class this command counts against - a lighter
+ * version of `SyncCommand`'s own `SyncCollectionBinding` (no adapter needed at all, since `GetItemEstimate`
+ * never serializes an item, only counts them). Supplied by the Mongo/SQL concrete subclasses. */
+export interface EstimateCollectionBinding {
+    entityClass: any;
+}
+/**
+ * Handles EAS `GetItemEstimate`: reports, per requested `<Collection>`, an estimated count of the
+ * `Add`/`Change`/`Delete`s a subsequent `Sync` of that collection would return - read-only, it never issues or
+ * consumes a `SyncKey` itself.
+ *
+ * The modern (14.0+) request/response reuses `WbxmlCodePage.AirSync`'s own `Collections`/`Collection`/`Class`/
+ * `CollectionId`/`SyncKey` via `SWITCH_PAGE` rather than this page's own legacy (`Folders`/`Folder`/`FolderId`)
+ * shape - see `WbxmlCodePages.ts`'s own doc comment on `WbxmlCodePage.ItemEstimate` for why, and
+ * `ItemOperationsCommand.fetchMessage`'s identical cross-page-reuse precedent.
+ *
+ * A `SyncKey` of `"0"` (or one this device has never synced this folder with before) reports the folder's
+ * total live item count - what a first `Sync` would report as `Add`s. Otherwise reuses `EasSyncKeyUtils.
+ * computeChanges()` (the same enumeration `SyncCommand` itself uses), capped at `DEFAULT_MAX_COUNT` - see its
+ * own doc comment for why this is a real, documented approximation on a very active folder rather than a
+ * precise unbounded count.
+ *
+ * **ACL-checked like `Sync`**: `estimateCollection()` requires `ACLAction.READ` on the client-supplied
+ * `CollectionId` before counting anything - without it, a crafted `CollectionId` belonging to another
+ * mailbox's folder would return a real pending-change count for it. A denied folder is reported identically to
+ * an unrecognized collection (`Status 2`), never distinguishable from "you don't have this collection at all".
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class GetItemEstimateCommand implements EasCommandHandler {
+    readonly command = "GetItemEstimate";
+    protected abstract collectionBindings: Record<string, EstimateCollectionBinding>;
+    private maxCount;
+    private _objectFactory?;
+    private aclUtils?;
+    private repos;
+    init(): Promise<void>;
+    handle(ctx: EasCommandContext): Promise<WbxmlElement | undefined>;
+    private estimateCollection;
+    private collectionElement;
+}