wldx-cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladimir Gorobets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# wldx-cli — `wx`, a command line for Wildix
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Version 0.1.1** · unofficial · MIT
+
+`wx` works with Wildix as **the logged-in user**: your chats today, more of x-bees later. It is the command-line
+twin of the [Wildix agent skills](https://github.com/gorets/wildix-skills) and shares their login.
+
+```sh
+npx wldx-cli chat list               # without installing
+npm i -g wldx-cli && wx chat list    # installed: the command is `wx`
+```
+
+Requires Node.js 22 or newer. No dependencies.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `wx chat list [--filter unread\|archived] [--section ID] [--cursor C]` | your channels, newest activity first |
+| `wx chat read <channel> [--unread] [--from SEQ] [--to SEQ]` | messages of a channel, newest first, 30 per page |
+| `wx chat send <channel> <text\|-> [--markdown] [--reply-to MESSAGE]` | send a message (`-` reads the text from stdin) |
+| `wx auth status` | the accounts you are logged in with and until when their token is valid (no network) |
+| `wx completion [bash\|zsh\|fish]` | the shell completion script (default: the shell of `$SHELL`) |
+
+A channel is an id or an inbox link; a message is an id or an inbox link to it. Every command takes
+`--account EMAIL` and `-h`. Output is JSON: indented on a terminal, one line in a pipe (`wx chat list | jq`).
+
+## Completion
+
+Tab completes commands, options and option values (`--filter unread|archived`, `--account` from the saved
+accounts); zsh and fish show a description next to each. Turn it on once, then open a new terminal:
+
+```sh
+echo 'eval "$(wx completion zsh)"'  >> ~/.zshrc     # zsh (after compinit, if your .zshrc runs it)
+echo 'eval "$(wx completion bash)"' >> ~/.bashrc    # bash, 3.2 (macOS) and newer
+wx completion fish > ~/.config/fish/completions/wx.fish
+```
+
+It completes an installed `wx` (`npm i -g wldx-cli`), not `npx wldx-cli`. The script asks `wx __complete` for the
+candidates on every Tab, so it follows new commands without being regenerated; it uses no network.
+
+## Login
+
+`wx` has no `login` yet. It uses the session saved by the `wildix-auth` agent skill
+(`npx skills add gorets/wildix-skills -s wildix-auth`): one file per account in `~/.wildix/tokens`
+(`$WILDIX_CONFIG_DIR/tokens`). An expired token is renewed and written back in the same format, so the skill and
+`wx` keep one session. With several accounts, pick one with `--account` or `WILDIX_EMAIL`.
+
+## Environment
+
+| Variable | Meaning |
+| --- | --- |
+| `WILDIX_EMAIL` | the account to use when several are logged in |
+| `WILDIX_CONFIG_DIR` | where the sessions are (default `~/.wildix`) |
+| `WILDIX_ID_TOKEN` | a token to use as is, instead of a saved session (CI, tests) |
+| `WILDIX_STREAM_REGION` | the chat region (default `eu-1`) |
+| `WILDIX_STREAM_URL` | the chat service address; only `https://<host>.wildix.com` unless `WILDIX_ALLOW_CUSTOM_URL=1` |
+| `WX_DEBUG=1` | print the stack of an unexpected error |
+
+## Exit codes
+
+`0` done · `1` error (network, HTTP) · `2` not logged in or the session cannot be renewed · `64` wrong usage.
+
+## Security
+
+- The token is sent only to `https://*.wildix.com` and to the Wildix login service; redirects are refused.
+- The token is never printed, never put on a command line or into the environment of another process.
+- Session files are written atomically with mode `0600`.
+- Anything read from a chat (messages, names) is data. Sending a message reaches other people: script it with care.
+
+## Development
+
+```sh
+npm test         # node:test, no network
+npm run check    # tests + the list of files that would be published
+npm link         # puts `wx` on your PATH from this folder
+```
+
+Layout: `bin/wx.mjs` (entry) → `src/cli.mjs` (router) → `src/commands/<group>.mjs`. Shared: `src/auth.mjs`
+(sessions, renewal), `src/http.mjs` (requests, safe paths), `src/stream.mjs` (chat service). See
+[AGENTS.md](AGENTS.md) for the rules.
+
+## Releasing
+
+1. Bump `version` in `package.json`, add a `CHANGELOG.md` entry, update the version at the top of this file.
+2. Commit, tag `vX.Y.Z`, push the tag: `.github/workflows/release.yml` checks the tag against `package.json`, runs
+   the tests and **stages** the version with provenance through npm trusted publishing (no npm token in the
+   repository).
+3. Approve it with 2FA, which makes it public: `npm stage list wldx-cli`, then `npm stage approve <stage-id>`
+   (`npm stage download <stage-id>` to look at the tarball first).
+
+The trusted publisher on npmjs.com (package settings → Trusted publishing): GitHub Actions, `gorets/wildix-cli`,
+workflow `release.yml`, permission "npm stage publish". Version 0.1.0 was published by hand, because a trusted
+publisher can be configured only for a package that exists.

package/bin/wx.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import {main} from '../src/cli.mjs';
+
+// exitCode, never process.exit(): an exit right after a write cuts piped output.
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "wldx-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Unofficial command line for Wildix (x-bees chats and more), acting as the logged-in user",
+  "keywords": [
+    "wildix",
+    "x-bees",
+    "cli",
+    "chat"
+  ],
+  "license": "MIT",
+  "author": "Vladimir Gorobets",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gorets/wildix-cli.git"
+  },
+  "homepage": "https://github.com/gorets/wildix-cli#readme",
+  "bugs": "https://github.com/gorets/wildix-cli/issues",
+  "type": "module",
+  "bin": {
+    "wx": "bin/wx.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "npm test && npm pack --dry-run"
+  }
+}

