rmapi-js 12.0.2 → 13.0.0

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { type BackgroundFilter, type CollectionContent, type Content, type DocumentContent, type ItemRef, type Metadata, type Orientation, RawRemarkable, type RmPage, type Tag, type TemplateContent, type TextAlignment, type ZoomMode } from "./raw.js";
+import { type BackgroundFilter, type CollectionContent, type Content, type DocumentContent, type Highlight, type ItemRef, type Metadata, type Orientation, type PageMetadata, RawRemarkable, type RmPage, type Tag, type TemplateContent, type TextAlignment, type ZoomMode } from "./raw.js";
 export { type DeviceModel, type DeviceScreen, deviceScreens, } from "./devices.js";
 export { HashNotFoundError, ValidationError } from "./error.js";
-export type { BackgroundFilter, CollectionContent, Content, CPageNumberValue, CPagePage, CPageStringValue, CPages, CPageUUID, DocumentContent, DocumentMetadata, Entries, FileType, ItemRef, KeyboardMetadata, LegacyCollectionContent, LegacyDocumentContent, Metadata, Orientation, PageTag, RawEntry, RawRemarkableApi, RmPage, SchemaVersion, Tag, TemplateContent, TextAlignment, UploadMimeType, ZoomMode, } from "./raw.js";
+export type { BackgroundFilter, CollectionContent, Content, CPageNumberValue, CPagePage, CPageStringValue, CPages, CPageUUID, DocumentContent, DocumentMetadata, Entries, EntryType, FileType, Highlight, HighlightRect, ItemRef, KeyboardMetadata, LegacyCollectionContent, LegacyDocumentContent, Metadata, Orientation, PageLayer, PageMetadata, PageTag, PendingEntry, RawEntry, RawRemarkableApi, RmPage, SchemaVersion, Tag, TemplateContent, TextAlignment, UploadMimeType, ZoomMode, } from "./raw.js";
 export type { RmBrush, RmLayer, RmLine, RmPageV5, RmPoint, RmVersion, } from "./rm5.js";
 export { decodeBrush, rmColors } from "./rm5.js";
