rmapi-js 11.2.0 → 12.0.0

package/dist/raw.d.ts

@@ -25,11 +25,19 @@ export type RequestMethod = "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | "OPTIO
 export type UploadMimeType = "application/pdf" | "application/epub+zip" | "folder";
 /** the schema version */
 export type SchemaVersion = 3 | 4;
-/** an simple entry without any extra information */
-export interface SimpleEntry {
-    /** the document id */
+/**
+ * a reference to stored cloud data: an id paired with the hash of its state
+ *
+ * This is the canonical way to point at something in the cloud. The `id` names
+ * *what*: a document's uuid at the high level, or a stored file name (like
+ * `<id>.content`) at the low level. The `hash` names *which version*, and
+ * changes every time that data mutates. Reads take one of these, and mutations
+ * return a fresh one with the new hash.
+ */
+export interface ItemRef {
+    /** the id of the referenced data: a document uuid, or a stored file name */
     id: string;
-    /** the document hash */
+    /** the hash of the referenced state */
     hash: string;
 }
 /**
@@ -40,13 +48,9 @@ export interface SimpleEntry {
  * files, the high level entry will have the same hash and id as the low-level
  * entry for that collection.
  */
-export interface RawEntry {
+export interface RawEntry extends ItemRef {
     /** 80000000 for schema 3 collection type or 0 for schema 4 or schema 3 files or */
     type: 80000000 | 0;
-    /** the hash of the collection this points to */
-    hash: string;
-    /** the unique id of the collection */
-    id: string;
     /** the number of subfiles */
     subfiles: number;
     /** the total size of everything in the collection */
@@ -410,6 +414,10 @@ export interface Metadata {
 }
 /** parse and validate the json text of a `.metadata` file */
 export declare function parseMetadata(text: string): Metadata;
+type AuthedFetch = (method: RequestMethod, url: string, init?: {
+    body?: string | Uint8Array;
+    headers?: Record<string, string>;
+}) => Promise<Response>;
 /**
  * access to the low-level reMarkable api
  *
@@ -469,7 +477,10 @@ export declare function parseMetadata(text: string): Metadata;
  *
  * Generally all hashes are 64 character hex strings, and all ids are uuid4.
  */
-export interface RawRemarkableApi {
+export declare class RawRemarkable {
+    #private;
+    constructor(authedFetch: AuthedFetch, cache: Map<string, string | null>, rawHost: string, uploadHost: string);
+    /** make an authorized request to remarkable */
     /**
      * gets the root hash and the current generation
      *
@@ -482,66 +493,62 @@ export interface RawRemarkableApi {
     /**
      * get the raw binary data associated with a hash
      *
-     * @param fileName - the logical file name (`<id>.<ext>` for files, or
-     *   `<id>.docSchema` / `"root.docSchema"` for entry indexes). reMarkable
-     *   validates this against the rm-filename header.
-     * @param hash - the hash to get the data for
+     * @param ref - a reference to the stored file. Its `id` is the logical file
+     *   name (`<id>.<ext>` for files, or `<id>.docSchema` / `"root.docSchema"`
+     *   for entry indexes), which reMarkable validates against the rm-filename
+     *   header. Sub-entries from {@link getEntries | `getEntries`} can be passed
+     *   directly.
      * @returns the data
      */
-    getHash(fileName: string, hash: string): Promise<Uint8Array>;
+    getHash({ id: fileName, hash }: ItemRef): Promise<Uint8Array>;
     /**
      * get raw text data associated with a hash
      *
      * We assume text data are small, and so cache the entire text. If you want to
      * avoid this, use {@link getHash | `getHash`} combined with a TextDecoder.
-  
-     * @param fileName - the logical file name (see {@link getHash})
-     * @param hash - the hash to get text for
+     *
+     * @param ref - a reference to the stored file (see {@link getHash})
      * @returns the text
      */
-    getText(fileName: string, hash: string): Promise<string>;
+    getText({ id: fileName, hash }: ItemRef): Promise<string>;
     /**
      * get the entries associated with a list hash
      *
      * A list hash is the root hash, or any hash with the type 80000000. NOTE
      * these are hashed differently than files.
-  
-     * @param fileName - `"root.docSchema"` for the root, or `"<id>.docSchema"`
-     *   for a sub-document's entry index
-     * @param hash - the hash to get entries for
+     *
+     * @param ref - a reference whose `id` is `"root.docSchema"` for the root, or
+     *   `"<id>.docSchema"` for a sub-document's entry index
      * @returns the entries
      */
-    getEntries(fileName: string, hash: string): Promise<Entries>;
+    getEntries(ref: ItemRef): Promise<Entries>;
     /**
      * get the parsed and validated `Content` of a content hash
      *
      * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
      * validation
-  
-     * @param fileName - typically `"<id>.content"`
-     * @param hash - the hash to get Content for
+     *
+     * @param ref - a reference to the stored file, typically `"<id>.content"`
      * @returns the content
      */
-    getContent(fileName: string, hash: string): Promise<Content>;
+    getContent(ref: ItemRef): Promise<Content>;
     /**
      * get the parsed and validated `Metadata` of a metadata hash
      *
      * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
      * validation
-  
-     * @param fileName - typically `"<id>.metadata"`
-     * @param hash - the hash to get Metadata for
+     *
+     * @param ref - a reference to the stored file, typically `"<id>.metadata"`
      * @returns the metadata
      */
-    getMetadata(fileName: string, hash: string): Promise<Metadata>;
+    getMetadata(ref: ItemRef): Promise<Metadata>;
     /**
      * get the parsed reMarkable lines (`.rm`) drawing of a page hash
-  
-     * @param fileName - typically `"<id>/<pageid>.rm"`
-     * @param hash - the hash to get the page for
+     *
+     * @param ref - a reference to the stored file, typically `"<id>/<pageid>.rm"`
      * @returns the parsed page
      */
-    getRm(fileName: string, hash: string): Promise<RmPage>;
+    getRm(ref: ItemRef): Promise<RmPage>;
     /**
      * the same as {@link putFile | `putFile`} but rendering an `RmPage` to `.rm`
      * bytes
@@ -585,7 +592,7 @@ export interface RawRemarkableApi {
      */
     putFile(fileName: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
     /** the same as {@link putFile | `putFile`} but with caching for text */
-    putText(fileName: string, content: string): Promise<[RawEntry, Promise<void>]>;
+    putText(fileName: string, text: string): Promise<[RawEntry, Promise<void>]>;
     /** the same as {@link putText | `putText`} but with extra validation for Content */
     putContent(fileName: string, content: Content): Promise<[RawEntry, Promise<void>]>;
     /** the same as {@link putText | `putText`} but with extra validation for Metadata */
@@ -624,10 +631,10 @@ export interface RawRemarkableApi {
      * @param visibleName - the name of the file as it should appear on the reMarkable
      * @param bytes - the bytes of the file to upload
      * @param mime - the mime type of the file to upload
-     
+  
      * @returns a simple entry with the id and hash of the uploaded file
      */
-    uploadFile(visibleName: string, bytes: Uint8Array, mime: UploadMimeType): Promise<SimpleEntry>;
+    uploadFile(visibleName: string, bytes: Uint8Array, mime: UploadMimeType): Promise<ItemRef>;
     /**
      * dump the current cache to a string to preserve between session
      *
@@ -637,30 +644,4 @@ export interface RawRemarkableApi {
     /** completely clear the cache */
     clearCache(): void;
 }
-type AuthedFetch = (method: RequestMethod, url: string, init?: {
-    body?: string | Uint8Array;
-    headers?: Record<string, string>;
-}) => Promise<Response>;
-export declare class RawRemarkable implements RawRemarkableApi {
-    #private;
-    constructor(authedFetch: AuthedFetch, cache: Map<string, string | null>, rawHost: string, uploadHost: string);
-    /** make an authorized request to remarkable */
-    getRootHash(): Promise<[string, number, SchemaVersion]>;
-    getHash(fileName: string, hash: string): Promise<Uint8Array>;
-    getText(fileName: string, hash: string): Promise<string>;
-    getEntries(fileName: string, hash: string): Promise<Entries>;
-    getContent(fileName: string, hash: string): Promise<Content>;
-    getMetadata(fileName: string, hash: string): Promise<Metadata>;
-    getRm(fileName: string, hash: string): Promise<RmPage>;
-    putRm(fileName: string, page: RmPageV5): Promise<[RawEntry, Promise<void>]>;
-    putRootHash(hash: string, generation: number, broadcast?: boolean): Promise<[string, number]>;
-    putFile(fileName: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
-    putText(fileName: string, text: string): Promise<[RawEntry, Promise<void>]>;
-    putContent(fileName: string, content: Content): Promise<[RawEntry, Promise<void>]>;
-    putMetadata(fileName: string, metadata: Metadata): Promise<[RawEntry, Promise<void>]>;
-    putEntries(id: string, entries: readonly RawEntry[], schemaVersion: SchemaVersion): Promise<[RawEntry, Promise<void>]>;
-    uploadFile(visibleName: string, bytes: Uint8Array, mime: UploadMimeType): Promise<SimpleEntry>;
-    dumpCache(): string;
-    clearCache(): void;
-}
-export {};
+export type { RawRemarkable as RawRemarkableApi };

package/dist/raw.js

@@ -233,7 +233,7 @@ const rootHash = z
     schemaVersion: z.number().int().nonnegative(),
 })
     .passthrough();
-const nativeSimpleEntry = z
+const nativeItemRef = z
     .object({
     docID: z.string(),
     hash: z.string(),
@@ -267,6 +267,65 @@ function parseRawEntryLine(line) {
         throw new Error(`line '${line}' was not formatted correctly`);
     }
 }
+/**
+ * access to the low-level reMarkable api
+ *
+ * This class gives more granualar access to the reMarkable cloud, but is more
+ * dangerous.
+ *
+ * ## Overview
+ *
+ * reMarkable uses an immutable file system, where each file is referenced by
+ * the 32 byte sha256 hash of its contents. Each file also has an id used to
+ * keep track of updates, so to "update" a file, you upload a new file, and
+ * change the hash associated with it's id.
+ *
+ * Each "item" (a document or a collection) is actually a list of files.
+ * The whole reMarkable state is then a list of these lists. Finally, the hash
+ * of that list is called the rootHash. To update anything, you have to update
+ * the root hash to point to a new list of updated items.
+ *
+ * This can be dangerous, as corrupting the root hash can destroy all of your
+ * files. It is therefore highly recommended to save your current root hash
+ * ({@link getRootHash | `getRootHash`}) before using this api to attempt file
+ * writes, so you can recover a previous "snapshot" should anything go wrong.
+ *
+ * ## Items
+ *
+ * Each item is a collection of individual files. Using
+ * {@link getEntries | `getEntries`} on the root hash will give you a list
+ * entries that correspond to items. Using `getEntries` on any of those items
+ * will get you the files that make up that item.
+ *
+ * The documented files are:
+ * - `<docid>.pdf` - a raw pdf document
+ * - `<docid>.epub` - a raw epub document
+ * - `<docid>.content` - a json file roughly describing document properties (see {@link DocumentContent | `DocumentContent`})
+ * - `<docid>.metadata` - metadata about the document (see {@link Metadata | `Metadata`})
+ * - `<docid>.pagedata` - a text file where each line is the template of that page
+ * - `<docid>/<pageid>.rm` - [speculative] raw remarkable vectors, text, etc
+ * - `<docid>/<pageid>-metadata.json` - [speculative] metadata about the individual page
+ * - `<docid>.highlights/<pageid>.json` - [speculative] highlights on the page
+ *
+ * Some items will have both a `.pdf` and `.epub` file, likely due to preparing
+ * for export. Collections only have `.content` and `.metadata` files, with
+ * `.content` only containing tags.
+ *
+ * ## Caching
+ *
+ * Since everything is tied to the hash of it's contents, we can agressively
+ * cache results. We assume that text contents are "small" and so fully cache
+ * them, where as binary files we treat as large and only store that we know
+ * they exist to prevent future writes.
+ *
+ * By default, this only persists as long as the api instance is alive. However,
+ * for performance reasons, you should call {@link dumpCache | `dumpCache`} to
+ * persist the cache between sessions.
+ *
+ * @remarks
+ *
+ * Generally all hashes are 64 character hex strings, and all ids are uuid4.
+ */
 export class RawRemarkable {
     #authedFetch;
     #rawHost;
@@ -288,6 +347,14 @@ export class RawRemarkable {
         this.#uploadHost = uploadHost;
     }
     /** make an authorized request to remarkable */
+    /**
+     * gets the root hash and the current generation
+     *
+     * When calling `putRootHash`, you should pass the generation you got from
+     * this call. That way you tell reMarkable you're updating the previous state.
+     *
+     * @returns the root hash and the current generation
+     */
     async getRootHash() {
         const res = await this.#authedFetch("GET", `${this.#rawHost}/sync/v4/root`);
         const raw = await res.text();
@@ -312,7 +379,17 @@ export class RawRemarkable {
         const raw = await resp.arrayBuffer();
         return new Uint8Array(raw);
     }
-    async getHash(fileName, hash) {
+    /**
+     * get the raw binary data associated with a hash
+     *
+     * @param ref - a reference to the stored file. Its `id` is the logical file
+     *   name (`<id>.<ext>` for files, or `<id>.docSchema` / `"root.docSchema"`
+     *   for entry indexes), which reMarkable validates against the rm-filename
+     *   header. Sub-entries from {@link getEntries | `getEntries`} can be passed
+     *   directly.
+     * @returns the data
+     */
+    async getHash({ id: fileName, hash }) {
         const cached = this.#cache.get(hash);
         if (cached != null) {
             const enc = new TextEncoder();
@@ -328,7 +405,16 @@ export class RawRemarkable {
             return res;
         }
     }
-    async getText(fileName, hash) {
+    /**
+     * get raw text data associated with a hash
+     *
+     * We assume text data are small, and so cache the entire text. If you want to
+     * avoid this, use {@link getHash | `getHash`} combined with a TextDecoder.
+     *
+     * @param ref - a reference to the stored file (see {@link getHash})
+     * @returns the text
+     */
+    async getText({ id: fileName, hash }) {
         const cached = this.#cache.get(hash);
         if (cached != null) {
             return cached;
@@ -342,8 +428,18 @@ export class RawRemarkable {
             return res;
         }
     }
-    async getEntries(fileName, hash) {
-        const rawFile = await this.getText(fileName, hash);
+    /**
+     * get the entries associated with a list hash
+     *
+     * A list hash is the root hash, or any hash with the type 80000000. NOTE
+     * these are hashed differently than files.
+     *
+     * @param ref - a reference whose `id` is `"root.docSchema"` for the root, or
+     *   `"<id>.docSchema"` for a sub-document's entry index
+     * @returns the entries
+     */
+    async getEntries(ref) {
+        const rawFile = await this.getText(ref);
         const [version, ...rest] = rawFile.slice(0, -1).split("\n");
         if (version === "3") {
             return { entries: rest.map(parseRawEntryLine) };
@@ -371,20 +467,50 @@ export class RawRemarkable {
             throw new Error(`schema version ${version} not supported`);
         }
     }
-    async getContent(fileName, hash) {
-        const raw = await this.getText(fileName, hash);
+    /**
+     * get the parsed and validated `Content` of a content hash
+     *
+     * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
+     * validation
+     *
+     * @param ref - a reference to the stored file, typically `"<id>.content"`
+     * @returns the content
+     */
+    async getContent(ref) {
+        const raw = await this.getText(ref);
         const loaded = JSON.parse(raw);
         return content.parse(loaded);
     }
-    async getMetadata(fileName, hash) {
-        const raw = await this.getText(fileName, hash);
+    /**
+     * get the parsed and validated `Metadata` of a metadata hash
+     *
+     * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
+     * validation
+     *
+     * @param ref - a reference to the stored file, typically `"<id>.metadata"`
+     * @returns the metadata
+     */
+    async getMetadata(ref) {
+        const raw = await this.getText(ref);
         const loaded = JSON.parse(raw);
         return metadata.parse(loaded);
     }
-    async getRm(fileName, hash) {
-        const bytes = await this.getHash(fileName, hash);
+    /**
+     * get the parsed reMarkable lines (`.rm`) drawing of a page hash
+     *
+     * @param ref - a reference to the stored file, typically `"<id>/<pageid>.rm"`
+     * @returns the parsed page
+     */
+    async getRm(ref) {
+        const bytes = await this.getHash(ref);
         return parseRm(bytes);
     }
+    /**
+     * the same as {@link putFile | `putFile`} but rendering an `RmPage` to `.rm`
+     * bytes
+     *
+     * Only version 3 and 5 pages can be rendered; version 6 pages are read-only.
+     */
     async putRm(fileName, page) {
         if (!fileName.endsWith(".rm")) {
             throw new Error(`fileName ${fileName} did not end with '.rm'`);
@@ -393,6 +519,25 @@ export class RawRemarkable {
             return await this.putFile(fileName, serializeRm(page));
         }
     }
+    /**
+     * update the current root hash
+     *
+     * This will fail if generation doesn't match the current server generation.
+     * This ensures that you are updating what you expect. IF you get a
+     * {@link GenerationError | `GenerationError`}, that indicates that the server
+     * was updated after you last got the generation. You should call
+     * {@link getRootHash | `getRootHash`} and then recompute the changes you want
+     * from the new root hash. If you ignore the update hash value and just call
+     * `putRootHash` again, you will overwrite the changes made by the other
+     * update.
+     *
+     * @param hash - the new root hash
+     * @param generation - the generation of the current root hash
+     * @param broadcast - [unknown] an option in the request
+     *
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns the new root hash and the new generation
+     */
     async putRootHash(hash, generation, broadcast = true) {
         if (!Number.isSafeInteger(generation)) {
             throw new Error(`generation ${generation} was not a safe integer`);
@@ -437,6 +582,20 @@ export class RawRemarkable {
             }
         }
     }
+    /**
+     * put a raw onto the server
+     *
+     * This returns the new expeced entry of the file you uploaded, and a promise
+     * to finish the upload successful. By splitting these two operations you can
+     * start using the uploaded entry while file finishes uploading.
+     *
+     * NOTE: This won't update the state of the reMarkable until this entry is
+     * incorporated into the root hash.
+     *
+     * @param fileName - the file name to upload (e.g. `<id>.pdf`)
+     * @param bytes - the bytes to upload
+     * @returns the new entry and a promise to finish the upload
+     */
     async putFile(fileName, bytes) {
         const hash = await digest(bytes);
         const res = {
@@ -448,6 +607,7 @@ export class RawRemarkable {
         };
         return [res, this.#putFile(fileName, hash, bytes)];
     }
+    /** the same as {@link putFile | `putFile`} but with caching for text */
     async putText(fileName, text) {
         const enc = new TextEncoder();
         const bytes = enc.encode(text);
@@ -460,6 +620,7 @@ export class RawRemarkable {
             }),
         ];
     }
+    /** the same as {@link putText | `putText`} but with extra validation for Content */
     async putContent(fileName, content) {
         if (!fileName.endsWith(".content")) {
             throw new Error(`fileName ${fileName} did not end with '.content'`);
@@ -468,6 +629,7 @@ export class RawRemarkable {
             return await this.putText(fileName, JSON.stringify(content));
         }
     }
+    /** the same as {@link putText | `putText`} but with extra validation for Metadata */
     async putMetadata(fileName, metadata) {
         if (!fileName.endsWith(".metadata")) {
             throw new Error(`fileName ${fileName} did not end with '.metadata'`);
@@ -476,6 +638,29 @@ export class RawRemarkable {
             return await this.putText(fileName, JSON.stringify(metadata));
         }
     }
+    /**
+     * put a set of entries to make an entry list file
+     *
+     * To fully upload an item:
+     * 1. upload all the constituent files and metadata
+     * 2. call this with all of the entries
+     * 3. append this entry to the root entry and call this again to update this root list
+     * 4. put the new root hash
+     *
+     * NOTE: reMarkable currently rejects newly written schema 3 root indexes
+     * with a 400 "Software must be updated" error, even for accounts that still
+     * report schema 3, so the root list should always be written as schema 4. A
+     * warning is logged if a schema 3 root index is written.
+     *
+     * @param id - the id of the list to upload - this should be the item id if
+     *   uploading an item list, or "root" if uploading a new root list. Note the
+     *   asymmetry with {@link getEntries | `getEntries`}: `getEntries` takes the
+     *   full `"<id>.docSchema"` file name, whereas `putEntries` takes the bare id
+     *   and appends `.docSchema` (and special-cases `"root"`) itself.
+     * @param entries - the entries to upload
+     *
+     * @returns the new list entry and a promise to finish the upload
+     */
     async putEntries(id, entries, schemaVersion) {
         if (id === "root" && schemaVersion === 3) {
             console.warn('writing a schema 3 root index, which reMarkable rejects with a 400 "Software must be updated" error; write the root index with schema version 4 instead');
@@ -520,6 +705,19 @@ export class RawRemarkable {
         };
         return [res, this.#putFile(`${id}.docSchema`, hash, entryBuff)];
     }
+    /**
+     * upload a file to the reMarkable cloud using the simple api
+     *
+     * This api is the same as used by the native reMarkable extension and works
+     * even if the backend schema version is version 4. Setting mime to "folder"
+     * allows folder creation.
+     *
+     * @param visibleName - the name of the file as it should appear on the reMarkable
+     * @param bytes - the bytes of the file to upload
+     * @param mime - the mime type of the file to upload
+  
+     * @returns a simple entry with the id and hash of the uploaded file
+     */
     async uploadFile(visibleName, bytes, mime) {
         const enc = new TextEncoder();
         const meta = enc
@@ -534,12 +732,18 @@ export class RawRemarkable {
             },
         });
         const loaded = (await resp.json());
-        const { docID, hash } = nativeSimpleEntry.parse(loaded);
+        const { docID, hash } = nativeItemRef.parse(loaded);
         return { id: docID, hash };
     }
+    /**
+     * dump the current cache to a string to preserve between session
+     *
+     * @returns a serialized version of the cache to pass to a new api instance
+     */
     dumpCache() {
         return JSON.stringify(Object.fromEntries(this.#cache));
     }
+    /** completely clear the cache */
     clearCache() {
         this.#cache.clear();
     }