# DevPlace XML-RPC examples

Runnable Python examples for the DevPlace XML-RPC bridge (`/xmlrpc`). They use only the
standard library (`xmlrpc.client`); no dependencies to install. Full reference:
`/docs/xmlrpc.html`.

## Files

| File | What it does |
|------|--------------|
| `client.py` | Reusable `DevPlace` wrapper: credential injection, all three auth styles, dotted-name calls, introspection helpers. Imported by the others. |
| `introspect.py` | Prints every available method with its help text. Needs no credentials. |
| `recipes.py` | Post, reply, vote, react, follow, message, and paginate the feed. |
| `mention_bot.py` | A bot that polls notifications and replies once to every `@mention`. |
| `chatbot.py` | An interactive chat bot over direct messages: polls the inbox, answers commands (`help`, `feed`, `echo`, `whoami`), and replies. |
| `ai_chatbot.py` | An AI-powered DM bot: message I/O over XML-RPC, replies generated by the DevPlace AI gateway, with per-user history. |
| `dm_client.py` | A two-way terminal chat client: send and receive direct messages with one user live. |
| `feed_watch.py` | Live feed ticker: prints new posts as they appear, optionally auto-upvotes posts matching keywords. |
| `digest.py` | Builds a digest of the latest posts, top members, and developer news; prints it or posts it. |
| `gist_backup.py` | Downloads all your gists to local files named by language. |
| `deploy_project.py` | Pushes a local directory into a new DevPlace project's virtual filesystem. |
| `rss_to_posts.py` | Polls an RSS/Atom feed and creates a post for each new entry. |
| `export_data.py` | Exports your profile, posts, gists, projects, bookmarks, and notifications to one JSON file. |

## Configuration

The scripts read their settings from environment variables:

| Variable | Default | Purpose |
|----------|---------|---------|
| `DEVPLACE_URL` | `https://devplace.net` | Full base URL of the DevPlace instance (scheme + host, no path) |
| `DEVPLACE_API_KEY` | `YOUR_API_KEY` | Your API key (from your profile page) |
| `DEVPLACE_POLL_SECONDS` | varies | Poll interval for the bots/watchers |
| `DEVPLACE_REPLY` | (a default) | Mention bot reply text |

`DEVPLACE_URL` defaults to `https://devplace.net`, so you only need to set `DEVPLACE_API_KEY`
to run the authenticated examples against the public instance.

## Run

```bash
# discover the API (no credentials needed)
python introspect.py

# run the automation recipes
DEVPLACE_API_KEY=xxxx python recipes.py

# run the mention bot (loops forever)
DEVPLACE_API_KEY=xxxx python mention_bot.py

# run the direct-message chat bot (loops forever, answers commands)
DEVPLACE_API_KEY=xxxx python chatbot.py

# open a two-way terminal chat with one user
DEVPLACE_API_KEY=xxxx python dm_client.py alice

# AI-powered DM bot (replies via the DevPlace AI gateway)
DEVPLACE_API_KEY=xxxx python ai_chatbot.py

# watch the feed live and auto-upvote posts mentioning "rust" or "python"
DEVPLACE_API_KEY=xxxx DEVPLACE_UPVOTE_KEYWORDS=rust,python python feed_watch.py

# build a digest and post it to the feed
DEVPLACE_API_KEY=xxxx DEVPLACE_DIGEST_POST=1 python digest.py

# back up every gist to ./gists_backup/
DEVPLACE_API_KEY=xxxx python gist_backup.py

# deploy a local folder as a new project
DEVPLACE_API_KEY=xxxx python deploy_project.py ./my-app "My App"

# mirror an RSS feed into posts
DEVPLACE_API_KEY=xxxx DEVPLACE_RSS_URL=https://example.com/feed.xml python rss_to_posts.py

# export all your data to JSON
DEVPLACE_API_KEY=xxxx python export_data.py alice
```

To run against a local dev server, point `DEVPLACE_URL` at it:

```bash
DEVPLACE_URL=http://localhost:10500 DEVPLACE_API_KEY=xxxx python recipes.py
```

## Authentication

`client.py` supports all three methods documented at `/docs/xmlrpc.html`:

```python
from client import DevPlace

# 1. API key (sent inside each call's parameter struct)
dp = DevPlace("https://devplace.net", api_key="YOUR_API_KEY")

# 2. Username and password (HTTP Basic via a credentialed URL)
dp = DevPlace("https://devplace.net", username="alice", password="secret123")
```

To authenticate with the API key as an HTTP header instead, see the `ApiKeyTransport` example
in `/docs/xmlrpc.html`.
