rmapi-js 11.1.2 → 12.0.0

package/dist/index.js

@@ -19,7 +19,7 @@
  * // list all items (documents and collections)
  * const [first, ...rest] = await api.listItems();
  * // rename first item
- * const entry = await api.rename(first.hash, "new name");
+ * const entry = await api.rename(first, "new name");
  * ```
  *
  * @example
@@ -56,12 +56,77 @@ import { v4 as uuid4 } from "uuid";
 import { z } from "zod";
 import { HashNotFoundError, ValidationError } from "./error.js";
 import { LruCache } from "./lru.js";
-import { RawRemarkable, } from "./raw.js";
+import { parseMetadata, RawRemarkable, } from "./raw.js";
 export { deviceScreens, } from "./devices.js";
 export { HashNotFoundError, ValidationError } from "./error.js";
+export { decodeBrush, rmColors } from "./rm5.js";
+export { crdtKey, END_MARKER, parseRmScene, ROOT_ID } from "./rm6.js";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
 const RAW_HOST = "https://eu.tectonic.remarkable.com";
 const UPLOAD_HOST = "https://internal.cloud.remarkable.com";
+/** the parent id of the root directory */
+const ROOT_ID = "";
+/** the parent id of the trash */
+const TRASH_ID = "trash";
+/** the id of the root entry list */
+const ROOT_LIST = "root";
+/** the file name of the root entry index */
+const ROOT_SCHEMA = `${ROOT_LIST}.docSchema`;
+/** base backoff in milliseconds for transient request retries */
+const TRANSIENT_BASE_MS = 200;
+/** base backoff in milliseconds for generation-conflict retries */
+const GENERATION_BASE_MS = 25;
+/** resolve after a number of milliseconds */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        // don't let a pending backoff keep a node process alive
+        timer.unref?.();
+    });
+}
+/** exponential backoff with full jitter, capped at 30 seconds */
+function backoffMs(attempt, baseMs) {
+    const capped = Math.min(baseMs * 2 ** attempt, 30_000);
+    return Math.random() * capped;
+}
+/**
+ * a mutex acquired by async iteration
+ *
+ * `for await (const _lock of mutex) { ... }` runs the body with the lock held
+ * and releases it when the body exits — by return, throw, or break — the way a
+ * `using` block would. Waiters are served in acquisition order.
+ */
+class Mutex {
+    #tail = Promise.resolve();
+    async *[Symbol.asyncIterator]() {
+        const previous = this.#tail;
+        let release;
+        this.#tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            yield;
+        }
+        finally {
+            release();
+        }
+    }
+}
+/** the ordered page ids of a document's content, from cPages or the legacy list */
+function pageOrder(content) {
+    if ("cPages" in content && content.cPages) {
+        return content.cPages.pages
+            .filter((page) => page.deleted === undefined)
+            .map((page) => page.id);
+    }
+    else if ("pages" in content && content.pages) {
+        return content.pages;
+    }
+    else {
+        return [];
+    }
+}
 // The section has all the types that are stored in the remarkable cloud.
 const idReg = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}||trash)$/;
 /** An error that gets thrown when the backend while trying to update
@@ -122,24 +187,51 @@ export async function register(code, { deviceDesc = "browser-chrome", uuid = uui
         return await resp.text();
     }
 }
-/** the implementation of that api */
+/**
+ * the api for accessing remarkable functions
+ *
+ * There are roughly two types of functions.
+ * - high-level api functions that provide simple access with a single round
+ *   trip based on the web api
+ * - low-level wrapped functions that take more round trips, but provide more
+ *   control and may be faster since they can be cached.
+ *
+ * Most of these functions validate the return values so that typescript is
+ * accurate. However, sometimes those return values are more strict than the
+ * "true" underlying types. If this happens, please [submit a an
+ * issue](https://github.com/erikbrinkman/rmapi-js/issues). In the mean time,
+ * you should be able to use the low level api to work around any restrictive
+ * validation.
+ */
 class Remarkable {
     #sessionToken;
     /** the same cache that underlies the raw api, allowing us to modify it */
     #cache;
+    /** scoped access to the raw low-level api */
     raw;
+    #maxGenerationRetries;
+    #maxTransientRetries;
     #lastHashGen;
     #schemaVersion;
-    constructor(sessionToken, rawHost, uploadHost, cache) {
+    /** serializes root updates on this instance so they don't self-conflict */
+    #rootMutex = new Mutex();
+    constructor(sessionToken, rawHost, uploadHost, cache, maxGenerationRetries, maxTransientRetries) {
         this.#sessionToken = sessionToken;
         this.#cache = cache;
+        this.#maxGenerationRetries = maxGenerationRetries;
+        this.#maxTransientRetries = maxTransientRetries;
         this.raw = new RawRemarkable((method, url, { body, headers } = {}) => this.#authedFetch(url, { method, body, headers }), cache, rawHost, uploadHost);
     }
     async #getRootHash(refresh = false) {
         if (refresh || this.#lastHashGen === undefined) {
             const [hash, generation, schemaVersion] = await this.raw.getRootHash();
-            this.#lastHashGen = [hash, generation];
-            this.#schemaVersion = schemaVersion;
+            // a slow older fetch can resolve after a newer write; only accept it if
+            // it doesn't regress the cached generation past a committed root
+            if (this.#lastHashGen === undefined ||
+                generation >= this.#lastHashGen[1]) {
+                this.#lastHashGen = [hash, generation];
+                this.#schemaVersion = schemaVersion;
+            }
         }
         return [...this.#lastHashGen, this.#schemaVersion];
     }
@@ -156,42 +248,119 @@ class Remarkable {
             throw ex;
         }
     }
-    async #authedFetch(url, { body, method = "POST", headers = {}, }) {
-        const resp = await fetch(url, {
-            method,
-            headers: {
-                Authorization: `Bearer ${this.#sessionToken}`,
-                ...headers,
-            },
-            // fetch works correctly with uint8 arrays, but is not hinted correctly
-            body: body,
+    /**
+     * run a root-mutating operation, retrying on generation conflicts
+     *
+     * On a {@link GenerationError | `GenerationError`} the cached generation was
+     * already invalidated by {@link #putRootHash}, so re-running `op` re-reads the
+     * latest root and re-applies the change. Callers must resolve any random ids
+     * before this so retries reuse the same (cached) blobs.
+     */
+    async #withRetry(op) {
+        // hold the root lock across the whole read-merge-write so concurrent
+        // mutators serialize instead of sharing a generation and forcing each
+        // other into avoidable conflicts
+        for await (const _lock of this.#rootMutex) {
+            for (let attempt = 0;; attempt++) {
+                try {
+                    return await op();
+                }
+                catch (ex) {
+                    if (ex instanceof GenerationError &&
+                        attempt < this.#maxGenerationRetries) {
+                        await sleep(backoffMs(attempt, GENERATION_BASE_MS));
+                    }
+                    else {
+                        throw ex;
+                    }
+                }
+            }
+        }
+        // the mutex yields exactly once, so the loop always returns or throws
+        throw new Error("unreachable");
+    }
+    /**
+     * splice an already-uploaded item entry into the root
+     *
+     * The entry and all its blobs must already be uploaded; only the
+     * generation-dependent root merge is retried, so a conflict re-reads the
+     * latest root and re-appends the (stable) entry without re-uploading blobs.
+     */
+    async #commit(entry) {
+        await this.#withRetry(async () => {
+            const [rootHash, generation] = await this.#getRootHash();
+            const { entries } = await this.raw.getEntries({
+                id: ROOT_SCHEMA,
+                hash: rootHash,
+            });
+            entries.push(entry);
+            const [rootEntry, uploadRoot] = await this.raw.putEntries(ROOT_LIST, entries, 4);
+            await uploadRoot;
+            await this.#putRootHash(rootEntry.hash, generation);
         });
