rmapi-js 14.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/index.d.ts

@@ -185,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
  *
@@ -206,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
      *
@@ -674,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
      *
@@ -720,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;
@@ -793,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

@@ -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
      *

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
      *