package/src/auth.mjs

@@ -0,0 +1,128 @@
+// The Wildix login of the user, shared with the wildix-auth agent skill: one file per account in
+// $WILDIX_CONFIG_DIR/tokens (default ~/.wildix/tokens), named <e-mail with @ as _at_>.prod.json, holding the Cognito
+// set {IdToken, AccessToken, RefreshToken, ExpiresIn, email, savedAt}. An expired IdToken is renewed with the
+// RefreshToken and written back in the same format, so the skill and the CLI keep using one session.
+//
+// The token is never printed and never put on a command line or into the environment of a child process.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {AuthError} from './errors.mjs';
+import {USER_AGENT} from './version.mjs';
+
+export const CLIENT_ID = '2un9vsk5ghu0ocurajqe4a6l1e';
+export const COGNITO_URL = 'https://cognito-idp.eu-central-1.amazonaws.com/';
+const RENEW_EARLY_MS = 60_000;
+export const LOGIN_HINT = 'Log in with the wildix-auth agent skill (npx skills add gorets/wildix-skills -s wildix-auth); `wx login` is not there yet.';
+
+export const configDir = (env = process.env) => env.WILDIX_CONFIG_DIR || path.join(os.homedir(), '.wildix');
+export const tokensDir = (env = process.env) => path.join(configDir(env), 'tokens');
+
+// The e-mail becomes part of a file name: letters, digits and . _ % + - @ only, no "..".
+export function tokenFile(email, env = process.env) {
+  if (!/^[A-Za-z0-9._%+@-]+$/.test(email) || email.includes('..')) throw new AuthError(`Not a valid e-mail: ${email}`);
+  return path.join(tokensDir(env), `${email.replace(/@/g, '_at_')}.prod.json`);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+export function jwtClaims(token) {
+  try {
+    return JSON.parse(Buffer.from(String(token).split('.')[1], 'base64url').toString('utf8'));
+  } catch {
+    return {};
+  }
+}
+
+// When the IdToken of a saved set stops being valid, in ms: its `exp` claim, else savedAt + ExpiresIn, else 0.
+export function expiresAt(set) {
+  const exp = jwtClaims(set?.IdToken).exp;
+  if (Number.isFinite(exp)) return exp * 1000;
+  const saved = Date.parse(set?.savedAt ?? '');
+  return Number.isFinite(saved) && Number.isFinite(set?.ExpiresIn) ? saved + set.ExpiresIn * 1000 : 0;
+}
+
+// The saved sessions: [{email, expiresAt}], never the tokens.
+export function sessions(env = process.env) {
+  const dir = tokensDir(env);
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((n) => n.endsWith('.prod.json')).sort();
+  } catch {
+    return [];
+  }
+  return names
+    .map((n) => readJson(path.join(dir, n)))
+    .filter((set) => typeof set?.email === 'string')
+    .map((set) => ({email: set.email, expiresAt: expiresAt(set)}));
+}
+
+// Which account: --account, else WILDIX_EMAIL, else the only saved session.
+export function pickAccount(env = process.env, account) {
+  const email = account || env.WILDIX_EMAIL;
+  if (email) return email;
+  const list = sessions(env);
+  if (!list.length) throw new AuthError(`Not logged in to Wildix. ${LOGIN_HINT}`);
+  if (list.length > 1) {
+    throw new AuthError(`Several Wildix accounts are logged in. Pick one with --account or WILDIX_EMAIL:\n${list.map((s) => `  ${s.email}`).join('\n')}`);
+  }
+  return list[0].email;
+}
+
+// The format of the skill: whole seconds, no milliseconds (its bash parses it with `date -f %Y-%m-%dT%H:%M:%SZ`).
+export const stamp = (ms) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+// Writes a token set privately (0600) and atomically; a set without IdToken, RefreshToken and ExpiresIn is refused.
+export function saveTokens(file, set) {
+  if (typeof set?.IdToken !== 'string' || typeof set?.RefreshToken !== 'string' || typeof set?.ExpiresIn !== 'number') {
+    throw new AuthError('The answer carried no complete set of tokens: nothing was saved.');
+  }
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, {recursive: true, mode: 0o700});
+  const tmp = path.join(dir, `.${path.basename(file)}.${crypto.randomBytes(6).toString('hex')}`);
+  fs.writeFileSync(tmp, `${JSON.stringify(set, null, 2)}\n`, {mode: 0o600, flag: 'wx'});
+  fs.renameSync(tmp, file);
+}
+
+async function renew(email, set, {env, fetchImpl, now}) {
+  const res = await fetchImpl(COGNITO_URL, {
+    method: 'POST',
+    headers: {
+      'user-agent': USER_AGENT,
+      'content-type': 'application/x-amz-json-1.1',
+      'cache-control': 'no-store',
+      'x-amz-target': 'AWSCognitoIdentityProviderService.InitiateAuth',
+    },
+    body: JSON.stringify({AuthFlow: 'REFRESH_TOKEN_AUTH', ClientId: CLIENT_ID, AuthParameters: {REFRESH_TOKEN: set.RefreshToken}, ClientMetadata: {}}),
+    redirect: 'error',
+    signal: AbortSignal.timeout(30_000),
+  });
+  const body = await res.json().catch(() => ({}));
+  const result = body?.AuthenticationResult;
+  if (!res.ok || body?.__type || typeof result?.IdToken !== 'string') {
+    throw new AuthError(`The session of ${email} could not be renewed (${body?.message || body?.__type || `HTTP ${res.status}`}). ${LOGIN_HINT}`);
+  }
+  // Cognito does not send a new RefreshToken on a refresh: the saved one is kept.
+  const next = {...result, email, savedAt: stamp(now), RefreshToken: set.RefreshToken, ExpiresIn: result.ExpiresIn ?? set.ExpiresIn};
+  saveTokens(tokenFile(email, env), next);
+  return next;
+}
+
+// A valid IdToken of the account: WILDIX_ID_TOKEN as given (tests, CI), else the saved session, renewed when it
+// expires within a minute.
+export async function getToken({account, env = process.env, fetchImpl = globalThis.fetch, now = Date.now()} = {}) {
+  if (env.WILDIX_ID_TOKEN) return env.WILDIX_ID_TOKEN;
+  const email = pickAccount(env, account);
+  const set = readJson(tokenFile(email, env));
+  if (typeof set?.IdToken !== 'string') throw new AuthError(`No saved session for ${email}. ${LOGIN_HINT}`);
+  if (expiresAt(set) - RENEW_EARLY_MS > now) return set.IdToken;
+  if (typeof set.RefreshToken !== 'string') throw new AuthError(`The session of ${email} has expired. ${LOGIN_HINT}`);
+  return (await renew(email, set, {env, fetchImpl, now})).IdToken;
+}

