rmapi-js 11.1.2 → 12.0.0

package/dist/raw.js

@@ -1,8 +1,39 @@
 import CRC32C from "crc-32/crc32c";
 import { z } from "zod";
 import { ValidationError } from "./error.js";
+import { HEADER_LENGTH, parseV5, serializeRm, VERSION_PREFIX, } from "./rm5.js";
+import { parseRmScene } from "./rm6.js";
 import { concatArrays } from "./utils.js";
 const hashReg = /^[0-9a-f]{64}$/;
+/**
+ * parse the bytes of a reMarkable `.rm` page file
+ *
+ * Dispatches on the header version: versions 3/5 parse to a flat
+ * {@link RmPageV5 | `RmPageV5`}; version 6 parses to an
+ * {@link RmScene | `RmScene`}. Throws for an unknown version or malformed data.
+ *
+ * @param data - the raw `.rm` file bytes
+ * @returns the parsed page
+ */
+export function parseRm(data) {
+    if (data.length < HEADER_LENGTH) {
+        throw new Error("data is too short to be a reMarkable .lines file");
+    }
+    const header = new TextDecoder().decode(data.subarray(0, HEADER_LENGTH));
+    if (!header.startsWith(VERSION_PREFIX)) {
+        throw new Error(`unrecognized .lines header: ${JSON.stringify(header)}`);
+    }
+    const versionChar = header.charAt(VERSION_PREFIX.length);
+    if (versionChar === "6") {
+        return parseRmScene(data);
+    }
+    else if (versionChar === "3" || versionChar === "5") {
+        return parseV5(data, versionChar === "3" ? 3 : 5);
+    }
+    else {
+        throw new Error(`unsupported .lines version '${versionChar}'`);
+    }
+}
 const tag = z
     .object({
     name: z.string(),
@@ -51,6 +82,7 @@ const cPagePage = z
         .object({ timestamp: z.string(), value: z.number().int() })
         .passthrough()
         .optional(),
+    modifed: z.string().optional(),
 })
     .passthrough();
 const cPages = z
@@ -183,6 +215,11 @@ const metadata = z
     source: z.string().optional(),
 })
     .passthrough();
+/** parse and validate the json text of a `.metadata` file */
+export function parseMetadata(text) {
+    const loaded = JSON.parse(text);
+    return metadata.parse(loaded);
+}
 const updatedRootHash = z
     .object({
     hash: z.string(),
@@ -196,7 +233,7 @@ const rootHash = z
     schemaVersion: z.number().int().nonnegative(),
 })
     .passthrough();
