rmapi-js 11.0.0 → 11.1.1

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/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,32 @@ 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` sets a fit-to-height zoom whose
+     * linear magnification is proportional to it: 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 page height fills the screen at
+     * `customZoomScale = sqrt(deviceAspect)` (≈`0.87` for 3:4 devices), not at
+     * `1`. `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,6 +57,7 @@ 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";
@@ -292,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");
         }
@@ -322,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

package/dist/raw.d.ts

@@ -226,38 +226,46 @@ 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
-     *
-     * 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.
+     * 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?: 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>>;