rmapi-js
    Preparing search index...

    Interface RawRemarkableApi

    access to the low-level reMarkable api

    This class gives more granualar access to the reMarkable cloud, but is more dangerous.

    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 (getRootHash) before using this api to attempt file writes, so you can recover a previous "snapshot" should anything go wrong.

    Each item is a collection of individual files. Using 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 DocumentContent)
    • <docid>.metadata - metadata about the document (see 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.

    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 dumpCache to persist the cache between sessions.

    Generally all hashes are 64 character hex strings, and all ids are uuid4.

    interface RawRemarkableApi {
        clearCache(): void;
        dumpCache(): string;
        getContent(hash: string): Promise<Content>;
        getEntries(hash: string): Promise<RawEntry[]>;
        getHash(hash: string): Promise<Uint8Array<ArrayBufferLike>>;
        getMetadata(hash: string): Promise<Metadata>;
        getRootHash(): Promise<[string, number]>;
        getText(hash: string): Promise<string>;
        putContent(
            id: string,
            content: Content,
        ): Promise<[RawFileEntry, Promise<void>]>;
        putEntries(
            id: string,
            entries: RawEntry[],
        ): Promise<[RawListEntry, Promise<void>]>;
        putFile(
            id: string,
            bytes: Uint8Array,
        ): Promise<[RawFileEntry, Promise<void>]>;
        putMetadata(
            id: string,
            metadata: Metadata,
        ): Promise<[RawFileEntry, Promise<void>]>;
        putRootHash(
            hash: string,
            generation: number,
            broadcast?: boolean,
        ): Promise<[string, number]>;
        putText(
            id: string,
            content: string,
        ): Promise<[RawFileEntry, Promise<void>]>;
    }
    Index

    Methods

    clearCache dumpCache getContent getEntries getHash getMetadata getRootHash getText putContent putEntries putFile putMetadata putRootHash putText

    Methods

    • completely clear the cache

      Returns void

    • dump the current cache to a string to preserve between session

      Returns string

      a serialized version of the cache to pass to a new api instance

    • get the parsed and validated Content of a content hash

      Use getText combined with JSON.parse to bypass validation

      Parameters

      • hash: string

        the hash to get Content for

      Returns Promise<Content>

      the content

    • 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.

      Parameters

      • hash: string

        the hash to get entries for

      Returns Promise<RawEntry[]>

      the entries

    • get the raw binary data associated with a hash

      Parameters

      • hash: string

        the hash to get the data for

      Returns Promise<Uint8Array<ArrayBufferLike>>

      the data

    • get the parsed and validated Metadata of a metadata hash

      Use getText combined with JSON.parse to bypass validation

      Parameters

      • hash: string

        the hash to get Metadata for

      Returns Promise<Metadata>

      the metadata

    • 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 Promise<[string, number]>

      the root hash and the current generation

    • 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 getHash combined with a TextDecoder.

      Parameters

      • hash: string

        the hash to get text for

      Returns Promise<string>

      the text

    • 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

      Parameters

      • id: string

        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.

      • entries: RawEntry[]

        the entries to upload

      Returns Promise<[RawListEntry, Promise<void>]>

      the new list entry and a promise to finish the upload

    • 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.

      Parameters

      • id: string

        the id of the file to upload

      • bytes: Uint8Array

        the bytes to upload

      Returns Promise<[RawFileEntry, Promise<void>]>

      the new entry and a promise to finish the upload

    • 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 GenerationError, that indicates that the server was updated after you last got the generation. You should call 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.

      Parameters

      • hash: string

        the new root hash

      • generation: number

        the generation of the current root hash

      • Optionalbroadcast: boolean

        [unknown] an option in the request

      Returns Promise<[string, number]>

      the new root hash and the new generation

      GenerationError if the generation doesn't match the current server generation

    • the same as putFile but with caching for text

      Parameters

      • id: string
      • content: string

      Returns Promise<[RawFileEntry, Promise<void>]>

    Settings

    Member Visibility

    On This Page

    OverviewItemsCaching
    Methods