Miniflux.js

Typed, modern JavaScript/TypeScript SDK for the Miniflux RSS reader API.

This is an unofficial community package. For the upstream API contract, see the official Miniflux API documentation.

Features

• Full TypeScript support and generated declaration files
• API key and password/basic authentication
• Coverage for feeds, entries, categories, users, enclosures and system endpoints
• Modern ESM package for Node.js 18.12+
• Small, dependency-free runtime built on the standard fetch API
• TypeDoc-powered API documentation

Installation

npm install @jedrzejjarocki/miniflux-js
# or
pnpm add @jedrzejjarocki/miniflux-js
# or
yarn add @jedrzejjarocki/miniflux-js
# or
bun add @jedrzejjarocki/miniflux-js

Requirements

• Node.js >=18.12.0
• ESM project or dynamic import support
• A reachable Miniflux instance with API access enabled

Quick start

API key authentication

import { MinifluxClient } from '@jedrzejjarocki/miniflux-js'

const client = new MinifluxClient({
  baseURL: 'https://reader.example.com',
  apiKey: process.env.MINIFLUX_API_KEY,
})

const me = await client.getMe()
const unread = await client.getEntries({ status: ['unread'], limit: 20 })

console.log(`Hello ${me.username}, you have ${unread.total} unread entries.`)

You can also set authType explicitly:

const client = new MinifluxClient({
  baseURL: 'https://reader.example.com',
  authType: 'api_key',
  apiKey: 'your-api-key',
})

Password authentication

const client = new MinifluxClient({
  baseURL: 'https://reader.example.com',
  authType: 'password',
  username: 'alice',
  password: 'correct-horse-battery-staple',
})

For integrations, API key authentication is recommended.

Common usage

Feeds

const feeds = await client.getFeeds()

const feed = await client.createFeed('https://example.com/feed.xml', 1)
await client.refreshFeed(feed.id)

await client.updateFeed(feed.id, {
  title: 'Example',
  scraper_rules: 'article',
})

Entries

const entries = await client.getEntries({
  status: ['unread'],
  order: 'published_at',
  direction: 'desc',
  limit: 50,
})

const first = entries.entries[0]
if (first) {
  await client.updateEntryStatus(first.id, 'read')
  await client.toggleBookmark(first.id)
}

Categories

const category = await client.createCategory('Technology')
const entries = await client.getCategoryEntries(category.id, { status: ['unread'] })
await client.markCategoryAsRead(category.id)

Search

const results = await client.searchEntries('typescript', 10)

System information

const health = await client.healthcheck()
const version = await client.getVersion()
const counters = await client.getCounters()

Error handling

All methods return promises. Failed Miniflux responses are converted to Error instances with the API error message when available.

try {
  await client.refreshAllFeeds()
} catch (error) {
  console.error(error instanceof Error ? error.message : error)
}

API overview

User methods

• getMe()
• getUsers()
• getUser(userId)
• createUser(username, password, isAdmin)
• updateUser(userId, changes)
• deleteUser(userId)
• markUserAsRead(userId)

Feed methods

• getFeeds()
• getFeed(feedId)
• createFeed(feedUrl, categoryId?)
• updateFeed(feedId, changes)
• deleteFeed(feedId)
• refreshFeed(feedId)
• refreshAllFeeds()
• markFeedAsRead(feedId)
• getFeedIcon(feedId)
• getFeedEntries(feedId, filter?)

Entry methods

• getEntries(filter?)
• getEntry(entryId)
• updateEntryStatus(entryId, status)
• updateEntry(entryId, payload)
• toggleBookmark(entryId)
• fetchContent(entryId)
• saveEntry(entryId)
• searchEntries(query, limit?)
• getMinifluxEntryUrl(entryId)

Category methods

• getCategories()
• createCategory(title)
• updateCategory(categoryId, title)
• deleteCategory(categoryId)
• refreshCategoryFeeds(categoryId)
• getCategoryEntries(categoryId, filter?)
• markCategoryAsRead(categoryId)

Enclosure methods

• getEnclosure(enclosureId)
• updateEnclosure(enclosureId, mediaProgression)

System methods

• healthcheck()
• getVersion()
• getCounters()

Documentation

Generate API documentation locally:

pnpm build:docs

Then open docs/index.html in your browser.

Development

pnpm install
pnpm lint
pnpm test
pnpm typecheck
pnpm build
pnpm build:docs

Integration tests require a running Miniflux instance. Copy .env.example to .env and adjust the values before running:

pnpm test:integration

Publishing checklist

Before publishing a new release:

pnpm lint
pnpm test
pnpm typecheck
pnpm build
pnpm build:docs
npm pack --dry-run

Then update CHANGELOG.md, bump the version and publish with npm publish.

License

MIT © Sevi.C