rmapi-js 1.1.0 → 2.1.0

package/dist/index.js

@@ -1,12 +1,17 @@
 /**
  * Create and interact with reMarkable cloud.
  *
+ * 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`}.
+ *
  * @example
  * A simple fetch
  * ```ts
  * import { register, remarkable } from "rmapi-js";
  *
- * const code = "..."  // eight letter code from https://my.remarkable.com/device/desktop/connect
+ * const code = "..."  // eight letter code from https://my.remarkable.com/device/browser/connect
  * const token = await register(code)
  * // persist token
  * const api = await remarkable(token);
@@ -35,19 +40,22 @@
  * const rootEntries = await api.getEntries(root);
  * rootEntries.push(entry);
  * const { hash } = await api.putEntries("", rootEntries);
- * await api.putRootHash(hash, gen);
+ * const nextGen = await api.putRootHash(hash, gen);
+ * await api.syncComplete(nextGen);
  * ```
  *
  * @packageDocumentation
  */
+import { fromByteArray } from "base64-js";
 import { v4 as uuid4 } from "uuid";
 import { concatBuffers, fromHex, toHex } from "./utils";
 import { validate } from "./validate";
 const SCHEMA_VERSION = "3";
-const AUTH_URL = "https://webapp-production-dot-remarkable-production.appspot.com";
-const BLOB_URL = "https://rm-blob-storage-prod.appspot.com";
+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 */
 export const builtinTools = [
     "Ballpoint",
@@ -117,6 +125,12 @@ export const builtinLineHeights = {
     /** double */
     xl: 200,
 };
+const uploadEntrySchema = {
+    properties: {
+        docID: { type: "string" },
+        hash: { type: "string" },
+    },
+};
 const urlResponseSchema = {
     properties: {
         relative_path: { type: "string" },
@@ -124,19 +138,22 @@ const urlResponseSchema = {
         expires: { type: "timestamp" },
         method: { enum: ["POST", "GET", "PUT", "DELETE"] },
     },
+    optionalProperties: {
+        maxuploadsize_bytes: { type: "float64" },
+    },
 };
 const commonProperties = {
     visibleName: { type: "string" },
-    parent: { type: "string" },
     lastModified: { type: "string" },
-    version: { type: "int32" },
-    synced: { type: "boolean" },
 };
 const commonOptionalProperties = {
+    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",
@@ -155,6 +172,34 @@ const metadataSchema = {
         },
     },
 };
+const baseMetadataProperties = {
+    id: { type: "string" },
+    hash: { type: "string" },
+};
+const metadataEntrySchema = {
+    discriminator: "type",
+    mapping: {
+        CollectionType: {
+            properties: {
+                ...commonProperties,
+                ...baseMetadataProperties,
+            },
+            optionalProperties: commonOptionalProperties,
+        },
+        DocumentType: {
+            properties: {
+                ...commonProperties,
+                ...baseMetadataProperties,
+                fileType: { enum: ["notebook", "epub", "pdf", ""] },
+            },
+            optionalProperties: {
+                ...commonOptionalProperties,
+                lastOpened: { type: "string" },
+                lastOpenedPage: { type: "int32" },
+            },
+        },
+    },
+};
 /** an error that results from a failed request */
 export class ResponseError extends Error {
     /** the response status number */
@@ -181,18 +226,18 @@ export class GenerationError extends Error {
 /**
  * register a device and get the token needed to access the api
  *
- * Have users go to `https://my.remarkable.com/device/desktop/connect` and pass
+ * Have users go to `https://my.remarkable.com/device/browser/connect` and pass
  * the resulting code into this function to get a device token. Persist that
  * token to use the api.
  *
- * @param code - the eight letter code a user got from `https://my.remarkable.com/device/desktop/connect`.
+ * @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 = "desktop-linux", uuid = uuid4(), authUrl = AUTH_URL, fetch = globalThis.fetch, } = {}) {
+export async function register(code, { deviceDesc = "browser-chrome", uuid = uuid4(), authHost = AUTH_HOST, fetch = globalThis.fetch, } = {}) {
     if (code.length !== 8) {
         throw new Error(`code should be length 8, but was ${code.length}`);
     }
-    const resp = await fetch(`${authUrl}/token/json/2/device/new`, {
+    const resp = await fetch(`${authHost}/token/json/2/device/new`, {
         method: "POST",
         headers: {
             Authorization: "Bearer",
@@ -253,37 +298,45 @@ export function parseEntry(line) {
 }
 /** the implementation of that api */
 class Remarkable {
-    userToken;
-    fetch;
-    cache;
-    subtle;
-    blobUrl;
-    constructor(userToken, fetch, cache, subtle, blobUrl) {
-        this.userToken = userToken;
-        this.fetch = fetch;
-        this.cache = cache;
-        this.subtle = subtle;
-        this.blobUrl = blobUrl;
+    #userToken;
+    #fetch;
+    #cache;
+    #subtle;
+    #syncHost;
+    constructor(userToken, fetch, cache, subtle, syncHost) {
+        this.#userToken = userToken;
+        this.#fetch = fetch;
+        this.#cache = cache;
+        this.#subtle = subtle;
+        this.#syncHost = syncHost;
     }
     /** make an authorized request to remarkable */
-    async authedFetch(url, body, method = "POST") {
-        const resp = await this.fetch(url, {
+    async #authedFetch(url, { body, method = "POST", headers = {}, }) {
+        const resp = await this.#fetch(url, {
             method,
             headers: {
-                Authorization: `Bearer ${this.userToken}`,
+                Authorization: `Bearer ${this.#userToken}`,
+                ...headers,
             },
-            body: body && JSON.stringify(body),
+            body,
         });
         if (!resp.ok) {
-            throw new ResponseError(resp.status, resp.statusText, "failed reMarkable request");
+            const msg = await resp.text();
+            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 }, body, headers) {
-        const resp = await this.fetch(url, {
+    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,
             body,
             headers,
@@ -297,14 +350,13 @@ class Remarkable {
         }
     }
     /** get the details for how to make a signed request to remarkable cloud */
-    async getUrl(relativePath, gen) {
+    async #getUrl(relativePath, gen, rootHash) {
         const key = gen === undefined ? "downloads" : "uploads";
-        const generation = gen === null || gen === undefined ? undefined : `${gen}`;
-        const resp = await this.authedFetch(`${this.blobUrl}/api/v1/signed-urls/${key}`, {
-            http_method: generation === undefined ? "GET" : "PUT",
-            relative_path: relativePath,
-            generation,
-        });
+        // NOTE this is done manually to serialize the bigints appropriately
+        const body = rootHash
+            ? `{ "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);
@@ -314,8 +366,8 @@ class Remarkable {
      * get the root hash and the current generation
      */
     async getRootHash() {
-        const signed = await this.getUrl("root");
-        const resp = await this.signedFetch(signed);
+        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");
@@ -326,10 +378,10 @@ class Remarkable {
      * write the root hash, incrementing from the current generation
      */
     async putRootHash(hash, generation) {
-        const signed = await this.getUrl("root", generation);
+        const signed = await this.#getUrl("root", generation, hash);
         let resp;
         try {
-            resp = await this.signedFetch(signed, hash, {
+            resp = await this.#signedFetch(signed, hash, {
                 [GENERATION_RACE_HEADER]: `${generation}`,
             });
         }
@@ -351,23 +403,23 @@ class Remarkable {
      * get text content associated with hash
      */
     async getBuffer(hash) {
-        const signed = await this.getUrl(hash);
-        const resp = await this.signedFetch(signed);
+        const signed = await this.#getUrl(hash);
+        const resp = await this.#signedFetch(signed);
         return await resp.arrayBuffer();
     }
     /**
      * get text content associated with hash
      */
     async getText(hash) {
-        const cached = this.cache && (await this.cache.get(hash));
+        const cached = await this.#cache?.get(hash);
         if (cached) {
             return cached;
         }
         else {
-            const signed = await this.getUrl(hash);
-            const resp = await this.signedFetch(signed);
+            const signed = await this.#getUrl(hash);
+            const resp = await this.#signedFetch(signed);
             const raw = await resp.text();
-            this.cache && (await this.cache.set(hash, raw));
+            await this.#cache?.set(hash, raw);
             return raw;
         }
     }
@@ -393,9 +445,9 @@ class Remarkable {
         return lines.map(parseEntry);
     }
     /** upload data to hash */
-    async putHash(hash, body) {
-        const signed = await this.getUrl(hash, null);
-        await this.signedFetch(signed, body);
+    async #putHash(hash, body) {
+        const signed = await this.#getUrl(hash, null);
+        await this.#signedFetch(signed, body);
     }
     /** put a reference to a set of entries into the cloud */
     async putEntries(documentId, entries) {
@@ -403,13 +455,13 @@ class Remarkable {
         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 digest = await this.#subtle.digest("SHA-256", hashes);
         const hash = toHex(digest);
         const entryContents = entries.map(formatEntry).join("");
         const contents = `${SCHEMA_VERSION}\n${entryContents}`;
         const buffer = enc.encode(contents);
-        await this.putHash(hash, buffer);
-        this.cache && (await this.cache.set(hash, contents));
+        await this.#putHash(hash, buffer);
+        await this.#cache?.set(hash, contents);
         return {
             hash,
             type: "80000000",
@@ -420,9 +472,9 @@ class Remarkable {
     }
     /** put a raw buffer in the cloud */
     async putBuffer(documentId, buffer) {
-        const digest = await this.subtle.digest("SHA-256", buffer);
+        const digest = await this.#subtle.digest("SHA-256", buffer);
         const hash = toHex(digest);
-        await this.putHash(hash, buffer);
+        await this.#putHash(hash, buffer);
         return {
             hash,
             type: "0",
@@ -435,16 +487,43 @@ class Remarkable {
     async putText(documentId, contents) {
         const enc = new TextEncoder();
         const entry = await this.putBuffer(documentId, enc.encode(contents));
-        this.cache && (await this.cache.set(entry.hash, contents));
+        await this.#cache?.set(entry.hash, contents);
         return entry;
     }
-    /** upload an epub */
-    async putEpub(visibleName, buffer, { parent = "", margins = 125, orientation, textAlignment, textScale = 1, lineHeight = -1, fontName = "", cover = "visited", lastTool, } = {}) {
+    /** put metadata into the cloud */
+    async putMetadata(documentId, metadata) {
+        return await this.putText(`${documentId}.metadata`, JSON.stringify(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}.epub`, buffer));
+        entryPromises.push(this.putBuffer(`${documentId}.${fileType}`, buffer));
         // upload metadata
         const metadata = {
             type: "DocumentType",
@@ -454,7 +533,16 @@ class Remarkable {
             synced: true,
             lastModified,
         };
-        entryPromises.push(this.putText(`${documentId}.metadata`, JSON.stringify(metadata)));
+        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);
+    }
+    /** 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,
@@ -478,12 +566,78 @@ class Remarkable {
             textAlignment,
             fontName,
         };
-        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);
+        return await this.#putContent(visibleName, buffer, "epub", parent, content);
+    }
+    /** 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);
+    }
+    /** 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,
+        });
+    }
+    /** get entries and metadata for all files */
+    async getEntriesMetadata() {
+        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);
+        return res;
+    }
+    /** upload a file */
+    async #uploadFile(visibleName, buffer, contentType) {
+        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",
+            },
+        });
+        const raw = await resp.text();
+        const res = JSON.parse(raw);
+        validate(uploadEntrySchema, res);
+        return res;
+    }
+    /** upload an epub */
+    async uploadEpub(visibleName, buffer) {
+        return await this.#uploadFile(visibleName, buffer, "application/epub+zip");
+    }
+    /** upload a pdf */
+    async uploadPdf(visibleName, buffer) {
+        // TODO why doesn't this work
+        return await this.#uploadFile(visibleName, buffer, "application/pdf");
     }
 }
 /**
@@ -492,11 +646,12 @@ class Remarkable {
  * This gets a temporary authentication token with the device token. If
  * requests start failing, simply recreate the api instance.
  *
- * @param deviceToken - the device token proving this api instance is registered. Create one with {@link register}.
+ * @param deviceToken - the device token proving this api instance is
+ *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export async function remarkable(deviceToken, { fetch = globalThis.fetch, cache, subtle = globalThis.crypto?.subtle, authUrl = AUTH_URL, blobUrl = BLOB_URL, } = {}) {
-    const resp = await fetch(`${authUrl}/token/json/2/user/new`, {
+export async function remarkable(deviceToken, { fetch = globalThis.fetch, cache, subtle = globalThis.crypto?.subtle, authHost = AUTH_HOST, syncHost = SYNC_HOST, } = {}) {
+    const resp = await fetch(`${authHost}/token/json/2/user/new`, {
         method: "POST",
         headers: {
             Authorization: `Bearer ${deviceToken}`,
@@ -506,5 +661,5 @@ export async function remarkable(deviceToken, { fetch = globalThis.fetch, cache,
         throw new Error(`couldn't fetch auth token: ${resp.statusText}`);
     }
     const userToken = await resp.text();
-    return new Remarkable(userToken, fetch, cache, subtle, blobUrl);
+    return new Remarkable(userToken, fetch, cache, subtle, syncHost);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rmapi-js",
-  "version": "1.1.0",
+  "version": "2.1.0",
   "description": "JavaScript implementation of the reMarkable 1.5 api",
   "repository": "git@github.com:erikbrinkman/rmapi-js.git",
   "author": "Erik Brinkman <erik.brinkman@gmail.com>",
@@ -8,54 +8,55 @@
   "keywords": [
     "remarkable"
   ],
-  "types": "dist/index.d.ts",
+  "types": "./dist/index.d.ts",
   "module": "bundle/rmapi-js.esm.min.js",
   "main": "bundle/rmapi-js.cjs.min.js",
   "unpkg": "bundle/rmapi-js.iife.min.js",
   "files": [
-    "/bundle/*.js",
-    "/dist/**/*.js",
-    "/dist/**/*.d.ts"
+    "./bundle/*.js",
+    "./dist/**/*.js",
+    "./dist/**/*.d.ts"
   ],
