rmapi-js 6.0.0 → 8.0.0

package/dist/index.d.ts

@@ -7,6 +7,62 @@ export interface Tag {
     /** the timestamp when this tag was added */
     timestamp: number;
 }
+/** a tag for individual pages */
+export interface PageTag extends Tag {
+    /** the id of the page this is on */
+    pageId: string;
+}
+/** the type of files reMarkable supports */
+export type FileType = "epub" | "pdf" | "notebook";
+/** all supported document orientations */
+export type Orientation = "portrait" | "landscape";
+/** all supported text alignments */
+export type TextAlignment = "justify" | "left";
+/** types of zoom modes for documents, applies primarily to pdf files */
+export type ZoomMode = "bestFit" | "customFit" | "fitToHeight" | "fitToWidth";
+/**
+ * types of background filter
+ *
+ * off has no background filter, best for images, full page applies the high
+ * contrast filter to the entire page. If this is omitted, reMarkable will try
+ * to apply the filter only to text areas.
+ */
+export type BackgroundFilter = "off" | "fullpage";
+/**
+ * the low-level entry corresponding to a collection of files
+ *
+ * A collection could be for the root collection, or for an individual document,
+ * which is often a collection of files. If an entry represents a collection of
+ * files, the high level entry will have the same hash and id as the low-level
+ * entry for that collection.
+ */
+export interface RawListEntry {
+    /** collection type (80000000) */
+    type: 80000000;
+    /** 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 */
+    size: number;
+}
+/** the low-level entry for a single file */
+export interface RawFileEntry {
+    /** file type (0) */
+    type: 0;
+    /** the hash of the file this points to */
+    hash: string;
+    /** the unique id of the file */
+    id: string;
+    /** the number of subfiles, always zero */
+    subfiles: 0;
+    /** the size of the file in bytes */
+    size: number;
+}
+/** a low-level stored entry */
+export type RawEntry = RawListEntry | RawFileEntry;
 /** common properties shared by collections and documents */
 export interface EntryCommon {
     /** the document id, a uuid4 */
@@ -45,10 +101,10 @@ export interface DocumentType extends EntryCommon {
 }
 /** a remarkable entry for cloud items */
 export type Entry = CollectionEntry | DocumentType;
-/** an simple entry produced by the upload api */
-export interface UploadEntry {
+/** an simple entry without any extra information */
+export interface SimpleEntry {
     /** the document id */
-    docID: string;
+    id: string;
     /** the document hash */
     hash: string;
 }
@@ -62,35 +118,17 @@ export interface HashesEntry {
     /** the mapping from old to new hashes */
     hashes: Record<string, string>;
 }
-/** stripped down version of RequestInit */
-export interface RequestInitLike {
-    /** request method */
-    readonly method?: RequestMethod | undefined;
-    /** request headers */
-    readonly headers?: Record<string, string>;
-    /** request body */
-    readonly body?: ArrayBuffer | string;
-}
-/** stripped down version of Headers */
-export interface HeadersLike {
-    /** get a specific header value */
-    get(key: string): string | null;
-}
-/** stripped down version of Response */
-export interface ResponseLike {
-    /** true if request was successful */
-    ok: boolean;
-    /** http status */
-    status: number;
-    /** text associated with status */
-    statusText: string;
-    /** get response body as text */
-    text(): Promise<string>;
-}
-/** stripped down version of fetch */
-export interface FetchLike {
-    /** the rough interface to fetch */
-    (url: string, options?: RequestInitLike): Promise<ResponseLike>;
+/** An error that gets thrown when the backend while trying to update
+ *
+ * IF you encounter this error, you likely just need to try th request again. If
+ * you're trying to do several high-level `put` operations simultaneously,
+ * you'll likely encounter this error. You should either try to do them
+ * serially, or call the low level api directly to do one generation update.
+ *
+ * @see {@link RawRemarkableApi | `RawRemarkableApi`}
+ */
+export declare class GenerationError extends Error {
+    constructor();
 }
 /** an error that results from a failed request */
 export declare class ResponseError extends Error {
@@ -108,6 +146,12 @@ export declare class ValidationError extends Error {
     readonly regex: RegExp;
     constructor(field: string, regex: RegExp, message: string);
 }
+/** an error that results while supplying a hash not found in the entries of the root hash */
+export declare class HashNotFoundError extends Error {
+    /** the hash that couldn't be found */
+    readonly hash: string;
+    constructor(hash: string);
+}
 /** options for registering with the api */
 export interface RegisterOptions {
     /**
@@ -123,8 +167,6 @@ export interface RegisterOptions {
     uuid?: string;
     /** The host to use for authorization requests */
     authHost?: string;
-    /** a function for making fetch requests, see {@link RemarkableOptions.fetch} for more info */
-    fetch?: FetchLike;
 }
 /**
  * register a device and get the token needed to access the api
@@ -136,36 +178,618 @@ export interface RegisterOptions {
  * @param code - the eight letter code a user got from `https://my.remarkable.com/device/browser/connect`.
  * @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, fetch, }?: RegisterOptions): Promise<string>;
-/** options for getting responses */
-export interface GetOptions {
+export declare function register(code: string, { deviceDesc, uuid, authHost, }?: RegisterOptions): Promise<string>;
+/** options available when uploading a document */
+export interface UploadOptions {
+    /** an optional parent id to set when uploading */
+    parent?: string;
+}
+/** document metadata stored in {@link Content} */
+export interface DocumentMetadata {
+    /** a list of authors as a string */
+    authors?: string[];
+    /** the title as a string */
+    title?: string;
+    /** the publication date as an ISO date or timestamp */
+    publicationDate?: string;
+    /** the publisher */
+    publisher?: string;
+}
+/** [speculative] metadata stored about keyboard interactions */
+export interface KeyboardMetadata {
+    /** [unknown] */
+    count: number;
+    /** [unknown] */
+    timestamp: number;
+}
+/** a c-page value who's type is a string */
+export interface CPageStringValue {
+    /** a pseudo-timestamp of the form "1:1" or "1:2" */
+    timestamp: string;
+    /** the stored value */
+    value: string;
+}
+/** a c-page value who's type is a string */
+export interface CPageNumberValue {
+    /** a pseudo-timestamp of the form "1:1" or "1:2" */
+    timestamp: string;
+    /** the stored value */
+    value: number;
+}
+/** [speculative] information about an individual page */
+export interface CPagePage {
+    /** [speculative] the page id */
+    id: string;
+    /** [unknown] values are like "aa", "ab", "ba", etc. */
+    idx: CPageStringValue;
+    /** [unknown] */
+    redir?: CPageNumberValue;
+    /** [speculative] the template name of the page */
+    template?: CPageStringValue;
+    /** [unknown] the value is a timestamp */
+    scrollTime?: CPageStringValue;
+    /** [unknown] */
+    verticalScroll?: CPageNumberValue;
+    /** [unknown] */
+    deleted?: CPageNumberValue;
+}
+/** [unknown] */
+export interface CPageUUID {
+    /** [unknown] */
+    first: string;
+    /** [unknown] */
+    second: number;
+}
+/** [unknown] metadata about pages */
+export interface CPages {
+    /** [speculative] the last time the document was opened */
+    lastOpened: CPageStringValue;
+    /** [unknown] */
+    original: CPageNumberValue;
+    /** [speculative] information about individual pages */
+    pages: CPagePage[];
+    /** [unknown] */
+    uuids: CPageUUID[];
+}
+/** the content metadata for collections (folders) */
+export interface CollectionContent {
+    /** the tags for the collection */
+    tags?: Tag[];
+    /** collections don't have a file type */
+    fileType?: undefined;
+}
+/**
+ * content metadata, stored with the "content" extension
+ *
+ * This largely contains description of how to render the document, rather than
+ * metadata about it.
+ */
+export interface DocumentContent {
+    /**
+     * which page to use for the thumbnail
+     *
+     * -1 indicates the last visited page, whereas 0 is the first page.
+     */
+    coverPageNumber: number;
+    /** metadata about the author, publishers, etc. */
+    documentMetadata: DocumentMetadata;
+    /** It's not known what this field is for */
+    dummyDocument?: boolean;
+    /** the largely contains metadata about what pens were used and their settings */
+    extraMetadata: Record<string, string>;
+    /** the underlying file type of this document */
+    fileType: FileType;
+    /**
+     * the name of the font to use for text rendering
+     *
+     * The reMarkable supports five fonts by default: "Noto Sans", "Noto Sans UI",
+     * "EB Garamond", "Noto Mono", and "Noto Serif". You can also set the font to
+     * the empty string or omit it for the default.
+     */
+    fontName: string;
+    /** the format version, this should always be 1 */
+    formatVersion: number;
+    /** the last opened page, starts at zero */
+    lastOpenedPage?: number;
+    /**
+     * the line height
+     *
+     * The reMarkable uses three built-in line heights: 100, 150, 200, and
+     * uses -1 to indicate the default line height, but heights outside of these
+     * also work.
+     */
+    lineHeight: number;
     /**
-     * whether to verify the types of the response
+     * the document margin in pixels
      *
-     * Omitting will make the results always work, but they might nit return
-     * accurate types anymore.
+     * The reMarkable uses three built-in margins: 50, 125, 200, but other margins
+     * are possible. The reMarkable used to default to margins of 180.
      */
-    verify?: boolean | undefined;
+    margins: number;
+    /** the document orientation */
+    orientation: Orientation;
+    /** this specifies the number of pages, it's not clear how this is different than pageCount */
+    originalPageCount?: number;
+    /** the number of pages */
+    pageCount: number;
+    /** the page tags for the document */
+    pageTags?: PageTag[];
+    /** a list of the ids of each page in the document */
+    pages?: string[];
+    /** a mapping from page number to page id in pages */
+    redirectionPageMap?: number[];
+    /** ostensibly the size in bytes of the file, but this differs from other measurements */
+    sizeInBytes: string;
+    /** document tags for this document */
+    tags?: Tag[];
+    /** text alignment for this document */
+    textAlignment: TextAlignment;
+    /**
+     * the font size
+     *
+     * reMarkable uses six built-in text scales: 0.7, 0.8, 1, 1.2, 1.5, 2, but
+     * values outside of this range are valid.
+     */
+    textScale: number;
+    /** [speculative] the center of the zoom for zoomed in documents */
+    customZoomCenterX?: number;
+    /** [speculative] the center of the zoom for zoomed in documents */
+    customZoomCenterY?: number;
+    /** [speculative] the orientation */
+    customZoomOrientation?: Orientation;
+    /** [speculative] the zoom height for zoomed in pages */
+    customZoomPageHeight?: number;
+    /** [speculative] the zoom width for zoomed in pages */
+    customZoomPageWidth?: number;
+    /** [speculative] the scale for zoomed in pages */
+    customZoomScale?: number;
+    /** what zoom mode is set for the page */
+    zoomMode?: ZoomMode;
+    /** [speculative] a transform matrix, a. la. css matrix transform */
+    transform?: Record<`m${"1" | "2" | "3"}${"1" | "2" | "3"}`, number>;
+    /** [speculative] metadata about keyboard use */
+    keyboardMetadata?: KeyboardMetadata;
+    /** [speculative] various other page metadata */
+    cPages?: CPages;
+    /**
+     * setting for the adaptive contrast filter
+     *
+     * off has no background filter, best for images, full page applies the high
+     * contrast filter to the entire page. If this is omitted, reMarkable will try
+     * to apply the filter only to text areas.
+     */
+    viewBackgroundFilter?: BackgroundFilter;
 }
-export interface UploadOptions extends GetOptions {
-    /** an optional parent id to set when uploading */
+/** content metadata for any item */
+export type Content = CollectionContent | DocumentContent;
+/**
+ * item level metadata
+ *
+ * Stored with the extension "metadata".
+ */
+export interface Metadata {
+    /** creation time, a string of the epoch timestamp */
+    createdTime?: string;
+    /** [speculative] true if the item has been actually deleted */
+    deleted?: boolean;
+    /** the last modify time, the string of the epoch timestamp */
+    lastModified: string;
+    /** the last opened epoch timestamp, isn't defined for CollectionType */
+    lastOpened?: string;
+    /** the last page opened, isn't defined for CollectionType, starts at 0*/
+    lastOpenedPage?: number;
+    /** [speculative] true if the metadata has been modified */
+    metadatamodified?: boolean;
+    /** [speculative] true if the item has been modified */
+    modified?: boolean;
+    /**
+     * the id of the parent collection
+     *
+     * This is the empty string for root (no parent), "trash" if it's in the
+     * trash, or the id of the parent.
+     */
+    parent: string;
+    /** true of the item is starred */
+    pinned: boolean;
+    /** [unknown] */
+    synced?: boolean;
+    /**
+     * the type of item this corresponds to
+     *
+     * DocumentType is a document, an epub, pdf, or notebook, CollectionType is a
+     * folder.
+     */
+    type: "DocumentType" | "CollectionType";
+    /** [speculative] metadata version, always 0 */
+    version?: number;
+    /** the visible name of the item, what it's called on the reMarkable */
+    visibleName: string;
+}
+/**
+ * options for putting a file onto reMarkable
+ *
+ * This is a more customizable version of the options available when using the
+ * simpler upload api. This comes with the risk that is uses lower level apis,
+ * and therefore has more failure points.
+ *
+ * @see {@link Content | `Content`} and {@link Metadata | `Metadata`} for more
+ * information on what these fields correspond to
+ */
+export interface PutOptions {
+    /**
+     * the collection to put this in
+     *
+     * The empty string ("") (default) is the root, "trash" is in the trash,
+     * otherwise this should be the uuid of a collection item to place this in.
+     */
     parent?: string;
+    /** true to star the item */
+    pinned?: boolean;
+    /** 0 for first page, -1 for last visited */
+    coverPageNumber?: number;
+    /** document metadata authors */
+    authors?: string[];
+    /** document metadata tile, NOTE this is not visibleName */
+    title?: string;
+    /** the publication date, as an ISO date or timestamp */
+    publicationDate?: string;
+    /** the publisher */
+    publisher?: string;
+    /** extra metadata often in the form of pen choices */
+    extraMetadata?: Record<string, string>;
+    /** the font to use for rendering */
+    fontName?: string;
+    /** the line height to render */
+    lineHeight?: number;
+    /** the margins to render */
+    margins?: number;
+    /** the document orientation */
+    orientation?: Orientation;
+    /** the names of the tags to add */
+    tags?: string[];
+    /** the document text alignment */
+    textAlignment?: TextAlignment;
+    /** the text scale of the document */
+    textScale?: number;
+    /** the document zoom mode */
+    zoomMode?: ZoomMode;
+    /** the contrast filter setting */
+    viewBackgroundFilter?: BackgroundFilter;
+    /**
+     * whether to refresh current file structure before putting
+     *
+     * If you suspect that other changes have been made to the remarkable backend
+     * between the last put and now, setting this to true will avoid a
+     * {@link GenerationError | `GenerationError`}, but will cause an unnecessary
+     * GET request otherwise.
+     */
+    refresh?: boolean;
+}
+/**
+ * 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 interface RawRemarkableApi {
+    /**
+     * 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
+     */
+    getRootHash(): Promise<[string, number]>;
+    /**
+     * get the raw binary data associated with a hash
+     *
+     * @param hash - the hash to get the data for
+     * @returns the data
+     */
+    getHash(hash: string): 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 hash - the hash to get text for
+     * @returns the text
+     */
+    getText(hash: string): 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 hash - the hash to get entries for
+     * @returns the entries
+     */
+    getEntries(hash: string): Promise<RawEntry[]>;
+    /**
+     * get the parsed and validated `Content` of a content hash
+     *
+     * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
+     * validation
+  
+     * @param hash - the hash to get Content for
+     * @returns the content
+     */
+    getContent(hash: string): Promise<Content>;
+    /**
+     * get the parsed and validated `Metadata` of a metadata hash
+     *
+     * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
+     * validation
+  
+     * @param hash - the hash to get Metadata for
+     * @returns the metadata
+     */
+    getMetadata(hash: string): Promise<Metadata>;
+    /**
+     * 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
+     */
+    putRootHash(hash: string, generation: number, broadcast?: boolean): Promise<[string, number]>;
+    /**
+     * 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 id - the id of the file to upload
+     * @param bytes - the bytes to upload
+     * @returns the new entry and a promise to finish the upload
+     */
+    putFile(id: string, bytes: Uint8Array): Promise<[RawFileEntry, Promise<void>]>;
+    /** the same as {@link putFile | `putFile`} but with caching for text */
+    putText(id: string, content: string): Promise<[RawFileEntry, Promise<void>]>;
+    /** the same as {@link putText | `putText`} but with extra validation for Content */
+    putContent(id: string, content: Content): Promise<[RawFileEntry, Promise<void>]>;
+    /** the same as {@link putText | `putText`} but with extra validation for Metadata */
+    putMetadata(id: string, metadata: Metadata): Promise<[RawFileEntry, Promise<void>]>;
+    /**
+     * 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
+     *
+     * @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.
+     * @param entries - the entries to upload
+     * @returns the new list entry and a promise to finish the upload
+     */
+    putEntries(id: string, entries: RawEntry[]): Promise<[RawListEntry, Promise<void>]>;
+    /**
+     * 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(): string;
+    /** completely clear the cache */
+    clearCache(): void;
 }
 /**
  * the api for accessing remarkable functions
+ *
+ * There are roughly two types of functions.
+ * - high-level api functions that provide simple access with a single round
+ *   trip based on the web api
+ * - low-level wrapped functions that take more round trips, but provide more
+ *   control and may be faster since they can be cached.
+ *
+ * Most of these functions validate the return values so that typescript is
+ * accurate. However, sometimes those return values are more strict than the
+ * "true" underlying types. If this happens, please [submit a an
+ * issue](https://github.com/erikbrinkman/rmapi-js/issues). In the mean time,
+ * you should be able to use the low level api to work around any restrictive
+ * validation.
  */
 export interface RemarkableApi {
+    /** scoped access to the raw low-level api */
+    raw: RawRemarkableApi;
     /**
-     * list all files
+     * list all items
+     *
+     * Items include both collections and documents. Documents that are in folders
+     * will have their parent set to something other than "" or "trash", but
+     * everything will be returned by this function.
      *
      * @example
      * ```ts
-     * await api.listFiles();
+     * await api.listItems();
      * ```
+     *
+     * @remarks
+     * This is now backed by the low level api, and you may notice some
+     * performance degradation if not taking advantage of the cache.
+     *
+     * @param refresh - if true, refresh the root hash before listing
+     * @returns a list of all items with some metadata
+     */
+    listItems(refresh?: boolean): Promise<Entry[]>;
+    /**
+     * similar to {@link listItems | `listItems`} but backed by the low level api
+     *
+     * @param refresh - if true, refresh the root hash before listing
+     */
+    listIds(refresh?: boolean): Promise<SimpleEntry[]>;
+    /**
+     * get the content metadata from an item hash
+     *
+     * This takes the high level item hash, e.g. the hashes you get from
+     * {@link listItems | `listItems`} or {@link listIds | `listIds`}.
+     *
+     * @remarks
+     * If this fails validation and you still want to get the content, you can use
+     * the low-level api to get the raw text of the `.content` file in the
+     * `RawListEntry` for this hash.
+     *
+     * @param hash - the hash of the item to get content for
+     * @returns the content
      */
-    listFiles(ops?: GetOptions): Promise<Entry[]>;
+    getContent(hash: string): Promise<Content>;
+    /**
+     * get the metadata from an item hash
+     *
+     * This takes the high level item hash, e.g. the hashes you get from
+     * {@link listItems | `listItems`} or {@link listIds | `listIds`}.
+     *
+     * @remarks
+     * If this fails validation and you still want to get the content, you can use
+     * the low-level api to get the raw text of the `.metadata` file in the
+     * `RawListEntry` for this hash.
+     *
+     * @param hash - the hash of the item to get metadata for
+     * @returns the metadata
+     */
+    getMetadata(hash: string): Promise<Metadata>;
+    /**
+     * get the pdf associated with a document hash
+     *
+     * This returns the raw input pdf, not the rendered pdf with any markup.
+     *
+     * @param hash - the hash of the document to get the pdf for (e.g. the hash
+     *     received from `listItems`)
+     * @returns the pdf bytes
+     */
+    getPdf(hash: string): Promise<Uint8Array>;
+    /**
+     * get the epub associated with a document hash
+     *
+     * This returns the raw input epub if a document was created from an epub.
+     *
+     * @param hash - the hash of the document to get the pdf for (e.g. the hash
+     *     received from `listItems`)
+     * @returns the epub bytes
+     */
+    getEpub(hash: string): Promise<Uint8Array>;
+    /**
+     * get the entire contents of a remarkable document
+     *
+     * This gets every file of associated with a document, and puts them into a
+     * zip archive.
+     *
+     * @remarks
+     * This is an experimental feature, that works for downloading the raw version
+     * of the document, but this format isn't understood enoguh to reput this on a
+     * different remarkable, so that functionality is currently disabled.
+     *
+     * @param hash - the hash of the document to get the contents for (e.g. the
+     *    hash received from `listItems`)
+     */
+    getDocument(hash: string): Promise<Uint8Array>;
+    /**
+     * use the low-level api to add a pdf document
+     *
+     * Since this uses the low-level api, it provides more options than
+     * {@link uploadPdf | `uploadPdf`}, but is a little more finicky. Notably, it
+     * may throw a {@link GenerationError | `GenerationError`} if the generation
+     * doesn't match the current server generation, requiring you to retry until
+     * it works.
+     *
+     * @param visibleName - the name to display on the reMarkable
+     * @param buffer - the raw pdf
+     * @param opts - put options
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns the entry for the newly inserted document
+     */
+    putPdf(visibleName: string, buffer: Uint8Array, opts?: PutOptions): Promise<SimpleEntry>;
+    /**
+     * use the low-level api to add an epub document
+     *
+     * Since this uses the low-level api, it provides more options than
+     * {@link uploadEpub | `uploadEpub`}, but is a little more finicky. Notably, it
+     * may throw a {@link GenerationError | `GenerationError`} if the generation
+     * doesn't match the current server generation, requiring you to retry until
+     * it works.
+     *
+     * @param visibleName - the name to display on the reMarkable
+     * @param buffer - the raw epub
+     * @param opts - put options
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns the entry for the newly inserted document
+     */
+    putEpub(visibleName: string, buffer: Uint8Array, opts?: PutOptions): Promise<SimpleEntry>;
     /** create a folder */
-    createFolder(visibleName: string, opts?: UploadOptions): Promise<UploadEntry>;
+    createFolder(visibleName: string, opts?: UploadOptions, refresh?: boolean): Promise<SimpleEntry>;
     /**
      * upload an epub
      *
@@ -174,10 +798,13 @@ export interface RemarkableApi {
      * await api.uploadEpub("My EPub", ...);
      * ```
      *
+     * @remarks
+     * this is now simply a less powerful version of {@link putEpub | `putEpub`}.
+     *
      * @param visibleName - the name to show for the uploaded epub
      * @param buffer - the epub contents
      */
-    uploadEpub(visibleName: string, buffer: ArrayBuffer, opts?: UploadOptions): Promise<UploadEntry>;
+    uploadEpub(visibleName: string, buffer: Uint8Array, opts?: UploadOptions): Promise<SimpleEntry>;
     /**
      * upload a pdf
      *
@@ -186,10 +813,13 @@ export interface RemarkableApi {
      * await api.uploadPdf("My PDF", ...);
      * ```
      *
+     * @remarks
+     * this is now simply a less powerful version of {@link putPdf | `putPdf`}.
+     *
      * @param visibleName - the name to show for the uploaded epub
      * @param buffer - the epub contents
      */
-    uploadPdf(visibleName: string, buffer: ArrayBuffer, opts?: UploadOptions): Promise<UploadEntry>;
+    uploadPdf(visibleName: string, buffer: Uint8Array, opts?: UploadOptions): Promise<SimpleEntry>;
     /**
      * move an entry
      *
@@ -201,7 +831,7 @@ export interface RemarkableApi {
      * @param hash - the hash of the file to move
      * @param parent - the id of the directory to move the entry to, "" (root) and "trash" are special parents
      */
-    move(hash: string, parent: string, opts?: GetOptions): Promise<HashEntry>;
+    move(hash: string, parent: string, refresh?: boolean): Promise<HashEntry>;
     /**
      * delete an entry
      *
@@ -211,7 +841,7 @@ export interface RemarkableApi {
      * ```
      * @param hash - the hash of the entry to delete
      */
-    delete(hash: string, opts?: GetOptions): Promise<HashEntry>;
+    delete(hash: string, refresh?: boolean): Promise<HashEntry>;
     /**
      * rename an entry
      *
@@ -222,7 +852,7 @@ export interface RemarkableApi {
      * @param hash - the hash of the entry to rename
      * @param visibleName - the new name to assign
      */
-    rename(hash: string, visibleName: string, opts?: GetOptions): Promise<HashEntry>;
+    rename(hash: string, visibleName: string, refresh?: boolean): Promise<HashEntry>;
     /**
      * move many entries
      *
@@ -234,7 +864,7 @@ export interface RemarkableApi {
      * @param hashes - an array of entry hashes to move
      * @param parent - the directory id to move the entries to, "" (root) and "trash" are special ids
      */
-    bulkMove(hashes: readonly string[], parent: string, opts?: GetOptions): Promise<HashesEntry>;
+    bulkMove(hashes: readonly string[], parent: string, refresh?: boolean): Promise<HashesEntry>;
     /**
      * delete many entries
      *
@@ -245,23 +875,40 @@ export interface RemarkableApi {
      *
      * @param hashes - the hashes of the entries to delete
      */
-    bulkDelete(hashes: readonly string[], opts?: GetOptions): Promise<HashesEntry>;
-}
-/** options for a remarkable instance */
-export interface RemarkableOptions {
+    bulkDelete(hashes: readonly string[], refresh?: boolean): Promise<HashesEntry>;
+    /**
+     * get the current cache value as a string
+     *
+     * You can use this to warm start a new instance of
+     * {@link remarkable | `remarkable`} with any previously cached results.
+     */
+    dumpCache(): string;
     /**
-     * the fetch method to use
+     * prune the cache so that it contains only reachable hashes
+     *
+     * The cache is append only, so it can grow without bound, even as hashes
+     * become unreachable. In the future, this may have better cache management to
+     * track this in real time, but for now, you can call this method, to keep it
+     * from growing continuously.
      *
-     * This should loosely conform to the WHATWG fetch, but is relaxed enough that
-     * node-fetch also works. This will default to the global definitions of
-     * fetch.
+     * @remarks
+     * This won't necessarily reduce the cache size. In order to see if
+     * hashes are reachable we first have to search through all existing entry
+     * lists.
      *
-     * In node you can either use `"node-fetch"`, or `node --experimental-fetch`
-     * for node 17.5 or higher.
+     * @param refresh - whether to refresh the root hash before pruning
+     */
+    pruneCache(refresh?: boolean): Promise<void>;
+    /**
+     * completely delete the cache
      *
-     * @defaultValue globalThis.fetch
+     * If the cache is causing memory issues, you can clear it, but this will hurt
+     * performance.
      */
-    fetch?: FetchLike;
+    clearCache(): void;
+}
+/** options for a remarkable instance */
+export interface RemarkableOptions {
     /**
      * the url for making authorization requests
      *
@@ -271,9 +918,32 @@ export interface RemarkableOptions {
     /**
      * the url for making synchronization requests
      *
-     * @defaultValue "https://internal.cloud.remarkable.com"
+     * @defaultValue "https://web.eu.tectonic.remarkable.com"
      */
     syncHost?: string;
+    /**
+     * the url for making requests using the low-level api
+     *
+     * @defaultValue "https://eu.tectonic.remarkable.com"
+     */
+    rawHost?: string;
+    /**
+     * an initial cache value
+     *
+     * Generated from calling {@link RemarkableApi.dumpCache | `dumpCache`} on a previous
+     * instance.
+     */
+    cache?: string;
+    /**
+     * the maximum size of the cache in terms of total string length
+     *
+     * By the JavaScript specification there are two bytes per character, but the
+     * total memory usage of the cache will also be larger than just the size of
+     * the data stored.
+     *
+     * @defaultValue Infinity
+     */
+    maxCacheSize?: number;
 }
 /**
  * create an instance of the api
@@ -285,4 +955,4 @@ export interface RemarkableOptions {
  *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export declare function remarkable(deviceToken: string, { fetch, authHost, syncHost, }?: RemarkableOptions): Promise<RemarkableApi>;
+export declare function remarkable(deviceToken: string, { authHost, rawHost, cache, maxCacheSize, }?: RemarkableOptions): Promise<RemarkableApi>;