@iann29/rastro 0.1.0-alpha.0

package/src/component/reports.ts

@@ -0,0 +1,720 @@
+import {
+  paginationOptsValidator,
+  paginationResultValidator,
+} from "convex/server";
+import { v } from "convex/values";
+import { query } from "./_generated/server.js";
+import {
+  AGGREGATE_SHARDS,
+  DAY_MS,
+  HOUR_MS,
+  MAX_AFFILIATES_PER_SITE,
+  MAX_FUNNELS_PER_SITE,
+  MAX_GOALS_PER_SITE,
+  MAX_JOURNEY_EVENTS,
+  MAX_LIVE_VISITORS,
+  MAX_MANUAL_PAGINATION_OFFSET,
+  MAX_OVERVIEW_AGGREGATE_ROWS,
+  MAX_REPORT_RANGE_DAYS,
+  MAX_REPORT_SITES,
+} from "./constants.js";
+import { fail } from "./errors.js";
+import { isPlainRecord } from "./guards.js";
+import {
+  affiliateFieldsValidator,
+  eventFieldsValidator,
+  funnelFieldsValidator,
+  goalFieldsValidator,
+  sessionFieldsValidator,
+} from "./validators.js";
+
+const sessionDocumentValidator = sessionFieldsValidator.extend({
+  _id: v.id("sessions"),
+  _creationTime: v.number(),
+});
+const eventDocumentValidator = eventFieldsValidator.extend({
+  _id: v.id("events"),
+  _creationTime: v.number(),
+});
+const liveSessionDocumentValidator = v.object({
+  _id: v.id("liveSessions"),
+  _creationTime: v.number(),
+  siteId: v.id("sites"),
+  sessionId: v.string(),
+  visitorId: v.string(),
+  path: v.string(),
+  startedAt: v.number(),
+  lastSeenAt: v.number(),
+  expiresAt: v.number(),
+  country: v.optional(v.string()),
+  city: v.optional(v.string()),
+  latitude: v.optional(v.number()),
+  longitude: v.optional(v.number()),
+  browser: v.string(),
+  os: v.string(),
+  source: v.string(),
+  device: v.string(),
+  pageviewCount: v.number(),
+  eventCount: v.number(),
+});
+const conversionDocumentValidator = v.object({
+  _id: v.id("conversions"),
+  _creationTime: v.number(),
+  siteId: v.id("sites"),
+  eventId: v.string(),
+  sessionId: v.string(),
+  visitorId: v.string(),
+  timestamp: v.number(),
+  path: v.string(),
+  revenueCents: v.number(),
+  currency: v.string(),
+  source: v.union(v.literal("tracker"), v.literal("trusted")),
+  goalKey: v.optional(v.string()),
+  affiliateId: v.optional(v.id("affiliates")),
+  affiliateAttributedAt: v.optional(v.number()),
+  affiliateExpiresAt: v.optional(v.number()),
+  affiliateSlug: v.optional(v.string()),
+  commissionCents: v.number(),
+});
+const metricTotalsValidator = v.object({
+  events: v.number(),
+  pageviews: v.number(),
+  clicks: v.number(),
+  customEvents: v.number(),
+  outboundClicks: v.number(),
+  sessions: v.number(),
+  visitors: v.number(),
+  conversions: v.number(),
+  revenueCents: v.number(),
+});
+const timePointValidator = metricTotalsValidator.extend({ timestamp: v.number() });
+const topItemValidator = v.object({
+  value: v.string(),
+  count: v.number(),
+  revenueCents: v.number(),
+});
+
+export const overview = query({
+  args: {
+    siteIds: v.array(v.id("sites")),
+    from: v.number(),
+    to: v.number(),
+    interval: v.optional(v.union(v.literal("hour"), v.literal("day"))),
+  },
+  returns: v.object({
+    from: v.number(),
+    to: v.number(),
+    interval: v.union(v.literal("hour"), v.literal("day")),
+    currency: v.string(),
+    totals: metricTotalsValidator,
+    timeSeries: v.array(timePointValidator),
+    topSources: v.array(topItemValidator),
+    topPages: v.array(topItemValidator),
+    topCountries: v.array(topItemValidator),
+    topDevices: v.array(topItemValidator),
+    topBrowsers: v.array(topItemValidator),
+    topEvents: v.array(topItemValidator),
+    topGoals: v.array(topItemValidator),
+  }),
+  handler: async (ctx, args) => {
+    const siteIds = validateSiteIds(args.siteIds);
+    const currencies = new Set<string>();
+    for (const siteId of siteIds) {
+      const site = await ctx.db.get("sites", siteId);
+      if (!site) fail("NOT_FOUND", "site not found", { siteId: String(siteId) });
+      currencies.add(site.currency ?? "USD");
+    }
+    if (currencies.size !== 1) {
+      fail("CURRENCY_MISMATCH", "overview sites must use the same currency", {
+        currencies: [...currencies].sort().join(","),
+      });
+    }
+    const currency = [...currencies][0];
+    const { from, to } = validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const interval = args.interval ?? (to - from <= 7 * DAY_MS ? "hour" : "day");
+    if (interval === "hour" && to - from > 7 * DAY_MS) {
+      fail("INVALID_ARGUMENT", "hourly reports are limited to seven days");
+    }
+    const intervalMs = interval === "hour" ? HOUR_MS : DAY_MS;
+    const firstBucket = Math.floor(from / intervalMs) * intervalMs;
+    const lastBucket = Math.floor(to / intervalMs) * intervalMs;
+    const bucketCount = Math.floor((lastBucket - firstBucket) / intervalMs) + 1;
+    const perSiteLimit = bucketCount * AGGREGATE_SHARDS;
+    if (perSiteLimit * siteIds.length > MAX_OVERVIEW_AGGREGATE_ROWS) {
+      fail(
+        "LIMIT_EXCEEDED",
+        "overview range is too wide for the requested number of sites",
+        { maximumAggregateRows: MAX_OVERVIEW_AGGREGATE_ROWS },
+      );
+    }
+    const totals = emptyTotals();
+    const points = new Map<number, MetricTotals>();
+    const dimensions = new Map<string, { value: string; count: number; revenueCents: number }>();
+
+    for (const siteId of siteIds) {
+      const buckets = await ctx.db
+        .query("aggregateBuckets")
+        .withIndex("by_siteId_and_granularity_and_bucketStart", (range) =>
+          range
+            .eq("siteId", siteId)
+            .eq("granularity", interval)
+            .gte("bucketStart", firstBucket)
+            .lte("bucketStart", lastBucket),
+        )
+        .take(perSiteLimit);
+      for (const bucket of buckets) {
+        addMetrics(totals, bucket);
+        const point = points.get(bucket.bucketStart) ?? emptyTotals();
+        addMetrics(point, bucket);
+        points.set(bucket.bucketStart, point);
+        for (const dimension of bucket.dimensions) {
+          const key = `${dimension.type}:${dimension.value}`;
+          const current = dimensions.get(key) ?? {
+            value: dimension.value,
+            count: 0,
+            revenueCents: 0,
+          };
+          current.count += dimension.count;
+          current.revenueCents += dimension.revenueCents;
+          dimensions.set(key, current);
+        }
+      }
+    }
+
+    const top = (type: string) =>
+      [...dimensions.entries()]
+        .filter(([key]) => key.startsWith(`${type}:`))
+        .map(([, value]) => value)
+        .sort((left, right) => right.count - left.count || left.value.localeCompare(right.value))
+        .slice(0, 10);
+    return {
+      from,
+      to,
+      interval,
+      currency,
+      totals,
+      timeSeries: [...points.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([timestamp, metrics]) => ({ timestamp, ...metrics })),
+      topSources: top("source"),
+      topPages: top("page"),
+      topCountries: top("country"),
+      topDevices: top("device"),
+      topBrowsers: top("browser"),
+      topEvents: top("event"),
+      topGoals: top("goal"),
+    };
+  },
+});
+
+export const liveVisitors = query({
+  args: {
+    siteIds: v.array(v.id("sites")),
+    now: v.number(),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(liveSessionDocumentValidator),
+  handler: async (ctx, args) => {
+    const siteIds = validateSiteIds(args.siteIds);
+    const limit = args.limit ?? 100;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIVE_VISITORS) {
+      fail("INVALID_ARGUMENT", `limit must be an integer between 1 and ${MAX_LIVE_VISITORS}`);
+    }
+    if (!Number.isFinite(args.now) || args.now < 0) {
+      fail("INVALID_ARGUMENT", "now must be a positive timestamp");
+    }
+    const rows = [];
+    for (const siteId of siteIds) {
+      rows.push(
+        ...(await ctx.db
+          .query("liveSessions")
+          .withIndex("by_siteId_and_expiresAt", (range) =>
+            range.eq("siteId", siteId).gte("expiresAt", args.now),
+          )
+          .order("desc")
+          .take(limit)),
+      );
+    }
+    return rows
+      .sort((left, right) => right.lastSeenAt - left.lastSeenAt)
+      .slice(0, limit)
+      .map((row) => ({
+        _id: row._id,
+        _creationTime: row._creationTime,
+        siteId: row.siteId,
+        sessionId: row.sessionId,
+        visitorId: row.visitorId,
+        path: row.path,
+        startedAt: row.startedAt,
+        lastSeenAt: row.lastSeenAt,
+        expiresAt: row.expiresAt,
+        ...(row.country ? { country: row.country } : {}),
+        ...(row.city ? { city: row.city } : {}),
+        ...(row.latitude !== undefined ? { latitude: row.latitude } : {}),
+        ...(row.longitude !== undefined ? { longitude: row.longitude } : {}),
+        browser: row.browser,
+        os: row.os,
+        source: row.source,
+        device: row.device,
+        pageviewCount: row.pageviewCount,
+        eventCount: row.eventCount,
+      }));
+  },
+});
+
+export const listSessions = query({
+  args: {
+    siteId: v.id("sites"),
+    from: v.number(),
+    to: v.number(),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(sessionDocumentValidator),
+  handler: async (ctx, args) => {
+    validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const pagination = parseManualPagination(args.paginationOpts);
+    const rows = await ctx.db
+      .query("sessions")
+      .withIndex("by_siteId_and_lastSeenAt", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .gte("lastSeenAt", args.from)
+          .lte("lastSeenAt", args.to),
+      )
+      .order("desc")
+      .take(pagination.offset + pagination.numItems + 1);
+    return manualPaginationResult(rows, pagination);
+  },
+});
+
+export const sessionJourney = query({
+  args: {
+    siteId: v.id("sites"),
+    sessionId: v.string(),
+    from: v.number(),
+    to: v.number(),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(eventDocumentValidator),
+  handler: async (ctx, args) => {
+    validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const pagination = parseManualPagination(args.paginationOpts);
+    const rows = await ctx.db
+      .query("events")
+      .withIndex("by_siteId_and_sessionId_and_timestamp", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .eq("sessionId", args.sessionId)
+          .gte("timestamp", args.from)
+          .lte("timestamp", args.to),
+      )
+      .order("asc")
+      .take(pagination.offset + pagination.numItems + 1);
+    return manualPaginationResult(rows, pagination);
+  },
+});
+
+export const listConversions = query({
+  args: {
+    siteId: v.id("sites"),
+    from: v.number(),
+    to: v.number(),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(conversionDocumentValidator),
+  handler: async (ctx, args) => {
+    validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const pagination = parseManualPagination(args.paginationOpts);
+    const rows = await ctx.db
+      .query("conversions")
+      .withIndex("by_siteId_and_timestamp", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .gte("timestamp", args.from)
+          .lte("timestamp", args.to),
+      )
+      .order("desc")
+      .take(pagination.offset + pagination.numItems + 1);
+    return manualPaginationResult(rows, pagination);
+  },
+});
+
+export const visitorJourney = query({
+  args: {
+    siteIds: v.array(v.id("sites")),
+    visitorId: v.string(),
+    from: v.number(),
+    to: v.number(),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(eventDocumentValidator),
+  handler: async (ctx, args) => {
+    const siteIds = validateSiteIds(args.siteIds);
+    validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const limit = args.limit ?? 200;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_JOURNEY_EVENTS) {
+      fail("INVALID_ARGUMENT", `limit must be an integer between 1 and ${MAX_JOURNEY_EVENTS}`);
+    }
+    const rows = [];
+    for (const siteId of siteIds) {
+      rows.push(
+        ...(await ctx.db
+          .query("events")
+          .withIndex("by_siteId_and_visitorId_and_timestamp", (range) =>
+            range
+              .eq("siteId", siteId)
+              .eq("visitorId", args.visitorId)
+              .gte("timestamp", args.from)
+              .lte("timestamp", args.to),
+          )
+          .order("asc")
+          .take(limit)),
+      );
+    }
+    return rows
+      .sort((left, right) => left.timestamp - right.timestamp || left.sequence - right.sequence)
+      .slice(0, limit);
+  },
+});
+
+const goalReportItemValidator = goalFieldsValidator.extend({
+  _id: v.id("goals"),
+  _creationTime: v.number(),
+  completions: v.number(),
+  valueCents: v.number(),
+});
+
+export const goalsReport = query({
+  args: { siteId: v.id("sites"), from: v.number(), to: v.number() },
+  returns: v.object({
+    goals: v.array(goalReportItemValidator),
+    truncated: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const goals = await ctx.db
+      .query("goals")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .take(MAX_GOALS_PER_SITE);
+    const completions = await ctx.db
+      .query("goalCompletions")
+      .withIndex("by_siteId_and_timestamp", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .gte("timestamp", args.from)
+          .lte("timestamp", args.to),
+      )
+      .take(5_001);
+    const totals = new Map<string, { completions: number; valueCents: number }>();
+    for (const completion of completions.slice(0, 5_000)) {
+      const key = String(completion.goalId);
+      const total = totals.get(key) ?? { completions: 0, valueCents: 0 };
+      total.completions += 1;
+      total.valueCents += completion.valueCents;
+      totals.set(key, total);
+    }
+    return {
+      goals: goals.map((goal) => ({
+        ...goal,
+        ...(totals.get(String(goal._id)) ?? { completions: 0, valueCents: 0 }),
+      })),
+      truncated: completions.length > 5_000,
+    };
+  },
+});
+
+const funnelReportItemValidator = funnelFieldsValidator.extend({
+  _id: v.id("funnels"),
+  _creationTime: v.number(),
+  stepsReport: v.array(
+    v.object({ step: v.number(), name: v.string(), entrants: v.number(), completions: v.number() }),
+  ),
+  truncated: v.boolean(),
+});
+
+export const funnelsReport = query({
+  args: { siteId: v.id("sites"), from: v.number(), to: v.number() },
+  returns: v.array(funnelReportItemValidator),
+  handler: async (ctx, args) => {
+    validateRange(args.from, args.to, 90);
+    const funnels = await ctx.db
+      .query("funnels")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .take(MAX_FUNNELS_PER_SITE);
+    const reports = [];
+    for (const funnel of funnels) {
+      const buckets = await ctx.db
+        .query("funnelStepBuckets")
+        .withIndex("by_siteId_and_funnelId_and_bucketStart", (range) =>
+          range
+            .eq("siteId", args.siteId)
+            .eq("funnelId", funnel._id)
+            .gte("bucketStart", Math.floor(args.from / DAY_MS) * DAY_MS)
+            .lte("bucketStart", Math.floor(args.to / DAY_MS) * DAY_MS),
+        )
+        .take(601);
+      const stepsReport = funnel.steps.map((step, index) => ({
+        step: index,
+        name: step.name,
+        entrants: 0,
+        completions: 0,
+      }));
+      for (const bucket of buckets.slice(0, 600)) {
+        const step = stepsReport[bucket.step];
+        if (step) {
+          step.entrants += bucket.entrants;
+          step.completions += bucket.completions;
+        }
+      }
+      reports.push({
+        ...funnel,
+        stepsReport,
+        truncated: buckets.length > 600,
+      });
+    }
+    return reports;
+  },
+});
+
+const affiliateReportItemValidator = affiliateFieldsValidator.extend({
+  _id: v.id("affiliates"),
+  _creationTime: v.number(),
+  visits: v.number(),
+  uniqueVisitors: v.number(),
+  conversions: v.number(),
+  revenueCents: v.number(),
+  commissionCents: v.number(),
+});
+
+export const affiliatesReport = query({
+  args: { siteId: v.id("sites"), from: v.number(), to: v.number() },
+  returns: v.object({
+    affiliates: v.array(affiliateReportItemValidator),
+    truncated: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const affiliateRows = await ctx.db
+      .query("affiliates")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .order("desc")
+      .take(MAX_AFFILIATES_PER_SITE + 1);
+    const affiliates = affiliateRows.slice(0, MAX_AFFILIATES_PER_SITE);
+    const stats = await ctx.db
+      .query("affiliateDailyStats")
+      .withIndex("by_siteId_and_bucketStart", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .gte("bucketStart", Math.floor(args.from / DAY_MS) * DAY_MS)
+          .lte("bucketStart", Math.floor(args.to / DAY_MS) * DAY_MS),
+      )
+      .take(5_001);
+    const sessions = await ctx.db
+      .query("sessions")
+      .withIndex("by_siteId_and_startedAt", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .gte("startedAt", args.from)
+          .lte("startedAt", args.to),
+      )
+      .take(5_001);
+    const visits = new Map<string, {
+      visits: number;
+      visitors: Set<string>;
+    }>();
+    for (const session of sessions.slice(0, 5_000)) {
+      if (!session.affiliateId) continue;
+      const key = String(session.affiliateId);
+      const total = visits.get(key) ?? {
+        visits: 0,
+        visitors: new Set<string>(),
+      };
+      total.visits += 1;
+      total.visitors.add(session.visitorId);
+      visits.set(key, total);
+    }
+    const totals = new Map<string, {
+      conversions: number;
+      revenueCents: number;
+      commissionCents: number;
+    }>();
+    for (const row of stats.slice(0, 5_000)) {
+      const key = String(row.affiliateId);
+      const total = totals.get(key) ?? {
+        conversions: 0,
+        revenueCents: 0,
+        commissionCents: 0,
+      };
+      total.conversions += row.conversions;
+      total.revenueCents += row.revenueCents;
+      total.commissionCents += row.commissionCents;
+      totals.set(key, total);
+    }
+    return {
+      affiliates: affiliates.map((affiliate) => {
+        const performance = totals.get(String(affiliate._id)) ?? {
+          conversions: 0,
+          revenueCents: 0,
+          commissionCents: 0,
+        };
+        const traffic = visits.get(String(affiliate._id));
+        return {
+          ...affiliate,
+          ...performance,
+          visits: traffic?.visits ?? 0,
+          uniqueVisitors: traffic?.visitors.size ?? 0,
+        };
+      }),
+      truncated:
+        affiliateRows.length > MAX_AFFILIATES_PER_SITE ||
+        stats.length > 5_000 ||
+        sessions.length > 5_000,
+    };
+  },
+});
+
+
+type MetricTotals = {
+  events: number;
+  pageviews: number;
+  clicks: number;
+  customEvents: number;
+  outboundClicks: number;
+  sessions: number;
+  visitors: number;
+  conversions: number;
+  revenueCents: number;
+};
+
+function emptyTotals(): MetricTotals {
+  return {
+    events: 0,
+    pageviews: 0,
+    clicks: 0,
+    customEvents: 0,
+    outboundClicks: 0,
+    sessions: 0,
+    visitors: 0,
+    conversions: 0,
+    revenueCents: 0,
+  };
+}
+
+function addMetrics(target: MetricTotals, source: MetricTotals) {
+  target.events += source.events;
+  target.pageviews += source.pageviews;
+  target.clicks += source.clicks;
+  target.customEvents += source.customEvents;
+  target.outboundClicks += source.outboundClicks;
+  target.sessions += source.sessions;
+  target.visitors += source.visitors;
+  target.conversions += source.conversions;
+  target.revenueCents += source.revenueCents;
+}
+
+function validateSiteIds<T>(siteIds: T[]): T[] {
+  const unique = [...new Set(siteIds)];
+  if (unique.length < 1 || unique.length > MAX_REPORT_SITES || unique.length !== siteIds.length) {
+    fail("INVALID_ARGUMENT", `siteIds must contain 1-${MAX_REPORT_SITES} unique IDs`);
+  }
+  return unique;
+}
+
+function validateRange(from: number, to: number, maxDays: number) {
+  if (
+    !Number.isFinite(from) ||
+    !Number.isFinite(to) ||
+    from < 0 ||
+    to <= from ||
+    to - from > maxDays * DAY_MS
+  ) {
+    fail("INVALID_ARGUMENT", `range must be positive, ordered, and at most ${maxDays} days`);
+  }
+  return { from: Math.trunc(from), to: Math.trunc(to) };
+}
+
+type ManualPaginationInput = {
+  cursor: string | null;
+  numItems: number;
+  maximumRowsRead?: number;
+  maximumBytesRead?: number;
+};
+
+type ManualPagination = {
+  offset: number;
+  numItems: number;
+};
+
+function parseManualPagination(
+  options: ManualPaginationInput,
+): ManualPagination {
+  validatePagination(options);
+  if (options.cursor === null) {
+    return { offset: 0, numItems: options.numItems };
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(atob(options.cursor));
+  } catch {
+    fail("INVALID_ARGUMENT", "pagination cursor is malformed");
+  }
+  if (
+    !isPlainRecord(decoded) ||
+    decoded.v !== 1 ||
+    typeof decoded.o !== "number" ||
+    !Number.isSafeInteger(decoded.o) ||
+    decoded.o < 0 ||
+    decoded.o > MAX_MANUAL_PAGINATION_OFFSET
+  ) {
+    fail("INVALID_ARGUMENT", "pagination cursor is invalid or exceeds the offset limit");
+  }
+  return { offset: decoded.o, numItems: options.numItems };
+}
+
+function manualPaginationResult<T>(
+  rows: T[],
+  pagination: ManualPagination,
+) {
+  const page = rows.slice(
+    pagination.offset,
+    pagination.offset + pagination.numItems,
+  );
+  const nextOffset = pagination.offset + page.length;
+  const isDone =
+    rows.length <= pagination.offset + pagination.numItems ||
+    nextOffset >= MAX_MANUAL_PAGINATION_OFFSET;
+  return {
+    page,
+    isDone,
+    continueCursor: btoa(JSON.stringify({
+      v: 1,
+      o: Math.min(nextOffset, MAX_MANUAL_PAGINATION_OFFSET),
+    })),
+  };
+}
+
+function validatePagination(options: {
+  numItems: number;
+  maximumRowsRead?: number;
+  maximumBytesRead?: number;
+}) {
+  if (!Number.isSafeInteger(options.numItems) || options.numItems < 1 || options.numItems > 100) {
+    fail("INVALID_ARGUMENT", "pagination numItems must be an integer between 1 and 100");
+  }
+  if (
+    options.maximumRowsRead !== undefined &&
+    (!Number.isSafeInteger(options.maximumRowsRead) ||
+      options.maximumRowsRead < 1 ||
+      options.maximumRowsRead > 1_000)
+  ) {
+    fail("INVALID_ARGUMENT", "maximumRowsRead must be an integer between 1 and 1000");
+  }
+  if (
+    options.maximumBytesRead !== undefined &&
+    (!Number.isSafeInteger(options.maximumBytesRead) ||
+      options.maximumBytesRead < 1 ||
+      options.maximumBytesRead > 8_000_000)
+  ) {
+    fail("INVALID_ARGUMENT", "maximumBytesRead must be an integer between 1 and 8000000");
+  }
+}