rmapi-js 8.0.0 → 8.1.0

package/dist/index.d.ts

@@ -99,8 +99,19 @@ export interface DocumentType extends EntryCommon {
     /** the timestamp of the last time this entry was opened */
     lastOpened: string;
 }
+/** a template, such as from methods.remarkable.com */
+export interface TemplateType extends EntryCommon {
+    /** the key to identify this as a template */
+    type: "TemplateType";
+    /** the timestamp of when the template was added/created */
+    createdTime?: string;
+    /** where this template was installed from */
+    source?: string;
+    /** indicates if this is a newly-installed template */
+    new?: boolean;
+}
 /** a remarkable entry for cloud items */
-export type Entry = CollectionEntry | DocumentType;
+export type Entry = CollectionEntry | DocumentType | TemplateType;
 /** an simple entry without any extra information */
 export interface SimpleEntry {
     /** the document id */
@@ -360,8 +371,45 @@ export interface DocumentContent {
      */
     viewBackgroundFilter?: BackgroundFilter;
 }
+/**
+ * content metadata, stored with the "content" extension
+ *
+ * This largely contains description of how to render the document, rather than
+ * metadata about it.
+ */
+export interface TemplateContent {
+    /** the template name */
+    name: string;
+    /** the template's author */
+    author: string;
+    /** Base64-encoded SVG icon image */
+    iconData: string;
+    /** category names this template belongs to (eg: "Planning", "Productivity") */
+    categories: string[];
+    /** labels associated with this template (eg: "Project management") */
+    labels: string[];
+    /** the orientation of this template */
+    orientation: "portrait" | "landscape";
+    /** semantic version for this template */
+    templateVersion: string;
+    /** template configuration format version (currently just `1`) */
+    formatVersion: number;
+    /**
+     * which screens the template supports:
+     *
+     * - `rm2`: reMarkable 2
+     * - `rmPP`: reMarkable Paper Pro
+     */
+    supportedScreens: ("rm2" | "rmPP")[];
+    /** constant values used by the commands in `items` */
+    constants?: {
+        [name: string]: number;
+    }[];
+    /** the template definition, an SVG-like DSL in JSON */
+    items: object[];
+}
 /** content metadata for any item */
-export type Content = CollectionContent | DocumentContent;
+export type Content = CollectionContent | DocumentContent | TemplateContent;
 /**
  * item level metadata
  *
@@ -399,7 +447,15 @@ export interface Metadata {
      * DocumentType is a document, an epub, pdf, or notebook, CollectionType is a
      * folder.
      */
-    type: "DocumentType" | "CollectionType";
+    type: "DocumentType" | "CollectionType" | "TemplateType";
+    /** whether this is this a newly-installed template */
+    new?: boolean;
+    /**
+     * the provider from which this item was obtained/installed
+     *
+     * Example: a template from "com.remarkable.methods".
+     */
+    source?: string;
     /** [speculative] metadata version, always 0 */
     version?: number;
     /** the visible name of the item, what it's called on the reMarkable */

package/dist/index.js

@@ -54,7 +54,7 @@
 import { fromByteArray } from "base64-js";
 import CRC32C from "crc-32/crc32c";
 import JSZip from "jszip";
-import { boolean, elements, enumeration, float64, int32, nullable, properties, string, timestamp, uint32, uint8, values, } from "jtd-ts";
+import { boolean, elements, empty, enumeration, float64, int32, nullable, properties, string, timestamp, uint32, uint8, values, } from "jtd-ts";
 import { v4 as uuid4 } from "uuid";
 import { LruCache } from "./lru";
 const AUTH_HOST = "https://webapp-prod.cloud.remarkable.engineering";
@@ -201,6 +201,19 @@ const cPages = properties({
 const collectionContent = properties(undefined, {
     tags: elements(tag),
 });
+const templateContent = properties({
+    name: string(),
+    author: string(),
+    iconData: string(),
+    categories: elements(string()),
+    labels: elements(string()),
+    orientation: enumeration("portrait", "landscape"),
+    templateVersion: string(),
+    formatVersion: uint8(),
+    supportedScreens: elements(enumeration("rm2", "rmPP")),
+    constants: elements(values(int32())),
+    items: elements(empty()),
+});
 const documentContent = properties({
     coverPageNumber: int32(),
     documentMetadata,
@@ -253,7 +266,7 @@ const metadata = properties({
     lastModified: string(),
     parent: string(),
     pinned: boolean(),
-    type: enumeration("DocumentType", "CollectionType"),
+    type: enumeration("DocumentType", "CollectionType", "TemplateType"),
     visibleName: string(),
 }, {
     lastOpened: string(),
@@ -399,18 +412,24 @@ class RawRemarkable {
         const raw = await this.getText(hash);
         const loaded = JSON.parse(raw);
         // jtd can't verify non-discriminated unions, in this case, we have fileType
-        // defined or not. As a result, we only do a normal guard for the presence
-        // of tags (e.g. empty content or only specify tags). Otherwise we'll throw
-        // the full error for the richer content.
-        if (collectionContent.guard(loaded)) {
-            return loaded;
-        }
-        else if (documentContent.guardAssert(loaded)) {
-            return loaded;
-        }
-        else {
-            throw Error("invalid content");
+        // defined or not. As a result, we try each, and concatenate the errors at the end
+        const errors = [];
+        for (const [name, valid] of [
+            ["collection", collectionContent],
+            ["template", templateContent],
+            ["document", documentContent],
+        ]) {
+            try {
+                if (valid.guardAssert(loaded))
+                    return loaded;
+            }
+            catch (ex) {
+                const msg = ex instanceof Error ? ex.message : "unknown error type";
+                errors.push(`Couldn't validate as ${name} because:\n${msg}`);
+            }
         }
+        const joined = errors.join("\n\nor\n\n");
+        throw new Error(`invalid content: ${joined}`);
     }
     async getMetadata(hash) {
         const raw = await this.getText(hash);
@@ -604,11 +623,24 @@ class Remarkable {
         else if (contentEnt === undefined) {
             throw new Error(`couldn't find content for hash ${hash}`);
         }
-        const [{ visibleName, lastModified, pinned, parent, lastOpened }, content] = await Promise.all([
+        const [{ visibleName, lastModified, pinned, parent, lastOpened, new: isNew, source, }, content,] = await Promise.all([
             this.raw.getMetadata(metaEnt.hash),
             this.raw.getContent(contentEnt.hash),
         ]);
-        if (content.fileType === undefined) {
+        if ("templateVersion" in content) {
+            return {
+                id,
+                hash,
+                visibleName,
+                lastModified,
+                new: isNew,
+                pinned,
+                source,
+                parent,
+                type: "TemplateType",
+            };
+        }
+        else if (content.fileType === undefined) {
             return {
                 id,
                 hash,