rmapi-js 8.1.0 → 8.2.0

package/dist/raw.d.ts

@@ -0,0 +1,538 @@
+/** request types */
+export type RequestMethod = "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+/**
+ * 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;
+/** the type of files reMarkable supports */
+export type FileType = "epub" | "pdf" | "notebook";
+/** a tag for an entry */
+export interface Tag {
+    /** the name of the tag */
+    name: string;
+    /** 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;
+}
+/** 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";
+/** 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;
+    /**
+     * the document margin in pixels
+     *
+     * The reMarkable uses three built-in margins: 50, 125, 200, but other margins
+     * are possible. The reMarkable used to default to margins of 180.
+     */
+    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;
+}
+/**
+ * content metadata, stored with the "content" extension
+ *
+ * This largely contains description of how to render the document, rather than
+ * metadata about it.
+ */
+export interface TemplateContent {
+    /** the template name */
+    name: string;
+    /** the template's author */
+    author: string;
+    /** Base64-encoded SVG icon image */
+    iconData: string;
+    /** category names this template belongs to (eg: "Planning", "Productivity") */
+    categories: string[];
+    /** labels associated with this template (eg: "Project management") */
+    labels: string[];
+    /** the orientation of this template */
+    orientation: "portrait" | "landscape";
+    /** semantic version for this template */
+    templateVersion: string;
+    /** template configuration format version (currently just `1`) */
+    formatVersion: number;
+    /**
+     * which screens the template supports:
+     *
+     * - `rm2`: reMarkable 2
+     * - `rmPP`: reMarkable Paper Pro
+     */
+    supportedScreens: ("rm2" | "rmPP")[];
+    /** constant values used by the commands in `items` */
+    constants?: {
+        [name: string]: number;
+    }[];
+    /** the template definition, an SVG-like DSL in JSON */
+    items: object[];
+}
+/** content metadata for any item */
+export type Content = CollectionContent | DocumentContent | TemplateContent;
+/**
+ * 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" | "TemplateType";
+    /** whether this is this a newly-installed template */
+    new?: boolean;
+    /**
+     * the provider from which this item was obtained/installed
+     *
+     * Example: a template from "com.remarkable.methods".
+     */
+    source?: string;
+    /** [speculative] metadata version, always 0 */
+    version?: number;
+    /** the visible name of the item, what it's called on the reMarkable */
+    visibleName: string;
+}
+/**
+ * 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;
+}
+interface 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);
+    /** make an authorized request to remarkable */
+    getRootHash(): Promise<[string, number]>;
+    getHash(hash: string): Promise<Uint8Array>;
+    getText(hash: string): Promise<string>;
+    getEntries(hash: string): Promise<RawEntry[]>;
+    getContent(hash: string): Promise<Content>;
+    getMetadata(hash: string): Promise<Metadata>;
+    putRootHash(hash: string, generation: number, broadcast?: boolean): Promise<[string, number]>;
+    putFile(id: string, bytes: Uint8Array): Promise<[RawFileEntry, Promise<void>]>;
+    putText(id: string, text: string): Promise<[RawFileEntry, Promise<void>]>;
+    putContent(id: string, content: Content): Promise<[RawFileEntry, Promise<void>]>;
+    putMetadata(id: string, metadata: Metadata): Promise<[RawFileEntry, Promise<void>]>;
+    putEntries(id: string, entries: RawEntry[]): Promise<[RawListEntry, Promise<void>]>;
+    dumpCache(): string;
+    clearCache(): void;
+}
+export {};