# DevPlace devRant API examples

Plug-and-play clients and scripts for the devRant-compatible REST protocol served at
`/api`. The Python scripts use only the standard library (`urllib`); the JavaScript
scripts use Node 18+ (global `fetch`, ES modules). No dependencies to install. Full
reference: `/docs/devrant.html`.

## Files

| File | Language | What it does |
|------|----------|--------------|
| `client.py` / `client.mjs` | Python / JS | Reusable `DevRant` client: login, token injection, every endpoint. Imported by the others. |
| `post_rant.py` / `post_rant.mjs` | Python / JS | Log in and post one rant from the command line. |
| `feed_watch.py` / `feed_watch.mjs` | Python / JS | Live feed ticker; optionally auto-upvotes rants matching keywords. |
| `smoke_test.py` / `smoke_test.mjs` | Python / JS | End-to-end conformance test: registers a throwaway user and exercises every endpoint, printing PASS/FAIL. |

## Configuration

The scripts read their settings from environment variables:

| Variable | Default | Purpose |
|----------|---------|---------|
| `DEVRANT_BASE` | `http://localhost:10500` | Base URL of the DevPlace server (no `/api` suffix) |
| `DEVRANT_USERNAME` | (none) | Username for write operations |
| `DEVRANT_PASSWORD` | (none) | Password for write operations |
| `DEVRANT_POLL_SECONDS` | `30` | `feed_watch` poll interval |
| `DEVRANT_UPVOTE_KEYWORDS` | (empty) | Comma-separated keywords `feed_watch` auto-upvotes |

## Run

```bash
# post a rant
DEVRANT_USERNAME=you DEVRANT_PASSWORD=secret6 \
  python post_rant.py "Posted from a script" "python,automation"

# same in JavaScript
DEVRANT_USERNAME=you DEVRANT_PASSWORD=secret6 \
  node post_rant.mjs "Posted from a script" "python,automation"

# watch the feed and auto-upvote anything mentioning rust
DEVRANT_USERNAME=you DEVRANT_PASSWORD=secret6 DEVRANT_UPVOTE_KEYWORDS=rust \
  python feed_watch.py

# run the full conformance test against a running server
DEVRANT_BASE=http://localhost:10500 python smoke_test.py
DEVRANT_BASE=http://localhost:10500 node smoke_test.mjs
```

## Notes

- Authentication follows the devRant model: `login()` calls `POST /api/users/auth-token`
  and stores the `(user_id, token_id, token_key)` triple, which is then sent with every
  call (query params for `GET`/`DELETE`, form body for `POST`).
- Read endpoints (feed, single rant, search, profiles) work without logging in.
- These scripts target a DevPlace server. A legacy devRant client hard-coded to
  `devrant.com` is reached only through host routing (DNS/reverse-proxy), which is an
  infrastructure concern outside these examples.