-        if (!resp.ok) {
+    }
+    async #authedFetch(url, { body, method = "POST", headers = {}, }) {
+        // the root PUT is a compare-and-set; retrying a lost-but-applied response
+        // would resurface as a false generation conflict and be double-applied by
+        // #withRetry, so never transient-retry it (GETs and content-addressed file
+        // PUTs are idempotent and safe to retry)
+        const transientRetries = method === "PUT" && url.endsWith("/sync/v3/root")
+            ? 0
+            : this.#maxTransientRetries;
+        for (let attempt = 0;; attempt++) {
+            let resp;
+            try {
+                resp = await fetch(url, {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.#sessionToken}`,
+                        ...headers,
+                    },
+                    // fetch works correctly with uint8 arrays, but is not hinted correctly
+                    body: body,
+                });
+            }
+            catch (ex) {
+                // a network-level failure, retry if we have attempts left
+                if (attempt < transientRetries) {
+                    await sleep(backoffMs(attempt, TRANSIENT_BASE_MS));
+                    continue;
+                }
+                throw ex;
+            }
+            if (resp.ok) {
+                return resp;
+            }
             const msg = await resp.text();
             if (msg === '{"message":"precondition failed"}\n') {
+                // a generation conflict; handled by #withRetry at the high level
                 throw new GenerationError();
             }
+            else if ((resp.status >= 500 || resp.status === 429) &&
+                attempt < transientRetries) {
+                await sleep(backoffMs(attempt, TRANSIENT_BASE_MS));
+            }
             else {
                 throw new ResponseError(resp.status, resp.statusText, `failed reMarkable request: ${msg}`);
             }
         }
-        else {
-            return resp;
-        }
     }
     async #convertEntry({ hash, id }) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
         const metaEnt = entries.find((ent) => ent.id.endsWith(".metadata"));
         const contentEnt = entries.find((ent) => ent.id.endsWith(".content"));
         if (metaEnt === undefined) {
             throw new Error(`couldn't find metadata for hash ${hash}`);
         }
         const [{ visibleName, lastModified, pinned, parent, lastOpened, createdTime, new: isNew, source, }, content,] = await Promise.all([
-            this.raw.getMetadata(metaEnt.id, metaEnt.hash),
+            this.raw.getMetadata(metaEnt),
             // collections don't always have content, since content only lists tags
             contentEnt === undefined
                 ? Promise.resolve({ fileType: undefined, tags: undefined })
-                : this.raw.getContent(contentEnt.id, contentEnt.hash),
+                : this.raw.getContent(contentEnt),
         ]);
         if ("templateVersion" in content) {
             return {
@@ -234,66 +403,269 @@ class Remarkable {
             };
         }
     }