package/src/cli.mjs

@@ -0,0 +1,136 @@
+// wx <group> <command> [options]: the router. Groups are listed in src/commands/index.mjs; a group is
+// {summary, auth?, commands: {name: {summary, usage, options, args: [min, max], run(ctx)}}}; `auth: true` loads a
+// valid token before the command runs. What run() returns is printed as JSON on stdout.
+import {parseArgs} from 'node:util';
+import path from 'node:path';
+import {getToken} from './auth.mjs';
+import {COMMON_OPTIONS, GROUPS, commandOf, groupOf} from './commands/index.mjs';
+import {SHELLS, TOP_LEVEL, complete, completionScript, completionUsage} from './completion.mjs';
+import {AuthError, UsageError} from './errors.mjs';
+import {VERSION} from './version.mjs';
+
+const pad = (s, n) => s + ' '.repeat(Math.max(1, n - s.length));
+
+function mainUsage() {
+  return [
+    'Usage: wx <command> [options]',
+    '',
+    'Commands:',
+    ...Object.entries(GROUPS).map(([name, g]) => `  ${pad(name, 12)}${g.summary}`),
+    ...Object.entries(TOP_LEVEL).map(([name, summary]) => `  ${pad(name, 12)}${summary}`),
+    '',
+    'Options:',
+    '  --account EMAIL   the logged-in Wildix account to use (or WILDIX_EMAIL)',
+    '  -h, --help        help of wx, a command or a subcommand',
+    '  -v, --version     the version of wx',
+    '',
+    'Without installing: npx wldx-cli <command>',
+  ].join('\n');
+}
+
+function groupUsage(name, g) {
+  return [`Usage: wx ${name} <command> [options]`, '', ...Object.values(g.commands).flatMap((cmd) => [`  ${cmd.usage}`, `      ${cmd.summary}`])].join('\n');
+}
+
+function commandUsage(cmd) {
+  const options = Object.entries({...cmd.options, ...COMMON_OPTIONS}).map(([name, o]) => {
+    const flag = `${o.short ? `-${o.short}, ` : ''}--${name}${o.type === 'string' ? ` ${o.choices ? o.choices.join('|') : 'VALUE'}` : ''}`;
+    return `  ${pad(flag, 34)}${o.description ?? ''}`;
+  });
+  return [`Usage: ${cmd.usage}`, '', cmd.summary, '', 'Options:', ...options].join('\n');
+}
+
+function line(stream, text) {
+  stream.write(text.endsWith('\n') ? text : `${text}\n`);
+}
+
+function print(stream, data) {
+  line(stream, JSON.stringify(data, null, stream.isTTY ? 2 : 0));
+}
+
+function completion(args, io) {
+  if (args.includes('-h') || args.includes('--help')) return line(io.stdout, completionUsage());
+  if (args.length > 1) throw new UsageError('wx completion takes one shell', completionUsage());
+  const shell = args[0] ?? path.basename(io.env.SHELL ?? '');
+  const script = completionScript(shell);
+  if (!script) throw new UsageError(`No completion for the shell "${shell}": give one of ${SHELLS.join(', ')}`, completionUsage());
+  line(io.stdout, script);
+}
+
+async function dispatch(argv, io) {
+  const [first, sub, ...rest] = argv;
+  if (!first || first === '-h' || first === '--help' || first === 'help') return line(io.stdout, mainUsage());
+  if (first === '-v' || first === '--version') return line(io.stdout, VERSION);
+  if (first === '__complete') {
+    const words = argv.slice(sub === '--' ? 2 : 1);
+    const out = complete(words, io.env);
+    if (out.length) line(io.stdout, out.join('\n'));
+    return;
+  }
+  if (first === 'completion') return completion(argv.slice(1), io);
+
+  const group = groupOf(first);
+  if (!group) throw new UsageError(`Unknown command: ${first}`, mainUsage());
+  if (sub === '-h' || sub === '--help') return line(io.stdout, groupUsage(first, group));
+  if (!sub) throw new UsageError(`wx ${first} needs a command`, groupUsage(first, group));
+  const cmd = commandOf(group, sub);
+  if (!cmd) throw new UsageError(`Unknown command: wx ${first} ${sub}`, groupUsage(first, group));
+
+  const options = {...COMMON_OPTIONS, ...cmd.options};
+  let parsed;
+  try {
+    parsed = parseArgs({args: rest, options, allowPositionals: true, strict: true});
+  } catch (e) {
+    if (String(e.code).startsWith('ERR_PARSE_ARGS')) throw new UsageError(e.message, commandUsage(cmd));
+    throw e;
+  }
+  const {values, positionals} = parsed;
+  if (values.help) return line(io.stdout, commandUsage(cmd));
+  for (const [name, o] of Object.entries(options)) {
+    if (o.choices && values[name] !== undefined && !o.choices.includes(values[name])) {
+      throw new UsageError(`--${name} must be one of ${o.choices.join(', ')}: ${values[name]}`, commandUsage(cmd));
+    }
+  }
+  const [min, max] = cmd.args;
+  if (positionals.length < min || positionals.length > max) {
+    throw new UsageError(positionals.length < min ? 'Missing arguments' : `Unexpected argument: ${positionals[max]}`, commandUsage(cmd));
+  }
+
+  const token = group.auth ? await getToken({account: values.account, env: io.env, fetchImpl: io.fetch, now: io.now()}) : undefined;
+  const ctx = {
+    values,
+    positionals,
+    env: io.env,
+    stdin: io.stdin,
+    now: io.now(),
+    client: (factory) => factory({token, env: io.env, fetchImpl: io.fetch}),
+  };
+  const result = await cmd.run(ctx);
+  if (result !== undefined) print(io.stdout, result);
+}
+
+// Runs wx with the arguments and returns the exit code: 0 done, 1 error, 2 not logged in, 64 wrong usage.
+export async function main(argv, io = {}) {
+  io = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdin: process.stdin,
+    env: process.env,
+    fetch: globalThis.fetch,
+    now: Date.now,
+    ...io,
+  };
+  try {
+    await dispatch(argv, io);
+    return 0;
+  } catch (e) {
+    line(io.stderr, `wx: ${e.message}`);
+    if (e instanceof UsageError) {
+      if (e.usage) line(io.stderr, `\n${e.usage}`);
+      return 64;
+    }
+    if (e instanceof AuthError) return 2;
+    if (io.env.WX_DEBUG === '1' && e.stack) line(io.stderr, e.stack);
+    return 1;
+  }
+}