-  "packageManager": "yarn@3.2.4",
+  "packageManager": "yarn@3.3.1",
   "scripts": {
     "doc": "typedoc",
-    "fmt": "prettier --cache --write 'src/*.ts' '*.json' 'bundle.mjs'",
-    "lint": "tsc && eslint --cache 'src/*.ts' 'bundle.mjs' && typedoc --emit none",
+    "fmt": "prettier --cache --write 'src/*.ts' '*.json' bundle.mjs",
+    "lint": "tsc && eslint --cache 'src/*.ts' bundle.mjs && typedoc --emit none",
     "test": "jest --coverage",
     "build": "tsc -p tsconfig.build.json && yarn node bundle.mjs",
     "prepack": "yarn lint && yarn test && yarn build"
   },
   "dependencies": {
-    "ajv": "^8.11.0",
+    "ajv": "^8.11.2",
+    "base64-js": "^1.5.1",
+    "jtd": "^0.1.1",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.19.3",
-    "@babel/preset-env": "^7.19.3",
+    "@babel/core": "^7.20.7",
+    "@babel/preset-env": "^7.20.2",
     "@babel/preset-typescript": "^7.18.6",
-    "@types/babel__core": "^7.1.19",
+    "@types/babel__core": "^7.1.20",
     "@types/babel__preset-env": "^7.9.2",
-    "@types/jest": "^29.1.2",
-    "@types/node": "^18.8.3",
-    "@types/uuid": "^8.3.4",
-    "@typescript-eslint/eslint-plugin": "^5.39.0",
-    "@typescript-eslint/parser": "^5.39.0",
+    "@types/jest": "^29.2.4",
+    "@types/node": "^18.11.18",
+    "@types/uuid": "^9.0.0",
+    "@typescript-eslint/eslint-plugin": "^5.47.1",
+    "@typescript-eslint/parser": "^5.47.1",
     "@yarnpkg/esbuild-plugin-pnp": "^3.0.0-rc.15",
-    "babel-jest": "^29.1.2",
-    "chalk": "^5.1.0",
-    "esbuild": "^0.15.10",
-    "eslint": "^8.24.0",
+    "babel-jest": "^29.3.1",
+    "chalk": "^5.2.0",
+    "esbuild": "^0.16.10",
+    "eslint": "^8.30.0",
     "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-jest": "^27.1.1",
-    "eslint-plugin-spellcheck": "^0.0.19",
+    "eslint-plugin-jest": "^27.1.7",
+    "eslint-plugin-spellcheck": "^0.0.20",
     "eslint-plugin-tsdoc": "^0.2.17",
-    "jest": "^29.1.2",
-    "jtd": "^0.1.1",
-    "prettier": "^2.7.1",
-    "prettier-plugin-organize-imports": "^3.1.1",
-    "typedoc": "^0.23.15",
-    "typescript": "^4.8.4"
+    "jest": "^29.3.1",
+    "prettier": "^2.8.1",
+    "prettier-plugin-organize-imports": "^3.2.1",
+    "typedoc": "^0.23.23",
+    "typescript": "^4.9.4"
   },
   "prettier": {
     "plugins": [
@@ -94,6 +95,7 @@
       "node": true
     },
     "rules": {
+      "@typescript-eslint/no-inferrable-types": "off",
       "tsdoc/syntax": "error",
       "no-warning-comments": [
         "error",
@@ -121,6 +123,7 @@
             "Paintbrushv",
             "Pencilv",
             "authed",
+            "bigints",
             "ebooks",
             "epub",
             "fineliner",
@@ -128,6 +131,7 @@
             "iife",
             "incrementing",
             "linux",
+            "macos",
             "rmapi",
             "subfiles",
             "urls",