rmapi-js 10.0.0 → 10.1.0

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, CPageStringValue, CPages, CPageUUID, DocumentContent, DocumentMetadata, Entries, FileType, KeyboardMetadata, Metadata, Orientation, PageTag, RawEntry, RawRemarkableApi, SchemaVersion, SimpleEntry, Tag, TemplateContent, TextAlignment, UploadMimeType, ZoomMode, } from "./raw";
+export type { BackgroundFilter, CollectionContent, Content, CPageNumberValue, CPagePage, CPageStringValue, CPages, CPageUUID, DocumentContent, DocumentMetadata, Entries, FileType, KeyboardMetadata, LegacyCollectionContent, LegacyDocumentContent, Metadata, Orientation, PageTag, RawEntry, RawRemarkableApi, SchemaVersion, SimpleEntry, Tag, TemplateContent, TextAlignment, UploadMimeType, ZoomMode, } from "./raw";
 /** common properties shared by collections and documents */
 export interface EntryCommon {
     /** the document id, a uuid4 */
@@ -21,7 +21,7 @@ export interface EntryCommon {
      */
     parent?: string;
     /** any tags the entry might have */
-    tags?: Tag[];
+    tags?: Tag[] | string[];
 }
 /** a folder, referred to in the api as a collection */
 export interface CollectionEntry extends EntryCommon {

package/dist/index.js

@@ -348,7 +348,7 @@ class Remarkable {
         ]);
         // now upload a new root entry
         rootEntries.push(collectionEntry);
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", rootEntries, schemaVersion);
+        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", rootEntries, 4);
         // before updating the root hash, first upload everything
         await Promise.all([
             uploadContent,
@@ -402,7 +402,7 @@ class Remarkable {
         ]);
         // now upload a new root entry
         rootEntries.push(collectionEntry);
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", rootEntries, schemaVersion);
+        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", rootEntries, 4);
         // before updating the root hash, first upload everything
         await Promise.all([
             uploadContent,
@@ -459,7 +459,7 @@ class Remarkable {
             throw new Error(`expected type ${expectedType} but got ${meta.type} for hash ${hash}`);
         }
         entries[hashInd] = newEnt;
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", entries, schemaVersion);
+        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", entries, 4);
         await Promise.all([uploadEnt, uploadRoot]);
         await this.#putRootHash(rootEntry.hash, generation);
         return { hash: newEnt.hash };
@@ -501,7 +501,7 @@ class Remarkable {
         }
         const [newEnt, uploadEnt] = await this.#editMetaRaw(hashEnt.id, hash, update, schemaVersion);
         entries[hashInd] = newEnt;
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", entries, schemaVersion);
+        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", entries, 4);
         await Promise.all([uploadEnt, uploadRoot]);
         await this.#putRootHash(rootEntry.hash, generation);
         return { hash: newEnt.hash };
@@ -547,7 +547,7 @@ class Remarkable {
             uploads.push(upload);
             result[toUpdate[i].hash] = newEnt.hash;
         }
-        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", newEntries, schemaVersion);
+        const [rootEntry, uploadRoot] = await this.raw.putEntries("root", newEntries, 4);
         await Promise.all([Promise.all(uploads), uploadRoot]);
         await this.#putRootHash(rootEntry.hash, generation);
         return { hashes: result };

package/dist/raw.d.ts

@@ -147,13 +147,21 @@ export interface CollectionContent {
     /** collections don't have a file type */
     fileType?: undefined;
 }
+/** legacy collection content can store tags as raw strings */
+export interface LegacyCollectionContent {
+    /** the legacy tag names for the collection */
+    tags?: string[];
+    /** collections don't have a file type */
+    fileType?: undefined;
+}
 /**
  * content metadata, stored with the "content" extension
  *
  * This largely contains description of how to render the document, rather than
  * metadata about it.
  */
-export interface DocumentContent {
+/** fields shared by current and legacy document content payloads */
+export interface CommonDocumentContent {
     /**
      * which page to use for the thumbnail
      *
@@ -209,8 +217,6 @@ export interface DocumentContent {
     redirectionPageMap?: number[];
     /** ostensibly the size in bytes of the file, but this differs from other measurements */
     sizeInBytes: string;
-    /** document tags for this document */
-    tags?: Tag[];
     /** text alignment for this document */
     textAlignment: TextAlignment;
     /**
@@ -269,6 +275,16 @@ export interface DocumentContent {
      */
     viewBackgroundFilter?: BackgroundFilter;
 }
+/** document content with modern structured tag payloads */
+export interface DocumentContent extends CommonDocumentContent {
+    /** document tags for this document */
+    tags?: Tag[];
+}
+/** legacy document content can store tags as raw strings */
+export interface LegacyDocumentContent extends CommonDocumentContent {
+    /** the legacy tag names for this document */
+    tags?: string[];
+}
 /**
  * content metadata, stored with the "content" extension
  *
@@ -307,7 +323,7 @@ export interface TemplateContent {
     items: object[];
 }
 /** content metadata for any item */
-export type Content = CollectionContent | DocumentContent | TemplateContent;
+export type Content = CollectionContent | LegacyCollectionContent | DocumentContent | LegacyDocumentContent | TemplateContent;
 /**
  * item level metadata
  *
@@ -533,6 +549,11 @@ export interface RawRemarkableApi {
      * 3. append this entry to the root entry and call this again to update this root list
      * 4. put the new root hash
      *
+     * NOTE: reMarkable currently rejects newly written schema 3 root indexes
+     * with a 400 "Software must be updated" error, even for accounts that still
+     * report schema 3, so the root list should always be written as schema 4. A
+     * warning is logged if a schema 3 root index is written.
+     *
      * @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

package/dist/raw.js

@@ -65,7 +65,10 @@ const cPages = properties({
 const collectionContent = properties(undefined, {
     tags: elements(tag),
 });
-const documentContent = properties({
+const legacyCollectionContent = properties(undefined, {
+    tags: elements(string()),
+});
+const documentContentRequired = {
     coverPageNumber: int32(),
     documentMetadata,
     extraMetadata: values(string()),
@@ -77,7 +80,8 @@ const documentContent = properties({
     sizeInBytes: string(),
     textAlignment: enumeration("", "justify", "left"),
     textScale: float64(),
-}, {
+};
+const documentContentOptional = {
     cPages,
     customZoomCenterX: float64(),
     customZoomCenterY: float64(),
@@ -97,7 +101,6 @@ const documentContent = properties({
     pages: nullable(elements(string())),
     pageTags: elements(pageTag),
     redirectionPageMap: elements(int32()),
-    tags: elements(tag),
     transform: properties(undefined, {
         m11: float64(),
         m12: float64(),
@@ -112,6 +115,14 @@ const documentContent = properties({
     // eslint-disable-next-line spellcheck/spell-checker
     viewBackgroundFilter: enumeration("off", "fullpage"),
     zoomMode: enumeration("bestFit", "customFit", "fitToHeight", "fitToWidth"),
+};
+const documentContent = properties(documentContentRequired, {
+    ...documentContentOptional,
+    tags: elements(tag),
+}, true);
+const legacyDocumentContent = properties(documentContentRequired, {
+    ...documentContentOptional,
+    tags: elements(string()),
 }, true);
 const templateContent = properties({
     name: string(),
@@ -298,8 +309,10 @@ export class RawRemarkable {
         const errors = [];
         for (const [name, valid] of [
             ["collection", collectionContent],
+            ["legacy collection", legacyCollectionContent],
             ["template", templateContent],
             ["document", documentContent],
+            ["legacy document", legacyDocumentContent],
         ]) {
             try {
                 if (valid.guardAssert(loaded))
@@ -407,6 +420,9 @@ export class RawRemarkable {
         }
     }
     async putEntries(id, entries, schemaVersion) {
+        if (id === "root" && schemaVersion === 3) {
+            console.warn('writing a schema 3 root index, which reMarkable rejects with a 400 "Software must be updated" error; write the root index with schema version 4 instead');
+        }
         // NOTE v3 collections have a special hash function, the hash of their
         // contents, so this needs to be different
         entries.sort((a, b) => a.id.localeCompare(b.id));
@@ -417,7 +433,8 @@ export class RawRemarkable {
             records.push(`0:${name}:${entries.length}:${size}\n`);
         }
         for (const { hash, type, id, subfiles, size } of entries) {
-            records.push(`${hash}:${type}:${id}:${subfiles}:${size}\n`);
+            const lineType = schemaVersion === 4 ? 0 : type;
+            records.push(`${hash}:${lineType}:${id}:${subfiles}:${size}\n`);
         }
         const enc = new TextEncoder();
         const entryBuff = enc.encode(records.join(""));