asimov-readwise-module 0.1.1

ASIMOV module.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

# ASIMOV Readwise Module

[![License](https://img.shields.io/badge/license-Public%20Domain-blue.svg)](https://unlicense.org)
[![Package on Crates.io](https://img.shields.io/crates/v/asimov-readwise-module)](https://crates.io/crates/asimov-readwise-module)
[![Documentation](https://docs.rs/asimov-readwise-module/badge.svg)](https://docs.rs/asimov-readwise-module)

[ASIMOV] module for importing data from [Readwise] and converting it to [JSON-LD] format.

## ✨ Features

- 📚 **Import Highlights**: Fetch and convert Readwise highlights to JSON-LD
- 📖 **Import Books**: Fetch and convert Readwise book lists to JSON-LD
- 🏷️ **Import Tags**: Fetch and convert Readwise tags to JSON-LD
- 🔄 **JSON-LD Output**: Structured data compatible with [KNOW] ontology
- ⚡ **Fast & Reliable**: Built with Rust for performance and safety
- 🚦 **Rate Limit Aware**: Respects Readwise API limits and provides clear error handling

## 🛠️ Prerequisites

- [Rust] 1.85+ (2024 edition) if building from source code
- [Readwise] account with API access
- `READWISE_API_KEY` environment variable

## ⬇️ Installation

### Installation with the [ASIMOV CLI]

```bash
asimov module install readwise -v
```

### Installation from Source Code

```bash
cargo install asimov-readwise-module
```

## 👉 Examples

### Import Highlights

```bash
# Import all highlights (transparent pagination)
asimov-readwise-importer https://readwise.io/highlights

# Import first 100 highlights only
asimov-readwise-importer https://readwise.io/highlights --page-size 100

# Import specific page
asimov-readwise-importer https://readwise.io/highlights --page 2 --page-size 50
```

### Import Books

```bash
# Import all books (transparent pagination)
asimov-readwise-importer https://readwise.io/books

# Import first 50 books only
asimov-readwise-importer https://readwise.io/books --page-size 50
```

### Import Tags

```bash
asimov-readwise-importer https://readwise.io/tags
```

### Other Commands

```bash
# Show version information
asimov-readwise-importer --version

# Show license information
asimov-readwise-importer --license

# Show help
asimov-readwise-importer --help
```

## ⚙ Configuration

### API Key Setup

Set your Readwise API key as an environment variable:

```bash
export READWISE_API_KEY="your-api-key-here"
```

Or use a `.env` file:

```env
READWISE_API_KEY=your-api-key-here
```

Get your API key from: <https://readwise.io/access_token>

### Rate Limiting

**Heads up**: This module plays nice with Readwise's API limits. If you get HTTP 429 errors (too many requests):

- **Just wait a bit**: The API will throw an error if you're going too fast
- **No auto-retry**: We don't automatically retry failed requests
- **Take it slow**: If you're grabbing lots of data, give it some breathing room

**The limits**: This plugin is limited to 20 requests per minute due to Readwise's API restrictions.

## 👨‍💻 Development

```bash
git clone https://github.com/asimov-modules/asimov-readwise-module.git
cd asimov-readwise-module
cargo test
```

---

[![Share on X](https://img.shields.io/badge/share%20on-x-03A9F4?logo=x)](https://x.com/intent/post?url=https://github.com/asimov-modules/asimov-readwise-module&text=asimov-readwise-module)
[![Share on Reddit](https://img.shields.io/badge/share%20on-reddit-red?logo=reddit)](https://reddit.com/submit?url=https://github.com/asimov-modules/asimov-readwise-module&title=asimov-readwise-module)
[![Share on Hacker News](https://img.shields.io/badge/share%20on-hn-orange?logo=ycombinator)](https://news.ycombinator.com/submitlink?u=https://github.com/asimov-modules/asimov-readwise-module&t=asimov-readwise-module)
[![Share on Facebook](https://img.shields.io/badge/share%20on-fb-1976D2?logo=facebook)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/asimov-modules/asimov-readwise-module)
[![Share on LinkedIn](https://img.shields.io/badge/share%20on-linkedin-3949AB?logo=linkedin)](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/asimov-modules/asimov-readwise-module)

[ASIMOV]: https://asimov.sh
[ASIMOV CLI]: https://cli.asimov.sh
[JSON-LD]: https://json-ld.org
[KNOW]: https://know.dev
[RDF]: https://www.w3.org/TR/rdf12-primer/
[Readwise]: https://readwise.io
[Rust]: https://rust-lang.org