-    /** list all items */
+    /**
+     * list all items
+     *
+     * Items include both collections and documents. Documents that are in folders
+     * will have their parent set to something other than "" or "trash", but
+     * everything will be returned by this function.
+     *
+     * @example
+     * ```ts
+     * await api.listItems();
+     * ```
+     *
+     * @remarks
+     * This is now backed by the low level api, and you may notice some
+     * performance degradation if not taking advantage of the cache.
+     *
+     * @param refresh - if true, refresh the root hash before listing
+     * @returns a list of all items with some metadata
+     */
     async listItems(refresh = false) {
         const ids = await this.listIds(refresh);
         return await Promise.all(ids.map((id) => this.#convertEntry(id)));
     }
+    /**
+     * similar to {@link listItems | `listItems`} but backed by the low level api
+     *
+     * @param refresh - if true, refresh the root hash before listing
+     */
     async listIds(refresh = false) {
         const [hash] = await this.#getRootHash(refresh);
-        const { entries } = await this.raw.getEntries("root.docSchema", hash);
+        const { entries } = await this.raw.getEntries({ id: ROOT_SCHEMA, hash });
         return entries.map(({ id, hash }) => ({ id, hash }));
     }
-    async getContent(id, hash) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
-        const [cont] = entries.filter((e) => e.id.endsWith(".content"));
+    /**
+     * get the content metadata for an item
+     *
+     * @remarks
+     * If this fails validation and you still want to get the content, you can use
+     * the low-level api to get the raw text of the `.content` file in the
+     * `RawEntry` for this hash.
+     *
+     * @param ref - a reference to the item (e.g. from `listItems` or `listIds`)
+     * @returns the content
+     */
+    async getContent({ id, hash }) {
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
+        const cont = entries.find((e) => e.id.endsWith(".content"));
         if (cont === undefined) {
             throw new Error(`couldn't find contents for hash ${hash}`);
         }
         else {
-            return await this.raw.getContent(cont.id, cont.hash);
+            return await this.raw.getContent(cont);
         }
     }
-    async getMetadata(id, hash) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
-        const [meta] = entries.filter((e) => e.id.endsWith(".metadata"));
+    /**
+     * get the metadata for an item
+     *
+     * @remarks
+     * If this fails validation and you still want to get the content, you can use
+     * the low-level api to get the raw text of the `.metadata` file in the
+     * `RawEntry` for this hash.
+     *
+     * @param ref - a reference to the item (e.g. from `listItems` or `listIds`)
+     * @returns the metadata
+     */
+    async getMetadata({ id, hash }) {
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
+        const meta = entries.find((e) => e.id.endsWith(".metadata"));
         if (meta === undefined) {
             throw new Error(`couldn't find metadata for hash ${hash}`);
         }
         else {
-            return await this.raw.getMetadata(meta.id, meta.hash);
+            return await this.raw.getMetadata(meta);
         }
     }
-    async getPdf(id, hash) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
-        const [pdf] = entries.filter((e) => e.id.endsWith(".pdf"));
+    /**
+     * get the pdf associated with a document
+     *
+     * This returns the raw input pdf, not the rendered pdf with any markup.
+     *
+     * @param ref - a reference to the document (e.g. from `listItems`)
+     * @returns the pdf bytes
+     */
+    async getPdf({ id, hash }) {
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
+        const pdf = entries.find((e) => e.id.endsWith(".pdf"));
         if (pdf === undefined) {
             throw new Error(`couldn't find pdf for hash ${hash}`);
         }
         else {
-            return await this.raw.getHash(pdf.id, pdf.hash);
+            return await this.raw.getHash(pdf);
         }
     }
-    async getEpub(id, hash) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
-        const [epub] = entries.filter((e) => e.id.endsWith(".epub"));
+    /**
+     * get the epub associated with a document
+     *
+     * This returns the raw input epub if a document was created from an epub.
+     *
+     * @param ref - a reference to the document (e.g. from `listItems`)
+     * @returns the epub bytes
+     */
+    async getEpub({ id, hash }) {
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
+        const epub = entries.find((e) => e.id.endsWith(".epub"));
         if (epub === undefined) {
             throw new Error(`couldn't find epub for hash ${hash}`);
         }
         else {
-            return await this.raw.getHash(epub.id, epub.hash);
+            return await this.raw.getHash(epub);
         }
     }
-    async getDocument(id, hash) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
+    /**
+     * get a single page's parsed reMarkable lines (`.rm`) drawing
+     *
+     * @param ref - a reference to the document (e.g. from `listItems`)
+     * @param pageId - the id of the page, from the document's `.content` page
+     *     list (see {@link getRmPages | `getRmPages`} for every page)
+     * @returns the parsed page, or `undefined` if the page exists but has no
+     *     `.rm` drawing (a page you haven't drawn on has no `.rm` file)
+     * @throws if `pageId` is not a page of the document
+     */
+    async getRmPage(ref, pageId) {
+        const { id, hash } = ref;
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
+        const content = await this.getContent(ref);
+        if (!pageOrder(content).includes(pageId)) {
+            throw new Error(`document ${id} has no page ${pageId}`);
+        }
+        const entry = entries.find((ent) => ent.id === `${id}/${pageId}.rm`);
+        if (entry === undefined) {
+            return undefined;
+        }
+        else {
+            return await this.raw.getRm(entry);
+        }
+    }
+    /**
+     * get every drawn page of a document, parsed, keyed by page id
+     *
+     * Returns a map from page id to its parsed {@link RmPage | `RmPage`},
+     * iterating in the page order given by the document's `.content`. Pages with
+     * no drawing (and soft-deleted pages) are omitted. Version 3, 5, and 6 pages
+     * are all supported.
+     *
+     * @param ref - a reference to the document (e.g. from `listItems`)
+     * @returns the drawn pages, keyed by page id, in document order
+     */
+    async getRmPages(ref) {
+        const { id, hash } = ref;
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
+        const content = await this.getContent(ref);
+        const byName = new Map(entries.map((entry) => [entry.id, entry]));
+        const drawn = pageOrder(content)
+            .map((pageId) => [pageId, byName.get(`${id}/${pageId}.rm`)])
+            .filter((pair) => pair[1] !== undefined);
+        const parsed = await Promise.all(drawn.map(([, entry]) => this.raw.getRm(entry)));
+        return new Map(drawn.map(([pageId], index) => [pageId, parsed[index]]));
+    }
+    /**
+     * get a document's entire contents as a zip archive
+     *
+     * This gets every file associated with a document and puts them into a zip
+     * archive.
+     *
+     * @remarks
+     * This is an experimental feature. The resulting archive round-trips back
+     * through {@link putDocumentArchive | `putDocumentArchive`}.
+     *
+     * @param ref - a reference to the document (e.g. from `listItems`)
+     */
+    async getDocumentArchive({ id, hash }) {
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
         const zip = new JSZip();
         for (const entry of entries) {
             // TODO if this is .metadata we might want to assert type === "DocumentType"
-            zip.file(entry.id, this.raw.getHash(entry.id, entry.hash));
+            zip.file(entry.id, this.raw.getHash(entry));
         }
         return zip.generateAsync({ type: "uint8array" });
     }
-    async #putFile(visibleName, fileType, buffer, { refresh, parent = "", pinned = false, zoomMode = "bestFit", viewBackgroundFilter, textScale = 1, textAlignment = "justify", fontName = "", coverPageNumber = -1, authors, title, publicationDate, publisher, extraMetadata = {}, lineHeight = -1, margins = 125, orientation = "portrait", tags, customZoomScale, customZoomCenterX, customZoomCenterY, customZoomPageWidth, customZoomPageHeight, customZoomOrientation, }) {
+    /**
+     * upload a document archive produced by {@link getDocumentArchive | `getDocumentArchive`}
+     *
+     * This explodes the zip archive back into its constituent files, uploads each
+     * as a blob, and commits a new document into the root.
+     *
+     * @remarks
+     * This is an experimental feature. By default a fresh document id is generated
+     * so re-uploading to the same account doesn't collide with the original; pass
+     * {@link PutDocumentOptions.id | `id`} to keep the original id. Like the other
+     * low-level puts, this may throw a {@link GenerationError | `GenerationError`}
+     * if the generation is stale, requiring a retry.
+     *
+     * @param buffer - the archive bytes, as returned by `getDocumentArchive`
+     * @param options - overrides for parent, visible name, and id
+     */
+    async putDocumentArchive(buffer, { refresh = false, parent, visibleName, id: keepId, } = {}) {
+        if (parent !== undefined && parent && !idReg.test(parent)) {
+            throw new ValidationError(parent, idReg, "parent must be a valid document id");
+        }
+        const zip = await JSZip.loadAsync(buffer);
+        const paths = Object.keys(zip.files).filter((path) => !zip.files[path].dir);
+        const metaPath = paths.find((path) => path.endsWith(".metadata"));
+        if (metaPath === undefined) {
+            throw new Error("archive did not contain a .metadata file");
+        }
+        const oldId = metaPath.slice(0, -9);
+        if (oldId.includes("/")) {
+            throw new Error(`unexpected nested .metadata path '${metaPath}'`);
+        }
+        const newId = keepId ?? uuid4();
+        // rewrite the old document id prefix on every archived file to the new id,
+        // patching the .metadata as we pass it (parent/name/lastModified). the
+        // blobs don't depend on the generation, so upload the rewritten files and
+        // the document index once, then let #commit retry only the root merge
+        const enc = new TextEncoder();
+        const dec = new TextDecoder();
+        const lastModified = Date.now().toFixed();
+        const [, , schemaVersion] = await this.#getRootHash(refresh);
+        const fileUploads = await Promise.all(paths.map(async (path) => {
+            if (!path.startsWith(oldId)) {
+                throw new Error(`archived file '${path}' did not start with '${oldId}'`);
+            }
+            const newPath = `${newId}${path.slice(oldId.length)}`;
+            let bytes = await zip.files[path].async("uint8array");
+            if (path === metaPath) {
+                const meta = parseMetadata(dec.decode(bytes));
+                if (parent !== undefined)
+                    meta.parent = parent;
+                if (visibleName !== undefined)
+                    meta.visibleName = visibleName;
+                meta.lastModified = lastModified;
+                bytes = enc.encode(JSON.stringify(meta));
+            }
+            return this.raw.putFile(newPath, bytes);
+        }));
+        const fileEntries = fileUploads.map(([entry]) => entry);
+        const [docEntry, uploadDoc] = await this.raw.putEntries(newId, fileEntries, schemaVersion);
+        await Promise.all([...fileUploads.map(([, upload]) => upload), uploadDoc]);
+        await this.#commit(docEntry);
+        return { id: newId, hash: docEntry.hash };
+    }
+    async #putFile(visibleName, fileType, buffer, { refresh, parent = ROOT_ID, pinned = false, zoomMode = "bestFit", viewBackgroundFilter, textScale = 1, textAlignment = "justify", fontName = "", coverPageNumber = -1, authors, title, publicationDate, publisher, extraMetadata = {}, lineHeight = -1, margins = 125, orientation = "portrait", tags, customZoomScale, customZoomCenterX, customZoomCenterY, customZoomPageWidth, customZoomPageHeight, customZoomOrientation, }) {
         if (parent && !idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
@@ -339,46 +711,94 @@ class Remarkable {
             redirectionPageMap: [0],
             sizeInBytes: buffer.length.toFixed(),
         };
-        // upload raw files, and get root hash
-        const [[contentEntry, uploadContent], [metadataEntry, uploadMetadata], [pagedataEntry, uploadPagedata], [fileEntry, uploadFile], [rootHash, generation, schemaVersion],] = await Promise.all([
+        // the schema version is needed to encode the document index; the blobs
+        // themselves don't depend on the generation, so upload them once and let
+        // #commit retry only the root merge
+        const [, , schemaVersion] = await this.#getRootHash(refresh);
+        const [[contentEntry, uploadContent], [metadataEntry, uploadMetadata], [pagedataEntry, uploadPagedata], [fileEntry, uploadFile],] = await Promise.all([
             this.raw.putContent(`${id}.content`, content),
             this.raw.putMetadata(`${id}.metadata`, metadata),
             this.raw.putText(`${id}.pagedata`, "\n"),
             this.raw.putFile(`${id}.${fileType}`, buffer),
-            this.#getRootHash(refresh),
-        ]);
-        // now fetch root entries and upload this file entry
-        const [[collectionEntry, uploadCollection], { entries: rootEntries }] = await Promise.all([
-            this.raw.putEntries(id, [contentEntry, metadataEntry, pagedataEntry, fileEntry], schemaVersion),
-            this.raw.getEntries("root.docSchema", rootHash),
         ]);
-        // now upload a new root entry
-        rootEntries.push(collectionEntry);
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", rootEntries, 4);
-        // before updating the root hash, first upload everything
+        const [collectionEntry, uploadCollection] = await this.raw.putEntries(id, [contentEntry, metadataEntry, pagedataEntry, fileEntry], schemaVersion);
+        // TODO we could return a full entry here, but we should probably decide
+        // what that should be, e.g. we could return more fields than the standard
+        // entry. Same for putFolder
+        // TODO we should also decide if the api should take hashes or ids...
         await Promise.all([
             uploadContent,
             uploadMetadata,
             uploadPagedata,
             uploadFile,
             uploadCollection,
-            uploadRoot,
         ]);
-        // TODO we could return a full entry here, but we should probably decide
-        // what that should be, e.g. we could return more fields than the standard
-        // entry. Same for putFolder
-        // TODO we should also decide if the api should take hashes or ids...
-        await this.#putRootHash(rootEntry.hash, generation);
+        await this.#commit(collectionEntry);
         return { id, hash: collectionEntry.hash };
     }
+    /**
+     * use the low-level api to add a pdf document
+     *
+     * Since this uses the low-level api, it provides more options than
+     * {@link uploadPdf | `uploadPdf`}, but is a little more finicky. Notably, it
+     * may throw a {@link GenerationError | `GenerationError`} if the generation
+     * doesn't match the current server generation, requiring you to retry until
+     * it works.
+     *
+     * @remarks
+     * When `zoomMode` is `"customFit"` the `customZoom*` fields describe the view,
+     * all in the source page's device pixels: `customZoomPageWidth` and
+     * `customZoomPageHeight` are the page dimensions scaled by the device dpi
+     * (`pagePt * dpi / 72`, see {@link deviceScreens | `deviceScreens`}), and the
+     * centers are in those pixels.
+     *
+     * The view always has the device's aspect ratio — you control its height and
+     * position, not its shape. `customZoomScale = screenHeight / viewHeight` in
+     * device pixels (`screenHeight` fixed per model, see {@link deviceScreens |
+     * `deviceScreens`}), normalized to 1:1 native pixels: at `1` the view is
+     * screen-tall, showing `screenHeight / customZoomPageHeight` of the page.
+     *
+     * `customZoomCenterX` offsets the center of the view horizontally from the
+     * page center, and `customZoomCenterY` is the absolute distance of the center
+     * down from the top of the page; the view's width follows from its height and
+     * the device aspect ratio.
+     *
+     * The fields are a single document-wide setting, but `customZoomCenterY` is
+     * applied against each page's own rendered height. On a page rendered taller
+     * than `customZoomPageHeight` that distance is a smaller fraction of the page,
+     * so the view sits higher and cuts off the bottom; on a shorter page it sits
+     * lower and cuts off the top. `customZoomScale` (a ratio) and
+     * `customZoomCenterX` (an offset from center) do not shift with page size.
+     *
+     * @param visibleName - the name to display on the reMarkable
+     * @param buffer - the raw pdf
+     * @param opts - put options
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns the entry for the newly inserted document
+     */
     async putPdf(visibleName, buffer, opts = {}) {
         return await this.#putFile(visibleName, "pdf", buffer, opts);
     }
+    /**
+     * use the low-level api to add an epub document
+     *
+     * Since this uses the low-level api, it provides more options than
+     * {@link uploadEpub | `uploadEpub`}, but is a little more finicky. Notably, it
+     * may throw a {@link GenerationError | `GenerationError`} if the generation
+     * doesn't match the current server generation, requiring you to retry until
+     * it works.
+     *
+     * @param visibleName - the name to display on the reMarkable
+     * @param buffer - the raw epub
+     * @param opts - put options
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns the entry for the newly inserted document
+     */
     async putEpub(visibleName, buffer, opts = {}) {
         return await this.#putFile(visibleName, "epub", buffer, opts);
     }
     /** create a folder */
-    async putFolder(visibleName, { parent = "" } = {}, refresh = false) {
+    async putFolder(visibleName, { parent = ROOT_ID } = {}, refresh = false) {
         if (parent && !idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
@@ -395,52 +815,68 @@ class Remarkable {
             type: "CollectionType",
             visibleName,
         };
-        // upload folder contents
-        const [[contentEntry, uploadContent], [metadataEntry, uploadMetadata], [rootHash, generation, schemaVersion],] = await Promise.all([
+        // the blobs don't depend on the generation, so upload them once and let
+        // #commit retry only the root merge
+        const [, , schemaVersion] = await this.#getRootHash(refresh);
+        const [[contentEntry, uploadContent], [metadataEntry, uploadMetadata]] = await Promise.all([
             this.raw.putContent(`${id}.content`, content),
             this.raw.putMetadata(`${id}.metadata`, metadata),
-            this.#getRootHash(refresh),
         ]);
-        // now fetch root entries and upload this file entry
-        const [[collectionEntry, uploadCollection], { entries: rootEntries }] = await Promise.all([
-            this.raw.putEntries(id, [contentEntry, metadataEntry], schemaVersion),
-            this.raw.getEntries("root.docSchema", rootHash),
-        ]);
-        // now upload a new root entry
-        rootEntries.push(collectionEntry);
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", rootEntries, 4);
-        // before updating the root hash, first upload everything
-        await Promise.all([
-            uploadContent,
-            uploadMetadata,
-            uploadCollection,
-            uploadRoot,
-        ]);
-        // put root hash and return
-        await this.#putRootHash(rootEntry.hash, generation);
+        const [collectionEntry, uploadCollection] = await this.raw.putEntries(id, [contentEntry, metadataEntry], schemaVersion);
+        await Promise.all([uploadContent, uploadMetadata, uploadCollection]);
+        await this.#commit(collectionEntry);
         return { id, hash: collectionEntry.hash };
     }
-    /** upload an epub */
+    /**
+     * upload an epub
+     *
+     * @example
+     * ```ts
+     * await api.uploadEpub("My EPub", ...);
+     * ```
+     *
+     * @remarks
+     * this uses a simpler api that works even with schema version 4.
+     *
+     * @param visibleName - the name to show for the uploaded epub
+     * @param buffer - the epub contents
+     */
     async uploadEpub(visibleName, buffer) {
         return await this.raw.uploadFile(visibleName, buffer, "application/epub+zip");
     }
-    /** upload a pdf */
+    /**
+     * upload a pdf
+     *
+     * @example
+     * ```ts
+     * await api.uploadPdf("My PDF", ...);
+     * ```
+     *
+     * @remarks
+     * this uses a simpler api that works even with schema version 4.
+     *
+     * @param visibleName - the name to show for the uploaded epub
+     * @param buffer - the epub contents
+     */
     async uploadPdf(visibleName, buffer) {
         return await this.raw.uploadFile(visibleName, buffer, "application/pdf");
     }
-    /** upload a folder */
+    /** create a folder using the simple api */
     async uploadFolder(visibleName) {
         return await this.raw.uploadFile(visibleName, new Uint8Array(0), "folder");
     }
     /** edit just a content entry */
     async #editContentRaw(id, hash, update, schemaVersion) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
         const contInd = entries.findIndex((ent) => ent.id.endsWith(".content"));
         const contEntry = entries[contInd];
         if (contEntry === undefined) {
             throw new Error("internal error: couldn't find content in entry hash");
         }
-        const cont = await this.raw.getContent(contEntry.id, contEntry.hash);
+        const cont = await this.raw.getContent(contEntry);
         Object.assign(cont, update);
         const [newContEntry, uploadCont] = await this.raw.putContent(contEntry.id, cont);
         entries[contInd] = newContEntry;
@@ -450,47 +886,90 @@ class Remarkable {
     }
     /** fully sync a content edit */
     async #editContent(hash, update, expectedType, refresh) {
-        const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
-        const { entries } = await this.raw.getEntries("root.docSchema", rootHash);
-        const hashInd = entries.findIndex((ent) => ent.hash === hash);
-        const hashEnt = entries[hashInd];
-        if (hashEnt === undefined) {
-            throw new HashNotFoundError(hash);
-        }
-        const [[newEnt, uploadEnt], meta] = await Promise.all([
-            this.#editContentRaw(hashEnt.id, hash, update, schemaVersion),
-            this.getMetadata(hashEnt.id, hash),
-        ]);
-        if (meta.type !== expectedType) {
-            throw new Error(`expected type ${expectedType} but got ${meta.type} for hash ${hash}`);
-        }
-        entries[hashInd] = newEnt;
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", entries, 4);
-        await Promise.all([uploadEnt, uploadRoot]);
-        await this.#putRootHash(rootEntry.hash, generation);
-        return { hash: newEnt.hash };
+        return await this.#withRetry(async () => {
+            const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
+            const { entries } = await this.raw.getEntries({
+                id: ROOT_SCHEMA,
+                hash: rootHash,
+            });
+            const hashInd = entries.findIndex((ent) => ent.hash === hash);
+            const hashEnt = entries[hashInd];
+            if (hashEnt === undefined) {
+                throw new HashNotFoundError(hash);
+            }
+            const [[newEnt, uploadEnt], meta] = await Promise.all([
+                this.#editContentRaw(hashEnt.id, hash, update, schemaVersion),
+                this.getMetadata(hashEnt),
+            ]);
+            if (meta.type !== expectedType) {
+                throw new Error(`expected type ${expectedType} but got ${meta.type} for hash ${hash}`);
+            }
+            entries[hashInd] = newEnt;
+            const [rootEntry, uploadRoot] = await this.raw.putEntries(ROOT_LIST, entries, 4);
+            await Promise.all([uploadEnt, uploadRoot]);
+            await this.#putRootHash(rootEntry.hash, generation);
+            return { id: hashEnt.id, hash: newEnt.hash };
+        });
     }
-    /** update document content */
-    async updateDocument(hash, content, refresh = false) {
-        return await this.#editContent(hash, content, "DocumentType", refresh);
+    /**
+     * update content metadata for a document
+     *
+     * @example
+     * ```ts
+     * const next = await api.updateDocument(doc, { textAlignment: "left" });
+     * ```
+     *
+     * @param ref - a reference to the file to update
+     * @param content - the fields of content to update
+     * @returns a reference to the updated entry, with its new hash
+     */
+    async updateDocument(ref, content, refresh = false) {
+        return await this.#editContent(ref.hash, content, "DocumentType", refresh);
     }
-    /** update collection content */
-    async updateCollection(hash, content, refresh = false) {
-        return await this.#editContent(hash, content, "CollectionType", refresh);
+    /**
+     * update content metadata for a collection
+     *
+     * @example
+     * ```ts
+     * const next = await api.updateCollection(dir, { textAlignment: "left" });
+     * ```
+     *
+     * @param ref - a reference to the collection to update
+     * @param content - the fields of content to update
+     * @returns a reference to the updated entry, with its new hash
+     */
+    async updateCollection(ref, content, refresh = false) {
+        return await this.#editContent(ref.hash, content, "CollectionType", refresh);
     }
-    /** update template content */
-    async updateTemplate(hash, content, refresh = false) {
-        return await this.#editContent(hash, content, "TemplateType", refresh);
+    /**
+     * update content metadata for a template
+     *
+     * @example
+     * ```ts
+     * const next = await api.updateTemplate(tmpl, { textAlignment: "left" });
+     * ```
+     *
+     * @param ref - a reference to the template to update
+     * @param content - the fields of content to update
+     * @returns a reference to the updated entry, with its new hash
+     */
+    async updateTemplate(ref, content, refresh = false) {
+        return await this.#editContent(ref.hash, content, "TemplateType", refresh);
     }
     async #editMetaRaw(id, hash, update, schemaVersion) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
+        const { entries } = await this.raw.getEntries({
+            id: `${id}.docSchema`,
+            hash,
+        });
         const metaInd = entries.findIndex((ent) => ent.id.endsWith(".metadata"));
         const metaEntry = entries[metaInd];
         if (metaEntry === undefined) {
             throw new Error("internal error: couldn't find metadata in entry hash");
         }
-        const meta = await this.raw.getMetadata(metaEntry.id, metaEntry.hash);
+        const meta = await this.raw.getMetadata(metaEntry);
         Object.assign(meta, update);
+        meta.version = (meta.version ?? 0) + 1;
+        meta.metadatamodified = true;
         const [newMetaEntry, uploadMeta] = await this.raw.putMetadata(metaEntry.id, meta);
         entries[metaInd] = newMetaEntry;
         const [result, uploadEntries] = await this.raw.putEntries(id, entries, schemaVersion);
@@ -498,74 +977,165 @@ class Remarkable {
         return [result, upload];
     }
     async #editMeta(hash, update, refresh = false) {
-        const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
-        const { entries } = await this.raw.getEntries("root.docSchema", rootHash);
-        const hashInd = entries.findIndex((ent) => ent.hash === hash);
-        const hashEnt = entries[hashInd];
-        if (hashEnt === undefined) {
-            throw new HashNotFoundError(hash);
-        }
-        const [newEnt, uploadEnt] = await this.#editMetaRaw(hashEnt.id, hash, update, schemaVersion);
-        entries[hashInd] = newEnt;
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", entries, 4);
-        await Promise.all([uploadEnt, uploadRoot]);
-        await this.#putRootHash(rootEntry.hash, generation);
-        return { hash: newEnt.hash };
-    }
-    /** move an entry */
-    async move(hash, parent, refresh = false) {
+        return await this.#withRetry(async () => {
+            const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
+            const { entries } = await this.raw.getEntries({
+                id: ROOT_SCHEMA,
+                hash: rootHash,
+            });
+            const hashInd = entries.findIndex((ent) => ent.hash === hash);
+            const hashEnt = entries[hashInd];
+            if (hashEnt === undefined) {
+                throw new HashNotFoundError(hash);
+            }
+            const [newEnt, uploadEnt] = await this.#editMetaRaw(hashEnt.id, hash, update, schemaVersion);
+            entries[hashInd] = newEnt;
+            const [rootEntry, uploadRoot] = await this.raw.putEntries(ROOT_LIST, entries, 4);
+            await Promise.all([uploadEnt, uploadRoot]);
+            await this.#putRootHash(rootEntry.hash, generation);
+            return { id: hashEnt.id, hash: newEnt.hash };
+        });
+    }
+    /**
+     * move an entry
+     *
+     * @example
+     * ```ts
+     * const next = await api.move(doc, dir.id);
+     * ```
+     *
+     * @param ref - a reference to the entry to move
+     * @param parent - the id of the directory to move the entry to, "" (root) and "trash" are special parents
+     * @returns a reference to the moved entry, with its new hash
+     */
+    async move(ref, parent, refresh = false) {
         if (!idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
-        return await this.#editMeta(hash, { parent }, refresh);
+        return await this.#editMeta(ref.hash, { parent }, refresh);
     }
-    /** delete an entry */
-    async delete(hash, refresh = false) {
-        return await this.move(hash, "trash", refresh);
+    /**
+     * delete an entry
+     *
+     * @example
+     * ```ts
+     * await api.delete(file);
+     * ```
+     * @param ref - a reference to the entry to delete
+     * @returns a reference to the deleted entry, with its new hash
+     */
+    async delete(ref, refresh = false) {
+        return await this.move(ref, TRASH_ID, refresh);
     }
-    /** rename an entry */
-    async rename(hash, visibleName, refresh = false) {
-        return await this.#editMeta(hash, { visibleName }, refresh);
+    /**
+     * rename an entry
+     *
+     * @example
+     * ```ts
+     * const next = await api.rename(file, "new name");
+     * ```
+     * @param ref - a reference to the entry to rename
+     * @param visibleName - the new name to assign
+     * @returns a reference to the renamed entry, with its new hash
+     */
+    async rename(ref, visibleName, refresh = false) {
+        return await this.#editMeta(ref.hash, { visibleName }, refresh);
     }
-    /** stared */
-    async stared(hash, stared, refresh = false) {
-        return await this.#editMeta(hash, { pinned: stared }, refresh);
+    /**
+     * star or unstar an entry
+     *
+     * @example
+     * ```ts
+     * const next = await api.star(file, true);
+     * ```
+     * @param ref - a reference to the entry to star
+     * @param starred - whether the entry should be starred or not
+     * @returns a reference to the updated entry, with its new hash
+     */
+    async star(ref, starred, refresh = false) {
+        return await this.#editMeta(ref.hash, { pinned: starred }, refresh);
     }
-    /** move many hashes */
-    async bulkMove(hashes, parent, refresh = false) {
+    /**
+     * move many entries
+     *
+     * @example
+     * ```ts
+     * const next = await api.bulkMove([file], dir.id);
+     * ```
+     *
+     * @param refs - references to the entries to move
+     * @param parent - the directory id to move the entries to, "" (root) and "trash" are special ids
+     * @returns references to the moved entries, each with its new hash
+     */
+    async bulkMove(refs, parent, refresh = false) {
         if (!idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
-        const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
-        const { entries } = await this.raw.getEntries("root.docSchema", rootHash);
-        const hashSet = new Set(hashes);
-        const toUpdate = [];
-        const newEntries = [];
-        for (const entry of entries) {
-            const part = hashSet.has(entry.hash) ? toUpdate : newEntries;
-            part.push(entry);
-        }
-        const resolved = await Promise.all(toUpdate.map(({ id, hash }) => this.#editMetaRaw(id, hash, { parent }, schemaVersion)));
-        const uploads = [];
-        const result = {};
-        for (const [i, [newEnt, upload]] of resolved.entries()) {
-            newEntries.push(newEnt);
-            uploads.push(upload);
-            result[toUpdate[i].hash] = newEnt.hash;
-        }
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", newEntries, 4);
-        await Promise.all([Promise.all(uploads), uploadRoot]);
-        await this.#putRootHash(rootEntry.hash, generation);
-        return { hashes: result };
-    }
-    /** delete many hashes */
-    async bulkDelete(hashes, refresh = false) {
-        return await this.bulkMove(hashes, "trash", refresh);
-    }
-    /** dump the raw cache */
+        return await this.#withRetry(async () => {
+            const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
+            const { entries } = await this.raw.getEntries({
+                id: ROOT_SCHEMA,
+                hash: rootHash,
+            });
+            const hashSet = new Set(refs.map((ref) => ref.hash));
+            const toUpdate = [];
+            const newEntries = [];
+            for (const entry of entries) {
+                const part = hashSet.has(entry.hash) ? toUpdate : newEntries;
+                part.push(entry);
+            }
+            const resolved = await Promise.all(toUpdate.map(({ id, hash }) => this.#editMetaRaw(id, hash, { parent }, schemaVersion)));
+            const uploads = [];
+            const result = [];
+            for (const [i, [newEnt, upload]] of resolved.entries()) {
+                newEntries.push(newEnt);
+                uploads.push(upload);
+                result.push({ id: toUpdate[i].id, hash: newEnt.hash });
+            }
+            const [rootEntry, uploadRoot] = await this.raw.putEntries(ROOT_LIST, newEntries, 4);
+            await Promise.all([Promise.all(uploads), uploadRoot]);
+            await this.#putRootHash(rootEntry.hash, generation);
+            return result;
+        });
+    }
+    /**
+     * delete many entries
+     *
+     * @example
+     * ```ts
+     * await api.bulkDelete([file]);
+     * ```
+     *
+     * @param refs - references to the entries to delete
+     * @returns references to the deleted entries, each with its new hash
+     */
+    async bulkDelete(refs, refresh = false) {
+        return await this.bulkMove(refs, TRASH_ID, refresh);
+    }
+    /**
+     * get the current cache value as a string
+     *
+     * You can use this to warm start a new instance of
+     * {@link remarkable | `remarkable`} with any previously cached results.
+     */
     dumpCache() {
         return this.raw.dumpCache();
     }
+    /**
+     * prune the cache so that it contains only reachable hashes
+     *
+     * The cache is append only, so it can grow without bound, even as hashes
+     * become unreachable. In the future, this may have better cache management to
+     * track this in real time, but for now, you can call this method, to keep it
+     * from growing continuously.
+     *
+     * @remarks
+     * This won't necessarily reduce the cache size. In order to see if
+     * hashes are reachable we first have to search through all existing entry
+     * lists.
+     *
+     * @param refresh - whether to refresh the root hash before pruning
+     */
     async pruneCache(refresh) {
         const [rootHash] = await this.#getRootHash(refresh);
         // start by assuming every cached hash is unreachable, then keep the ones we reach
@@ -575,7 +1145,7 @@ class Remarkable {
         // should only go one step) to track all hashes encountered
         // NOTE that we could increase the cache in this process, or it's possible
         // for other calls to increase the cache with misc values.
-        const base = await this.raw.getEntries("root.docSchema", rootHash);
+        const base = await this.raw.getEntries({ id: ROOT_SCHEMA, hash: rootHash });
         let entries = [base.entries];
         let nextEntries = [];
         while (entries.length) {
@@ -583,7 +1153,7 @@ class Remarkable {
                 for (const { hash, subfiles, id } of entryList) {
                     toDelete.delete(hash);
                     if (subfiles > 0) {
-                        nextEntries.push(this.raw.getEntries(`${id}.docSchema`, hash));
+                        nextEntries.push(this.raw.getEntries({ id: `${id}.docSchema`, hash }));
                     }
                 }
             }
@@ -595,6 +1165,12 @@ class Remarkable {
             this.#cache.delete(key);
         }
     }
+    /**
+     * completely delete the cache
+     *
+     * If the cache is causing memory issues, you can clear it, but this will hurt
+     * performance.
+     */
     clearCache() {
         this.raw.clearCache();
     }
@@ -628,7 +1204,7 @@ export async function auth(deviceToken, { authHost = AUTH_HOST } = {}) {
  * @param sessionToken - the session token used for authorization
  * @returns an api instance
  */
-export function session(sessionToken, { rawHost = RAW_HOST, uploadHost = UPLOAD_HOST, cache, maxCacheSize = Infinity, } = {}) {
+export function session(sessionToken, { rawHost = RAW_HOST, uploadHost = UPLOAD_HOST, cache, maxCacheSize = Infinity, maxGenerationRetries = 10, maxTransientRetries = 3, } = {}) {
     const initCache = JSON.parse(cache ?? "{}");
     const parsedCache = cached.safeParse(initCache);
     if (parsedCache.success) {
@@ -636,7 +1212,7 @@ export function session(sessionToken, { rawHost = RAW_HOST, uploadHost = UPLOAD_
         const cacheMap = maxCacheSize === Infinity
             ? new Map(entries)
             : new LruCache(maxCacheSize, entries);
-        return new Remarkable(sessionToken, rawHost, uploadHost, cacheMap);
+        return new Remarkable(sessionToken, rawHost, uploadHost, cacheMap, maxGenerationRetries, maxTransientRetries);
     }
     throw new Error("cache was not a valid cache (json string mapping); your cache must be corrupted somehow. Either initialize remarkable without a cache, or fix its format.");
 }
@@ -651,12 +1227,14 @@ export function session(sessionToken, { rawHost = RAW_HOST, uploadHost = UPLOAD_
  * @returns an api instance
  */
 export async function remarkable(deviceToken, options = {}) {
-    const { authHost, rawHost, uploadHost, cache, maxCacheSize } = options ?? {};
+    const { authHost, rawHost, uploadHost, cache, maxCacheSize, maxGenerationRetries, maxTransientRetries, } = options ?? {};
     const sessionToken = await auth(deviceToken, { authHost });
     return session(sessionToken, {
         rawHost,
         uploadHost,
         cache,
         maxCacheSize,
+        maxGenerationRetries,
+        maxTransientRetries,
     });
 }