rmapi-js 11.1.2 → 12.0.0

package/dist/raw.d.ts

@@ -1,14 +1,43 @@
+import { type RmPageV5 } from "./rm5.js";
+import { type RmScene } from "./rm6.js";
+/**
+ * a parsed reMarkable `.rm` page
+ *
+ * A discriminated union on `version`: versions 3/5 parse to the flat, renderable
+ * {@link RmPageV5 | `RmPageV5`}; version 6 parses to the richer
+ * {@link RmScene | `RmScene`} CRDT scene (`version: 6`).
+ */
+export type RmPage = RmPageV5 | RmScene;
+/**
+ * parse the bytes of a reMarkable `.rm` page file
+ *
+ * Dispatches on the header version: versions 3/5 parse to a flat
+ * {@link RmPageV5 | `RmPageV5`}; version 6 parses to an
+ * {@link RmScene | `RmScene`}. Throws for an unknown version or malformed data.
+ *
+ * @param data - the raw `.rm` file bytes
+ * @returns the parsed page
+ */
+export declare function parseRm(data: Uint8Array): RmPage;
 /** request types */
 export type RequestMethod = "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
 /** the supported upload mime types */
 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;
 }
 /**
@@ -19,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 */
@@ -120,6 +145,14 @@ export interface CPagePage {
     verticalScroll?: CPageNumberValue;
     /** [unknown] */
     deleted?: CPageNumberValue;
+    /**
+     * a per-page last-modified epoch-milliseconds timestamp
+     *
+     * The misspelling is reMarkable's own: the firmware writes this key as
+     * `modifed`. Unlike the sibling fields it is a bare string, not a
+     * timestamped value.
+     */
+    modifed?: string;
 }
 /** [unknown] */
 export interface CPageUUID {
@@ -379,6 +412,12 @@ export interface Metadata {
     /** the visible name of the item, what it's called on the reMarkable */
     visibleName: string;
 }
+/** 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
  *
@@ -438,7 +477,10 @@ export interface 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
      *
@@ -451,58 +493,69 @@ 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 ref - a reference to the stored file, typically `"<id>/<pageid>.rm"`
+     * @returns the parsed page
+     */
+    getRm(ref: ItemRef): Promise<RmPage>;
+    /**
+     * 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>]>;
     /**
      * update the current root hash
      *
@@ -533,17 +586,17 @@ export interface RawRemarkableApi {
      * NOTE: This won't update the state of the reMarkable until this entry is
      * incorporated into the root hash.
      *
-     * @param id - the id of the file to upload
+     * @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
      */
-    putFile(id: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
+    putFile(fileName: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
     /** the same as {@link putFile | `putFile`} but with caching for text */
-    putText(id: 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(id: string, content: Content): Promise<[RawEntry, Promise<void>]>;
+    putContent(fileName: string, content: Content): Promise<[RawEntry, Promise<void>]>;
     /** the same as {@link putText | `putText`} but with extra validation for Metadata */
-    putMetadata(id: string, metadata: Metadata): Promise<[RawEntry, Promise<void>]>;
+    putMetadata(fileName: string, metadata: Metadata): Promise<[RawEntry, Promise<void>]>;
     /**
      * put a set of entries to make an entry list file
      *
@@ -559,7 +612,10 @@ export interface RawRemarkableApi {
      * 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.
+     *   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
@@ -575,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
      *
@@ -588,28 +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>;
-    putRootHash(hash: string, generation: number, broadcast?: boolean): Promise<[string, number]>;
-    putFile(id: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
-    putText(id: string, text: string): Promise<[RawEntry, Promise<void>]>;
-    putContent(id: string, content: Content): Promise<[RawEntry, Promise<void>]>;
-    putMetadata(id: 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 };