rmapi-js 11.1.2 → 11.2.0

package/dist/index.js

@@ -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
@@ -128,18 +193,29 @@ class Remarkable {
     /** the same cache that underlies the raw api, allowing us to modify it */
     #cache;
     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,28 +232,99 @@ 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(ROOT_SCHEMA, 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);
@@ -241,12 +388,12 @@ class Remarkable {
     }
     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(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"));
+        const cont = entries.find((e) => e.id.endsWith(".content"));
         if (cont === undefined) {
             throw new Error(`couldn't find contents for hash ${hash}`);
         }
@@ -256,7 +403,7 @@ class Remarkable {
     }
     async getMetadata(id, hash) {
         const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
-        const [meta] = entries.filter((e) => e.id.endsWith(".metadata"));
+        const meta = entries.find((e) => e.id.endsWith(".metadata"));
         if (meta === undefined) {
             throw new Error(`couldn't find metadata for hash ${hash}`);
         }
@@ -266,7 +413,7 @@ class Remarkable {
     }
     async getPdf(id, hash) {
         const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
-        const [pdf] = entries.filter((e) => e.id.endsWith(".pdf"));
+        const pdf = entries.find((e) => e.id.endsWith(".pdf"));
         if (pdf === undefined) {
             throw new Error(`couldn't find pdf for hash ${hash}`);
         }
@@ -276,7 +423,7 @@ class Remarkable {
     }
     async getEpub(id, hash) {
         const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
-        const [epub] = entries.filter((e) => e.id.endsWith(".epub"));
+        const epub = entries.find((e) => e.id.endsWith(".epub"));
         if (epub === undefined) {
             throw new Error(`couldn't find epub for hash ${hash}`);
         }
@@ -284,7 +431,31 @@ class Remarkable {
             return await this.raw.getHash(epub.id, epub.hash);
         }
     }
-    async getDocument(id, hash) {
+    async getRmPage(id, hash, pageId) {
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
+        const content = await this.getContent(id, hash);
+        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.id, entry.hash);
+        }
+    }
+    async getRmPages(id, hash) {
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
+        const content = await this.getContent(id, hash);
+        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.id, entry.hash)));
+        return new Map(drawn.map(([pageId], index) => [pageId, parsed[index]]));
+    }
+    async getDocumentArchive(id, hash) {
         const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
         const zip = new JSZip();
         for (const entry of entries) {
@@ -293,7 +464,61 @@ class Remarkable {
         }
         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, }) {
+    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 };
+    }
+    /** @deprecated renamed; use {@link getDocumentArchive | `getDocumentArchive`} */
+    async getDocument(id, hash) {
+        return await this.getDocumentArchive(id, hash);
+    }
+    /** @deprecated renamed; use {@link putDocumentArchive | `putDocumentArchive`} */
+    async putDocument(buffer, options) {
+        return await this.putDocumentArchive(buffer, options);
+    }
+    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,36 +564,29 @@ 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 };
     }
     async putPdf(visibleName, buffer, opts = {}) {
@@ -378,7 +596,7 @@ class Remarkable {
         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,29 +613,16 @@ 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 */
@@ -450,25 +655,27 @@ 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(ROOT_SCHEMA, 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_LIST, entries, 4);
+            await Promise.all([uploadEnt, uploadRoot]);
+            await this.#putRootHash(rootEntry.hash, generation);
+            return { hash: newEnt.hash };
+        });
     }
     /** update document content */
     async updateDocument(hash, content, refresh = false) {
@@ -491,6 +698,8 @@ class Remarkable {
         }
         const meta = await this.raw.getMetadata(metaEntry.id, metaEntry.hash);
         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,19 +707,21 @@ 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 };
+        return await this.#withRetry(async () => {
+            const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
+            const { entries } = await this.raw.getEntries(ROOT_SCHEMA, 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 { hash: newEnt.hash };
+        });
     }
     /** move an entry */
     async move(hash, parent, refresh = false) {
@@ -521,46 +732,52 @@ class Remarkable {
     }
     /** delete an entry */
     async delete(hash, refresh = false) {
-        return await this.move(hash, "trash", refresh);
+        return await this.move(hash, TRASH_ID, refresh);
     }
     /** rename an entry */
     async rename(hash, visibleName, refresh = false) {
         return await this.#editMeta(hash, { visibleName }, refresh);
     }
-    /** stared */
+    /** star or unstar an entry */
+    async star(hash, starred, refresh = false) {
+        return await this.#editMeta(hash, { pinned: starred }, refresh);
+    }
+    /** @deprecated misspelling; use {@link star | `star`} */
     async stared(hash, stared, refresh = false) {
-        return await this.#editMeta(hash, { pinned: stared }, refresh);
+        return await this.star(hash, stared, refresh);
     }
     /** move many hashes */
     async bulkMove(hashes, 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 };
+        return await this.#withRetry(async () => {
+            const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
+            const { entries } = await this.raw.getEntries(ROOT_SCHEMA, 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_LIST, 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);
+        return await this.bulkMove(hashes, TRASH_ID, refresh);
     }
     /** dump the raw cache */
     dumpCache() {
@@ -575,7 +792,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(ROOT_SCHEMA, rootHash);
         let entries = [base.entries];
         let nextEntries = [];
         while (entries.length) {
@@ -628,7 +845,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 +853,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 +868,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,
     });
 }