rmapi-js 14.1.0 → 14.3.0

package/dist/index.d.ts

@@ -86,6 +86,18 @@ export declare class ResponseError extends Error {
     readonly statusText: string;
     constructor(status: number, statusText: string, message: string);
 }
+/** an error that results from the service rejecting a registration */
+export declare class RegisterError extends ResponseError {
+    /** the response body */
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string);
+}
+/** an error that results from the service refusing to issue a session token */
+export declare class AuthError extends ResponseError {
+    /** the response body */
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string);
+}
 /** options for registering with the api */
 export interface RegisterOptions {
     /**
@@ -110,6 +122,7 @@ export interface RegisterOptions {
  * token to use the api.
  *
  * @param code - the eight letter code a user got from `https://my.remarkable.com/device/browser/connect`.
+ * @throws RegisterError if the service rejects the registration
  * @returns the device token necessary for creating an api instace. These never expire so persist as long as necessary.
  */
 export declare function register(code: string, { deviceDesc, uuid, authHost, }?: RegisterOptions): Promise<string>;
@@ -667,6 +680,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
      *
@@ -716,6 +751,41 @@ 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
      *
@@ -855,6 +925,7 @@ export interface RemarkableOptions extends AuthOptions, RemarkableSessionOptions
  *
  * @param deviceToken - the device token proving this api instance is
  *    registered. Create one with {@link register}.
+ * @throws AuthError if the service refuses to issue a session token
  * @returns the session token returned by the reMarkable service
  */
 export declare function auth(deviceToken: string, { authHost }?: AuthOptions): Promise<string>;

package/dist/index.js

@@ -205,6 +205,24 @@ export class ResponseError extends Error {
         this.statusText = statusText;
     }
 }
+/** an error that results from the service rejecting a registration */
+export class RegisterError extends ResponseError {
+    /** the response body */
+    body;
+    constructor(status, statusText, body) {
+        super(status, statusText, "couldn't register api");
+        this.body = body;
+    }
+}
+/** an error that results from the service refusing to issue a session token */
+export class AuthError extends ResponseError {
+    /** the response body */
+    body;
+    constructor(status, statusText, body) {
+        super(status, statusText, "couldn't fetch auth token");
+        this.body = body;
+    }
+}
 /**
  * register a device and get the token needed to access the api
  *
@@ -213,6 +231,7 @@ export class ResponseError extends Error {
  * token to use the api.
  *
  * @param code - the eight letter code a user got from `https://my.remarkable.com/device/browser/connect`.
+ * @throws RegisterError if the service rejects the registration
  * @returns the device token necessary for creating an api instace. These never expire so persist as long as necessary.
  */
 export async function register(code, { deviceDesc = "browser-chrome", uuid = uuid4(), authHost = AUTH_HOST, } = {}) {
@@ -223,6 +242,7 @@ export async function register(code, { deviceDesc = "browser-chrome", uuid = uui
         method: "POST",
         headers: {
             Authorization: "Bearer",
+            "Content-Type": "application/json",
         },
         body: JSON.stringify({
             code,
@@ -230,11 +250,12 @@ export async function register(code, { deviceDesc = "browser-chrome", uuid = uui
             deviceID: uuid,
         }),
     });
+    const body = await resp.text();
     if (!resp.ok) {
-        throw new ResponseError(resp.status, resp.statusText, "couldn't register api");
+        throw new RegisterError(resp.status, resp.statusText, body);
     }
     else {
-        return await resp.text();
+        return body;
     }
 }
 const tokenClaims = z
@@ -407,26 +428,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
@@ -1517,6 +1547,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
      *
@@ -1631,6 +1685,118 @@ 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
      *
@@ -1840,6 +2006,7 @@ function decodeCache(dumped) {
  *
  * @param deviceToken - the device token proving this api instance is
  *    registered. Create one with {@link register}.
+ * @throws AuthError if the service refuses to issue a session token
  * @returns the session token returned by the reMarkable service
  */
 export async function auth(deviceToken, { authHost = AUTH_HOST } = {}) {
@@ -1849,10 +2016,13 @@ export async function auth(deviceToken, { authHost = AUTH_HOST } = {}) {
             Authorization: `Bearer ${deviceToken}`,
         },
     });
+    const body = await resp.text();
     if (!resp.ok) {
-        throw new Error(`couldn't fetch auth token: ${resp.statusText}`);
+        throw new AuthError(resp.status, resp.statusText, body);
+    }
+    else {
+        return body;
     }
-    return await resp.text();
 }
 /**
  * Create an API instance from an existing session token.