# atBB Bruno API Collections

This directory contains [Bruno](https://www.usebruno.com/) API collections for testing and documenting the atBB forum API.

## Structure

```
bruno/
├── environments/           # Environment configurations
│   ├── local.bru          # Local development (default)
│   └── dev.bru            # Development server
└── AppView API/           # AppView API endpoints
    ├── Health/            # Health check
    ├── Auth/              # OAuth authentication flow
    ├── Forum/             # Forum metadata
    ├── Categories/        # Category management
    ├── Topics/            # Topic (thread) operations
    └── Posts/             # Post (reply) operations
```

## Getting Started

### 1. Install Bruno

Download and install Bruno from [usebruno.com](https://www.usebruno.com/) or via package manager:

```sh
# macOS (Homebrew)
brew install bruno

# Arch Linux
yay -S bruno-bin

# Or download from GitHub releases
```

### 2. Open the Collection

1. Launch Bruno
2. Click "Open Collection"
3. Navigate to `/path/to/atbb-monorepo/bruno`
4. Select the `bruno` folder

### 3. Start Your Local Servers

```sh
# In the monorepo root
pnpm dev
```

This will start:
- AppView API at `http://localhost:3000`
- Web UI at `http://localhost:3001`

### 4. Configure Environment Variables

The `local` environment is pre-configured for local development. Update these variables in `environments/local.bru` as needed:

- `appview_url` - AppView API base URL (default: `http://localhost:3000`)
- `web_url` - Web UI base URL (default: `http://localhost:3001`)
- `forum_did` - Forum DID from your `.env` file
- `user_handle` - Your AT Protocol handle for testing auth (e.g., `user.bsky.social`)
- `topic_id` - A valid topic ID for testing topic retrieval

## API Overview

### Health Check

- **GET /api/healthz** - Service health status

### Authentication

OAuth flow using `@atproto/oauth-client-node`:

1. **GET /api/auth/login?handle=user.bsky.social** - Initiate login
2. **GET /api/auth/callback** - OAuth callback (handled by PDS redirect)
3. **GET /api/auth/session** - Check current session
4. **GET /api/auth/logout** - Logout and revoke tokens

**Note:** OAuth login requires a browser flow. Use the Web UI for interactive testing.

### Forum Data

- **GET /api/forum** - Get forum metadata
- **GET /api/categories** - List all categories
- **GET /api/topics/:id** - Get topic with replies
- **POST /api/topics** - Create new topic (requires auth)
- **POST /api/posts** - Create reply (requires auth)

## Testing Authenticated Endpoints

Authenticated endpoints (`POST /api/topics`, `POST /api/posts`) require a valid session cookie (`atbb_session`). Bruno's cookie jar will automatically store and send cookies.

**To test authenticated endpoints:**

1. Use your browser to log in via the Web UI at `http://localhost:3001`
2. Use browser dev tools to copy the `atbb_session` cookie value
3. In Bruno, go to the collection settings and add a header:
   ```
   Cookie: atbb_session=<your-cookie-value>
   ```

Or use Bruno's cookie management to manually set the cookie.

## Environment Variables Reference

| Variable | Description | Example |
|----------|-------------|---------|
| `appview_url` | AppView API base URL | `http://localhost:3000` |
| `web_url` | Web UI base URL | `http://localhost:3001` |
| `forum_did` | Forum DID | `did:plc:abc123...` |
| `user_handle` | Your AT Protocol handle | `user.bsky.social` |
| `topic_id` | Valid topic ID for testing | `1` |

## Bruno Features Used

- **Environments** - Switch between local/dev with one click
- **Variables** - `{{variable}}` syntax for reusable values
- **Assertions** - Automated response validation
- **Documentation** - Inline docs for each endpoint
- **Request chaining** - Variables can be set from responses (not used yet, but available)

## Tips

- Use the **Environments dropdown** in Bruno to switch between local and dev
- Each request includes a **Docs** tab explaining the endpoint
- **Assertions** will automatically validate responses (green checkmark = passed)
- Browse requests by category in the left sidebar
- Requests are plain text files — they're versioned in git!

## Adding New Endpoints

When you add new API routes:

1. Create a new `.bru` file in the appropriate folder
2. Follow the existing format (meta, get/post, headers, body, docs)
3. Use environment variables (`{{appview_url}}`) for URLs
4. Add assertions to validate responses
5. Commit the file — it's part of your API documentation!

## Resources

- [Bruno Documentation](https://docs.usebruno.com/)
- [AT Protocol Docs](https://atproto.com/)
- [atBB Project Plan](../docs/atproto-forum-plan.md)