Reddit Saved API for Browser Extensions

一个轻量级的 TypeScript 库，用于在浏览器插件中获取 Reddit 保存的内容。

基于 PRAW (Python Reddit API Wrapper) 的设计理念，专门为浏览器插件环境改造。

🎯 快速体验

本项目包含一个完整的示例浏览器插件，可以直接使用：

``bash


1. 克隆或下载本项目

2. 安装依赖

npm install

3. 构建库和插件

npm run build:extension

4. 在 Chrome 中加载插件

- 打开 chrome://extensions/

- 开启"开发者模式"

- 点击"加载已解压的扩展程序"

- 选择 extension/ 目录

`

插件功能：
- 🔐 自动检测 Reddit 登录状态
- 👤 展示用户信息（头像、用户名、bio、Karma）确认身份
- 📚 查看保存的 Reddit 帖子和评论，按类型过滤
- 📝 查看自己发过的帖子，按排序方式切换
- 🎨 三步交互流程（登录检查 → 用户确认 → 内容浏览）

详见 extension/README.md

特性

- 🔐 Cookie 认证 - 直接使用用户已登录的 Reddit 会话，无需 OAuth2 配置
- 📦 TypeScript 支持 - 完整的类型定义
- 👤 用户信息 - 获取用户头像、bio、Karma 等详细信息
- 📝 用户帖子 - 获取用户发过的帖子，支持排序和分页
- 🚀 轻量级 - 无外部依赖
- ⚡ 自动分页 - 支持获取所有保存的内容
- 🔄 速率限制 - 自动处理 Reddit API 的速率限制
- 🔁 重试机制 - 网络错误自动重试

安装

`bash
npm install @youmind-openlab/reddit-api


或


pnpm add @youmind-openlab/reddit-api
`

前置要求

你的浏览器插件需要在 manifest.json 中声明以下权限：

`json
{
"permissions": ["cookies"],
"host_permissions": ["https://.reddit.com/"]
}
`

快速开始

$3

`typescript
import { createRedditClient, isSubmission, isComment } from '@youmind-openlab/reddit-api';

// 创建客户端
const reddit = createRedditClient();

// 检查用户是否已登录
if (await reddit.isLoggedIn()) {
// 获取保存的内容（分页）
const { items, after } = await reddit.getSaved({ limit: 25 });

for (const item of items) {
if (isSubmission(item)) {
console.log('帖子:', item.title);
} else if (isComment(item)) {
console.log('评论:', item.body.slice(0, 100));
}
}
}
`

$3

`typescript
// 使用异步迭代器（推荐，内存效率高）
for await (const item of reddit.getAllSaved()) {
console.log(item.name, item.subreddit);
}

// 或者一次性获取所有内容
const allItems = await reddit.getAllSavedArray();
console.log(共保存了 ${allItems.length} 条内容);
`

$3

`typescript
// 仅获取保存的帖子
const { items: submissions } = await reddit.getSavedSubmissions({ limit: 10 });

// 仅获取保存的评论
const { items: comments } = await reddit.getSavedComments({ limit: 10 });

// 使用异步迭代器获取所有帖子
for await (const submission of reddit.getAllSavedSubmissions()) {
console.log(submission.title);
}
`

$3

`typescript
// 保存帖子或评论
await reddit.save('t3_abc123'); // 帖子
await reddit.save('t1_xyz789'); // 评论

// 取消保存
await reddit.unsave('t3_abc123');
`

$3

`typescript
const user = await reddit.getMe();
console.log(用户名: ${user.name});
console.log(Karma: ${user.total_karma});

// 便捷方法
const avatar = await reddit.getAvatarUrl();
const bio = await reddit.getBio();
`

$3

`typescript
// 获取当前用户的帖子
const { items } = await reddit.getMySubmissions({ limit: 25, sort: 'new' });

// 获取指定用户的帖子
const { items: posts } = await reddit.getUserSubmissions('username', {
sort: 'top',
time: 'year',
});