package/src/commands/auth.mjs

@@ -0,0 +1,32 @@
+// wx auth: the saved Wildix sessions (shared with the wildix-auth agent skill). Never prints a token.
+import {AuthError} from '../errors.mjs';
+import {pickAccount, sessions} from '../auth.mjs';
+
+export default {
+  summary: 'the Wildix accounts you are logged in with',
+  commands: {
+    status: {
+      summary: 'saved sessions, which one is used and until when its token is valid (no network)',
+      usage: 'wx auth status',
+      options: {},
+      args: [0, 0],
+      async run({values, env, now}) {
+        let account = null;
+        try {
+          account = pickAccount(env, values.account);
+        } catch (e) {
+          if (!(e instanceof AuthError)) throw e;
+        }
+        return {
+          account,
+          tokenFromEnvironment: Boolean(env.WILDIX_ID_TOKEN),
+          sessions: sessions(env).map((s) => ({
+            email: s.email,
+            tokenValidUntil: s.expiresAt ? new Date(s.expiresAt).toISOString() : null,
+            expired: s.expiresAt <= now,
+          })),
+        };
+      },
+    },
+  },
+};

package/src/commands/chat.mjs

@@ -0,0 +1,72 @@
+// wx chat: channels and messages of the Wildix stream service, as the logged-in user.
+import {UsageError} from '../errors.mjs';
+import {apiPath, query} from '../http.mjs';
+import {channelId, messageId, streamClient} from '../stream.mjs';
+
+const SEQ_MAX = 999_999_999_999;
+
+function seq(name, value) {
+  if (value === undefined) return undefined;
+  if (!/^\d{1,12}$/.test(value) || Number(value) > SEQ_MAX) throw new UsageError(`--${name} must be a whole number from 0 to ${SEQ_MAX}: ${value}`);
+  return Number(value);
+}
+
+async function readText(arg, stdin) {
+  if (arg !== '-') return arg;
+  const chunks = [];
+  for await (const c of stdin) chunks.push(c);
+  return Buffer.concat(chunks.map((c) => Buffer.from(c))).toString('utf8');
+}
+
+export default {
+  summary: 'chats: list channels, read and send messages',
+  auth: true,
+  commands: {
+    list: {
+      summary: 'your channels, newest activity first',
+      usage: 'wx chat list [--filter unread|archived] [--section ID] [--cursor C]',
+      options: {
+        filter: {type: 'string', description: 'only unread or archived channels', choices: ['unread', 'archived']},
+        section: {type: 'string', description: 'only the channels of a section'},
+        cursor: {type: 'string', description: 'the next page (nextCursor of the previous one)'},
+      },
+      args: [0, 0],
+      async run({values, client}) {
+        return client(streamClient).call('GET', `/channels${query({filter: values.filter, section: values.section, cursor: values.cursor})}`);
+      },
+    },
+    read: {
+      summary: 'messages of a channel, newest first, 30 per page',
+      usage: 'wx chat read <channel> [--unread] [--from SEQ] [--to SEQ]',
+      options: {
+        unread: {type: 'boolean', description: 'start at the first unread message'},
+        from: {type: 'string', description: 'from this sequence number'},
+        to: {type: 'string', description: 'up to this sequence number'},
+      },
+      args: [1, 1],
+      async run({values, positionals, client}) {
+        const ch = channelId(positionals[0]);
+        const q = query({from: seq('from', values.from), to: seq('to', values.to), anchor: values.unread && 'firstUnread'});
+        return client(streamClient).call('GET', apiPath`/channels/${ch}/messages` + q);
+      },
+    },
+    send: {
+      summary: 'send a message to a channel ("-" reads the text from stdin)',
+      usage: 'wx chat send <channel> <text|-> [--markdown] [--reply-to MESSAGE]',
+      options: {
+        markdown: {type: 'boolean', description: 'the text is markdown'},
+        'reply-to': {type: 'string', description: 'quote this message (id or inbox link)'},
+      },
+      args: [2, 2],
+      async run({values, positionals, client, stdin}) {
+        const ch = channelId(positionals[0]);
+        const text = await readText(positionals[1], stdin);
+        if (!text.trim()) throw new UsageError('Nothing to send: the text is empty');
+        const body = {text};
+        if (values.markdown) body.markdown = true;
+        if (values['reply-to']) body.quote = {channelId: ch, messageId: messageId(values['reply-to'])};
+        return client(streamClient).call('POST', apiPath`/channels/${ch}/messages`, body);
+      },
+    },
+  },
+};

