rmapi-js 13.0.0 → 14.1.0

package/dist/raw.js

@@ -66,14 +66,14 @@ const tag = z
     name: z.string(),
     timestamp: z.number(),
 })
-    .passthrough();
+    .loose();
 const pageTag = z
     .object({
     name: z.string(),
     pageId: z.string(),
     timestamp: z.number(),
 })
-    .passthrough();
+    .loose();
 const documentMetadata = z
     .object({
     authors: z.array(z.string()).optional(),
@@ -81,53 +81,51 @@ const documentMetadata = z
     publicationDate: z.string().optional(),
     publisher: z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const cPagePage = z
     .object({
     id: z.string(),
-    idx: z.object({ timestamp: z.string(), value: z.string() }).passthrough(),
+    idx: z.object({ timestamp: z.string(), value: z.string() }).loose(),
     template: z
         .object({ timestamp: z.string(), value: z.string() })
-        .passthrough()
+        .loose()
         .optional(),
     redir: z
         .object({ timestamp: z.string(), value: z.number().int() })
-        .passthrough()
+        .loose()
         .optional(),
     scrollTime: z
         .object({
         timestamp: z.string(),
-        value: z.string().datetime({ offset: true }),
+        value: z.iso.datetime({ offset: true }),
     })
-        .passthrough()
+        .loose()
         .optional(),
     verticalScroll: z
         .object({ timestamp: z.string(), value: z.number() })
-        .passthrough()
+        .loose()
         .optional(),
     deleted: z
         .object({ timestamp: z.string(), value: z.number().int() })
-        .passthrough()
+        .loose()
         .optional(),
     modifed: z.string().optional(),
 })
-    .passthrough();
+    .loose();
 const cPages = z
     .object({
-    lastOpened: z
-        .object({ timestamp: z.string(), value: z.string() })
-        .passthrough(),
+    lastOpened: z.object({ timestamp: z.string(), value: z.string() }).loose(),
     original: z
         .object({ timestamp: z.string(), value: z.number().int() })
-        .passthrough(),
+        .loose(),
     pages: z.array(cPagePage),
     uuids: z
         .array(z
         .object({ first: z.string(), second: z.number().int().nonnegative() })
-        .passthrough())
+        .loose())
         .nullable(),
 })
-    .passthrough();
+    .loose();
 const collectionContent = z
     .object({
     tags: z.array(tag).optional(),
@@ -162,7 +160,7 @@ const documentContentOptional = {
     formatVersion: z.number().int().nonnegative().optional(),
     keyboardMetadata: z
         .object({ count: z.number().int().nonnegative(), timestamp: z.number() })
-        .passthrough()
+        .loose()
         .optional(),
     lastOpenedPage: z.number().int().optional(),
     margins: z.number().int().nonnegative().optional(),
@@ -183,7 +181,7 @@ const documentContentOptional = {
         m32: z.number().optional(),
         m33: z.number().optional(),
     })
-        .passthrough()
+        .loose()
         .optional(),
     viewBackgroundFilter: z.enum(["off", "fullpage"]).optional(),
     zoomMode: z
@@ -192,13 +190,13 @@ const documentContentOptional = {
 };
 const commonDocumentContent = z
     .object({ ...documentContentRequired, ...documentContentOptional })
-    .passthrough();
+    .loose();
 const documentContent = commonDocumentContent
     .extend({ tags: z.array(tag).optional() })
-    .passthrough();
+    .loose();
 const legacyDocumentContent = commonDocumentContent
     .extend({ tags: z.array(z.string()).optional() })
-    .passthrough();
+    .loose();
 const templateContent = z
     .object({
     id: z.string().optional(),
@@ -216,7 +214,7 @@ const templateContent = z
     items: z.array(z.unknown()),
     formatVersion: z.number().int().nonnegative().optional(),
 })
-    .passthrough();
+    .loose();
 // content payloads aren't discriminable (legacy/modern differ only by tags
 // element type), so this is an ordered union: the first matching variant wins
 const content = z.union([
@@ -242,17 +240,17 @@ const highlightsFile = z
             width: z.number(),
             height: z.number(),
         })
-            .passthrough()),
+            .loose()),
     })
-        .passthrough())),
+        .loose())),
 })
-    .passthrough();
+    .loose();
 const pageMetadataReg = /\/[^/]+-metadata\.json$/;
 const pageMetadata = z
     .object({
-    layers: z.array(z.object({ name: z.string() }).passthrough()),
+    layers: z.array(z.object({ name: z.string() }).loose()),
 })
-    .passthrough();
+    .loose();
 const metadata = z
     .object({
     lastModified: z.string().optional(),
@@ -271,7 +269,7 @@ const metadata = z
     new: z.boolean().optional(),
     source: z.string().optional(),
 })
-    .passthrough();
+    .loose();
 /** parse and validate the json text of a `.metadata` file */
 export function parseMetadata(text) {
     const loaded = JSON.parse(text);
@@ -282,20 +280,20 @@ const updatedRootHash = z
     hash: z.string(),
     generation: z.number(),
 })
-    .passthrough();
+    .loose();
 const rootHash = z
     .object({
     hash: z.string(),
     generation: z.number(),
     schemaVersion: z.number().int().nonnegative(),
 })
-    .passthrough();
+    .loose();
 const nativeItemRef = z
     .object({
     docID: z.string(),
     hash: z.string(),
 })