// 自动分页获取所有帖子
for await (const post of reddit.getAllMySubmissions()) {
console.log(post.title);
}
`

API 参考

$3

创建 Reddit 客户端实例。

参数：
- config.userAgent - 用户代理字符串（可选）
- config.timeout - 请求超时时间，毫秒（默认 30000）
- config.redditUrl - Reddit URL（默认 'https://www.reddit.com'）

$3

#### 方法

| 方法 | 描述 |
|------|------|
| isLoggedIn() | 检查用户是否已登录 |
| getMe() | 获取当前用户信息（头像、Karma、bio 等） |
| getUsername() | 获取当前用户名 |
| getAvatarUrl() | 获取用户头像 URL |
| getBio() | 获取用户个人简介 |
| getSaved(options?) | 获取保存的内容（单页） |
| getAllSaved(options?) | 获取所有保存的内容（异步迭代器） |
| getAllSavedArray(options?) | 获取所有保存的内容（数组） |
| getSavedSubmissions(options?) | 获取保存的帖子 |
| getAllSavedSubmissions(options?) | 获取所有保存的帖子 |
| getSavedComments(options?) | 获取保存的评论 |
| getAllSavedComments(options?) | 获取所有保存的评论 |
| getMySubmissions(options?) | 获取当前用户的帖子（单页） |
| getUserSubmissions(username, options?) | 获取指定用户的帖子（单页） |
| getAllMySubmissions(options?) | 获取当前用户所有帖子（异步迭代器） |
| getAllUserSubmissions(username, options?) | 获取指定用户所有帖子（异步迭代器） |
| save(fullname, category?) | 保存内容 |
| unsave(fullname) | 取消保存 |
| getRateLimitInfo() | 获取速率限制信息 |
| clearCache() | 清除缓存 |

$3

`typescript
interface GetSavedOptions {
limit?: number; // 获取数量限制
after?: string; // 分页游标（下一页）
before?: string; // 分页游标（上一页）
count?: number; // 已获取数量
time?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'all';
type?: 'links' | 'comments';
}
`

$3

`typescript
interface GetSubmissionsOptions {
limit?: number; // 获取数量限制
sort?: 'hot' | 'new' | 'top' | 'controversial';
time?: 'hour' | 'day' | 'week' | 'month' | 'year' | 'all';
after?: string; // 分页游标（下一页）
before?: string; // 分页游标（上一页）
count?: number; // 已获取数量
}
`

$3

`typescript
// 判断类型
import { isSubmission, isComment } from '@youmind-openlab/reddit-api';

isSubmission(item) // 是否是帖子
isComment(item) // 是否是评论
`

在 Background Script 中使用

`typescript
// background.ts
import { createRedditClient, isSubmission, isComment } from '@youmind-openlab/reddit-api';

const reddit = createRedditClient();

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.type === 'GET_SAVED') {
reddit.getAllSavedArray({ limit: 100 })
.then(items => sendResponse({ success: true, items }))
.catch(error => sendResponse({ success: false, error: error.message }));
return true; // 保持消息通道开启
}
});
`

与 PRAW 的对比

| 功能 | PRAW | 本库 |
|------|------|------|
| 语言 | Python | TypeScript |
| 运行环境 | 服务器/命令行 | 浏览器插件 |
| 认证方式 | OAuth2 | Cookies |
| 功能范围 | 完整 Reddit API | saved、用户信息、用户帖子 |
| 大小 | 完整库 | 轻量级 |

项目结构

`
praw-for-browser-extension/
├── src/ # TypeScript 源码
│ ├── types/ # 类型定义
│ ├── auth.ts # Cookie 认证模块
│ ├── requestor.ts # HTTP 请求模块
│ ├── reddit.ts # Reddit 客户端
│ └── index.ts # 导出入口
├── dist/ # 构建产物
├── extension/ # 示例浏览器插件
│ ├── manifest.json # 插件配置
│ ├── background/ # 后台脚本
│ ├── popup/ # 弹窗界面
│ └── icons/ # 图标
├── examples/ # 代码示例
└── scripts/ # 构建脚本
``

许可证

MIT