rmapi-js 14.0.0 → 14.2.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
      *
@@ -625,6 +667,28 @@ declare class Remarkable {
      * @returns a reference to the deleted entry, with its new hash
      */
     delete(ref: ItemRef, refresh?: boolean): Promise<ItemRef>;
+    /**
+     * permanently delete an entry
+     *
+     * Unlike {@link delete | `delete`}, which moves an entry to the trash where
+     * the device can still restore it, this drops the entry from the account
+     * outright. Its files stay in the cloud, but nothing points at them anymore
+     * and nothing brings the entry back.
+     *
+     * Only the entry named goes: purging a folder leaves everything inside it
+     * pointing at a parent that's no longer there. Those entries stay in the
+     * account and {@link listItems | `listItems`} still returns them, but no
+     * folder holds them, so nothing browsing the tree will find them. Purge the
+     * contents first, or use {@link purgeTrash | `purgeTrash`}, which takes the
+     * whole tree.
+     *
+     * @example
+     * ```ts
+     * await api.purge(file);
+     * ```
+     * @param ref - a reference to the entry to purge
+     */
+    purge(ref: ItemRef, refresh?: boolean): Promise<void>;
     /**
      * rename an entry
      *
@@ -674,6 +738,66 @@ declare class Remarkable {
      * @returns references to the deleted entries, each with its new hash
      */
     bulkDelete(refs: readonly ItemRef[], refresh?: boolean): Promise<ItemRef[]>;
+    /**
+     * permanently delete many entries
+     *
+     * The bulk form of {@link purge | `purge`}, done in a single root write.
+     *
+     * @example
+     * ```ts
+     * await api.bulkPurge([file]);
+     * ```
+     *
+     * @param refs - references to the entries to purge
+     */
+    bulkPurge(refs: readonly ItemRef[], refresh?: boolean): Promise<void>;
+    /**
+     * permanently delete everything in the trash
+     *
+     * Trashing a folder doesn't touch what's inside it — those entries keep
+     * naming the folder as their parent, which is what lets the device restore
+     * them together — so the trash holds the whole tree hanging off it, not just
+     * the entries whose parent is "trash". This purges all of it in one root
+     * write.
+     *
+     * @example
+     * ```ts
+     * await api.purgeTrash();
+     * ```
+     *
+     * @remarks
+     * Finding that tree means reading every item's metadata, so this costs about
+     * as much as {@link listItems | `listItems`}.
+     *
+     * @param refresh - if true, refresh the root hash before purging
+     * @returns references to the entries that were purged
+     */
+    purgeTrash(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 +844,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 +921,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) {
@@ -353,26 +407,35 @@ class Remarkable {
                 hash: rootHash,
             });
             entries.push(entry);
-            let newRoot;
-            {
-                const env_2 = { stack: [], error: void 0, hasError: false };
-                try {
-                    const rootEntry = __addDisposableResource(env_2, await this.raw.putEntries(ROOT_LIST, entries, 4), true);
-                    newRoot = rootEntry.hash;
-                }
-                catch (e_2) {
-                    env_2.error = e_2;
-                    env_2.hasError = true;
-                }
-                finally {
-                    const result_2 = __disposeResources(env_2);
-                    if (result_2)
-                        await result_2;
-                }
-            }
-            await this.#putRootHash(newRoot, generation);
+            await this.#writeRoot(entries, generation);
         });
     }
+    /**
+     * upload a new root index and point the account at it
+     *
+     * Every blob the index names must already be uploaded, since the root hash
+     * lands as soon as the index does.
+     */
+    async #writeRoot(entries, generation) {
+        let newRoot;
+        {
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                const rootEntry = __addDisposableResource(env_2, await this.raw.putEntries(ROOT_LIST, entries, 4), true);
+                newRoot = rootEntry.hash;
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                const result_2 = __disposeResources(env_2);
+                if (result_2)
+                    await result_2;
+            }
+        }
+        await this.#putRootHash(newRoot, generation);
+    }
     async #authedFetch(url, { body, method = "POST", headers = {}, }) {
         // the root PUT is a compare-and-set; retrying a lost-but-applied response
         // would resurface as a false generation conflict and be double-applied by