-    .passthrough();
+    .loose();
 async function digest(buff) {
     const digest = await crypto.subtle.digest("SHA-256", 
     // NOTE this is type hinted wrong, but it does work correctly on a uint8 view
@@ -389,6 +387,7 @@ function parseRawEntryLine(line) {
  */
 export class RawRemarkable {
     #authedFetch;
+    #authedSocket;
     #rawHost;
     #uploadHost;
     /**
@@ -402,8 +401,9 @@ export class RawRemarkable {
      */
     #cache;
     #maxCachedBytes;
-    constructor(authedFetch, cache, rawHost, uploadHost, maxCachedBytes) {
+    constructor(authedFetch, authedSocket, cache, rawHost, uploadHost, maxCachedBytes) {
         this.#authedFetch = authedFetch;
+        this.#authedSocket = authedSocket;
         this.#cache = cache;
         this.#rawHost = rawHost;
         this.#uploadHost = uploadHost;
@@ -867,6 +867,22 @@ export class RawRemarkable {
         const { docID, hash } = nativeItemRef.parse(loaded);
         return { id: docID, hash };
     }
+    /**
+     * open the websocket reMarkable pushes notifications to
+     *
+     * The server drops the socket every few minutes, so anything long lived has
+     * to reopen it. {@link RemarkableApi.listen | `listen`} does that, and parses
+     * the sync notifications out of what arrives.
+     *
+     * reMarkable authorizes the handshake with a header, which node and bun can
+     * attach but a browser's `WebSocket` can't, so this is server side only.
+     *
+     * @returns the connecting socket
+     */
+    notifications() {
+        const host = this.#rawHost.replace(/^http/, "ws");
+        return this.#authedSocket(`${host}/notifications/ws/json/1`);
+    }
     /**
      * dump the current cache to a string to preserve between session
      *

package/dist/rm5.d.ts

@@ -13,6 +13,7 @@
  *
  * @packageDocumentation
  */
+import { type RmBrushCode, type RmColorCode } from "./codes.js";
 /** the flat reMarkable `.lines` file versions read into an {@link RmPageV5} */
 export type RmVersion = 3 | 5;
 /** a single sampled point along a stroke */
@@ -30,20 +31,12 @@ export interface RmPoint {
     /** 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.
- */
+/** a single stroke (called a "line") within a layer */
 export interface RmLine {
-    /** the raw brush/pen type code */
-    brushType: number;
-    /** the raw color code */
-    color: number;
+    /** the pen code, named by {@link rmBrushes | `rmBrushes`} */
+    brushType: RmBrushCode;
+    /** the color code, named by {@link rmColors | `rmColors`} */
+    color: RmColorCode;
     /** a per-stroke padding field, typically 0 */
     padding?: number;
     /** the base brush size */
@@ -70,23 +63,6 @@ export interface RmPageV5 {
     /** 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 */

package/dist/rm5.js

@@ -13,47 +13,7 @@
  *
  * @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",
-};
+import { rmBrushCode, rmColorCode, } from "./codes.js";
 /** 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 */
@@ -83,8 +43,8 @@ export function parseV5(data, version) {
         const numLines = readInt();
         const lines = [];
         for (let line = 0; line < numLines; line++) {
-            const brushType = readInt();
-            const color = readInt();
+            const brushType = rmBrushCode.parse(readInt());
+            const color = rmColorCode.parse(readInt());
             const padding = readInt();
             const brushBaseSize = readFloat();
             const unknown = version === 5 ? readInt() : undefined;

package/dist/rm6.d.ts

@@ -11,6 +11,7 @@
  *
  * @packageDocumentation
  */
+import { type RmBrushCode, type RmColorCode } from "./codes.js";
 /**
  * a CRDT identifier: an `(authorId, counter)` pair, unique across replicas
  *
@@ -54,10 +55,10 @@ export interface RmV6Point {
 }
 /** a version 6 stroke */
 export interface RmV6Line {
-    /** the raw pen/tool code */
-    tool: number;
-    /** the raw color code */
-    color: number;
+    /** the pen code, named by `rmBrushes` */
+    tool: RmBrushCode;
+    /** the color code, named by `rmColors` */
+    color: RmColorCode;
     /** the stroke thickness scale */
     thicknessScale: number;
     /** the length at which the stroke starts */
@@ -94,8 +95,8 @@ export interface GlyphRange {
     start?: number;
     /** the length of the range */
     length: number;
-    /** the raw color code */
-    color: number;
+    /** the color code, named by `rmColors` */
+    color: RmColorCode;
     /** the highlighted text */
     text: string;
     /** the bounding rectangles of the highlight */

package/dist/rm6.js

@@ -11,6 +11,7 @@
  *
  * @packageDocumentation
  */
+import { rmBrushCode, rmColorCode, } from "./codes.js";
 /** the scene-tree root node id */
 export const ROOT_ID = { authorId: 0, counter: 1 };
 /** the CRDT sequence end marker / unset id */
@@ -342,8 +343,8 @@ function readItemEnvelope(reader, readValue) {
     return { parentId, item: { itemId, leftId, rightId, deletedLength, value } };
 }
 function readLineValue(reader, version) {
-    const tool = reader.readInt(1);
-    const color = reader.readInt(2);
+    const tool = rmBrushCode.parse(reader.readInt(1));
+    const color = rmColorCode.parse(reader.readInt(2));
     const thicknessScale = reader.readDouble(3);
     const startingLength = reader.readFloat(4);
     const points = reader.subblock(5, () => {
@@ -394,7 +395,7 @@ function readGlyphValue(reader) {
     const explicitLength = reader.hasTag(3, TAG_BYTE4)
         ? reader.readInt(3)
         : undefined;
-    const color = reader.readInt(4);
+    const color = rmColorCode.parse(reader.readInt(4));
     const text = reader.readString(5);
     const rectangles = reader.subblock(6, () => {
         const count = reader.varuint();