@rapidmx/activesync-plugin 1.0.0-beta.2

package/dist/lib/sql/EasRouteSQL.js

@@ -0,0 +1,63 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { MailboxSQL } from "@rapidmx/restapi/sql";
+import { RouteDecorators } from "@rapidrest/service-core";
+import { DeviceSyncStateSQL } from "../models/sql/DeviceSyncStateSQL.js";
+import { BaseEasRoute } from "../BaseEasRoute.js";
+import { ProvisionCommand } from "../commands/ProvisionCommand.js";
+import { PingCommand } from "../commands/PingCommand.js";
+import { FolderSyncCommandSQL } from "../commands/sql/FolderSyncCommandSQL.js";
+import { SyncCommandSQL } from "../commands/sql/SyncCommandSQL.js";
+import { SendMailCommandSQL } from "../commands/sql/SendMailCommandSQL.js";
+import { SmartForwardCommandSQL } from "../commands/sql/SmartForwardCommandSQL.js";
+import { SmartReplyCommandSQL } from "../commands/sql/SmartReplyCommandSQL.js";
+import { ItemOperationsCommandSQL } from "../commands/sql/ItemOperationsCommandSQL.js";
+import { SearchCommandSQL } from "../commands/sql/SearchCommandSQL.js";
+import { MeetingResponseCommandSQL } from "../commands/sql/MeetingResponseCommandSQL.js";
+import { SettingsCommandSQL } from "../commands/sql/SettingsCommandSQL.js";
+import { GetItemEstimateCommandSQL } from "../commands/sql/GetItemEstimateCommandSQL.js";
+import { MoveItemsCommandSQL } from "../commands/sql/MoveItemsCommandSQL.js";
+import { ResolveRecipientsCommandSQL } from "../commands/sql/ResolveRecipientsCommandSQL.js";
+const { Route } = RouteDecorators;
+/**
+ * SQL-backed concrete `BaseEasRoute`, mounted at the protocol's well-known path. Exported from this plugin's
+ * `./sql` entry point.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+let EasRouteSQL = class EasRouteSQL extends BaseEasRoute {
+    constructor() {
+        super(...arguments);
+        this.deviceSyncStateClass = DeviceSyncStateSQL;
+        this.mailboxClass = MailboxSQL;
+        this.commandHandlerClasses = [
+            ProvisionCommand,
+            FolderSyncCommandSQL,
+            SyncCommandSQL,
+            SendMailCommandSQL,
+            SmartForwardCommandSQL,
+            SmartReplyCommandSQL,
+            ItemOperationsCommandSQL,
+            SearchCommandSQL,
+            MeetingResponseCommandSQL,
+            SettingsCommandSQL,
+            PingCommand,
+            GetItemEstimateCommandSQL,
+            MoveItemsCommandSQL,
+            ResolveRecipientsCommandSQL,
+        ];
+    }
+};
+EasRouteSQL = __decorate([
+    Route("/Microsoft-Server-ActiveSync")
+], EasRouteSQL);
+export { EasRouteSQL };
+//# sourceMappingURL=EasRouteSQL.js.map

package/dist/lib/sql/EasRouteSQL.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EasRouteSQL.js","sourceRoot":"","sources":["../../../src/sql/EasRouteSQL.ts"],"names":[],"mappings":";;;;;;AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,8CAA8C,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,yBAAyB,EAAE,MAAM,8CAA8C,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAC7E,OAAO,EAAE,2BAA2B,EAAE,MAAM,gDAAgD,CAAC;AAC7F,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC;AAElC;;;;;GAKG;AAEI,IAAM,WAAW,GAAjB,MAAM,WAAY,SAAQ,YAA4C;IAAtE;;QACO,yBAAoB,GAAQ,kBAAkB,CAAC;QAC/C,iBAAY,GAAQ,UAAU,CAAC;QAC/B,0BAAqB,GAAU;YACrC,gBAAgB;YAChB,oBAAoB;YACpB,cAAc;YACd,kBAAkB;YAClB,sBAAsB;YACtB,oBAAoB;YACpB,wBAAwB;YACxB,gBAAgB;YAChB,yBAAyB;YACzB,kBAAkB;YAClB,WAAW;YACX,yBAAyB;YACzB,mBAAmB;YACnB,2BAA2B;SAC9B,CAAC;IACN,CAAC;CAAA,CAAA;AAnBY,WAAW;IADvB,KAAK,CAAC,8BAA8B,CAAC;GACzB,WAAW,CAmBvB"}

package/dist/lib/sql/index.js

@@ -0,0 +1,9 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+export * from "./EasRouteSQL.js";
+export * from "./DeviceSyncStateRouteSQL.js";
+export * from "../commands/sql/index.js";
+export * from "../adapters/sql/index.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sql/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC"}

package/dist/lib/sql.js

@@ -0,0 +1,15 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * This plugin's `./sql` entry point: exactly the classes a server host loads for a SQL deployment - the
+ * mounted routes, the device-state model and its cleanup job. Anything else exported here would be registered
+ * by the host too (and an abstract `BackgroundService` would even be started), so the command and adapter
+ * classes these routes use stay internal.
+ */
+export { EasRouteSQL } from "./sql/EasRouteSQL.js";
+export { DeviceSyncStateRouteSQL } from "./sql/DeviceSyncStateRouteSQL.js";
+export { DeviceSyncStateSQL } from "./models/sql/DeviceSyncStateSQL.js";
+export { EasDeviceStateCleanupJobSQL } from "./jobs/sql/EasDeviceStateCleanupJobSQL.js";
+//# sourceMappingURL=sql.js.map

