add upload api (#27)

Author: erikbrinkman

src/index.spec.ts

@@ -389,29 +389,16 @@ ${epubHash}:0:doc.epub:0:1
     const pdf = enc.encode("pdf content");
     mockFetch(
       emptyResponse(),
-      jsonResponse({
-        hash: repHash("abcd0123"),
-        generation: 0,
-        schemaVersion: 3,
-      }),
-      emptyResponse(), // .content
-      emptyResponse(), // .metadata
-      // eslint-disable-next-line spellcheck/spell-checker
-      emptyResponse(), // .pagedata
-      emptyResponse(), // .pdf
-      textResponse("3\n"),
-      emptyResponse(), // .docSchema
-      emptyResponse(), // root.docSchema
       jsonResponse({
         hash: repHash("1"),
-        generation: 1,
-      }), // root hash
+        docID: "fake pdf id",
+      }),
     );
 
     const api = await remarkable("");
     const res = await api.uploadPdf("new name", pdf);
 
-    expect(res.id).toHaveLength(36);
+    expect(res.id).toBe("fake pdf id");
     expect(res.hash).toHaveLength(64);
   });
 
@@ -451,29 +438,16 @@ ${epubHash}:0:doc.epub:0:1
     const epub = enc.encode("epub content");
     mockFetch(
       emptyResponse(),
-      jsonResponse({
-        hash: repHash("abcd0123"),
-        generation: 0,
-        schemaVersion: 3,
-      }),
-      emptyResponse(), // .content
-      emptyResponse(), // .metadata
-      // eslint-disable-next-line spellcheck/spell-checker
-      emptyResponse(), // .pagedata
-      emptyResponse(), // .epub
-      textResponse("3\n"),
-      emptyResponse(), // .docSchema
-      emptyResponse(), // root.docSchema
       jsonResponse({
         hash: repHash("1"),
-        generation: 1,
-      }), // root hash
+        docID: "fake epub id",
+      }),
     );
 
     const api = await remarkable("");
     const res = await api.uploadEpub("new name", epub);
 
-    expect(res.id).toHaveLength(36);
+    expect(res.id).toBe("fake epub id");
     expect(res.hash).toHaveLength(64);
   });
 
@@ -528,7 +502,7 @@ ${epubHash}:0:doc.epub:0:1
     );
 
     const api = await remarkable("");
-    const res = await api.createFolder("new folder");
+    const res = await api.putFolder("new folder");
 
     expect(res.id).toHaveLength(36);
     expect(res.hash).toHaveLength(64);
@@ -824,7 +798,7 @@ hash2:80000000:other:0:2
     mockFetch(emptyResponse());
 
     const api = await remarkable("");
-    expect(api.createFolder("test", { parent: "invalid" })).rejects.toThrow(
+    expect(api.putFolder("test", { parent: "invalid" })).rejects.toThrow(
       "parent must be a valid document id",
     );
   });

src/index.ts

@@ -68,6 +68,7 @@ import {
   type RawListEntry,
   type RawRemarkableApi,
   type RequestMethod,
+  type SimpleEntry,
   type Tag,
   type TemplateContent,
   type TextAlignment,
@@ -94,14 +95,17 @@ export type {
   RawFileEntry,
   RawListEntry,
   RawRemarkableApi,
+  SimpleEntry,
   Tag,
   TemplateContent,
   TextAlignment,
+  UploadMimeType,
   ZoomMode,
 } from "./raw";
 
 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 //
@@ -165,14 +169,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 */
@@ -185,6 +181,12 @@ export interface HashesEntry {
   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
@@ -285,12 +287,6 @@ export async function register(
   }
 }
 
-/** 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
  *
@@ -513,9 +509,9 @@ export interface RemarkableApi {
   ): Promise<SimpleEntry>;
 
   /** create a folder */
-  createFolder(
+  putFolder(
     visibleName: string,
-    opts?: UploadOptions,
+    opts?: FolderOptions,
     refresh?: boolean,
   ): Promise<SimpleEntry>;
 
@@ -528,16 +524,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
@@ -548,16 +540,15 @@ 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
@@ -739,6 +730,7 @@ class Remarkable implements RemarkableApi {
   constructor(
     userToken: string,
     rawHost: string,
+    uploadHost: string,
     cache: Map<string, string | null>,
   ) {
     this.#userToken = userToken;
@@ -748,6 +740,7 @@ class Remarkable implements RemarkableApi {
         this.#authedFetch(url, { method, body, headers }),
       cache,
       rawHost,
+      uploadHost,
     );
   }
 
@@ -815,8 +808,6 @@ class Remarkable implements RemarkableApi {
     const contentEnt = entries.find((ent) => ent.id.endsWith(".content"));
     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 [
@@ -832,7 +823,10 @@ class Remarkable implements RemarkableApi {
       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 {
@@ -1074,9 +1068,9 @@ class Remarkable implements RemarkableApi {
   }
 
   /** create a folder */
-  async createFolder(
+  async putFolder(
     visibleName: string,
-    { parent = "" }: UploadOptions = {},
+    { parent = "" }: FolderOptions = {},
     refresh: boolean = false,
   ): Promise<SimpleEntry> {
     if (parent && !idReg.test(parent)) {
@@ -1142,18 +1136,25 @@ class Remarkable implements RemarkableApi {
   async uploadEpub(
     visibleName: string,
     buffer: Uint8Array,
-    opts: UploadOptions = {},
   ): Promise<SimpleEntry> {
-    return await this.putEpub(visibleName, buffer, opts);
+    return await this.raw.uploadFile(
+      visibleName,
+      buffer,
+      "application/epub+zip",
+    );
   }
 
   /** upload a pdf */
   async uploadPdf(
     visibleName: string,
     buffer: Uint8Array,
-    opts: UploadOptions = {},
   ): Promise<SimpleEntry> {
-    return await this.putPdf(visibleName, buffer, opts);
+    return await this.raw.uploadFile(visibleName, buffer, "application/pdf");
+  }
+
+  /** upload a folder */
+  async uploadFolder(visibleName: string): Promise<SimpleEntry> {
+    return await this.raw.uploadFile(visibleName, new Uint8Array(0), "folder");
   }
 
   /** edit just a content entry */
@@ -1437,6 +1438,13 @@ export interface RemarkableOptions {
    */
   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
    *
@@ -1484,6 +1492,7 @@ export async function remarkable(
   {
     authHost = AUTH_HOST,
     rawHost = RAW_HOST,
+    uploadHost = UPLOAD_HOST,
     cache,
     maxCacheSize = Infinity,
   }: RemarkableOptions = {},
@@ -1505,7 +1514,7 @@ export async function remarkable(
       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.",