miaw-core 1.9.0 → 1.10.0

package/.env.example

@@ -0,0 +1,59 @@
+# miaw-core / miaw-cli runtime configuration
+#
+# Copy to .env and edit. Every value here is optional — each has a default and
+# each can also be supplied as a CLI flag. Flags win over environment variables.
+#
+#   cp .env.example .env
+#
+# .env is gitignored. Prefer this file over CLI flags for anything containing a
+# password: flags land in your shell history and in the process list, where any
+# other user on the machine can read them.
+
+# ─── Instance ────────────────────────────────────────────────────────────────
+
+# Instance ID. Sessions are isolated per instance. (flag: --instance-id)
+MIAW_INSTANCE_ID=default
+
+# Where session credentials are stored, as {MIAW_SESSION_PATH}/{MIAW_INSTANCE_ID}/
+# (flag: --session-path)
+MIAW_SESSION_PATH=./sessions-cli
+
+# ─── Proxy (all optional; added in v1.10.0) ──────────────────────────────────
+
+# A single proxy for this instance. (flag: --proxy)
+# Schemes: http, https, socks4, socks4a, socks5, socks5h
+#
+# Prefer the h/a variants (socks5h, socks4a): plain socks5/socks4 resolve DNS
+# locally, so the destination hostname leaks to your resolver even though the
+# connection itself is tunnelled.
+#
+# Passwords containing @ : / ? # or % must be percent-encoded here
+# ("p@ss#1" becomes "p%40ss%231"), or use the ProxyConfig object form in code.
+#
+# MIAW_PROXY=socks5h://user:password@proxy.example.com:1080
+
+# A proxy list file instead of a single proxy — TXT (one per line) or JSON
+# array. One proxy is selected per process using MIAW_PROXY_STRATEGY.
+# Ignored when MIAW_PROXY is also set. (flag: --proxy-file)
+#
+# See examples/proxies.example.txt for the format.
+#
+# MIAW_PROXY_FILE=./proxies.txt
+
+# How a proxy is picked from MIAW_PROXY_FILE. (flag: --proxy-strategy)
+#   deterministic  same instanceId always maps to the same proxy   [default]
+#   round-robin    next in the list, wrapping
+#   random         uniform random
+#   weighted       random, biased by each entry's weight=
+#
+# Leave this as deterministic for anything with a persisted WhatsApp session.
+# WhatsApp treats a session's source IP as a trust signal, so a session whose
+# egress IP jumps between runs looks like an account takeover. Rotation is for
+# spreading instances across proxies, never for rotating a live session's IP.
+#
+# MIAW_PROXY_STRATEGY=deterministic
+
+# ─── Logging ─────────────────────────────────────────────────────────────────
+
+# Verbose Baileys logging. (flag: --debug)
+# DEBUG=false

package/CHANGELOG.md

