rmapi-js 11.2.0 → 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
@@ -187,11 +187,27 @@ 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;
@@ -273,7 +289,10 @@ class Remarkable {
     async #commit(entry) {
         await this.#withRetry(async () => {
             const [rootHash, generation] = await this.#getRootHash();
-            const { entries } = await this.raw.getEntries(ROOT_SCHEMA, rootHash);
+            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;
@@ -327,18 +346,21 @@ class Remarkable {
         }
     }
     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 {
@@ -381,59 +403,146 @@ 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_SCHEMA, 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);
+    /**
+     * 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);
+    /**
+     * 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);
+    /**
+     * 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);
+    /**
+     * 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 getRmPage(id, hash, pageId) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
-        const content = await this.getContent(id, 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}`);
         }
@@ -442,28 +551,74 @@ class Remarkable {
             return undefined;
         }
         else {
-            return await this.raw.getRm(entry.id, entry.hash);
+            return await this.raw.getRm(entry);
         }
     }
-    async getRmPages(id, hash) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
-        const content = await this.getContent(id, hash);
+    /**
+     * 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.id, entry.hash)));
+        const parsed = await Promise.all(drawn.map(([, entry]) => this.raw.getRm(entry)));
         return new Map(drawn.map(([pageId], index) => [pageId, parsed[index]]));
     }
-    async getDocumentArchive(id, hash) {
-        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
+    /**
+     * 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" });
     }
+    /**
+     * 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");
@@ -510,14 +665,6 @@ class Remarkable {
         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");
@@ -589,9 +736,64 @@ class Remarkable {
         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);
     }
@@ -625,27 +827,56 @@ class Remarkable {
         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;
@@ -657,7 +888,10 @@ class Remarkable {
     async #editContent(hash, update, expectedType, refresh) {
         return await this.#withRetry(async () => {
             const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
-            const { entries } = await this.raw.getEntries(ROOT_SCHEMA, rootHash);
+            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) {
@@ -665,7 +899,7 @@ class Remarkable {
             }
             const [[newEnt, uploadEnt], meta] = await Promise.all([
                 this.#editContentRaw(hashEnt.id, hash, update, schemaVersion),
-                this.getMetadata(hashEnt.id, hash),
+                this.getMetadata(hashEnt),
             ]);
             if (meta.type !== expectedType) {
                 throw new Error(`expected type ${expectedType} but got ${meta.type} for hash ${hash}`);
@@ -674,29 +908,65 @@ class Remarkable {
             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 };
+            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;
@@ -709,7 +979,10 @@ class Remarkable {
     async #editMeta(hash, update, refresh = false) {
         return await this.#withRetry(async () => {
             const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
-            const { entries } = await this.raw.getEntries(ROOT_SCHEMA, rootHash);
+            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) {
@@ -720,41 +993,91 @@ class Remarkable {
             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 };
+            return { id: hashEnt.id, hash: newEnt.hash };
         });
     }
-    /** move an entry */
-    async move(hash, parent, refresh = false) {
+    /**
+     * 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_ID, refresh);
-    }
-    /** rename an entry */
-    async rename(hash, visibleName, refresh = false) {
-        return await this.#editMeta(hash, { visibleName }, 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);
     }
-    /** star or unstar an entry */
-    async star(hash, starred, refresh = false) {
-        return await this.#editMeta(hash, { pinned: starred }, 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);
     }
-    /** @deprecated misspelling; use {@link star | `star`} */
-    async stared(hash, stared, refresh = false) {
-        return await this.star(hash, 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");
         }
         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 { 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) {
@@ -763,26 +1086,56 @@ class Remarkable {
             }
             const resolved = await Promise.all(toUpdate.map(({ id, hash }) => this.#editMetaRaw(id, hash, { parent }, schemaVersion)));
             const uploads = [];
-            const result = {};
+            const result = [];
             for (const [i, [newEnt, upload]] of resolved.entries()) {
                 newEntries.push(newEnt);
                 uploads.push(upload);
-                result[toUpdate[i].hash] = newEnt.hash;
+                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 { hashes: result };
+            return result;
         });
     }
-    /** delete many hashes */
-    async bulkDelete(hashes, refresh = false) {
-        return await this.bulkMove(hashes, TRASH_ID, refresh);
+    /**
+     * 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);
     }
-    /** dump the raw cache */
+    /**
+     * 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
@@ -792,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_SCHEMA, rootHash);
+        const base = await this.raw.getEntries({ id: ROOT_SCHEMA, hash: rootHash });
         let entries = [base.entries];
         let nextEntries = [];
         while (entries.length) {
@@ -800,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 }));
                     }
                 }
             }
@@ -812,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();
     }