@nimbus-dev/connectors 0.2.3 → 0.3.0

package/connectors/readwise/src/book-mapping.ts

@@ -0,0 +1,109 @@
+/**
+ * A Readwise book (`GET /api/v2/books/`) as a sync item. Ported from the gateway's
+ * `readwise-book-mapping.ts` (Nimbus origin/main 61e034a5) with every field rule unchanged;
+ * `test/mapping-parity.test.ts` pins each field to what the gateway stored.
+ *
+ * `externalId` is `book/<numeric id>`, NOT the bare id. Readwise numbers books and highlights in
+ * separate sequences, so book 9001 and highlight 9001 both exist, and the gateway's item key is
+ * `<service>:<externalId>`: a bare id would let one type's row overwrite the other's.
+ */
+import {
+  asRecord,
+  namedTags,
+  numberField,
+  parseIsoMs,
+  type ReadwiseMappingContext,
+  type ReadwiseSyncItem,
+  stringField,
+} from "./record-fields.ts";
+
+/** Keeps `readwise:book/<id>` distinct from the highlight `readwise:<id>`. */
+export const READWISE_BOOK_EXTERNAL_ID_PREFIX = "book/";
+
+/** Trimmed string field, or null when absent/blank. */
+function trimmedField(row: Record<string, unknown>, key: string): string | null {
+  const raw = stringField(row, key);
+  if (raw === undefined) {
+    return null;
+  }
+  const trimmed = raw.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+function firstNonNull(candidates: readonly (string | null)[], fallback: string): string {
+  for (const candidate of candidates) {
+    if (candidate !== null) {
+      return candidate;
+    }
+  }
+  return fallback;
+}
+
+export function mapReadwiseBookToItem(
+  raw: unknown,
+  ctx: ReadwiseMappingContext,
+): ReadwiseSyncItem | null {
+  const row = asRecord(raw);
+  if (row === undefined) {
+    return null;
+  }
+
+  const idNum = numberField(row, "id");
+  if (idNum === undefined) {
+    return null;
+  }
+  const id = String(idNum);
+
+  const title = trimmedField(row, "title");
+  const author = trimmedField(row, "author");
+  const category = trimmedField(row, "category");
+  const source = trimmedField(row, "source");
+  const documentNote = trimmedField(row, "document_note");
+  const asin = trimmedField(row, "asin");
+  const sourceUrl = trimmedField(row, "source_url");
+  const highlightsUrl = trimmedField(row, "highlights_url");
+  const numHighlights = numberField(row, "num_highlights") ?? null;
+  const tags = namedTags(row["tags"]);
+
+  const lastHighlightAt = parseIsoMs(row["last_highlight_at"]);
+  const updatedAt = parseIsoMs(row["updated"]);
+
+  const titleText = firstNonNull([title, author], `Book ${id}`);
+  const bodyPreview = firstNonNull([documentNote, author, category], titleText);
+
+  // Kindle/ePub books have no public source URL; the Readwise book-review page
+  // is the only stable, user-openable URL for them.
+  const canonicalUrl = sourceUrl ?? highlightsUrl;
+
+  const modifiedAt = updatedAt ?? lastHighlightAt ?? ctx.syncedAt;
+
+  const metadata: Record<string, unknown> = {
+    // NUMBER, not the stringified id: a highlight stores its parent as
+    // `metadata.book_id` (a number), and this is the field that joins them.
+    book_id: idNum,
+    title,
+    author,
+    category,
+    source,
+    num_highlights: numHighlights,
+    asin,
+    tags,
+    document_note: documentNote,
+    source_url: sourceUrl,
+    highlights_url: highlightsUrl,
+    last_highlight_at: lastHighlightAt,
+    updated_at: updatedAt,
+    canonical_url: canonicalUrl,
+  };
+
+  return {
+    type: "book",
+    externalId: `${READWISE_BOOK_EXTERNAL_ID_PREFIX}${id}`,
+    title: titleText,
+    bodyPreview,
+    url: canonicalUrl,
+    canonicalUrl,
+    modifiedAt,
+    metadata,
+  };
+}

package/connectors/readwise/src/extension.ts

@@ -0,0 +1,11 @@
+// Entry point of the signed Readwise extension (bundled to dist/server.js by `build:extension`).
+// Kept apart from server.ts so the standalone/gateway entry stays untouched; bootstrap only.
+// Only this entry registers the reserved `__nimbus_sync` tool; server.ts users never see it.
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { registerReadwiseSyncTool } from "./sync-tool.ts";
+import { registerReadwiseTools } from "./tools.ts";
+
+await runReadOnlyMcpConnector("nimbus-readwise", (reg) => {
+  registerReadwiseTools(reg);
+  registerReadwiseSyncTool(reg);
+});

package/connectors/readwise/src/highlight-mapping.ts

@@ -0,0 +1,88 @@
+/**
+ * A Readwise highlight (`GET /api/v2/highlights/`) as a sync item. Ported from the gateway's
+ * `readwise-highlight-mapping.ts` (Nimbus origin/main 61e034a5) with every field rule unchanged:
+ * a migrated user's rows are updated in place only while `type` and `externalId` stay
+ * byte-identical, and `test/mapping-parity.test.ts` pins every other field to what the gateway
+ * stored. Highlights keep the BARE numeric id as `externalId`.
+ */
+import {
+  asRecord,
+  namedTags,
+  numberField,
+  parseIsoMs,
+  type ReadwiseMappingContext,
+  type ReadwiseSyncItem,
+  stringField,
+} from "./record-fields.ts";
+
+const TITLE_MAX = 80;
+
+export function mapReadwiseHighlightToItem(
+  raw: unknown,
+  ctx: ReadwiseMappingContext,
+): ReadwiseSyncItem | null {
+  const row = asRecord(raw);
+  if (row === undefined) {
+    return null;
+  }
+
+  const idNum = numberField(row, "id");
+  if (idNum === undefined) {
+    return null;
+  }
+  const id = String(idNum);
+
+  const text = stringField(row, "text") ?? null;
+  const note = stringField(row, "note") ?? null;
+  const location = numberField(row, "location") ?? null;
+  const locationType = stringField(row, "location_type") ?? null;
+  const color = stringField(row, "color") ?? null;
+  const bookId = numberField(row, "book_id") ?? null;
+  const sourceUrl = stringField(row, "url") ?? null;
+  const tags = namedTags(row["tags"]);
+
+  const highlightedAt = parseIsoMs(row["highlighted_at"]);
+  const updatedAt = parseIsoMs(row["updated"]);
+
+  const trimmedText = text === null ? "" : text.trim();
+  let title: string;
+  if (trimmedText === "") {
+    title = `Highlight ${id}`;
+  } else if (trimmedText.length > TITLE_MAX) {
+    title = `${trimmedText.slice(0, TITLE_MAX)}…`;
+  } else {
+    title = trimmedText;
+  }
+
+  const bodyPreview = note !== null && note !== "" ? note : (text ?? "");
+
+  const canonicalUrl = sourceUrl !== null && sourceUrl !== "" ? sourceUrl : null;
+
+  const modifiedAt = updatedAt ?? highlightedAt ?? ctx.syncedAt;
+
+  const metadata: Record<string, unknown> = {
+    highlight_id: id,
+    text,
+    note,
+    book_id: bookId,
+    location,
+    location_type: locationType,
+    color,
+    tags,
+    source_url: canonicalUrl,
+    highlighted_at: highlightedAt,
+    updated_at: updatedAt,
+    canonical_url: canonicalUrl,
+  };
+
+  return {
+    type: "highlight",
+    externalId: id,
+    title,
+    bodyPreview,
+    url: canonicalUrl,
+    canonicalUrl,
+    modifiedAt,
+    metadata,
+  };
+}

package/connectors/readwise/src/readwise-base.ts

@@ -0,0 +1,6 @@
+/**
+ * The Readwise origin, in ONE place: the read tools and the sync walk both import it. There is no
+ * environment or argument override — the SaaS host is fixed — so the only way to point either at
+ * another host is to substitute this module in a test-only build.
+ */
+export const READWISE_BASE = "https://readwise.io";

package/connectors/readwise/src/record-fields.ts

@@ -0,0 +1,72 @@
+/*
+ * Field readers for the two Readwise mappers, ported unchanged from the gateway's
+ * `unknown-record.ts` and `_lib/field-helpers.ts` (Nimbus origin/main 61e034a5). Each rule is
+ * load-bearing for parity with rows the gateway already indexed, so none of them is "simplified":
+ * `shared/search-filter.ts` has an `asRecord` of the same rule but a `stringField` that returns ""
+ * rather than `undefined`, which would change what a missing field maps to.
+ */
+
+export function asRecord(v: unknown): Record<string, unknown> | undefined {
+  if (v === null || typeof v !== "object" || Array.isArray(v)) {
+    return undefined;
+  }
+  return v as Record<string, unknown>;
+}
+
+export function stringField(r: Record<string, unknown>, key: string): string | undefined {
+  const v = r[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+export function numberField(r: Record<string, unknown>, key: string): number | undefined {
+  const v = r[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/**
+ * The non-empty `name` values of an array of tag objects (`[{ id, name }]`), in input order. A
+ * non-array yields `[]`; an entry that is not a plain object, or whose `name` is absent, not a
+ * string, or empty, is skipped.
+ */
+export function namedTags(raw: unknown): string[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const names: string[] = [];
+  for (const t of raw) {
+    const row = asRecord(t);
+    if (row === undefined) {
+      continue;
+    }
+    const name = stringField(row, "name");
+    if (name !== undefined && name !== "") {
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+/** An ISO-8601 string as epoch ms, or `null` when it is not a string or does not parse. */
+export function parseIsoMs(v: unknown): number | null {
+  return typeof v === "string" && Number.isFinite(Date.parse(v)) ? Date.parse(v) : null;
+}
+
+/**
+ * The one item shape both mappers emit: a sync-v1 `SyncItem` with the body as a preview. Exactly
+ * these eight fields — `service` and `syncedAt` are the gateway's, never the item's.
+ */
+export interface ReadwiseSyncItem {
+  readonly type: "highlight" | "book";
+  readonly externalId: string;
+  readonly title: string;
+  readonly bodyPreview: string;
+  readonly url: string | null;
+  readonly canonicalUrl: string | null;
+  readonly modifiedAt: number;
+  readonly metadata: Record<string, unknown>;
+}
+
+export interface ReadwiseMappingContext {
+  /** The walk's `now`: only the `modifiedAt` fallback for a row with no usable timestamp. */
+  readonly syncedAt: number;
+}

package/connectors/readwise/src/sync-tool.ts

@@ -0,0 +1,56 @@
+/**
+ * The reserved `__nimbus_sync` tool (sync contract v1, `@nimbus-dev/sdk/sync`). Registered by the
+ * extension entry (`extension.ts`) ONLY: the standalone and gateway-bundled `server.ts` never
+ * offers it. A read tool — it only GETs Readwise — and it takes no URL: the host is fixed in
+ * `readwise-base.ts`, and the cursor only ever selects a stream and a page number.
+ */
+import { SYNC_TOOL_NAME, type SyncRequest } from "@nimbus-dev/sdk/sync";
+import { z } from "zod";
+import type { McpListResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { type ReadwiseFetch, readwiseSyncPage } from "./sync.ts";
+
+const SYNC_REQUEST = z.object({
+  cursor: z.string().nullable(),
+  depth: z.enum(["metadata_only", "summary", "full"]),
+  historyFloorMs: z.number().optional(),
+});
+
+/**
+ * The parsed arguments as the SDK's `SyncRequest`. Typed both ways on purpose: `depth` must stay the
+ * SDK's `SyncDepth`, and an absent `historyFloorMs` stays absent rather than `undefined`.
+ */
+function toSyncRequest(args: z.infer<typeof SYNC_REQUEST>): SyncRequest {
+  return {
+    cursor: args.cursor,
+    depth: args.depth,
+    ...(args.historyFloorMs === undefined ? {} : { historyFloorMs: args.historyFloorMs }),
+  };
+}
+
+export interface ReadwiseSyncToolOptions {
+  /** Defaults to the global `fetch`; tests serve Readwise through it. */
+  readonly fetch?: ReadwiseFetch;
+}
+
+export function registerReadwiseSyncTool(
+  reg: ZodToolRegistrar,
+  options: ReadwiseSyncToolOptions = {},
+): void {
+  reg(
+    SYNC_TOOL_NAME,
+    "Nimbus gateway sync (contract v1): one page of the user's Readwise highlights, then books, per call. Reserved for the gateway.",
+    SYNC_REQUEST,
+    async (args): Promise<McpListResult> => {
+      const request = toSyncRequest(args);
+      // `depth` and `historyFloorMs` are accepted and ignored: the gateway applies depth itself,
+      // and Readwise's walk was never bounded by a history floor.
+      const response = await readwiseSyncPage(request.cursor, {
+        // Read per call, as the read tools do, so a token set after start-up is used.
+        token: process.env["READWISE_TOKEN"],
+        ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+      });
+      return { content: [{ type: "text", text: JSON.stringify(response) }] };
+    },
+  );
+}

package/connectors/readwise/src/sync.ts

@@ -0,0 +1,348 @@
+/**
+ * The Readwise sync walk, served one page per `__nimbus_sync` call.
+ *
+ * Ported from the gateway's `readwise-sync.ts` + `runSinglePassPaginatedSync` (Nimbus origin/main
+ * 61e034a5), which walked two streams in one run: highlights (`/api/v2/highlights/`), then books
+ * (`/api/v2/books/`), each at most {@link READWISE_SYNC_MAX_PAGES} DRF pages of 1000. The gateway
+ * now drives the paging, so the position between calls lives in an extension-owned cursor:
+ *
+ * - `null`, the resting cursor, or ANY value this module did not mint → highlights page 1.
+ * - mid-walk: `nimbus-readwise1:` + base64url(`{"stream":"highlights"|"books","page":N}`), the
+ *   encoding the gateway's `encodeNimbusJsonCursor` used for the resting cursor.
+ * - after the last books page: {@link READWISE_RESTING_CURSOR}, byte-identical to the gateway's
+ *   `pass1Cursor()`, with `hasMore: false`.
+ * - a page split for size: the same position plus `"skip":K`, the number of that page's MAPPED
+ *   items (see {@link mapPage}) already returned. See {@link READWISE_SYNC_RESPONSE_BUDGET_BYTES}.
+ *
+ * A stream ends when its page is empty, its `next` is null/empty, or its 20th page was read; the
+ * highlights stream's end hands off to books page 1 in the same response that carries the page's
+ * items. An HTTP error other than 429/401/403, or a body that is not JSON, ends the CURRENT stream
+ * with no items — exactly where today's walk degraded a first-page error to an empty result and
+ * broke out on a later-page one. A rejected fetch propagates (today's `sync()` threw).
+ *
+ * The token is only ever an `Authorization` header value: no response, log or error carries it.
+ */
+import type { SyncResponse } from "@nimbus-dev/sdk/sync";
+import { mapReadwiseBookToItem } from "./book-mapping.ts";
+import { mapReadwiseHighlightToItem } from "./highlight-mapping.ts";
+import { READWISE_BASE } from "./readwise-base.ts";
+import { asRecord, type ReadwiseMappingContext, type ReadwiseSyncItem } from "./record-fields.ts";
+
+type OkResponse = Extract<SyncResponse, { status: "ok" }>;
+
+const CURSOR_PREFIX = "nimbus-readwise1:";
+const PAGE_SIZE = 1000;
+
+/** Per-stream page cap, as today. */
+export const READWISE_SYNC_MAX_PAGES = 20;
+
+export type ReadwiseStream = "highlights" | "books";
+
+export interface ReadwiseCursorPosition {
+  readonly stream: ReadwiseStream;
+  readonly page: number;
+  /**
+   * How many of this page's MAPPED items (after null-mapped rows are dropped and repeated ids
+   * collapsed) earlier calls already returned. Absent means 0; when present, a positive integer.
+   */
+  readonly skip?: number;
+}
+
+/**
+ * The most a response's JSON text may weigh, in UTF-8 bytes. The gateway refuses a `__nimbus_sync`
+ * result over 4 MiB (`MCP_TOOL_RESULT_MAX_BYTES`), which fails the run; 3 MiB leaves room for the
+ * MCP envelope around the text. A page of 1000 long highlights repeats each text in the title, the
+ * preview and the metadata, and can pass 4 MiB, so a page over budget is split across calls.
+ */
+export const READWISE_SYNC_RESPONSE_BUDGET_BYTES = 3 * 1024 * 1024;
+
+const STREAMS: Readonly<
+  Record<
+    ReadwiseStream,
+    {
+      readonly path: string;
+      readonly map: (raw: unknown, ctx: ReadwiseMappingContext) => ReadwiseSyncItem | null;
+    }
+  >
+> = {
+  highlights: { path: "/api/v2/highlights/", map: mapReadwiseHighlightToItem },
+  books: { path: "/api/v2/books/", map: mapReadwiseBookToItem },
+};
+
+function encodePayload(payload: unknown): string {
+  return CURSOR_PREFIX + Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+
+/** The cursor a finished pass rests on: the gateway's `pass1Cursor()`, byte for byte. */
+export const READWISE_RESTING_CURSOR = encodePayload({ pass: 1 });
+
+export function encodeReadwiseCursor(position: ReadwiseCursorPosition): string {
+  const skip = position.skip ?? 0;
+  return encodePayload(
+    skip === 0
+      ? { stream: position.stream, page: position.page }
+      : { stream: position.stream, page: position.page, skip },
+  );
+}
+
+function isStream(v: unknown): v is ReadwiseStream {
+  return v === "highlights" || v === "books";
+}
+
+/**
+ * The position a cursor this module minted points at, or `null` for anything else — which the
+ * walk reads as "start a full pass". Strict: exactly `stream` and `page`, plus `skip` only when it
+ * is a positive safe integer; a known stream, a page within the cap, and the canonical encoding
+ * (so no two spellings name one position).
+ */
+export function decodeReadwiseCursor(raw: string | null): ReadwiseCursorPosition | null {
+  if (!raw?.startsWith(CURSOR_PREFIX)) {
+    return null;
+  }
+  let payload: unknown;
+  try {
+    payload = JSON.parse(
+      Buffer.from(raw.slice(CURSOR_PREFIX.length), "base64url").toString("utf8"),
+    ) as unknown;
+  } catch {
+    return null;
+  }
+  const o = asRecord(payload);
+  if (o === undefined) {
+    return null;
+  }
+  const { stream, page, skip } = o;
+  const keyCount = Object.keys(o).length;
+  if (keyCount === 3) {
+    if (typeof skip !== "number" || !Number.isSafeInteger(skip) || skip < 1) {
+      return null;
+    }
+  } else if (keyCount !== 2) {
+    return null;
+  }
+  if (
+    !isStream(stream) ||
+    typeof page !== "number" ||
+    !Number.isSafeInteger(page) ||
+    page < 1 ||
+    page > READWISE_SYNC_MAX_PAGES
+  ) {
+    return null;
+  }
+  const position: ReadwiseCursorPosition =
+    typeof skip === "number" ? { stream, page, skip } : { stream, page };
+  return encodeReadwiseCursor(position) === raw ? position : null;
+}
+
+/** The fetch the walk uses; a seam so tests serve Readwise without a network. */
+export type ReadwiseFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+export interface ReadwiseSyncDeps {
+  /** `READWISE_TOKEN` as the process received it; blank or absent → `unauthenticated`. */
+  readonly token: string | undefined;
+  /** Defaults to the global `fetch`. */
+  readonly fetch?: ReadwiseFetch;
+  /** Defaults to `Date.now`. The mappers' `modifiedAt` fallback and the Retry-After clock. */
+  readonly now?: () => number;
+  /** Defaults to {@link READWISE_SYNC_RESPONSE_BUDGET_BYTES}; tests lower it to split small pages. */
+  readonly budgetBytes?: number;
+}
+
+type PageOutcome =
+  | { readonly kind: "ok"; readonly parsed: unknown }
+  | { readonly kind: "http_error"; readonly status: number; readonly retryAfter: string | null }
+  | { readonly kind: "parse_error" };
+
+/** A failure's message with every occurrence of the token cut out. */
+function redactedError(e: unknown, token: string): Error {
+  const message = e instanceof Error ? e.message : String(e);
+  return new Error(`Readwise request failed: ${message.split(token).join("[redacted]")}`);
+}
+
+async function getPage(url: string, token: string, fetchFn: ReadwiseFetch): Promise<PageOutcome> {
+  let text: string;
+  let res: Response;
+  try {
+    res = await fetchFn(url, {
+      headers: { Authorization: `Token ${token}`, Accept: "application/json" },
+    });
+    text = await res.text();
+  } catch (e) {
+    throw redactedError(e, token);
+  }
+  if (!res.ok) {
+    return { kind: "http_error", status: res.status, retryAfter: res.headers.get("retry-after") };
+  }
+  try {
+    return { kind: "ok", parsed: JSON.parse(text) as unknown };
+  } catch {
+    return { kind: "parse_error" };
+  }
+}
+
+/** The DRF page envelope both list endpoints use; anything else reads as an empty, final page. */
+function parseReadwisePage(parsed: unknown): { items: unknown[]; hasMore: boolean } {
+  const root = asRecord(parsed);
+  if (root === undefined) {
+    return { items: [], hasMore: false };
+  }
+  const results = root["results"];
+  const items = Array.isArray(results) ? results : [];
+  const nextRaw = root["next"];
+  const next = typeof nextRaw === "string" && nextRaw !== "" ? nextRaw : null;
+  return { items, hasMore: items.length > 0 && next !== null };
+}
+
+/**
+ * `Retry-After` as a non-negative integer of ms: delta-seconds, or an HTTP-date (IMF-fixdate or
+ * RFC 850, both in GMT) as the time until then, clamped at 0. Anything else — absent, negative,
+ * fractional, too large, the obsolete zone-less asctime form — is `undefined`, and the field is
+ * left out so the gateway applies its own default.
+ */
+export function parseRetryAfterMs(header: string | null, now: number): number | undefined {
+  if (header === null) {
+    return undefined;
+  }
+  const v = header.trim();
+  if (/^\d+$/.test(v)) {
+    const ms = Number(v) * 1000;
+    return Number.isSafeInteger(ms) ? ms : undefined;
+  }
+  if (!/^[A-Za-z]{3,9}, .+ GMT$/.test(v)) {
+    return undefined;
+  }
+  const at = Date.parse(v);
+  if (!Number.isSafeInteger(at)) {
+    return undefined;
+  }
+  return Math.max(0, at - now);
+}
+
+function pageUrl(position: ReadwiseCursorPosition): string {
+  const params = new URLSearchParams({ page_size: String(PAGE_SIZE), page: String(position.page) });
+  return `${READWISE_BASE}${STREAMS[position.stream].path}?${params.toString()}`;
+}
+
+/** The mapped rows of one page; a repeated externalId keeps its LAST row, as today's upserts did. */
+function mapPage(
+  rows: readonly unknown[],
+  stream: ReadwiseStream,
+  ctx: ReadwiseMappingContext,
+): ReadwiseSyncItem[] {
+  const byId = new Map<string, ReadwiseSyncItem>();
+  for (const raw of rows) {
+    const item = STREAMS[stream].map(raw, ctx);
+    if (item !== null) {
+      byId.set(item.externalId, item);
+    }
+  }
+  return [...byId.values()];
+}
+
+/** The response that ends `stream`: highlights hand off to books page 1; books end the pass. */
+function endOfStream(stream: ReadwiseStream, items: ReadwiseSyncItem[]): OkResponse {
+  return stream === "highlights"
+    ? {
+        status: "ok",
+        items,
+        cursor: encodeReadwiseCursor({ stream: "books", page: 1 }),
+        hasMore: true,
+      }
+    : { status: "ok", items, cursor: READWISE_RESTING_CURSOR, hasMore: false };
+}
+
+/** The UTF-8 size of the exact text the tool returns for `response`. */
+export function syncResponseBytes(response: SyncResponse): number {
+  return Buffer.byteLength(JSON.stringify(response), "utf8");
+}
+
+/**
+ * `whole` when it fits the budget; otherwise the largest prefix of `items` that fits, with a
+ * cursor that resumes this page right after it. The page's own continuation (next page, handoff,
+ * end of pass) lives in `whole`, so only the call that returns the page's LAST item carries it;
+ * a remainder still over budget is split again by the next call.
+ *
+ * At least one item goes out even when that item alone is over budget, so the walk always
+ * progresses instead of re-fetching the same page forever. That is safe: one item is bounded — the
+ * gateway drops any item whose metadata passes 64 KiB, and its title and preview are one
+ * highlight's or book's own text — so a one-item response stays far under the gateway's 4 MiB.
+ */
+function fitToBudget(
+  whole: OkResponse,
+  position: ReadwiseCursorPosition,
+  budget: number,
+): SyncResponse {
+  // One item (or none) is never split: that response carries the page's own continuation.
+  if (whole.items.length <= 1 || syncResponseBytes(whole) <= budget) {
+    return whole;
+  }
+  const skipped = position.skip ?? 0;
+  const prefix = (count: number): OkResponse => ({
+    status: "ok",
+    items: whole.items.slice(0, count),
+    cursor: encodeReadwiseCursor({ ...position, skip: skipped + count }),
+    hasMore: true,
+  });
+  // The largest count in [1, items - 1] that fits; the size only grows with the count, and all
+  // of the items (`whole`) are already known not to fit.
+  let lo = 1;
+  let hi = whole.items.length - 1;
+  let best = 1;
+  while (lo <= hi) {
+    const mid = Math.floor((lo + hi) / 2);
+    if (syncResponseBytes(prefix(mid)) <= budget) {
+      best = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return prefix(best);
+}
+
+/** One `__nimbus_sync` call: fetch the page `cursor` points at and answer with its items. */
+export async function readwiseSyncPage(
+  cursor: string | null,
+  deps: ReadwiseSyncDeps,
+): Promise<SyncResponse> {
+  const token = deps.token?.trim() ?? "";
+  if (token === "") {
+    return { status: "unauthenticated" };
+  }
+  const position = decodeReadwiseCursor(cursor) ?? { stream: "highlights", page: 1 };
+  const now = (deps.now ?? Date.now)();
+  const fetchFn: ReadwiseFetch = deps.fetch ?? ((url, init) => fetch(url, init));
+
+  const outcome = await getPage(pageUrl(position), token, fetchFn);
+  if (outcome.kind === "http_error") {
+    if (outcome.status === 429) {
+      const retryAfterMs = parseRetryAfterMs(outcome.retryAfter, now);
+      return retryAfterMs === undefined
+        ? { status: "rate_limited" }
+        : { status: "rate_limited", retryAfterMs };
+    }
+    if (outcome.status === 401 || outcome.status === 403) {
+      return { status: "unauthenticated" };
+    }
+    return endOfStream(position.stream, []);
+  }
+  if (outcome.kind === "parse_error") {
+    return endOfStream(position.stream, []);
+  }
+
+  const page = parseReadwisePage(outcome.parsed);
+  // `skip` counts MAPPED items: the same page maps to the same items in the same order, so the
+  // count holds across the calls that split it. A field edited in between changes values, not
+  // positions; a row added to or removed from the page in between shifts the split by that many.
+  const items = mapPage(page.items, position.stream, { syncedAt: now }).slice(position.skip ?? 0);
+  const whole: OkResponse =
+    page.hasMore && position.page < READWISE_SYNC_MAX_PAGES
+      ? {
+          status: "ok",
+          items,
+          cursor: encodeReadwiseCursor({ stream: position.stream, page: position.page + 1 }),
+          hasMore: true,
+        }
+      : endOfStream(position.stream, items);
+  return fitToBudget(whole, position, deps.budgetBytes ?? READWISE_SYNC_RESPONSE_BUDGET_BYTES);
+}