rmapi-js 11.1.2 → 12.0.0

package/README.md

@@ -62,8 +62,9 @@ Using these apis is a little riskier since they can potentially result in data l
 // upload with custom line height not avilable through reMarkable
 await api.putEpub("name", buffer, { lineHeight: 180 })
 
-// fetch an uploaded epub, using the id and hash (from listItems)
-const buffer = await api.getEpub(id, hash)
+// fetch an uploaded epub, passing an item reference (from listItems)
+const [entry] = await api.listItems()
+const buffer = await api.getEpub(entry)
 ```
 
 ### Gotchas

package/dist/index.d.ts

@@ -1,13 +1,13 @@
-import { type BackgroundFilter, type CollectionContent, type Content, type DocumentContent, type Metadata, type Orientation, type RawRemarkableApi, type SimpleEntry, type Tag, type TemplateContent, type TextAlignment, type ZoomMode } from "./raw.js";
+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";
 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, KeyboardMetadata, LegacyCollectionContent, LegacyDocumentContent, Metadata, Orientation, PageTag, RawEntry, RawRemarkableApi, SchemaVersion, SimpleEntry, Tag, TemplateContent, TextAlignment, UploadMimeType, ZoomMode, } from "./raw.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 { 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";
 /** common properties shared by collections and documents */
-export interface EntryCommon {
-    /** the document id, a uuid4 */
-    id: string;
-    /** the current hash of the state of this entry */
-    hash: string;
+export interface EntryCommon extends ItemRef {
     /** the visible display name of this entry */
     visibleName: string;
     /** the last modified timestamp */
@@ -51,21 +51,27 @@ export interface TemplateType extends EntryCommon {
 }
 /** a remarkable entry for cloud items */
 export type Entry = CollectionEntry | DocumentType | TemplateType;
-/** the new hash of a modified entry */
-export interface HashEntry {
-    /** the actual hash */
-    hash: string;
-}
-/** the mapping from old hashes to new hashes after a bulk modify */
-export interface HashesEntry {
-    /** the mapping from old to new hashes */
-    hashes: Record<string, string>;
-}
 /** options for creating a folder */
 export interface FolderOptions {
     /** the id of the folder's parent directory, "" or omitted for root */
     parent?: string;
 }
+/** options for uploading a full document archive */
+export interface PutDocumentOptions {
+    /** if true, refresh the root hash before uploading */
+    refresh?: boolean;
+    /** the parent to place the document under, overriding the archived value */
+    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
  *
  * IF you encounter this error, you likely just need to try th request again. If
@@ -201,9 +207,11 @@ export interface PutOptions {
  * you should be able to use the low level api to work around any restrictive
  * validation.
  */
-export interface RemarkableApi {
+declare class Remarkable {
+    #private;
     /** scoped access to the raw low-level api */
-    raw: RawRemarkableApi;
+    readonly raw: RawRemarkable;
+    constructor(sessionToken: string, rawHost: string, uploadHost: string, cache: Map<string, string | null>, maxGenerationRetries: number, maxTransientRetries: number);
     /**
      * list all items
      *
@@ -229,77 +237,102 @@ export interface RemarkableApi {
      *
      * @param refresh - if true, refresh the root hash before listing
      */
-    listIds(refresh?: boolean): Promise<SimpleEntry[]>;
+    listIds(refresh?: boolean): Promise<ItemRef[]>;
     /**
-     * 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`}.
+     * get the content metadata for an item
      *
      * @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
      * `RawEntry` for this hash.
      *
-     * @param id - the id of the item (as returned by `listIds`)
-     * @param hash - the hash of the item to get content for
+     * @param ref - a reference to the item (e.g. from `listItems` or `listIds`)
      * @returns the content
      */
