malpercio.dev
WIP! A BB-style forum, on the ATmosphere!
We're still working... we'll be back soon when we have something to show off!
node
typescript
hono
htmx
atproto
1# atBB Bruno API Collections
2
3This directory contains [Bruno](https://www.usebruno.com/) API collections for testing and documenting the atBB forum API.
4
5## Structure
6
7```
8bruno/
9├── environments/ # Environment configurations
10│ ├── local.bru # Local development (default)
11│ └── dev.bru # Development server
12└── AppView API/ # AppView API endpoints
13 ├── Health/ # Health check
14 ├── Auth/ # OAuth authentication flow
15 ├── Forum/ # Forum metadata
16 ├── Categories/ # Category management
17 ├── Topics/ # Topic (thread) operations
18 └── Posts/ # Post (reply) operations
19```
20
21## Getting Started
22
23### 1. Install Bruno
24
25Download and install Bruno from [usebruno.com](https://www.usebruno.com/) or via package manager:
26
27```sh
28# macOS (Homebrew)
29brew install bruno
30
31# Arch Linux
32yay -S bruno-bin
33
34# Or download from GitHub releases
35```
36
37### 2. Open the Collection
38
391. Launch Bruno
402. Click "Open Collection"
413. Navigate to `/path/to/atbb-monorepo/bruno`
424. Select the `bruno` folder
43
44### 3. Start Your Local Servers
45
46```sh
47# In the monorepo root
48pnpm dev
49```
50
51This will start:
52- AppView API at `http://localhost:3000`
53- Web UI at `http://localhost:3001`
54
55### 4. Configure Environment Variables
56
57The `local` environment is pre-configured for local development. Update these variables in `environments/local.bru` as needed:
58
59- `appview_url` - AppView API base URL (default: `http://localhost:3000`)
60- `web_url` - Web UI base URL (default: `http://localhost:3001`)
61- `forum_did` - Forum DID from your `.env` file
62- `user_handle` - Your AT Protocol handle for testing auth (e.g., `user.bsky.social`)
63- `topic_id` - A valid topic ID for testing topic retrieval
64
65## API Overview
66
67### Health Check
68
69- **GET /api/healthz** - Service health status
70
71### Authentication
72
73OAuth flow using `@atproto/oauth-client-node`:
74
751. **GET /api/auth/login?handle=user.bsky.social** - Initiate login
762. **GET /api/auth/callback** - OAuth callback (handled by PDS redirect)
773. **GET /api/auth/session** - Check current session
784. **GET /api/auth/logout** - Logout and revoke tokens
79
80**Note:** OAuth login requires a browser flow. Use the Web UI for interactive testing.
81
82### Forum Data
83
84- **GET /api/forum** - Get forum metadata
85- **GET /api/categories** - List all categories
86- **GET /api/topics/:id** - Get topic with replies
87- **POST /api/topics** - Create new topic (requires auth)
88- **POST /api/posts** - Create reply (requires auth)
89
90## Testing Authenticated Endpoints
91
92Authenticated endpoints (`POST /api/topics`, `POST /api/posts`) require a valid session cookie (`atbb_session`). Bruno's cookie jar will automatically store and send cookies.
93
94**To test authenticated endpoints:**
95
961. Use your browser to log in via the Web UI at `http://localhost:3001`
972. Use browser dev tools to copy the `atbb_session` cookie value
983. In Bruno, go to the collection settings and add a header:
99 ```
100 Cookie: atbb_session=<your-cookie-value>
101 ```
102
103Or use Bruno's cookie management to manually set the cookie.
104
105## Environment Variables Reference
106
107| Variable | Description | Example |
108|----------|-------------|---------|
109| `appview_url` | AppView API base URL | `http://localhost:3000` |
110| `web_url` | Web UI base URL | `http://localhost:3001` |
111| `forum_did` | Forum DID | `did:plc:abc123...` |
112| `user_handle` | Your AT Protocol handle | `user.bsky.social` |
113| `topic_id` | Valid topic ID for testing | `1` |
114
115## Bruno Features Used
116
117- **Environments** - Switch between local/dev with one click
118- **Variables** - `{{variable}}` syntax for reusable values
119- **Assertions** - Automated response validation
120- **Documentation** - Inline docs for each endpoint
121- **Request chaining** - Variables can be set from responses (not used yet, but available)
122
123## Tips
124
125- Use the **Environments dropdown** in Bruno to switch between local and dev
126- Each request includes a **Docs** tab explaining the endpoint
127- **Assertions** will automatically validate responses (green checkmark = passed)
128- Browse requests by category in the left sidebar
129- Requests are plain text files — they're versioned in git!
130
131## Adding New Endpoints
132
133When you add new API routes:
134
1351. Create a new `.bru` file in the appropriate folder
1362. Follow the existing format (meta, get/post, headers, body, docs)
1373. Use environment variables (`{{appview_url}}`) for URLs
1384. Add assertions to validate responses
1395. Commit the file — it's part of your API documentation!
140
141## Resources
142
143- [Bruno Documentation](https://docs.usebruno.com/)
144- [AT Protocol Docs](https://atproto.com/)
145- [atBB Project Plan](../docs/atproto-forum-plan.md)