rmapi-js 6.0.0 → 7.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Erik Brinkman
+Copyright (c) 2024 Erik Brinkman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,22 +5,18 @@
 [![npm](https://img.shields.io/npm/v/rmapi-js)](https://www.npmjs.com/package/rmapi-js)
 [![license](https://img.shields.io/github/license/erikbrinkman/rmapi-js)](LICENSE)
 
-JavaScript implementation of the reMarkable api. This implementation is built
-around web standards for fetch, but can easily be patched to work for node. It
-should also be pretty easy to customize to work with
+JavaScript implementation of the reMarkable api. It should also be pretty easy
+to customize to work with
 [rmfakecloud](https://github.com/ddvk/rmfakecloud), although that might take a
 little bit of extra plumbing.
 
-reMarkable keep updating their API, makig it hard to keep all features
-functioning. The current version is based on the api used by reMarkables web uploader and file viewer. While this api works for moving and uploading, it doesn't support more fine-grained access to document configuration, or downloading.
-
 ## API
 
 Before using this API it's necessary to have some rudimentary understanding of
 how the API works.
 
 All data is stored via its sha256 hash. This includes raw files ("documents")
-and folders ("collections"). The hash indicates the full current state to manage simultaneous edits. Most entries or edits will take an input hash, and return an output hash. Additionally, every entry has an id, which is a uuid4, and remains constantant over the lifetime of the file. There are two special ids, "" (the empty string) which corresponds to the root collection, e.g. the default location for all files, and "trash", which is the trash.
+and folders ("collections"). The hash indicates the full current state to manage simultaneous edits. Most entries or edits will take an input hash, and return an output hash. Additionally, every entry has an id, which is a uuid4, and remains constantant over the lifetime of the file or folder. There are two special ids, "" (the empty string) which corresponds to the root collection, e.g. the default location for all files, and "trash", which is the trash.
 
 ## Usage
 
@@ -48,30 +44,39 @@ await api.uploadEpub("name", buffer);
 await api.uploadPdf("name", buffer);
 ```
 
-### Node
+There are alos low level apis that more directly manipulate cloud storage.
+Using these apis is a little riskier since they can potentially result in data loss, but it does come with increased flexibility.
 
-This uses web standards by default, so using within node takes a little more effort. You also need to have a globally defined fetch. There are several ways to
-accomplish this. In node 17.5 or higher you can enable global fetch with
-`node --experimental-fetch`
+```ts
+// ...
 
-You can also rely on `"node-fetch"` which is compliant enough
+// upload with custom line height not avilable through reMarkable
+await api.putEpub("name", buffer, { lineHeight: 180 })
 
-```js
-import fetch from "node-fetch";
-global.fetch = fetch;
+// fetch an uploaded pdf, using the hash (from listFiles)
+const buffer = await api.getEpub(hash)
 ```
 
-or
+### Gotchas
+
+By default, all calls try to do their best to verify that the input and output
+matches what I expect. However, since I reverse-engineered this, some of it
+could be wrong. If you ever run into a `ValidationError` and know you want
+whatever data is returned, You'll have to use the low-level api under `api.raw`
+to access the raw text file and parse the result yourself.
 
-```js
-import fetch from "node-fetch";
-const api = await remarkable(token, { fetch });
-```
+It seems that exporting happens within the apps themselves, which will require
+layout of the remarkable file structure. That's currently outside the scope of
+this project.
 
-### Gotchas
+## Users
 
-By default, all calls try to do their best to verify that the input and output matches what I expect. However, since I reverse-engineered this, some of it could be wrong. If you ever run into a `ValidationError` and know you want whatever data is returned, simply pass `{ verify: false }` in the options to that API, and that should temporarily remove the blocker. However note that in instances like this, the typescript types will be wrong.
+- [✉️ Send Via](https://sendvia.me/) [[github](https://github.com/PaulKinlan/send-to-remarkable)] - upload to reMarkable via email
+- [ⓡ rePub](https://chromewebstore.google.com/detail/repub/blkjpagbjaekkpojgcgdapmikoaolpbl) [[github](https://github.com/hafaio/repub)] - web clipper for reMarkable that supports images and customization
 
 ## Contributing
 
-Thie current API provides high level limited access. I'd love to reverse engineer what the apps use so this can one again tweak document settings as well as download files. Any help doing this or suggesting approaches would be grealy appreciated!
+Since this has all been reverse engineered, any help expanding the api would be
+helpful. For example, There's currently a function to download the entire state
+of a document, but I ran into trouble trying to reupload that exact same file as
+a clone.