agrmohit / omnivore-epub Goto Github PK

A program to generate epub file from articles saved in your Omnivore library and optionally send it to your eReader using email

License: MIT License

TypeScript 100.00%

deno epub-generator omnivore omnivore-api read-it-later kindle pocketbook

omnivore-epub's Introduction

Omnivore EPUB

A program to generate epub file from articles saved in your Omnivore library and optionally send it to your eReader using email.

Omnivore is an open source read-it-later app similar to Pocket and Instapaper.

Forked from here

OS Support

This program uses no OS specific code and should work on all platforms supported by Deno.

Download

To download the latest version of the program, you can use git to clone the repository
If you are not familiar with git, you can always download the latest version by going to the latest GitHub release
Then, under Assets click on Source code (zip) which will download the latest release of the program in a zip file which you will need to unzip.
The program checks for updates when run and will notify you of new releases when available. This can be disabled in the config file.

Usage

Install Deno
Get an API token for Omnivore following instructions here
Put your token in the token field in config file
Modify the configuration file if necessary
In your terminal, go to the app folder and run the following command deno run -A main.ts
The ebook with extension .epub should be in the app directory after execution

Send to eReader

List of eReaders that support sending ebook using email:

Tip

Make sure the email address used is approved to send ebook to your eReader

Configuring email

