cli + tui to publish to leaflet (wip) & manage tasks, notes & watch/read lists 馃崈
desertthunder.dev
charm
leaflet
readability
golang
1---
2title: External Integrations
3sidebar_label: Overview
4sidebar_position: 1
5description: Overview of external service integrations.
6---
7
8# External Integrations
9
10Noteleaf integrates with external services to enrich your productivity workflow and extend functionality beyond local storage.
11
12## Available Integrations
13
14### Open Library API
15
16Free book metadata service for building your reading list.
17
18**Features:**
19
20- Search books by title, author, ISBN
21- Fetch metadata (author, year, subjects)
22- Edition and publication information
23- No API key required
24
25**Use Cases:**
26
27- Adding books to reading list
28- Enriching book metadata
29- Discovering related works
30
31See [Open Library API](./openlibrary.md) for details.
32
33### Leaflet.pub
34
35Decentralized publishing platform built on AT Protocol.
36
37**Features:**
38
39- Publish notes as structured documents
40- Pull existing documents into local notes
41- Update published content
42- Manage drafts and publications
43
44**Use Cases:**
45
46- Blog publishing from terminal
47- Long-form content management
48- Decentralized content ownership
49
50See [Leaflet.pub section](../leaflet/intro.md) for details.
51
52### AT Protocol (Bluesky)
53
54Authentication and identity via AT Protocol network.
55
56**Features:**
57
58- Decentralized identity (DID)
59- Session management
60- Token refresh
61- Secure authentication
62
63**Use Cases:**
64
65- Leaflet.pub authentication
66- Portable identity across services
67- Content verification
68
69See [Authentication](../leaflet/authentication.md) for details.
70
71## Integration Architecture
72
73### Service Layer
74
75External integrations live in `internal/services/`:
76
77- `services.go` - Open Library API client
78- `atproto.go` - AT Protocol authentication
79- `http.go` - HTTP utilities and rate limiting
80
81### Rate Limiting
82
83All external services use rate limiting to respect API quotas:
84
85- Open Library: 3 requests/second
86- AT Protocol: Per PDS configuration
87
88Rate limiters are built-in and automatic.
89
90### Error Handling
91
92Services implement consistent error handling:
93
94- Network errors
95- Rate limit exceeded
96- Authentication failures
97- Invalid responses
98
99Errors propagate to user with actionable messages.
100
101## Configuration
102
103Integration configuration in `.noteleaf.conf.toml`:
104
105```toml
106# Open Library (no configuration needed)
107# book_api_key = "" # Reserved for future use
108
109# AT Protocol / Leaflet.pub
110atproto_handle = "username.bsky.social"
111atproto_did = "did:plc:..."
112atproto_pds_url = "https://bsky.social"
113atproto_access_jwt = "..."
114atproto_refresh_jwt = "..."
115```
116
117See [Configuration](../Configuration.md) for all options.
118
119## Offline Support
120
121Noteleaf works fully offline for local data. Integrations are optional enhancements:
122
123- Books can be added manually without Open Library
124- Notes exist locally without Leaflet.pub
125- Tasks and media work without any external service
126
127External services enhance but don't require connectivity.
128
129## Privacy and Data
130
131### Data Sent
132
133**Open Library:**
134
135- Search queries
136- Work/edition IDs
137
138**AT Protocol:**
139
140- Handle/DID
141- Published note content
142- Authentication credentials
143
144### Data Stored Locally
145
146- API responses (cached)
147- Session tokens
148- Publication metadata
149
150### No Tracking
151
152Noteleaf does not:
153
154- Track usage
155- Send analytics
156- Share data with third parties
157- Require accounts (except for publishing)
158
159## Resources
160
161- [Open Library API Documentation](https://openlibrary.org/developers/api)
162- [AT Protocol Docs](https://atproto.com)
163- [Leaflet.pub](https://leaflet.pub)
164- [Bluesky](https://bsky.app)