rmapi-js 11.2.0 → 12.0.1

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,21 +1,17 @@
-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";
+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, RmPage, 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 */
-    lastModified: string;
+    lastModified?: string;
     /** true if the entry is starred in most ui elements */
     pinned: boolean;
     /**
@@ -55,16 +51,6 @@ 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 */
@@ -221,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
      *
@@ -249,73 +237,60 @@ 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 id - the id of the document (as returned by `listIds`)
-     * @param hash - the hash of the document (e.g. from `listItems`)
+     * @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(id: string, hash: string, pageId: string): Promise<RmPage | undefined>;
+    getRmPage(ref: ItemRef, pageId: string): Promise<RmPage | undefined>;
     /**
      * get every drawn page of a document, parsed, keyed by page id
      *
@@ -324,11 +299,10 @@ export interface RemarkableApi {
      * 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`)
+     * @param ref - a reference to 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>>;
+    getRmPages(ref: ItemRef): Promise<Map<string, RmPage>>;
     /**
      * get a document's entire contents as a zip archive
      *
@@ -339,11 +313,9 @@ export interface RemarkableApi {
      * 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`)
+     * @param ref - a reference to the document (e.g. from `listItems`)
      */
-    getDocumentArchive(id: string, hash: string): Promise<Uint8Array>;
+    getDocumentArchive({ id, hash }: ItemRef): Promise<Uint8Array>;
     /**
      * upload a document archive produced by {@link getDocumentArchive | `getDocumentArchive`}
      *
@@ -360,11 +332,7 @@ export interface RemarkableApi {
      * @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>;
+    putDocumentArchive(buffer: Uint8Array, { refresh, parent, visibleName, id: keepId, }?: PutDocumentOptions): Promise<ItemRef>;
     /**
      * use the low-level api to add a pdf document
      *
@@ -405,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
      *
@@ -421,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
      *
@@ -438,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
      *
@@ -453,118 +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>;
     /**
      * star or unstar an entry
      *
      * @example
      * ```ts
-     * await api.star(file.hash, true);
+     * const next = await api.star(file, true);
      * ```
-     * @param hash - the hash of the entry to star
+     * @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
      */
-    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>;
+    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
      *
@@ -596,6 +567,7 @@ export interface RemarkableApi {
      */
     clearCache(): void;
 }
+export type { Remarkable as RemarkableApi };
 /** configuration for exchanging a device token */
 export interface AuthOptions {
     /**
@@ -677,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, maxGenerationRetries, maxTransientRetries, }?: RemarkableSessionOptions): RemarkableApi;
+export declare function session(sessionToken: string, { rawHost, uploadHost, cache, maxCacheSize, maxGenerationRetries, maxTransientRetries, }?: RemarkableSessionOptions): Remarkable;
 /**
  * create an instance of the api
  *
@@ -688,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>;