rmapi-js 9.0.3 → 10.0.0

package/dist/index.d.ts

@@ -228,10 +228,11 @@ export interface RemarkableApi {
      * the low-level api to get the raw text of the `.content` file in the
      * `RawEntry` for this hash.
      *
+     * @param id - the id of the item (as returned by `listIds`)
      * @param hash - the hash of the item to get content for
      * @returns the content
      */
-    getContent(hash: string): Promise<Content>;
+    getContent(id: string, hash: string): Promise<Content>;
     /**
      * get the metadata from an item hash
      *
@@ -243,30 +244,33 @@ export interface RemarkableApi {
      * the low-level api to get the raw text of the `.metadata` file in the
      * `RawEntry` for this hash.
      *
+     * @param id - the id of the item (as returned by `listIds`)
      * @param hash - the hash of the item to get metadata for
      * @returns the metadata
      */
-    getMetadata(hash: string): Promise<Metadata>;
+    getMetadata(id: string, hash: string): Promise<Metadata>;
     /**
      * get the pdf associated with a document hash
      *
      * This returns the raw input pdf, not the rendered pdf with any markup.
      *
+     * @param id - the id of the document (as returned by `listIds`)
      * @param hash - the hash of the document to get the pdf for (e.g. the hash
      *     received from `listItems`)
      * @returns the pdf bytes
      */
-    getPdf(hash: string): Promise<Uint8Array>;
+    getPdf(id: string, hash: string): Promise<Uint8Array>;
     /**
      * get the epub associated with a document hash
      *
      * This returns the raw input epub if a document was created from an epub.
      *
-     * @param hash - the hash of the document to get the pdf for (e.g. the hash
+     * @param id - the id of the document (as returned by `listIds`)
+     * @param hash - the hash of the document to get the epub for (e.g. the hash
      *     received from `listItems`)
      * @returns the epub bytes
      */
-    getEpub(hash: string): Promise<Uint8Array>;
+    getEpub(id: string, hash: string): Promise<Uint8Array>;
     /**
      * get the entire contents of a remarkable document
      *
@@ -278,10 +282,11 @@ export interface RemarkableApi {
      * of the document, but this format isn't understood enoguh to reput this on a
      * different remarkable, so that functionality is currently disabled.
      *
-     * @param hash - the hash of the document to get the contents for (e.g. the
+     * @param id - the id of the document (as returned by `listIds`)
+     * @param hash - the hash of the document to get contents for (e.g. the
      *    hash received from `listItems`)
      */
-    getDocument(hash: string): Promise<Uint8Array>;
+    getDocument(id: string, hash: string): Promise<Uint8Array>;
     /**
      * use the low-level api to add a pdf document
      *

package/dist/index.js

@@ -180,18 +180,18 @@ class Remarkable {
         }
     }
     async #convertEntry({ hash, id }) {
-        const { entries } = await this.raw.getEntries(hash);
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
         const metaEnt = entries.find((ent) => ent.id.endsWith(".metadata"));
         const contentEnt = entries.find((ent) => ent.id.endsWith(".content"));
         if (metaEnt === undefined) {
             throw new Error(`couldn't find metadata for hash ${hash}`);
         }
         const [{ visibleName, lastModified, pinned, parent, lastOpened, new: isNew, source, }, content,] = await Promise.all([
-            this.raw.getMetadata(metaEnt.hash),
+            this.raw.getMetadata(metaEnt.id, metaEnt.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),
+                : this.raw.getContent(contentEnt.id, contentEnt.hash),
         ]);
         if ("templateVersion" in content) {
             return {
@@ -240,55 +240,55 @@ class Remarkable {
     }
     async listIds(refresh = false) {
         const [hash] = await this.#getRootHash(refresh);
-        const { entries } = await this.raw.getEntries(hash);
+        const { entries } = await this.raw.getEntries("root.docSchema", hash);
         return entries.map(({ id, hash }) => ({ id, hash }));
     }
-    async getContent(hash) {
-        const { entries } = await this.raw.getEntries(hash);
+    async getContent(id, hash) {
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
         const [cont] = entries.filter((e) => e.id.endsWith(".content"));
         if (cont === undefined) {
             throw new Error(`couldn't find contents for hash ${hash}`);
         }
         else {
-            return await this.raw.getContent(cont.hash);
+            return await this.raw.getContent(cont.id, cont.hash);
         }
     }
-    async getMetadata(hash) {
-        const { entries } = await this.raw.getEntries(hash);
+    async getMetadata(id, hash) {
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
         const [meta] = entries.filter((e) => e.id.endsWith(".metadata"));
         if (meta === undefined) {
             throw new Error(`couldn't find metadata for hash ${hash}`);
         }
         else {
-            return await this.raw.getMetadata(meta.hash);
+            return await this.raw.getMetadata(meta.id, meta.hash);
         }
     }
-    async getPdf(hash) {
-        const { entries } = await this.raw.getEntries(hash);
+    async getPdf(id, hash) {
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
         const [pdf] = entries.filter((e) => e.id.endsWith(".pdf"));
         if (pdf === undefined) {
             throw new Error(`couldn't find pdf for hash ${hash}`);
         }
         else {
-            return await this.raw.getHash(pdf.hash);
+            return await this.raw.getHash(pdf.id, pdf.hash);
         }
     }
-    async getEpub(hash) {
-        const { entries } = await this.raw.getEntries(hash);
+    async getEpub(id, hash) {
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
         const [epub] = entries.filter((e) => e.id.endsWith(".epub"));
         if (epub === undefined) {
             throw new Error(`couldn't find epub for hash ${hash}`);
         }
         else {
-            return await this.raw.getHash(epub.hash);
+            return await this.raw.getHash(epub.id, epub.hash);
         }
     }
-    async getDocument(hash) {
-        const { entries } = await this.raw.getEntries(hash);
+    async getDocument(id, hash) {
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
         const zip = new JSZip();
         for (const entry of entries) {
             // TODO if this is .metadata we might want to assert type === "DocumentType"
-            zip.file(entry.id, this.raw.getHash(entry.hash));
+            zip.file(entry.id, this.raw.getHash(entry.id, entry.hash));
         }
         return zip.generateAsync({ type: "uint8array" });
     }
@@ -344,7 +344,7 @@ class Remarkable {
         // now fetch root entries and upload this file entry
         const [[collectionEntry, uploadCollection], { entries: rootEntries }] = await Promise.all([
             this.raw.putEntries(id, [contentEntry, metadataEntry, pagedataEntry, fileEntry], schemaVersion),
-            this.raw.getEntries(rootHash),
+            this.raw.getEntries("root.docSchema", rootHash),
         ]);
         // now upload a new root entry
         rootEntries.push(collectionEntry);
@@ -398,7 +398,7 @@ class Remarkable {
         // now fetch root entries and upload this file entry
         const [[collectionEntry, uploadCollection], { entries: rootEntries }] = await Promise.all([
             this.raw.putEntries(id, [contentEntry, metadataEntry], schemaVersion),
-            this.raw.getEntries(rootHash),
+            this.raw.getEntries("root.docSchema", rootHash),
         ]);
         // now upload a new root entry
         rootEntries.push(collectionEntry);
@@ -428,13 +428,13 @@ class Remarkable {
     }
     /** edit just a content entry */
     async #editContentRaw(id, hash, update, schemaVersion) {
-        const { entries } = await this.raw.getEntries(hash);
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
         const contInd = entries.findIndex((ent) => ent.id.endsWith(".content"));
         const contEntry = entries[contInd];
         if (contEntry === undefined) {
             throw new Error("internal error: couldn't find content in entry hash");
         }
-        const cont = await this.raw.getContent(contEntry.hash);
+        const cont = await this.raw.getContent(contEntry.id, contEntry.hash);
         Object.assign(cont, update);
         const [newContEntry, uploadCont] = await this.raw.putContent(contEntry.id, cont);
         entries[contInd] = newContEntry;
@@ -445,7 +445,7 @@ class Remarkable {
     /** fully sync a content edit */
     async #editContent(hash, update, expectedType, refresh) {
         const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
-        const { entries } = await this.raw.getEntries(rootHash);
+        const { entries } = await this.raw.getEntries("root.docSchema", rootHash);
         const hashInd = entries.findIndex((ent) => ent.hash === hash);
         const hashEnt = entries[hashInd];
         if (hashEnt === undefined) {
@@ -453,7 +453,7 @@ class Remarkable {
         }
         const [[newEnt, uploadEnt], meta] = await Promise.all([
             this.#editContentRaw(hashEnt.id, hash, update, schemaVersion),
-            this.getMetadata(hash),
+            this.getMetadata(hashEnt.id, hash),
         ]);
         if (meta.type !== expectedType) {
             throw new Error(`expected type ${expectedType} but got ${meta.type} for hash ${hash}`);
@@ -477,13 +477,13 @@ class Remarkable {
         return await this.#editContent(hash, content, "TemplateType", refresh);
     }
     async #editMetaRaw(id, hash, update, schemaVersion) {
-        const { entries } = await this.raw.getEntries(hash);
+        const { entries } = await this.raw.getEntries(`${id}.docSchema`, hash);
         const metaInd = entries.findIndex((ent) => ent.id.endsWith(".metadata"));
         const metaEntry = entries[metaInd];
         if (metaEntry === undefined) {
             throw new Error("internal error: couldn't find metadata in entry hash");
         }
-        const meta = await this.raw.getMetadata(metaEntry.hash);
+        const meta = await this.raw.getMetadata(metaEntry.id, metaEntry.hash);
         Object.assign(meta, update);
         const [newMetaEntry, uploadMeta] = await this.raw.putMetadata(metaEntry.id, meta);
         entries[metaInd] = newMetaEntry;
@@ -493,7 +493,7 @@ class Remarkable {
     }
     async #editMeta(hash, update, refresh = false) {
         const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
-        const { entries } = await this.raw.getEntries(rootHash);
+        const { entries } = await this.raw.getEntries("root.docSchema", rootHash);
         const hashInd = entries.findIndex((ent) => ent.hash === hash);
         const hashEnt = entries[hashInd];
         if (hashEnt === undefined) {
@@ -531,7 +531,7 @@ class Remarkable {
             throw new ValidationError(parent, idReg, "parent must be a valid document id");
         }
         const [rootHash, generation, schemaVersion] = await this.#getRootHash(refresh);
-        const { entries } = await this.raw.getEntries(rootHash);
+        const { entries } = await this.raw.getEntries("root.docSchema", rootHash);
         const hashSet = new Set(hashes);
         const toUpdate = [];
         const newEntries = [];
@@ -568,15 +568,15 @@ class Remarkable {
         // should only go one step) to track all hashes encountered
         // NOTE that we could increase the cache in this process, or it's possible
         // for other calls to increase the cache with misc values.
-        const base = await this.raw.getEntries(rootHash);
+        const base = await this.raw.getEntries("root.docSchema", rootHash);
         let entries = [base.entries];
         let nextEntries = [];
         while (entries.length) {
             for (const entryList of entries) {
-                for (const { hash, type } of entryList) {
+                for (const { hash, type, id } of entryList) {
                     toDelete.add(hash);
                     if (type === 80000000) {
-                        nextEntries.push(this.raw.getEntries(hash));
+                        nextEntries.push(this.raw.getEntries(`${id}.docSchema`, hash));
                     }
                 }
             }

package/dist/raw.d.ts

@@ -431,50 +431,58 @@ export interface RawRemarkableApi {
     /**
      * get the raw binary data associated with a hash
      *
+     * @param fileName - the logical file name (`<id>.<ext>` for files, or
+     *   `<id>.docSchema` / `"root.docSchema"` for entry indexes). reMarkable
+     *   validates this against the rm-filename header.
      * @param hash - the hash to get the data for
      * @returns the data
      */
-    getHash(hash: string): Promise<Uint8Array>;
+    getHash(fileName: string, hash: string): Promise<Uint8Array>;
     /**
      * get raw text data associated with a hash
      *
      * We assume text data are small, and so cache the entire text. If you want to
      * avoid this, use {@link getHash | `getHash`} combined with a TextDecoder.
   
+     * @param fileName - the logical file name (see {@link getHash})
      * @param hash - the hash to get text for
      * @returns the text
      */
-    getText(hash: string): Promise<string>;
+    getText(fileName: string, hash: string): Promise<string>;
     /**
      * get the entries associated with a list hash
      *
      * A list hash is the root hash, or any hash with the type 80000000. NOTE
      * these are hashed differently than files.
   
+     * @param fileName - `"root.docSchema"` for the root, or `"<id>.docSchema"`
+     *   for a sub-document's entry index
      * @param hash - the hash to get entries for
      * @returns the entries
      */
-    getEntries(hash: string): Promise<Entries>;
+    getEntries(fileName: string, hash: string): Promise<Entries>;
     /**
      * get the parsed and validated `Content` of a content hash
      *
      * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
      * validation
   
+     * @param fileName - typically `"<id>.content"`
      * @param hash - the hash to get Content for
      * @returns the content
      */
-    getContent(hash: string): Promise<Content>;
+    getContent(fileName: string, hash: string): Promise<Content>;
     /**
      * get the parsed and validated `Metadata` of a metadata hash
      *
      * Use {@link getText | `getText`} combined with `JSON.parse` to bypass
      * validation
   
+     * @param fileName - typically `"<id>.metadata"`
      * @param hash - the hash to get Metadata for
      * @returns the metadata
      */
-    getMetadata(hash: string): Promise<Metadata>;
+    getMetadata(fileName: string, hash: string): Promise<Metadata>;
     /**
      * update the current root hash
      *
@@ -564,11 +572,11 @@ export declare class RawRemarkable implements RawRemarkableApi {
     constructor(authedFetch: AuthedFetch, cache: Map<string, string | null>, rawHost: string, uploadHost: string);
     /** make an authorized request to remarkable */
     getRootHash(): Promise<[string, number, SchemaVersion]>;
-    getHash(hash: string): Promise<Uint8Array>;
-    getText(hash: string): Promise<string>;
-    getEntries(hash: string): Promise<Entries>;
-    getContent(hash: string): Promise<Content>;
-    getMetadata(hash: string): Promise<Metadata>;
+    getHash(fileName: string, hash: string): Promise<Uint8Array>;
+    getText(fileName: string, hash: string): Promise<string>;
+    getEntries(fileName: string, hash: string): Promise<Entries>;
+    getContent(fileName: string, hash: string): Promise<Content>;
+    getMetadata(fileName: string, hash: string): Promise<Metadata>;
     putRootHash(hash: string, generation: number, broadcast?: boolean): Promise<[string, number]>;
     putFile(id: string, bytes: Uint8Array): Promise<[RawEntry, Promise<void>]>;
     putText(id: string, text: string): Promise<[RawEntry, Promise<void>]>;

package/dist/raw.js

@@ -222,23 +222,23 @@ export class RawRemarkable {
             return [hash, generation, schemaVersion];
         }
     }
-    async #getHash(hash) {
+    async #getHash(fileName, hash) {
         if (!hashReg.test(hash)) {
             throw new ValidationError(hash, hashReg, "hash was not a valid hash");
         }
-        const resp = await this.#authedFetch("GET", `${this.#rawHost}/sync/v3/files/${hash}`);
+        const resp = await this.#authedFetch("GET", `${this.#rawHost}/sync/v3/files/${hash}`, { headers: { "rm-filename": fileName } });
         // TODO switch to `.bytes()`.
         const raw = await resp.arrayBuffer();
         return new Uint8Array(raw);
     }
-    async getHash(hash) {
+    async getHash(fileName, hash) {
         const cached = this.#cache.get(hash);
         if (cached != null) {
             const enc = new TextEncoder();
             return enc.encode(cached);
         }
         else {
-            const res = await this.#getHash(hash);
+            const res = await this.#getHash(fileName, hash);
             // mark that we know hash exists
             const cacheVal = this.#cache.get(hash);
             if (cacheVal === undefined) {
@@ -247,22 +247,22 @@ export class RawRemarkable {
             return res;
         }
     }
-    async getText(hash) {
+    async getText(fileName, hash) {
         const cached = this.#cache.get(hash);
         if (cached != null) {
             return cached;
         }
         else {
             // NOTE two simultaneous requests will fetch twice
-            const raw = await this.#getHash(hash);
+            const raw = await this.#getHash(fileName, hash);
             const dec = new TextDecoder();
             const res = dec.decode(raw);
             this.#cache.set(hash, res);
             return res;
         }
     }
-    async getEntries(hash) {
-        const rawFile = await this.getText(hash);
+    async getEntries(fileName, hash) {
+        const rawFile = await this.getText(fileName, hash);
         const [version, ...rest] = rawFile.slice(0, -1).split("\n");
         if (version === "3") {
             return { entries: rest.map(parseRawEntryLine) };
@@ -290,8 +290,8 @@ export class RawRemarkable {
             throw new Error(`schema version ${version} not supported`);
         }
     }
-    async getContent(hash) {
-        const raw = await this.getText(hash);
+    async getContent(fileName, hash) {
+        const raw = await this.getText(fileName, 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 try each, and concatenate the errors at the end
@@ -313,8 +313,8 @@ export class RawRemarkable {
         const joined = errors.join("\n\nor\n\n");
         throw new Error(`invalid content: ${joined}`);
     }
-    async getMetadata(hash) {
-        const raw = await this.getText(hash);
+    async getMetadata(fileName, hash) {
+        const raw = await this.getText(fileName, hash);
         const loaded = JSON.parse(raw);
         if (!metadata.guardAssert(loaded))
             throw Error("invalid metadata");
@@ -345,7 +345,7 @@ export class RawRemarkable {
             throw new Error(`new generation ${newGen} was not a safe integer; please file a bug report`);
         }
     }
-    async #putFile(hash, fileName, bytes) {
+    async #putFile(fileName, hash, bytes) {
         // if the hash is already in the cache, writing is pointless
         if (!this.#cache.has(hash)) {
             const crc = CRC32C.buf(bytes, 0);
@@ -376,7 +376,7 @@ export class RawRemarkable {
             subfiles: 0,
             size: bytes.length,
         };
-        return [res, this.#putFile(hash, id, bytes)];
+        return [res, this.#putFile(id, hash, bytes)];
     }
     async putText(id, text) {
         const enc = new TextEncoder();
@@ -444,11 +444,7 @@ export class RawRemarkable {
             subfiles: entries.length,
             size,
         };
-        return [
-            res,
-            // NOTE when monitoring requests, this had the extension .docSchema appended, but I'm not entirely sure why
-            this.#putFile(hash, `${id}.docSchema`, entryBuff),
-        ];
+        return [res, this.#putFile(`${id}.docSchema`, hash, entryBuff)];
     }
     async uploadFile(visibleName, bytes, mime) {
         const enc = new TextEncoder();