rmapi-js 8.1.1 → 8.3.0

package/dist/error.d.ts

@@ -0,0 +1,14 @@
+/** an error that results from a failed request */
+export declare class ValidationError extends Error {
+    /** the response status number */
+    readonly field: string;
+    /** the response status text */
+    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);
+}

package/dist/error.js

@@ -0,0 +1,21 @@
+/** an error that results from a failed request */
+export class ValidationError extends Error {
+    /** the response status number */
+    field;
+    /** the response status text */
+    regex;
+    constructor(field, regex, message) {
+        super(message);
+        this.field = field;
+        this.regex = regex;
+    }
+}
+/** an error that results while supplying a hash not found in the entries of the root hash */
+export class HashNotFoundError extends Error {
+    /** the hash that couldn't be found */
+    hash;
+    constructor(hash) {
+        super(`'${hash}' not found in the root hash`);
+        this.hash = hash;
+    }
+}

package/dist/index.d.ts

@@ -1,68 +1,6 @@
-/** request types */
-export type RequestMethod = "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
-/** 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;
-}
-/** 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;
+import { type BackgroundFilter, type CollectionContent, type Content, type DocumentContent, type Metadata, type Orientation, type RawRemarkableApi, type Tag, type TemplateContent, type TextAlignment, type ZoomMode } from "./raw";
+export { HashNotFoundError, ValidationError } from "./error";
+export type { BackgroundFilter, CollectionContent, Content, CPageNumberValue, CPagePage, CPages, CPageStringValue, CPageUUID, DocumentContent, DocumentMetadata, FileType, KeyboardMetadata, Metadata, Orientation, PageTag, RawEntry, RawFileEntry, RawListEntry, RawRemarkableApi, Tag, TemplateContent, TextAlignment, ZoomMode, } from "./raw";
 /** common properties shared by collections and documents */
 export interface EntryCommon {
     /** the document id, a uuid4 */
@@ -149,20 +87,6 @@ export declare class ResponseError extends Error {
     readonly statusText: string;
     constructor(status: number, statusText: string, message: string);
 }
-/** an error that results from a failed request */
-export declare class ValidationError extends Error {
-    /** the response status number */
-    readonly field: string;
-    /** the response status text */
-    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 {
     /**
@@ -195,272 +119,6 @@ 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;
-    /**
-     * 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;
-}
 /**
  * options for putting a file onto reMarkable
  *
@@ -521,187 +179,6 @@ export interface PutOptions {
      */
     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
  *
@@ -876,6 +353,42 @@ export interface RemarkableApi {
      * @param buffer - the epub contents
      */
     uploadPdf(visibleName: string, buffer: Uint8Array, opts?: UploadOptions): Promise<SimpleEntry>;
+    /**
+     * update content metadata for a document
+     *
+     * @example
+     * ```ts
+     * await api.updateDocument(doc.hash, { textAlignment: "left" });
+     * ```
+     *
+     * @param hash - the hash of the file to update
+     * @param content - the fields of content to update
+     */
+    updateDocument(hash: string, content: Partial<DocumentContent>, refresh?: boolean): Promise<HashEntry>;
+    /**
+     * update content metadata for a collection
+     *
+     * @example
+     * ```ts
+     * await api.updateCollection(doc.hash, { textAlignment: "left" });
+     * ```
+     *
+     * @param hash - the hash of the file to update
+     * @param content - the fields of content to update
+     */
+    updateCollection(hash: string, content: Partial<CollectionContent>, refresh?: boolean): Promise<HashEntry>;
+    /**
+     * update content metadata for a template
+     *
+     * @example
+     * ```ts
+     * await api.updateTemplate(doc.hash, { textAlignment: "left" });
+     * ```
+     *
+     * @param hash - the hash of the file to update
+     * @param content - the fields of content to update
+     */
+    updateTemplate(hash: string, content: Partial<TemplateContent>, refresh?: boolean): Promise<HashEntry>;
     /**
      * move an entry
      *
@@ -909,6 +422,17 @@ export interface RemarkableApi {
      * @param visibleName - the new name to assign
      */
     rename(hash: string, visibleName: string, refresh?: boolean): Promise<HashEntry>;
+    /**
+     * set if an entry is stared
+     *
+     * @example
+     * ```ts
+     * await api.stared(file.hash, true);
+     * ```
+     * @param hash - the hash of the entry to rename
+     * @param stared - whether the entry should be stared or not
+     */
+    stared(hash: string, stared: boolean, refresh?: boolean): Promise<HashEntry>;
     /**
      * move many entries
      *