rmapi-js 8.2.0 → 8.4.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { type BackgroundFilter, type CollectionContent, type Content, type DocumentContent, type Metadata, type Orientation, type RawRemarkableApi, type Tag, type TemplateContent, type TextAlignment, type ZoomMode } from "./raw";
+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";
 export { HashNotFoundError, ValidationError } from "./error";
-export type { BackgroundFilter, CollectionContent, Content, CPageNumberValue, CPagePage, CPages, CPageStringValue, CPageUUID, DocumentContent, DocumentMetadata, FileType, KeyboardMetadata, Metadata, Orientation, PageTag, RawEntry, RawFileEntry, RawListEntry, RawRemarkableApi, Tag, TemplateContent, TextAlignment, ZoomMode, } from "./raw";
+export type { BackgroundFilter, CollectionContent, Content, CPageNumberValue, CPagePage, CPages, CPageStringValue, CPageUUID, DocumentContent, DocumentMetadata, FileType, KeyboardMetadata, Metadata, Orientation, PageTag, RawEntry, RawFileEntry, RawListEntry, RawRemarkableApi, SimpleEntry, Tag, TemplateContent, TextAlignment, UploadMimeType, ZoomMode, } from "./raw";
 /** common properties shared by collections and documents */
 export interface EntryCommon {
     /** the document id, a uuid4 */
@@ -50,13 +50,6 @@ export interface TemplateType extends EntryCommon {
 }
 /** a remarkable entry for cloud items */
 export type Entry = CollectionEntry | DocumentType | TemplateType;
-/** an simple entry without any extra information */
-export interface SimpleEntry {
-    /** the document id */
-    id: string;
-    /** the document hash */
-    hash: string;
-}
 /** the new hash of a modified entry */
 export interface HashEntry {
     /** the actual hash */
@@ -67,6 +60,11 @@ 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;
+}
 /** 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
@@ -114,11 +112,6 @@ export interface RegisterOptions {
  * @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, authHost, }?: RegisterOptions): Promise<string>;
-/** options available when uploading a document */
-export interface UploadOptions {
-    /** an optional parent id to set when uploading */
-    parent?: string;
-}
 /**
  * options for putting a file onto reMarkable
  *
@@ -322,7 +315,7 @@ export interface RemarkableApi {
      */
     putEpub(visibleName: string, buffer: Uint8Array, opts?: PutOptions): Promise<SimpleEntry>;
     /** create a folder */
-    createFolder(visibleName: string, opts?: UploadOptions, refresh?: boolean): Promise<SimpleEntry>;
+    putFolder(visibleName: string, opts?: FolderOptions, refresh?: boolean): Promise<SimpleEntry>;
     /**
      * upload an epub
      *
@@ -332,12 +325,12 @@ export interface RemarkableApi {
      * ```
      *
      * @remarks
-     * this is now simply a less powerful version of {@link putEpub | `putEpub`}.
+     * this uses a simpler api that works even with schema version 4.
      *
      * @param visibleName - the name to show for the uploaded epub
      * @param buffer - the epub contents
      */
-    uploadEpub(visibleName: string, buffer: Uint8Array, opts?: UploadOptions): Promise<SimpleEntry>;
+    uploadEpub(visibleName: string, buffer: Uint8Array): Promise<SimpleEntry>;
     /**
      * upload a pdf
      *
@@ -347,12 +340,14 @@ export interface RemarkableApi {
      * ```
      *
      * @remarks
-     * this is now simply a less powerful version of {@link putPdf | `putPdf`}.
+     * this uses a simpler api that works even with schema version 4.
      *
      * @param visibleName - the name to show for the uploaded epub
      * @param buffer - the epub contents
      */
-    uploadPdf(visibleName: string, buffer: Uint8Array, opts?: UploadOptions): Promise<SimpleEntry>;
+    uploadPdf(visibleName: string, buffer: Uint8Array): Promise<SimpleEntry>;
+    /** create a folder using the simple api */
+    uploadFolder(visibleName: string): Promise<SimpleEntry>;
     /**
      * update content metadata for a document
      *
@@ -501,6 +496,12 @@ export interface RemarkableOptions {
      * @defaultValue "https://web.eu.tectonic.remarkable.com"
      */
     syncHost?: string;
+    /**
+     * the base url for making upload requests
+     *
+     * @defaultValue "https://internal.cloud.remarkable.com"
+     */
+    uploadHost?: string;
     /**
      * the url for making requests using the low-level api
      *
@@ -535,4 +536,4 @@ export interface RemarkableOptions {
  *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export declare function remarkable(deviceToken: string, { authHost, rawHost, cache, maxCacheSize, }?: RemarkableOptions): Promise<RemarkableApi>;
+export declare function remarkable(deviceToken: string, { authHost, rawHost, uploadHost, cache, maxCacheSize, }?: RemarkableOptions): Promise<RemarkableApi>;

package/dist/index.js

@@ -60,6 +60,7 @@ import { RawRemarkable, } from "./raw";
 export { HashNotFoundError, ValidationError } from "./error";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
 const RAW_HOST = "https://eu.tectonic.remarkable.com";
+const UPLOAD_HOST = "https://internal.cloud.remarkable.com";
 // ------------ //
 // Request Info //
 // ------------ //
@@ -130,10 +131,10 @@ class Remarkable {
     #cache;
     raw;
     #lastHashGen;
-    constructor(userToken, rawHost, cache) {
+    constructor(userToken, rawHost, uploadHost, cache) {
         this.#userToken = userToken;
         this.#cache = cache;
-        this.raw = new RawRemarkable((method, url, { body, headers } = {}) => this.#authedFetch(url, { method, body, headers }), cache, rawHost);
+        this.raw = new RawRemarkable((method, url, { body, headers } = {}) => this.#authedFetch(url, { method, body, headers }), cache, rawHost, uploadHost);
     }
     async #getRootHash(refresh = false) {
         if (refresh || this.#lastHashGen === undefined) {
@@ -160,7 +161,8 @@ class Remarkable {
                 Authorization: `Bearer ${this.#userToken}`,
                 ...headers,
             },
-            body,
+            // fetch works correctly with uint8 arrays, but is not hinted correctly
+            body: body,
         });
         if (!resp.ok) {
             const msg = await resp.text();
@@ -182,12 +184,12 @@ class Remarkable {
         if (metaEnt === undefined) {
             throw new Error(`couldn't find metadata for hash ${hash}`);
         }
-        else if (contentEnt === undefined) {
-            throw new Error(`couldn't find content for hash ${hash}`);
-        }
         const [{ visibleName, lastModified, pinned, parent, lastOpened, new: isNew, source, }, content,] = await Promise.all([
             this.raw.getMetadata(metaEnt.hash),
-            this.raw.getContent(contentEnt.hash),
+            // collections don't always have content, since content only lists tags
+            contentEnt === undefined
+                ? Promise.resolve({ fileType: undefined, tags: undefined })
+                : this.raw.getContent(contentEnt.hash),
         ]);
         if ("templateVersion" in content) {
             return {
@@ -373,7 +375,7 @@ class Remarkable {
         return await this.#putFile(visibleName, "epub", buffer, opts);
     }
     /** create a folder */
-    async createFolder(visibleName, { parent = "" } = {}, refresh = false) {
+    async putFolder(visibleName, { parent = "" } = {}, refresh = false) {
         if (parent && !idReg.test(parent)) {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
@@ -416,12 +418,16 @@ class Remarkable {
         return { id, hash: collectionEntry.hash };
     }
     /** upload an epub */
-    async uploadEpub(visibleName, buffer, opts = {}) {
-        return await this.putEpub(visibleName, buffer, opts);
+    async uploadEpub(visibleName, buffer) {
+        return await this.raw.uploadFile(visibleName, buffer, "application/epub+zip");
     }
     /** upload a pdf */
-    async uploadPdf(visibleName, buffer, opts = {}) {
-        return await this.putPdf(visibleName, buffer, opts);
+    async uploadPdf(visibleName, buffer) {
+        return await this.raw.uploadFile(visibleName, buffer, "application/pdf");
+    }
+    /** upload a folder */
+    async uploadFolder(visibleName) {
+        return await this.raw.uploadFile(visibleName, new Uint8Array(0), "folder");
     }
     /** edit just a content entry */
     async #editContentRaw(id, hash, update) {
@@ -599,7 +605,7 @@ const cached = values(nullable(string()));
  *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export async function remarkable(deviceToken, { authHost = AUTH_HOST, rawHost = RAW_HOST, cache, maxCacheSize = Infinity, } = {}) {
+export async function remarkable(deviceToken, { authHost = AUTH_HOST, rawHost = RAW_HOST, uploadHost = UPLOAD_HOST, cache, maxCacheSize = Infinity, } = {}) {
     const resp = await fetch(`${authHost}/token/json/2/user/new`, {
         method: "POST",
         headers: {
@@ -616,7 +622,7 @@ export async function remarkable(deviceToken, { authHost = AUTH_HOST, rawHost =
         const cache = maxCacheSize === Infinity
             ? new Map(entries)
             : new LruCache(maxCacheSize, entries);
-        return new Remarkable(userToken, rawHost, cache);
+        return new Remarkable(userToken, rawHost, uploadHost, cache);
     }
     else {
         throw new Error("cache was not a valid cache (json string mapping); your cache must be corrupted somehow. Either initialize remarkable without a cache, or fix its format.");

package/dist/raw.d.ts

@@ -1,5 +1,14 @@
 /** request types */
 export type RequestMethod = "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+/** the supported upload mime types */
+export type UploadMimeType = "application/pdf" | "application/epub+zip" | "folder";
+/** an simple entry without any extra information */
+export interface SimpleEntry {
+    /** the document id */
+    id: string;
+    /** the document hash */
+    hash: string;
+}
 /**
  * the low-level entry corresponding to a collection of files
  *
@@ -167,7 +176,7 @@ export interface DocumentContent {
      */
     fontName: string;
     /** the format version, this should always be 1 */
-    formatVersion: number;
+    formatVersion?: number;
     /** the last opened page, starts at zero */
     lastOpenedPage?: number;
     /**
@@ -210,17 +219,37 @@ export interface DocumentContent {
      * values outside of this range are valid.
      */
     textScale: number;
-    /** [speculative] the center of the zoom for zoomed in documents */
+    /**
+     * the center of the zoom for customFit zoom
+     *
+     * This is an absolute offset from the center of the page. Negative numbers
+     * indicate shifted left and positive numbers indicate shifted right. The
+     * units are relative to the document pixels, but it's not sure how the
+     * document size is calculated.
+     */
     customZoomCenterX?: number;
-    /** [speculative] the center of the zoom for zoomed in documents */
+    /**
+     * the center of the zoom for customFit documents
+     *
+     * This is an absolute number relative to the top of the page. Negative
+     * numbers indicate shifted up, while positive numbers indicate shifted down.
+     * The units are relative to the document pixels, but it's not sure how the
+     * document size is calculated.
+     */
     customZoomCenterY?: number;
-    /** [speculative] the orientation */
+    /** this seems unused */
     customZoomOrientation?: Orientation;
-    /** [speculative] the zoom height for zoomed in pages */
+    /** this seems unused */
     customZoomPageHeight?: number;
-    /** [speculative] the zoom width for zoomed in pages */
+    /** this seems unused */
     customZoomPageWidth?: number;
-    /** [speculative] the scale for zoomed in pages */
+    /**
+     * the scale for customFit documents
+     *
+     * 1 indicates no zoom, smaller numbers indicate zoomed out, larger numbers
+     * indicate zoomed in. reMarkable generally allows setting this from 0.5 to 5,
+     * but values outside that bound are still supported.
+     */
     customZoomScale?: number;
     /** what zoom mode is set for the page */
     zoomMode?: ZoomMode;
@@ -261,7 +290,7 @@ export interface TemplateContent {
     /** semantic version for this template */
     templateVersion: string;
     /** template configuration format version (currently just `1`) */
-    formatVersion: number;
+    formatVersion?: number;
     /**
      * which screens the template supports:
      *
@@ -498,9 +527,24 @@ export interface RawRemarkableApi {
      * @param id - the id of the list to upload - this should be the item id if
      *   uploading an item list, or "root" if uploading a new root list.
      * @param entries - the entries to upload
+     *
      * @returns the new list entry and a promise to finish the upload
      */
     putEntries(id: string, entries: RawEntry[]): Promise<[RawListEntry, Promise<void>]>;
+    /**
+     * upload a file to the reMarkable cloud using the simple api
+     *
+     * This api is the same as used by the native reMarkable extension and works
+     * even if the backend schema version is version 4. Setting mime to "folder"
+     * allows folder creation.
+     *
+     * @param visibleName - the name of the file as it should appear on the reMarkable
+     * @param bytes - the bytes of the file to upload
+     * @param mime - the mime type of the file to upload
+     
+     * @returns a simple entry with the id and hash of the uploaded file
+     */
+    uploadFile(visibleName: string, bytes: Uint8Array, mime: UploadMimeType): Promise<SimpleEntry>;
     /**
      * dump the current cache to a string to preserve between session
      *
@@ -518,7 +562,7 @@ interface AuthedFetch {
 }
 export declare class RawRemarkable implements RawRemarkableApi {
     #private;
-    constructor(authedFetch: AuthedFetch, cache: Map<string, string | null>, rawHost: string);
+    constructor(authedFetch: AuthedFetch, cache: Map<string, string | null>, rawHost: string, uploadHost: string);
     /** make an authorized request to remarkable */
     getRootHash(): Promise<[string, number]>;
     getHash(hash: string): Promise<Uint8Array>;
@@ -532,6 +576,7 @@ export declare class RawRemarkable implements RawRemarkableApi {
     putContent(id: string, content: Content): Promise<[RawFileEntry, Promise<void>]>;
     putMetadata(id: string, metadata: Metadata): Promise<[RawFileEntry, Promise<void>]>;
     putEntries(id: string, entries: RawEntry[]): Promise<[RawListEntry, Promise<void>]>;
+    uploadFile(visibleName: string, bytes: Uint8Array, mime: UploadMimeType): Promise<SimpleEntry>;
     dumpCache(): string;
     clearCache(): void;
 }

package/dist/raw.js

@@ -70,7 +70,6 @@ const documentContent = properties({
     extraMetadata: values(string()),
     fileType: enumeration("epub", "notebook", "pdf"),
     fontName: string(),
-    formatVersion: uint8(),
     lineHeight: int32(),
     orientation: enumeration("portrait", "landscape"),
     pageCount: uint32(),
@@ -86,6 +85,7 @@ const documentContent = properties({
     customZoomPageWidth: float64(),
     customZoomScale: float64(),
     dummyDocument: boolean(),
+    formatVersion: uint8(),
     keyboardMetadata: properties({
         count: uint32(),
         timestamp: float64(),
@@ -120,10 +120,11 @@ const templateContent = properties({
     labels: elements(string()),
     orientation: enumeration("portrait", "landscape"),
     templateVersion: string(),
-    formatVersion: uint8(),
     supportedScreens: elements(enumeration("rm2", "rmPP")),
     constants: elements(values(int32())),
     items: elements(empty()),
+}, {
+    formatVersion: uint8(),
 });
 const metadata = properties({
     lastModified: string(),
@@ -150,8 +151,14 @@ const rootHash = properties({
     generation: float64(),
     schemaVersion: uint8(),
 }, undefined, true);
+const NativeSimpleEntry = properties({
+    docID: string(),
+    hash: string(),
+}, undefined, true);
 async function digest(buff) {
-    const digest = await crypto.subtle.digest("SHA-256", buff);
+    const digest = await crypto.subtle.digest("SHA-256", 
+    // NOTE this is type hinted wrong, but it does work correctly on a uint8 view
+    buff);
     return [...new Uint8Array(digest)]
         .map((x) => x.toString(16).padStart(2, "0"))
         .join("");
@@ -159,6 +166,7 @@ async function digest(buff) {
 export class RawRemarkable {
     #authedFetch;
     #rawHost;
+    #uploadHost;
     /**
      * a cache of all hashes we know exist
      *
@@ -169,10 +177,11 @@ export class RawRemarkable {
      * not to write a a cached value again, but we'll still need to read it.
      */
     #cache;
-    constructor(authedFetch, cache, rawHost) {
+    constructor(authedFetch, cache, rawHost, uploadHost) {
         this.#authedFetch = authedFetch;
         this.#cache = cache;
         this.#rawHost = rawHost;
+        this.#uploadHost = uploadHost;
     }
     /** make an authorized request to remarkable */
     async getRootHash() {
@@ -417,6 +426,23 @@ export class RawRemarkable {
             this.#putFile(hash, `${id}.docSchema`, enc.encode(records.join(""))),
         ];
     }
+    async uploadFile(visibleName, bytes, mime) {
+        const enc = new TextEncoder();
+        const meta = fromByteArray(enc.encode(JSON.stringify({ file_name: visibleName })));
+        const resp = await this.#authedFetch("POST", `${this.#uploadHost}/doc/v2/files`, {
+            body: bytes,
+            headers: {
+                "Content-Type": mime,
+                "rm-meta": meta,
+                "rm-source": "RoR-Browser",
+            },
+        });
+        const loaded = (await resp.json());
+        if (!NativeSimpleEntry.guardAssert(loaded))
+            throw Error("invalid upload response");
+        const { docID, hash } = loaded;
+        return { id: docID, hash };
+    }
     dumpCache() {
         return JSON.stringify(Object.fromEntries(this.#cache));
     }