-    getContent(id: string, hash: string): Promise<Content>;
+    getContent({ id, hash }: ItemRef): 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`}.
+     * get the metadata for an item
      *
      * @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
      * `RawEntry` for this hash.
      *
-     * @param id - the id of the item (as returned by `listIds`)
-     * @param hash - the hash of the item to get metadata for
+     * @param ref - a reference to the item (e.g. from `listItems` or `listIds`)
      * @returns the metadata
      */
-    getMetadata(id: string, hash: string): Promise<Metadata>;
+    getMetadata({ id, hash }: ItemRef): Promise<Metadata>;
     /**
-     * get the pdf associated with a document hash
+     * get the pdf associated with a document
      *
      * This returns the raw input pdf, not the rendered pdf with any markup.
      *
-     * @param id - the id of the document (as returned by `listIds`)
-     * @param hash - the hash of the document to get the pdf for (e.g. the hash
-     *     received from `listItems`)
+     * @param ref - a reference to the document (e.g. from `listItems`)
      * @returns the pdf bytes
      */
-    getPdf(id: string, hash: string): Promise<Uint8Array>;
+    getPdf({ id, hash }: ItemRef): Promise<Uint8Array>;
     /**
-     * get the epub associated with a document hash
+     * get the epub associated with a document
      *
      * This returns the raw input epub if a document was created from an epub.
      *
-     * @param id - the id of the document (as returned by `listIds`)
-     * @param hash - the hash of the document to get the epub for (e.g. the hash
-     *     received from `listItems`)
+     * @param ref - a reference to the document (e.g. from `listItems`)
      * @returns the epub bytes
      */
-    getEpub(id: string, hash: string): Promise<Uint8Array>;
+    getEpub({ id, hash }: ItemRef): Promise<Uint8Array>;
+    /**
+     * get a single page's parsed reMarkable lines (`.rm`) drawing
+     *
+     * @param ref - a reference to the document (e.g. from `listItems`)
+     * @param pageId - the id of the page, from the document's `.content` page
+     *     list (see {@link getRmPages | `getRmPages`} for every page)
+     * @returns the parsed page, or `undefined` if the page exists but has no
+     *     `.rm` drawing (a page you haven't drawn on has no `.rm` file)
+     * @throws if `pageId` is not a page of the document
+     */
+    getRmPage(ref: ItemRef, pageId: string): Promise<RmPage | undefined>;
     /**
-     * get the entire contents of a remarkable document
+     * get every drawn page of a document, parsed, keyed by page id
+     *
+     * Returns a map from page id to its parsed {@link RmPage | `RmPage`},
+     * iterating in the page order given by the document's `.content`. Pages with
+     * no drawing (and soft-deleted pages) are omitted. Version 3, 5, and 6 pages
+     * are all supported.
      *
-     * This gets every file of associated with a document, and puts them into a
-     * zip archive.
+     * @param ref - a reference to the document (e.g. from `listItems`)
+     * @returns the drawn pages, keyed by page id, in document order
+     */
+    getRmPages(ref: ItemRef): Promise<Map<string, RmPage>>;
+    /**
+     * get a document's entire contents as a zip archive
+     *
+     * This gets every file associated with a document and puts them into a zip
+     * archive.
+     *
+     * @remarks
+     * This is an experimental feature. The resulting archive round-trips back
+     * through {@link putDocumentArchive | `putDocumentArchive`}.
+     *
+     * @param ref - a reference to the document (e.g. from `listItems`)
+     */
+    getDocumentArchive({ id, hash }: ItemRef): Promise<Uint8Array>;
+    /**
+     * upload a document archive produced by {@link getDocumentArchive | `getDocumentArchive`}
+     *
+     * This explodes the zip archive back into its constituent files, uploads each
+     * as a blob, and commits a new document into the root.
      *
      * @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.
+     * 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.
      *
-     * @param id - the id of the document (as returned by `listIds`)
-     * @param hash - the hash of the document to get contents for (e.g. the
-     *    hash received from `listItems`)
+     * @param buffer - the archive bytes, as returned by `getDocumentArchive`
+     * @param options - overrides for parent, visible name, and id
      */
-    getDocument(id: string, hash: string): Promise<Uint8Array>;
+    putDocumentArchive(buffer: Uint8Array, { refresh, parent, visibleName, id: keepId, }?: PutDocumentOptions): Promise<ItemRef>;
     /**
      * use the low-level api to add a pdf document
      *
@@ -340,7 +373,7 @@ export interface RemarkableApi {
      * @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>;
+    putPdf(visibleName: string, buffer: Uint8Array, opts?: PutOptions): Promise<ItemRef>;
     /**
      * use the low-level api to add an epub document
      *
@@ -356,9 +389,9 @@ export interface RemarkableApi {
      * @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>;
+    putEpub(visibleName: string, buffer: Uint8Array, opts?: PutOptions): Promise<ItemRef>;
     /** create a folder */
-    putFolder(visibleName: string, opts?: FolderOptions, refresh?: boolean): Promise<SimpleEntry>;
+    putFolder(visibleName: string, { parent }?: FolderOptions, refresh?: boolean): Promise<ItemRef>;
     /**
      * upload an epub
      *
@@ -373,7 +406,7 @@ export interface RemarkableApi {
      * @param visibleName - the name to show for the uploaded epub
      * @param buffer - the epub contents
      */
-    uploadEpub(visibleName: string, buffer: Uint8Array): Promise<SimpleEntry>;
+    uploadEpub(visibleName: string, buffer: Uint8Array): Promise<ItemRef>;
     /**
      * upload a pdf
      *
@@ -388,112 +421,121 @@ export interface RemarkableApi {
      * @param visibleName - the name to show for the uploaded epub
      * @param buffer - the epub contents
      */
-    uploadPdf(visibleName: string, buffer: Uint8Array): Promise<SimpleEntry>;
+    uploadPdf(visibleName: string, buffer: Uint8Array): Promise<ItemRef>;
     /** create a folder using the simple api */
-    uploadFolder(visibleName: string): Promise<SimpleEntry>;
+    uploadFolder(visibleName: string): Promise<ItemRef>;
     /**
      * update content metadata for a document
      *
      * @example
      * ```ts