package/dist/lib/sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.js","sourceRoot":"","sources":["../../src/sql.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E;;;;;GAKG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2CAA2C,CAAC"}

package/dist/types/BaseDeviceSyncStateRoute.d.ts

@@ -0,0 +1,34 @@
+import { type JWTUser } from "@rapidrest/core";
+import { HttpRequest } from "@rapidrest/service-core";
+import type { DeviceSyncState } from "./models/DeviceSyncState.js";
+/**
+ * Admin-only trigger for the `RemoteWipe` sub-flow `ProvisionCommand` implements. `restapi` has no route of its
+ * own for `DeviceSyncState` (it's a protocol-internal entity, not a domain object a normal API consumer ever
+ * lists or edits directly), so this lives here instead, following the exact `trustedRoles`/`UserUtils.hasRoles`
+ * gating pattern `BaseMailboxRoute` already uses for its own admin-vs-owner scoping.
+ *
+ * Setting `remoteWipeRequested: true` (and `provisioned: false` alongside it) is the entire trigger: the next
+ * request that device makes of any kind is already forced back through `Provision` by `BaseEasRoute.dispatch()`'s
+ * existing 449 gate, at which point `ProvisionCommand.issuePolicy` sees the flag and sends the device a
+ * `RemoteWipe` directive instead of a normal policy document - no separate push/notification channel is needed.
+ *
+ * `deviceSyncStateClass` is supplied by the Mongo/SQL concrete subclasses, the same one-line-per-backend
+ * pattern used throughout this library.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class BaseDeviceSyncStateRoute<D extends DeviceSyncState> {
+    protected abstract deviceSyncStateClass: any;
+    protected trustedRoles: string[];
+    private _objectFactory?;
+    private deviceSyncStateRepo?;
+    private getDeviceSyncStateRepo;
+    /**
+     * Marks `uid` (a `DeviceSyncState`'s own id, not a device id string - the admin looks this up via whatever
+     * device-listing view a deployment builds on top of `DeviceSyncState`'s ordinary CRUD, out of scope here)
+     * for remote wipe. Optional JSON body `{ accountOnly?: boolean }` — recorded for admin audit only; see
+     * `ProvisionCommand`'s own doc comment for why the wire directive sent to the device doesn't distinguish
+     * the two.
+     */
+    remoteWipe(uid: string, req: HttpRequest, user?: JWTUser): Promise<D>;
+}

package/dist/types/BaseEasRoute.d.ts