-const nativeSimpleEntry = z
+const nativeItemRef = z
     .object({
     docID: z.string(),
     hash: z.string(),
@@ -230,6 +267,65 @@ function parseRawEntryLine(line) {
         throw new Error(`line '${line}' was not formatted correctly`);
     }
 }
+/**
+ * access to the low-level reMarkable api
+ *
+ * This class gives more granualar access to the reMarkable cloud, but is more
+ * dangerous.
+ *
+ * ## Overview
+ *
+ * reMarkable uses an immutable file system, where each file is referenced by
+ * the 32 byte sha256 hash of its contents. Each file also has an id used to
+ * keep track of updates, so to "update" a file, you upload a new file, and
+ * change the hash associated with it's id.
+ *
+ * Each "item" (a document or a collection) is actually a list of files.
+ * The whole reMarkable state is then a list of these lists. Finally, the hash
+ * of that list is called the rootHash. To update anything, you have to update
+ * the root hash to point to a new list of updated items.
+ *
+ * This can be dangerous, as corrupting the root hash can destroy all of your
+ * files. It is therefore highly recommended to save your current root hash
+ * ({@link getRootHash | `getRootHash`}) before using this api to attempt file
+ * writes, so you can recover a previous "snapshot" should anything go wrong.
+ *
+ * ## Items
+ *
+ * Each item is a collection of individual files. Using
+ * {@link getEntries | `getEntries`} on the root hash will give you a list
+ * entries that correspond to items. Using `getEntries` on any of those items
+ * will get you the files that make up that item.
+ *
+ * The documented files are:
+ * - `<docid>.pdf` - a raw pdf document
+ * - `<docid>.epub` - a raw epub document
+ * - `<docid>.content` - a json file roughly describing document properties (see {@link DocumentContent | `DocumentContent`})
+ * - `<docid>.metadata` - metadata about the document (see {@link Metadata | `Metadata`})
+ * - `<docid>.pagedata` - a text file where each line is the template of that page
+ * - `<docid>/<pageid>.rm` - [speculative] raw remarkable vectors, text, etc
+ * - `<docid>/<pageid>-metadata.json` - [speculative] metadata about the individual page
+ * - `<docid>.highlights/<pageid>.json` - [speculative] highlights on the page
+ *
+ * Some items will have both a `.pdf` and `.epub` file, likely due to preparing
+ * for export. Collections only have `.content` and `.metadata` files, with
+ * `.content` only containing tags.
+ *
+ * ## Caching
+ *
+ * Since everything is tied to the hash of it's contents, we can agressively
+ * cache results. We assume that text contents are "small" and so fully cache
+ * them, where as binary files we treat as large and only store that we know
+ * they exist to prevent future writes.
+ *
+ * By default, this only persists as long as the api instance is alive. However,
+ * for performance reasons, you should call {@link dumpCache | `dumpCache`} to
+ * persist the cache between sessions.
+ *
+ * @remarks
+ *
+ * Generally all hashes are 64 character hex strings, and all ids are uuid4.
+ */
 export class RawRemarkable {
     #authedFetch;
     #rawHost;
@@ -251,6 +347,14 @@ export class RawRemarkable {
         this.#uploadHost = uploadHost;
     }
     /** make an authorized request to remarkable */
+    /**
+     * gets the root hash and the current generation
+     *
+     * When calling `putRootHash`, you should pass the generation you got from
+     * this call. That way you tell reMarkable you're updating the previous state.
+     *
+     * @returns the root hash and the current generation
+     */
     async getRootHash() {
         const res = await this.#authedFetch("GET", `${this.#rawHost}/sync/v4/root`);
         const raw = await res.text();
@@ -275,7 +379,17 @@ export class RawRemarkable {
         const raw = await resp.arrayBuffer();
         return new Uint8Array(raw);
     }
-    async getHash(fileName, hash) {
+    /**
+     * get the raw binary data associated with a hash
+     *
+     * @param ref - a reference to the stored file. Its `id` is the logical file
+     *   name (`<id>.<ext>` for files, or `<id>.docSchema` / `"root.docSchema"`
+     *   for entry indexes), which reMarkable validates against the rm-filename
+     *   header. Sub-entries from {@link getEntries | `getEntries`} can be passed
+     *   directly.
+     * @returns the data
+     */
+    async getHash({ id: fileName, hash }) {
         const cached = this.#cache.get(hash);
         if (cached != null) {
             const enc = new TextEncoder();
@@ -291,7 +405,16 @@ export class RawRemarkable {
             return res;
         }
     }
-    async getText(fileName, hash) {
+    /**
+     * get raw text data associated with a hash
+     *
+     * We assume text data are small, and so cache the entire text. If you want to
+     * avoid this, use {@link getHash | `getHash`} combined with a TextDecoder.
+     *
+     * @param ref - a reference to the stored file (see {@link getHash})
+     * @returns the text
+     */
+    async getText({ id: fileName, hash }) {
         const cached = this.#cache.get(hash);
         if (cached != null) {
             return cached;
@@ -305,8 +428,18 @@ export class RawRemarkable {
             return res;
         }
     }
-    async getEntries(fileName, hash) {
-        const rawFile = await this.getText(fileName, hash);
+    /**
+     * get the entries associated with a list hash
+     *
+     * A list hash is the root hash, or any hash with the type 80000000. NOTE
+     * these are hashed differently than files.
+     *
+     * @param ref - a reference whose `id` is `"root.docSchema"` for the root, or
+     *   `"<id>.docSchema"` for a sub-document's entry index
+     * @returns the entries
+     */
+    async getEntries(ref) {
+        const rawFile = await this.getText(ref);
         const [version, ...rest] = rawFile.slice(0, -1).split("\n");
         if (version === "3") {
             return { entries: rest.map(parseRawEntryLine) };
@@ -334,16 +467,77 @@ export class RawRemarkable {
             throw new Error(`schema version ${version} not supported`);
         }
     }
-    async getContent(fileName, hash) {
-        const raw = await this.getText(fileName, hash);
+    /**
+     * get the parsed and validated `Content` of a content hash
+     *
+     * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
+     * validation
+     *
+     * @param ref - a reference to the stored file, typically `"<id>.content"`
+     * @returns the content
+     */
+    async getContent(ref) {
+        const raw = await this.getText(ref);
         const loaded = JSON.parse(raw);
         return content.parse(loaded);
     }
-    async getMetadata(fileName, hash) {
-        const raw = await this.getText(fileName, hash);
+    /**
+     * get the parsed and validated `Metadata` of a metadata hash
+     *
+     * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
+     * validation
+     *
+     * @param ref - a reference to the stored file, typically `"<id>.metadata"`
+     * @returns the metadata
+     */
+    async getMetadata(ref) {
+        const raw = await this.getText(ref);
         const loaded = JSON.parse(raw);
         return metadata.parse(loaded);
     }
+    /**
+     * get the parsed reMarkable lines (`.rm`) drawing of a page hash
+     *
+     * @param ref - a reference to the stored file, typically `"<id>/<pageid>.rm"`
+     * @returns the parsed page
+     */
+    async getRm(ref) {
+        const bytes = await this.getHash(ref);
+        return parseRm(bytes);
+    }
+    /**
+     * the same as {@link putFile | `putFile`} but rendering an `RmPage` to `.rm`
+     * bytes
+     *
+     * Only version 3 and 5 pages can be rendered; version 6 pages are read-only.
+     */
+    async putRm(fileName, page) {
+        if (!fileName.endsWith(".rm")) {
+            throw new Error(`fileName ${fileName} did not end with '.rm'`);
+        }
+        else {
+            return await this.putFile(fileName, serializeRm(page));
+        }
+    }
+    /**
+     * update the current root hash
+     *
+     * This will fail if generation doesn't match the current server generation.
+     * This ensures that you are updating what you expect. IF you get a
+     * {@link GenerationError | `GenerationError`}, that indicates that the server
+     * was updated after you last got the generation. You should call
+     * {@link getRootHash | `getRootHash`} and then recompute the changes you want
+     * from the new root hash. If you ignore the update hash value and just call
+     * `putRootHash` again, you will overwrite the changes made by the other
+     * update.
+     *
+     * @param hash - the new root hash
+     * @param generation - the generation of the current root hash
+     * @param broadcast - [unknown] an option in the request
+     *
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns the new root hash and the new generation
+     */
     async putRootHash(hash, generation, broadcast = true) {
         if (!Number.isSafeInteger(generation)) {
             throw new Error(`generation ${generation} was not a safe integer`);
@@ -388,21 +582,36 @@ export class RawRemarkable {
             }
         }
     }
-    async putFile(id, bytes) {
+    /**
+     * put a raw onto the server
+     *
+     * This returns the new expeced entry of the file you uploaded, and a promise
+     * to finish the upload successful. By splitting these two operations you can
+     * start using the uploaded entry while file finishes uploading.
+     *
+     * NOTE: This won't update the state of the reMarkable until this entry is
+     * incorporated into the root hash.
+     *
+     * @param fileName - the file name to upload (e.g. `<id>.pdf`)
+     * @param bytes - the bytes to upload
+     * @returns the new entry and a promise to finish the upload
+     */
+    async putFile(fileName, bytes) {
         const hash = await digest(bytes);
         const res = {
-            id,
+            id: fileName,
             hash,
             type: 0,
             subfiles: 0,
             size: bytes.length,
         };
-        return [res, this.#putFile(id, hash, bytes)];
+        return [res, this.#putFile(fileName, hash, bytes)];
     }
-    async putText(id, text) {
+    /** the same as {@link putFile | `putFile`} but with caching for text */
+    async putText(fileName, text) {
         const enc = new TextEncoder();
         const bytes = enc.encode(text);
-        const [ent, upload] = await this.putFile(id, bytes);
+        const [ent, upload] = await this.putFile(fileName, bytes);
         return [
             ent,
             upload.then(() => {
@@ -411,22 +620,47 @@ export class RawRemarkable {
             }),
         ];
     }
-    async putContent(id, content) {
-        if (!id.endsWith(".content")) {
-            throw new Error(`id ${id} did not end with '.content'`);
+    /** the same as {@link putText | `putText`} but with extra validation for Content */
+    async putContent(fileName, content) {
+        if (!fileName.endsWith(".content")) {
+            throw new Error(`fileName ${fileName} did not end with '.content'`);
         }
         else {
-            return await this.putText(id, JSON.stringify(content));
+            return await this.putText(fileName, JSON.stringify(content));
         }
     }
-    async putMetadata(id, metadata) {
-        if (!id.endsWith(".metadata")) {
-            throw new Error(`id ${id} did not end with '.metadata'`);
+    /** the same as {@link putText | `putText`} but with extra validation for Metadata */
+    async putMetadata(fileName, metadata) {
+        if (!fileName.endsWith(".metadata")) {
+            throw new Error(`fileName ${fileName} did not end with '.metadata'`);
         }
         else {
-            return await this.putText(id, JSON.stringify(metadata));
+            return await this.putText(fileName, JSON.stringify(metadata));
         }
     }
+    /**
+     * put a set of entries to make an entry list file
+     *
+     * To fully upload an item:
+     * 1. upload all the constituent files and metadata
+     * 2. call this with all of the entries
+     * 3. append this entry to the root entry and call this again to update this root list
+     * 4. put the new root hash
+     *
+     * NOTE: reMarkable currently rejects newly written schema 3 root indexes
+     * with a 400 "Software must be updated" error, even for accounts that still
+     * report schema 3, so the root list should always be written as schema 4. A
+     * warning is logged if a schema 3 root index is written.
+     *
+     * @param id - the id of the list to upload - this should be the item id if
+     *   uploading an item list, or "root" if uploading a new root list. Note the
+     *   asymmetry with {@link getEntries | `getEntries`}: `getEntries` takes the
+     *   full `"<id>.docSchema"` file name, whereas `putEntries` takes the bare id
+     *   and appends `.docSchema` (and special-cases `"root"`) itself.
+     * @param entries - the entries to upload
+     *
+     * @returns the new list entry and a promise to finish the upload
+     */
     async putEntries(id, entries, schemaVersion) {
         if (id === "root" && schemaVersion === 3) {
             console.warn('writing a schema 3 root index, which reMarkable rejects with a 400 "Software must be updated" error; write the root index with schema version 4 instead');
@@ -471,6 +705,19 @@ export class RawRemarkable {
         };
         return [res, this.#putFile(`${id}.docSchema`, hash, entryBuff)];
     }
+    /**
+     * upload a file to the reMarkable cloud using the simple api
+     *
+     * This api is the same as used by the native reMarkable extension and works
+     * even if the backend schema version is version 4. Setting mime to "folder"
+     * allows folder creation.
+     *
+     * @param visibleName - the name of the file as it should appear on the reMarkable
+     * @param bytes - the bytes of the file to upload
+     * @param mime - the mime type of the file to upload
+  
+     * @returns a simple entry with the id and hash of the uploaded file
+     */
     async uploadFile(visibleName, bytes, mime) {
         const enc = new TextEncoder();
         const meta = enc
@@ -485,12 +732,18 @@ export class RawRemarkable {
             },
         });
         const loaded = (await resp.json());
-        const { docID, hash } = nativeSimpleEntry.parse(loaded);
+        const { docID, hash } = nativeItemRef.parse(loaded);
         return { id: docID, hash };
     }
+    /**
+     * dump the current cache to a string to preserve between session
+     *
+     * @returns a serialized version of the cache to pass to a new api instance
+     */
     dumpCache() {
         return JSON.stringify(Object.fromEntries(this.#cache));
     }
+    /** completely clear the cache */
     clearCache() {
         this.#cache.clear();
     }

package/dist/rm5.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Parse and render the flat (version 3 and 5) reMarkable `.rm` page format.
+ *
+ * A `.rm` file is the vector drawing for a single notebook page. The version 3
+ * and 5 formats are a flat, little-endian struct of layers, each holding strokes
+ * ("lines"), each holding sampled points (they differ only by one extra
+ * per-stroke field in version 5). {@link parseV5 | `parseV5`} reads them into an
+ * {@link RmPageV5 | `RmPageV5`} and {@link serializeRm | `serializeRm`} renders
+ * it back to byte-exact bytes.
+ *
+ * The newer version 6 "scene tree" format lives in `./rm6.js`; the version
+ * dispatch that picks between them (`parseRm`) lives in `./raw.js`.
+ *
+ * @packageDocumentation
+ */
+/** the flat reMarkable `.lines` file versions read into an {@link RmPageV5} */
+export type RmVersion = 3 | 5;
+/** a single sampled point along a stroke */
+export interface RmPoint {
+    /** the horizontal position in device pixels (see the page type for the origin) */
+    x: number;
+    /** the vertical position in device pixels (see the page type for the origin) */
+    y: number;
+    /** the pen speed at this point */
+    speed: number;
+    /** the pen tilt/heading in radians */
+    direction: number;
+    /** the stroke width at this point */
+    width: number;
+    /** the pen pressure, from 0 to 1 */
+    pressure: number;
+}
+/**
+ * a single stroke (called a "line") within a layer
+ *
+ * `brushType` and `color` are kept as raw integers because both are overloaded
+ * across firmware versions (there are two pen-code families, and the color
+ * field is reinterpreted as a palette index when colored annotations are
+ * enabled), so the right meaning can only be resolved with the source firmware
+ * in mind.
+ */
+export interface RmLine {
+    /** the raw brush/pen type code */
+    brushType: number;
+    /** the raw color code */
+    color: number;
+    /** a per-stroke padding field, typically 0 */
+    padding?: number;
+    /** the base brush size */
+    brushBaseSize: number;
+    /** [unknown] a per-stroke field only present in version 5 */
+    unknown?: number;
+    /** the sampled points making up the stroke, in order */
+    points: RmPoint[];
+}
+/** a drawing layer, an ordered set of strokes */
+export interface RmLayer {
+    /** the strokes on this layer, in order */
+    lines: RmLine[];
+}
+/**
+ * a parsed version 3 or 5 page
+ *
+ * Coordinates use a top-left origin: `x` in `[0, width]`, `y` in `[0, height]`,
+ * in device pixels. Only these pages can be re-rendered (via `raw.putRm`).
+ */
+export interface RmPageV5 {
+    /** the file format version */
+    version: 3 | 5;
+    /** the drawing layers, back to front */
+    layers: RmLayer[];
+}
+/** a decoded pen/tool for a stroke */
+export type RmBrush = "brush" | "pencil" | "ballpoint" | "marker" | "fineliner" | "highlighter" | "eraser" | "mechanicalPencil" | "eraseArea" | "calligraphy" | "shader";
+/**
+ * decode a raw {@link RmLine.brushType | `brushType`} code to a pen name
+ *
+ * Best-effort and advisory: the reMarkable pen codes come in two firmware
+ * families and new ones appear over time, so an unrecognized code returns
+ * `undefined`. The raw `brushType` int stays authoritative.
+ */
+export declare function decodeBrush(code: number): RmBrush | undefined;
+/**
+ * the default (monochrome) reMarkable palette, by raw {@link RmLine.color | `color`}
+ *
+ * Advisory only: when "colored annotations" are enabled or on version 6, the
+ * `color` field is reinterpreted, so resolve against the source firmware.
+ */
+export declare const rmColors: Readonly<Record<number, string>>;
+/** the length of the fixed `.lines` header, in bytes */
+export declare const HEADER_LENGTH = 43;
+/** the ascii prefix of the header, immediately followed by the version digit */
+export declare const VERSION_PREFIX = "reMarkable .lines file, version=";
+/**
+ * parse a version 3 or 5 (flat struct) `.rm` page
+ *
+ * Named for version 5, the common case, but the two formats differ only by the
+ * extra {@link RmLine.unknown | `unknown`} field version 5 adds per stroke.
+ */
+export declare function parseV5(data: Uint8Array, version: 3 | 5): RmPageV5;
+/**
+ * render a page back into reMarkable `.rm` file bytes
+ *
+ * The inverse of {@link parseV5 | `parseV5`}: `serializeRm(parseV5(bytes, v))`
+ * reproduces the original bytes for version 3 and 5 files. A missing `padding`
+ * or (version 5) `unknown` field is written as `0`.
+ *
+ * @param page - the page to render
+ * @returns the `.rm` file bytes
+ */
+export declare function serializeRm(page: RmPageV5): Uint8Array;