package/src/commands/index.mjs

@@ -0,0 +1,15 @@
+// The command groups of wx and the options every command takes. An option is a node:util parseArgs option plus
+// `description` (help and completion), `choices` (the router refuses other values, completion offers them) and
+// `complete: 'accounts'` (completion offers the logged-in accounts).
+import auth from './auth.mjs';
+import chat from './chat.mjs';
+
+export const GROUPS = {chat, auth};
+
+export const COMMON_OPTIONS = {
+  account: {type: 'string', description: 'the logged-in Wildix account to use', complete: 'accounts'},
+  help: {type: 'boolean', short: 'h', description: 'help of the command'},
+};
+
+export const groupOf = (name) => (Object.hasOwn(GROUPS, name) ? GROUPS[name] : undefined);
+export const commandOf = (group, name) => (group && Object.hasOwn(group.commands, name) ? group.commands[name] : undefined);

package/src/completion.mjs

@@ -0,0 +1,105 @@
+// Shell completion. `wx completion <shell>` prints a small script; on every Tab it runs
+// `wx __complete -- <words after wx, the last one being the word under the cursor>`, which prints the candidates,
+// one per line as "value<TAB>description". The candidates come from the command definitions (and the saved
+// accounts for --account), so completion follows the commands without a regenerated script. No network.
+import {sessions} from './auth.mjs';
+import {COMMON_OPTIONS, GROUPS, commandOf, groupOf} from './commands/index.mjs';
+
+export const SHELLS = ['bash', 'zsh', 'fish'];
+
+export const TOP_LEVEL = {
+  completion: 'print the shell completion script (bash, zsh, fish)',
+};
+
+const TOP_OPTIONS = {'--help': 'help of wx', '--version': 'the version of wx'};
+
+function valuesOf(option, env) {
+  if (option.choices) return option.choices.map((v) => [v]);
+  if (option.complete === 'accounts') return sessions(env).map((s) => [s.email]);
+  return [];
+}
+
+// The candidates for the word under the cursor: ["value\tdescription", ...].
+export function complete(words, env = process.env) {
+  const cur = words.length ? words[words.length - 1] : '';
+  const done = words.slice(0, -1);
+  const offer = (pairs) => pairs.filter(([v]) => v.startsWith(cur)).map(([v, d]) => (d ? `${v}\t${d}` : v));
+
+  if (done.length === 0) {
+    return offer([
+      ...Object.entries(GROUPS).map(([name, g]) => [name, g.summary]),
+      ...Object.entries(TOP_LEVEL),
+      ...(cur.startsWith('-') ? Object.entries(TOP_OPTIONS) : []),
+    ]);
+  }
+  if (done[0] === 'completion') return done.length === 1 ? offer(SHELLS.map((s) => [s, `the script for ${s}`])) : [];
+
+  const group = groupOf(done[0]);
+  if (!group) return [];
+  if (done.length === 1) return offer(Object.entries(group.commands).map(([name, cmd]) => [name, cmd.summary]));
+
+  const cmd = commandOf(group, done[1]);
+  if (!cmd) return [];
+  const options = {...cmd.options, ...COMMON_OPTIONS};
+  const prev = done[done.length - 1];
+  if (done.length > 2 && prev.startsWith('--')) {
+    const option = Object.hasOwn(options, prev.slice(2)) ? options[prev.slice(2)] : undefined;
+    if (option?.type === 'string') return offer(valuesOf(option, env));
+  }
+  if (cur.startsWith('-')) {
+    const used = new Set(done.slice(2).filter((w) => w.startsWith('--')).map((w) => w.slice(2)));
+    return offer(Object.entries(options).filter(([name, o]) => o.multiple || !used.has(name)).map(([name, o]) => [`--${name}`, o.description]));
+  }
+  return [];
+}
+
+const SCRIPTS = {
+  bash: `# wx completion for bash. Add to ~/.bashrc:  eval "$(wx completion bash)"
+_wx_complete() {
+  # The words are taken before IFS changes: bash 3.2 (macOS) joins the elements of a quoted array slice when IFS
+  # is a newline.
+  local words=("\${COMP_WORDS[@]:1:COMP_CWORD}") out line
+  COMPREPLY=()
+  out=$(wx __complete -- "\${words[@]}" 2>/dev/null) || return 0
+  local IFS=$'\\n'
+  for line in $out; do
+    COMPREPLY+=("\${line%%$'\\t'*}")
+  done
+}
+complete -F _wx_complete wx
+`,
+  zsh: `# wx completion for zsh. Add to ~/.zshrc (after compinit):  eval "$(wx completion zsh)"
+_wx() {
+  local -a lines items
+  local line
+  lines=("\${(@f)$(wx __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)}")
+  for line in $lines; do
+    [[ -n $line ]] || continue
+    if [[ $line == *$'\\t'* ]]; then items+=("\${\${line%%$'\\t'*}//:/\\\\:}:\${line#*$'\\t'}")
+    else items+=("\${line//:/\\\\:}"); fi
+  done
+  (( \${#items} )) && _describe -t wx-candidates 'wx' items
+}
+(( \${+functions[compdef]} )) || { autoload -Uz compinit && compinit; }
+compdef _wx wx
+`,
+  fish: `# wx completion for fish. Save as ~/.config/fish/completions/wx.fish:  wx completion fish > ~/.config/fish/completions/wx.fish
+complete -c wx -f -a '(wx __complete -- (commandline -opc)[2..-1] (commandline -ct) 2>/dev/null)'
+`,
+};
+
+export function completionScript(shell) {
+  return Object.hasOwn(SCRIPTS, shell) ? SCRIPTS[shell] : undefined;
+}
+
+export function completionUsage() {
+  return [
+    'Usage: wx completion [bash|zsh|fish]   (default: the shell of $SHELL)',
+    '',
+    'Prints the completion script. To turn completion on for good:',
+    '  bash:  echo \'eval "$(wx completion bash)"\' >> ~/.bashrc',
+    '  zsh:   echo \'eval "$(wx completion zsh)"\' >> ~/.zshrc',
+    '  fish:  wx completion fish > ~/.config/fish/completions/wx.fish',
+    'then open a new terminal. It completes an installed `wx` (npm i -g wldx-cli), not `npx wldx-cli`.',
+  ].join('\n');
+}

