rmapi-js 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,404 @@
+/** request types */
+export declare type RequestMethod = "POST" | "GET" | "PUT" | "DELETE";
+/** text alignment types */
+export declare 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 */
+export declare const builtinFontNames: readonly ["Maison Neue", "EB Garamond", "Noto Sans", "Noto Serif", "Noto Mono", "Noto Sans UI"];
+/** text scale options */
+export declare const builtinTextScales: {
+    /** the smallest */
+    readonly xs: 0.7;
+    /** small */
+    readonly sm: 0.8;
+    /** medium / default */
+    readonly md: 1;
+    /** large */
+    readonly lg: 1.2;
+    /** extra large */
+    readonly xl: 1.5;
+    /** double extra large */
+    readonly xx: 2;
+};
+/** margin options */
+export declare const builtinMargins: {
+    /** small */
+    readonly sm: 50;
+    /** medium */
+    readonly md: 125;
+    /** default for read on remarkable */
+    readonly rr: 180;
+    /** large */
+    readonly lg: 200;
+};
+/** line height options */
+export declare const builtinLineHeights: {
+    /** default */
+    readonly df: -1;
+    /** normal */
+    readonly md: 100;
+    /** half */
+    readonly lg: 150;
+    /** double */
+    readonly xl: 200;
+};
+/** a remarkable entry for a cloud collection */
+export interface CollectionEntry {
+    /** collection type */
+    type: "80000000";
+    /** the hash of the file this points to */
+    hash: string;
+    /** the unique id of the collection */
+    documentId: string;
+    /** the number of subfiles */
+    subfiles: number;
+    /** collections don't have sizes */
+    size: 0n;
+}
+/** a remarkable entry for cloud data */
+export interface FileEntry {
+    /** file type */
+    type: "0";
+    /** the hash of the file this points to */
+    hash: string;
+    /** the unique id of the file */
+    documentId: string;
+    /** files don't have subfiles */
+    subfiles: 0;
+    /** size of the file */
+    size: bigint;
+}
+/** a remarkable entry for cloud items */
+export declare type Entry = CollectionEntry | FileEntry;
+/** common metadata for documents and collections */
+export interface CommonMetadata {
+    /** name of content */
+    visibleName: string;
+    /** parent uuid or "" for root or "trash" */
+    parent: string;
+    /** last modified time */
+    lastModified: string;
+    /** unsure */
+    version: number;
+    /** unsure */
+    pinned?: boolean;
+    /** unsure */
+    synced: boolean;
+    /** unsure */
+    modified?: boolean;
+    /** if file is deleted */
+    deleted?: boolean;
+    /** unsure */
+    metadatamodified?: boolean;
+}
+/** metadata for collection types */
+export interface CollectionTypeMetadata extends CommonMetadata {
+    /** the key for collection types */
+    type: "CollectionType";
+}
+/** metadata for document types */
+export interface DocumentTypeMetadata extends CommonMetadata {
+    /** the key for document types */
+    type: "DocumentType";
+    /** last opened time for documents */
+    lastOpened?: string;
+    /** last opened page for documents */
+    lastOpenedPage?: number;
+}
+/**
+ * metadata for a document or collection (folder)
+ *
+ * This is found in the the `.metadata` file.
+ */
+export declare type Metadata = CollectionTypeMetadata | DocumentTypeMetadata;
+/** extra content metadata */
+export declare type ExtraMetadata = Record<string, string | undefined>;
+/** remarkable file type; empty for notebook */
+export declare type FileType = "pdf" | "epub" | "";
+/** document matrix transform */
+export declare type Transform = Record<`m${1 | 2 | 3}${1 | 2 | 3}`, number>;
+/** content document metadata */
+export interface DocumentMetadata {
+    /** document title */
+    title?: string;
+    /** document authors */
+    authors?: string[];
+}
+/**
+ * content metadata
+ *
+ * This is found in the `.content` file.
+ */
+export interface Content {
+    /** is this a dummy document */
+    dummyDocument: boolean;
+    /** document metadata */
+    documentMetadata?: DocumentMetadata;
+    /** extra metadata */
+    extraMetadata: ExtraMetadata;
+    /** file type */
+    fileType: FileType;
+    /** font */
+    fontName?: string;
+    /** last opened page */
+    lastOpenedPage: number;
+    /** line height */
+    lineHeight: number;
+    /** page margins in points */
+    margins: number;
+    /** orientation */
+    orientation?: "portrait" | "landscape";
+    /** number of pages */
+    pageCount: number;
+    /** page ids */
+    pages: string[];
+    /** number to use for the coverage page, -1 for last opened */
+    coverPageNumber: number;
+    /** text scale */
+    textScale: number;
+    /** page transform */
+    transform?: Transform;
+    /** format version */
+    formatVersion: number;
+    /** text alignment */
+    textAlignment?: TextAlignment;
+}
+/** anything that can be awaited */
+export declare type Awaitable<T> = T | PromiseLike<T>;
+/** stripped down version of RequestInit */
+export interface RequestInitLike {
+    /** request method */
+    readonly method?: RequestMethod | undefined;
+    /** request headers */
+    readonly headers?: Record<string, string>;
+    /** request body */
+    readonly body?: ArrayBuffer | string;
+}
+/** stripped down version of Headers */
+export interface HeadersLike {
+    /** get a specific header value */
+    get(key: string): string | null;
+}
+/** stripped down version of Response */
+export interface ResponseLike {
+    /** true if request was successful */
+    ok: boolean;
+    /** http status */
+    status: number;
+    /** text associated with status */
+    statusText: string;
+    /** headers in response */
+    headers: HeadersLike;
+    /** get response body as text */
+    text(): Awaitable<string>;
+    /** get response body as an array buffer */
+    arrayBuffer(): Awaitable<ArrayBuffer>;
+}
+/** stripped down version of fetch */
+export interface FetchLike {
+    (url: string, options?: RequestInitLike | undefined): Awaitable<ResponseLike>;
+}
+/** async storage, map like */
+export interface CacheLike {
+    /** get value for key or undefined if missing */
+    get(key: string): Awaitable<string | undefined>;
+    /** set value for key */
+    set(key: string, value: string): Awaitable<void>;
+}
+/** stripped down version of subtle crypto */
+export interface SubtleCryptoLike {
+    /** a digest function */
+    digest(algorithm: "SHA-256", data: ArrayBuffer): Promise<ArrayBuffer>;
+}
+/** an error that results from a failed request */
+export declare class ResponseError extends Error {
+    /** the response status number */
+    readonly status: number;
+    /** the response status text */
+    readonly statusText: string;
+    constructor(status: number, statusText: string, message: string);
+}
+/**
+ * an error that results from trying yp update the wrong generation.
+ *
+ * If we try to update the root hash of files, but the generation has changed
+ * relative to the one we're updating from, this will fail.
+ */
+export declare class GenerationError extends Error {
+    constructor();
+}
+/** options for registering with the api */
+export interface RegisterOptions {
+    /**
+     * the device description to use
+     *
+     * Using an improper one will results in the registration being rejected.
+     */
+    deviceDesc?: string;
+    /**
+     * the unique id of this device
+     *
+     * If omitted it will be randomly generated */
+    uuid?: string;
+    /** The url to user for authorization requests */
+    authUrl?: 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
+ * 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`.
+ * @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>;
+/** options for uploading an epub document */
+export interface PutEpubOptions {
+    /** the parent id, default to root */
+    parent?: string | undefined;
+    /** the margins of the epub 180 is good for articles, 125 for books */
+    margins?: number | keyof typeof builtinMargins | undefined;
+    /** the height of lines */
+    lineHeight?: number | keyof typeof builtinLineHeights | undefined;
+    /** the scale of text */
+    textScale?: number | keyof typeof builtinTextScales | undefined;
+    /** the page orientation */
+    orientation?: "portrait" | "landscape" | undefined;
+    /** the text alignment */
+    textAlignment?: TextAlignment | undefined;
+    /** which page should be shone as the cover */
+    cover?: "first" | "visited" | undefined;
+    /** the font name, should probably come from `builtinFontNames` */
+    fontName?: string | undefined;
+    /** the tool to have enabled by default */
+    lastTool?: string;
+    /** set to false to disable notifying other clients of the update */
+    notify?: boolean | undefined;
+    /**
+     * set number of retries for publish
+     *
+     * The final part of uploading involves update the root hash to include the
+     * new contents. If several places are attempting to change content this will
+     * fail, so setting a positive number of retries here causes it to retry that
+     * final step.
+     */
+    retries?: number | undefined;
+}
+/**
+ * the api for accessing remarkable functions
+ */
+export interface RemarkableApi {
+    /** sends a signal to the server that a sync is complete and other devices should update */
+    syncComplete(): Promise<void>;
+    /**
+     * get the root hash and the current generation
+     *
+     * If this hasn't changed, then neither have any of the files.
+     */
+    getRootHash(): Promise<[string, bigint]>;
+    /**
+     * write the root hash, incrimenting from the current generation
+     *
+     * This will fail if the current generation isn't equal to the passed in
+     * generation. Use this to preven race conditions. If this rejects, refetch
+     * the root hash, resync the updates, and then try to put again.
+     *
+     * @param hash - the hash of the new root collection
+     * @param generation - the current generation this builds off of
+     * @returns the new generation
+     */
+    putRootHash(hash: string, generation: bigint): Promise<bigint>;
+    /**
+     * get array buffer associated with a hash
+     *
+     * @param hash - the hash to get text data from
+     */
+    getBuffer(hash: string): Promise<ArrayBuffer>;
+    /**
+     * get text content associated with hash
+     *
+     * This call uses the cache if provided since contents of a specific hash
+     * should never change. This isn't atomic so calling with the same hash in
+     * quick succession could result in two requests being fired instead of the
+     * second waiting for the first.
+     *
+     * @param hash - the hash to get text data from
+     */
+    getText(hash: string): Promise<string>;
+    /** get metadata from hash */
+    getMetadata(hash: string): Promise<Metadata>;
+    /** get entries from a collection hash */
+    getEntries(hash: string): Promise<Entry[]>;
+    /** put a reference to a set of entries into the cloud */
+    putEntries(documentId: string, entries: Entry[]): Promise<CollectionEntry>;
+    /** put a raw buffer in the cloud */
+    putBuffer(documentId: string, buffer: Uint8Array): Promise<FileEntry>;
+    /**
+     * put a raw text in the cloud
+     *
+     * This is similar to `putBuffer` but will also cache the upload.
+     */
+    putText(documentId: string, contents: string): Promise<FileEntry>;
+    /**
+     * upload an epub
+     *
+     * @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<void>;
+}
+/** options for a remarkable instance */
+export interface RemarkableOptions {
+    /**
+     * the fetch method to use
+     *
+     * This should loosely conform to the WHATWG fetch, but is relaxed enough that
+     * node-fetch also works. This will default to the global definitions of
+     * fetch.
+     *
+     * In node you can either use `"node-fetch"`, or `node --experimental-fetch`
+     * for node 17.5 or higher.
+     */
+    fetch?: FetchLike;
+    /**
+     * an optional cache for text requests
+     *
+     * If you're using the api to sync between a local copy and the cloud, you'll
+     * want to keep a cache so that as long as a file's hash doesn't change you
+     * don't need to request another copy.
+     *
+     * @remarks currently there are no mechanisms that actually clear the cache,
+     * so be warned if the cache doesn't have an auto clearning mechansim that
+     * some old files may stay around for quite a while
+     */
+    cache?: CacheLike;
+    /**
+     * a subtle-crypto-like object
+     *
+     * This should have a digest function like the api of `crypto.subtle`, it's
+     * default value.  In node try
+     * `import { webcrypto } from "crypto"; global.crypto = webcrypto` or pass in
+     * `webcrypto.subtle`.
+     */
+    subtle?: SubtleCryptoLike;
+    /** the url for making authorization requests */
+    authUrl?: string;
+    /** the window for making blob requests */
+    blobUrl?: string;
+}
+/**
+ * create an instance of the api
+ *
+ * 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}.
+ * @returns an api instance
+ */
+export declare function remarkable(deviceToken: string, { fetch, cache, subtle, authUrl, blobUrl, }?: RemarkableOptions): Promise<RemarkableApi>;