@dorakika/weread-api

Type-safe WeRead (微信读书) API client for Node.js & browsers.

Install

npm install @dorakika/weread-api

Quick start

import { WereadClient, formatDate, formatDuration } from '@dorakika/weread-api'

const client = new WereadClient({ apiKey: 'wrk-xxxxxxxx' })

// Search books
const { results } = await client.search.books({ keyword: '三体', count: 5 })
for (const group of results) {
  console.log(`— ${group.title} —`)
  for (const { bookInfo } of group.books) {
    console.log(`  ${bookInfo.title} — ${bookInfo.author}`)
  }
}

// Bookshelf
const shelf = await client.shelf.sync()
console.log(`${shelf.books.length} books on shelf`)

// Reading stats this month
const stats = await client.readdata.detail({ mode: 'monthly' })
console.log(`Read ${formatDuration(stats.totalReadTime)} across ${stats.readDays} days`)

// Iterate all notebooks (auto-paginated)
for await (const nb of client.notebook.all({ pageSize: 50 })) {
  console.log(`${nb.book.title}: ${nb.noteCount} highlights`)
}

API namespaces

| Namespace | Method | Description | |-----------|--------|-------------| | client.search | .books(params) | Search bookstore | | client.search | .all(params) | Async generator over all search results | | client.book | .info({bookId}) | Book details | | client.book | .chapters({bookId}) | Table of contents | | client.book | .progress({bookId}) | Reading progress | | client.shelf | .sync() | Full bookshelf | | client.notebook | .list(params?) | Notebooks page | | client.notebook | .all(options?) | Async generator over all notebooks | | client.bookmark | .list({bookId}) | Highlights for a book | | client.bestbookmarks | .all({bookId}) | Popular highlights | | client.underlines | .stats({bookId, chapterUid}) | Highlight popularity per chapter | | client.readreviews | .forRange(params) | Thoughts under highlights | | client.readreviews | .single({reviewId}) | Single thought detail | | client.review | .list({bookId}) | Public reviews | | client.review | .all({bookId}) | Async generator over all reviews | | client.review | .mine({bookid}) | My thoughts/reviews | | client.review | .single({reviewId}) | Single review detail | | client.readdata | .detail({mode}) | Reading statistics | | client.discover | .recommend(params?) | Personalized recommendations | | client.discover | .recommendAll(params?) | Async generator over all recs | | client.discover | .similar({bookId}) | Similar books | | client.discover | .similarAll({bookId}) | Async generator over all similar | | client.profile | .summary() | Shelf + progress summary |

Utilities

import { formatDate, formatDuration, toDate } from '@dorakika/weread-api'
import { bookLink, chapterLink, highlightLink } from '@dorakika/weread-api'

formatDate(1715678901)    // → '2024-05-14'
formatDuration(3661)       // → '1小时1分钟'
bookLink('abc123')         // → 'weread://reading?bId=abc123'

Error handling

import { WereadError, WereadAuthError, WereadHttpError } from '@dorakika/weread-api'

try {
  await client.search.books({ keyword: '三体' })
} catch (err) {
  if (err instanceof WereadAuthError) {
    console.error('Set WEREAD_API_KEY')
  } else if (err instanceof WereadError) {
    if (err.upgradeInfo) console.warn('Upgrade:', err.upgradeInfo.message)
    console.error(`API error [${err.errcode}]: ${err.message}`)
  }
}

License

MIT