rmapi-js 5.0.0 → 7.0.0

package/dist/index.js

@@ -4,10 +4,11 @@
  * After getting a device token with the {@link register | `register`} method,
  * persist it and create api instances using {@link remarkable | `remarkable`}.
  * Outside of registration, all relevant methods are in
- * {@link RemarkableApi | `RemarkableApi`}.
+ * {@link RemarkableApi | `RemarkableApi`}, or it's interior
+ * {@link RawRemarkableApi | `RawRemarkableApi`} (for lower level functions).
  *
  * @example
- * A simple fetch
+ * A simple rename
  * ```ts
  * import { register, remarkable } from "rmapi-js";
  *
@@ -15,17 +16,10 @@
  * const token = await register(code)
  * // persist token
  * const api = await remarkable(token);
- * const rootEntries = await api.getEntries();
- * for (const entry of rootEntries) {
- *   const children = await api.getEntries(entry.hash);
- *   for (const { hash, documentId } of children) {
- *     if (documentId.endsWith(".metadata")) {
- *       const meta = api.getMetadata(hash);
- *       // get metadata for entry
- *       console.log(meta);
- *     }
- *   }
- * }
+ * // list all items (documents and collections)
+ * const [first, ...rest] = api.listItems();
+ * // rename first item
+ * const entry = api.rename(first.hash, "new name");
  * ```
  *
  * @example
@@ -38,173 +32,91 @@
  * await api.create(entry);
  * ```
  *
+ * @remarks
+ *
+ * The cloud api is essentially a collection of entries. Each entry has an id,
+ * which is a uuid4 and a hash, which indicates it's current state, and changes
+ * as the item mutates, where the id is constant. Most mutable operations take
+ * the initial hash so that merge conflicts can be resolved. Each entry has a
+ * number of properties, but a key property is the `parent`, which represents
+ * its parent in the file structure. This will be another document id, or one of
+ * two special ids, "" (the empty string) for the root directory, or "trash" for
+ * the trash.
+ *
+ * Detailed information about the low-level storage an apis can be found in
+ * {@link RawRemarkableApi | `RawRemarkableApi`}.
+ *
+ * Additionally, this entire api was reverse engineered, so some things are only
+ * `[speculative]`, or entirely `[unknown]`. If something breaks, please
+ * [file an issue!](https://github.com/erikbrinkman/rmapi-js/issues)
+ *
  * @packageDocumentation
  */
 import { fromByteArray } from "base64-js";
-import stringify from "json-stable-stringify";
+import CRC32C from "crc-32/crc32c";
+import JSZip from "jszip";
+import { boolean, discriminator, elements, enumeration, float64, int32, nullable, properties, string, timestamp, uint32, uint8, values, } from "jtd-ts";
 import { v4 as uuid4 } from "uuid";
-import { concatBuffers, fromHex, toHex } from "./utils";
-import { validate } from "./validate";
-const SCHEMA_VERSION = "3";
+import { LruCache } from "./lru";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
-const SYNC_HOST = "https://internal.cloud.remarkable.com";
-const GENERATION_HEADER = "x-goog-generation";
-const GENERATION_RACE_HEADER = "x-goog-if-generation-match";
-const CONTENT_LENGTH_RANGE_HEADER = "x-goog-content-length-range";
-/** tool options */
-/* eslint-disable spellcheck/spell-checker */
-export const builtinTools = [
-    "Ballpoint",
-    "Ballpointv2",
-    "Brush",
-    "Calligraphy",
-    "ClearPage",
-    "EraseSection",
-    "Eraser",
-    "Fineliner",
-    "Finelinerv2",
-    "Highlighter",
-    "Highlighterv2",
-    "Marker",
-    "Markerv2",
-    "Paintbrush",
-    "Paintbrushv2",
-    "Pencilv2",
-    "SharpPencil",
-    "SharpPencilv2",
-    "SolidPen",
-    "ZoomTool",
-];
-/* eslint-enable spellcheck/spell-checker */
-/** font name options */
-/* eslint-disable spellcheck/spell-checker */
-export const builtinFontNames = [
-    "Maison Neue",
-    "EB Garamond",
-    "Noto Sans",
-    "Noto Serif",
-    "Noto Mono",
-    "Noto Sans UI",
-];
-/* eslint-enable spellcheck/spell-checker */
-/** text scale options */
-export const builtinTextScales = {
-    /** the smallest */
-    xs: 0.7,
-    /** small */
-    sm: 0.8,
-    /** medium / default */
-    md: 1.0,
-    /** large */
-    lg: 1.2,
-    /** extra large */
-    xl: 1.5,
-    /** double extra large */
-    xx: 2.0,
-};
-/** margin options */
-export const builtinMargins = {
-    /** small */
-    sm: 50,
-    /** medium */
-    md: 125,
-    /** default for read on remarkable */
-    rr: 180,
-    /** large */
-    lg: 200,
-};
-/** line height options */
-export const builtinLineHeights = {
-    /** default */
-    df: -1,
-    /** normal */
-    md: 100,
-    /** half */
-    lg: 150,
-    /** double */
-    xl: 200,
-};
-const uploadEntrySchema = {
-    properties: {
-        docID: { type: "string" },
-        hash: { type: "string" },
-    },
-};
-const urlResponseSchema = {
-    properties: {
-        relative_path: { type: "string" },
-        url: { type: "string" },
-        expires: { type: "timestamp" },
-        method: { enum: ["POST", "GET", "PUT", "DELETE"] },
-    },
-    optionalProperties: {
-        maxuploadsize_bytes: { type: "float64" },
-    },
-};
+const RAW_HOST = "https://eu.tectonic.remarkable.com";
+const SYNC_HOST = "https://web.eu.tectonic.remarkable.com";
+const idReg = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}||trash)$/;
+const hashReg = /^[0-9a-f]{64}$/;
+const tag = properties({
+    name: string(),
+    timestamp: float64(),
+}, undefined, true);
+const pageTag = properties({
+    name: string(),
+    pageId: string(),
+    timestamp: float64(),
+}, undefined, true);
 const commonProperties = {
-    visibleName: { type: "string" },
+    id: string(),
+    hash: string(),
+    visibleName: string(),
+    lastModified: string(),
+    pinned: boolean(),
 };
 const commonOptionalProperties = {
-    lastModified: { type: "string" },
-    version: { type: "int32" },
-    pinned: { type: "boolean" },
-    synced: { type: "boolean" },
-    modified: { type: "boolean" },
-    deleted: { type: "boolean" },
-    metadatamodified: { type: "boolean" },
-    parent: { type: "string" },
-};
-const metadataSchema = {
-    discriminator: "type",
-    mapping: {
-        CollectionType: {
-            properties: commonProperties,
-            optionalProperties: commonOptionalProperties,
-            additionalProperties: true,
-        },
-        DocumentType: {
-            properties: commonProperties,
-            optionalProperties: {
-                ...commonOptionalProperties,
-                lastOpened: { type: "string" },
-                lastOpenedPage: { type: "int32" },
-                createdTime: { type: "string" },
-            },
-            additionalProperties: true,
-        },
-    },
-};
-const baseMetadataProperties = {
-    id: { type: "string" },
-    hash: { type: "string" },
-};
-const metadataEntrySchema = {
-    discriminator: "type",
-    mapping: {
-        CollectionType: {
-            properties: {
-                ...commonProperties,
-                ...baseMetadataProperties,
-            },
-            optionalProperties: commonOptionalProperties,
-            additionalProperties: true,
-        },
-        DocumentType: {
-            properties: {
-                ...commonProperties,
-                ...baseMetadataProperties,
-                fileType: { enum: ["notebook", "epub", "pdf", ""] },
-            },
-            optionalProperties: {
-                ...commonOptionalProperties,
-                lastOpened: { type: "string" },
-                lastOpenedPage: { type: "int32" },
-                createdTime: { type: "string" },
-            },
-            additionalProperties: true,
-        },
-    },
+    parent: string(),
+    tags: elements(properties({
+        name: string(),
+        timestamp: float64(),
+    }, undefined, true)),
 };
+const entry = discriminator("type", {
+    CollectionType: properties(commonProperties, commonOptionalProperties, true),
+    DocumentType: properties({
+        ...commonProperties,
+        lastOpened: string(),
+        fileType: enumeration("epub", "pdf", "notebook"),
+    }, commonOptionalProperties, true),
+});
+const entries = elements(entry);
+const uploadEntry = properties({
+    docID: string(),
+    hash: string(),
+}, undefined, true);
+const hashEntry = properties({ hash: string() }, undefined, true);
+const hashesEntry = properties({
+    hashes: values(string()),
+}, undefined, true);
+/** An error that gets thrown when the backend while trying to update
+ *
+ * IF you encounter this error, you likely just need to try th request again. If
+ * you're trying to do several high-level `put` operations simultaneously,
+ * you'll likely encounter this error. You should either try to do them
+ * serially, or call the low level api directly to do one generation update.
+ *
+ * @see {@link RawRemarkableApi | `RawRemarkableApi`}
+ */
+export class GenerationError extends Error {
+    constructor() {
+        super("root generation was stale; try put again");
+    }
+}
 /** an error that results from a failed request */
 export class ResponseError extends Error {
     /** the response status number */
@@ -217,15 +129,16 @@ export class ResponseError extends Error {
         this.statusText = statusText;
     }
 }
-/**
- * an error that results from trying yp update the wrong generation.
- *
- * If we try to update the root hash of files, but the generation has changed
- * relative to the one we're updating from, this will fail.
- */
-export class GenerationError extends Error {
-    constructor() {
-        super("Generation preconditions failed. This means the current state is out of date with the cloud and needs to be re-synced.");
+/** an error that results from a failed request */
+export class ValidationError extends Error {
+    /** the response status number */
+    field;
+    /** the response status text */
+    regex;
+    constructor(field, regex, message) {
+        super(message);
+        this.field = field;
+        this.regex = regex;
     }
 }
 /**
@@ -238,7 +151,7 @@ export class GenerationError extends Error {
  * @param code - the eight letter code a user got from `https://my.remarkable.com/device/browser/connect`.
  * @returns the device token necessary for creating an api instace. These never expire so persist as long as necessary.
  */
