Reddit Node SDK

A minimal Reddit API SDK for Node.js using native fetch API.

Features

• 🚀 Minimal and lightweight
• 📦 Zero dependencies (uses native Node.js fetch)
• 🔐 OAuth2 access token authentication
• 📘 Full TypeScript support
• 🗂️ Modular structure with separated concerns

Installation

npm install reddit-node-sdk

Quick Start

import { RedditClient } from 'reddit-node-sdk';

const client = new RedditClient('your-app-name/1.0');

const me = await client.getMe(accessToken);
console.log(`Hello, ${me.name}!`);

Project Structure

src/
├── types/           # TypeScript type definitions
│   ├── common.ts    # Common types (RequestContext, options)
│   └── account.ts   # Account endpoint types
├── endpoints/       # Endpoint implementations
│   └── account.ts   # Account-related endpoints
└── RedditClient.ts  # Main client class

API Reference

RedditClient

Constructor

new RedditClient(userAgent: string, options?: RedditClientOptions)

• userAgent (required): A unique identifier for your application
• options (optional):
  • baseUrl: Custom API base URL (default: https://oauth.reddit.com)

Account Endpoints

All methods require a valid OAuth2 accessToken as the first parameter.

getMe(accessToken, options?)

Get information about the authenticated user.

const me = await client.getMe(accessToken);
console.log(me.name, me.total_karma);

Returns: RedditMeResponse with fields:

• name, id, created_utc
• link_karma, comment_karma, total_karma
• verified, is_gold, has_verified_email
• subreddit (user profile subreddit)
• And many more...

getKarma(accessToken, options?)

Get breakdown of karma by subreddit.

const karma = await client.getKarma(accessToken);
karma.data.forEach(entry => {
  console.log(`r/${entry.sr}: ${entry.link_karma} link, ${entry.comment_karma} comment`);
});

Returns: KarmaListResponse

Note: This endpoint may not be available for all accounts (returns 404).

getPrefs(accessToken, options?)

Get user preference settings.

const prefs = await client.getPrefs(accessToken);
console.log(`Language: ${prefs.lang}, Night mode: ${prefs.nightmode}`);

Options:

• fields: Comma-separated list of preference fields to return

Returns: UserPreferences with fields like:

• lang, country_code
• nightmode, over_18
• default_comment_sort, num_comments
• email_* preferences
• And 60+ other preference fields

updatePrefs(accessToken, prefs)

Update user preferences.

await client.updatePrefs(accessToken, {
  nightmode: true,
  lang: 'en'
});

Parameters:

• prefs: Partial object with preferences to update

Returns: Updated UserPreferences

getTrophies(accessToken, options?)

Get list of trophies for the current user.

const trophies = await client.getTrophies(accessToken);
trophies.data.trophies.forEach(trophy => {
  console.log(trophy.data.name);
});

Returns: TrophiesResponse with structure:

{
  kind: "TrophyList",
  data: {
    trophies: Trophy[]
  }
}

Research Notes

This SDK was built by testing actual Reddit API responses. Key findings documented in code:

Account Endpoints (/api/v1/me/*)

• GET /api/v1/me: Returns comprehensive user account data (30+ fields)
• GET /api/v1/me/karma: Returns karma breakdown by subreddit (may return 404 for some accounts)
• GET /api/v1/me/prefs: Returns flat JSON object with 60+ preference settings
• PATCH /api/v1/me/prefs: Accepts partial JSON to update specific preferences
• GET /api/v1/me/trophies: Returns {kind: "TrophyList", data: {trophies: []}}

All endpoints require:

• Authorization: Bearer {accessToken} header
• User-Agent: {your-user-agent} header

Example

See examples/basic-usage.ts for a complete working example.

export REDDIT_ACCESS_TOKEN="your-token-here"
npm run example

Expected output:

=== Testing Account Endpoints ===

1. GET /api/v1/me
   Username: your_username
   ID: xxxxx
   Karma: 123 (Link: 100, Comment: 23)
   Verified: true
   Gold: false

2. GET /api/v1/me/prefs
   Language: en
   Night mode: false
   Over 18: false
   ...

✓ All tests completed!

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run example
npm run example

License

MIT