rmapi-js 12.0.2 → 13.0.0

package/dist/lru.d.ts

@@ -1,8 +1,8 @@
-export declare class LruCache extends Map<string, string | null> {
+export declare class LruCache extends Map<string, Uint8Array | null> {
     #private;
-    constructor(maxSize: number, entries?: Iterable<[string, string | null]>);
-    get(key: string): string | null | undefined;
-    set(key: string, value: string | null): this;
+    constructor(maxSize: number, entries?: Iterable<[string, Uint8Array | null]>);
+    get(key: string): Uint8Array | null | undefined;
+    set(key: string, value: Uint8Array | null): this;
     delete(key: string): boolean;
     clear(): void;
 }

package/dist/lru.js

@@ -23,10 +23,10 @@ export class LruCache extends Map {
             this.#currentSize += key.length; // adding a new key
         }
         else if (existing !== null) {
-            this.#currentSize -= existing.length; // removing old value
+            this.#currentSize -= existing.byteLength; // removing old value
         }
         if (value !== null) {
-            this.#currentSize += value.length;
+            this.#currentSize += value.byteLength;
         }
         // delete existing value
         super.delete(key);
@@ -38,7 +38,7 @@ export class LruCache extends Map {
             super.delete(oldestKey);
             this.#currentSize -= oldestKey.length;
             if (oldestValue !== null) {
-                this.#currentSize -= oldestValue.length;
+                this.#currentSize -= oldestValue.byteLength;
             }
         }
         // finally insert new key and return
@@ -52,7 +52,7 @@ export class LruCache extends Map {
         }
         super.delete(key);
         if (value !== null) {
-            this.#currentSize -= value.length;
+            this.#currentSize -= value.byteLength;
         }
         this.#currentSize -= key.length;
         return true;

package/dist/raw.d.ts

@@ -1,5 +1,17 @@
+import "core-js/modules/es.async-disposable-stack.constructor.js";
+import "core-js/modules/es.symbol.async-dispose.js";
+import "core-js/modules/es.uint8-array.from-base64.js";
+import "core-js/modules/es.uint8-array.from-hex.js";
+import "core-js/modules/es.uint8-array.to-base64.js";
+import "core-js/modules/es.uint8-array.to-hex.js";
 import { type RmPageV5 } from "./rm5.js";
 import { type RmScene } from "./rm6.js";
+/** the dump format version; absent means the original text-only format */
+export declare const CACHE_VERSION = 2;
+/** marks a dumped cache entry stored as utf-8 text */
+export declare const TEXT_PREFIX = "t";
+/** marks a dumped cache entry stored as base64 */
+export declare const BYTES_PREFIX = "b";
 /**
  * a parsed reMarkable `.rm` page
  *
@@ -19,6 +31,17 @@ export type RmPage = RmPageV5 | RmScene;
  * @returns the parsed page
  */
 export declare function parseRm(data: Uint8Array): RmPage;
+/**
+ * serialize a parsed reMarkable `.rm` page back to bytes
+ *
+ * The inverse of {@link parseRm | `parseRm`}: versions 3 and 5 render from a
+ * flat {@link RmPageV5 | `RmPageV5`}, version 6 from an
+ * {@link RmScene | `RmScene`}.
+ *
+ * @param page - the page to render
+ * @returns the `.rm` file bytes
+ */
+export declare function serializeRm(page: RmPage): Uint8Array;
 /** request types */
 export type RequestMethod = "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
 /** the supported upload mime types */
@@ -56,8 +79,38 @@ export interface RawEntry extends ItemRef {
     /** the total size of everything in the collection */
     size: number;
 }
+/**
+ * an entry whose upload is still in flight
+ *
+ * The hash is a digest of the bytes, so the entry describes the upload before
+ * the server has it — you can splice it into a parent index immediately.
+ * Disposing waits for the upload to land, and throws if it failed, so scoping
+ * it keeps a root hash from being written against a file that never arrived:
+ *
+ * ```ts
+ * let hash;
+ * {
+ *   await using entry = await raw.putFile(`${id}.pdf`, bytes);
+ *   hash = entry.hash;
+ * }
+ * await raw.putRootHash(hash, generation);
+ * ```
+ *
+ * Where the number of uploads isn't known until runtime, collect them in an
+ * `AsyncDisposableStack` with `stack.use(entry)`; the scope holding the stack
+ * waits for all of them.
+ */
+export interface PendingEntry extends RawEntry, AsyncDisposable {
+}
 /** the type of files reMarkable supports */
 export type FileType = "epub" | "pdf" | "notebook";
+/**
+ * the kind of entry this is
+ *
+ * DocumentType is an epub, pdf, or notebook, CollectionType is a folder, and
+ * TemplateType is a template.
+ */
+export type EntryType = "DocumentType" | "CollectionType" | "TemplateType";
 /**
  * a parsed entries file
  *
@@ -368,6 +421,44 @@ export interface TemplateContent {
 }
 /** content metadata for any item */
 export type Content = CollectionContent | LegacyCollectionContent | DocumentContent | LegacyDocumentContent | TemplateContent;
+/** a rectangle with its origin at the top left of the source document page */
+export interface HighlightRect {
+    /** the distance from the left edge of the page */
+    x: number;
+    /** the distance from the top edge of the page */
+    y: number;
+    /** the width */
+    width: number;
+    /** the height */
+    height: number;
+}
+/**
+ * a single text-highlight fragment on a pdf or epub page
+ *
+ * reMarkable splits one highlighted passage into a fragment per line it spans.
+ */
+export interface Highlight {
+    /** the highlighted text */
+    text: string;
+    /** [speculative] an index into the highlight palette, not the pen palette */
+    color: number;
+    /** the character offset of the highlight within the page's text */
+    start: number;
+    /** the number of characters highlighted */
+    length: number;
+    /** the rectangles the highlight spans, one per line */
+    rects: HighlightRect[];
+}
+/** a single layer on a page */
+export interface PageLayer {
+    /** the layer's display name */
+    name: string;
+}
+/** a page's layer metadata, from `<docid>/<pageid>-metadata.json` */
+export interface PageMetadata {
+    /** the page's layers, in order */
+    layers: PageLayer[];
+}
 /**
  * item level metadata
  *
@@ -399,13 +490,8 @@ export interface Metadata {
     pinned: boolean;
     /** [unknown] */
     synced?: boolean | null;
-    /**
-     * the type of item this corresponds to
-     *
-     * DocumentType is a document, an epub, pdf, or notebook, CollectionType is a
-     * folder.
-     */
-    type: "DocumentType" | "CollectionType" | "TemplateType";
+    /** the type of item this corresponds to */
+    type: EntryType;
     /** whether this is this a newly-installed template */
     new?: boolean;
     /**
@@ -461,9 +547,10 @@ type AuthedFetch = (method: RequestMethod, url: string, init?: {
  * - `<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>.template` - a template attached to the item (see {@link TemplateContent | `TemplateContent`})
  * - `<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
+ * - `<docid>/<pageid>-metadata.json` - page layer metadata (see {@link PageMetadata | `PageMetadata`})
+ * - `<docid>.highlights/<pageid>.json` - text highlights on the page (see {@link Highlight | `Highlight`})
  *
  * Some items will have both a `.pdf` and `.epub` file, likely due to preparing
  * for export. Collections only have `.content` and `.metadata` files, with
@@ -472,9 +559,12 @@ type AuthedFetch = (method: RequestMethod, url: string, init?: {
  * ## 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.
+ * cache results. Anything up to `maxCachedBytes` is kept as the bytes that were
+ * transferred; anything larger records only that the hash exists, which is
+ * enough to skip writing it again.
+ *
+ * A dump is tied to the account it came from, since a known hash is taken as
+ * proof the server already holds that file. Don't share one between accounts.
  *
  * By default, this only persists as long as the api instance is alive. However,
  * for performance reasons, you should call {@link dumpCache | `dumpCache`} to
@@ -486,8 +576,7 @@ type AuthedFetch = (method: RequestMethod, url: string, init?: {
  */
 export declare class RawRemarkable {
     #private;
-    constructor(authedFetch: AuthedFetch, cache: Map<string, string | null>, rawHost: string, uploadHost: string);
-    /** make an authorized request to remarkable */
+    constructor(authedFetch: AuthedFetch, cache: Map<string, Uint8Array | null>, rawHost: string, uploadHost: string, maxCachedBytes: number);
     /**
      * gets the root hash and the current generation
      *
@@ -517,18 +606,18 @@ export declare class RawRemarkable {
      * @param ref - a reference to the stored file (see {@link getHash})
      * @returns the text
      */
-    getText({ id: fileName, hash }: ItemRef): Promise<string>;
+    getText(ref: 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 ref - a reference whose `id` is `"root.docSchema"` for the root, or
-     *   `"<id>.docSchema"` for a sub-document's entry index
+     * @param ref - a reference whose `id` is the bare document id, or `"root"`
+     *   for the root index
      * @returns the entries
      */
-    getEntries(ref: ItemRef): Promise<Entries>;
+    getEntries({ id, hash }: ItemRef): Promise<Entries>;
     /**
      * get the parsed and validated `Content` of a content hash
      *
@@ -556,13 +645,34 @@ export declare class RawRemarkable {
      * @returns the parsed page
      */
     getRm(ref: ItemRef): Promise<RmPage>;
+    /**
+     * get the parsed text highlights of a page
+     *
+     * @param ref - a reference to a `<docid>.highlights/<pageid>.json` file
+     * @returns the page's highlights; [speculative] each inner array groups the
+     *     fragments of one highlighted passage
+     */
+    getHighlights(ref: ItemRef): Promise<Highlight[][]>;
+    /**
+     * get a template stored as a `<docid>.template` sidecar file
+     *
+     * @param ref - a reference to a `<docid>.template` file
+     * @returns the template content
+     */
+    getTemplate(ref: ItemRef): Promise<TemplateContent>;
+    /**
+     * get the parsed layer metadata of a page
+     *
+     * @param ref - a reference to a `<docid>/<pageid>-metadata.json` file
+     * @returns the page metadata
+     */
+    getPageMetadata(ref: ItemRef): Promise<PageMetadata>;
     /**
      * 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.
      */
-    putRm(fileName: string, page: RmPageV5): Promise<[RawEntry, Promise<void>]>;
+    putRm(fileName: string, page: RmPage): Promise<PendingEntry>;
     /**
      * update the current root hash
      *
@@ -584,26 +694,54 @@ export declare class RawRemarkable {
      */
     putRootHash(hash: string, generation: number, broadcast?: boolean): Promise<[string, number]>;
     /**
-     * put a raw onto the server
+     * put a raw file 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.
+     * The returned entry is usable immediately, while the upload is still in
+     * flight; disposing it waits for the upload to finish. See
+     * {@link PendingEntry | `PendingEntry`}.
      *
      * 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
+     * @returns the new entry, pending its upload
+     */
+    putFile(fileName: string, bytes: Uint8Array): Promise<PendingEntry>;
+    /** the same as {@link putFile | `putFile`} but with extra validation for Content */
+    putContent(fileName: string, content: Content): Promise<PendingEntry>;
+    /**
+     * the same as {@link putFile | `putFile`} but for a `.pagedata` file
+     *
+     * @param fileName - the file to write, of the form `<docid>.pagedata`
+     * @param templates - one template name per page, in page order
+     */
+    putPagedata(fileName: string, templates: readonly string[]): Promise<PendingEntry>;
+    /**
+     * the same as {@link putFile | `putFile`} but with extra validation for page
+     * layer metadata
+     *
+     * @param fileName - the file to write, of the form
+     *     `<docid>/<pageid>-metadata.json`
+     * @param meta - the page's layer metadata
+     */
+    putPageMetadata(fileName: string, meta: PageMetadata): Promise<PendingEntry>;
+    /** the same as {@link putFile | `putFile`} but with extra validation for a template sidecar */
+    putTemplate(fileName: string, template: TemplateContent): Promise<PendingEntry>;
+    /** the same as {@link putFile | `putFile`} but with extra validation for Metadata */
+    putMetadata(fileName: string, metadata: Metadata): Promise<PendingEntry>;
+    /**
+     * the same as {@link putFile | `putFile`} but with extra validation for
+     * highlights
+     *
+     * Rewraps the array in the file's `highlights` envelope, which
+     * {@link getHighlights | `getHighlights`} strips.
+     *
+     * @param fileName - the file to write, of the form
+     *     `<docid>.highlights/<pageid>.json`
+     * @param highlights - the page's highlights
      */
-    putFile(fileName: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
-    /** the same as {@link putFile | `putFile`} but with caching for text */
-    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 */
-    putMetadata(fileName: string, metadata: Metadata): Promise<[RawEntry, Promise<void>]>;
+    putHighlights(fileName: string, highlights: readonly Highlight[][]): Promise<PendingEntry>;
     /**
      * put a set of entries to make an entry list file
      *
@@ -621,13 +759,11 @@ export declare class RawRemarkable {
      * @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
+     * @returns the new list entry, pending its upload
      */
-    putEntries(id: string, entries: readonly RawEntry[], schemaVersion: SchemaVersion): Promise<[RawEntry, Promise<void>]>;
+    putEntries(id: string, entries: readonly RawEntry[], schemaVersion: SchemaVersion): Promise<PendingEntry>;
     /**
      * upload a file to the reMarkable cloud using the simple api
      *