77 lines
3.1 KiB
TypeScript
77 lines
3.1 KiB
TypeScript
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
import { API_OPERATIONS } from '../src/web/api-catalog.js';
|
|
|
|
const rows = API_OPERATIONS.map((operation) =>
|
|
`| \`${operation.method}\` | \`${operation.path}\` | ${operation.summary} | ${operation.access} | ${operation.mutates ? 'yes' : 'no'} |`,
|
|
).join('\n');
|
|
|
|
const document = `# RedditBot API
|
|
|
|
This file is generated from \`src/web/api-catalog.ts\`. Run \`npm run docs:api\`
|
|
after changing the HTTP surface. The live OpenAPI 3.1 document is available at
|
|
\`GET /api/openapi.json\`, and compact agent discovery is available at
|
|
\`GET /api/v1/capabilities\`.
|
|
|
|
## Authentication
|
|
|
|
The dashboard token is an administrator credential. Browser users can exchange
|
|
it for an HttpOnly, SameSite=Strict session; API clients can send it as a bearer
|
|
token.
|
|
|
|
Optional least-privilege bearer credentials are configured with:
|
|
|
|
- \`REDDIT_BOT_AGENT_READ_TOKEN\`: GET, HEAD, SSE, and private-media reads except debug routes.
|
|
- \`REDDIT_BOT_AGENT_CONTROL_TOKEN\`: read access plus mutations under \`/api/v1\`.
|
|
|
|
Control credentials cannot send messages, import sessions, activate accounts,
|
|
or update legacy configuration endpoints. Those operations require the
|
|
administrator dashboard token.
|
|
|
|
## Agent entry points
|
|
|
|
- \`GET /healthz\`: unauthenticated process liveness with no private state.
|
|
- \`GET /api/v1/readyz\`: component readiness and authentication degradation.
|
|
- \`GET /api/v1/overview\`: bot, account, sync, rate-limit, and recent-error snapshot.
|
|
- \`GET /api/v1/control\`: current running state.
|
|
- \`POST /api/v1/control/start\`, \`/stop\`, or \`POST /api/v1/control\`: explicit bot control.
|
|
- \`POST /api/v1/jobs\`: tracked chat/media sync; poll \`GET /api/v1/jobs/:id\`.
|
|
- \`GET /api/events/stream\`: replayable typed SSE events.
|
|
|
|
## MCP server
|
|
|
|
Run the stdio MCP adapter with \`npm run mcp\`. It connects to
|
|
\`REDDIT_BOT_API_URL\` (default \`http://127.0.0.1:3000\`) and reads its bearer
|
|
credential from \`REDDIT_BOT_AGENT_TOKEN\`, then the scoped agent variables, and
|
|
finally \`WEB_DASHBOARD_TOKEN\`.
|
|
|
|
Read tools cover overview, readiness, accounts, activity, conversations,
|
|
errors, sync state, and performance. Control tools include \`start_bot\`,
|
|
\`stop_bot\`, \`set_bot_running\`, \`trigger_sync\`, and \`get_job\`. External
|
|
message tools are separately annotated as destructive/non-idempotent and need
|
|
an administrator credential.
|
|
|
|
## Operations
|
|
|
|
| Method | Path | Summary | Access | Mutates |
|
|
|---|---|---|---|---|
|
|
${rows}
|
|
|
|
## Error model
|
|
|
|
Errors use JSON with an \`error\` string and optional \`detail\`. Authentication
|
|
failures are \`401\`; recognized but insufficient agent credentials receive
|
|
\`403\`; invalid inputs receive \`400\`; unavailable services receive \`503\`.
|
|
Long-running agent jobs expose failure text in the job resource.
|
|
`;
|
|
|
|
const target = path.resolve(process.cwd(), 'docs/api.md');
|
|
if (process.argv.includes('--check')) {
|
|
if (!fs.existsSync(target) || fs.readFileSync(target, 'utf8') !== document) {
|
|
process.stderr.write('docs/api.md is stale; run npm run docs:api\n');
|
|
process.exitCode = 1;
|
|
}
|
|
} else {
|
|
fs.writeFileSync(target, document);
|
|
}
|