rmapi-js 10.2.0 → 11.1.0

package/dist/devices.d.ts

@@ -0,0 +1,22 @@
+/** a reMarkable device display */
+export interface DeviceScreen {
+    /** the marketing name */
+    name: string;
+    /** native portrait width in pixels */
+    width: number;
+    /** native portrait height in pixels */
+    height: number;
+    /** display density in dots per inch */
+    dpi: number;
+}
+/** the model number of a known reMarkable device */
+export type DeviceModel = "RM100" | "RM110" | "RM02A" | "RM03A" | "RM102";
+/**
+ * display specs for known reMarkable devices, keyed by model number
+ *
+ * These feed the `customFit` zoom math: `customZoomPageWidth`/`customZoomPageHeight`
+ * are the source page in device pixels (`pagePt * dpi / 72`), and `width`/`height`
+ * give the screen aspect. Every model is 3:4 (0.75) except the Paper Pro Move,
+ * which is 9:16.
+ */
+export declare const deviceScreens: Record<DeviceModel, DeviceScreen>;

package/dist/devices.js

@@ -0,0 +1,20 @@
+/**
+ * display specs for known reMarkable devices, keyed by model number
+ *
+ * These feed the `customFit` zoom math: `customZoomPageWidth`/`customZoomPageHeight`
+ * are the source page in device pixels (`pagePt * dpi / 72`), and `width`/`height`
+ * give the screen aspect. Every model is 3:4 (0.75) except the Paper Pro Move,
+ * which is 9:16.
+ */
+export const deviceScreens = {
+    RM100: { name: "reMarkable 1", width: 1404, height: 1872, dpi: 226 },
+    RM110: { name: "reMarkable 2", width: 1404, height: 1872, dpi: 226 },
+    RM02A: { name: "reMarkable Paper Pro", width: 1620, height: 2160, dpi: 229 },
+    RM03A: {
+        name: "reMarkable Paper Pro Move",
+        width: 954,
+        height: 1696,
+        dpi: 264,
+    },
+    RM102: { name: "reMarkable Paper Pure", width: 1404, height: 1872, dpi: 226 },
+};

package/dist/error.d.ts

@@ -0,0 +1,14 @@
+/** an error that results from a failed request */
+export declare class ValidationError extends Error {
+    /** the response status number */
+    readonly field: string;
+    /** the response status text */
+    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);
+}

package/dist/error.js