@@ -0,0 +1,65 @@
+import { type JWTUser } from "@rapidrest/core";
+import { HttpRequest, HttpResponse } from "@rapidrest/service-core";
+import { Mailbox } from "@rapidmx/restapi";
+import { DeviceSyncState } from "./models/DeviceSyncState.js";
+/**
+ * Abstract base for the single fixed EAS endpoint (`POST /Microsoft-Server-ActiveSync` by MS-ASHTTP
+ * convention, though the concrete path is left to the consuming application to mount via `@Route(...)` — see
+ * `BaseMailIngestRoute.ts` for the identical undecorated-base-class pattern this follows). Unlike every other
+ * route in this library, EAS dispatches on a `Cmd` query parameter against one URL rather than path-based REST
+ * routing, so there is exactly one `@Post()` method here, not one per operation.
+ *
+ * **Auth**: `@Auth(["jwt"])` — the framework's own default strategy, unchanged from every other route in this
+ * app. A real native EAS client obtaining that JWT in the first place (rather than the app's own web/API
+ * clients, which already have one) requires an OAuth 2.0 Authorization Server capability this library
+ * deliberately does not implement itself — see the architecture plan's "Auth" section for the full reasoning
+ * behind this choice over a per-request Basic Auth strategy.
+ *
+ * **Dispatch flow**: resolve the caller's own `Mailbox` (never a client-supplied one — `resolveCallerMailboxUid`,
+ * the same helper `BaseSearchRoute` already uses), find-or-create that (mailbox, device) pair's
+ * `DeviceSyncState`, enforce the provisioning gate, decode the WBXML request body (if any), dispatch to the
+ * matching registered `EasCommandHandler`, bump `lastSyncAt`, and encode the handler's response back to WBXML.
+ *
+ * **Command handlers** are supplied via `commandHandlerClasses` (empty by default — this class alone is just
+ * the transport skeleton; concrete command support, e.g. `ProvisionCommand`/`FolderSyncCommand`, is added
+ * incrementally in later work by having a concrete subclass populate this array) and instantiated once each in
+ * `@Init` via `ObjectFactory`, so a handler can `@Inject` its own dependencies like any other DI-managed class
+ * in this library.
+ *
+ * **`OPTIONS` protocol discovery**: real EAS clients conventionally probe `OPTIONS` before their first `POST`
+ * to read `MS-ASProtocolVersions`/`MS-ASProtocolCommands` and learn what the server supports - see `options()`
+ * below. This requires `@rapidrest/service-core` >=1.5.0, whose global CORS middleware consults
+ * `IHttpRouter.hasExplicitOptionsRoute()` before its blanket preflight `204` - confirmed live end to end
+ * against a real `service-core` 1.5.0 install (`test/routes/{mongo,sql}/EasRoute.test.ts`'s `OPTIONS`
+ * describe block), not assumed.
+ *
+ * `deviceSyncStateClass`/`mailboxClass` are 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 BaseEasRoute<D extends DeviceSyncState, M extends Mailbox = Mailbox> {
+    protected abstract deviceSyncStateClass: any;
+    protected abstract mailboxClass: any;
+    /** Command handler classes to instantiate (one each) in `@Init`. Empty until a concrete command lands -
+     * every request is then answered with HTTP 501 (see `dispatch()`), which is the correct, honest behavior
+     * for a transport skeleton with no commands implemented yet, not a bug to work around. */
+    protected commandHandlerClasses: any[];
+    private _objectFactory?;
+    private deviceSyncStateRepo?;
+    private mailboxRepo?;
+    private readonly handlers;
+    private logger;
+    init(): Promise<void>;
+    /**
+     * Answers a real client's pre-flight `MS-ASProtocolVersions`/`MS-ASProtocolCommands` capability probe -
+     * see this class's own doc comment for the `service-core` version dependency this needs to actually run.
+     * Deliberately unauthenticated (no `@Auth`): this is capability discovery, not mailbox access, and a real
+     * Exchange server answers it the same way regardless of credentials. `MS-ASProtocolCommands` is built from
+     * `this.handlers`, not a separately-maintained list, so it can never drift out of sync with the commands a
+     * concrete subclass actually registered via `commandHandlerClasses`.
+     */
+    options(res: HttpResponse): Promise<void>;
+    dispatch(req: HttpRequest, res: HttpResponse, user?: JWTUser): Promise<void>;
+    private findOrCreateDeviceSyncState;
+}

