rmapi-js 11.1.1 → 11.2.0

package/dist/raw.d.ts

@@ -1,3 +1,24 @@
+import { type RmPageV5 } from "./rm5.js";
+import { type RmScene } from "./rm6.js";
+/**
+ * a parsed reMarkable `.rm` page
+ *
+ * A discriminated union on `version`: versions 3/5 parse to the flat, renderable
+ * {@link RmPageV5 | `RmPageV5`}; version 6 parses to the richer
+ * {@link RmScene | `RmScene`} CRDT scene (`version: 6`).
+ */
+export type RmPage = RmPageV5 | RmScene;
+/**
+ * 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 declare function parseRm(data: Uint8Array): RmPage;
 /** request types */
 export type RequestMethod = "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
 /** the supported upload mime types */
@@ -120,6 +141,14 @@ export interface CPagePage {
     verticalScroll?: CPageNumberValue;
     /** [unknown] */
     deleted?: CPageNumberValue;
+    /**
+     * a per-page last-modified epoch-milliseconds timestamp
+     *
+     * The misspelling is reMarkable's own: the firmware writes this key as
+     * `modifed`. Unlike the sibling fields it is a bare string, not a
+     * timestamped value.
+     */
+    modifed?: string;
 }
 /** [unknown] */
 export interface CPageUUID {
@@ -256,13 +285,10 @@ export interface CommonDocumentContent {
     /**
      * the scale for a customFit zoom
      *
-     * The linear magnification is proportional to customZoomScale: the visible
-     * page-height fraction is `sqrt(deviceAspect) / customZoomScale`, where
-     * `deviceAspect` is `screenWidth / screenHeight` (0.75 for 3:4 models, 0.5625
-     * for the Paper Pro Move). The rendered page height fills the screen at
-     * `customZoomScale = sqrt(deviceAspect)` (≈0.87 for 3:4 devices), not at 1.
-     * reMarkable generally allows 0.5 to 5, but values outside that bound are
-     * still supported.
+     * `customZoomScale = screenHeight / viewHeight` in device pixels, normalized to
+     * 1:1 native pixels: at 1 the view is screen-tall, showing `screenHeight /
+     * customZoomPageHeight` of the page. reMarkable generally allows 0.5 to 5, but
+     * values outside that bound are still supported.
      */
     customZoomScale?: number;
     /** the zoom mode; customFit applies the customZoom* fields, the rest auto-fit */
@@ -382,6 +408,8 @@ export interface Metadata {
     /** the visible name of the item, what it's called on the reMarkable */
     visibleName: string;
 }
+/** parse and validate the json text of a `.metadata` file */
+export declare function parseMetadata(text: string): Metadata;
 /**
  * access to the low-level reMarkable api
  *
@@ -506,6 +534,21 @@ export interface RawRemarkableApi {
      * @returns the metadata
      */
     getMetadata(fileName: string, hash: string): Promise<Metadata>;
+    /**
+     * get the parsed reMarkable lines (`.rm`) drawing of a page hash
+  
+     * @param fileName - typically `"<id>/<pageid>.rm"`
+     * @param hash - the hash to get the page for
+     * @returns the parsed page
+     */
+    getRm(fileName: string, hash: string): Promise<RmPage>;
+    /**
+     * 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.
+     */
+    putRm(fileName: string, page: RmPageV5): Promise<[RawEntry, Promise<void>]>;
     /**
      * update the current root hash
      *
@@ -536,17 +579,17 @@ export interface RawRemarkableApi {
      * NOTE: This won't update the state of the reMarkable until this entry is
      * incorporated into the root hash.
      *
-     * @param id - the id of the file to upload
+     * @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
      */
-    putFile(id: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
+    putFile(fileName: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
     /** the same as {@link putFile | `putFile`} but with caching for text */
-    putText(id: string, content: string): Promise<[RawEntry, Promise<void>]>;
+    putText(fileName: string, content: string): Promise<[RawEntry, Promise<void>]>;
     /** the same as {@link putText | `putText`} but with extra validation for Content */
-    putContent(id: string, content: Content): Promise<[RawEntry, Promise<void>]>;
+    putContent(fileName: string, content: Content): Promise<[RawEntry, Promise<void>]>;
     /** the same as {@link putText | `putText`} but with extra validation for Metadata */
-    putMetadata(id: string, metadata: Metadata): Promise<[RawEntry, Promise<void>]>;
+    putMetadata(fileName: string, metadata: Metadata): Promise<[RawEntry, Promise<void>]>;
     /**
      * put a set of entries to make an entry list file
      *
@@ -562,7 +605,10 @@ export interface RawRemarkableApi {
      * 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.
+     *   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
@@ -605,11 +651,13 @@ export declare class RawRemarkable implements RawRemarkableApi {
     getEntries(fileName: string, hash: string): Promise<Entries>;
     getContent(fileName: string, hash: string): Promise<Content>;
     getMetadata(fileName: string, hash: string): Promise<Metadata>;
+    getRm(fileName: string, hash: string): Promise<RmPage>;
+    putRm(fileName: string, page: RmPageV5): Promise<[RawEntry, Promise<void>]>;
     putRootHash(hash: string, generation: number, broadcast?: boolean): Promise<[string, number]>;
-    putFile(id: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
-    putText(id: string, text: string): Promise<[RawEntry, Promise<void>]>;
-    putContent(id: string, content: Content): Promise<[RawEntry, Promise<void>]>;
-    putMetadata(id: string, metadata: Metadata): Promise<[RawEntry, Promise<void>]>;
+    putFile(fileName: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
+    putText(fileName: string, text: string): Promise<[RawEntry, Promise<void>]>;
+    putContent(fileName: string, content: Content): Promise<[RawEntry, Promise<void>]>;
+    putMetadata(fileName: string, metadata: Metadata): Promise<[RawEntry, Promise<void>]>;
     putEntries(id: string, entries: readonly RawEntry[], schemaVersion: SchemaVersion): Promise<[RawEntry, Promise<void>]>;
     uploadFile(visibleName: string, bytes: Uint8Array, mime: UploadMimeType): Promise<SimpleEntry>;
     dumpCache(): string;

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(),
@@ -344,6 +381,18 @@ export class RawRemarkable {
         const loaded = JSON.parse(raw);
         return metadata.parse(loaded);
     }
+    async getRm(fileName, hash) {
+        const bytes = await this.getHash(fileName, hash);
+        return parseRm(bytes);
+    }
+    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));
+        }
+    }
     async putRootHash(hash, generation, broadcast = true) {
         if (!Number.isSafeInteger(generation)) {
             throw new Error(`generation ${generation} was not a safe integer`);
@@ -388,21 +437,21 @@ export class RawRemarkable {
             }
         }
     }
-    async putFile(id, bytes) {
+    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) {
+    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,20 +460,20 @@ export class RawRemarkable {
             }),
         ];
     }
-    async putContent(id, content) {
-        if (!id.endsWith(".content")) {
-            throw new Error(`id ${id} did not end with '.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'`);
+    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));
         }
     }
     async putEntries(id, entries, schemaVersion) {

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;

package/dist/rm5.js

@@ -0,0 +1,181 @@
+/**
+ * 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
+ */
+const BRUSHES = {
+    0: "brush",
+    12: "brush",
+    1: "pencil",
+    14: "pencil",
+    2: "ballpoint",
+    15: "ballpoint",
+    3: "marker",
+    16: "marker",
+    4: "fineliner",
+    17: "fineliner",
+    5: "highlighter",
+    18: "highlighter",
+    6: "eraser",
+    7: "mechanicalPencil",
+    13: "mechanicalPencil",
+    8: "eraseArea",
+    21: "calligraphy",
+    23: "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 function decodeBrush(code) {
+    return BRUSHES[code];
+}
+/**
+ * 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 const rmColors = {
+    0: "black",
+    1: "gray",
+    2: "white",
+};
+/** the length of the fixed `.lines` header, in bytes */
+export const HEADER_LENGTH = 43;
+/** the ascii prefix of the header, immediately followed by the version digit */
+export 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 function parseV5(data, version) {
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    let offset = HEADER_LENGTH;
+    const readInt = () => {
+        const value = view.getInt32(offset, true);
+        offset += 4;
+        return value;
+    };
+    const readFloat = () => {
+        const value = view.getFloat32(offset, true);
+        offset += 4;
+        return value;
+    };
+    const numLayers = readInt();
+    const layers = [];
+    for (let layer = 0; layer < numLayers; layer++) {
+        const numLines = readInt();
+        const lines = [];
+        for (let line = 0; line < numLines; line++) {
+            const brushType = readInt();
+            const color = readInt();
+            const padding = readInt();
+            const brushBaseSize = readFloat();
+            const unknown = version === 5 ? readInt() : undefined;
+            const numPoints = readInt();
+            const points = new Array(numPoints);
+            for (let point = 0; point < numPoints; point++) {
+                points[point] = {
+                    x: readFloat(),
+                    y: readFloat(),
+                    speed: readFloat(),
+                    direction: readFloat(),
+                    width: readFloat(),
+                    pressure: readFloat(),
+                };
+            }
+            const parsed = {
+                brushType,
+                color,
+                padding,
+                brushBaseSize,
+                points,
+            };
+            if (unknown !== undefined) {
+                parsed.unknown = unknown;
+            }
+            lines.push(parsed);
+        }
+        layers.push({ lines });
+    }
+    return { version, layers };
+}
+/**
+ * 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 function serializeRm(page) {
+    const { version } = page;
+    // runtime backstop for untyped (JS) callers passing a v6 page
+    if (version !== 3 && version !== 5) {
+        throw new Error(`rendering version ${version} .lines files is not supported (only 3 and 5)`);
+    }
+    const strokeHeaderSize = version === 5 ? 24 : 20;
+    let size = HEADER_LENGTH + 4;
+    for (const layer of page.layers) {
+        size += 4;
+        for (const line of layer.lines) {
+            size += strokeHeaderSize + line.points.length * 24;
+        }
+    }
+    const bytes = new Uint8Array(size);
+    const view = new DataView(bytes.buffer);
+    const header = `${VERSION_PREFIX}${version}`.padEnd(HEADER_LENGTH, " ");
+    for (let index = 0; index < HEADER_LENGTH; index++) {
+        bytes[index] = header.charCodeAt(index);
+    }
+    let offset = HEADER_LENGTH;
+    const writeInt = (value) => {
+        view.setInt32(offset, value, true);
+        offset += 4;
+    };
+    const writeFloat = (value) => {
+        view.setFloat32(offset, value, true);
+        offset += 4;
+    };
+    writeInt(page.layers.length);
+    for (const layer of page.layers) {
+        writeInt(layer.lines.length);
+        for (const line of layer.lines) {
+            writeInt(line.brushType);
+            writeInt(line.color);
+            writeInt(line.padding ?? 0);
+            writeFloat(line.brushBaseSize);
+            if (version === 5) {
+                writeInt(line.unknown ?? 0);
+            }
+            writeInt(line.points.length);
+            for (const point of line.points) {
+                writeFloat(point.x);
+                writeFloat(point.y);
+                writeFloat(point.speed);
+                writeFloat(point.direction);
+                writeFloat(point.width);
+                writeFloat(point.pressure);
+            }
+        }
+    }
+    return bytes;
+}