rmapi-js 11.1.2 → 11.2.0

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-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 Metadata, type Orientation, type RawRemarkableApi, type RmPage, type SimpleEntry, 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, KeyboardMetadata, LegacyCollectionContent, LegacyDocumentContent, Metadata, Orientation, PageTag, RawEntry, RawRemarkableApi, RmPage, SchemaVersion, SimpleEntry, 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 */
@@ -66,6 +70,22 @@ 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
@@ -285,21 +305,66 @@ export interface RemarkableApi {
      */
     getEpub(id: string, hash: string): Promise<Uint8Array>;
     /**
-     * get the entire contents of a remarkable document
+     * get a single page's parsed reMarkable lines (`.rm`) drawing
      *
-     * This gets every file of associated with a document, and puts them into a
-     * zip archive.
+     * @param id - the id of the document (as returned by `listIds`)
+     * @param hash - the hash of 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(id: string, hash: string, pageId: string): Promise<RmPage | undefined>;
+    /**
+     * 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.
+     *
+     * @param id - the id of the document (as returned by `listIds`)
+     * @param hash - the hash of the document (e.g. from `listItems`)
+     * @returns the drawn pages, keyed by page id, in document order
+     */
+    getRmPages(id: string, hash: string): 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, 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. The resulting archive round-trips back
+     * through {@link putDocumentArchive | `putDocumentArchive`}.
      *
      * @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`)
      */
+    getDocumentArchive(id: string, hash: string): 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. 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 buffer - the archive bytes, as returned by `getDocumentArchive`
+     * @param options - overrides for parent, visible name, and id
+     */
+    putDocumentArchive(buffer: Uint8Array, options?: PutDocumentOptions): Promise<SimpleEntry>;
+    /** @deprecated renamed; use {@link getDocumentArchive | `getDocumentArchive`} */
     getDocument(id: string, hash: string): Promise<Uint8Array>;
+    /** @deprecated renamed; use {@link putDocumentArchive | `putDocumentArchive`} */
+    putDocument(buffer: Uint8Array, options?: PutDocumentOptions): Promise<SimpleEntry>;
     /**
      * use the low-level api to add a pdf document
      *
@@ -461,14 +526,20 @@ export interface RemarkableApi {
      */
     rename(hash: string, visibleName: string, refresh?: boolean): Promise<HashEntry>;
     /**
-     * set if an entry is stared
+     * star or unstar an entry
      *
      * @example
      * ```ts
-     * await api.stared(file.hash, true);
+     * await api.star(file.hash, true);
      * ```
-     * @param hash - the hash of the entry to rename
-     * @param stared - whether the entry should be stared or not
+     * @param hash - the hash of the entry to star
+     * @param starred - whether the entry should be starred or not
+     */
+    star(hash: string, starred: boolean, refresh?: boolean): Promise<HashEntry>;
+    /**
+     * set if an entry is starred
+     *
+     * @deprecated misspelling; use {@link star | `star`} instead
      */
     stared(hash: string, stared: boolean, refresh?: boolean): Promise<HashEntry>;
     /**
@@ -565,6 +636,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 +677,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): RemarkableApi;
 /**
  * create an instance of the api
  *