@rapidmx/activesync 1.0.0-beta.0

package/dist/lib/BaseEasRoute.js

@@ -0,0 +1,213 @@
+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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiError, ObjectDecorators } from "@rapidrest/core";
+import { ApiErrorMessages, ApiErrors, RepoUtils, RouteDecorators, } from "@rapidrest/service-core";
+import { WbxmlDecoder } from "./codec/WbxmlDecoder.js";
+import { WbxmlEncoder } from "./codec/WbxmlEncoder.js";
+import { persistDeviceSyncState } from "./EasSyncKeyUtils.js";
+import { resolveCallerMailboxUid } from "@rapidmx/restapi";
+const { Init, Logger } = ObjectDecorators;
+const { Auth, Options, Post, Request, Response, User: AuthUser } = RouteDecorators;
+/** HTTP 449 ("Retry With") is not a standard HTTP status, but is the long-established Exchange ActiveSync
+ * convention a real client recognizes as "you must successfully complete `Provision` before this command will
+ * be honored" - simpler than constructing a command-specific WBXML error body for every possible command a
+ * client might send before it's provisioned. */
+const HTTP_STATUS_RETRY_WITH = 449;
+/** `MS-ASProtocolVersions` value this library actually implements against: confirmed via `[MS-ASHTTP]` that
+ * "14.0"/"14.1" are the versions whose `ComposeMail`/`Email2` WBXML code pages cover MIME-based
+ * `SendMail`/`SmartForward`/`SmartReply` (what `ComposeMailCommand` actually sends) - not 12.x (which predates
+ * MIME-based compose). `16.0`/`16.1` are now included too, now that `SettingsCommand` implements `Oof` (their
+ * other headline addition, `RightsManagementInformation`, remains unimplemented, but that alone doesn't gate
+ * the version string - `MS-ASProtocolCommands` below is the real capability gate, derived live from
+ * `this.handlers`, so a client probing capabilities correctly sees any specific unsupported command regardless
+ * of which protocol versions are declared, exactly as it already does for `GetItemEstimate`/`MoveItems`/
+ * `ResolveRecipients`). No MS-ASCMD `Sync`/`FolderSync`/`Provision` schema element became newly mandatory
+ * between 14.1 and 16.1 outside `Oof`/IRM. Ascending, matching the order Microsoft's own spec lists them in. */
+const MS_AS_PROTOCOL_VERSIONS = "14.0,14.1,16.0,16.1";
+function firstQueryValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+/**
+ * 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 class BaseEasRoute {
+    constructor() {
+        /** 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. */
+        this.commandHandlerClasses = [];
+        this.handlers = new Map();
+    }
+    async init() {
+        this.deviceSyncStateRepo = await this._objectFactory.newInstance(RepoUtils, {
+            name: this.deviceSyncStateClass.name,
+            args: [this.deviceSyncStateClass],
+        });
+        this.mailboxRepo = await this._objectFactory.newInstance(RepoUtils, {
+            name: this.mailboxClass.name,
+            args: [this.mailboxClass],
+        });
+        for (const HandlerClass of this.commandHandlerClasses) {
+            const handler = await this._objectFactory.newInstance(HandlerClass);
+            this.handlers.set(handler.command, handler);
+        }
+    }
+    /**
+     * 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`.
+     */
+    async options(res) {
+        res.setHeader("MS-ASProtocolVersions", MS_AS_PROTOCOL_VERSIONS)
+            .setHeader("MS-ASProtocolCommands", Array.from(this.handlers.keys()).join(","))
+            .status(200)
+            .send();
+    }
+    async dispatch(req, res, user) {
+        if (!this.deviceSyncStateRepo || !this.mailboxRepo) {
+            throw new ApiError(ApiErrors.INTERNAL_ERROR, 500, ApiErrorMessages.INTERNAL_ERROR);
+        }
+        if (!user) {
+            throw new ApiError(ApiErrors.AUTH_PERMISSION_FAILURE, 403, ApiErrorMessages.AUTH_PERMISSION_FAILURE);
+        }
+        const cmd = firstQueryValue(req.query["Cmd"]);
+        const deviceId = firstQueryValue(req.query["DeviceId"]);
+        const deviceType = firstQueryValue(req.query["DeviceType"]) ?? "Unknown";
+        const policyKey = firstQueryValue(req.query["PolicyKey"]);
+        if (!cmd || !deviceId) {
+            throw new ApiError(ApiErrors.INVALID_REQUEST, 400, ApiErrorMessages.INVALID_REQUEST);
+        }
+        const mailboxUid = await resolveCallerMailboxUid(this.mailboxRepo, user);
+        if (!mailboxUid) {
+            throw new ApiError(ApiErrors.NOT_FOUND, 404, ApiErrorMessages.NOT_FOUND);
+        }
+        const deviceSyncState = await this.findOrCreateDeviceSyncState(mailboxUid, deviceId, deviceType);
+        // Every command except the two that must work on an unprovisioned device (Provision itself, and
+        // Settings - real clients query Settings/DeviceInformation as part of first-run setup, before
+        // provisioning completes) requires the device to have already been provisioned.
+        if (!deviceSyncState.provisioned && cmd !== "Provision" && cmd !== "Settings") {
+            res.status(HTTP_STATUS_RETRY_WITH).send();
+            return;
+        }
+        const handler = this.handlers.get(cmd);
+        if (!handler) {
+            res.status(501).send();
+            return;
+        }
+        const request = req.rawBody && req.rawBody.length > 0 ? new WbxmlDecoder().decode(req.rawBody) : undefined;
+        const response = await handler.handle({
+            user,
+            mailboxUid,
+            deviceId,
+            deviceType,
+            policyKey,
+            deviceSyncState,
+            deviceSyncStateRepo: this.deviceSyncStateRepo,
+            query: req.query,
+            request,
+            req,
+        });
+        await persistDeviceSyncState(deviceSyncState, this.deviceSyncStateRepo, { lastSyncAt: new Date() });
+        if (!response) {
+            res.status(200).send();
+            return;
+        }
+        const buffer = new WbxmlEncoder().encode(response);
+        res.setHeader("Content-Type", "application/vnd.ms-sync.wbxml")
+            .setHeader("Content-Length", buffer.length)
+            .status(200)
+            .send(buffer);
+    }
+    async findOrCreateDeviceSyncState(mailboxUid, deviceId, deviceType) {
+        const existing = await this.deviceSyncStateRepo.find({ mailboxUid, deviceId }, { ignoreACL: true, limit: 1 });
+        if (existing[0]) {
+            return existing[0];
+        }
+        const instance = this.deviceSyncStateRepo.instantiateObject({
+            mailboxUid,
+            deviceId,
+            deviceType,
+            folderSyncKeys: {},
+            provisioned: false,
+        });
+        return await this.deviceSyncStateRepo.create(instance, { ignoreACL: true });
+    }
+}
+__decorate([
+    Logger,
+    __metadata("design:type", Object)
+], BaseEasRoute.prototype, "logger", void 0);
+__decorate([
+    Init,
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], BaseEasRoute.prototype, "init", null);
+__decorate([
+    Options(),
+    __param(0, Response),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], BaseEasRoute.prototype, "options", null);
+__decorate([
+    Auth(["jwt"]),
+    Post(),
+    __param(0, Request),
+    __param(1, Response),
+    __param(2, AuthUser),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], BaseEasRoute.prototype, "dispatch", null);
+//# sourceMappingURL=BaseEasRoute.js.map

