rmapi-js 8.3.0 → 8.5.0

package/README.md

@@ -21,19 +21,28 @@ and folders ("collections"). The hash indicates the full current state to manage
 ## Usage
 
 To explore files in the cloud, you need to first register your api and persist
-the token. Then you can use `listFiles` to explore entries of different file
+the token. Then you can use `listItems` to explore entries of different file
 collections.
 
 ```ts
-import { register, remarkable } from "rmapi-js";
+import { auth, register, remarkable, session } from "rmapi-js";
 
 const code = "..."; // eight letter code from https://my.remarkable.com/device/desktop/connect
 const token = await register(code);
 // persist token so you don't have to register again
 const api = await remarkable(token);
-const fileEntries = await api.listFiles();
+const fileEntries = await api.listItems();
+
+// In stateless environments, exchange once and reuse.
+const sessionToken = await auth(token);
+const api = session(sessionToken);
+// cache `sessionToken` and reuse it across workers
 ```
 
+`auth` performs the same network call that `remarkable` does for you internally,
+returning a short-lived session token. `session` is synchronous,
+letting you construct clients from cached tokens without making a network call.
+
 To upload an epub or pdf, simply call upload with the appropriate name and buffer.
 
 ```ts
@@ -53,7 +62,7 @@ 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 pdf, using the hash (from listFiles)
+// fetch an uploaded pdf, using the hash (from listItems)
 const buffer = await api.getEpub(hash)
 ```
 

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, CPageStringValue, CPages, 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
      *
@@ -487,20 +482,29 @@ export interface RemarkableApi {
      */
     clearCache(): void;
 }
