# @kody/reddit — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Never paste
OAuth client secrets or access tokens. Do not disable live webhooks or jobs
(this package declares none).

## Auth

| Item | Value |
| --- | --- |
| Integration | `reddit` (or `reddit-<purpose>` via `account`) |
| API base | `https://oauth.reddit.com` |
| Reconnect | `https://kody.codes/connect/oauth?provider=reddit` |
| Hosts | `oauth.reddit.com`, `www.reddit.com` |
| User-Agent | package sends `web:kody.reddit:1.0.0 (https://kody.codes/@kody/reddit)` |

Transport uses `createAuthenticatedFetch('reddit')`. There is no usable public
Reddit OpenAPI for the full OAuth surface — prefer named helpers, then
`./request`.

## Import paths

| Export | Import |
| --- | --- |
| root overview | `kody:@kody/reddit` |
| accounts | `kody:@kody/reddit/accounts` |
| smoke-test | `kody:@kody/reddit/smoke-test` |
| get-me | `kody:@kody/reddit/get-me` |
| get-subreddit | `kody:@kody/reddit/get-subreddit` |
| get-listing | `kody:@kody/reddit/get-listing` |
| search | `kody:@kody/reddit/search` |
| get-user | `kody:@kody/reddit/get-user` |
| get-post | `kody:@kody/reddit/get-post` |
| request | `kody:@kody/reddit/request` |
| submit-post | `kody:@kody/reddit/submit-post` |
| submit-comment | `kody:@kody/reddit/submit-comment` |
| vote | `kody:@kody/reddit/vote` |

Prefer static `kody:@kody/reddit/...` imports from `execute`. Do not lead with
`packages.invoke`.

## Smoke test (read-only)

Run on the **forked** package after connect. Does not return the username.

```js
import smokeTest from 'kody:@kody/reddit/smoke-test'

export default async function main() {
	return await smokeTest()
	// => { ok: true, integration: 'reddit', hasId: true, hasName: true }
}
```

## Common snippets

```js
import getListing from 'kody:@kody/reddit/get-listing'

export default async function main() {
	return await getListing({ subreddit: 'programming', sort: 'hot', limit: 5 })
}
```

```js
import search from 'kody:@kody/reddit/search'

export default async function main() {
	return await search({ query: 'kody agents', limit: 5 })
}
```

## dryRun / confirm (writes)

`submit-post`, `submit-comment`, and `vote` never mutate when `dryRun: true`.
A live write requires a fresh `confirm: true` after the user approved the exact
payload.

```js
import submitPost from 'kody:@kody/reddit/submit-post'

export default async function main() {
	return await submitPost({
		subreddit: 'test',
		title: 'Draft title',
		text: 'Draft body',
		dryRun: true,
	})
}
```

## Edge cases / fork notes

- Jobs are off — do not add scrapers or 24/7 bots in forks without explicit ask.
- HTTP 401 / 403: reconnect; confirm Reddit app is a **web app** and redirect is
  exactly `https://kody.codes/connect/oauth`.
- HTTP 429: unique User-Agent is required; this package sets one. If token
  exchange itself is blocked, reconnect after the connect page UA is fixed —
  never paste tokens into chat.
- `./request` uses whatever scopes the saved token already has.
- Pass `account: '<purpose>'` for `reddit-<purpose>`; never hard-code a username.
- Never paste Reddit client secrets or access tokens into chat or logs.