@serve.zone/coremail 1.1.0 → 1.3.0

package/ts/coremail.persistence.ts

@@ -1,12 +1,12 @@
 import * as plugins from './plugins.js';
 import {
-  normalizeCoreMailConnectionInfo,
+  createCoreMailRawOutboundMessage,
   normalizeCoreMailEnvelope,
-  normalizeCoreMailGatewayMessage,
   normalizeCoreMailOutboundMessage,
 } from './coremail.validation.js';
 import type {
   ISubmissionPartRecord,
+  TCoreMailSubmissionSource,
   TTransferGrantPurpose,
 } from './interfaces.js';
 
@@ -49,6 +49,47 @@ export interface ICoreMailQuotaCounterRecord {
   updatedAt: number;
 }
 
+/**
+ * Per-binding, per-UTC-day outbound and inbound counters.
+ *
+ * Counted events are durable transitions, not requests: a replayed transition
+ * contributes nothing. Rows are retained for 90 days by the maintenance sweep.
+ */
+export interface ICoreMailStatCounterRecord {
+  statId: TCoreMailSha256;
+  tenantId: string;
+  serviceId: string;
+  bindingId: string;
+  /** UTC midnight of the counted day, in milliseconds. */
+  dayUtc: number;
+  submittedApi: number;
+  submittedSmtp: number;
+  delivered: number;
+  deferred: number;
+  failed: number;
+  deadLettered: number;
+  received: number;
+  acknowledgedProcessed: number;
+  acknowledgedDiscarded: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** Counter names an increment may target. */
+export const coreMailStatKinds = [
+  'submittedApi',
+  'submittedSmtp',
+  'delivered',
+  'deferred',
+  'failed',
+  'deadLettered',
+  'received',
+  'acknowledgedProcessed',
+  'acknowledgedDiscarded',
+] as const;
+
+export type TCoreMailStatKind = (typeof coreMailStatKinds)[number];
+
 export interface ICoreMailTransferGrantRecord {
   grantId: string;
   authorityKind: 'control' | 'gateway' | 'workload';
@@ -79,6 +120,14 @@ export interface ICoreMailSubmissionRecord {
   idempotencyKey: string;
   submissionDigest: TCoreMailSha256;
   state: plugins.serveZoneInterfaces.data.TCoreMailSubmissionState;
+  /** Absent on records persisted before the discriminator existed; read as 'api'. */
+  source?: TCoreMailSubmissionSource;
+  /**
+   * Set once, in the same transition that first publishes the immutable MIME.
+   * Its presence is what makes the submitted-counter increment exactly-once
+   * across an interrupted publication that finalization later repeats.
+   */
+  statsSubmittedCountedAt?: number;
   message: plugins.serveZoneInterfaces.data.ICoreMailOutboundMessageDescriptor;
   parts: ISubmissionPartRecord[];
   mimeObjectKey?: string;
@@ -608,6 +657,39 @@ export const assertCoreMailTransferGrantRecord = (
   }
 };
 
+export const assertCoreMailStatCounterRecord = (
+  valueArg: unknown,
+): asserts valueArg is ICoreMailStatCounterRecord => {
+  const value = requireRecord(
+    valueArg,
+    [
+      'statId',
+      'tenantId',
+      'serviceId',
+      'bindingId',
+      'dayUtc',
+      ...coreMailStatKinds,
+      'createdAt',
+      'updatedAt',
+    ],
+    [],
+    'CoreMailStatCounter',
+  );
+  requireSha256(value.statId, 'CoreMailStatCounter.statId');
+  requireIdentifier(value.tenantId, 'CoreMailStatCounter.tenantId');
+  requireIdentifier(value.serviceId, 'CoreMailStatCounter.serviceId');
+  requireIdentifier(value.bindingId, 'CoreMailStatCounter.bindingId');
+  const dayUtc = requireInteger(value.dayUtc, 'CoreMailStatCounter.dayUtc');
+  if (dayUtc % 86_400_000 !== 0) {
+    throw new Error('CoreMailStatCounter.dayUtc must be a UTC day boundary.');
+  }
+  for (const kind of coreMailStatKinds) {
+    requireInteger(value[kind], `CoreMailStatCounter.${kind}`);
+  }
+  requireInteger(value.createdAt, 'CoreMailStatCounter.createdAt');
+  requireInteger(value.updatedAt, 'CoreMailStatCounter.updatedAt');
+};
+
 export const assertCoreMailSubmissionRecord = (
   valueArg: unknown,
 ): asserts valueArg is ICoreMailSubmissionRecord => {
@@ -630,6 +712,8 @@ export const assertCoreMailSubmissionRecord = (
       'updatedAt',
     ],
     [
+      'source',
+      'statsSubmittedCountedAt',
       'mimeObjectKey',
       'mimeSha256',
       'mimeLengthBytes',
@@ -677,6 +761,17 @@ export const assertCoreMailSubmissionRecord = (
   if (!submissionStates.has(String(value.state))) {
     throw new Error('CoreMailSubmission.state is invalid.');
   }
+  if (
+    value.source !== undefined
+    && value.source !== 'api'
+    && value.source !== 'smtp'
+  ) {
+    throw new Error('CoreMailSubmission.source is invalid.');
+  }
+  // Records persisted before the discriminator existed are API submissions.
+  const source: TCoreMailSubmissionSource = value.source === undefined
+    ? 'api'
+    : value.source;
   const messageRecord = requireRecord(
     value.message,
     ['sender', 'recipients', 'subject', 'parts'],
@@ -689,50 +784,98 @@ export const assertCoreMailSubmissionRecord = (
     ['displayName'],
     'CoreMailSubmission.message.sender',
   );
-  const normalizedMessage = normalizeCoreMailOutboundMessage(value.message, {
-    schemaVersion: 2,
-    bindingId: String(value.bindingId),
-    serviceId: String(value.serviceId),
-    tenantId: String(value.tenantId),
-    revision: Number(value.bindingRevision),
-    state: 'active',
-    capabilities: ['outbound'],
-    credentials: [],
-    allowedSenders: [String(sender.address)],
-    inboundRecipients: [],
-    limits: {
-      messagesPerMinute: 1,
-      messagesPerDay: 1,
-      maxPendingInbound: 1,
-    },
-  });
-  requireNormalized(
-    value.message,
-    normalizedMessage,
-    'CoreMailSubmission.message',
-  );
-  if (!Array.isArray(value.parts) || value.parts.length === 0) {
-    throw new Error('CoreMailSubmission.parts is invalid.');
-  }
-  value.parts.forEach((partArg, indexArg) =>
-    assertPart(partArg, `CoreMailSubmission.parts[${indexArg}]`)
-  );
-  const parts = value.parts as ISubmissionPartRecord[];
-  if (
-    new Set(parts.map((partArg) => partArg.partId)).size !== parts.length
-    || canonicalJson(parts.map((partArg) => ({
-      partId: partArg.partId,
-      kind: partArg.kind,
-      contentType: partArg.contentType,
-      ...(partArg.filename === undefined ? {} : { filename: partArg.filename }),
-      ...(partArg.contentId === undefined
-        ? {}
-        : { contentId: partArg.contentId }),
-      sha256: partArg.sha256,
-      lengthBytes: partArg.lengthBytes,
-    }))) !== canonicalJson(normalizedMessage.parts)
-  ) {
-    throw new Error('CoreMailSubmission parts do not match message intent.');
+  if (source === 'smtp') {
+    // An SMTP submission carries opaque exact bytes owned by the immutable
+    // MIME tuple. It has no CoreMail-composed body, so it has no part
+    // descriptors and no part objects to upload — the non-empty and
+    // parts-match-intent rules below do not apply to it.
+    const recipients = requireRecord(
+      messageRecord.recipients,
+      ['to'],
+      [],
+      'CoreMailSubmission.message.recipients',
+    );
+    if (
+      !Array.isArray(recipients.to)
+      || messageRecord.subject !== ''
+      || !Array.isArray(messageRecord.parts)
+      || messageRecord.parts.length !== 0
+      || Object.hasOwn(messageRecord, 'replyTo')
+      || Object.hasOwn(messageRecord, 'headers')
+      || Object.hasOwn(sender, 'displayName')
+    ) {
+      throw new Error('CoreMailSubmission raw message is invalid.');
+    }
+    const envelope = normalizeCoreMailEnvelope({
+      mailFrom: sender.address,
+      rcptTo: recipients.to.map((recipientArg) =>
+        requireRecord(
+          recipientArg,
+          ['address'],
+          [],
+          'CoreMailSubmission.message.recipients.to[]',
+        ).address
+      ),
+    });
+    if (envelope.mailFrom === '') {
+      throw new Error('CoreMailSubmission raw message has no envelope sender.');
+    }
+    requireNormalized(
+      value.message,
+      createCoreMailRawOutboundMessage(envelope),
+      'CoreMailSubmission.message',
+    );
+    if (!Array.isArray(value.parts) || value.parts.length !== 0) {
+      throw new Error('CoreMailSubmission raw parts must be empty.');
+    }
+  } else {
+    const normalizedMessage = normalizeCoreMailOutboundMessage(value.message, {
+      schemaVersion: 2,
+      bindingId: String(value.bindingId),
+      serviceId: String(value.serviceId),
+      tenantId: String(value.tenantId),
+      revision: Number(value.bindingRevision),
+      state: 'active',
+      capabilities: ['outbound'],
+      credentials: [],
+      allowedSenders: [String(sender.address)],
+      inboundRecipients: [],
+      limits: {
+        messagesPerMinute: 1,
+        messagesPerDay: 1,
+        maxPendingInbound: 1,
+      },
+    });
+    requireNormalized(
+      value.message,
+      normalizedMessage,
+      'CoreMailSubmission.message',
+    );
+    if (!Array.isArray(value.parts) || value.parts.length === 0) {
+      throw new Error('CoreMailSubmission.parts is invalid.');
+    }
+    value.parts.forEach((partArg, indexArg) =>
+      assertPart(partArg, `CoreMailSubmission.parts[${indexArg}]`)
+    );
+    const parts = value.parts as ISubmissionPartRecord[];
+    if (
+      new Set(parts.map((partArg) => partArg.partId)).size !== parts.length
+      || canonicalJson(parts.map((partArg) => ({
+        partId: partArg.partId,
+        kind: partArg.kind,
+        contentType: partArg.contentType,
+        ...(partArg.filename === undefined
+          ? {}
+          : { filename: partArg.filename }),
+        ...(partArg.contentId === undefined
+          ? {}
+          : { contentId: partArg.contentId }),
+        sha256: partArg.sha256,
+        lengthBytes: partArg.lengthBytes,
+      }))) !== canonicalJson(normalizedMessage.parts)
+    ) {
+      throw new Error('CoreMailSubmission parts do not match message intent.');
+    }
   }
   requireInteger(value.attempts, 'CoreMailSubmission.attempts');
   requireInteger(value.createdAt, 'CoreMailSubmission.createdAt');
@@ -758,6 +901,10 @@ export const assertCoreMailSubmissionRecord = (
   if (mimeFieldCount !== 0 && mimeFieldCount !== 3) {
     throw new Error('CoreMailSubmission immutable MIME tuple is incomplete.');
   }
+  if (source === 'smtp' && mimeFieldCount !== 3) {
+    // The exact bytes are an SMTP submission's only content.
+    throw new Error('CoreMailSubmission raw submission has no immutable MIME.');
+  }
   if (value.transportMessageId !== undefined) {
     requireIdentifier(
       value.transportMessageId,
@@ -768,6 +915,7 @@ export const assertCoreMailSubmissionRecord = (
     requireUuid(value.transportGrantId, 'CoreMailSubmission.transportGrantId');
   }
   for (const [key, entry] of [
+    ['statsSubmittedCountedAt', value.statsSubmittedCountedAt],
     ['gatewayStatusUpdatedAt', value.gatewayStatusUpdatedAt],
     ['mimePublishedAt', value.mimePublishedAt],
     ['nextAttemptAt', value.nextAttemptAt],
@@ -1097,12 +1245,12 @@ export const assertCoreMailInboundHandoffRecord = (
   }
   requireNormalized(
     value.message,
-    normalizeCoreMailGatewayMessage(value.message),
+    plugins.serveZoneInterfaces.data.normalizeCoreMailGatewayMessage(value.message),
     'CoreMailInboundHandoff.message',
   );
   requireNormalized(
     value.source,
-    normalizeCoreMailConnectionInfo(value.source),
+    plugins.serveZoneInterfaces.data.normalizeCoreMailConnectionInfo(value.source),
     'CoreMailInboundHandoff.source',
   );
   if (

package/ts/coremail.stats.ts

@@ -0,0 +1,342 @@
+import * as plugins from './plugins.js';
+import type { ICoreMailModels } from './classes.models.js';
+import { createSha256 } from './classes.storage.js';
+import {
+  coreMailStatKinds,
+  type ICoreMailStatCounterRecord,
+  type TCoreMailStatKind,
+} from './coremail.persistence.js';
+
+const dayMs = 86_400_000;
+
+/** How long a counted day is retained before the maintenance sweep drops it. */
+export const coreMailStatRetentionMs = 90 * dayMs;
+
+export interface ICoreMailStatAuthority {
+  tenantId: string;
+  serviceId: string;
+  bindingId: string;
+}
+
+export interface ICoreMailStatDescriptor extends ICoreMailStatAuthority {
+  statId: plugins.serveZoneInterfaces.data.TCoreMailSha256;
+  dayUtc: number;
+}
+
+/**
+ * The counter row an event at `nowArg` belongs to.
+ *
+ * Counters are keyed by binding rather than binding revision: a revision bump
+ * is a configuration change, not a new tenant, and a day's totals must survive
+ * one.
+ */
+export const createCoreMailStatDescriptor = (
+  authorityArg: ICoreMailStatAuthority,
+  nowArg: number,
+): ICoreMailStatDescriptor => {
+  const dayUtc = Math.floor(nowArg / dayMs) * dayMs;
+  return {
+    tenantId: authorityArg.tenantId,
+    serviceId: authorityArg.serviceId,
+    bindingId: authorityArg.bindingId,
+    dayUtc,
+    statId: createSha256(JSON.stringify({
+      tenantId: authorityArg.tenantId,
+      serviceId: authorityArg.serviceId,
+      bindingId: authorityArg.bindingId,
+      dayUtc,
+    })),
+  };
+};
+
+const matchesDescriptor = (
+  counterArg: plugins.smartdata.TStoredDocument<ICoreMailStatCounterRecord>,
+  descriptorArg: ICoreMailStatDescriptor,
+): boolean =>
+  counterArg.tenantId === descriptorArg.tenantId
+  && counterArg.serviceId === descriptorArg.serviceId
+  && counterArg.bindingId === descriptorArg.bindingId
+  && counterArg.dayUtc === descriptorArg.dayUtc;
+
+/** Create the day's row if it does not exist yet. Safe to call concurrently. */
+export const ensureCoreMailStatCounter = async (
+  modelsArg: ICoreMailModels,
+  descriptorArg: ICoreMailStatDescriptor,
+): Promise<void> => {
+  const existing = await modelsArg.StatCounter.exact.findStoredOne({
+    statId: descriptorArg.statId,
+  });
+  if (existing) {
+    if (!matchesDescriptor(existing, descriptorArg)) {
+      throw new Error('CoreMail stat counter identity conflicts with persisted state.');
+    }
+    return;
+  }
+  try {
+    const result = await modelsArg.StatCounter.exact.insert({
+      ...descriptorArg,
+      ...Object.fromEntries(coreMailStatKinds.map((kindArg) => [kindArg, 0])) as
+        Record<TCoreMailStatKind, number>,
+      createdAt: descriptorArg.dayUtc,
+      updatedAt: descriptorArg.dayUtc,
+    });
+    if (result.status !== 'conflict') {
+      return;
+    }
+  } catch (error) {
+    if (
+      !(error instanceof plugins.smartdata.SmartdataExactPersistenceError)
+      || error.code !== 'unique_conflict'
+    ) {
+      throw error;
+    }
+  }
+  const concurrent = await modelsArg.StatCounter.exact.findStoredOne({
+    statId: descriptorArg.statId,
+  });
+  if (!concurrent || !matchesDescriptor(concurrent, descriptorArg)) {
+    throw new Error('CoreMail stat counter identity conflicts with persisted state.');
+  }
+};
+
+/**
+ * Add one to a counter through the revision-fenced transition primitive, so
+ * the read and the write are one atomic compare-and-set. Call this inside the
+ * transaction that carries the counted state transition; then the event and
+ * its count commit together or not at all.
+ */
+export const incrementCoreMailStatCounter = async (
+  modelsArg: ICoreMailModels,
+  descriptorArg: ICoreMailStatDescriptor,
+  kindArg: TCoreMailStatKind,
+  updatedAtArg: number,
+  sessionArg?: plugins.smartdata.SmartdataSession,
+): Promise<void> => {
+  const counter = await modelsArg.StatCounter.exact.findStoredOne(
+    { statId: descriptorArg.statId },
+    sessionArg ? { session: sessionArg } : undefined,
+  );
+  if (!counter) {
+    throw new Error('CoreMail stat counter is unavailable.');
+  }
+  if (!matchesDescriptor(counter, descriptorArg)) {
+    throw new Error('CoreMail stat counter identity conflicts with persisted state.');
+  }
+  const update = await modelsArg.StatCounter.exact.transition({
+    current: counter,
+    change: (modelArg) => {
+      modelArg[kindArg] += 1;
+      modelArg.updatedAt = updatedAtArg;
+    },
+  }, sessionArg ? { session: sessionArg } : undefined);
+  if (update.status !== 'transitioned') {
+    throw new Error('CoreMail stat counter transition was contended.');
+  }
+};
+
+/**
+ * Ensure the day's row exists, then count one event on it.
+ *
+ * For a counted transition that runs inside a transaction, call
+ * `ensureCoreMailStatCounter` before opening it and
+ * `incrementCoreMailStatCounter` with the session inside it — the same order
+ * the quota counters use, so the row insert never contends with the
+ * transaction that increments it.
+ */
+export const countCoreMailStat = async (
+  modelsArg: ICoreMailModels,
+  authorityArg: ICoreMailStatAuthority,
+  kindArg: TCoreMailStatKind,
+  nowArg: number,
+  sessionArg?: plugins.smartdata.SmartdataSession,
+): Promise<ICoreMailStatDescriptor> => {
+  const descriptor = createCoreMailStatDescriptor(authorityArg, nowArg);
+  await ensureCoreMailStatCounter(modelsArg, descriptor);
+  await incrementCoreMailStatCounter(
+    modelsArg,
+    descriptor,
+    kindArg,
+    nowArg,
+    sessionArg,
+  );
+  return descriptor;
+};
+
+/** Maximum rows one statistics page may return. */
+export const coreMailStatPageMaximum = 200;
+
+const dayPattern = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
+
+/** `YYYY-MM-DD` to the UTC midnight milliseconds the counter rows are keyed by. */
+export const parseCoreMailStatDay = (valueArg: unknown, labelArg: string): number => {
+  if (typeof valueArg !== 'string' || !dayPattern.test(valueArg)) {
+    throw new Error(`CoreMail statistics ${labelArg} must be a YYYY-MM-DD day.`);
+  }
+  const parsed = Date.parse(`${valueArg}T00:00:00.000Z`);
+  if (!Number.isSafeInteger(parsed) || parsed % dayMs !== 0) {
+    throw new Error(`CoreMail statistics ${labelArg} must be a real UTC day.`);
+  }
+  return parsed;
+};
+
+export const formatCoreMailStatDay = (dayUtcArg: number): string =>
+  new Date(dayUtcArg).toISOString().slice(0, 10);
+
+export interface ICoreMailStatCursorPosition {
+  dayUtc: number;
+  statId: plugins.serveZoneInterfaces.data.TCoreMailSha256;
+}
+
+/**
+ * Opaque composite cursor over `(dayUtc, statId)`.
+ *
+ * It carries no authority: the control session is what authorizes the read,
+ * and every filter is re-applied on the next page, so a replayed cursor can
+ * only ever resume the same ordered scan.
+ */
+export const encodeCoreMailStatCursor = (
+  positionArg: ICoreMailStatCursorPosition,
+): string =>
+  Buffer.from(
+    JSON.stringify({ v: 1, d: positionArg.dayUtc, s: positionArg.statId }),
+    'utf8',
+  ).toString('base64url');
+
+export const decodeCoreMailStatCursor = (
+  valueArg: unknown,
+): ICoreMailStatCursorPosition => {
+  if (
+    typeof valueArg !== 'string'
+    || valueArg.length === 0
+    || valueArg.length
+      > plugins.serveZoneInterfaces.data.coreMailLimits.cursorBytes
+  ) {
+    throw new Error('CoreMail statistics cursor is invalid.');
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(Buffer.from(valueArg, 'base64url').toString('utf8'));
+  } catch {
+    throw new Error('CoreMail statistics cursor is invalid.');
+  }
+  const record = decoded as { v?: unknown; d?: unknown; s?: unknown };
+  if (
+    !record
+    || typeof record !== 'object'
+    || record.v !== 1
+    || !Number.isSafeInteger(record.d)
+    || Number(record.d) % dayMs !== 0
+    || typeof record.s !== 'string'
+  ) {
+    throw new Error('CoreMail statistics cursor is invalid.');
+  }
+  try {
+    return {
+      dayUtc: Number(record.d),
+      statId: plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(record.s),
+    };
+  } catch {
+    throw new Error('CoreMail statistics cursor is invalid.');
+  }
+};
+
+/** Project one counter row onto the wire contract. */
+export const toCoreMailServiceMailStatistics = (
+  counterArg: ICoreMailStatCounterRecord,
+): plugins.serveZoneInterfaces.data.ICoreMailServiceMailStatistics =>
+  plugins.serveZoneInterfaces.data.normalizeCoreMailServiceMailStatistics({
+    tenantId: counterArg.tenantId,
+    serviceId: counterArg.serviceId,
+    bindingId: counterArg.bindingId,
+    dayUtc: formatCoreMailStatDay(counterArg.dayUtc),
+    outbound: {
+      submittedApi: counterArg.submittedApi,
+      submittedSmtp: counterArg.submittedSmtp,
+      delivered: counterArg.delivered,
+      deferred: counterArg.deferred,
+      failed: counterArg.failed,
+      deadLettered: counterArg.deadLettered,
+    },
+    inbound: {
+      received: counterArg.received,
+      acknowledgedProcessed: counterArg.acknowledgedProcessed,
+      acknowledgedDiscarded: counterArg.acknowledgedDiscarded,
+    },
+    updatedAt: counterArg.updatedAt,
+  });
+
+/** One ordered, bounded page of per-service daily counters. */
+export const listCoreMailServiceMailStatistics = async (
+  modelsArg: ICoreMailModels,
+  requestArg: {
+    fromDayUtc: string;
+    toDayUtc: string;
+    serviceIds?: string[];
+    cursor?: string;
+    limit: number;
+  },
+): Promise<{
+  statistics: plugins.serveZoneInterfaces.data.ICoreMailServiceMailStatistics[];
+  nextCursor?: string;
+}> => {
+  const fromDayUtc = parseCoreMailStatDay(requestArg.fromDayUtc, 'fromDayUtc');
+  const toDayUtc = parseCoreMailStatDay(requestArg.toDayUtc, 'toDayUtc');
+  if (toDayUtc < fromDayUtc) {
+    throw new Error('CoreMail statistics range is inverted.');
+  }
+  if (
+    !Number.isSafeInteger(requestArg.limit)
+    || requestArg.limit < 1
+    || requestArg.limit > coreMailStatPageMaximum
+  ) {
+    throw new Error(
+      `CoreMail statistics limit must be between 1 and ${coreMailStatPageMaximum}.`,
+    );
+  }
+  let serviceIds: string[] | undefined;
+  if (requestArg.serviceIds !== undefined) {
+    if (
+      !Array.isArray(requestArg.serviceIds)
+      || requestArg.serviceIds.length === 0
+      || requestArg.serviceIds.length > 1_000
+      || requestArg.serviceIds.some((entryArg) => typeof entryArg !== 'string')
+    ) {
+      throw new Error('CoreMail statistics serviceIds filter is invalid.');
+    }
+    serviceIds = [...new Set(requestArg.serviceIds)];
+  }
+  const cursor = requestArg.cursor === undefined
+    ? undefined
+    : decodeCoreMailStatCursor(requestArg.cursor);
+  const rows = await modelsArg.StatCounter.exact.findStored({
+    filter: {
+      $and: [
+        { dayUtc: { $gte: fromDayUtc, $lte: toDayUtc } },
+        ...(serviceIds ? [{ serviceId: { $in: serviceIds } }] : []),
+        ...(cursor
+          ? [{
+              $or: [
+                { dayUtc: { $gt: cursor.dayUtc } },
+                { dayUtc: cursor.dayUtc, statId: { $gt: cursor.statId } },
+              ],
+            }]
+          : []),
+      ],
+    },
+    sort: { dayUtc: 1, statId: 1 },
+    limit: requestArg.limit + 1,
+  });
+  const page = rows.slice(0, requestArg.limit);
+  const last = page.at(-1);
+  return {
+    statistics: page.map(toCoreMailServiceMailStatistics),
+    ...(rows.length > page.length && last
+      ? {
+          nextCursor: encodeCoreMailStatCursor({
+            dayUtc: last.dayUtc,
+            statId: last.statId,
+          }),
+        }
+      : {}),
+  };
+};