Ability to send ebook over email is disabled by default
To enable it, set emailSupport to true in the config file
Set emailHost to the SMTP address of your email provider
E.g. smtp.gmail.com for Gmail and smtp-mail.outlook.com for Outlook
Set emailPort to the SMTP Port. Usually it is 587, 465 or 25
Set emailUser which is usually your email address
Set emailPassword to your email account password. This is stored locally on your device and is never sent to us
Set emailRecipient to the email you want to receive ebook on (your eReader's email address). See the links in list of eReaders above to know more
You may need to set emailAllowSTARTTLS to false when using 465 as emailPort. Leave it to true when not sure

Caution

The email password is stored in plaintext on your device, unencrypted. Therefore, it is highly recommended to use app password instead of your account password whenever your email provider supports it

You may also need to turn on 2FA (Two Factor Authentication)

Instructions for setting an app password for a few popular email providers:

Configuration

Configuration options available in the config file

Option	Type	Description
token	string	Omnivore API Token
endpoint	string	Omnivore GraphQL API endpoint
title	string	Title of the ebook
author	string	Author of the ebook
cover	string	URL for fetching cover image for the ebook
description	string	Description of the ebook
addLabelsInContent	boolean	Whether to add the labels for the article below title
addArticleLinkInContent	boolean	Whether to add the link for the article below title
allowImages	boolean	Whether to add images linked in article in the ebook
outputFileName	string	ebook file name
maxArticleCount	number	Number of articles to fetch
searchQuery	string	Valid query for article search
ignoredLabels	string[]	List of labels to exclude from the ebook
ignoredLinks	string[]	List of urls to exclude from the ebook
emailSupport	boolean	Whether to send the ebook via email (to your eReader)
emailHost	string	SMTP Hostname of your email provider
emailPort	number	Usually one of 587, 465 or 25. Prefer 587 when available
emailUser	string	Username/Email address of your email account
emailPassword	string	Password of your email account. Prefer app password
emailRecipient	string	Email address that should receive your ebook
emailFrom	string	Sender name that appears to the email receiver
emailAllowSTARTTLS	boolean	Allow connecting to the SMTP server using STARTTLS
emailSizeWarningSuppress	boolean	Show a warning if ebook is over emailSizeWarningMinSize
emailSizeWarningMinSize	number	Min ebook size to show warning while sending email in MB
updateCheck	boolean	Check for updates when run
showReleaseNotes	boolean	Show release notes when an update is available

Custom searchQuery

Setting searchQuery is the recommended way to filter and sort articles. You can learn more about how to use them on the official Omnivore documentation Search | Omnivore Docs.

The default value is sort:saved-desc which returns all unarchived articles sorted by saved date, recently added articles first.

You can also use it to filter by labels. In case the label contain a space, you will need to escape the double-quotes using a forward slash \. Example: sort:saved-desc label:\"Send to Kindle\"

Star History

omnivore-epub's People

Contributors

Stargazers

Watchers

Forkers

zsoltika tsutomu-n sascharucks tmr232 sibrash4 tofagerl

omnivore-epub's Issues

Error running the script

Was happy to find someone had same need to get epubs out of Omnivore. However running the script on my Mac result to error:

~ deno run -A gen-epub.ts
〰️ getting article list
error: Uncaught (in promise) Error: Unexpected server error: {"response":{"errors":[{"message":"Unexpected server error"}],"status":500,"headers":{}},"request":{"query":"\n    {\n      articles(first: 100) {\n        ... on ArticlesSuccess {\n          edges {\n            cursor\n            node {\n              title\n              slug\n              description\n              url\n              savedAt\n              language\n              subscription\n              isArchived\n              author\n              labels {\n                name\n              }\n            }\n          }\n        }\n      }\n    }\n  "}}
    at makeRequest (file:///Users/toni/Library/Caches/deno/npm/registry.npmjs.org/graphql-request/6.1.0/build/esm/index.js:282:15)

My Deno version info:

~ deno --version
deno 1.37.2 (release, aarch64-apple-darwin)
v8 11.8.172.13
typescript 5.2.2

Errors out with too many requests

I am not exactly sure how many articles are there in my omnivore. The account settings show 289 items. I set the maxArticles to 300 and also set to exclude 1 label which has maybe 30 articles or so attached. First time I saw that it didnt error out but only few articles were there in the ouput. So I ran again and I got this error.

error: Uncaught (in promise) Error: GraphQL Error (Code: 429): {"response":{"error":"Too many requests, please try again later.","status":429,"headers":{}},"request":{"query":"{\n    article (username: \"anonymous\", slug: \"2-2-cross-validation-stat-508-18d50ca7b53\") {\n      ... on ArticleSuccess {\n        article {\n          id, slug, url, content\n        }\n      }\n    }\n  }"}}
    at makeRequest (file:///home/linn/.cache/deno/npm/registry.npmjs.org/graphql-request/6.1.0/build/esm/index.js:282:15)
    at Object.runMicrotasks (ext:core/01_core.js:659:26)
    at processTicksAndRejections (ext:deno_node/_next_tick.ts:53:10)
    at runNextTicks (ext:deno_node/_next_tick.ts:71:3)
    at eventLoopTick (ext:core/01_core.js:176:21)
    at async getArticle (file:///home/linn/work/archived/2023/aug2023/omniexp-jackson/newexp/omnivore-epub/main.ts:125:16)
    at async makeEbook (file:///home/linn/work/archived/2023/aug2023/omniexp-jackson/newexp/omnivore-epub/main.ts:163:22)
    at async file:///home/linn/work/archived/2023/aug2023/omniexp-jackson/newexp/omnivore-epub/main.ts:217:1

Automatically escape quotes in the search query

I wanted to only take some articles, chosen by a label, as there are some that I prefer to read on my phone.

So I created a label and changed the search query: sort:saved-desc label:"Send to Kindle".

To escape it properly, I had to do double escaping - once for the JSON file, and once for the GQL request:

  "searchQuery": "sort:saved-desc label:\\\"Send to Kindle\\\"",

I think it would be nice if the script did the escaping-for-GQL on its own.

Feature request: set the downloaded article's state to archived

I love your script and swapping out Instapaper for me.

It would be great if after successfully downloading and converting to epub all the downloaded articles would be archived (now I'm doing this manually).

[FR] Separate epubs per article / Aside: KOreader intregration

Is your feature request related to a problem?

I lose my progress reading long articles when new articles get added, and need to search for my place again.

Describe the solution you'd like

Omnivore-epub could make different epubs for each article in the list, so progress could be kept for long articles. This could be a toggle, so the current functionality could remain for those that prefer one epub with everything in it.

Describe alternatives you've considered

Alternatively, the user could specify a certain article length that warrants a standalone epub vs. being grouped in with other articles.

We could also use omnivore's labeling system to determine whether articles should be in their own epub or in the main epub.

I'm not sure how to keep progress if articles are all in one file unless we integrate with peoples' epub readers. KOreader has a feature called Progress sync which could be used to save progress and place it back at the same place in the article they were reading. This would come with the added benefit forwarding progress back to omnivore, similar to #2. This change seems much more complicated, however.

Aside: There's also a "Move to archive" feature in KOreader, which could be used with the proposed "separate epubs" feature to allow the user to archive omnivore articles from KOreader.

Pocketbook EPUB viewer 3 crash

When I access certain parts of the omnivore epub using the default pocketbook viewer (3), the viewer crashes. I can mitigate this crash by opening it in the epub 2 viewer. I'm on a pocketbook era with software U700.6.8.2911

Steps to reproduce crash:

Add this article to your omnivore library.
Make and move epub to pocketbook era.
Attempt to view that section of the epub.

Maybe there's something corrupted in the epub in that section, or maybe the pocketbook reader has a bug.

If you need someone with the device to test a fix, I'd be happy to help!