-     * await api.updateDocument(doc.hash, { textAlignment: "left" });
+     * const next = await api.updateDocument(doc, { textAlignment: "left" });
      * ```
      *
-     * @param hash - the hash of the file to update
+     * @param ref - a reference to the file to update
      * @param content - the fields of content to update
+     * @returns a reference to the updated entry, with its new hash
      */
-    updateDocument(hash: string, content: Partial<DocumentContent>, refresh?: boolean): Promise<HashEntry>;
+    updateDocument(ref: ItemRef, content: Partial<DocumentContent>, refresh?: boolean): Promise<ItemRef>;
     /**
      * update content metadata for a collection
      *
      * @example
      * ```ts
-     * await api.updateCollection(doc.hash, { textAlignment: "left" });
+     * const next = await api.updateCollection(dir, { textAlignment: "left" });
      * ```
      *
-     * @param hash - the hash of the file to update
+     * @param ref - a reference to the collection to update
      * @param content - the fields of content to update
+     * @returns a reference to the updated entry, with its new hash
      */
-    updateCollection(hash: string, content: Partial<CollectionContent>, refresh?: boolean): Promise<HashEntry>;
+    updateCollection(ref: ItemRef, content: Partial<CollectionContent>, refresh?: boolean): Promise<ItemRef>;
     /**
      * update content metadata for a template
      *
      * @example
      * ```ts
-     * await api.updateTemplate(doc.hash, { textAlignment: "left" });
+     * const next = await api.updateTemplate(tmpl, { textAlignment: "left" });
      * ```
      *
-     * @param hash - the hash of the file to update
+     * @param ref - a reference to the template to update
      * @param content - the fields of content to update
+     * @returns a reference to the updated entry, with its new hash
      */
-    updateTemplate(hash: string, content: Partial<TemplateContent>, refresh?: boolean): Promise<HashEntry>;
+    updateTemplate(ref: ItemRef, content: Partial<TemplateContent>, refresh?: boolean): Promise<ItemRef>;
     /**
      * move an entry
      *
      * @example
      * ```ts
-     * await api.move(doc.hash, dir.id);
+     * const next = await api.move(doc, dir.id);
      * ```
      *
-     * @param hash - the hash of the file to move
+     * @param ref - a reference to the entry to move
      * @param parent - the id of the directory to move the entry to, "" (root) and "trash" are special parents
+     * @returns a reference to the moved entry, with its new hash
      */
-    move(hash: string, parent: string, refresh?: boolean): Promise<HashEntry>;
+    move(ref: ItemRef, parent: string, refresh?: boolean): Promise<ItemRef>;
     /**
      * delete an entry
      *
      * @example
      * ```ts
-     * await api.delete(file.hash);
+     * await api.delete(file);
      * ```
-     * @param hash - the hash of the entry to delete
+     * @param ref - a reference to the entry to delete
+     * @returns a reference to the deleted entry, with its new hash
      */
-    delete(hash: string, refresh?: boolean): Promise<HashEntry>;
+    delete(ref: ItemRef, refresh?: boolean): Promise<ItemRef>;
     /**
      * rename an entry
      *
      * @example
      * ```ts
