rmapi-js 8.1.1 → 8.3.0

package/dist/index.js

@@ -51,25 +51,20 @@
  *
  * @packageDocumentation
  */
-import { fromByteArray } from "base64-js";
-import CRC32C from "crc-32/crc32c";
 import JSZip from "jszip";
-import { boolean, elements, empty, enumeration, float64, int32, nullable, properties, string, timestamp, uint32, uint8, values, } from "jtd-ts";
+import { nullable, string, values } from "jtd-ts";
 import { v4 as uuid4 } from "uuid";
+import { HashNotFoundError, ValidationError } from "./error";
 import { LruCache } from "./lru";
+import { RawRemarkable, } from "./raw";
+export { HashNotFoundError, ValidationError } from "./error";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
 const RAW_HOST = "https://eu.tectonic.remarkable.com";
+// ------------ //
+// Request Info //
+// ------------ //
+// The section has all the types that are stored in the remarkable cloud.
 const idReg = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}||trash)$/;
-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);
 /** 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
@@ -96,27 +91,6 @@ export class ResponseError extends Error {
         this.statusText = statusText;
     }
 }
-/** 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;
-    }
-}
-/** an error that results while supplying a hash not found in the entries of the root hash */
-export class HashNotFoundError extends Error {
-    /** the hash that couldn't be found */
-    hash;
-    constructor(hash) {
-        super(`'${hash}' not found in the root hash`);
-        this.hash = hash;
-    }
-}
 /**
  * register a device and get the token needed to access the api
  *
@@ -149,418 +123,6 @@ export async function register(code, { deviceDesc = "browser-chrome", uuid = uui
         return await resp.text();
     }
 }
-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 templateContent = properties({
-    name: string(),
-    author: string(),
-    iconData: string(),
-    categories: elements(string()),
-    labels: elements(string()),
-    orientation: enumeration("portrait", "landscape"),
-    templateVersion: string(),
-    formatVersion: uint8(),
-    supportedScreens: elements(enumeration("rm2", "rmPP")),
-    constants: elements(values(int32())),
-    items: elements(empty()),
-});
-const documentContent = properties({
-    coverPageNumber: int32(),
-    documentMetadata,
-    extraMetadata: values(string()),
-    fileType: enumeration("epub", "notebook", "pdf"),
-    fontName: string(),
-    formatVersion: uint8(),
-    lineHeight: int32(),
-    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(),
-    margins: 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", "TemplateType"),
-    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("");
-}
-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 try each, and concatenate the errors at the end
-        const errors = [];
-        for (const [name, valid] of [
-            ["collection", collectionContent],
-            ["template", templateContent],
-            ["document", documentContent],
-        ]) {
-            try {
-                if (valid.guardAssert(loaded))
-                    return loaded;
-            }
-            catch (ex) {
-                const msg = ex instanceof Error ? ex.message : "unknown error type";
-                errors.push(`Couldn't validate as ${name} because:\n${msg}`);
-            }
-        }
-        const joined = errors.join("\n\nor\n\n");
-        throw new Error(`invalid content: ${joined}`);
-    }
-    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: 0,
-            subfiles: 0,
-            size: bytes.length,
-        };
-        return [res, this.#putFile(hash, id, bytes)];
-    }
-    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 await this.putText(id, JSON.stringify(content));
-        }
-    }
-    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;
@@ -861,6 +423,56 @@ class Remarkable {
     async uploadPdf(visibleName, buffer, opts = {}) {
         return await this.putPdf(visibleName, buffer, opts);
     }
+    /** edit just a content entry */
+    async #editContentRaw(id, hash, update) {
+        const entries = await this.raw.getEntries(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.hash);
+        Object.assign(cont, update);
+        const [newContEntry, uploadCont] = await this.raw.putContent(contEntry.id, cont);
+        entries[contInd] = newContEntry;
+        const [result, uploadEntries] = await this.raw.putEntries(id, entries);
+        const upload = Promise.all([uploadCont, uploadEntries]);
+        return [result, upload];
+    }
+    /** fully sync a content edit */
+    async #editContent(hash, update, expectedType, refresh) {
+        const [rootHash, generation] = await this.#getRootHash(refresh);
+        const entries = await this.raw.getEntries(rootHash);
+        const hashInd = entries.findIndex((ent) => ent.hash === hash);
+        const hashEnt = entries[hashInd];
+        if (hashEnt === undefined) {
+            throw new HashNotFoundError(hash);
+        }
+        const [[newEnt, uploadEnt], meta] = await Promise.all([
+            this.#editContentRaw(hashEnt.id, hash, update),
+            this.getMetadata(hash),
+        ]);
+        if (meta.type !== expectedType) {
+            throw new Error(`expected type ${expectedType} but got ${meta.type} for hash ${hash}`);
+        }
+        entries[hashInd] = newEnt;
+        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", entries);
+        await Promise.all([uploadEnt, uploadRoot]);
+        await this.#putRootHash(rootEntry.hash, generation);
+        return { hash: newEnt.hash };
+    }
+    /** update document content */
+    async updateDocument(hash, content, refresh = false) {
+        return await this.#editContent(hash, content, "DocumentType", refresh);
+    }
+    /** update collection content */
+    async updateCollection(hash, content, refresh = false) {
+        return await this.#editContent(hash, content, "CollectionType", refresh);
+    }
+    /** update template content */
+    async updateTemplate(hash, content, refresh = false) {
+        return await this.#editContent(hash, content, "TemplateType", refresh);
+    }
     async #editMetaRaw(id, hash, update) {
         const entries = await this.raw.getEntries(hash);
         const metaInd = entries.findIndex((ent) => ent.id.endsWith(".metadata"));
@@ -872,8 +484,8 @@ class Remarkable {
         Object.assign(meta, update);
         const [newMetaEntry, uploadMeta] = await this.raw.putMetadata(metaEntry.id, meta);
         entries[metaInd] = newMetaEntry;
-        const [result, uploadentries] = await this.raw.putEntries(id, entries);
-        const upload = Promise.all([uploadMeta, uploadentries]).then(() => { });
+        const [result, uploadEntries] = await this.raw.putEntries(id, entries);
+        const upload = Promise.all([uploadMeta, uploadEntries]);
         return [result, upload];
     }
     async #editMeta(hash, update, refresh = false) {
@@ -906,6 +518,10 @@ class Remarkable {
     async rename(hash, visibleName, refresh = false) {
         return await this.#editMeta(hash, { visibleName }, refresh);
     }
+    /** stared */
+    async stared(hash, stared, refresh = false) {
+        return await this.#editMeta(hash, { pinned: stared }, refresh);
+    }
     /** move many hashes */
     async bulkMove(hashes, parent, refresh = false) {
         if (!idReg.test(parent)) {
@@ -929,8 +545,7 @@ class Remarkable {
             result[toUpdate[i].hash] = newEnt.hash;
         }
         const [rootEntry, uploadRoot] = await this.raw.putEntries("root", newEntries);
-        uploads.push(uploadRoot);
-        await Promise.all(uploads);
+        await Promise.all([Promise.all(uploads), uploadRoot]);
         await this.#putRootHash(rootEntry.hash, generation);
         return { hashes: result };
     }