rmapi-js 1.1.0 → 2.1.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /** request types */
-export declare type RequestMethod = "POST" | "GET" | "PUT" | "DELETE";
+export type RequestMethod = "POST" | "GET" | "PUT" | "DELETE";
 /** text alignment types */
-export declare type TextAlignment = "justify" | "left";
+export type TextAlignment = "justify" | "left";
 /** tool options */
 export declare const builtinTools: readonly ["Ballpoint", "Ballpointv2", "Brush", "Calligraphy", "ClearPage", "EraseSection", "Eraser", "Fineliner", "Finelinerv2", "Highlighter", "Highlighterv2", "Marker", "Markerv2", "Paintbrush", "Paintbrushv2", "Pencilv2", "SharpPencil", "SharpPencilv2", "SolidPen", "ZoomTool"];
 /** font name options */
@@ -47,7 +47,7 @@ export declare const builtinLineHeights: {
 export interface CollectionEntry {
     /** collection type */
     type: "80000000";
-    /** the hash of the file this points to */
+    /** the hash of the collection this points to */
     hash: string;
     /** the unique id of the collection */
     documentId: string;
@@ -70,26 +70,33 @@ export interface FileEntry {
     size: bigint;
 }
 /** a remarkable entry for cloud items */
-export declare type Entry = CollectionEntry | FileEntry;
+export type Entry = CollectionEntry | FileEntry;
+/** an simple entry produced by the upload api */
+export interface UploadEntry {
+    /** the document id */
+    docID: string;
+    /** the document hash */
+    hash: string;
+}
 /** common metadata for documents and collections */
 export interface CommonMetadata {
     /** name of content */
     visibleName: string;
-    /** parent uuid or "" for root or "trash" */
-    parent: string;
+    /** parent uuid (documentId) or "" for root or "trash" */
+    parent?: string;
     /** last modified time */
     lastModified: string;
-    /** unsure */
-    version: number;
-    /** unsure */
+    /** unknown significance */
+    version?: number;
+    /** unknown significance */
     pinned?: boolean;
-    /** unsure */
-    synced: boolean;
-    /** unsure */
+    /** unknown significance */
+    synced?: boolean;
+    /** unknown significance */
     modified?: boolean;
     /** if file is deleted */
     deleted?: boolean;
-    /** unsure */
+    /** unknown significance */
     metadatamodified?: boolean;
 }
 /** metadata for collection types */
@@ -111,13 +118,30 @@ export interface DocumentTypeMetadata extends CommonMetadata {
  *
  * This is found in the the `.metadata` file.
  */
-export declare type Metadata = CollectionTypeMetadata | DocumentTypeMetadata;
+export type Metadata = CollectionTypeMetadata | DocumentTypeMetadata;
+/** fields common to all {@link MetadataEntry | MetadataEntries} */
+export interface BaseMetadataEntry {
+    /** the document id of the entry */
+    id: string;
+    /** the hash of the entry */
+    hash: string;
+}
+/** the metadata entry for a collection */
+export interface CollectionMetadataEntry extends BaseMetadataEntry, CollectionTypeMetadata {
+}
+/** the metadata entry for a document */
+export interface DocumentMetadataEntry extends BaseMetadataEntry, DocumentTypeMetadata {
+    /** the type of the document */
+    fileType: FileType;
+}
+/** a full metadata entry returned by {@link RemarkableApi.getEntriesMetadata} */
+export type MetadataEntry = CollectionMetadataEntry | DocumentMetadataEntry;
 /** extra content metadata */
-export declare type ExtraMetadata = Record<string, string | undefined>;
+export type ExtraMetadata = Record<string, string | undefined>;
 /** remarkable file type; empty for notebook */
-export declare type FileType = "pdf" | "epub" | "";
+export type FileType = "notebook" | "pdf" | "epub" | "";
 /** document matrix transform */
-export declare type Transform = Record<`m${1 | 2 | 3}${1 | 2 | 3}`, number>;
+export type Transform = Record<`m${1 | 2 | 3}${1 | 2 | 3}`, number>;
 /** content document metadata */
 export interface DocumentMetadata {
     /** document title */
@@ -165,7 +189,7 @@ export interface Content {
     textAlignment?: TextAlignment;
 }
 /** anything that can be awaited */
-export declare type Awaitable<T> = T | PromiseLike<T>;
+export type Awaitable<T> = T | PromiseLike<T>;
 /** stripped down version of RequestInit */
 export interface RequestInitLike {
     /** request method */
@@ -235,28 +259,28 @@ export interface RegisterOptions {
      *
      * Using an improper one will results in the registration being rejected.
      */
-    deviceDesc?: string;
+    deviceDesc?: "desktop-windows" | "desktop-macos" | "desktop-linux" | "mobile-android" | "mobile-ios" | "browser-chrome" | "remarkable";
     /**
      * the unique id of this device
      *
      * If omitted it will be randomly generated */
     uuid?: string;
-    /** The url to user for authorization requests */
-    authUrl?: string;
+    /** The host to use for authorization requests */
+    authHost?: string;
     /** a function for making fetch requests, see {@link RemarkableOptions.fetch} for more info */
     fetch?: FetchLike;
 }
 /**
  * register a device and get the token needed to access the api
  *
- * Have users go to `https://my.remarkable.com/device/desktop/connect` and pass
+ * Have users go to `https://my.remarkable.com/device/browser/connect` and pass
  * the resulting code into this function to get a device token. Persist that
  * token to use the api.
  *
- * @param code - the eight letter code a user got from `https://my.remarkable.com/device/desktop/connect`.
+ * @param code - the eight letter code a user got from `https://my.remarkable.com/device/browser/connect`.
  * @returns the device token necessary for creating an api instace. These never expire so persist as long as necessary.
  */
-export declare function register(code: string, { deviceDesc, uuid, authUrl, fetch, }?: RegisterOptions): Promise<string>;
+export declare function register(code: string, { deviceDesc, uuid, authHost, fetch, }?: RegisterOptions): Promise<string>;
 /** options for uploading an epub document */
 export interface PutEpubOptions {
     /** the parent id, default to root */
@@ -278,6 +302,17 @@ export interface PutEpubOptions {
     /** the tool to have enabled by default */
     lastTool?: string;
 }
+/** options for uploading a pdf */
+export interface PutPdfOptions {
+    /** the parent id, default to root */
+    parent?: string | undefined;
+    /** the page orientation */
+    orientation?: "portrait" | "landscape" | undefined;
+    /** which page should be shone as the cover */
+    cover?: "first" | "visited" | undefined;
+    /** the tool to have enabled by default */
+    lastTool?: string;
+}
 /**
  * the api for accessing remarkable functions
  */
@@ -333,6 +368,23 @@ export interface RemarkableApi {
      * This is similar to `putBuffer` but will also cache the upload.
      */
     putText(documentId: string, contents: string): Promise<FileEntry>;
+    /**
+     * put metadata into the cloud
+     *
+     * This is a small wrapper around {@link RemarkableApi.putText | `putText`}.
+     *
+     * @param documentId - this should be the documentId of the item that this is
+     *   metadata for; it should not end in `.metadata`
+     * @param metadata - the metadata to upload
+     */
+    putMetadata(documentId: string, metadata: Metadata): Promise<FileEntry>;
+    /**
+     * create a new collection (folder)
+     *
+     * @param documentId - the name of the new folder
+     * @param parent - the documentId of the parent collection (folder)
+     */
+    putCollection(visibleName: string, parent?: string): Promise<CollectionEntry>;
     /**
      * upload an epub
      *
@@ -347,19 +399,98 @@ export interface RemarkableApi {
      * more information.
      *
      * ```ts
-     * const entry = await putEpub(...);
+     * const entry = await api.putEpub(...);
      * const [root, gen] = await api.getRootHash();
      * const rootEntries = await api.getEntries(root);
      * rootEntries.push(entry);
      * const { hash } = await api.putEntries("", rootEntries);
-     * await api.putRootHash(hash, gen);
+     * const nextGen = await api.putRootHash(hash, gen);
+     * await api.syncComplete(nextGen);
      * ```
      *
      * @param visibleName - the name to show for the uploaded epub
      * @param buffer - the epub contents
      * @param opts - extra options you can specify at upload
      */
-    putEpub(visibleName: string, buffer: Uint8Array, opts?: PutEpubOptions): Promise<Entry>;
+    putEpub(visibleName: string, buffer: Uint8Array, opts?: PutEpubOptions): Promise<CollectionEntry>;
+    /**
+     * upload a pdf
+     *
+     * @remarks this only uploads the raw data and returns an entry that could be
+     * uploaded as part of a larger collection. To make sure devices know about
+     * it, you'll still need to update the root hash, and potentially notify
+     * other devices.
+     *
+     * @example
+     * This example shows a full process upload. Note that it may fail if other
+     * devices are simultaneously syncing content. See {@link putRootHash} for
+     * more information.
+     *
+     * ```ts
+     * const entry = await api.putPdf(...);
+     * const [root, gen] = await api.getRootHash();
+     * const rootEntries = await api.getEntries(root);
+     * rootEntries.push(entry);
+     * const { hash } = await api.putEntries("", rootEntries);
+     * const nextGen = await api.putRootHash(hash, gen);
+     * await api.syncComplete(nextGen);
+     * ```
+     *
+     * @param visibleName - the name to show for the uploaded pdf
+     * @param buffer - the pdf contents
+     * @param opts - extra options you can specify at upload
+     */
+    putPdf(visibleName: string, buffer: Uint8Array, opts?: PutPdfOptions): Promise<CollectionEntry>;
+    /**
+     * indicate that a sync is complete and push updates to other devices
+     *
+     * @remarks after successfully putting a new root hash, use this to indicate
+     * that other devices should pick up the change.
+     */
+    syncComplete(generation: bigint): Promise<void>;
+    /**
+     * get metadata on all entries
+     *
+     * @remarks this uses a newer api, that returns metadata associated with all
+     * entries and their hash and documentId.
+     */
+    getEntriesMetadata(): Promise<MetadataEntry[]>;
+    /**
+     * upload an epub
+     *
+     * @remarks this uses a newer api that performs a full upload and sync, but
+     * doesn't allow adding the same level of extra content data. Useful if you
+     * just want to upload a document with no fuss.
+     *
+     * @example
+     * ```ts
+     * await api.uploadEpub("My EPub", ...);
+     * ```
+     *
+     * @param visibleName - the name to show for the uploaded epub
+     * @param buffer - the epub contents
+     */
+    uploadEpub(visibleName: string, buffer: Uint8Array): Promise<UploadEntry>;
+    /**
+     * upload a pdf
+     *
+     * this currently uploads invalid pdfs, but it's not clear why, which is why
+     * this is marked as experimental. Potentially some tweak in the formatting
+     * of buffer will fix it.
+     *
+     * @remarks this uses a newer api that performs a full upload and sync, but
+     * doesn't allow adding the same level of extra information.
+     *
+     * @example
+     * ```ts
+     * await api.uploadPdf("My PDF", ...);
+     * ```
+     *
+     * @param visibleName - the name to show for the uploaded epub
+     * @param buffer - the epub contents
+     * @experimental
+     */
+    uploadPdf(visibleName: string, buffer: Uint8Array): Promise<UploadEntry>;
 }
 /** format an entry */
 export declare function formatEntry({ hash, type, documentId, subfiles, size, }: Entry): string;
@@ -400,9 +531,11 @@ export interface RemarkableOptions {
      */
     subtle?: SubtleCryptoLike;
     /** the url for making authorization requests */
-    authUrl?: string;
-    /** the window for making blob requests */
-    blobUrl?: string;
+    authHost?: string;
+    /** the url for making raw document requests */
+    docHost?: string;
+    /** the url for making synchronization requests */
+    syncHost?: string;
 }
 /**
  * create an instance of the api
@@ -410,7 +543,8 @@ export interface RemarkableOptions {
  * This gets a temporary authentication token with the device token. If
  * requests start failing, simply recreate the api instance.
  *
- * @param deviceToken - the device token proving this api instance is registered. Create one with {@link register}.
+ * @param deviceToken - the device token proving this api instance is
+ *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export declare function remarkable(deviceToken: string, { fetch, cache, subtle, authUrl, blobUrl, }?: RemarkableOptions): Promise<RemarkableApi>;
+export declare function remarkable(deviceToken: string, { fetch, cache, subtle, authHost, syncHost, }?: RemarkableOptions): Promise<RemarkableApi>;