package/dist/types/CompactDateTime.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Formats a date as MS-ASDTYPE's "Compact DateTime" (`YYYYMMDDTHHMMSSZ`, always UTC) - the format
+ * `Calendar`/`Tasks` timestamp fields (`StartTime`/`EndTime`/`UtcDueDate`/...) use, distinct from the plain
+ * `dateTime` type (`YYYY-MM-DDTHH:MM:SS.MSSZ`, i.e. `Date.prototype.toISOString()`) `Email`'s `DateReceived`
+ * uses - confirmed against the published MS-ASDTYPE spec (`2.7.2 Compact DateTime` vs `2.7 dateTime Data
+ * Type`), not assumed, since sending the wrong one is exactly the kind of silent-until-a-real-device-connects
+ * bug this library's WBXML codec work already ran into once with tag casing (`"Mime"` vs `"MIME"`).
+ *
+ * Accepts `Date | string` and normalizes via `new Date(...)` - a real, discovered-by-testing gap: fields
+ * embedded inside a `simple-json` column (e.g. `RecurrenceRule.until`) round-trip through `JSON.stringify`/
+ * `JSON.parse` on the SQL backend, which does not preserve `Date` instances, so `until` comes back as a plain
+ * ISO string there even though the Mongo backend (native BSON dates) hands back a real `Date` for the exact
+ * same field - a caller passing either must work on both backends without knowing which one it's talking to.
+ */
+export declare function toCompactDateTime(date: Date | string): string;
+/**
+ * Parses MS-ASDTYPE's "Compact DateTime" (`YYYYMMDDTHHMMSSZ`) back into a `Date` - the reverse of
+ * `toCompactDateTime`, needed for `Sync`'s client-originated `Add`/`Change` commands on `Calendar`/`Tasks`.
+ * Throws (rather than returning an unvalidated `Date` that would silently carry `NaN`s) for anything not
+ * matching the exact expected shape.
+ */
+export declare function fromCompactDateTime(value: string): Date;

package/dist/types/EasCommandHandler.d.ts