package/dist/lib/BaseEasRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseEasRoute.js","sourceRoot":"","sources":["../../src/BaseEasRoute.ts"],"names":[],"mappings":"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"}

package/dist/lib/CompactDateTime.js

@@ -0,0 +1,43 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * 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 function toCompactDateTime(date) {
+    const d = date instanceof Date ? date : new Date(date);
+    const pad = (n) => String(n).padStart(2, "0");
+    return (`${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}` +
+        `T${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`);
+}
+/** Anchored strictly to `toCompactDateTime`'s own output shape (`YYYYMMDDTHHMMSSZ`) - a client sending
+ * anything else has sent a malformed item, which the caller (an `EasCollectionSyncAdapter.fromApplicationData`
+ * implementation) should treat as `Status 6` rather than silently guessing. */
+const COMPACT_DATE_TIME_PATTERN = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
+/**
+ * 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 function fromCompactDateTime(value) {
+    const match = COMPACT_DATE_TIME_PATTERN.exec(value);
+    if (!match) {
+        throw new Error(`Not a valid Compact DateTime value: '${value}'`);
+    }
+    const [, year, month, day, hour, minute, second] = match;
+    return new Date(Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second)));
+}
+//# sourceMappingURL=CompactDateTime.js.map

package/dist/lib/CompactDateTime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompactDateTime.js","sourceRoot":"","sources":["../../src/CompactDateTime.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAmB;IACjD,MAAM,CAAC,GAAG,IAAI,YAAY,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,OAAO,CACH,GAAG,CAAC,CAAC,cAAc,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE;QACxE,IAAI,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,GAAG,CAChF,CAAC;AACN,CAAC;AAED;;+EAE+E;AAC/E,MAAM,yBAAyB,GAAG,gDAAgD,CAAC;AAEnF;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC7C,MAAM,KAAK,GAAG,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,wCAAwC,KAAK,GAAG,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;IACzD,OAAO,IAAI,IAAI,CACX,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CACvG,CAAC;AACN,CAAC"}

package/dist/lib/EasCommandHandler.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=EasCommandHandler.js.map

package/dist/lib/EasCommandHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EasCommandHandler.js","sourceRoot":"","sources":["../../src/EasCommandHandler.ts"],"names":[],"mappings":""}

package/dist/lib/EasSyncKeyUtils.js

@@ -0,0 +1,119 @@
+/** Formats a `SyncKey` back into its wire string form. */
+export function formatSyncKey(key) {
+    return `${key.generation}:${key.watermark.toISOString()}`;
+}
+/** 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 function parseSyncKey(value) {
+    const separator = value.indexOf(":");
+    if (separator === -1) {
+        return undefined;
+    }
+    const generation = Number(value.slice(0, separator));
+    const watermark = new Date(value.slice(separator + 1));
+    if (!Number.isFinite(generation) || Number.isNaN(watermark.getTime())) {
+        return undefined;
+    }
+    return { generation, watermark };
+}
+/**
+ * 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 function resolveSyncKey(clientValue, storedValue) {
+    if (!clientValue || clientValue === "0") {
+        return { kind: "initial" };
+    }
+    if (storedValue === undefined || clientValue !== storedValue) {
+        return { kind: "invalid" };
+    }
+    const parsed = parseSyncKey(storedValue);
+    return parsed ? { kind: "valid", key: parsed } : { kind: "invalid" };
+}
+/**
+ * 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 async function persistDeviceSyncState(deviceSyncState, deviceSyncStateRepo, patch) {
+    Object.assign(deviceSyncState, patch);
+    const updated = await deviceSyncStateRepo.update({ uid: deviceSyncState.uid, version: deviceSyncState.version, ...patch }, deviceSyncState, { ignoreACL: true, skipPush: true });
+    Object.assign(deviceSyncState, updated);
+}
+/** A tolerance window for treating a row's `dateCreated`/`dateModified` as "close enough" to be an `Add`
+ * rather than a `Change` - the two are set within the same request handler and so are typically only
+ * milliseconds apart, never exactly equal down to the microsecond depending on the datastore's clock
+ * resolution. */
+const NEWLY_CREATED_TOLERANCE_MS = 1000;
+/**
+ * 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 async function computeChanges(repo, scopeField, scopeUid, watermark, windowSize) {
+    // Overfetch by one (per stream) so a full window can be distinguished from an exact-fit window without a
+    // separate count() round trip - the same trick `ExternalShareExpirationJob`/`MailboxQuotaRecalcJob` already
+    // use for their own MoreAvailable-shaped bookkeeping. `limit`/`sort` must be baked into the query object
+    // itself (not just `options`) for the SQL backend - see those same jobs' comments on this exact requirement.
+    const baseCriteria = { [scopeField]: scopeUid, dateModified: `gt(${watermark.toISOString()})` };
+    const findOptions = { ignoreACL: true, limit: windowSize + 1, sort: "dateModified" };
+    const [liveRows, deletedRows] = await Promise.all([
+        repo.find({ ...baseCriteria, sort: "dateModified", limit: windowSize + 1 }, findOptions),
+        repo.find({ ...baseCriteria, deleted: true, sort: "dateModified", limit: windowSize + 1 }, findOptions),
+    ]);
+    const merged = [...liveRows, ...deletedRows].sort((a, b) => new Date(a.dateModified).getTime() - new Date(b.dateModified).getTime());
+    const moreAvailable = merged.length > windowSize;
+    const page = moreAvailable ? merged.slice(0, windowSize) : merged;
+    const adds = [];
+    const changes = [];
+    const deletes = [];
+    let newWatermark = watermark;
+    for (const row of page) {
+        const dateModified = new Date(row.dateModified);
+        if (dateModified.getTime() > newWatermark.getTime()) {
+            newWatermark = dateModified;
+        }
+        if (row.deleted === true) {
+            deletes.push(row);
+        }
+        else {
+            const dateCreated = new Date(row.dateCreated);
+            const isNewlyCreated = Math.abs(dateModified.getTime() - dateCreated.getTime()) < NEWLY_CREATED_TOLERANCE_MS;
+            (isNewlyCreated ? adds : changes).push(row);
+        }
+    }
+    return { adds, changes, deletes, newWatermark, moreAvailable };
+}
+//# sourceMappingURL=EasSyncKeyUtils.js.map

package/dist/lib/EasSyncKeyUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EasSyncKeyUtils.js","sourceRoot":"","sources":["../../src/EasSyncKeyUtils.ts"],"names":[],"mappings":"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"}