@@ -5,6 +5,113 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.10.0] - 2026-07-29
+
+**Proxy files, rotation, and CLI diagnostics** - builds on the v1.3.0 proxy core.
+All additive; no breaking changes.
+
+### Added
+
+- **`socks5h://` and `socks4a://` support.** These resolve DNS *at the proxy*;
+  plain `socks5://` / `socks4://` resolve locally, so the destination hostname still
+  leaks to your DNS resolver even though the connection is tunnelled. Both variants
+  were previously rejected as unsupported protocols despite the underlying agent
+  supporting them.
+- **Proxy list files** - `loadProxyList()` / `loadProxyListSync()` / `parseProxyList()`
+  read TXT (one per line, `#`/`;` comments, optional `weight=` and `label=` tokens,
+  scheme-less `host:port[:user:pass]` vendor forms) or JSON (array of strings and/or
+  objects, or a `{ "proxies": [...] }` wrapper). Format is auto-detected by extension
+  then by content. `validateProxyList()` partitions a list; `watchProxyList()` hot-reloads
+  a file.
+- **`ProxyRotator`** - `round-robin`, `random`, `weighted`, and `deterministic`
+  strategies, plus `ProxyRotator.fromFile()`, `setProxies()`, `getStats()`, and `close()`.
+  It returns a `ProxyPoolEntry` you pass to `new MiawClient({ proxy })`, so `getProxyInfo()`
+  and proxy validation keep working for rotated instances.
+- **`maskProxyUrl()`** - exported credential masking; `getProxyInfo()` now uses it.
+- **CLI**: `proxy list` (alias `ls`), `proxy test <url>`, `proxy test-all`. These need
+  **no WhatsApp connection** - they probe the proxy through the same agent Baileys uses,
+  so you can validate a proxy before spending a pairing attempt on it. `proxy test-all`
+  exits non-zero if any proxy fails, so it can gate a deploy.
+- **CLI global flags**: `--proxy-file <path>`, `--proxy-strategy <strategy>`
+  (default `deterministic`; `instance` accepted as an alias). Env fallbacks:
+  `MIAW_PROXY`, `MIAW_PROXY_FILE`, `MIAW_PROXY_STRATEGY`.
+- **[.env.example](./.env.example)** - documents every `MIAW_*` runtime variable,
+  including `MIAW_INSTANCE_ID` and `MIAW_SESSION_PATH`, which the CLI has always
+  read but which were never written down anywhere.
+- **[docs/DEPLOYMENT_PROXY.md](./docs/DEPLOYMENT_PROXY.md)** - operational notes for
+  deploying with proxies: why `instanceId` must be stable across rollouts, treating
+  proxy files as secrets, ConfigMap-safe hot reload, egress firewall rules, and the
+  sticky-session requirement.
+- **[docs/PROXY.md](./docs/PROXY.md)** - dedicated proxy guide covering configuration,
+  proxy files, rotation, CLI diagnostics, troubleshooting, security, and provider
+  selection. Replaces the internal `docs/PROXY_SUPPORT_PLAN.md`, which is removed.
+- 97 new tests (42 loader, 33 rotator, 22 CLI). The CLI proxy tests are the first in
+  `tests/integration/cli/` that run without a WhatsApp session.
+
+### Fixed
+
+- **Media uploads through a proxy were broken and always had been** (since v1.3.0).
+  `fetchAgent` was set to an undici `ProxyAgent`, but Baileys declares it as an
+  `https.Agent` and its Node upload path hands it to `https.request({ agent })`, which
+  cannot use a Dispatcher. Every `sendImage`/`sendVideo`/`sendDocument` through a proxy
+  failed with "Media upload failed on all hosts". `fetchAgent` is now the same
+  `http.Agent` as `wsAgent`. **Uploads are consequently proxied on SOCKS too**, which
+  the previous documentation said was impossible.
+- **Media downloads were never proxied.** Baileys downloads with
+  `fetch(url, { dispatcher })` and never wires a proxy into that path, and
+  `downloadMedia()` passed no options — so every download revealed the real IP
+  regardless of proxy settings. It now passes an undici Dispatcher explicitly.
+  This works for HTTP/HTTPS proxies; SOCKS downloads remain direct because undici
+  has no SOCKS transport.
+- `proxy test` reported a **407 Proxy Authentication Required as success**. A 407 comes
+  from the proxy itself and means the tunnel was refused, so nothing ever reached
+  WhatsApp - but the probe counted any HTTP status as reachable. `proxy test-all` would
+  therefore green-light a proxy list with wrong credentials, defeating the pre-flight
+  check it exists to provide. It now fails with `EPROXYAUTH` and a non-zero exit code.
+- Proxy credentials leaked in two places: `MiawClient` interpolated the raw proxy URL,
+  password included, into its "Invalid proxy configuration" error (which lands in logs
+  and stack traces), and the CLI printed the raw `--proxy` URL to the REPL startup
+  banner. Both are masked now.
+
+### Notes
+
+- `--proxy-strategy` defaults to `deterministic` so a given `instanceId` keeps a stable
+  egress IP across runs. **Rotation is for distributing instances across proxies, never
+  for rotating a live session's IP** - WhatsApp treats a session's source IP as a trust
+  signal, and churning it looks like account takeover.
+- Deterministic selection uses rendezvous hashing rather than `hash % length`, so adding
+  or removing a proxy remaps only the instances that were on it. Under modulo, one edit
+  to your proxy file would change the egress IP of every live session at once.
+- SOCKS proxies still route media over a direct connection: Node's `fetch()` requires an
+  undici dispatcher and undici has no SOCKS transport. `proxy list` and `proxy test`
+  report this per proxy. See [docs/PROXY.md](./docs/PROXY.md).
+
+## [1.9.2] - 2026-07-09
+
+**CommonJS-consumer fix** - Let `require()` resolve the package.
+
+### Fixed
+
+- The `exports` map only declared the `import` condition, so CommonJS /
+  `require()` resolution (e.g. `ts-node` compiling to CJS) failed with
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`. Added a `default` condition pointing at the
+  same ESM build; on Node >=22.12 `require(esm)` now resolves it. The package
+  stays ESM-only — no separate CJS build was added.
+
+## [1.9.1] - 2026-07-07
+
+**Message receipts** - Observe delivery/read/played status of messages you send.
+
+### Added
+
+- New `message_receipt` event (`MessageReceiptUpdate`) surfaced from Baileys'
+  `message-receipt.update`: `{ messageId, chatId, recipientId, type, timestamp, fromMe }`
+  where `type` is `'delivery' | 'read' | 'played'` (derived from the receipt
+  timestamps). This is the observe half of read-receipts — `markAsRead` sends
+  them, `message_receipt` now reports incoming ones.
+- Added `docs/DEFERRED_FEATURES.md` tracking the remaining deferred backlog
+  (group/community admin, privacy & blocklist, calls, leftover message types).
+
 ## [1.9.0] - 2026-07-07
 
 **Communities** - Wrap Baileys' `community*` API (communities are hubs that link
@@ -314,6 +421,49 @@ unchanged.
 
 ---
 
+## [1.3.0] - 2026-03-13
+
+**Proxy support** - route a WhatsApp connection through a proxy, per instance.
+
+_Backfilled: this release shipped in commit `8def495` but was never recorded here._
+
+### Added
+
+- `proxy` option on `MiawClientOptions`, accepting a URL string or a `ProxyConfig`
+  object (`{ url, username?, password? }`). Supports HTTP, HTTPS, SOCKS4, and SOCKS5.
+- `createProxyAgents()` and `validateProxyConfig()` in `src/utils/proxy-agent.ts`.
+  Dual-agent approach: `https-proxy-agent` / `socks-proxy-agent` for the WebSocket
+  transport, `undici`'s `ProxyAgent` for media upload/download.
+- `agent` and `fetchAgent` escape-hatch options for supplying custom transports.
+- `MiawClient.getProxyInfo()` for inspecting the active proxy.
+- `--proxy <url>` CLI flag.
+
+### Notes
+
+- SOCKS proxies tunnel the WebSocket but not media transfers: Node's `fetch()` needs an
+  undici dispatcher and undici has no SOCKS transport, so media falls back to a direct
+  connection.
+
+## [1.2.0] - 2026-01-20
+
+**Code quality release** - configurable timeouts, validation utilities, and type safety.
+
+_Backfilled: this release shipped in commit `2e922d2` but was never recorded here._
+
+### Added
+
+- Configurable timeouts and exported `TIMEOUTS` / `THRESHOLDS` constants.
+- Validation utilities and type-guard helpers (`isError`, `getErrorMessage`,
+  `isBaileysMessage`, `isBaileysMessageUpsert`).
+- Custom logger support.
+- CLI: `send video`, `send audio`, `media download`; topic-specific help sub-commands
+  and expanded autocomplete.
+
+### Changed
+
+- Type-safety improvements throughout; 14 of 15 issues from the code review report
+  resolved. No breaking changes.
+
 ## [1.1.0] - 2026-01-02
 
 **Baileys v7 Migration** - ESM-only release with improved session stability

package/README.md

@@ -28,6 +28,9 @@ For a detailed comparison, see [Baileys vs Miaw Core Comparison](./docs/BAILEYS_
 
 - **[CLI Guide](./docs/CLI.md)** - Command-line interface usage
 - **[Usage Guide](./docs/USAGE.md)** - Complete guide for all current features
+- **[Proxy Guide](./docs/PROXY.md)** - Proxies, proxy list files, and rotation strategies
+- **[Proxy Deployment Notes](./docs/DEPLOYMENT_PROXY.md)** - Operational guidance for deploying with proxies
+- **[LID Resolution](./docs/LID_RESOLUTION.md)** - Working with privacy-masked (`@lid`) JIDs
 - **[Baileys Comparison](./docs/BAILEYS_VS_MIAW_COMPARISON.md)** - Feature comparison with raw Baileys
 - **[Migration Guide](./docs/MIGRATION.md)** - Upgrading between versions
 - **[Test Coverage](./docs/TEST_COVERAGE_ANALYSIS.md)** - API coverage analysis
@@ -41,6 +44,7 @@ For a detailed comparison, see [Baileys vs Miaw Core Comparison](./docs/BAILEYS_
 - **Auto-Reconnection** - Handles connection drops and reconnects automatically
 - **Session Management** - File-based session storage with automatic persistence
 - **Multiple Instances** - Run multiple WhatsApp connections in a single process
+- **Proxy Support** - HTTP/HTTPS/SOCKS proxies, proxy list files, and per-instance rotation
 - **TypeScript Support** - Full type definitions for excellent IDE experience
 - **Event-Driven** - Easy-to-use event system for messages and connection states
 - **Normalized Messages** - Simplified message format, no more complex Baileys structures
@@ -177,7 +181,7 @@ npm run test:watch
 npm run test:coverage
 ```
 