@@ -0,0 +1,59 @@
+import type { JWTUser } from "@rapidrest/core";
+import type { HttpRequest, RepoUtils } from "@rapidrest/service-core";
+import type { WbxmlElement } from "./codec/WbxmlElement.js";
+import type { DeviceSyncState } from "./models/DeviceSyncState.js";
+/**
+ * Everything an `EasCommandHandler` needs to process one dispatched EAS command — assembled once by
+ * `BaseEasRoute.dispatch()` per request and handed to whichever handler matches `?Cmd=`.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface EasCommandContext {
+    /** The authenticated caller, per the same `@AuthUser` JWT payload every other route in this library reads. */
+    readonly user: JWTUser;
+    /** The `Mailbox` this request operates against — resolved server-side from `user` (`ownerUserUid`), never
+     * taken from client input. */
+    readonly mailboxUid: string;
+    /** The client-supplied `?DeviceId=` query value, identifying this device within the mailbox. */
+    readonly deviceId: string;
+    /** The client-supplied `?DeviceType=` query value (e.g. `iPhone`, `Android`). */
+    readonly deviceType: string;
+    /** The client-supplied `?PolicyKey=` query value, if present - the provisioning policy key the device is
+     * currently operating under. Not yet validated against `deviceSyncState.policyKey` here (deferred to
+     * `ProvisionCommand`'s own implementation); handlers that care should compare it themselves for now. */
+    readonly policyKey?: string;
+    /** This device's persisted sync/provisioning state, looked up (or newly created) by `BaseEasRoute` before
+     * dispatch. Handlers read/write cursor and provisioning fields on this directly. */
+    readonly deviceSyncState: DeviceSyncState;
+    /** The live repo backing `deviceSyncState`'s concrete entity class, for handlers that need to persist a
+     * change to it (e.g. a new `SyncKey`, an updated `policyKey`, flipping `provisioned`). Typed `RepoUtils<any>`
+     * rather than `RepoUtils<DeviceSyncState>` deliberately - `RepoUtils<D>`'s underlying TypeORM `Repository<D>`
+     * is not covariant in `D` (a handful of its methods, e.g. `sum()`, use `D`-dependent conditional types), so
+     * `BaseEasRoute`'s own `RepoUtils<D>` (for its concrete `D extends DeviceSyncState`) cannot be narrowed to
+     * this field's type without `any` somewhere in between. */
+    readonly deviceSyncStateRepo: RepoUtils<any>;
+    /** Every query-string parameter on the request, for the handful of commands with additional command-
+     * specific query parameters beyond the common four already broken out above. */
+    readonly query: Record<string, string | string[]>;
+    /** The decoded WBXML request body, or `undefined` for a command sent with an empty body (legal for a few
+     * commands, e.g. a bare `GetItemEstimate`-less `Ping` continuation). */
+    readonly request?: WbxmlElement;
+    /** The raw underlying HTTP request, for the rare handler that needs something this context doesn't
+     * already surface (e.g. a header). */
+    readonly req: HttpRequest;
+}
+/**
+ * One EAS protocol command (`Provision`, `FolderSync`, `Sync`, ...). `BaseEasRoute` builds one instance of
+ * each registered handler class in its own `@Init` (via `ObjectFactory`, so a handler can `@Inject` its own
+ * dependencies exactly like any other DI-managed class in this library) and dispatches to the one whose
+ * `command` matches the request's `?Cmd=` value.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface EasCommandHandler {
+    /** The exact `?Cmd=` value this handler answers to (e.g. `"FolderSync"`). */
+    readonly command: string;
+    /** Processes the command and returns the WBXML element tree to send back as the response body, or
+     * `undefined` for a command whose successful response is legitimately empty. */
+    handle(ctx: EasCommandContext): Promise<WbxmlElement | undefined>;
+}

package/dist/types/EasSyncKeyUtils.d.ts

@@ -0,0 +1,89 @@
+import type { RecoverableBaseEntity, RepoUtils } from "@rapidrest/service-core";
+import type { DeviceSyncState } from "./models/DeviceSyncState.js";
+/**
+ * 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,55 @@
+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`. May return a
+     * `Promise` - `EmailSyncAdapter` needs this to resolve `Message.labelUids` against the `Label` repo before
+     * rendering `Categories`; every other adapter today returns a plain `WbxmlElement`, which callers `await`
+     * through unchanged (the same optional-async shape `fromApplicationData` already established below). */
+    toApplicationData(item: T): WbxmlElement | Promise<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,71 @@
+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.
+ *
+ * Emits MS-ASEMAIL's `Categories`/`Category` (also read-only) from `Message.labelUids`, resolved against the
+ * `Label` repo to real display names - a stale `labelUids` entry (the label was since deleted) is silently
+ * dropped rather than surfacing as an error, the same "tolerate a dangling reference" stance `SearchCommand`
+ * already takes for a stale search-index entry. Deliberately not writable: unlike `Contact.categories` (a
+ * plain free-form string array with no separate entity behind it), a `Label` is a real mailbox-scoped entity
+ * referenced by uid - a write path would need to resolve category name strings back to `Label`s and create new
+ * ones on the fly for names that don't exist yet, real added scope this pragmatic subset defers. One `find()`
+ * per message that actually has labels (most won't, since labels are opt-in) - not batched across a whole Sync
+ * page/search result set, a documented, modest N+1 tradeoff rather than widening this adapter's own interface
+ * further to let a caller pre-resolve names for a whole batch.
+ *
+ * `labelClass` is supplied by the Mongo/SQL concrete subclasses.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class EmailSyncAdapter implements EasCollectionSyncAdapter<Message> {
+    readonly collectionClass = "Email";
+    protected abstract labelClass: any;
+    private _objectFactory?;
+    private labelRepo?;
+    private blobStore?;
+    init(): Promise<void>;
+    toApplicationData(message: Message): Promise<WbxmlElement>;
+    private resolveLabelNames;
+    /**
+     * `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;