@@ -0,0 +1,21 @@
+/** an error that results from a failed request */
+export class ValidationError extends Error {
+    /** the response status number */
+    field;
+    /** the response status text */
+    regex;
+    constructor(field, regex, message) {
+        super(message);
+        this.field = field;
+        this.regex = regex;
+    }
+}
+/** an error that results while supplying a hash not found in the entries of the root hash */
+export class HashNotFoundError extends Error {
+    /** the hash that couldn't be found */
+    hash;
+    constructor(hash) {
+        super(`'${hash}' not found in the root hash`);
+        this.hash = hash;
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { type BackgroundFilter, type CollectionContent, type Content, type DocumentContent, type Metadata, type Orientation, type RawRemarkableApi, type SimpleEntry, type Tag, type TemplateContent, type TextAlignment, type ZoomMode } from "./raw.js";
+export { type DeviceModel, type DeviceScreen, deviceScreens, } from "./devices.js";
 export { HashNotFoundError, ValidationError } from "./error.js";
 export type { BackgroundFilter, CollectionContent, Content, CPageNumberValue, CPagePage, CPageStringValue, CPages, CPageUUID, DocumentContent, DocumentMetadata, Entries, FileType, KeyboardMetadata, LegacyCollectionContent, LegacyDocumentContent, Metadata, Orientation, PageTag, RawEntry, RawRemarkableApi, SchemaVersion, SimpleEntry, Tag, TemplateContent, TextAlignment, UploadMimeType, ZoomMode, } from "./raw.js";
 /** common properties shared by collections and documents */
@@ -162,6 +163,18 @@ export interface PutOptions {
     zoomMode?: ZoomMode;
     /** the contrast filter setting */
     viewBackgroundFilter?: BackgroundFilter;
+    /** the custom zoom scale, applied when zoomMode is "customFit" */
+    customZoomScale?: number;
+    /** the horizontal center offset for customFit zoom */
+    customZoomCenterX?: number;
+    /** the vertical center offset for customFit zoom */
+    customZoomCenterY?: number;
+    /** the rendered page width in pixels, the unit customFit centers use */
+    customZoomPageWidth?: number;
+    /** the rendered page height in pixels, the unit customFit centers use */
+    customZoomPageHeight?: number;
+    /** the orientation the customFit zoom was set in */
+    customZoomOrientation?: Orientation;
     /**
      * whether to refresh current file structure before putting
      *
@@ -296,6 +309,28 @@ export interface RemarkableApi {
      * doesn't match the current server generation, requiring you to retry until
      * it works.
      *
+     * @remarks
+     * When `zoomMode` is `"customFit"` the `customZoom*` fields describe the view,
+     * all in the source page's device pixels: `customZoomPageWidth` and
+     * `customZoomPageHeight` are the page dimensions scaled by the device dpi
+     * (`pagePt * dpi / 72`, see {@link deviceScreens | `deviceScreens`}), and the
+     * centers are in those pixels.
+     *
+     * The view always has the device's aspect ratio — you control its height and
+     * position, not its shape. `customZoomScale` is a fit-to-height zoom: at `1`
+     * the page height fills the screen, and the linear magnification is
+     * `customZoomScale` squared. `customZoomCenterX` offsets the center of the
+     * view horizontally from the page center, and `customZoomCenterY` is the
+     * absolute distance of the center down from the top of the page; the view's
+     * width follows from its height and the device aspect ratio.
+     *
+     * The fields are a single document-wide setting, but `customZoomCenterY` is
+     * applied against each page's own rendered height. On a page rendered taller
+     * than `customZoomPageHeight` that distance is a smaller fraction of the page,
+     * so the view sits higher and cuts off the bottom; on a shorter page it sits
+     * lower and cuts off the top. `customZoomScale` (a ratio) and
+     * `customZoomCenterX` (an offset from center) do not shift with page size.
+     *
      * @param visibleName - the name to display on the reMarkable
      * @param buffer - the raw pdf
      * @param opts - put options

package/dist/index.js

@@ -57,13 +57,11 @@ import { z } from "zod";
 import { HashNotFoundError, ValidationError } from "./error.js";
 import { LruCache } from "./lru.js";
 import { RawRemarkable, } from "./raw.js";
+export { deviceScreens, } from "./devices.js";
 export { HashNotFoundError, ValidationError } from "./error.js";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
 const RAW_HOST = "https://eu.tectonic.remarkable.com";
 const UPLOAD_HOST = "https://internal.cloud.remarkable.com";
-// ------------ //
-// Request Info //
-// ------------ //
 // The section has all the types that are stored in the remarkable cloud.
 const idReg = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}||trash)$/;
 /** An error that gets thrown when the backend while trying to update
@@ -295,7 +293,7 @@ class Remarkable {
         }
         return zip.generateAsync({ type: "uint8array" });
     }
-    async #putFile(visibleName, fileType, buffer, { refresh, parent = "", pinned = false, zoomMode = "bestFit", viewBackgroundFilter, textScale = 1, textAlignment = "justify", fontName = "", coverPageNumber = -1, authors, title, publicationDate, publisher, extraMetadata = {}, lineHeight = -1, margins = 125, orientation = "portrait", tags, }) {
+    async #putFile(visibleName, fileType, buffer, { refresh, parent = "", pinned = false, zoomMode = "bestFit", viewBackgroundFilter, textScale = 1, textAlignment = "justify", fontName = "", coverPageNumber = -1, authors, title, publicationDate, publisher, extraMetadata = {}, lineHeight = -1, margins = 125, orientation = "portrait", tags, customZoomScale, customZoomCenterX, customZoomCenterY, customZoomPageWidth, customZoomPageHeight, customZoomOrientation, }) {
         if (parent && !idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
@@ -325,6 +323,12 @@ class Remarkable {
             textAlignment,
             textScale,
             zoomMode,
+            customZoomScale,
+            customZoomCenterX,
+            customZoomCenterY,
+            customZoomPageWidth,
+            customZoomPageHeight,
+            customZoomOrientation,
             viewBackgroundFilter,
             // NOTE for some reason we need to "fake" the number of pages at 1, and
             // create "valid" output for that
@@ -339,7 +343,6 @@ class Remarkable {
         const [[contentEntry, uploadContent], [metadataEntry, uploadMetadata], [pagedataEntry, uploadPagedata], [fileEntry, uploadFile], [rootHash, generation, schemaVersion],] = await Promise.all([
             this.raw.putContent(`${id}.content`, content),
             this.raw.putMetadata(`${id}.metadata`, metadata),
-            // eslint-disable-next-line spellcheck/spell-checker
             this.raw.putText(`${id}.pagedata`, "\n"),
             this.raw.putFile(`${id}.${fileType}`, buffer),
             this.#getRootHash(refresh),

package/dist/lru.d.ts

@@ -0,0 +1,8 @@
+export declare class LruCache extends Map<string, string | null> {
+    #private;
+    constructor(maxSize: number, entries?: Iterable<[string, string | null]>);
+    get(key: string): string | null | undefined;
+    set(key: string, value: string | null): this;
+    delete(key: string): boolean;
+    clear(): void;
+}

package/dist/lru.js

@@ -0,0 +1,64 @@
+export class LruCache extends Map {
+    #maxSize;
+    #currentSize = 0;
+    constructor(maxSize, entries = []) {
+        super();
+        this.#maxSize = maxSize;
+        for (const [key, value] of entries) {
+            this.set(key, value);
+        }
+    }
+    get(key) {
+        const res = super.get(key);
+        if (res !== undefined) {
+            // update order so key is most recent
+            super.delete(key);
+            super.set(key, res);
+        }
+        return res;
+    }
+    set(key, value) {
+        const existing = super.get(key);
+        if (existing === undefined) {
+            this.#currentSize += key.length; // adding a new key
+        }
+        else if (existing !== null) {
+            this.#currentSize -= existing.length; // removing old value
+        }
+        if (value !== null) {
+            this.#currentSize += value.length;
+        }
+        // delete existing value
+        super.delete(key);
+        // evict down to desired size
+        let entry;
+        while (this.#currentSize > this.#maxSize &&
+            (entry = this.entries().next().value)) {
+            const [oldestKey, oldestValue] = entry;
+            super.delete(oldestKey);
+            this.#currentSize -= oldestKey.length;
+            if (oldestValue !== null) {
+                this.#currentSize -= oldestValue.length;
+            }
+        }
+        // finally insert new key and return
+        super.set(key, value);
+        return this;
+    }
+    delete(key) {
+        const value = super.get(key);
+        if (value === undefined) {
+            return false;
+        }
+        super.delete(key);
+        if (value !== null) {
+            this.#currentSize -= value.length;
+        }
+        this.#currentSize -= key.length;
+        return true;
+    }
+    clear() {
+        super.clear();
+        this.#currentSize = 0;
+    }
+}

package/dist/raw.d.ts

@@ -1,4 +1,3 @@
-import "core-js/proposals/array-buffer-base64";
 /** request types */
 export type RequestMethod = "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
 /** the supported upload mime types */
@@ -227,38 +226,43 @@ export interface CommonDocumentContent {
      */
     textScale: number;
     /**
-     * the center of the zoom for customFit zoom
+     * the horizontal center of a customFit zoom
      *
-     * This is an absolute offset from the center of the page. Negative numbers
-     * indicate shifted left and positive numbers indicate shifted right. The
-     * units are relative to the document pixels, but it's not sure how the
-     * document size is calculated.
+     * An offset in device pixels from the horizontal center of the page (0 =
+     * centered, negative = left, positive = right). This and
+     * {@link customZoomCenterY} are in the page's own frame, so device
+     * orientation does not affect them.
      */
     customZoomCenterX?: number;
     /**
-     * the center of the zoom for customFit documents
+     * the vertical center of a customFit zoom
      *
-     * This is an absolute number relative to the top of the page. Negative
-     * numbers indicate shifted up, while positive numbers indicate shifted down.
-     * The units are relative to the document pixels, but it's not sure how the
-     * document size is calculated.
+     * An absolute distance in device pixels from the top of the page (negative =
+     * up, positive = down); centering is half the page's rendered height.
      */
     customZoomCenterY?: number;
-    /** this seems unused */
+    /** the orientation the customFit zoom was set in */
     customZoomOrientation?: Orientation;
-    /** this seems unused */
+    /**
+     * the rendered height of the pdf page, in device pixels
+     *
+     * Computed from the pdf page height in points and the device dpi as
+     * `heightPt * dpi / 72`; the dpi depends on the model (see
+     * {@link deviceScreens | `deviceScreens`}).
+     */
     customZoomPageHeight?: number;
-    /** this seems unused */
+    /** the rendered width of the pdf page, in device pixels */
     customZoomPageWidth?: number;
     /**
-     * the scale for customFit documents
+     * the scale for a customFit zoom
      *
-     * 1 indicates no zoom, smaller numbers indicate zoomed out, larger numbers
-     * indicate zoomed in. reMarkable generally allows setting this from 0.5 to 5,
-     * but values outside that bound are still supported.
+     * Calibrated on the page's fit-to-height: at 1 the rendered page height fills
+     * the screen and the linear magnification is customZoomScale squared. 1
+     * indicates no zoom; reMarkable generally allows 0.5 to 5, but values outside
+     * that bound are still supported.
      */
     customZoomScale?: number;
-    /** what zoom mode is set for the page */
+    /** the zoom mode; customFit applies the customZoom* fields, the rest auto-fit */
     zoomMode?: ZoomMode;
     /** [speculative] a transform matrix, a. la. css matrix transform */
     transform?: Partial<Record<`m${"1" | "2" | "3"}${"1" | "2" | "3"}`, number>>;

package/dist/raw.js

@@ -2,7 +2,6 @@ import CRC32C from "crc-32/crc32c";
 import { z } from "zod";
 import { ValidationError } from "./error.js";
 import { concatArrays } from "./utils.js";
-import "core-js/proposals/array-buffer-base64";
 const hashReg = /^[0-9a-f]{64}$/;
 const tag = z
     .object({
@@ -127,7 +126,6 @@ const documentContentOptional = {
     })
         .passthrough()
         .optional(),
-    // eslint-disable-next-line spellcheck/spell-checker
     viewBackgroundFilter: z.enum(["off", "fullpage"]).optional(),
     zoomMode: z
         .enum(["bestFit", "customFit", "fitToHeight", "fitToWidth"])
@@ -380,7 +378,6 @@ export class RawRemarkable {
                 body: bytes,
                 headers: {
                     "rm-filename": fileName,
-                    // eslint-disable-next-line spellcheck/spell-checker
                     "x-goog-hash": `crc32c=${crcHash}`,
                 },
             });