-export type { AuthorIdsBlock, CrdtId, GlyphRange, LwwValue, MigrationInfoBlock, PageInfoBlock, Rectangle, RmBlock, RmScene, RmSceneItem, RmSceneLayer, RmV6Line, RmV6Point, RmV6Text, RmV6TextValue, RootTextBlock, SceneGlyphItemBlock, SceneGroupItemBlock, SceneInfoBlock, SceneItem, SceneLineItemBlock, SceneTextItemBlock, SceneTombstoneItemBlock, SceneTreeBlock, TreeNodeBlock, UnknownBlock, } from "./rm6.js";
-export { crdtKey, END_MARKER, parseRmScene, ROOT_ID } from "./rm6.js";
+export type { AuthorIdsBlock, CrdtId, GlyphRange, LwwValue, MigrationInfoBlock, PageInfoBlock, Rectangle, RmBlock, RmScene, RmSceneItem, RmSceneLayer, RmV6Line, RmV6Point, RmV6Text, RmV6TextValue, RootTextBlock, SceneGlyphItemBlock, SceneGroupItemBlock, SceneInfoBlock, SceneItem, SceneLineItemBlock, SceneTextItemBlock, SceneTombstoneItemBlock, SceneTreeBlock, TreeNodeAnchor, TreeNodeBlock, UnknownBlock, } from "./rm6.js";
+export { crdtKey } from "./rm6.js";
 /** common properties shared by collections and documents */
 export interface EntryCommon extends ItemRef {
     /** the visible display name of this entry */
@@ -30,7 +30,7 @@ export interface CollectionEntry extends EntryCommon {
     type: "CollectionType";
 }
 /** a file, referred to in the api as a document */
-export interface DocumentType extends EntryCommon {
+export interface DocumentEntry extends EntryCommon {
     /** the key to identify this as a document */
     type: "DocumentType";
     /** the type of the file */
@@ -39,7 +39,7 @@ export interface DocumentType extends EntryCommon {
     lastOpened: string;
 }
 /** a template, such as from methods.remarkable.com */
-export interface TemplateType extends EntryCommon {
+export interface TemplateEntry extends EntryCommon {
     /** the key to identify this as a template */
     type: "TemplateType";
     /** the timestamp of when the template was added/created */
@@ -50,7 +50,7 @@ export interface TemplateType extends EntryCommon {
     new?: boolean;
 }
 /** a remarkable entry for cloud items */
-export type Entry = CollectionEntry | DocumentType | TemplateType;
+export type Entry = CollectionEntry | DocumentEntry | TemplateEntry;
 /** options for creating a folder */
 export interface FolderOptions {
     /** the id of the folder's parent directory, "" or omitted for root */
@@ -64,13 +64,6 @@ export interface PutDocumentOptions {
     parent?: string;
     /** the visible name to use, overriding the archived value */
     visibleName?: string;
-    /**
-     * reuse this document id instead of generating a fresh one
-     *
-     * By default a new uuid is generated so re-uploading an archive to the same
-     * account doesn't collide with the original. Pass an id to restore in place.
-     */
-    id?: string;
 }
 /** An error that gets thrown when the backend while trying to update
  *
@@ -211,7 +204,7 @@ declare class Remarkable {
     #private;
     /** scoped access to the raw low-level api */
     readonly raw: RawRemarkable;
-    constructor(sessionToken: string, rawHost: string, uploadHost: string, cache: Map<string, string | null>, maxGenerationRetries: number, maxTransientRetries: number);
+    constructor(sessionToken: string, rawHost: string, uploadHost: string, cache: Map<string, Uint8Array | null>, maxGenerationRetries: number, maxTransientRetries: number, maxCachedBytes: number);
     /**
      * list all items
      *
@@ -233,11 +226,14 @@ declare class Remarkable {
      */
     listItems(refresh?: boolean): Promise<Entry[]>;
     /**
-     * similar to {@link listItems | `listItems`} but backed by the low level api
+     * list a reference to every item, backed by the low level api
+     *
+     * Unlike {@link listItems | `listItems`} this doesn't read each item's
+     * metadata, so it's cheaper but only gives you ids and hashes.
      *
      * @param refresh - if true, refresh the root hash before listing
      */
-    listIds(refresh?: boolean): Promise<ItemRef[]>;
+    listRefs(refresh?: boolean): Promise<ItemRef[]>;
     /**
      * get the content metadata for an item
      *
@@ -246,10 +242,10 @@ declare class Remarkable {
      * the low-level api to get the raw text of the `.content` file in the
      * `RawEntry` for this hash.
      *
-     * @param ref - a reference to the item (e.g. from `listItems` or `listIds`)
+     * @param ref - a reference to the item (e.g. from `listItems` or `listRefs`)
      * @returns the content
      */
-    getContent({ id, hash }: ItemRef): Promise<Content>;
+    getContent(ref: ItemRef): Promise<Content>;
     /**
      * get the metadata for an item
      *
@@ -258,10 +254,10 @@ declare class Remarkable {
      * the low-level api to get the raw text of the `.metadata` file in the
      * `RawEntry` for this hash.
      *
-     * @param ref - a reference to the item (e.g. from `listItems` or `listIds`)
+     * @param ref - a reference to the item (e.g. from `listItems` or `listRefs`)
      * @returns the metadata
      */
-    getMetadata({ id, hash }: ItemRef): Promise<Metadata>;
+    getMetadata(ref: ItemRef): Promise<Metadata>;
     /**
      * get the pdf associated with a document
      *
@@ -270,7 +266,7 @@ declare class Remarkable {
      * @param ref - a reference to the document (e.g. from `listItems`)
      * @returns the pdf bytes
      */
-    getPdf({ id, hash }: ItemRef): Promise<Uint8Array>;
+    getPdf(ref: ItemRef): Promise<Uint8Array>;
     /**
      * get the epub associated with a document
      *
@@ -279,7 +275,7 @@ declare class Remarkable {
      * @param ref - a reference to the document (e.g. from `listItems`)
      * @returns the epub bytes
      */
-    getEpub({ id, hash }: ItemRef): Promise<Uint8Array>;
+    getEpub(ref: ItemRef): Promise<Uint8Array>;
     /**
      * get a single page's parsed reMarkable lines (`.rm`) drawing
      *
@@ -303,6 +299,147 @@ declare class Remarkable {
      * @returns the drawn pages, keyed by page id, in document order
      */
     getRmPages(ref: ItemRef): Promise<Map<string, RmPage>>;
+    /**
+     * write a single page's reMarkable lines (`.rm`) drawing
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @param page - the drawing to write, replacing any already there
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if `pageId` is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    putRmPage(ref: ItemRef, pageId: string, page: RmPage, refresh?: boolean): Promise<ItemRef>;
+    /**
+     * write several pages' reMarkable lines (`.rm`) drawings in one commit
+     *
+     * @param ref - a reference to the document
+     * @param pages - the drawings to write, keyed by page id, replacing any
+     *     already on those pages and leaving every other page alone
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if any key is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    putRmPages(ref: ItemRef, pages: ReadonlyMap<string, RmPage>, refresh?: boolean): Promise<ItemRef>;
+    /**
+     * get a single page's text highlights
+     *
+     * These are separate from the highlighter strokes drawn in a `.rm` scene.
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @returns the page's highlights, or `undefined` if the page has none
+     * @throws if `pageId` is not a page of the document
+     */
+    getHighlights(ref: ItemRef, pageId: string): Promise<Highlight[][] | undefined>;
+    /**
+     * get every highlighted page of a document, keyed by page id
+     *
+     * @param ref - a reference to the document
+     * @returns the highlights in page order, omitting pages with none
+     */
+    getHighlightPages(ref: ItemRef): Promise<Map<string, Highlight[][]>>;
+    /**
+     * write a single page's text highlights, replacing any already there
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @param highlights - the highlights to write
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if `pageId` is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    putHighlights(ref: ItemRef, pageId: string, highlights: readonly Highlight[][], refresh?: boolean): Promise<ItemRef>;
+    /**
+     * write several pages' text highlights in one commit
+     *
+     * @param ref - a reference to the document
+     * @param pages - the highlights to write, keyed by page id, replacing any
+     *     already on those pages and leaving every other page alone
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if any key is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    putHighlightPages(ref: ItemRef, pages: ReadonlyMap<string, readonly Highlight[][]>, refresh?: boolean): Promise<ItemRef>;
+    /**
+     * get a template attached to an item as a `.template` sidecar
+     *
+     * This is distinct from a {@link TemplateEntry | `TemplateEntry`} (whose
+     * template is its `.content`); collections and documents can carry a template
+     * this way.
+     *
+     * @param ref - a reference to the item
+     * @returns the template content, or `undefined` if the item has no `.template`
+     */
+    getTemplate(ref: ItemRef): Promise<TemplateContent | undefined>;
+    /**
+     * attach a template to an item as a `.template` sidecar
+     *
+     * @param ref - a reference to the item
+     * @param template - the template to attach, replacing any already there
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns a reference to the updated item, with its new hash
+     */
+    putTemplate(ref: ItemRef, template: TemplateContent, refresh?: boolean): Promise<ItemRef>;
+    /**
+     * get a document's per-page template names
+     *
+     * The `.pagedata` file lists one template name per page, in page order (an
+     * empty string for a page with no template).
+     *
+     * @param ref - a reference to the document
+     * @returns the per-page template names, or `undefined` if the document has
+     *     no `.pagedata`
+     */
+    getPagedata(ref: ItemRef): Promise<string[] | undefined>;
+    /**
+     * set a document's per-page template names
+     *
+     * @param ref - a reference to the document
+     * @param templates - one template name per page, in page order, an empty
+     *     string for a page with no template
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @returns a reference to the updated document, with its new hash
+     */
+    putPagedata(ref: ItemRef, templates: readonly string[], refresh?: boolean): Promise<ItemRef>;
+    /**
+     * get a single page's layer metadata
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @returns the page's layer metadata, or `undefined` if the page has none
+     * @throws if `pageId` is not a page of the document
+     */
+    getPageMetadata(ref: ItemRef, pageId: string): Promise<PageMetadata | undefined>;
+    /**
+     * get every page's layer metadata, keyed by page id
+     *
+     * @param ref - a reference to the document
+     * @returns the layer metadata in page order, omitting pages with none
+     */
+    getPageMetadataPages(ref: ItemRef): Promise<Map<string, PageMetadata>>;
+    /**
+     * write a single page's layer metadata, replacing any already there
+     *
+     * @param ref - a reference to the document
+     * @param pageId - the id of the page, from the document's `.content` page list
+     * @param meta - the layer metadata to write
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if `pageId` is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    putPageMetadata(ref: ItemRef, pageId: string, meta: PageMetadata, refresh?: boolean): Promise<ItemRef>;
+    /**
+     * write several pages' layer metadata in one commit
+     *
+     * @param ref - a reference to the document
+     * @param pages - the layer metadata to write, keyed by page id, replacing any
+     *     already on those pages and leaving every other page alone
+     * @throws GenerationError if the generation doesn't match the current server generation
+     * @throws if any key is not a page of the document
+     * @returns a reference to the updated document, with its new hash
+     */
+    putPageMetadataPages(ref: ItemRef, pages: ReadonlyMap<string, PageMetadata>, refresh?: boolean): Promise<ItemRef>;
     /**
      * get a document's entire contents as a zip archive
      *
@@ -315,7 +452,7 @@ declare class Remarkable {
      *
      * @param ref - a reference to the document (e.g. from `listItems`)
      */
-    getDocumentArchive({ id, hash }: ItemRef): Promise<Uint8Array>;
+    getDocumentArchive(ref: ItemRef): Promise<Uint8Array>;
     /**
      * upload a document archive produced by {@link getDocumentArchive | `getDocumentArchive`}
      *
@@ -323,16 +460,16 @@ declare class Remarkable {
      * as a blob, and commits a new document into the root.
      *
      * @remarks
-     * This is an experimental feature. By default a fresh document id is generated
-     * so re-uploading to the same account doesn't collide with the original; pass
-     * {@link PutDocumentOptions.id | `id`} to keep the original id. Like the other
-     * low-level puts, this may throw a {@link GenerationError | `GenerationError`}
-     * if the generation is stale, requiring a retry.
+     * This is an experimental feature. A fresh document id is generated, so
+     * re-uploading to the same account doesn't collide with the original. Like
+     * the other low-level puts, this may throw a
+     * {@link GenerationError | `GenerationError`} if the generation is stale,
+     * requiring a retry.
      *
      * @param buffer - the archive bytes, as returned by `getDocumentArchive`
-     * @param options - overrides for parent, visible name, and id
+     * @param options - overrides for parent and visible name
      */
-    putDocumentArchive(buffer: Uint8Array, { refresh, parent, visibleName, id: keepId, }?: PutDocumentOptions): Promise<ItemRef>;
+    putDocumentArchive(buffer: Uint8Array, { refresh, parent, visibleName }?: PutDocumentOptions): Promise<ItemRef>;
     /**
      * use the low-level api to add a pdf document
      *
@@ -599,15 +736,24 @@ export interface RemarkableSessionOptions {
      */
     cache?: string;
     /**
-     * the maximum size of the cache in terms of total string length
+     * the maximum size of the cache, in bytes of cached content plus key 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.
+     * The total memory usage of the cache will be somewhat larger than this,
+     * since it counts only the stored data.
      *
      * @defaultValue Infinity
      */
     maxCacheSize?: number;
+    /**
+     * the largest stored file to keep the contents of, in bytes
+     *
+     * Anything larger is fetched normally but only its existence is recorded, so
+     * one big pdf can't evict everything else. Set to `0` to cache nothing but
+     * existence, or `Infinity` to keep whatever is read.
+     *
+     * @defaultValue 1048576
+     */
+    maxCachedBytes?: number;
     /**
      * how many times to retry updating the root hash after a generation conflict
      *
@@ -649,7 +795,7 @@ export declare function auth(deviceToken: string, { authHost }?: AuthOptions): P
  * @param sessionToken - the session token used for authorization
  * @returns an api instance
  */
-export declare function session(sessionToken: string, { rawHost, uploadHost, cache, maxCacheSize, maxGenerationRetries, maxTransientRetries, }?: RemarkableSessionOptions): Remarkable;
+export declare function session(sessionToken: string, { rawHost, uploadHost, cache, maxCacheSize, maxCachedBytes, maxGenerationRetries, maxTransientRetries, }?: RemarkableSessionOptions): Remarkable;
 /**
  * create an instance of the api
  *