-/** options for a remarkable instance */
-export interface RemarkableOptions {
+/** configuration for exchanging a device token */
+export interface AuthOptions {
     /**
      * the url for making authorization requests
      *
      * @defaultValue "https://webapp-prod.cloud.remarkable.engineering"
      */
     authHost?: string;
+}
+/** options for constructing an api instance from a session token */
+export interface RemarkableSessionOptions {
     /**
      * the url for making synchronization requests
      *
      * @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
      *
@@ -525,14 +529,35 @@ export interface RemarkableOptions {
      */
     maxCacheSize?: number;
 }
+/** options for a remarkable instance */
+export interface RemarkableOptions extends AuthOptions, RemarkableSessionOptions {
+}
+/**
+ * Exchange a device token for a session token.
+ *
+ * @param deviceToken - the device token proving this api instance is
+ *    registered. Create one with {@link register}.
+ * @returns the session token returned by the reMarkable service
+ */
+export declare function auth(deviceToken: string, { authHost }?: AuthOptions): Promise<string>;
+/**
+ * Create an API instance from an existing session token.
+ *
+ * If requests start failing, simply recreate the api instance with a freshly
+ * fetched session token.
+ *
+ * @param sessionToken - the session token used for authorization
+ * @returns an api instance
+ */
+export declare function session(sessionToken: string, { rawHost, uploadHost, cache, maxCacheSize, }?: RemarkableSessionOptions): RemarkableApi;
 /**
  * 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.
+ * This gets a temporary authentication token with the device token and then
+ * constructs 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, { authHost, rawHost, cache, maxCacheSize, }?: RemarkableOptions): Promise<RemarkableApi>;
+export declare function remarkable(deviceToken: string, options?: 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 //
 // ------------ //
@@ -125,15 +126,15 @@ export async function register(code, { deviceDesc = "browser-chrome", uuid = uui
 }
 /** the implementation of that api */
 class Remarkable {
-    #userToken;
+    #sessionToken;
     /** the same cache that underlies the raw api, allowing us to modify it */
     #cache;
     raw;
     #lastHashGen;
-    constructor(userToken, rawHost, cache) {
-        this.#userToken = userToken;
+    constructor(sessionToken, rawHost, uploadHost, cache) {
+        this.#sessionToken = sessionToken;
         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) {
@@ -157,10 +158,11 @@ class Remarkable {
         const resp = await fetch(url, {
             method,
             headers: {
-                Authorization: `Bearer ${this.#userToken}`,
+                Authorization: `Bearer ${this.#sessionToken}`,
                 ...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) {
@@ -590,16 +596,13 @@ class Remarkable {
 }
 const cached = values(nullable(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.
+ * Exchange a device token for a session token.
  *
  * @param deviceToken - the device token proving this api instance is
  *    registered. Create one with {@link register}.
- * @returns an api instance
+ * @returns the session token returned by the reMarkable service
  */
-export async function remarkable(deviceToken, { authHost = AUTH_HOST, rawHost = RAW_HOST, cache, maxCacheSize = Infinity, } = {}) {
+export async function auth(deviceToken, { authHost = AUTH_HOST } = {}) {
     const resp = await fetch(`${authHost}/token/json/2/user/new`, {
         method: "POST",
         headers: {
@@ -609,16 +612,46 @@ export async function remarkable(deviceToken, { authHost = AUTH_HOST, rawHost =
     if (!resp.ok) {
         throw new Error(`couldn't fetch auth token: ${resp.statusText}`);
     }
-    const userToken = await resp.text();
+    return await resp.text();
+}
+/**
+ * Create an API instance from an existing session token.
+ *
+ * If requests start failing, simply recreate the api instance with a freshly
+ * fetched session token.
+ *
+ * @param sessionToken - the session token used for authorization
+ * @returns an api instance
+ */
+export function session(sessionToken, { rawHost = RAW_HOST, uploadHost = UPLOAD_HOST, cache, maxCacheSize = Infinity, } = {}) {
     const initCache = JSON.parse(cache ?? "{}");
     if (cached.guard(initCache)) {
         const entries = Object.entries(initCache);
-        const cache = maxCacheSize === Infinity
+        const cacheMap = maxCacheSize === Infinity
             ? new Map(entries)
             : new LruCache(maxCacheSize, entries);
-        return new Remarkable(userToken, rawHost, 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.");
+        return new Remarkable(sessionToken, rawHost, uploadHost, cacheMap);
     }
+    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.");
+}
+/**
+ * create an instance of the api
+ *
+ * This gets a temporary authentication token with the device token and then
+ * constructs the api instance.
+ *
+ * @param deviceToken - the device token proving this api instance is
+ *    registered. Create one with {@link register}.
+ * @returns an api instance
+ */
+export async function remarkable(deviceToken, options = {}) {
+    const { authHost, rawHost, uploadHost, cache, maxCacheSize, syncHost } = options ?? {};
+    const sessionToken = await auth(deviceToken, { authHost });
+    return session(sessionToken, {
+        rawHost,
+        uploadHost,
+        cache,
+        maxCacheSize,
+        syncHost,
+    });
 }

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
  *
@@ -52,7 +61,7 @@ export interface PageTag extends Tag {
 /** all supported document orientations */
 export type Orientation = "portrait" | "landscape";
 /** all supported text alignments */
-export type TextAlignment = "justify" | "left";
+export type TextAlignment = "" | "justify" | "left";
 /** types of zoom modes for documents, applies primarily to pdf files */
 export type ZoomMode = "bestFit" | "customFit" | "fitToHeight" | "fitToWidth";
 /**
@@ -193,8 +202,8 @@ export interface DocumentContent {
     pageCount: number;
     /** the page tags for the document */
     pageTags?: PageTag[];
-    /** a list of the ids of each page in the document */
-    pages?: string[];
+    /** a list of the ids of each page in the document, or null when never opened */
+    pages?: string[] | null;
     /** a mapping from page number to page id in pages */
     redirectionPageMap?: number[];
     /** ostensibly the size in bytes of the file, but this differs from other measurements */
@@ -518,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
      *
@@ -530,15 +554,13 @@ export interface RawRemarkableApi {
     /** completely clear the cache */
     clearCache(): void;
 }
-interface AuthedFetch {
-    (method: RequestMethod, url: string, init?: {
-        body?: string | Uint8Array;
-        headers?: Record<string, string>;
-    }): Promise<Response>;
-}
+type AuthedFetch = (method: RequestMethod, url: string, init?: {
+    body?: string | Uint8Array;
+    headers?: Record<string, string>;
+}) => Promise<Response>;
 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>;
@@ -552,6 +574,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

@@ -1,6 +1,6 @@
 import { fromByteArray } from "base64-js";
 import CRC32C from "crc-32/crc32c";
-import { boolean, elements, empty, enumeration, float64, int32, properties, string, timestamp, uint32, uint8, values, } from "jtd-ts";
+import { boolean, elements, empty, enumeration, float64, int32, nullable, properties, string, timestamp, uint8, uint32, values, } from "jtd-ts";
 import { ValidationError } from "./error.js";
 const hashReg = /^[0-9a-f]{64}$/;
 const tag = properties({
@@ -74,7 +74,7 @@ const documentContent = properties({
     orientation: enumeration("portrait", "landscape"),
     pageCount: uint32(),
     sizeInBytes: string(),
-    textAlignment: enumeration("justify", "left"),
+    textAlignment: enumeration("", "justify", "left"),
     textScale: float64(),
 }, {
     cPages,
@@ -90,10 +90,10 @@ const documentContent = properties({
         count: uint32(),
         timestamp: float64(),
     }, undefined, true),
-    lastOpenedPage: uint32(),
+    lastOpenedPage: int32(),
     margins: uint32(),
     originalPageCount: int32(),
-    pages: elements(string()),
+    pages: nullable(elements(string())),
     pageTags: elements(pageTag),
     redirectionPageMap: elements(int32()),
     tags: elements(tag),
@@ -134,7 +134,7 @@ const metadata = properties({
     visibleName: string(),
 }, {
     lastOpened: string(),
-    lastOpenedPage: uint32(),
+    lastOpenedPage: int32(),
     createdTime: string(),
     deleted: boolean(),
     metadatamodified: boolean(),
@@ -151,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("");
@@ -160,6 +166,7 @@ async function digest(buff) {
 export class RawRemarkable {
     #authedFetch;
     #rawHost;
+    #uploadHost;
     /**
      * a cache of all hashes we know exist
      *
@@ -170,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() {
@@ -235,7 +243,7 @@ export class RawRemarkable {
     async getEntries(hash) {
         const rawFile = await this.getText(hash);
         const [version, ...rest] = rawFile.slice(0, -1).split("\n");
-        if (version != "3") {
+        if (version !== "3") {
             throw new Error(`schema version ${version} not supported`);
         }
         else {
@@ -253,8 +261,8 @@ export class RawRemarkable {
                         hash,
                         type: 80000000,
                         id,
-                        subfiles: parseInt(subfiles),
-                        size: parseInt(size),
+                        subfiles: parseInt(subfiles, 10),
+                        size: parseInt(size, 10),
                     };
                 }
                 else if (type === "0" && subfiles === "0") {
@@ -263,7 +271,7 @@ export class RawRemarkable {
                         type: 0,
                         id,
                         subfiles: 0,
-                        size: parseInt(size),
+                        size: parseInt(size, 10),
                     };
                 }
                 else {
@@ -418,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));
     }