# @kody/reddit

Official Reddit logo (`#FF4500`) from [Reddit brand guidelines](https://www.redditinc.com/brand).

## Intent

Give any Kody account reusable, headless Reddit helpers for subreddit metadata, listings, search, user reads, a generic authenticated request escape hatch, and guarded writes (submit post, submit comment, vote). Author identity is always resolved from the connected Reddit account — never hard-coded to a specific username.

This listing is meant to be forked. After you fork, connect **your** Reddit account and run the smoke test on **your** copy. Do not treat the live `@kody/reddit` integration as yours.

Share this package as https://kody.codes/@kody/reddit
(never a `/community/{listing_id}` URL).

## What it does

- Verify the saved `reddit` OAuth integration and read the connected account
- Look up a subreddit, listing, search result, user, or post/comment thread
- Call uncommon Reddit OAuth endpoints with `./request`
- Preview a post, comment, or vote with `dryRun: true`, then mutate only after `confirm: true`

Do not use this package as a scraper, a 24/7 bot, or a place to paste access tokens. Jobs are off.

## Prerequisites / setup

Reddit is **bring-your-own OAuth**. There is no built-in Kody Reddit app. Tokens come from the hosted connect page (`createAuthenticatedFetch('reddit')`). Never paste a client secret or access token into chat.

1. Open [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps) → **create another app…**.
2. Choose **web app**.
3. **redirect uri** → add exactly `https://kody.codes/connect/oauth` (the connect page shows the same value with a copy button).
4. Note the app’s client id (under the name) and secret (paste them into Kody, not into chat).
5. Open this prefilled connect URL while signed in to Kody:

```text
https://kody.codes/connect/oauth?provider=reddit
```

First-time setup also needs Reddit’s authorize and token URLs. Use this complete prefilled URL when the connection does not exist yet:

```text
https://kody.codes/connect/oauth?provider=reddit&authorizeUrl=https%3A%2F%2Fwww.reddit.com%2Fapi%2Fv1%2Fauthorize&tokenUrl=https%3A%2F%2Fwww.reddit.com%2Fapi%2Fv1%2Faccess_token&apiBaseUrl=https%3A%2F%2Foauth.reddit.com&flow=confidential&tokenExchangeStyle=basic-form&allowedHosts=oauth.reddit.com%2Cwww.reddit.com&dashboardUrl=https%3A%2F%2Fwww.reddit.com%2Fprefs%2Fapps&scopes=identity%20read%20history%20mysubreddits%20submit%20edit%20vote%20save&extraAuthorizeParams=duration%3Dpermanent
```

Decoded:

- Redirect / callback: `https://kody.codes/connect/oauth`
- Authorize: `https://www.reddit.com/api/v1/authorize`
- Token: `https://www.reddit.com/api/v1/access_token`
- API base: `https://oauth.reddit.com`
- Flow: `confidential` with `tokenExchangeStyle=basic-form` (HTTP Basic + form body)
- Hosts: `oauth.reddit.com`, `www.reddit.com`
- Extra authorize param: `duration=permanent` (needed for a refresh token)
- Scopes: `identity`, `read`, `history`, `mysubreddits`, `submit`, `edit`, `vote`, `save`

6. Paste the client id and secret into the Kody form, continue to Reddit, and approve.
7. Agents: see [`AGENTS.md`](./AGENTS.md) for smoke-test imports and write previews.

Reconnect the same connection with `https://kody.codes/connect/oauth?provider=reddit`. Kody reuses the saved authorize/token endpoints.

### Scopes

| Scope | Used by |
| --- | --- |
| `identity` | `./smoke-test`, `./get-me` |
| `read` | listings, search, subreddit about, posts, comments, user about |
| `history` | authenticated user history when requested through `./request` |
| `mysubreddits` | subscribed-community reads through `./request` |
| `submit` | `./submit-post`, `./submit-comment` |
| `edit` | edits through `./request` |
| `vote` | `./vote` |
| `save` | saves through `./request` |

Pass `account: '<purpose>'` for integration `reddit-<purpose>` (omit → `reddit`). Do not hard-code a username in forks.

## Done when

- The `reddit` OAuth integration is connected; hosts `oauth.reddit.com` and `www.reddit.com` are approved
- Smoke test returns `{ ok: true, integration: 'reddit', hasId: true, hasName: true }` without the username
- Writes preview with `dryRun: true` and only run live with `confirm: true` after you approve the exact payload

## Branding

`community-icon.svg` uses Reddit’s official brand mark (`#FF4500`) from [Reddit brand guidelines](https://www.redditinc.com/brand). Reddit® is a trademark of Reddit, Inc. This package is not affiliated with or endorsed by Reddit.

## Docs

- [Reddit API](https://www.reddit.com/dev/api)
- [OAuth2](https://github.com/reddit-archive/reddit/wiki/OAuth2)
- [prefs/apps](https://www.reddit.com/prefs/apps)