rmapi-js 13.0.0 → 14.1.0

package/README.md

@@ -67,6 +67,20 @@ const [entry] = await api.listItems()
 const buffer = await api.getEpub(entry)
 ```
 
+To react to changes as they happen, `listen` yields a notification each time a
+device finishes syncing. It names the device, not what changed, so use it as a
+cue to re-read whatever you care about. Compare against `deviceId` to skip your
+own syncs. reMarkable authorizes the socket's handshake with a header, and a
+browser's `WebSocket` takes only a url, so this needs node or bun.
+
+```ts
+for await (const { attributes } of api.listen()) {
+  if (attributes.sourceDeviceID !== api.deviceId) {
+    const fileEntries = await api.listItems(true);
+  }
+}
+```
+
 ### Gotchas
 
 By default, all calls try to do their best to verify that the input and output

package/dist/codes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The pen and color codes a stroke carries, shared by every `.rm` version.
+ *
+ * A stroke stores its pen and its color as small integers. Both sets grew with
+ * the firmware, so a code from a newer device can name the same pen or color
+ * as an older one. Reading a page checks the codes against these lists.
+ *
+ * @packageDocumentation
+ */
+import { z } from "zod";
+/** a pen/tool name for a stroke */
+export type RmBrush = "brush" | "pencil" | "ballpoint" | "marker" | "fineliner" | "highlighter" | "eraser" | "mechanicalPencil" | "eraseArea" | "calligraphy" | "shader";
+/** a pen code that appears in a file */
+export type RmBrushCode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 21 | 23;
+export declare const rmBrushCode: z.ZodType<RmBrushCode>;
+/**
+ * the reMarkable pens, by code
+ *
+ * The codes come in two firmware families, so two codes can name the same pen.
+ */
+export declare const rmBrushes: Readonly<Record<RmBrushCode, RmBrush>>;
+/** a color name for a stroke */
+export type RmColor = "black" | "gray" | "white" | "yellow" | "green" | "pink" | "blue" | "red" | "grayOverlap" | "highlight" | "cyan" | "magenta";
+/** a color code that appears in a file */
+export type RmColorCode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
+export declare const rmColorCode: z.ZodType<RmColorCode>;
+/**
+ * the reMarkable palette, by code
+ *
+ * The palette grew when colored annotations arrived and again for the Paper
+ * Pro, so two codes can name the same color. `"highlight"` is a marker rather
+ * than a color — the stroke's real color is its `colorRgba`. The shade a name
+ * renders as depends on the device.
+ */
+export declare const rmColors: Readonly<Record<RmColorCode, RmColor>>;

package/dist/codes.js

@@ -0,0 +1,61 @@
+/**
+ * The pen and color codes a stroke carries, shared by every `.rm` version.
+ *
+ * A stroke stores its pen and its color as small integers. Both sets grew with
+ * the firmware, so a code from a newer device can name the same pen or color
+ * as an older one. Reading a page checks the codes against these lists.
+ *
+ * @packageDocumentation
+ */
+import { z } from "zod";
+export const rmBrushCode = z.literal([0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 13, 14, 15, 16, 17, 18, 21, 23], { error: "unknown pen code" });
+/**
+ * the reMarkable pens, by code
+ *
+ * The codes come in two firmware families, so two codes can name the same pen.
+ */
+export const rmBrushes = {
+    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",
+};
+export const rmColorCode = z.literal([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13], { error: "unknown color code" });
+/**
+ * the reMarkable palette, by code
+ *
+ * The palette grew when colored annotations arrived and again for the Paper
+ * Pro, so two codes can name the same color. `"highlight"` is a marker rather
+ * than a color — the stroke's real color is its `colorRgba`. The shade a name
+ * renders as depends on the device.
+ */
+export const rmColors = {
+    0: "black",
+    1: "gray",
+    2: "white",
+    3: "yellow",
+    4: "green",
+    5: "pink",
+    6: "blue",
+    7: "red",
+    8: "grayOverlap",
+    9: "highlight",
+    10: "green",
+    11: "cyan",
+    12: "magenta",
+    13: "yellow",
+};

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { type BackgroundFilter, type CollectionContent, type Content, type DocumentContent, type Highlight, type ItemRef, type Metadata, type Orientation, type PageMetadata, RawRemarkable, type RmPage, type Tag, type TemplateContent, type TextAlignment, type ZoomMode } from "./raw.js";
+export type { RmBrush, RmBrushCode, RmColor, RmColorCode, } from "./codes.js";
+export { rmBrushes, rmColors } from "./codes.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, EntryType, FileType, Highlight, HighlightRect, ItemRef, KeyboardMetadata, LegacyCollectionContent, LegacyDocumentContent, Metadata, Orientation, PageLayer, PageMetadata, PageTag, PendingEntry, RawEntry, RawRemarkableApi, RmPage, SchemaVersion, Tag, TemplateContent, TextAlignment, UploadMimeType, ZoomMode, } from "./raw.js";
-export type { RmBrush, RmLayer, RmLine, RmPageV5, RmPoint, RmVersion, } from "./rm5.js";
-export { decodeBrush, rmColors } from "./rm5.js";
+export type { RmLayer, RmLine, RmPageV5, RmPoint, RmVersion, } from "./rm5.js";
 export type { AuthorIdsBlock, CrdtId, GlyphRange, LwwValue, MigrationInfoBlock, PageInfoBlock, Rectangle, RmBlock, RmScene, RmSceneItem, RmSceneLayer, RmV6Line, RmV6Point, RmV6Text, RmV6TextValue, RootTextBlock, SceneGlyphItemBlock, SceneGroupItemBlock, SceneInfoBlock, SceneItem, SceneLineItemBlock, SceneTextItemBlock, SceneTombstoneItemBlock, SceneTreeBlock, TreeNodeAnchor, TreeNodeBlock, UnknownBlock, } from "./rm6.js";
 export { crdtKey } from "./rm6.js";
 /** common properties shared by collections and documents */
@@ -184,6 +185,41 @@ export interface PutOptions {
      */
     refresh?: boolean;
 }
+/** what a sync notification says happened */
+export interface SyncEventAttributes {
+    /** the kind of event, always a sync completion here */
+    event: "SyncComplete";
+    /**
+     * the device that synced
+     *
+     * Tablets report their serial, api clients the id they registered with, so
+     * compare it against {@link RemarkableApi.deviceId | `deviceId`} to spot your
+     * own syncs.
+     */
+    sourceDeviceID: string;
+    /** the account that synced, as an auth0 id */
+    auth0UserID: string;
+    /** the same value as `auth0UserID` in every event we've seen */
+    userID?: string;
+    /** the notification family, always "SyncEventNotification" so far */
+    eventType?: string;
+    /** the format version, always "1" so far */
+    eventVersion?: string;
+    /** the organization of a managed account, otherwise empty */
+    orgID?: string;
+}
+/**
+ * a sync notification pushed over the notification socket
+ *
+ * Events carry a little more, but nothing worth depending on, so the rest is
+ * passed through untyped rather than validated.
+ */
+export interface SyncEvent {
+    /** what happened */
+    attributes: SyncEventAttributes;
+    /** the id of this notification */
+    messageid?: string;
+}
 /**
  * the api for accessing remarkable functions
  *
@@ -205,6 +241,13 @@ declare class Remarkable {
     /** scoped access to the raw low-level api */
     readonly raw: RawRemarkable;
     constructor(sessionToken: string, rawHost: string, uploadHost: string, cache: Map<string, Uint8Array | null>, maxGenerationRetries: number, maxTransientRetries: number, maxCachedBytes: number);
+    /**
+     * the id this api is registered under
+     *
+     * This is the uuid passed to {@link register | `register`}, which reMarkable
+     * stamps on everything this client does. Tablets use their serial instead.
+     */
+    get deviceId(): string;
     /**
      * list all items
      *
@@ -673,6 +716,31 @@ declare class Remarkable {
      * @returns references to the deleted entries, each with its new hash
      */
     bulkDelete(refs: readonly ItemRef[], refresh?: boolean): Promise<ItemRef[]>;
+    /**
+     * listen for sync notifications
+     *
+     * reMarkable sends one every time a device finishes syncing. It names the
+     * device, not what changed, so use it as a cue to re-read.
+     *
+     * The socket is reopened when the server drops it, which happens every few
+     * minutes. Leaving the loop closes it. Session tokens expire after a few
+     * hours, and this throws once reconnecting with an expired one fails.
+     *
+     * 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.
+     *
+     * @example
+     * ```ts
+     * for await (const { attributes } of api.listen()) {
+     *   if (attributes.sourceDeviceID !== api.deviceId) {
+     *     const entries = await api.listItems(true);
+     *   }
+     * }
+     * ```
+     *
+     * @returns the notifications, in the order they arrive
+     */
+    listen(): AsyncGenerator<SyncEvent, void, undefined>;
     /**
      * get the current cache value as a string
      *
@@ -719,6 +787,10 @@ export interface RemarkableSessionOptions {
     /**
      * the base url for making upload requests
      *
+     * @deprecated uploads now go to the same server as everything else, so this
+     *   will be removed and `rawHost` will cover both. Point `rawHost` at the
+     *   backend you want instead.
+     *
      * @defaultValue "https://internal.cloud.remarkable.com"
      */
     uploadHost?: string;
@@ -792,6 +864,9 @@ export declare function auth(deviceToken: string, { authHost }?: AuthOptions): P
  * If requests start failing, simply recreate the api instance with a freshly
  * fetched session token.
  *
+ * The device id is read out of the token, so this throws if it isn't one
+ * reMarkable minted.
+ *
  * @param sessionToken - the session token used for authorization
  * @returns an api instance
  */

package/dist/index.js

@@ -110,9 +110,9 @@ import { z } from "zod";
 import { HashNotFoundError, ValidationError } from "./error.js";
 import { LruCache } from "./lru.js";
 import { BYTES_PREFIX, CACHE_VERSION, parseMetadata, RawRemarkable, TEXT_PREFIX, } from "./raw.js";
+export { rmBrushes, rmColors } from "./codes.js";
 export { deviceScreens, } from "./devices.js";
 export { HashNotFoundError, ValidationError } from "./error.js";
-export { decodeBrush, rmColors } from "./rm5.js";
 export { crdtKey } from "./rm6.js";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
 const RAW_HOST = "https://eu.tectonic.remarkable.com";
@@ -237,6 +237,45 @@ export async function register(code, { deviceDesc = "browser-chrome", uuid = uui
         return await resp.text();
     }
 }
+const tokenClaims = z
+    .object({ "device-id": z.string() })
+    .loose();
+function tokenDeviceId(token) {
+    const [, payload] = token.split(".", 2);
+    if (payload === undefined) {
+        throw new Error("token wasn't a jwt, so it had no device id");
+    }
+    const decoded = Uint8Array.fromBase64(payload, {
+        alphabet: "base64url",
+        lastChunkHandling: "loose",
+    });
+    const json = new TextDecoder().decode(decoded);
+    const parsed = tokenClaims.parse(JSON.parse(json));
+    return parsed["device-id"];
+}
+const notification = z
+    .object({
+    message: z
+        .object({ attributes: z.object({ event: z.string() }).loose() })
+        .loose(),
+})
+    .loose();
+const syncEvent = z
+    .object({
+    attributes: z
+        .object({
+        event: z.literal("SyncComplete"),
+        sourceDeviceID: z.string(),
+        auth0UserID: z.string(),
+        userID: z.string().optional(),
+        eventType: z.string().optional(),
+        eventVersion: z.string().optional(),
+        orgID: z.string().optional(),
+    })
+        .loose(),
+    messageid: z.string().optional(),
+})
+    .loose();
 /**
  * the api for accessing remarkable functions
  *
@@ -259,6 +298,7 @@ class Remarkable {
     #cache;
     /** scoped access to the raw low-level api */
     raw;
+    #deviceId;
     #maxGenerationRetries;
     #maxTransientRetries;
     #lastHashGen;
@@ -267,10 +307,24 @@ class Remarkable {
     #rootMutex = new Mutex();
     constructor(sessionToken, rawHost, uploadHost, cache, maxGenerationRetries, maxTransientRetries, maxCachedBytes) {
         this.#sessionToken = sessionToken;
+        this.#deviceId = tokenDeviceId(sessionToken);
         this.#cache = cache;
         this.#maxGenerationRetries = maxGenerationRetries;
         this.#maxTransientRetries = maxTransientRetries;
-        this.raw = new RawRemarkable((method, url, { body, headers } = {}) => this.#authedFetch(url, { method, body, headers }), cache, rawHost, uploadHost, maxCachedBytes);
+        this.raw = new RawRemarkable((method, url, { body, headers } = {}) => this.#authedFetch(url, { method, body, headers }), (url) => 
+        // node and bun both take headers here, the dom types don't know about them
+        new WebSocket(url, {
+            headers: { Authorization: `Bearer ${this.#sessionToken}` },
+        }), cache, rawHost, uploadHost, maxCachedBytes);
+    }
+    /**
+     * the id this api is registered under
+     *
+     * This is the uuid passed to {@link register | `register`}, which reMarkable
+     * stamps on everything this client does. Tablets use their serial instead.
+     */
+    get deviceId() {
+        return this.#deviceId;
     }
     async #getRootHash(refresh = false) {
         if (refresh || this.#lastHashGen === undefined) {
@@ -1577,6 +1631,107 @@ class Remarkable {
     async bulkDelete(refs, refresh = false) {
         return await this.bulkMove(refs, TRASH_ID, refresh);
     }
+    /**
+     * listen for sync notifications
+     *
+     * reMarkable sends one every time a device finishes syncing. It names the
+     * device, not what changed, so use it as a cue to re-read.
+     *
+     * The socket is reopened when the server drops it, which happens every few
+     * minutes. Leaving the loop closes it. Session tokens expire after a few
+     * hours, and this throws once reconnecting with an expired one fails.
+     *
+     * 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.
+     *
+     * @example
+     * ```ts
+     * for await (const { attributes } of api.listen()) {
+     *   if (attributes.sourceDeviceID !== api.deviceId) {
+     *     const entries = await api.listItems(true);
+     *   }
+     * }
+     * ```
+     *
+     * @returns the notifications, in the order they arrive
+     */
+    listen() {
+        const stop = new AbortController();
+        const events = this.#listen(stop.signal);
+        const { return: finish } = events;
+        // an async generator only acts on return once it reaches a yield, so
+        // stopping has to unblock the loop and let it end on its own
+        events.return = async (value) => {
+            stop.abort();
+            return await finish.call(events, value);
+        };
+        return events;
+    }
+    async *#listen(signal) {
+        for (let failures = 0;;) {
+            const socket = this.raw.notifications();
+            const closeSocket = () => {
+                socket.close();
+            };
+            signal.addEventListener("abort", closeSocket, { once: true });
+            const queued = [];
+            let arrived = () => { };
+            // tells a failed handshake, likely an expired token, from the server's
+            // routine drop of a healthy socket
+            let opened = false;
+            let done = false;
+            socket.addEventListener("open", () => {
+                opened = true;
+            });
+            socket.addEventListener("message", ({ data }) => {
+                queued.push(data);
+                arrived();
+            });
+            socket.addEventListener("error", () => {
+                done = true;
+                arrived();
+            });
+            socket.addEventListener("close", () => {
+                done = true;
+                arrived();
+            });
+            try {
+                while (!done || queued.length) {
+                    const raw = queued.shift();
+                    if (raw === undefined) {
+                        await new Promise((res) => {
+                            arrived = res;
+                        });
+                    }
+                    else {
+                        const { message } = notification.parse(JSON.parse(raw));
+                        // screenshare and passcode events share the socket, and their
+                        // attributes are shaped differently
+                        if (message.attributes.event === "SyncComplete") {
+                            yield syncEvent.parse(message);
+                        }
+                    }
+                }
+            }
+            finally {
+                signal.removeEventListener("abort", closeSocket);
+                socket.close();
+            }
+            if (signal.aborted) {
+                return;
+            }
+            else if (opened) {
+                failures = 0;
+            }
+            else if (failures < this.#maxTransientRetries) {
+                failures++;
+            }
+            else {
+                throw new Error("couldn't open the reMarkable notification socket; the session token may have expired");
+            }
+            await sleep(backoffMs(failures, TRANSIENT_BASE_MS));
+        }
+    }
     /**
      * get the current cache value as a string
      *
@@ -1705,6 +1860,9 @@ export async function auth(deviceToken, { authHost = AUTH_HOST } = {}) {
  * If requests start failing, simply recreate the api instance with a freshly
  * fetched session token.
  *
+ * The device id is read out of the token, so this throws if it isn't one
+ * reMarkable minted.
+ *
  * @param sessionToken - the session token used for authorization
  * @returns an api instance
  */

package/dist/raw.d.ts

@@ -511,6 +511,7 @@ type AuthedFetch = (method: RequestMethod, url: string, init?: {
     body?: string | Uint8Array;
     headers?: Record<string, string>;
 }) => Promise<Response>;
+type AuthedSocket = (url: string) => WebSocket;
 /**
  * access to the low-level reMarkable api
  *
@@ -576,7 +577,7 @@ type AuthedFetch = (method: RequestMethod, url: string, init?: {
  */
 export declare class RawRemarkable {
     #private;
-    constructor(authedFetch: AuthedFetch, cache: Map<string, Uint8Array | null>, rawHost: string, uploadHost: string, maxCachedBytes: number);
+    constructor(authedFetch: AuthedFetch, authedSocket: AuthedSocket, cache: Map<string, Uint8Array | null>, rawHost: string, uploadHost: string, maxCachedBytes: number);
     /**
      * gets the root hash and the current generation
      *
@@ -778,6 +779,19 @@ export declare class RawRemarkable {
      * @returns a simple entry with the id and hash of the uploaded file
      */
     uploadFile(visibleName: string, bytes: Uint8Array, mime: UploadMimeType): Promise<ItemRef>;
+    /**
+     * 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(): WebSocket;
     /**
      * dump the current cache to a string to preserve between session
      *