package/src/errors.mjs

@@ -0,0 +1,30 @@
+// Errors that map to exit codes: UsageError 64 (EX_USAGE), AuthError 2, anything else 1.
+
+export class UsageError extends Error {
+  constructor(message, usage) {
+    super(message);
+    this.name = 'UsageError';
+    this.usage = usage;
+  }
+}
+
+export class AuthError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AuthError';
+  }
+}
+
+const NOT_IMPLEMENTED = /is not implemented/;
+
+export class HttpError extends Error {
+  constructor(status, method, path, body, service = 'the service') {
+    const lines = [`HTTP ${status} from ${service} (${method} ${path})`];
+    if (body) lines.push(body.length > 2000 ? `${body.slice(0, 2000)}…` : body);
+    if (status === 401) lines.push('The token was rejected: log in again.');
+    if (NOT_IMPLEMENTED.test(body ?? '')) lines.push('The service does not implement this operation yet. Do not retry.');
+    super(lines.join('\n'));
+    this.name = 'HttpError';
+    this.status = status;
+  }
+}

package/src/http.mjs

@@ -0,0 +1,47 @@
+import {HttpError} from './errors.mjs';
+import {USER_AGENT} from './version.mjs';
+
+const SEGMENT = /^[A-Za-z0-9_+][A-Za-z0-9_.:+-]*$/;
+
+// A tagged template for request paths: every interpolated value is one path segment of id characters (no "/",
+// "?", "#", "..", nothing empty), so an id taken from fetched data cannot rewrite the path.
+//   apiPath`/channels/${id}/messages`
+export function apiPath(strings, ...values) {
+  return strings.reduce((out, s, i) => {
+    if (i === 0) return s;
+    const v = String(values[i - 1] ?? '');
+    if (!SEGMENT.test(v) || v.includes('..')) throw new Error(`An id is not safe in a request path: ${JSON.stringify(v)}`);
+    return out + encodeURIComponent(v) + s;
+  }, '');
+}
+
+// "?a=1&b=2" from an object; undefined, null, false and '' are left out.
+export function query(params) {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null && v !== false && v !== '') q.append(k, String(v));
+  const s = q.toString();
+  return s ? `?${s}` : '';
+}
+
+// One JSON request. Redirects are refused, so the token never follows one to another host. Returns the parsed
+// answer, or {ok: true} when it is empty; throws HttpError on a status other than 2xx.
+export async function request(url, {method = 'GET', token, body, service, fetchImpl = globalThis.fetch, timeoutMs = 60_000} = {}) {
+  const headers = {'user-agent': USER_AGENT, accept: 'application/json'};
+  if (token) headers.authorization = `Bearer ${token}`;
+  if (body !== undefined) headers['content-type'] = 'application/json';
+  const res = await fetchImpl(url, {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+    redirect: 'error',
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const text = await res.text();
+  if (!res.ok) throw new HttpError(res.status, method, new URL(url).pathname, text, service);
+  if (!text) return {ok: true};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {text};
+  }
+}

package/src/stream.mjs

@@ -0,0 +1,43 @@
+// The Wildix stream service (chats): https://<region>.stream.wildix.com/api/v1, region eu-1 by default.
+import {UsageError} from './errors.mjs';
+import {request} from './http.mjs';
+
+const WILDIX_HOST = /^https:\/\/[a-z0-9-]+(\.[a-z0-9-]+)*\.wildix\.com(:[0-9]+)?$/;
+const ID = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+
+// The base address. The token is only ever sent to https://<host>.wildix.com; WILDIX_ALLOW_CUSTOM_URL=1 lifts this
+// for tests against a local server.
+export function streamBase(env = process.env) {
+  const base = (env.WILDIX_STREAM_URL || `https://${env.WILDIX_STREAM_REGION || 'eu-1'}.stream.wildix.com`).replace(/\/+$/, '');
+  if (env.WILDIX_ALLOW_CUSTOM_URL !== '1' && !WILDIX_HOST.test(base)) {
+    throw new UsageError(`The stream service address must be https://<host>.wildix.com, got: ${base}`);
+  }
+  return base;
+}
+
+const valid = (v) => ID.test(v) && !v.includes('..');
+
+// A channel id from an id, a "type:id" form or an inbox link (the message part of a link is dropped).
+export function channelId(input) {
+  let v = String(input).replace(/[?#].*$/s, '');
+  const at = v.indexOf('/inbox/');
+  if (at >= 0) v = v.slice(at + '/inbox/'.length);
+  v = v.split('/')[0];
+  v = v.slice(v.lastIndexOf(':') + 1);
+  if (!valid(v)) throw new UsageError(`Not a channel id: ${input}`);
+  return v;
+}
+
+// A message id from an id or from an inbox link to the message (the last path segment).
+export function messageId(input) {
+  const v = String(input).replace(/[?#].*$/s, '').replace(/\/+$/, '').split('/').pop();
+  if (!valid(v)) throw new UsageError(`Not a message id: ${input}`);
+  return v;
+}
+
+export function streamClient({token, env = process.env, fetchImpl}) {
+  const api = `${streamBase(env)}/api/v1`;
+  return {
+    call: (method, path, body) => request(api + path, {method, token, body, fetchImpl, service: 'the stream service'}),
+  };
+}

package/src/version.mjs

@@ -0,0 +1,4 @@
+import {readFileSync} from 'node:fs';
+
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+export const USER_AGENT = `wldx-cli/${VERSION}`;