@@ -1463,6 +1526,30 @@ class Remarkable {
     async delete(ref, refresh = false) {
         return await this.move(ref, TRASH_ID, refresh);
     }
+    /**
+     * permanently delete an entry
+     *
+     * Unlike {@link delete | `delete`}, which moves an entry to the trash where
+     * the device can still restore it, this drops the entry from the account
+     * outright. Its files stay in the cloud, but nothing points at them anymore
+     * and nothing brings the entry back.
+     *
+     * Only the entry named goes: purging a folder leaves everything inside it
+     * pointing at a parent that's no longer there. Those entries stay in the
+     * account and {@link listItems | `listItems`} still returns them, but no
+     * folder holds them, so nothing browsing the tree will find them. Purge the
+     * contents first, or use {@link purgeTrash | `purgeTrash`}, which takes the
+     * whole tree.
+     *
+     * @example
+     * ```ts
+     * await api.purge(file);
+     * ```
+     * @param ref - a reference to the entry to purge
+     */
+    async purge(ref, refresh = false) {
+        await this.bulkPurge([ref], refresh);
+    }
     /**
      * rename an entry
      *
@@ -1577,6 +1664,219 @@ class Remarkable {
     async bulkDelete(refs, refresh = false) {
         return await this.bulkMove(refs, TRASH_ID, refresh);
     }
+    /**
+     * permanently delete many entries
+     *
+     * The bulk form of {@link purge | `purge`}, done in a single root write.
+     *
+     * @example
+     * ```ts
+     * await api.bulkPurge([file]);
+     * ```
+     *
+     * @param refs - references to the entries to purge
+     */
+    async bulkPurge(refs, refresh = false) {
+        if (!refs.length) {
+            return;
+        }
+        await this.#withRetry(async () => {
+            const [rootHash, generation] = await this.#getRootHash(refresh);
+            const { entries } = await this.raw.getEntries({
+                id: ROOT_LIST,
+                hash: rootHash,
+            });
+            const wanted = new Set(refs.map((ref) => `${ref.id}\0${ref.hash}`));
+            const found = new Set();
+            const newEntries = [];
+            for (const entry of entries) {
+                const key = `${entry.id}\0${entry.hash}`;
+                if (wanted.has(key)) {
+                    found.add(key);
+                }
+                else {
+                    newEntries.push(entry);
+                }
+            }
+            for (const ref of refs) {
+                if (!found.has(`${ref.id}\0${ref.hash}`)) {
+                    throw new HashNotFoundError(ref.hash);
+                }
+            }
+            await this.#writeRoot(newEntries, generation);
+        });
+    }
+    /**
+     * permanently delete everything in the trash
+     *
+     * Trashing a folder doesn't touch what's inside it — those entries keep
+     * naming the folder as their parent, which is what lets the device restore
+     * them together — so the trash holds the whole tree hanging off it, not just
+     * the entries whose parent is "trash". This purges all of it in one root
+     * write.
+     *
+     * @example
+     * ```ts
+     * await api.purgeTrash();
+     * ```
+     *
+     * @remarks
+     * Finding that tree means reading every item's metadata, so this costs about
+     * as much as {@link listItems | `listItems`}.
+     *
+     * @param refresh - if true, refresh the root hash before purging
+     * @returns references to the entries that were purged
+     */
+    async purgeTrash(refresh = false) {
+        return await this.#withRetry(async () => {
+            const [rootHash, generation] = await this.#getRootHash(refresh);
+            const { entries } = await this.raw.getEntries({
+                id: ROOT_LIST,
+                hash: rootHash,
+            });
+            const parents = await Promise.all(entries.map(async (entry) => (await this.getMetadata(entry)).parent));
+            const children = new Map();
+            for (const [ind, entry] of entries.entries()) {
+                const siblings = children.get(parents[ind]);
+                if (siblings === undefined) {
+                    children.set(parents[ind], [entry]);
+                }
+                else {
+                    siblings.push(entry);
+                }
+            }
+            const trashed = new Set();
+            let frontier = children.get(TRASH_ID) ?? [];
+            while (frontier.length) {
+                const next = [];
+                for (const { id } of frontier) {
+                    // skipping what we've already seen also ends a parent cycle, which
+                    // the account shouldn't have but which would loop here forever
+                    if (!trashed.has(id)) {
+                        trashed.add(id);
+                        next.push(...(children.get(id) ?? []));
+                    }
+                }
+                frontier = next;
+            }
+            if (!trashed.size) {
+                return [];
+            }
+            const purged = [];
+            const newEntries = [];
+            for (const entry of entries) {
+                if (trashed.has(entry.id)) {
+                    purged.push({ id: entry.id, hash: entry.hash });
+                }
+                else {
+                    newEntries.push(entry);
+                }
+            }
+            await this.#writeRoot(newEntries, generation);
+            return purged;
+        });
+    }
+    /**
+     * 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 +2005,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
      *