-export async function register(code, { deviceDesc = "browser-chrome", uuid = uuid4(), authHost = AUTH_HOST, fetch = globalThis.fetch, } = {}) {
+export async function register(code, { deviceDesc = "browser-chrome", uuid = uuid4(), authHost = AUTH_HOST, } = {}) {
     if (code.length !== 8) {
         throw new Error(`code should be length 8, but was ${code.length}`);
     }
@@ -260,71 +173,433 @@ export async function register(code, { deviceDesc = "browser-chrome", uuid = uui
         return await resp.text();
     }
 }
-/** format an entry */
-export function formatEntry({ hash, type, documentId, subfiles, size, }) {
-    return `${hash}:${type}:${documentId}:${subfiles}:${size}\n`;
+const documentMetadata = properties(undefined, {
+    authors: elements(string()),
+    title: string(),
+    publicationDate: string(),
+    publisher: string(),
+}, true);
+const cPagePage = properties({
+    id: string(),
+    idx: properties({
+        timestamp: string(),
+        value: string(),
+    }, undefined, true),
+}, {
+    template: properties({
+        timestamp: string(),
+        value: string(),
+    }, undefined, true),
+    redir: properties({
+        timestamp: string(),
+        value: int32(),
+    }, undefined, true),
+    scrollTime: properties({
+        timestamp: string(),
+        value: timestamp(),
+    }, undefined, true),
+    verticalScroll: properties({
+        timestamp: string(),
+        value: float64(),
+    }, undefined, true),
+    deleted: properties({
+        timestamp: string(),
+        value: int32(),
+    }, undefined, true),
+}, true);
+const cPages = properties({
+    lastOpened: properties({
+        timestamp: string(),
+        value: string(),
+    }, undefined, true),
+    original: properties({
+        timestamp: string(),
+        value: int32(),
+    }, undefined, true),
+    pages: elements(cPagePage),
+    uuids: elements(properties({
+        first: string(),
+        second: uint32(),
+    }, undefined, true)),
+}, undefined, true);
+const collectionContent = properties(undefined, {
+    tags: elements(tag),
+});
+const documentContent = properties({
+    coverPageNumber: int32(),
+    documentMetadata,
+    extraMetadata: values(string()),
+    fileType: enumeration("epub", "notebook", "pdf"),
+    fontName: string(),
+    formatVersion: uint8(),
+    lineHeight: int32(),
+    margins: uint32(),
+    orientation: enumeration("portrait", "landscape"),
+    pageCount: uint32(),
+    sizeInBytes: string(),
+    textAlignment: enumeration("justify", "left"),
+    textScale: float64(),
+}, {
+    cPages,
+    customZoomCenterX: float64(),
+    customZoomCenterY: float64(),
+    customZoomOrientation: enumeration("portrait", "landscape"),
+    customZoomPageHeight: float64(),
+    customZoomPageWidth: float64(),
+    customZoomScale: float64(),
+    dummyDocument: boolean(),
+    keyboardMetadata: properties({
+        count: uint32(),
+        timestamp: float64(),
+    }, undefined, true),
+    lastOpenedPage: uint32(),
+    originalPageCount: int32(),
+    pages: elements(string()),
+    pageTags: elements(pageTag),
+    redirectionPageMap: elements(int32()),
+    tags: elements(tag),
+    transform: properties({
+        m11: float64(),
+        m12: float64(),
+        m13: float64(),
+        m21: float64(),
+        m22: float64(),
+        m23: float64(),
+        m31: float64(),
+        m32: float64(),
+        m33: float64(),
+    }, undefined, true),
+    // eslint-disable-next-line spellcheck/spell-checker
+    viewBackgroundFilter: enumeration("off", "fullpage"),
+    zoomMode: enumeration("bestFit", "customFit", "fitToHeight", "fitToWidth"),
+}, true);
+const metadata = properties({
+    lastModified: string(),
+    parent: string(),
+    pinned: boolean(),
+    type: enumeration("DocumentType", "CollectionType"),
+    visibleName: string(),
+}, {
+    lastOpened: string(),
+    lastOpenedPage: uint32(),
+    createdTime: string(),
+    deleted: boolean(),
+    metadatamodified: boolean(),
+    modified: boolean(),
+    synced: boolean(),
+    version: uint8(),
+}, true);
+const updatedRootHash = properties({
+    hash: string(),
+    generation: float64(),
+}, undefined, true);
+const rootHash = properties({
+    hash: string(),
+    generation: float64(),
+    schemaVersion: uint8(),
+}, undefined, true);
+async function digest(buff) {
+    const digest = await crypto.subtle.digest("SHA-256", buff);
+    return [...new Uint8Array(digest)]
+        .map((x) => x.toString(16).padStart(2, "0"))
+        .join("");
 }
-/** parse an entry */
-export function parseEntry(line) {
-    const [hash, type, documentId, subfiles, size] = line.split(":");
-    if (hash === undefined ||
-        type === undefined ||
-        documentId === undefined ||
-        subfiles === undefined ||
-        size === undefined) {
-        throw new Error(`entries line didn't contain five fields: '${line}'`);
-    }
-    if (type === "80000000") {
-        return {
+class RawRemarkable {
+    #authedFetch;
+    #rawHost;
+    /**
+     * a cache of all hashes we know exist
+     *
+     * The backend is a readonly file system of hashes to content. After a hash has
+     * been read or written successfully, we know it exists, and potentially it's
+     * contents. We don't want to cache large binary files, but we can cache the
+     * small text based metadata files. For binary files we write null, so we know
+     * not to write a a cached value again, but we'll still need to read it.
+     */
+    #cache;
+    constructor(authedFetch, cache, rawHost) {
+        this.#authedFetch = authedFetch;
+        this.#cache = cache;
+        this.#rawHost = rawHost;
+    }
+    /** make an authorized request to remarkable */
+    async getRootHash() {
+        const res = await this.#authedFetch("GET", `${this.#rawHost}/sync/v4/root`);
+        const raw = await res.text();
+        const loaded = JSON.parse(raw);
+        if (!rootHash.guardAssert(loaded))
+            throw Error("invalid root hash");
+        const { hash, generation, schemaVersion } = loaded;
+        if (schemaVersion !== 3) {
+            throw new Error(`schema version ${schemaVersion} not supported`);
+        }
+        else if (!Number.isSafeInteger(generation)) {
+            throw new Error(`generation ${generation} was not a safe integer; please file a bug report`);
+        }
+        else {
+            return [hash, generation];
+        }
+    }
+    async #getHash(hash) {
+        if (!hashReg.test(hash)) {
+            throw new ValidationError(hash, hashReg, "hash was not a valid hash");
+        }
+        const resp = await this.#authedFetch("GET", `${this.#rawHost}/sync/v3/files/${hash}`);
+        // TODO switch to `.bytes()`.
+        const raw = await resp.arrayBuffer();
+        return new Uint8Array(raw);
+    }
+    async getHash(hash) {
+        const cached = this.#cache.get(hash);
+        if (cached != null) {
+            const enc = new TextEncoder();
+            return enc.encode(cached);
+        }
+        else {
+            const res = await this.#getHash(hash);
+            // mark that we know hash exists
+            const cacheVal = this.#cache.get(hash);
+            if (cacheVal === undefined) {
+                this.#cache.set(hash, null);
+            }
+            return res;
+        }
+    }
+    async getText(hash) {
+        const cached = this.#cache.get(hash);
+        if (cached != null) {
+            return cached;
+        }
+        else {
+            // NOTE two simultaneous requests will fetch twice
+            const raw = await this.#getHash(hash);
+            const dec = new TextDecoder();
+            const res = dec.decode(raw);
+            this.#cache.set(hash, res);
+            return res;
+        }
+    }
+    async getEntries(hash) {
+        const rawFile = await this.getText(hash);
+        const [version, ...rest] = rawFile.slice(0, -1).split("\n");
+        if (version != "3") {
+            throw new Error(`schema version ${version} not supported`);
+        }
+        else {
+            return rest.map((line) => {
+                const [hash, type, id, subfiles, size] = line.split(":");
+                if (hash === undefined ||
+                    type === undefined ||
+                    id === undefined ||
+                    subfiles === undefined ||
+                    size === undefined) {
+                    throw new Error(`line '${line}' was not formatted correctly`);
+                }
+                else if (type === "80000000") {
+                    return {
+                        hash,
+                        type: 80000000,
+                        id,
+                        subfiles: parseInt(subfiles),
+                        size: parseInt(size),
+                    };
+                }
+                else if (type === "0" && subfiles === "0") {
+                    return {
+                        hash,
+                        type: 0,
+                        id,
+                        subfiles: 0,
+                        size: parseInt(size),
+                    };
+                }
+                else {
+                    throw new Error(`line '${line}' was not formatted correctly`);
+                }
+            });
+        }
+    }
+    async getContent(hash) {
+        const raw = await this.getText(hash);
+        const loaded = JSON.parse(raw);
+        // jtd can't verify non-discriminated unions, in this case, we have fileType
+        // defined or not. As a result, we only do a normal guard for the presence
+        // of tags (e.g. empty content or only specify tags). Otherwise we'll throw
+        // the full error for the richer content.
+        if (collectionContent.guard(loaded)) {
+            return loaded;
+        }
+        else if (documentContent.guardAssert(loaded)) {
+            return loaded;
+        }
+        else {
+            throw Error("invalid content");
+        }
+    }
+    async getMetadata(hash) {
+        const raw = await this.getText(hash);
+        const loaded = JSON.parse(raw);
+        if (!metadata.guardAssert(loaded))
+            throw Error("invalid metadata");
+        return loaded;
+    }
+    async putRootHash(hash, generation, broadcast = true) {
+        if (!Number.isSafeInteger(generation)) {
+            throw new Error(`generation ${generation} was not a safe integer`);
+        }
+        else if (!hashReg.test(hash)) {
+            throw new ValidationError(hash, hashReg, "rootHash was not a valid hash");
+        }
+        const body = JSON.stringify({
+            hash,
+            generation,
+            broadcast,
+        });
+        const resp = await this.#authedFetch("PUT", `${this.#rawHost}/sync/v3/root`, { body });
+        const raw = await resp.text();
+        const loaded = JSON.parse(raw);
+        if (!updatedRootHash.guardAssert(loaded))
+            throw Error("invalid root hash");
+        const { hash: newHash, generation: newGen } = loaded;
+        if (Number.isSafeInteger(newGen)) {
+            return [newHash, newGen];
+        }
+        else {
+            throw new Error(`new generation ${newGen} was not a safe integer; please file a bug report`);
+        }
+    }
+    async #putFile(hash, fileName, bytes) {
+        // if the hash is already in the cache, writing is pointless
+        if (!this.#cache.has(hash)) {
+            const crc = CRC32C.buf(bytes, 0);
+            const buff = new ArrayBuffer(4);
+            new DataView(buff).setInt32(0, crc, false);
+            const crcHash = fromByteArray(new Uint8Array(buff));
+            await this.#authedFetch("PUT", `${this.#rawHost}/sync/v3/files/${hash}`, {
+                body: bytes,
+                headers: {
+                    "rm-filename": fileName,
+                    // eslint-disable-next-line spellcheck/spell-checker
+                    "x-goog-hash": `crc32c=${crcHash}`,
+                },
+            });
+            // mark that we know this hash exists
+            const cacheVal = this.#cache.get(hash);
+            if (cacheVal === undefined) {
+                this.#cache.set(hash, null);
+            }
+        }
+    }
+    async putFile(id, bytes) {
+        const hash = await digest(bytes);
+        const res = {
+            id,
             hash,
-            type,
-            documentId,
-            subfiles: parseInt(subfiles),
-            size: BigInt(size),
+            type: 0,
+            subfiles: 0,
+            size: bytes.length,
         };
+        return [res, this.#putFile(hash, id, bytes)];
     }
-    else if (type === "0") {
-        if (subfiles !== "0") {
-            throw new Error(`file type entry had nonzero number of subfiles: ${subfiles}`);
+    async putText(id, text) {
+        const enc = new TextEncoder();
+        const bytes = enc.encode(text);
+        const [ent, upload] = await this.putFile(id, bytes);
+        return [
+            ent,
+            upload.then(() => {
+                // on success, write to cache
+                this.#cache.set(ent.hash, text);
+            }),
+        ];
+    }
+    async putContent(id, content) {
+        if (!id.endsWith(".content")) {
+            throw new Error(`id ${id} did not end with '.content'`);
         }
         else {
-            return {
-                hash,
-                type,
-                documentId,
-                subfiles: 0,
-                size: BigInt(size),
-            };
+            return await this.putText(id, JSON.stringify(content));
         }
     }
-    else {
-        throw new Error(`entries line contained invalid type: ${type}`);
+    async putMetadata(id, metadata) {
+        if (!id.endsWith(".metadata")) {
+            throw new Error(`id ${id} did not end with '.metadata'`);
+        }
+        else {
+            return await this.putText(id, JSON.stringify(metadata));
+        }
+    }
+    async putEntries(id, entries) {
+        // NOTE collections have a special hash function, the hash of their
+        // contents, so this needs to be different
+        entries.sort((a, b) => a.id.localeCompare(b.id));
+        const hashBuff = new Uint8Array(entries.length * 32);
+        for (const [start, { hash }] of entries.entries()) {
+            for (const [i, byte] of (hash.match(/../g) ?? []).entries()) {
+                hashBuff[start * 32 + i] = parseInt(byte, 16);
+            }
+        }
+        const hash = await digest(hashBuff);
+        const size = entries.reduce((acc, ent) => acc + ent.size, 0);
+        const records = ["3\n"];
+        for (const { hash, type, id, subfiles, size } of entries) {
+            records.push(`${hash}:${type}:${id}:${subfiles}:${size}\n`);
+        }
+        const res = {
+            id,
+            hash,
+            type: 80000000,
+            subfiles: entries.length,
+            size,
+        };
+        const enc = new TextEncoder();
+        return [
+            res,
+            // NOTE when monitoring requests, this had the extension .docSchema appended, but I'm not entirely sure why
+            this.#putFile(hash, `${id}.docSchema`, enc.encode(records.join(""))),
+        ];
+    }
+    dumpCache() {
+        return JSON.stringify(Object.fromEntries(this.#cache));
+    }
+    clearCache() {
+        this.#cache.clear();
     }
 }
 /** the implementation of that api */
 class Remarkable {
     #userToken;
-    #fetch;
-    #subtle;
     #syncHost;
-    // caches
-    #cacheLimitBytes;
-    #cache = new Map();
-    #rootCache = null;
-    constructor(userToken, fetch, subtle, syncHost, cacheLimitBytes, initCache) {
+    /** the same cache that underlies the raw api, allowing us to modify it */
+    #cache;
+    raw;
+    #lastHashGen;
+    constructor(userToken, syncHost, rawHost, cache) {
         this.#userToken = userToken;
-        this.#fetch = fetch;
-        this.#subtle = subtle;
         this.#syncHost = syncHost;
-        this.#cacheLimitBytes = cacheLimitBytes;
-        // set cache
-        for (const [hash, val] of initCache) {
-            this.#cache.set(hash, Promise.resolve(val));
+        this.#cache = cache;
+        this.raw = new RawRemarkable((method, url, { body, headers } = {}) => this.#authedFetch(url, { method, body, headers }), cache, rawHost);
+    }
+    async #getRootHash(refresh = false) {
+        if (refresh || this.#lastHashGen === undefined) {
+            this.#lastHashGen = await this.raw.getRootHash();
+        }
+        return this.#lastHashGen;
+    }
+    async #putRootHash(hash, generation) {
+        try {
+            this.#lastHashGen = await this.raw.putRootHash(hash, generation);
+        }
+        catch (ex) {
+            // if we hit a generation error, invalidate our cached generation
+            if (ex instanceof GenerationError) {
+                this.#lastHashGen = undefined;
+            }
+            throw ex;
         }
     }
-    /** make an authorized request to remarkable */
     async #authedFetch(url, { body, method = "POST", headers = {}, }) {
-        const resp = await this.#fetch(url, {
+        const resp = await fetch(url, {
             method,
             headers: {
                 Authorization: `Bearer ${this.#userToken}`,
@@ -334,503 +609,309 @@ class Remarkable {
         });
         if (!resp.ok) {
             const msg = await resp.text();
-            throw new ResponseError(resp.status, resp.statusText, `failed reMarkable request: ${msg}`);
+            if (msg === '{"message":"precondition failed"}\n') {
+                throw new GenerationError();
+            }
+            else {
+                throw new ResponseError(resp.status, resp.statusText, `failed reMarkable request: ${msg}`);
+            }
         }
         else {
             return resp;
         }
     }
-    /** make a signed request to the cloud */
-    async #signedFetch({ url, method, maxuploadsize_bytes }, body, add_headers = {}) {
-        const headers = maxuploadsize_bytes
-            ? {
-                ...add_headers,
-                [CONTENT_LENGTH_RANGE_HEADER]: `0,${maxuploadsize_bytes}`,
-            }
-            : add_headers;
-        const resp = await this.#fetch(url, {
-            method,
+    /** a generic request to the new files api
+     *
+     * @param meta - remarkable metadata to set, often json formatted or empty
+     * @param method - the http method to use
+     * @param contentType - the http content type to set
+     * @param body - body content, often raw bytes or json
+     * @param hash - the hash of a specific file to target
+     */
+    async #fileRequest({ meta = "", method = "GET", 
+    // eslint-disable-next-line spellcheck/spell-checker
+    contentType = "text/plain;charset=UTF-8", body, hash, } = {}) {
+        const encoder = new TextEncoder();
+        const encMeta = encoder.encode(meta);
+        const suffix = hash === undefined ? "" : `/${hash}`;
+        const resp = await this.#authedFetch(`${this.#syncHost}/doc/v2/files${suffix}`, {
             body,
-            headers,
+            method,
+            headers: {
+                "content-type": contentType,
+                "rm-meta": fromByteArray(encMeta),
+                "rm-source": "WebLibrary",
+            },
         });
-        if (!resp.ok) {
-            const msg = await resp.text();
-            throw new ResponseError(resp.status, resp.statusText, msg);
-        }
-        else {
-            return resp;
-        }
-    }
-    /** get the details for how to make a signed request to remarkable cloud */
-    async #getUrl(relativePath, gen, rootHash) {
-        const key = gen === undefined ? "downloads" : "uploads";
-        // NOTE this is done manually to serialize the bigints appropriately
-        const body = rootHash && gen !== null && gen !== undefined
-            ? `{ "http_method": "PUT", "relative_path": "${relativePath}", "root_schema": "${rootHash}", "generation": ${gen} }`
-            : JSON.stringify({ http_method: "GET", relative_path: relativePath });
-        const resp = await this.#authedFetch(`${this.#syncHost}/sync/v2/signed-urls/${key}`, { body });
         const raw = await resp.text();
-        const res = JSON.parse(raw);
-        validate(urlResponseSchema, res);
+        return JSON.parse(raw);
+    }
+    /** list all items */
+    async listItems() {
+        const res = await this.#fileRequest();
+        if (!entries.guardAssert(res))
+            throw Error("invalid entries");
         return res;
     }
-    /**
-     * get the root hash and the current generation
-     */
-    async getRootHash({ cache = true } = {}) {
-        if (cache) {
-            while (this.#rootCache) {
-                try {
-                    const [hash, gen] = await this.#rootCache;
-                    return [hash, gen];
-                }
-                catch {
-                    // noop
-                }
-            }
-        }
-        const prom = (async () => {
-            try {
-                const signed = await this.#getUrl("root");
-                const resp = await this.#signedFetch(signed);
-                const generation = resp.headers.get(GENERATION_HEADER);
-                if (!generation) {
-                    throw new Error("no generation header in root hash");
-                }
-                else {
-                    return [await resp.text(), BigInt(generation)];
-                }
-            }
-            catch (ex) {
-                this.#rootCache = null;
-                throw ex;
-            }
-        })();
-        this.#rootCache = prom;
-        const [hash, gen] = await prom;
-        return [hash, gen];
+    async listIds(refresh = false) {
+        const [hash] = await this.#getRootHash(refresh);
+        const entries = await this.raw.getEntries(hash);
+        return entries.map(({ id, hash }) => ({ id, hash }));
     }
-    /**
-     * write the root hash, incrementing from the current generation
-     */
-    async putRootHash(hash, generation) {
-        const signed = await this.#getUrl("root", generation, hash);
-        let resp;
-        try {
-            resp = await this.#signedFetch(signed, hash, {
-                [GENERATION_RACE_HEADER]: `${generation}`,
-            });
-        }
-        catch (ex) {
-            if (ex instanceof ResponseError && ex.status === 412) {
-                this.#rootCache = null;
-                throw new GenerationError();
-            }
-            else {
-                throw ex;
-            }
+    async getContent(hash) {
+        const entries = await this.raw.getEntries(hash);
+        const [cont] = entries.filter((e) => e.id.endsWith(".content"));
+        if (cont === undefined) {
+            throw new Error(`couldn't find contents for hash ${hash}`);
         }
-        const genStr = resp.headers.get(GENERATION_HEADER);
-        if (!genStr) {
-            throw new Error("no generation header in root hash");
+        else {
+            return await this.raw.getContent(cont.hash);
         }
-        const gen = BigInt(genStr);
-        this.#rootCache = Promise.resolve([hash, gen]);
-        return gen;
     }
-    /**
-     * get content associated with hash
-     */
-    async #getHash(hash) {
-        let cached = this.#cache.get(hash);
-        while (cached) {
-            try {
-                const val = await cached;
-                if (val) {
-                    return val;
-                }
-                else {
-                    cached = undefined; // break
-                }
-            }
-            catch {
-                // try again if promise rejected
-                cached = this.#cache.get(hash);
-            }
+    async getMetadata(hash) {
+        const entries = await this.raw.getEntries(hash);
+        const [meta] = entries.filter((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.hash);
         }
-        const prom = (async () => {
-            const signed = await this.#getUrl(hash);
-            const resp = await this.#signedFetch(signed);
-            return await resp.arrayBuffer();
-        })();
-        // set cache with appropriate promise that cleans up on rejection
-        this.#cache.set(hash, prom.then((buff) => (buff.byteLength < this.#cacheLimitBytes ? buff : null), (ex) => {
-            this.#cache.delete(hash);
-            throw ex;
-        }));
-        return await prom;
-    }
-    /**
-     * get text content associated with hash
-     */
-    async getBuffer(hash) {
-        const buff = await this.#getHash(hash);
-        // copy if it is long enough to be cached to preven mutations
-        return buff.byteLength < this.#cacheLimitBytes ? buff.slice(0) : buff;
-    }
-    /**
-     * get text content associated with hash
-     */
-    async getText(hash) {
-        const buff = await this.#getHash(hash);
-        const decoder = new TextDecoder();
-        return decoder.decode(buff);
-    }
-    /**
-     * get json content associated with hash
-     */
-    async getJson(hash) {
-        const str = await this.getText(hash);
-        return JSON.parse(str);
     }
-    /**
-     * get metadata from hash
-     *
-     * Call with `verify: false` to disable checking the response.
-     */
-    async getMetadata(hash, { verify = true } = {}) {
-        const raw = await this.getJson(hash);
-        validate(metadataSchema, raw, verify);
-        return raw;
+    async getPdf(hash) {
+        const entries = await this.raw.getEntries(hash);
+        const [pdf] = entries.filter((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.hash);
+        }
     }
-    /**
-     * get entries from a collection hash
-     */
-    async getEntries(hash) {
-        if (hash === undefined) {
-            const [newHash] = await this.getRootHash({ cache: true });
-            hash = newHash;
+    async getEpub(hash) {
+        const entries = await this.raw.getEntries(hash);
+        const [epub] = entries.filter((e) => e.id.endsWith(".epub"));
+        if (epub === undefined) {
+            throw new Error(`couldn't find epub for hash ${hash}`);
         }
-        const raw = await this.getText(hash);
-        // slice for trailing new line
-        const [schema, ...lines] = raw.slice(0, -1).split("\n");
-        if (schema !== SCHEMA_VERSION) {
-            throw new Error(`got unexpected schema version: ${schema}`);
+        else {
+            return await this.raw.getHash(epub.hash);
         }
-        return lines.map(parseEntry);
     }
-    /** upload data to hash */
-    async #putHash(hash, body) {
-        // try cached version
-        const cached = this.#cache.get(hash);
-        if (cached) {
-            try {
-                await cached;
-                return;
-            }
-            catch {
-                // noop
-            }
+    async getDocument(hash) {
+        const entries = await this.raw.getEntries(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.hash));
         }
-        // if missing or rejected then put for real
-        const prom = (async () => {
-            try {
-                const signed = await this.#getUrl(hash, null);
-                await this.#signedFetch(signed, body);
-                return body.byteLength < this.#cacheLimitBytes ? body : null;
-            }
-            catch (ex) {
-                this.#cache.delete(hash);
-                throw ex;
-            }
-        })();
-        this.#cache.set(hash, prom);
-        await prom;
+        return zip.generateAsync({ type: "uint8array" });
     }
-    /** put a reference to a set of entries into the cloud */
-    async putEntries(documentId, entries) {
-        // hash of a collection is the hash of all hashes in documentId order
+    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, }) {
+        if (parent && !idReg.test(parent)) {
+            throw new ValidationError(parent, idReg, "parent must be a valid document id");
+        }
+        const id = uuid4();
+        const now = new Date();
         const enc = new TextEncoder();
-        entries.sort((a, b) => a.documentId.localeCompare(b.documentId));
-        const hashes = concatBuffers(entries.map((ent) => fromHex(ent.hash)));
-        const digest = await this.#subtle.digest("SHA-256", hashes);
-        const hash = toHex(new Uint8Array(digest));
-        const entryContents = entries.map(formatEntry).join("");
-        const contents = `${SCHEMA_VERSION}\n${entryContents}`;
-        const buffer = enc.encode(contents).buffer;
-        await this.#putHash(hash, buffer);
-        return {
-            hash,
-            type: "80000000",
-            documentId,
-            subfiles: entries.length,
-            size: 0n,
-        };
+        // upload raw files, and get root hash
+        const [[contentEntry, uploadContent], [metadataEntry, uploadMetadata], [pagedataEntry, uploadPagedata], [fileEntry, uploadFile], [rootHash, generation],] = await Promise.all([
+            this.raw.putContent(`${id}.content`, {
+                coverPageNumber,
+                documentMetadata: { authors, title, publicationDate, publisher },
+                extraMetadata,
+                lineHeight,
+                margins,
+                orientation,
+                fileType,
+                formatVersion: 1,
+                tags: tags?.map((name) => ({ name, timestamp: +now })) ?? [],
+                fontName,
+                textAlignment,
+                textScale,
+                zoomMode,
+                viewBackgroundFilter,
+                // NOTE for some reason we need to "fake" the number of pages at 1, and
+                // create "valid" output for that
+                originalPageCount: 1,
+                pageCount: 1,
+                pageTags: [],
+                pages: [uuid4()],
+                redirectionPageMap: [0],
+                sizeInBytes: buffer.length.toFixed(),
+            }),
+            this.raw.putMetadata(`${id}.metadata`, {
+                parent,
+                pinned,
+                lastModified: (+now).toFixed(),
+                createdTime: (+now).toFixed(),
+                type: "DocumentType",
+                visibleName,
+                lastOpened: "0",
+                lastOpenedPage: 0,
+            }),
+            // eslint-disable-next-line spellcheck/spell-checker
+            this.raw.putFile(`${id}.pagedata`, enc.encode("\n")),
+            this.raw.putFile(`${id}.${fileType}`, buffer),
+            this.#getRootHash(refresh),
+        ]);
+        // now fetch root entries and upload this file entry
+        const [[collectionEntry, uploadCollection], rootEntries] = await Promise.all([
+            this.raw.putEntries(id, [
+                contentEntry,
+                metadataEntry,
+                pagedataEntry,
+                fileEntry,
+            ]),
+            this.raw.getEntries(rootHash),
+        ]);
+        // now upload a new root entry
+        rootEntries.push(collectionEntry);
+        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", rootEntries);
+        // before updating the root hash, first upload everything
+        await Promise.all([
+            uploadContent,
+            uploadMetadata,
+            uploadPagedata,
+            uploadFile,
+            uploadCollection,
+            uploadRoot,
+        ]);
+        await this.#putRootHash(rootEntry.hash, generation);
+        return { id, hash: collectionEntry.hash };
+    }
+    async putPdf(visibleName, buffer, opts = {}) {
+        return await this.#putFile(visibleName, "pdf", buffer, opts);
+    }
+    async putEpub(visibleName, buffer, opts = {}) {
+        return await this.#putFile(visibleName, "epub", buffer, opts);
     }
-    /** put a raw buffer in the cloud */
-    async putBuffer(documentId, buffer) {
-        const digest = await this.#subtle.digest("SHA-256", buffer);
-        const hash = toHex(new Uint8Array(digest));
-        await this.#putHash(hash, buffer);
-        return {
-            hash,
-            type: "0",
-            documentId,
-            subfiles: 0,
-            size: BigInt(buffer.byteLength),
-        };
+    /** upload a file */
+    async #uploadFile(parent, visibleName, buffer, contentType) {
+        if (!idReg.test(parent)) {
+            throw new ValidationError(parent, idReg, "parent must be a valid document id");
+        }
+        const res = await this.#fileRequest({
+            meta: JSON.stringify({ parent, file_name: visibleName }),
+            method: "POST",
+            contentType,
+            body: buffer,
+        });
+        this.#lastHashGen = undefined; // clear the hash gen since this will change it
+        if (!uploadEntry.guardAssert(res))
+            throw Error("invalid upload entry");
+        const { hash, docID: id } = res;
+        return { hash, id };
     }
-    /** put text in the cloud */
-    async putText(documentId, contents) {
-        const enc = new TextEncoder();
-        const encoded = enc.encode(contents).buffer;
-        return await this.putBuffer(documentId, encoded);
-    }
-    /** put json in the cloud */
-    async putJson(documentId, contents) {
-        return await this.putText(documentId, stringify(contents));
-    }
-    /** put metadata into the cloud */
-    async putMetadata(documentId, metadata) {
-        return await this.putJson(`${documentId}.metadata`, metadata);
-    }
-    /** put a new collection (folder) */
-    async putCollection(visibleName, parent = "") {
-        const documentId = uuid4();
-        const lastModified = `${new Date().valueOf()}`;
-        const entryPromises = [];
-        // upload metadata
-        const metadata = {
-            type: "CollectionType",
-            visibleName,
-            version: 0,
-            parent,
-            synced: true,
-            lastModified,
-        };
-        entryPromises.push(this.putMetadata(documentId, metadata));
-        entryPromises.push(this.putText(`${documentId}.content`, "{}"));
-        const entries = await Promise.all(entryPromises);
-        return await this.putEntries(documentId, entries);
-    }
-    /** upload a content file */
-    async #putContent(visibleName, buffer, fileType, parent, content) {
-        /* istanbul ignore if */
-        if (content.fileType !== fileType) {
-            throw new Error(`internal error: fileTypes don't match: ${fileType}, ${content.fileType}`);
-        }
-        const documentId = uuid4();
-        const lastModified = `${new Date().valueOf()}`;
-        const entryPromises = [];
-        // upload main document
-        entryPromises.push(this.putBuffer(`${documentId}.${fileType}`, buffer));
-        // upload metadata
-        const metadata = {
-            type: "DocumentType",
-            visibleName,
-            version: 0,
-            parent,
-            synced: true,
-            lastModified,
-        };
-        entryPromises.push(this.putMetadata(documentId, metadata));
-        entryPromises.push(this.putText(`${documentId}.content`, JSON.stringify(content)));
-        // NOTE we technically get the entries a bit earlier, so could upload this
-        // before all contents are uploaded, but this also saves us from uploading
-        // the contents entry before all have uploaded successfully
-        const entries = await Promise.all(entryPromises);
-        return await this.putEntries(documentId, entries);
+    /** create a folder */
+    async createFolder(visibleName, { parent = "" } = {}) {
+        return await this.#uploadFile(parent, visibleName, new Uint8Array(0), "folder");
     }
     /** upload an epub */
-    async putEpub(visibleName, buffer, { parent = "", margins = 125, orientation, textAlignment, textScale = 1, lineHeight = -1, fontName = "", cover = "visited", lastTool, } = {}) {
-        // upload content file
-        const content = {
-            dummyDocument: false,
-            extraMetadata: {
-                LastTool: lastTool,
-            },
-            fileType: "epub",
-            pageCount: 0,
-            lastOpenedPage: 0,
-            lineHeight: typeof lineHeight === "string"
-                ? builtinLineHeights[lineHeight]
-                : lineHeight,
-            margins: typeof margins === "string" ? builtinMargins[margins] : margins,
-            textScale: typeof textScale === "string"
-                ? builtinTextScales[textScale]
-                : textScale,
-            pages: [],
-            coverPageNumber: cover === "first" ? 0 : -1,
-            formatVersion: 1,
-            orientation,
-            textAlignment,
-            fontName,
-        };
-        return await this.#putContent(visibleName, buffer, "epub", parent, content);
+    async uploadEpub(visibleName, buffer, { parent = "" } = {}) {
+        return await this.#uploadFile(parent, visibleName, buffer, "application/epub+zip");
     }
     /** upload a pdf */
-    async putPdf(visibleName, buffer, { parent = "", orientation, cover = "first", lastTool } = {}) {
-        // upload content file
-        const content = {
-            dummyDocument: false,
-            extraMetadata: {
-                LastTool: lastTool,
-            },
-            fileType: "pdf",
-            pageCount: 0,
-            lastOpenedPage: 0,
-            lineHeight: -1,
-            margins: 125,
-            textScale: 1,
-            pages: [],
-            coverPageNumber: cover === "first" ? 0 : -1,
-            formatVersion: 1,
-            orientation,
-        };
-        return await this.#putContent(visibleName, buffer, "pdf", parent, content);
+    async uploadPdf(visibleName, buffer, { parent = "" } = {}) {
+        return await this.#uploadFile(parent, visibleName, buffer, "application/pdf");
     }
-    /** send sync complete request */
-    async syncComplete(generation) {
-        // NOTE this is done manually to properly serialize the bigint
-        const body = `{ "generation": ${generation} }`;
-        await this.#authedFetch(`${this.#syncHost}/sync/v2/sync-complete`, {
-            body,
+    async #modify(hash, properties) {
+        if (!hashReg.test(hash)) {
+            throw new ValidationError(hash, hashReg, "hash to modify was not a valid hash");
+        }
+        // this does not allow setting pinned, although I don't know why
+        const res = await this.#fileRequest({
+            hash,
+            body: JSON.stringify(properties),
+            method: "PATCH",
         });
+        this.#lastHashGen = undefined; // clear the hash gen since this will change it
+        if (!hashEntry.guardAssert(res))
+            throw Error("invalid hash entry");
+        return res;
     }
-    /** try to sync, always succeed */
-    async #tryPutRootEntries(gen, entries, sync) {
-        const { hash } = await this.putEntries("", entries);
-        const nextGen = await this.putRootHash(hash, gen);
-        if (sync) {
-            try {
-                await this.syncComplete(nextGen);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        }
-        else {
-            return false;
+    /** move an entry */
+    async move(hash, parent) {
+        if (!idReg.test(parent)) {
+            throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
+        return await this.#modify(hash, { parent });
     }
-    /** high level api to create an entry */
-    async create(entry, { cache = true, sync = true } = {}) {
-        const [root, gen] = await this.getRootHash({ cache });
-        const rootEntries = await this.getEntries(root);
-        rootEntries.push(entry);
-        return await this.#tryPutRootEntries(gen, rootEntries, sync);
+    /** delete an entry */
+    async delete(hash) {
+        return await this.move(hash, "trash");
     }
-    /** high level api to move a document / collection */
-    async move(documentId, dest, { cache = true, sync = true } = {}) {
-        const [root, gen] = await this.getRootHash({ cache });
-        const rootEntries = await this.getEntries(root);
-        // check if destination is a collection
-        if (!dest || dest === "trash") {
-            // fine
-        }
-        else {
-            // TODO some of these could be done in parallel
-            const entry = rootEntries.find((ent) => ent.documentId === dest);
-            if (!entry) {
-                throw new Error(`destination id not found: ${dest}`);
-            }
-            else if (entry.type !== "80000000") {
-                throw new Error(`destination id was a raw file: ${dest}`);
-            }
-            const ents = await this.getEntries(entry.hash);
-            const [meta] = ents.filter((ent) => ent.documentId === `${dest}.metadata`);
-            if (!meta) {
-                throw new Error(`destination id didn't have metadata: ${dest}`);
-            }
-            const metadata = await this.getMetadata(meta.hash);
-            if (metadata.type !== "CollectionType") {
-                throw new Error(`destination id wasn't a collection: ${dest}`);
-            }
-        }
-        // get entry to move from root
-        const ind = rootEntries.findIndex((ent) => ent.documentId === documentId);
-        if (ind === -1) {
-            throw new Error(`document not found: ${documentId}`);
-        }
-        const [oldEntry] = rootEntries.splice(ind, 1);
-        if (oldEntry.type !== "80000000") {
-            throw new Error(`document was a raw file: ${documentId}`);
-        }
-        // get metadata from entry
-        const docEnts = await this.getEntries(oldEntry.hash);
-        const metaInd = docEnts.findIndex((ent) => ent.documentId === `${documentId}.metadata`);
-        if (metaInd === -1) {
-            throw new Error(`document didn't have metadata: ${documentId}`);
-        }
-        const [metaEnt] = docEnts.splice(metaInd, 1);
-        const metadata = await this.getMetadata(metaEnt.hash);
-        // update metadata
-        metadata.parent = dest;
-        const newMetaEnt = await this.putMetadata(documentId, metadata);
-        docEnts.push(newMetaEnt);
-        // update root entries
-        const newEntry = await this.putEntries(documentId, docEnts);
-        rootEntries.push(newEntry);
-        return await this.#tryPutRootEntries(gen, rootEntries, sync);
-    }
-    /** get entries and metadata for all files */
-    async getEntriesMetadata({ verify = true } = {}) {
-        const resp = await this.#authedFetch(`${this.#syncHost}/doc/v2/files`, {
-            method: "GET",
-            headers: {
-                "rm-source": "RoR-Browser",
-            },
-        });
-        const raw = await resp.text();
-        const res = JSON.parse(raw);
-        const schema = {
-            elements: metadataEntrySchema,
-        };
-        validate(schema, res, verify);
-        return res;
+    /** rename an entry */
+    async rename(hash, visibleName) {
+        return await this.#modify(hash, { file_name: visibleName });
     }
-    /** upload a file */
-    async #uploadFile(visibleName, buffer, contentType, verify) {
-        const encoder = new TextEncoder();
-        const meta = encoder.encode(JSON.stringify({ file_name: visibleName }));
-        const resp = await this.#authedFetch(`${this.#syncHost}/doc/v2/files`, {
-            body: buffer,
-            headers: {
-                "content-type": contentType,
-                "rm-meta": fromByteArray(meta),
-                "rm-source": "RoR-Browser",
-            },
+    /** bulk modify hashes */
+    async #bulkModify(hashes, properties) {
+        const invalidHashes = hashes.filter((hash) => !hashReg.test(hash));
+        if (invalidHashes.length) {
+            throw new ValidationError(hashes.join(", "), hashReg, "hashes to modify were not a valid hashes");
+        }
+        // this does not allow setting pinned, although I don't know why
+        const res = await this.#fileRequest({
+            body: JSON.stringify({
+                updates: properties,
+                hashes,
+            }),
+            method: "PATCH",
         });
-        const raw = await resp.text();
-        const res = JSON.parse(raw);
-        validate(uploadEntrySchema, res, verify);
+        this.#lastHashGen = undefined; // clear the hash gen since this will change it
+        if (!hashesEntry.guardAssert(res))
+            throw Error("invalid hashes entry");
         return res;
     }
-    /** upload an epub */
-    async uploadEpub(visibleName, buffer, { verify = true } = {}) {
-        return await this.#uploadFile(visibleName, buffer, "application/epub+zip", verify);
-    }
-    /** upload a pdf */
-    async uploadPdf(visibleName, buffer, { verify = true } = {}) {
-        // TODO why doesn't this work
-        return await this.#uploadFile(visibleName, buffer, "application/pdf", verify);
-    }
-    async getCache() {
-        const promises = [];
-        for (const [hash, prom] of this.#cache) {
-            promises.push(prom.then((val) => [hash, val], () => [hash, null]));
-        }
-        const entries = await Promise.all(promises);
-        const cache = new Map();
-        for (const [hash, val] of entries) {
-            if (val) {
-                cache.set(hash, val);
+    /** move many hashes */
+    async bulkMove(hashes, parent) {
+        if (!idReg.test(parent)) {
+            throw new ValidationError(parent, idReg, "parent must be a valid document id");
+        }
+        return await this.#bulkModify(hashes, { parent });
+    }
+    /** delete many hashes */
+    async bulkDelete(hashes) {
+        return await this.bulkMove(hashes, "trash");
+    }
+    // TODO ostensibly we could implement a bulk rename but idk why
+    /** dump the raw cache */
+    dumpCache() {
+        return this.raw.dumpCache();
+    }
+    async pruneCache(refresh) {
+        const [rootHash] = await this.#getRootHash(refresh);
+        // the keys to delete, we'll drop every key we can currently reach
+        const toDelete = new Set(this.#cache.keys());
+        // bfs through entries (to semi-optimize promise waiting, although this
+        // 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.
+        let entries = [await this.raw.getEntries(rootHash)];
+        let nextEntries = [];
+        while (entries.length) {
+            for (const entryList of entries) {
+                for (const { hash, type } of entryList) {
+                    toDelete.add(hash);
+                    if (type === 80000000) {
+                        nextEntries.push(this.raw.getEntries(hash));
+                    }
+                }
             }
+            entries = await Promise.all(nextEntries);
+            nextEntries = [];
+        }
+        for (const key of toDelete) {
+            this.#cache.delete(key);
         }
-        return cache;
+    }
+    // finally remove any values we had in the cache initially, but couldn't reach
+    clearCache() {
+        this.raw.clearCache();
     }
 }
+const cached = values(nullable(string()));
 /**
  * create an instance of the api
  *
@@ -841,10 +922,7 @@ class Remarkable {
  *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export async function remarkable(deviceToken, { fetch = globalThis.fetch, subtle = globalThis.crypto?.subtle, authHost = AUTH_HOST, syncHost = SYNC_HOST, cacheLimitBytes = 1048576, initCache = [], } = {}) {
-    if (!subtle) {
-        throw new Error("subtle was missing, try specifying it manually");
-    }
+export async function remarkable(deviceToken, { authHost = AUTH_HOST, syncHost = SYNC_HOST, rawHost = RAW_HOST, cache, maxCacheSize = Infinity, } = {}) {
     const resp = await fetch(`${authHost}/token/json/2/user/new`, {
         method: "POST",
         headers: {
@@ -855,5 +933,15 @@ export async function remarkable(deviceToken, { fetch = globalThis.fetch, subtle
         throw new Error(`couldn't fetch auth token: ${resp.statusText}`);
     }
     const userToken = await resp.text();
-    return new Remarkable(userToken, fetch, subtle, syncHost, cacheLimitBytes, initCache);
+    const initCache = JSON.parse(cache ?? "{}");
+    if (cached.guard(initCache)) {
+        const entries = Object.entries(initCache);
+        const cache = maxCacheSize === Infinity
+            ? new Map(entries)
+            : new LruCache(maxCacheSize, entries);
+        return new Remarkable(userToken, syncHost, rawHost, cache);
+    }
+    else {
+        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.");
+    }
 }