rmapi-js 0.0.1

package/dist/index.js

@@ -0,0 +1,535 @@
+/**
+ * Create and interact with reMarkable cloud.
+ *
+ * @example
+ * A simple fetch
+ * ```ts
+ * import { register, remarkable } from "rmapi-js";
+ *
+ * const code = "..."  // eight letter code from https://my.remarkable.com/device/desktop/connect
+ * const token = await register(code)
+ * // persist token
+ * const api = await remarkable(token);
+ * const [root] = await api.getRootHash();
+ * const fileEntries = await api.getEntries(root);
+ * for (const entry of fileEntries) {
+ *   const children = await api.getEntries(entry.hash);
+ *   for (const { hash, documentId } of children) {
+ *     if (documentId.endsWith(".metadata")) {
+ *       const meta = api.getMetadata(hash);
+ *       // get metadata for entry
+ *       console.log(meta);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * A simple upload
+ * ```ts
+ * import { remarkable } from "rmapi-js";
+ *
+ * const api = await remarkable(...);
+ * await api.putEpub("document name", epubBuffer);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { v4 as uuid4 } from "uuid";
+import { concatBuffers, fromHex, toHex } from "./utils";
+import { validate } from "./validate";
+const SCHEMA_VERSION = "3";
+const AUTH_URL = "https://webapp-production-dot-remarkable-production.appspot.com";
+const BLOB_URL = "https://rm-blob-storage-prod.appspot.com";
+const GENERATION_HEADER = "x-goog-generation";
+const GENERATION_RACE_HEADER = "x-goog-if-generation-match";
+/** tool options */
+export const builtinTools = [
+    "Ballpoint",
+    "Ballpointv2",
+    "Brush",
+    "Calligraphy",
+    "ClearPage",
+    "EraseSection",
+    "Eraser",
+    "Fineliner",
+    "Finelinerv2",
+    "Highlighter",
+    "Highlighterv2",
+    "Marker",
+    "Markerv2",
+    "Paintbrush",
+    "Paintbrushv2",
+    "Pencilv2",
+    "SharpPencil",
+    "SharpPencilv2",
+    "SolidPen",
+    "ZoomTool",
+];
+/** font name options */
+export const builtinFontNames = [
+    "Maison Neue",
+    "EB Garamond",
+    "Noto Sans",
+    "Noto Serif",
+    "Noto Mono",
+    "Noto Sans UI",
+];
+/** text scale options */
+export const builtinTextScales = {
+    /** the smallest */
+    xs: 0.7,
+    /** small */
+    sm: 0.8,
+    /** medium / default */
+    md: 1.0,
+    /** large */
+    lg: 1.2,
+    /** extra large */
+    xl: 1.5,
+    /** double extra large */
+    xx: 2.0,
+};
+/** margin options */
+export const builtinMargins = {
+    /** small */
+    sm: 50,
+    /** medium */
+    md: 125,
+    /** default for read on remarkable */
+    rr: 180,
+    /** large */
+    lg: 200,
+};
+/** line height options */
+export const builtinLineHeights = {
+    /** default */
+    df: -1,
+    /** normal */
+    md: 100,
+    /** half */
+    lg: 150,
+    /** double */
+    xl: 200,
+};
+const urlResponseSchema = {
+    properties: {
+        relative_path: { type: "string" },
+        url: { type: "string" },
+        expires: { type: "timestamp" },
+        method: { enum: ["POST", "GET", "PUT", "DELETE"] },
+    },
+};
+const commonProperties = {
+    visibleName: { type: "string" },
+    parent: { type: "string" },
+    lastModified: { type: "string" },
+    version: { type: "int32" },
+    synced: { type: "boolean" },
+};
+const commonOptionalProperties = {
+    pinned: { type: "boolean" },
+    modified: { type: "boolean" },
+    deleted: { type: "boolean" },
+    metadatamodified: { type: "boolean" },
+};
+const metadataSchema = {
+    discriminator: "type",
+    mapping: {
+        CollectionType: {
+            properties: commonProperties,
+            optionalProperties: commonOptionalProperties,
+        },
+        DocumentType: {
+            properties: commonProperties,
+            optionalProperties: {
+                ...commonOptionalProperties,
+                lastOpened: { type: "string" },
+                lastOpenedPage: { type: "int32" },
+            },
+        },
+    },
+};
+/** an error that results from a failed request */
+export class ResponseError extends Error {
+    /** the response status number */
+    status;
+    /** the response status text */
+    statusText;
+    constructor(status, statusText, message) {
+        super(message);
+        this.status = status;
+        this.statusText = statusText;
+    }
+}
+/**
+ * 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 class GenerationError extends Error {
+    constructor() {
+        super("Generation preconditions failed. This means the current state is out of date with the cloud and needs to be re-synced.");
+    }
+}
+/**
+ * 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 async function register(code, { deviceDesc = "desktop-linux", uuid = uuid4(), authUrl = AUTH_URL, fetch = globalThis.fetch, } = {}) {
+    if (code.length !== 8) {
+        throw new Error(`code should be length 8, but was ${code.length}`);
+    }
+    const resp = await fetch(`${authUrl}/token/json/2/device/new`, {
+        method: "POST",
+        headers: {
+            Authorization: "Bearer",
+        },
+        body: JSON.stringify({
+            code,
+            deviceDesc,
+            deviceID: uuid,
+        }),
+    });
+    if (!resp.ok) {
+        throw new ResponseError(resp.status, resp.statusText, "couldn't register api");
+    }
+    else {
+        return await resp.text();
+    }
+}
+/** format an entry */
+function formatEntry({ hash, type, documentId, subfiles, size, }) {
+    return `${hash}:${type}:${documentId}:${subfiles}:${size}\n`;
+}
+/** parse an entry */
+function parseEntry(line) {
+    const [hash, type, documentId, subfiles, size] = line.split(":");
+    if (hash === undefined ||
+        type === undefined ||
+        documentId === undefined ||
+        subfiles === undefined ||
+        size === undefined) {
+        throw new Error(`entries line didn't contain five fields: '${line}'`);
+    }
+    if (type === "80000000") {
+        if (size !== "0") {
+            throw new Error(`collection type entry had nonzero size: ${size}`);
+        }
+        else {
+            return {
+                hash,
+                type,
+                documentId,
+                subfiles: parseInt(subfiles),
+                size: 0n,
+            };
+        }
+    }
+    else if (type === "0") {
+        if (subfiles !== "0") {
+            throw new Error(`file type entry had nonzero number of subfiles: ${subfiles}`);
+        }
+        else {
+            return {
+                hash,
+                type,
+                documentId,
+                subfiles: 0,
+                size: BigInt(size),
+            };
+        }
+    }
+    else {
+        throw new Error(`entries line contained invalid type: ${type}`);
+    }
+}
+/** the implementation of that api */
+class Remarkable {
+    userToken;
+    fetch;
+    cache;
+    subtle;
+    blobUrl;
+    constructor(userToken, fetch, cache, subtle, blobUrl) {
+        this.userToken = userToken;
+        this.fetch = fetch;
+        this.cache = cache;
+        this.subtle = subtle;
+        this.blobUrl = blobUrl;
+    }
+    /** make an authorized request to remarkable */
+    async authedFetch(url, body, method = "POST") {
+        const resp = await this.fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.userToken}`,
+            },
+            body: body && JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            throw new ResponseError(resp.status, resp.statusText, "failed reMarkable request");
+        }
+        else {
+            return resp;
+        }
+    }
+    /** make a signed request to the cloud */
+    async signedFetch({ url, method }, body, headers) {
+        const resp = await this.fetch(url, {
+            method,
+            body,
+            headers,
+        });
+        if (!resp.ok) {
+            const msg = await resp.text();
+            throw new ResponseError(resp.status, resp.statusText, msg);
+        }
+        else {
+            return resp;
+        }
+    }
+    /** get the details for how to make a signed request to remarkable cloud */
+    async getUrl(relativePath, gen) {
+        const key = gen === undefined ? "downloads" : "uploads";
+        const generation = gen === null || gen === undefined ? undefined : `${gen}`;
+        const resp = await this.authedFetch(`${this.blobUrl}/api/v1/signed-urls/${key}`, {
+            http_method: generation === undefined ? "GET" : "PUT",
+            relative_path: relativePath,
+            generation,
+        });
+        const raw = await resp.text();
+        const res = JSON.parse(raw);
+        validate(urlResponseSchema, res);
+        return res;
+    }
+    /** sends a signal to the server that a sync is complete and other devices should update */
+    async syncComplete() {
+        await this.authedFetch(`${this.blobUrl}/api/v1/sync-complete`);
+    }
+    /**
+     * get the root hash and the current generation
+     */
+    async getRootHash() {
+        const signed = await this.getUrl("root");
+        const resp = await this.signedFetch(signed);
+        const generation = resp.headers.get(GENERATION_HEADER);
+        if (!generation) {
+            throw new Error("no generation header in root hash");
+        }
+        return [await resp.text(), BigInt(generation)];
+    }
+    /**
+     * write the root hash, incrementing from the current generation
+     */
+    async putRootHash(hash, generation) {
+        const signed = await this.getUrl("root", generation);
+        let resp;
+        try {
+            resp = await this.signedFetch(signed, hash, {
+                [GENERATION_RACE_HEADER]: `${generation}`,
+            });
+        }
+        catch (ex) {
+            if (ex instanceof ResponseError && ex.status === 412) {
+                throw new GenerationError();
+            }
+            else {
+                throw ex;
+            }
+        }
+        const gen = resp.headers.get(GENERATION_HEADER);
+        if (!gen) {
+            throw new Error("no generation header in root hash");
+        }
+        return BigInt(gen);
+    }
+    /**
+     * get text content associated with hash
+     */
+    async getBuffer(hash) {
+        const signed = await this.getUrl(hash);
+        const resp = await this.signedFetch(signed);
+        return await resp.arrayBuffer();
+    }
+    /**
+     * get text content associated with hash
+     */
+    async getText(hash) {
+        const cached = this.cache && (await this.cache.get(hash));
+        if (cached) {
+            return cached;
+        }
+        else {
+            const signed = await this.getUrl(hash);
+            const resp = await this.signedFetch(signed);
+            const raw = await resp.text();
+            this.cache && (await this.cache.set(hash, raw));
+            return raw;
+        }
+    }
+    /**
+     * get metadata from hash
+     */
+    async getMetadata(hash) {
+        const raw = await this.getText(hash);
+        const parsed = JSON.parse(raw);
+        validate(metadataSchema, parsed);
+        return parsed;
+    }
+    /**
+     * get entries from a collection hash
+     */
+    async getEntries(hash) {
+        const raw = await this.getText(hash);
+        // slice for trailing new line
+        const [schema, ...lines] = raw.slice(0, -1).split("\n");
+        if (schema !== SCHEMA_VERSION) {
+            throw new Error(`got unexpected schema version: ${schema}`);
+        }
+        return lines.map(parseEntry);
+    }
+    /** upload data to hash */
+    async putHash(hash, body) {
+        const signed = await this.getUrl(hash, null);
+        await this.signedFetch(signed, body);
+    }
+    /** put a reference to a set of entries into the cloud */
+    async putEntries(documentId, entries) {
+        // hash of a collection is the hash of all hashes in documentId order
+        const enc = new TextEncoder();
+        entries.sort((a, b) => a.documentId.localeCompare(b.documentId));
+        const hashes = concatBuffers(entries.map((ent) => fromHex(ent.hash)));
+        const digest = await this.subtle.digest("SHA-256", hashes);
+        const hash = toHex(digest);
+        const entryContents = entries.map(formatEntry).join("");
+        const contents = `${SCHEMA_VERSION}\n${entryContents}`;
+        const buffer = enc.encode(contents);
+        await this.putHash(hash, buffer);
+        this.cache && (await this.cache.set(hash, contents));
+        return {
+            hash,
+            type: "80000000",
+            documentId,
+            subfiles: entries.length,
+            size: 0n,
+        };
+    }
+    /** put a raw buffer in the cloud */
+    async putBuffer(documentId, buffer) {
+        const digest = await this.subtle.digest("SHA-256", buffer);
+        const hash = toHex(digest);
+        await this.putHash(hash, buffer);
+        return {
+            hash,
+            type: "0",
+            documentId,
+            subfiles: 0,
+            size: BigInt(buffer.length),
+        };
+    }
+    /** put cached text in the cloud */
+    async putText(documentId, contents) {
+        const enc = new TextEncoder();
+        const entry = await this.putBuffer(documentId, enc.encode(contents));
+        this.cache && (await this.cache.set(entry.hash, contents));
+        return entry;
+    }
+    /** upload an epub */
+    async putEpub(visibleName, buffer, { parent = "", margins = 125, orientation, textAlignment, textScale = 1, lineHeight = -1, fontName = "", cover = "visited", lastTool, notify = true, retries = 3, } = {}) {
+        const documentId = uuid4();
+        const lastModified = `${new Date().valueOf()}`;
+        const entryPromises = [];
+        // upload main document
+        entryPromises.push(this.putBuffer(`${documentId}.epub`, buffer));
+        // upload metadata
+        const metadata = {
+            type: "DocumentType",
+            visibleName,
+            version: 0,
+            parent,
+            synced: true,
+            lastModified,
+        };
+        entryPromises.push(this.putText(`${documentId}.metadata`, JSON.stringify(metadata)));
+        // upload content file
+        const content = {
+            dummyDocument: false,
+            extraMetadata: {
+                LastTool: lastTool,
+            },
+            fileType: "epub",
+            pageCount: 0,
+            lastOpenedPage: 0,
+            lineHeight: typeof lineHeight === "string"
+                ? builtinLineHeights[lineHeight]
+                : lineHeight,
+            margins: typeof margins === "string" ? builtinMargins[margins] : margins,
+            textScale: typeof textScale === "string"
+                ? builtinTextScales[textScale]
+                : textScale,
+            pages: [],
+            coverPageNumber: cover === "first" ? 0 : -1,
+            formatVersion: 1,
+            orientation,
+            textAlignment,
+            fontName,
+        };
+        entryPromises.push(this.putText(`${documentId}.content`, JSON.stringify(content)));
+        // NOTE we technically get the entries a bit earlier, so could upload this
+        // before all contents are uploaded, but this also saves us from uploading
+        // the contents entry before all have uploaded successfully
+        const entries = await Promise.all(entryPromises);
+        const entry = await this.putEntries(documentId, entries);
+        // sync root hash
+        // if server undergoes update, this will fail, and we'll need to start
+        // again, up to `retries`.
+        for (;; --retries) {
+            try {
+                const [root, gen] = await this.getRootHash();
+                const rootEntries = await this.getEntries(root);
+                rootEntries.push(entry);
+                const { hash } = await this.putEntries("", rootEntries);
+                await this.putRootHash(hash, gen);
+                break;
+            }
+            catch (ex) {
+                if (retries <= 0 || !(ex instanceof GenerationError)) {
+                    throw ex;
+                }
+            }
+        }
+        if (notify) {
+            await this.syncComplete();
+        }
+    }
+}
+/**
+ * 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 async function remarkable(deviceToken, { fetch = globalThis.fetch, cache, subtle = globalThis.crypto?.subtle, authUrl = AUTH_URL, blobUrl = BLOB_URL, } = {}) {
+    const resp = await fetch(`${authUrl}/token/json/2/user/new`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${deviceToken}`,
+        },
+    });
+    if (!resp.ok) {
+        throw new Error(`couldn't fetch auth token: ${resp.statusText}`);
+    }
+    const userToken = await resp.text();
+    return new Remarkable(userToken, fetch, cache, subtle, blobUrl);
+}

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+/** convert a buffer to hex */
+export declare function toHex(buffer: ArrayBuffer): string;
+/** convert a hex string to a buffer */
+export declare function fromHex(hex: string): Uint8Array;
+/** concat buffers */
+export declare function concatBuffers(buffers: Uint8Array[]): Uint8Array;

