rmapi-js 7.0.0 → 8.0.0

package/README.md

@@ -73,6 +73,7 @@ this project.
 
 - [✉️ Send Via](https://sendvia.me/) [[github](https://github.com/PaulKinlan/send-to-remarkable)] - upload to reMarkable via email
 - [ⓡ rePub](https://chromewebstore.google.com/detail/repub/blkjpagbjaekkpojgcgdapmikoaolpbl) [[github](https://github.com/hafaio/repub)] - web clipper for reMarkable that supports images and customization
+- [reMarkable Digest](https://digest.ferrucc.io) - create and receive a daily digest on your reMarkable
 
 ## Contributing
 

package/dist/index.d.ts

@@ -146,6 +146,12 @@ export declare class ValidationError extends Error {
     readonly regex: RegExp;
     constructor(field: string, regex: RegExp, message: string);
 }
+/** an error that results while supplying a hash not found in the entries of the root hash */
+export declare class HashNotFoundError extends Error {
+    /** the hash that couldn't be found */
+    readonly hash: string;
+    constructor(hash: string);
+}
 /** options for registering with the api */
 export interface RegisterOptions {
     /**
@@ -671,9 +677,14 @@ export interface RemarkableApi {
      * 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
      */
-    listItems(): Promise<Entry[]>;
+    listItems(refresh?: boolean): Promise<Entry[]>;
     /**
      * similar to {@link listItems | `listItems`} but backed by the low level api
      *
@@ -778,7 +789,7 @@ export interface RemarkableApi {
      */
     putEpub(visibleName: string, buffer: Uint8Array, opts?: PutOptions): Promise<SimpleEntry>;
     /** create a folder */
-    createFolder(visibleName: string, opts?: UploadOptions): Promise<SimpleEntry>;
+    createFolder(visibleName: string, opts?: UploadOptions, refresh?: boolean): Promise<SimpleEntry>;
     /**
      * upload an epub
      *
@@ -787,6 +798,9 @@ export interface RemarkableApi {
      * await api.uploadEpub("My EPub", ...);
      * ```
      *
+     * @remarks
+     * this is now simply a less powerful version of {@link putEpub | `putEpub`}.
+     *
      * @param visibleName - the name to show for the uploaded epub
      * @param buffer - the epub contents
      */
@@ -799,6 +813,9 @@ export interface RemarkableApi {
      * await api.uploadPdf("My PDF", ...);
      * ```
      *
+     * @remarks
+     * this is now simply a less powerful version of {@link putPdf | `putPdf`}.
+     *
      * @param visibleName - the name to show for the uploaded epub
      * @param buffer - the epub contents
      */
@@ -814,7 +831,7 @@ export interface RemarkableApi {
      * @param hash - the hash of the file to move
      * @param parent - the id of the directory to move the entry to, "" (root) and "trash" are special parents
      */
-    move(hash: string, parent: string): Promise<HashEntry>;
+    move(hash: string, parent: string, refresh?: boolean): Promise<HashEntry>;
     /**
      * delete an entry
      *
@@ -824,7 +841,7 @@ export interface RemarkableApi {
      * ```
      * @param hash - the hash of the entry to delete
      */
-    delete(hash: string): Promise<HashEntry>;
+    delete(hash: string, refresh?: boolean): Promise<HashEntry>;
     /**
      * rename an entry
      *
@@ -835,7 +852,7 @@ export interface RemarkableApi {
      * @param hash - the hash of the entry to rename
      * @param visibleName - the new name to assign
      */
-    rename(hash: string, visibleName: string): Promise<HashEntry>;
+    rename(hash: string, visibleName: string, refresh?: boolean): Promise<HashEntry>;
     /**
      * move many entries
      *
@@ -847,7 +864,7 @@ export interface RemarkableApi {
      * @param hashes - an array of entry hashes to move
      * @param parent - the directory id to move the entries to, "" (root) and "trash" are special ids
      */
-    bulkMove(hashes: readonly string[], parent: string): Promise<HashesEntry>;
+    bulkMove(hashes: readonly string[], parent: string, refresh?: boolean): Promise<HashesEntry>;
     /**
      * delete many entries
      *
@@ -858,7 +875,7 @@ export interface RemarkableApi {
      *
      * @param hashes - the hashes of the entries to delete
      */
-    bulkDelete(hashes: readonly string[]): Promise<HashesEntry>;
+    bulkDelete(hashes: readonly string[], refresh?: boolean): Promise<HashesEntry>;
     /**
      * get the current cache value as a string
      *
@@ -938,4 +955,4 @@ export interface RemarkableOptions {
  *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export declare function remarkable(deviceToken: string, { authHost, syncHost, rawHost, cache, maxCacheSize, }?: RemarkableOptions): Promise<RemarkableApi>;
+export declare function remarkable(deviceToken: string, { authHost, rawHost, cache, maxCacheSize, }?: RemarkableOptions): Promise<RemarkableApi>;

package/dist/index.js

@@ -29,7 +29,6 @@
  *
  * const api = await remarkable(...);
  * const entry = await api.putEpub("document name", epubBuffer);
- * await api.create(entry);
  * ```
  *
  * @remarks
@@ -55,12 +54,11 @@
 import { fromByteArray } from "base64-js";
 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 { boolean, elements, enumeration, float64, int32, nullable, properties, string, timestamp, uint32, uint8, values, } from "jtd-ts";
 import { v4 as uuid4 } from "uuid";
 import { LruCache } from "./lru";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
 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({
@@ -72,37 +70,6 @@ const pageTag = properties({
     pageId: string(),
     timestamp: float64(),
 }, undefined, true);
-const commonProperties = {
-    id: string(),
-    hash: string(),
-    visibleName: string(),
-    lastModified: string(),
-    pinned: boolean(),
-};
-const commonOptionalProperties = {
-    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
@@ -141,6 +108,15 @@ export class ValidationError extends Error {
         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
  *
@@ -569,14 +545,12 @@ class RawRemarkable {
 /** the implementation of that api */
 class Remarkable {
     #userToken;
-    #syncHost;
     /** the same cache that underlies the raw api, allowing us to modify it */
     #cache;
     raw;
     #lastHashGen;
-    constructor(userToken, syncHost, rawHost, cache) {
+    constructor(userToken, rawHost, cache) {
         this.#userToken = userToken;
-        this.#syncHost = syncHost;
         this.#cache = cache;
         this.raw = new RawRemarkable((method, url, { body, headers } = {}) => this.#authedFetch(url, { method, body, headers }), cache, rawHost);
     }
@@ -620,38 +594,51 @@ class Remarkable {
             return resp;
         }
     }
-    /** 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,
-            method,
-            headers: {
-                "content-type": contentType,
-                "rm-meta": fromByteArray(encMeta),
-                "rm-source": "WebLibrary",
-            },
-        });
-        const raw = await resp.text();
-        return JSON.parse(raw);
+    async #convertEntry({ hash, id }) {
+        const entries = await this.raw.getEntries(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}`);
+        }
+        else if (contentEnt === undefined) {
+            throw new Error(`couldn't find content for hash ${hash}`);
+        }
+        const [{ visibleName, lastModified, pinned, parent, lastOpened }, content] = await Promise.all([
+            this.raw.getMetadata(metaEnt.hash),
+            this.raw.getContent(contentEnt.hash),
+        ]);
+        if (content.fileType === undefined) {
+            return {
+                id,
+                hash,
+                visibleName,
+                lastModified,
+                pinned,
+                parent,
+                tags: content.tags,
+                type: "CollectionType",
+            };
+        }
+        else {
+            return {
+                id,
+                hash,
+                visibleName,
+                lastModified,
+                pinned,
+                parent,
+                tags: content.tags,
+                lastOpened: lastOpened ?? "",
+                fileType: content.fileType,
+                type: "DocumentType",
+            };
+        }
     }
     /** list all items */
-    async listItems() {
-        const res = await this.#fileRequest();
-        if (!entries.guardAssert(res))
-            throw Error("invalid entries");
-        return res;
+    async listItems(refresh = false) {
+        const ids = await this.listIds(refresh);
+        return await Promise.all(ids.map((id) => this.#convertEntry(id)));
     }
     async listIds(refresh = false) {
         const [hash] = await this.#getRootHash(refresh);
@@ -713,45 +700,46 @@ class Remarkable {
         }
         const id = uuid4();
         const now = new Date();
-        const enc = new TextEncoder();
+        const metadata = {
+            parent,
+            pinned,
+            lastModified: (+now).toFixed(),
+            createdTime: (+now).toFixed(),
+            type: "DocumentType",
+            visibleName,
+            lastOpened: "0",
+            lastOpenedPage: 0,
+        };
+        const 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(),
+        };
         // 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,
-            }),
+            this.raw.putContent(`${id}.content`, content),
+            this.raw.putMetadata(`${id}.metadata`, metadata),
             // eslint-disable-next-line spellcheck/spell-checker
-            this.raw.putFile(`${id}.pagedata`, enc.encode("\n")),
+            this.raw.putText(`${id}.pagedata`, "\n"),
             this.raw.putFile(`${id}.${fileType}`, buffer),
             this.#getRootHash(refresh),
         ]);
@@ -777,6 +765,10 @@ class Remarkable {
             uploadCollection,
             uploadRoot,
         ]);
+        // TODO we could return a full entry here, but we should probably decide
+        // what that should be, e.g. we could return more fields than the standard
+        // entry. Same for putFolder
+        // TODO we should also decide if the api should take hashes or ids...
         await this.#putRootHash(rootEntry.hash, generation);
         return { id, hash: collectionEntry.hash };
     }
@@ -786,96 +778,134 @@ class Remarkable {
     async putEpub(visibleName, buffer, opts = {}) {
         return await this.#putFile(visibleName, "epub", buffer, opts);
     }
-    /** upload a file */
-    async #uploadFile(parent, visibleName, buffer, contentType) {
-        if (!idReg.test(parent)) {
+    /** create a folder */
+    async createFolder(visibleName, { parent = "" } = {}, refresh = false) {
+        if (parent && !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 };
-    }
-    /** create a folder */
-    async createFolder(visibleName, { parent = "" } = {}) {
-        return await this.#uploadFile(parent, visibleName, new Uint8Array(0), "folder");
+        const id = uuid4();
+        const now = new Date();
+        const content = {
+            tags: [],
+        };
+        const metadata = {
+            lastModified: (+now).toFixed(),
+            createdTime: (+now).toFixed(),
+            parent,
+            pinned: false,
+            type: "CollectionType",
+            visibleName,
+        };
+        // upload folder contents
+        const [[contentEntry, uploadContent], [metadataEntry, uploadMetadata], [rootHash, generation],] = await Promise.all([
+            this.raw.putContent(`${id}.content`, content),
+            this.raw.putMetadata(`${id}.metadata`, metadata),
+            this.#getRootHash(refresh),
+        ]);
+        // now fetch root entries and upload this file entry
+        const [[collectionEntry, uploadCollection], rootEntries] = await Promise.all([
+            this.raw.putEntries(id, [contentEntry, metadataEntry]),
+            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,
+            uploadCollection,
+            uploadRoot,
+        ]);
+        // put root hash and return
+        await this.#putRootHash(rootEntry.hash, generation);
+        return { id, hash: collectionEntry.hash };
     }
     /** upload an epub */
-    async uploadEpub(visibleName, buffer, { parent = "" } = {}) {
-        return await this.#uploadFile(parent, visibleName, buffer, "application/epub+zip");
+    async uploadEpub(visibleName, buffer, opts = {}) {
+        return await this.putEpub(visibleName, buffer, opts);
     }
     /** upload a pdf */
-    async uploadPdf(visibleName, buffer, { parent = "" } = {}) {
-        return await this.#uploadFile(parent, visibleName, buffer, "application/pdf");
+    async uploadPdf(visibleName, buffer, opts = {}) {
+        return await this.putPdf(visibleName, buffer, opts);
     }
-    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;
+    async #editMetaRaw(id, hash, update) {
+        const entries = await this.raw.getEntries(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.hash);
+        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(() => { });
+        return [result, upload];
+    }
+    async #editMeta(hash, update, refresh = false) {
+        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] = await this.#editMetaRaw(hashEnt.id, hash, update);
+        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 };
     }
     /** move an entry */
-    async move(hash, parent) {
+    async move(hash, parent, refresh = false) {
         if (!idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
-        return await this.#modify(hash, { parent });
+        return await this.#editMeta(hash, { parent }, refresh);
     }
     /** delete an entry */
-    async delete(hash) {
-        return await this.move(hash, "trash");
+    async delete(hash, refresh = false) {
+        return await this.move(hash, "trash", refresh);
     }
     /** rename an entry */
-    async rename(hash, visibleName) {
-        return await this.#modify(hash, { file_name: visibleName });
-    }
-    /** 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",
-        });
-        this.#lastHashGen = undefined; // clear the hash gen since this will change it
-        if (!hashesEntry.guardAssert(res))
-            throw Error("invalid hashes entry");
-        return res;
+    async rename(hash, visibleName, refresh = false) {
+        return await this.#editMeta(hash, { visibleName }, refresh);
     }
     /** move many hashes */
-    async bulkMove(hashes, parent) {
+    async bulkMove(hashes, parent, refresh = false) {
         if (!idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
-        return await this.#bulkModify(hashes, { parent });
+        const [rootHash, generation] = await this.#getRootHash(refresh);
+        const entries = await this.raw.getEntries(rootHash);
+        const hashSet = new Set(hashes);
+        const toUpdate = [];
+        const newEntries = [];
+        for (const entry of entries) {
+            const part = hashSet.has(entry.hash) ? toUpdate : newEntries;
+            part.push(entry);
+        }
+        const resolved = await Promise.all(toUpdate.map(({ id, hash }) => this.#editMetaRaw(id, hash, { parent })));
+        const uploads = [];
+        const result = {};
+        for (const [i, [newEnt, upload]] of resolved.entries()) {
+            newEntries.push(newEnt);
+            uploads.push(upload);
+            result[toUpdate[i].hash] = newEnt.hash;
+        }
+        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", newEntries);
+        uploads.push(uploadRoot);
+        await Promise.all(uploads);
+        await this.#putRootHash(rootEntry.hash, generation);
+        return { hashes: result };
     }
     /** delete many hashes */
-    async bulkDelete(hashes) {
-        return await this.bulkMove(hashes, "trash");
+    async bulkDelete(hashes, refresh = false) {
+        return await this.bulkMove(hashes, "trash", refresh);
     }
-    // TODO ostensibly we could implement a bulk rename but idk why
     /** dump the raw cache */
     dumpCache() {
         return this.raw.dumpCache();
@@ -922,7 +952,7 @@ const cached = values(nullable(string()));
  *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export async function remarkable(deviceToken, { authHost = AUTH_HOST, syncHost = SYNC_HOST, rawHost = RAW_HOST, cache, maxCacheSize = Infinity, } = {}) {
+export async function remarkable(deviceToken, { authHost = AUTH_HOST, rawHost = RAW_HOST, cache, maxCacheSize = Infinity, } = {}) {
     const resp = await fetch(`${authHost}/token/json/2/user/new`, {
         method: "POST",
         headers: {
@@ -939,7 +969,7 @@ export async function remarkable(deviceToken, { authHost = AUTH_HOST, syncHost =
         const cache = maxCacheSize === Infinity
             ? new Map(entries)
             : new LruCache(maxCacheSize, entries);
-        return new Remarkable(userToken, syncHost, rawHost, cache);
+        return new Remarkable(userToken, 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.");