-## Current Capabilities (v1.4.1)
+## Current Capabilities (v1.10.0)
 
 Built on **Baileys v7.0.0-rc13** - the latest WhatsApp Web protocol implementation.
 
@@ -193,6 +197,14 @@ Built on **Baileys v7.0.0-rc13** - the latest WhatsApp Web protocol implementati
 - ✅ TypeScript support
 - ✅ Error handling
 
+### Networking
+
+- ✅ HTTP / HTTPS / SOCKS4 / SOCKS5 proxies, per instance
+- ✅ Proxy list files (TXT / JSON) with validation and hot reload
+- ✅ Rotation strategies (round-robin, random, weighted, deterministic-per-instance)
+- ✅ `miaw-cli proxy test` connectivity diagnostics — no WhatsApp connection needed
+- ⚠️ SOCKS proxies: media *downloads* use a direct connection ([details](./docs/PROXY.md#️-socks-media-downloads-use-a-direct-connection))
+
 ### Advanced Messaging
 
 - ✅ Reply/quote messages

package/bin/miaw-cli.ts

@@ -17,6 +17,11 @@ import { runRepl } from "../src/cli/repl.js";
 import { runCommand } from "../src/cli/commands/index.js";
 import { initializeCLICleanup } from "../src/cli/utils/cleanup.js";
 import { getErrorMessage } from "../src/utils/type-guards.js";
+import { maskProxyUrl } from "../src/utils/proxy-agent.js";
+import {
+  parseProxyStrategy,
+  selectProxyForInstance,
+} from "../src/cli/utils/proxy-config.js";
 
 // Initialize CLI cleanup handlers for graceful shutdown
 initializeCLICleanup();
@@ -28,6 +33,10 @@ dotenv.config({ path: ".env.test" });
 // Default configuration
 const DEFAULT_INSTANCE_ID = process.env.MIAW_INSTANCE_ID || "default";
 const DEFAULT_SESSION_PATH = process.env.MIAW_SESSION_PATH || "./sessions-cli";
+// Proxy credentials belong in .env, not in shell history.
+const DEFAULT_PROXY = process.env.MIAW_PROXY || undefined;
+const DEFAULT_PROXY_FILE = process.env.MIAW_PROXY_FILE || undefined;
+const DEFAULT_PROXY_STRATEGY_ENV = process.env.MIAW_PROXY_STRATEGY || undefined;
 
 /**
  * Parse CLI arguments
@@ -78,7 +87,10 @@ USAGE:
 GLOBAL FLAGS:
   --instance-id <id>                          Instance ID (default: "default")
   --session-path <path>                       Session directory
-  --proxy <url>                               Proxy URL (http, https, socks4, socks5)
+  --proxy <url>                               Proxy URL (http/https/socks4/socks4a/socks5/socks5h)
+  --proxy-file <path>                         Proxy list file (.txt one-per-line, or .json array)
+  --proxy-strategy <strategy>                 Pick from --proxy-file: round-robin | random |
+                                              weighted | deterministic (default: deterministic)
   --json                                      Output as JSON
   --debug                                     Enable verbose logging
 
@@ -93,6 +105,7 @@ COMMANDS:
   profile     Profile management (picture, name, status)
   label       Label management - WhatsApp Business (list, chats, add, chat)
   catalog     Catalog management - WhatsApp Business (list, collections, product)
+  proxy       Inspect and test proxies (list, test, test-all) - no connection needed
 
 COMMON OPTIONS:
   --limit N                                   Limit number of results
@@ -103,6 +116,8 @@ EXAMPLES:
   miaw-cli send text 6281234567890 "Hello"
   miaw-cli group participants add 120363xxx@g.us 628xxx
   miaw-cli contact add 6281234567890 "John Doe"
+  miaw-cli proxy test socks5://proxy.example.com:1080
+  miaw-cli --instance-id bot-3 --proxy-file ./proxies.txt get groups
 
 REPL MODE:
   Run 'miaw-cli' without arguments to start interactive mode.
@@ -132,8 +147,35 @@ async function main() {
   const jsonOutput = flags.json === true;
   const debugMode = flags.debug === true;
 
-  // Extract proxy flag
-  const proxyUrl = flags.proxy as string | undefined;
+  // Extract proxy flags (CLI flag wins over the MIAW_PROXY* env fallbacks)
+  const explicitProxy = (flags.proxy as string | undefined) || DEFAULT_PROXY;
+  const proxyFile = (flags["proxy-file"] as string | undefined) || DEFAULT_PROXY_FILE;
+
+  let proxyStrategy;
+  try {
+    proxyStrategy = parseProxyStrategy(
+      (flags["proxy-strategy"] as string | undefined) || DEFAULT_PROXY_STRATEGY_ENV
+    );
+  } catch (error: unknown) {
+    console.error(`❌ ${getErrorMessage(error)}`);
+    process.exit(1);
+  }
+
+  // Precedence: an explicit --proxy always wins; otherwise a --proxy-file
+  // selects one proxy for this process. The default strategy is
+  // deterministic so a given instanceId keeps a stable egress IP across
+  // invocations - round-robin here would silently rotate a live session's IP.
+  let proxyUrl = explicitProxy;
+  if (explicitProxy && proxyFile) {
+    console.log("⚠️  --proxy overrides --proxy-file");
+  } else if (!explicitProxy && proxyFile) {
+    try {
+      proxyUrl = await selectProxyForInstance(proxyFile, proxyStrategy, instanceId);
+    } catch (error: unknown) {
+      console.error(`❌ Failed to select a proxy from ${proxyFile}: ${getErrorMessage(error)}`);
+      process.exit(1);
+    }
+  }
 
   // Create client configuration
   const clientConfig = {
@@ -141,6 +183,8 @@ async function main() {
     sessionPath,
     debug: debugMode,
     ...(proxyUrl && { proxy: proxyUrl }),
+    ...(proxyFile && { proxyFile }),
+    proxyStrategy,
   };
 
   // No command provided - start REPL
@@ -148,7 +192,7 @@ async function main() {
     console.log(`\n🚀 Starting miaw-cli REPL...`);
     console.log(`📂 Instance: ${instanceId}`);
     console.log(`📂 Session: ${sessionPath}`);
-    if (proxyUrl) console.log(`🌐 Proxy: ${proxyUrl}`);
+    if (proxyUrl) console.log(`🌐 Proxy: ${maskProxyUrl(proxyUrl)}`);
     console.log(`🔧 Debug: ${debugMode ? "ON" : "OFF"}\n`);
 
     try {
@@ -166,6 +210,8 @@ async function main() {
       clientConfig,
       jsonOutput,
       flags,
+      ...(proxyFile && { proxyFile }),
+      proxyStrategy,
     });
 
     if (!success) {

package/dist/cli/commands/commands-index.d.ts

@@ -13,6 +13,7 @@ export { cmdCommunityList, cmdCommunityInfo, cmdCommunityCreate, cmdCommunityLea
 export { cmdMediaDownload } from "./media.js";
 export { cmdGroupList, cmdGroupInfo, cmdGroupParticipants, cmdGroupInviteLink, cmdGroupCreate, cmdGroupLeave, cmdGroupInviteAccept, cmdGroupInviteRevoke, cmdGroupInviteInfo, cmdGroupParticipantsAdd, cmdGroupParticipantsRemove, cmdGroupParticipantsPromote, cmdGroupParticipantsDemote, cmdGroupNameSet, cmdGroupDescriptionSet, cmdGroupPictureSet, } from "./group.js";
 export { cmdCheck, } from "./misc.js";
+export { cmdProxyList, cmdProxyTest, cmdProxyTestAll, } from "./proxy.js";
 export { cmdContactList, cmdContactInfo, cmdContactBusiness, cmdContactPicture, cmdContactAdd, cmdContactRemove, } from "./contact.js";
 export { cmdProfilePictureSet, cmdProfilePictureRemove, cmdProfileNameSet, cmdProfileStatusSet, } from "./profile.js";
 export { cmdLabelAdd, cmdLabelChats, cmdLabelChatAdd, cmdLabelChatRemove, } from "./label.js";

package/dist/cli/commands/commands-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands-index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/commands-index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,WAAW,EACX,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"commands-index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/commands-index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,WAAW,EACX,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,cAAc,CAAC"}

package/dist/cli/commands/commands-index.js

@@ -13,6 +13,7 @@ export { cmdCommunityList, cmdCommunityInfo, cmdCommunityCreate, cmdCommunityLea
 export { cmdMediaDownload } from "./media.js";
 export { cmdGroupList, cmdGroupInfo, cmdGroupParticipants, cmdGroupInviteLink, cmdGroupCreate, cmdGroupLeave, cmdGroupInviteAccept, cmdGroupInviteRevoke, cmdGroupInviteInfo, cmdGroupParticipantsAdd, cmdGroupParticipantsRemove, cmdGroupParticipantsPromote, cmdGroupParticipantsDemote, cmdGroupNameSet, cmdGroupDescriptionSet, cmdGroupPictureSet, } from "./group.js";
 export { cmdCheck, } from "./misc.js";
+export { cmdProxyList, cmdProxyTest, cmdProxyTestAll, } from "./proxy.js";
 export { cmdContactList, cmdContactInfo, cmdContactBusiness, cmdContactPicture, cmdContactAdd, cmdContactRemove, } from "./contact.js";
 export { cmdProfilePictureSet, cmdProfilePictureRemove, cmdProfileNameSet, cmdProfileStatusSet, } from "./profile.js";
 export { cmdLabelAdd, cmdLabelChats, cmdLabelChatAdd, cmdLabelChatRemove, } from "./label.js";

package/dist/cli/commands/commands-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"commands-index.js","sourceRoot":"","sources":["../../../src/cli/commands/commands-index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,WAAW,EACX,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"commands-index.js","sourceRoot":"","sources":["../../../src/cli/commands/commands-index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,WAAW,EACX,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,cAAc,CAAC"}

package/dist/cli/commands/index.d.ts

@@ -8,11 +8,17 @@ export interface CommandContext {
         instanceId: string;
         sessionPath: string;
         debug?: boolean;
+        /** Set by bin/miaw-cli.ts from --proxy or a --proxy-file selection. */
+        proxy?: string;
     };
     jsonOutput?: boolean;
     flags?: {
         [key: string]: string | boolean;
     };
+    /** Proxy list file from --proxy-file, for the `proxy` commands. */
+    proxyFile?: string;
+    /** Selection strategy from --proxy-strategy. */
+    proxyStrategy?: string;
 }
 /**
  * Run a command

package/dist/cli/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoHH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAC7C;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA2+BpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyHH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,uEAAuE;QACvE,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC5C,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA2hCpE"}

package/dist/cli/commands/index.js

@@ -33,7 +33,10 @@ cmdProfilePictureSet, cmdProfilePictureRemove, cmdProfileNameSet, cmdProfileStat
 // Label commands (Business)
 cmdLabelAdd, cmdLabelChats, cmdLabelChatAdd, cmdLabelChatRemove, 
 // Catalog commands (Business)
-cmdCatalogList, cmdCatalogCollections, cmdCatalogProductCreate, cmdCatalogProductUpdate, cmdCatalogProductDelete, } from "./commands-index.js";
+cmdCatalogList, cmdCatalogCollections, cmdCatalogProductCreate, cmdCatalogProductUpdate, cmdCatalogProductDelete, 
+// Proxy commands (no connection required)
+cmdProxyList, cmdProxyTest, cmdProxyTestAll, } from "./commands-index.js";
+import { resolveProxyFile } from "../utils/proxy-config.js";
 /**
  * Run a command
  */
