rmapi-js 8.4.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 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, SimpleEntry, Tag, TemplateContent, TextAlignment, UploadMimeType, 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 */
@@ -482,14 +482,17 @@ 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
      *
@@ -526,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, uploadHost, cache, maxCacheSize, }?: RemarkableOptions): Promise<RemarkableApi>;
+export declare function remarkable(deviceToken: string, options?: RemarkableOptions): Promise<RemarkableApi>;

package/dist/index.js

@@ -126,13 +126,13 @@ 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, uploadHost, 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, uploadHost);
     }
@@ -158,7 +158,7 @@ class Remarkable {
         const resp = await fetch(url, {
             method,
             headers: {
-                Authorization: `Bearer ${this.#userToken}`,
+                Authorization: `Bearer ${this.#sessionToken}`,
                 ...headers,
             },
             // fetch works correctly with uint8 arrays, but is not hinted correctly
@@ -596,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, uploadHost = UPLOAD_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: {
@@ -615,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, 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.");
+        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

@@ -61,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";
 /**
@@ -202,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 */
@@ -554,12 +554,10 @@ 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, uploadHost: string);

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(),
@@ -243,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 {
@@ -261,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") {
@@ -271,7 +271,7 @@ export class RawRemarkable {
                         type: 0,
                         id,
                         subfiles: 0,
-                        size: parseInt(size),
+                        size: parseInt(size, 10),
                     };
                 }
                 else {