stdout-chat 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `stdout-chat` (the CLI). Dates are release dates.
 
+## [0.3.0] — 2026-09-20
+
+### What's New
+
+- `/dm <nick|sid>` at the prompt invites someone from #void to a private chat. Pass a nick, or the id of one of their lines (the dim column on the left) to target that author. The invite lives 10 minutes; accepting happens in the app, and the private chat itself opens on your phone — the CLI prints the server's answer (`invite sent · nova has 10 min · you'll get a push when they accept`) or its refusal verbatim (`not_found`, `busy`, `rate_limited` …).
+
+### Technical
+
+- `lib/api.js`: `dm({ nick | sid }, key)` → `POST /void/dm`, JSON body `{sid}` or `{nick}`, `Accept: application/json`, returns `{ id, to, expires_at }`. Errors go through the existing `ApiError` mapping (server `message` verbatim, `retry_after` honoured).
+- `lib/session.js`: `cmdDm` — no key → the usual hint, no argument → `usage: /dm <nick|sid>`, argument equal to a `sid` seen this session → `{sid}`, otherwise `{nick}`; the success line is built from the returned `to`.
+- Tests: 76 → 82 (`/dm` sid/nick routing, usage, no-key, verbatim errors; `api.dm` request shape).
+
 ## [0.2.0] — 2026-09-20
 
 ### What's New

package/README.md

@@ -47,6 +47,7 @@ The key is checked against the server, then saved to `~/.config/stdout-chat/conf
 | `/r <id> text` | reply to a line — ids are the dim column on the left |
 | `/top` | this week's top authors |
 | `/who` | how many are in the room |
+| `/dm <nick|sid>` | invite them to a private chat — a line's id targets its author; the chat itself opens on your phone |
 | `/key sc_…` | save a key · `/key` shows who you are · `/key off` forgets it |
 | `/notify` | desktop banners: `/notify` shows the level · `/notify mentions` (default) · `all` · `off` |
 | `/clear` | clear the screen |
@@ -97,6 +98,7 @@ void() {  # void · void -f · void -r a1b4 text · void some words
 - `GET /void` for history, `GET /void/stream` (Server-Sent Events) for the live feed, `POST /void` to speak, `GET /void/me` to check a key. All JSON.
 - Reconnects with backoff (1 → 30 s) and `Last-Event-ID`, so nothing is missed across the server's 15-minute stream rotation.
 - Plain scrolling output with a `readline` prompt: no alternate screen, no curses — works in tmux splits and over ssh.
+- `POST /void/dm` sends a private-chat invite (`/dm`). The invite lives 10 minutes; when they accept you get a push and the private chat opens in the app on your phone — the terminal only sends the invite and prints what the server says.
 
 ## Notifications
 

package/bin/stdout-chat.js

@@ -25,7 +25,7 @@ usage: npx stdout-chat [options]
   -v, --version   print the version
 
 at the prompt:
-  /help  /r <id> text  /top  /who  /key sc_…  /key off  /notify  /clear  /quit
+  /help  /r <id> text  /dm <nick|sid>  /top  /who  /key sc_…  /key off  /notify  /clear  /quit
   anything else is posted to #void
 
 desktop banners (macOS / Linux) when someone replies to you or writes @you —

package/lib/api.js

@@ -90,6 +90,20 @@ export function createApi({ base = DEFAULT_API, version = '0.0.0', fetchImpl = n
       });
     },
 
+    /**
+     * POST /void/dm {sid} | {nick} → 201 { id, to, expires_at }. Same shape as
+     * post(): JSON in, JSON out (Accept: application/json); the session builds
+     * the human line from `to`. Errors carry the server's message verbatim.
+     */
+    dm({ nick, sid } = {}, key) {
+      const body = sid != null && sid !== '' ? { sid: String(sid) } : { nick: String(nick == null ? '' : nick) };
+      return json(`${root}/void/dm`, {
+        method: 'POST',
+        headers: headers({ 'Content-Type': 'application/json' }, key),
+        body: JSON.stringify(body),
+      });
+    },
+
     /** GET /void/stream → Response (200, body is a ReadableStream). Throws ApiError on non-2xx. */
     async openStream({ lastEventId = null, signal = null } = {}) {
       const extra = { 'Cache-Control': 'no-cache' };

package/lib/session.js

@@ -15,6 +15,7 @@ export const HELP_TEXT = [
   '/r <id> text       reply to a line (ids are the dim column on the left)',
   '/top               this week\'s top authors',
   '/who               how many are in the room',
+  '/dm <nick|sid>     invite them to a private chat (accept happens in the app)',
   '/key sc_…          save your key (get it in the app: /key)',
   '/key off           forget the key on this machine (revoke it in the app)',
   '/notify            desktop banners: mentions (default) · all · off',
@@ -309,6 +310,9 @@ export class Session {
       case '/who':
         await this.cmdWho();
         return;
+      case '/dm':
+        await this.cmdDm(rest);
+        return;
       case '/key':
         await this.cmdKey(rest);
         return;
@@ -352,6 +356,28 @@ export class Session {
     this.info(this.count === 1 ? '1 in room' : `${this.count} in room`);
   }
 
+  /** `/dm <nick|sid>`: a sid seen this session targets that line's author, anything else is a nick. */
+  async cmdDm(arg) {
+    if (!this.key) { this.info(HINT_NO_KEY); return; }
+    if (!arg) { this.info('usage: /dm <nick|sid>'); return; }
+    const target = this.isKnownSid(arg) ? { sid: arg } : { nick: arg };
+    let res;
+    try {
+      res = await this.api.dm(target, this.key);
+    } catch (err) {
+      this.error(errorMessage(err));
+      return;
+    }
+    const to = res && res.to != null && res.to !== '' ? String(res.to) : arg;
+    this.info(`invite sent · ${to} has 10 min · you'll get a push when they accept`);
+  }
+
+  /** True when `s` is the short id (the dim left column) of a line seen this session. */
+  isKnownSid(s) {
+    for (const m of this.lines.values()) if (m && m.sid != null && String(m.sid) === s) return true;
+    return false;
+  }
+
   async cmdKey(arg) {
     if (!arg) {
       if (this.me) this.info(greeting(this.me));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stdout-chat",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "#void from your terminal — read, tail and post to stdout.chat's public room. Zero dependencies.",
   "type": "module",
   "bin": {