@@ -93,6 +96,46 @@ export async function runCommand(command, args, context) {
                 return false;
         }
     }
+    // Proxy commands (don't require connection - they probe the proxy directly).
+    // Must stay ABOVE getOrCreateClient() so no client is ever constructed.
+    if (command === "proxy") {
+        const subCommand = parsedArgs._[0] || "";
+        const subArgs = parsedArgs._.slice(1);
+        const proxyFile = resolveProxyFile(parsedArgs, context.flags, context.proxyFile);
+        // Flags arrive from two different places: one-shot mode strips every
+        // --flag in bin/miaw-cli.ts before calling runCommand (so they land in
+        // context.flags), while the REPL passes the raw tokenized line (so they
+        // land in parsedArgs). Both must be read or the flag silently no-ops.
+        const showIp = parsedArgs.ip === true || context.flags?.ip === true;
+        const rawTimeout = parsedArgs.timeout ?? context.flags?.timeout;
+        const timeoutMs = typeof rawTimeout === "number"
+            ? rawTimeout
+            : typeof rawTimeout === "string" && /^\d+$/.test(rawTimeout)
+                ? Number(rawTimeout)
+                : undefined;
+        const probeOptions = {
+            showIp,
+            ...(timeoutMs !== undefined && { timeoutMs }),
+        };
+        switch (subCommand) {
+            case "ls":
+            case "list":
+                return await cmdProxyList(proxyFile, jsonOutput);
+            case "test":
+                return await cmdProxyTest(subArgs[0] || context.flags?.proxy || clientConfig.proxy, probeOptions, jsonOutput);
+            case "test-all":
+                return await cmdProxyTestAll(proxyFile, probeOptions, jsonOutput);
+            default:
+                if (!subCommand) {
+                    console.log("Usage: proxy <command>");
+                }
+                else {
+                    console.log(`❌ Unknown proxy command: ${subCommand}`);
+                }
+                console.log("Commands: list, test, test-all");
+                return false;
+        }
+    }
     // Create or get cached client for commands that need connection
     const client = getOrCreateClient(clientConfig);
     // Get commands
@@ -940,7 +983,7 @@ export async function runCommand(command, args, context) {
  * Parse command arguments.
  * Only auto-converts known numeric flags to numbers; all others stay as strings.
  */
-const NUMERIC_FLAGS = new Set(["limit", "count", "cursor"]);
+const NUMERIC_FLAGS = new Set(["limit", "count", "cursor", "timeout"]);
 function parseCommandArgs(args) {
     const parsed = { _: [] };
     for (let i = 0; i < args.length; i++) {