Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Scarvy/readwise-reader-api
An unofficial JS/TS client for the Readwise Reader API 📚
https://github.com/Scarvy/readwise-reader-api
api-client javascript readwise readwise-reader typescript
Last synced: 3 months ago
JSON representation
An unofficial JS/TS client for the Readwise Reader API 📚
- Host: GitHub
- URL: https://github.com/Scarvy/readwise-reader-api
- Owner: Scarvy
- License: isc
- Created: 2024-01-12T22:37:30.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-07-25T19:25:12.000Z (4 months ago)
- Last Synced: 2024-07-25T22:08:32.754Z (4 months ago)
- Topics: api-client, javascript, readwise, readwise-reader, typescript
- Language: TypeScript
- Homepage:
- Size: 107 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-readwise - readwise-reader-api - An unofficial JS/TS client for the Readwise Reader API. (Client Libraries)
README
# An unofficial Readwise & Reader SDK for JavaScript
This client provides a convenient way to interact with the Readwise & Reader API, suitable for both JavaScript and TypeScript applications.
## Installation
```bash
npm install readwise-reader-api
```
## Usage
### Prerequisites
1. Obtain a Readwise API token [here](https://readwise.io/access_token)
2. Store in .env file or in an environment variable.
```bash
export READWISE_TOKEN=
```
Import and initialize a client (`Readwise` or `Reader`) using an access token.
```typescript
import { Readwise } from "readwise-reader-api";
const readwise = new Readwise({
auth: process.env.READWISE_TOKEN,
});
```
Make a request to any Readwise (or Reader) API endpoint.
> See the complete list of endpoints in the API Reference:
>
> - [Readwise](https://readwise.io/api_deets)
> - [Readwise Reader](https://readwise.io/reader_api)
```javascript
(async () => {
const daily_review = await readwise.review.daily();
})();
```
Each method returns a `Promise` which resolves the response.
```javascript
console.log(daily_review);
```
```bash
{
review_id: 104932226,
review_url: 'https://readwise.io/reviews/104932226',
review_completed: true,
highlights: [
{
text: '“If it walks like a duck and it quacks like a duck, then it must be a duck.”',
title: 'Practices of the Python Pro',
author: 'Dane Hillard',
url: null,
source_url: 'https://read.readwise.io/read/01h65f61js5qpaycd1409e22qw',
source_type: 'article',
category: null,
location_type: 'offset',
location: 78999682,
note: '',
highlighted_at: '2023-09-17T15:46:42.883825Z',
highlight_url: 'https://read.readwise.io/read/01hahx56818mje85sga832j5t2',
image_url: 'https://readwise-assets.s3.amazonaws.com/static/images/article0.00998d930354.png',
id: 597114893,
api_source: null
},
...
{
text: 'we continue along this rate of change and follow a “Large Model Moore’s Law,” then these far-fetched scenarios may just enter the realm of the possible.',
title: 'Generative AI: A Creative New World',
author: 'Sonya Huang',
url: null,
source_url: 'https://read.readwise.io/read/01h6qabyzghazrt1qsjvf9zeqa',
source_type: 'article',
category: null,
location_type: 'offset',
location: 21926,
note: '',
highlighted_at: '2023-08-04T15:17:58.196413Z',
highlight_url: 'https://read.readwise.io/read/01h70j0xryxnwm3b6wcf4n6kfh',
image_url: 'https://www.sequoiacap.com/wp-content/uploads/sites/6/2022/09/robots-1-1960.jpg',
id: 574654751,
api_source: null
},
]
}
```
## Client Library References
A reference for all methods and types available in Readwise and Reader Client libraries.
### Readwise
**EXPORT Highlights**: Export all highlights after a specific date.
```typescript
async function exportHighlights() {
try {
const highlights: ReadwiseBookHighlights[] =
await readwise.highlights.export({
updatedAfter: "2024-01-27T00:00:00Z",
});
console.log(highlights);
} catch (error) {
console.error("Error:", error);
}
}
```
**LIST Highlights**: List all highlights after a specific date.
```typescript
async function listHighlights() {
try {
const highlights: ReadwiseHighlight[] = await readwise.highlights.list({
highlighted_at__gt: "2024-01-27T00:00:00Z",
});
console.log(highlights);
} catch (error) {
console.error("Error:", error);
}
}
```
**DAILY REVIEW:** Returns your daily review highlights.
```typescript
async function getDailyReview() {
/** Get Daily Review */
try {
const review = await readwise.review.daily();
console.log(review);
} catch (error) {
console.error("Error:", error);
}
}
```
**DETAILS Book:** Get details for a book (eg Article, Blog, Tweet, Book, etc.).
```typescript
async function getBookDetails() {
try {
const book: ReadwiseBook = await readwise.books.details({
book_id: "35943114",
});
console.log(book);
} catch (error) {
console.error("Error:", error);
}
}
```
**LIST Highlights (in Book):** Get all highlights for a single book (eg Article, Blog, Tweet, Book, etc.).
```typescript
async function getBookHighlights() {
try {
const book_highlights: ReadwiseHighlight[] = await readwise.highlights.list(
{ book_id: 35943114 },
);
console.log(book_highlights);
} catch (error) {
console.error("Error:", error);
}
}
```
**EXPORT Highlights (in Book):** Export all highlights for a single book (eg Article, Blog, Tweet, Book, etc.).
```typescript
async function exportBookHighlights(): Promise {
try {
const highlights: ReadwiseBookHighlights[] =
await readwise.highlights.export({ ids: 35943114 });
console.log(highlights);
} catch (error) {
console.error("Error:", error);
}
}
```
### Advanced Usage
Get all highlights for a particular category (eg "Tweets")
```typescript
async function getHighlightsFromTweets() {
const books: ReadwiseBook[] = await readwise.books.list({
category: "tweets",
});
for (const book of books) {
const highlights = await readwise.highlights.list({ book_id: book.id });
if (highlights.length > 0) {
console.log(book.title);
for (const highlight of highlights) {
console.log(highlight.text);
}
}
}
}
```
### Readwise Reader
Provides the ability to create, list, and retrieve documents.
```typescript
import { Reader } from 'readwise-reader-api
const reader = new Reader({
auth: process.env.READWISE_TOKEN,
});
```
**CREATE Document:** Create a document.
```typescript
const result = await reader.document.create({
url: url,
title: "New Title",
});
```
The response will show if document already exists or not.
```bash
{
document_already_exists: true,
data: {
id: '01hqeecsxa5qx6beyjvbrz37e4',
url: 'https://read.readwise.io/read/01hqeecsxa5qx6beyjvbrz37e4'
}
}
```
**LIST Documents:** List documents for a specific _location_, _category_ and/or _date_.
```typescript
async function listReaderDocuments() {
try {
console.log("Getting documents...");
const docs = await reader.document.list(
"new",
"article",
"2024-01-01T00:00:00Z",
);
console.log(docs);
} catch (error) {
console.error("Error:", error);
}
}
```
**GET Document by ID:** Retrieve a single document.
```typescript
async function getReaderDocument() {
try {
console.log("Getting a specific document...");
const doc = await reader.document.id("01hkwssvj7g207daxvk5k1tc4d");
console.log(doc);
} catch (error) {
console.error("Error:", error);
}
}
```
### Available Readwise and Reader Types
```typescript
export {
/** Readwise */
ReadwiseBook,
ReadwiseBookHighlights,
ReadwiseHighlight,
ReadwiseLibraryCategoryType,
/** Reader */
ReaderDocument,
ReaderLocationType,
ReaderCategoryType,
} from "./api-endpoints";
```