-     * await api.rename(file.hash, "new name");
+     * const next = await api.rename(file, "new name");
      * ```
-     * @param hash - the hash of the entry to rename
+     * @param ref - a reference to the entry to rename
      * @param visibleName - the new name to assign
+     * @returns a reference to the renamed entry, with its new hash
      */
-    rename(hash: string, visibleName: string, refresh?: boolean): Promise<HashEntry>;
+    rename(ref: ItemRef, visibleName: string, refresh?: boolean): Promise<ItemRef>;
     /**
-     * set if an entry is stared
+     * star or unstar an entry
      *
      * @example
      * ```ts
-     * await api.stared(file.hash, true);
+     * const next = await api.star(file, true);
      * ```
-     * @param hash - the hash of the entry to rename
-     * @param stared - whether the entry should be stared or not
+     * @param ref - a reference to the entry to star
+     * @param starred - whether the entry should be starred or not
+     * @returns a reference to the updated entry, with its new hash
      */
-    stared(hash: string, stared: boolean, refresh?: boolean): Promise<HashEntry>;
+    star(ref: ItemRef, starred: boolean, refresh?: boolean): Promise<ItemRef>;
     /**
      * move many entries
      *
      * @example
      * ```ts
-     * await api.bulkMove([file.hash], dir.id);
+     * const next = await api.bulkMove([file], dir.id);
      * ```
      *
-     * @param hashes - an array of entry hashes to move
+     * @param refs - references to the entries to move
      * @param parent - the directory id to move the entries to, "" (root) and "trash" are special ids
+     * @returns references to the moved entries, each with its new hash
      */
-    bulkMove(hashes: readonly string[], parent: string, refresh?: boolean): Promise<HashesEntry>;
+    bulkMove(refs: readonly ItemRef[], parent: string, refresh?: boolean): Promise<ItemRef[]>;
     /**
      * delete many entries
      *
      * @example
      * ```ts
-     * await api.bulkDelete([file.hash]);
+     * await api.bulkDelete([file]);
      * ```
      *
-     * @param hashes - the hashes of the entries to delete
+     * @param refs - references to the entries to delete
+     * @returns references to the deleted entries, each with its new hash
      */
-    bulkDelete(hashes: readonly string[], refresh?: boolean): Promise<HashesEntry>;
+    bulkDelete(refs: readonly ItemRef[], refresh?: boolean): Promise<ItemRef[]>;
     /**
      * get the current cache value as a string
      *
@@ -525,6 +567,7 @@ export interface RemarkableApi {
      */
     clearCache(): void;
 }
+export type { Remarkable as RemarkableApi };
 /** configuration for exchanging a device token */
 export interface AuthOptions {
     /**
@@ -565,6 +608,26 @@ export interface RemarkableSessionOptions {
      * @defaultValue Infinity
      */
     maxCacheSize?: number;
+    /**
+     * how many times to retry updating the root hash after a generation conflict
+     *
+     * High-level mutators re-fetch the latest root and re-apply their change on a
+     * {@link GenerationError | `GenerationError`} up to this many times. Because
+     * the document id and uploaded blobs are stable across attempts, retries
+     * reuse the cache and don't orphan blobs. Set to `0` to surface the error
+     * immediately, matching the previous behavior.
+     *
+     * @defaultValue 10
+     */
+    maxGenerationRetries?: number;
+    /**
+     * how many times to retry a request after a transient network or 5xx error
+     *
+     * Applies to every request; generation conflicts are not counted here.
+     *
+     * @defaultValue 3
+     */
+    maxTransientRetries?: number;
 }
 /** options for a remarkable instance */
 export interface RemarkableOptions extends AuthOptions, RemarkableSessionOptions {
@@ -586,7 +649,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, }?: RemarkableSessionOptions): RemarkableApi;
+export declare function session(sessionToken: string, { rawHost, uploadHost, cache, maxCacheSize, maxGenerationRetries, maxTransientRetries, }?: RemarkableSessionOptions): Remarkable;
 /**
  * create an instance of the api
  *
@@ -597,4 +660,4 @@ export declare function session(sessionToken: string, { rawHost, uploadHost, cac
  *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export declare function remarkable(deviceToken: string, options?: RemarkableOptions): Promise<RemarkableApi>;
+export declare function remarkable(deviceToken: string, options?: RemarkableOptions): Promise<Remarkable>;