package/dist/utils.js

@@ -0,0 +1,24 @@
+/** convert a buffer to hex */
+export function toHex(buffer) {
+    return [...new Uint8Array(buffer)]
+        .map((x) => x.toString(16).padStart(2, "0"))
+        .join("");
+}
+/** convert a hex string to a buffer */
+export function fromHex(hex) {
+    return new Uint8Array((hex.match(/../g) ?? []).map((h) => parseInt(h, 16)));
+}
+/** concat buffers */
+export function concatBuffers(buffers) {
+    let length = 0;
+    for (const buff of buffers) {
+        length += buff.length;
+    }
+    const result = new Uint8Array(length);
+    let offset = 0;
+    for (const buff of buffers) {
+        result.set(buff, offset);
+        offset += buff.length;
+    }
+    return result;
+}

package/dist/validate.d.ts

@@ -0,0 +1,3 @@
+import { JTDSchemaType as JtdSchema } from "ajv/dist/jtd";
+export type { JtdSchema };
+export declare function validate<T>(schema: JtdSchema<T>, obj: unknown): asserts obj is T;

package/dist/validate.js

@@ -0,0 +1,8 @@
+import { validate as jtdValidate } from "jtd";
+export function validate(schema, obj) {
+    const errors = jtdValidate(schema, obj);
+    if (errors.length) {
+        // TODO better errors
+        throw new Error(`couldn't validate schema: ${JSON.stringify(obj)} didn't match schema ${JSON.stringify(schema)}`);
+    }
+}