miaw-core 1.9.1 → 1.12.0

package/.env.example

@@ -0,0 +1,78 @@
+# 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) ──────────────────────────────────
+#
+# Precedence, highest first (v1.11.0):
+#   1. MIAW_PROXY / --proxy        always wins; warns when it shadows a pin
+#   2. a pin in <MIAW_SESSION_PATH>/instances.json, per instance
+#   3. MIAW_PROXY_FILE + strategy  hashed on the TARGET instanceId
+#   4. direct
+#
+# The pin store is written by `miaw-cli instance set-proxy <id> ...`, not by
+# env vars - it is per-instance state, so it belongs with the sessions rather
+# than with process config. It holds credentials when a URL is pinned, so it is
+# written 0600 and must live on the same persistent, secret-grade volume as the
+# session directories. See docs/DEPLOYMENT_INSTANCE_PROXY.md.
+
+# 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. A proxy is selected per instance using MIAW_PROXY_STRATEGY, keyed on
+# the instance the command targets (v1.11.0; before that, once per process
+# against the startup instance).
+# Ignored when MIAW_PROXY is also set, and outranked by a per-instance pin.
+# (flag: --proxy-file)
+#
+# Also required when an instance is pinned by label (`instance set-proxy <id>
+# --label eu`): the label names an entry in THIS file. A label pin that cannot
+# be resolved refuses to connect rather than silently going direct.
+#
+# 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,330 @@ 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.12.0] - 2026-09-02
+
+**Baileys 7.0.0-rc14, and the deferred feature backlog cleared.** All additive;
+no breaking changes.
+
+### Changed
+
+- **Operator notes:** [docs/DEPLOYMENT_V1.12.0.md](docs/DEPLOYMENT_V1.12.0.md) —
+  no env, migration or state-format changes; rollback does not require re-pairing.
+- **Upgraded `@whiskeysockets/baileys` from `7.0.0-rc13` to `7.0.0-rc14`** (pinned
+  exactly, as before). Four substantive upstream commits:
+  - WhatsApp Web version `2.3000.1035194821` → `2.3000.1043857760`. Low impact —
+    `resolveWAVersion()` already prefers the live version from `web.whatsapp.com`,
+    so the bundled constant is only the third-tier fallback — but a fresher
+    fallback is still worth having.
+  - **`profilePictureUrl` fix.** The privacy `tctoken` now nests under the
+    `picture` query node and carries a `t` attribute, matching WA Web. This
+    affects `getContactInfo()`, `getProfilePicture()` and `getChatInfo()` when
+    the target has profile-picture privacy enabled.
+  - New `Browsers.android()` identity (see below).
+  - An internal `Long` type import fix.
+
+  No public API changed; miaw-core's whole Baileys surface — including the
+  `updateBussinesProfile` typo, `signalRepository.lidMapping`, the hand-built
+  `remove-companion-device` node, `messaging-history.set` `lidPnMappings`, the
+  `resyncAppState` collection names, and the dispatcher passed into
+  `downloadMediaMessage` — is byte-identical between the two releases.
+
+### Added
+
+- **`BrowserPresets`** — `macOS`, `windows`, `ubuntu` and `android` browser
+  identities for the `browser` option, which was previously undocumented outside
+  its JSDoc. The default is unchanged (`macOS("Chrome")`).
+- **Android connection identity.** `BrowserPresets.android()` negotiates as an
+  Android client rather than a web one. Baileys reports this is required to
+  **receive view-once media**, which a web session is never sent
+  ([#2201](https://github.com/WhiskeySockets/Baileys/pull/2201)); miaw-core
+  already normalizes view-once messages, so if that holds,
+  `message.media.viewOnce` and `downloadMedia()` work with no further change.
+  The handshake is verified here; the view-once receipt itself is upstream's
+  claim and is **not** confirmed end-to-end — see `tests/verify-viewonce.ts` to
+  check it on your own account. Baileys marks the identity experimental; prefer
+  a dedicated `instanceId` over switching an established session.
+- **Group & community administration.** `setGroupAnnounceOnly`,
+  `setGroupRestrictInfo`, `setGroupMemberAddMode`, `setGroupJoinApproval`,
+  `setGroupEphemeral`, `getGroupJoinRequests`, `approveGroupJoinRequests`,
+  `rejectGroupJoinRequests`, and the eight `setCommunity*` /
+  `*CommunityJoinRequests` equivalents.
+- **Privacy settings.** `getPrivacySettings()` plus `setLastSeenPrivacy`,
+  `setOnlinePrivacy`, `setProfilePicturePrivacy`, `setStatusPrivacy`,
+  `setReadReceiptsPrivacy`, `setGroupAddPrivacy`, `setMessagesPrivacy`,
+  `setCallPrivacy`, `setDefaultDisappearingMode` and `setLinkPreviewsDisabled`.
+- **Blocklist.** `blockContact()`, `unblockContact()`, `getBlocklist()`,
+  `isBlocked()`.
+- **Calls.** A new `call` event carrying a normalized `MiawCall`, plus
+  `rejectCall()` and `createCallLink()`. A single call fires the event several
+  times as it progresses; `status === "offer"` is the only stage at which
+  `rejectCall()` still works.
+- **Disappearing messages.** `setChatEphemeral()` for 1:1 chats alongside the
+  group and community variants, with an `EphemeralDuration` constant for the four
+  durations the WhatsApp UI offers.
+- **Group invite cards.** `sendGroupInvite()` sends the rich "join my group" card
+  rather than a pasted link. Its payload type is `GroupInviteMessage` — distinct
+  from the existing `GroupInviteInfo`, which is the *preview* returned by
+  `getGroupInviteInfo()` before joining.
+- **Pin-in-chat.** `pinMessage()` / `unpinMessage()`, with a `PinDuration`
+  constant. WhatsApp accepts only 24h, 7d and 30d here — a different set from the
+  disappearing-message durations.
+- **CLI:** `group|community announce|restrict|add-mode|approval|ephemeral`,
+  `group|community requests list|approve|reject`, `privacy
+  show|set|disappearing|link-previews`, `block list|add|remove`, `call link`,
+  `chat ephemeral|pin-message|unpin-message`, and `send group-invite`. All with
+  tab completion and `help` topics.
+- **`tests/unit/baileys-export-surface.test.ts`** — imports Baileys unmocked and
+  asserts every symbol the two import sites destructure still exists. Seventeen
+  unit suites replace the module wholesale with hand-written factories, so
+  without this a renamed or removed upstream export stays invisible until
+  runtime.
+
+### Fixed
+
+- **`community invite-link` was advertised but never worked.** The subcommand
+  list printed by `community` has named it since v1.9.0, but the dispatch
+  switch had no `case` for it, so it fell through to the unknown-command
+  branch and always errored. `group invite-link` has existed since v1.4.
+- **Five `help` topics tab-completed and then failed.** `help chat|story|
+  community|call|business` were offered by completion but had no case in
+  `showReplHelp()`, printing "Unknown help topic". The completion tree, the
+  dispatch and two "available topics" lines were four hand-maintained copies
+  of the same list; they are now all derived from one `HELP_TOPIC_HANDLERS`
+  map, and the five missing help screens were written.
+- **`test:manual:build` never worked and has been removed.** It ran
+  `node dist/tests/interactive-test.js`, but `tsconfig.json` sets
+  `rootDir: ./src` and excludes `tests/`, so `dist/tests/` is never emitted.
+- **`sendGroupInvite()` failed for any group without a profile picture.** Baileys
+  embeds a thumbnail on the invite card by calling `getProfilePicUrl(groupJid)`
+  and does not guard it; WhatsApp answers `item-not-found` for a pictureless
+  group, which throws and aborts the whole send. Since most groups have no
+  picture, the unguarded path failed more often than it worked. `sendGroupInvite`
+  now passes its own guarded hook — Baileys spreads caller options last, so it
+  wins — and sends the card without a thumbnail rather than not at all. Found by
+  live testing; it is invisible to unit tests because the mock never throws.
+- **Omitting a disappearing-message duration silently disabled it.**
+  `miaw-cli group ephemeral <jid>` with no duration turned disappearing messages
+  **off** for the whole group instead of printing a usage line — `Number("")` is
+  `0`, and `0` is a valid duration meaning "off", so the missing argument parsed
+  as a successful request to disable. Same for `community ephemeral`,
+  `chat ephemeral`, and `privacy disappearing` (which changed an account-wide
+  default). Found in review of this release, before any of it shipped.
+- **`--force` could swallow the following token.** It was missing from
+  `BOOLEAN_FLAGS` in `bin/miaw-cli.ts`, the same class of bug that `--json` hit
+  previously.
+- **CLI docs gap.** `chat` commands were entirely undocumented in
+  [CLI.md](docs/CLI.md) despite shipping in v1.7.0; they now have a section.
+
+### Verified live
+
+Against a real WhatsApp connection (Baileys rc14):
+
+- **`profilePictureUrl`** — the upstream tctoken-nesting fix. 2 of 5 real
+  contacts resolved to live URLs; the rest correctly returned `null`.
+- **`getPrivacySettings()`** — WhatsApp returned 16 categories; the 8 with
+  Baileys setters map onto typed fields and the other 8 survive under `raw`.
+- **All 19 v1.12.0 write paths** — every group setting toggled and restored with
+  a read-back confirming the change landed, plus 1:1 ephemeral, privacy
+  round-trips, `sendGroupInvite`, pin/unpin, and `createCallLink`. 19/19.
+- **`BrowserPresets.android()`** — WhatsApp issued a QR rather than a 428, so
+  the `Platform.ANDROID` handshake is accepted. End-to-end view-once *receipt*
+  is not yet confirmed; see [FOLLOW_UPS.md](docs/FOLLOW_UPS.md) section 7.
+- **No regressions from rc14.** The CLI integration suite has 15 pre-existing
+  failures, unrelated to this release — running the same six suites against
+  rc13 produced a byte-identical failure set. They are catalogued in
+  [FOLLOW_UPS.md](docs/FOLLOW_UPS.md) section 9.
+
+### Internal
+
+- `jest.config.js` sets `maxWorkers: 1`. The live-connection suites share a
+  single WhatsApp session, and forking one worker per core for a full run is
+  memory-hungry; `test:cli` already passed `--runInBand` for the first reason.
+- CLI integration teardown moved from `10-business-commands.test.ts` to the new
+  `13-privacy-call-commands.test.ts`. Files run in name order and 13 is now the
+  last one needing a connection (11 and 12 are deliberately offline), so
+  disconnecting at 10 would pull the socket out from under it.
+- 615 unit tests across 29 suites (up from 417), 105 CLI router tests (up from
+  26), 278 CLI integration tests across 13 files (up from 238).
+- New `tests/unit/cli-help-consistency.test.ts` and a dispatchability sweep in
+  `01-command-router.test.ts`, both verified to fail against the previous code.
+- The manual runner grew from 82 to 96 entries, and gained a `community` group:
+  all 19 community methods, v1.9.0's included, had been unreachable from it.
+
+## [1.11.0] - 2026-09-02
+
+### Added
+
+- **Per-instance proxy pins (CLI).** `miaw-cli instance set-proxy <id>` persists a
+  proxy assignment to `<session-path>/instances.json`, so
+  `miaw-cli --instance-id bot-3 <command>` uses bot-3's proxy with no flags.
+  Four sources: a positional URL, `--label <name>` (selects a `label=` entry from
+  the proxy file and stores **no credentials**), `--from-env <VAR>`, and
+  `--from-file` (materializes the current deterministic selection).
+  `instance unset-proxy <id>` removes it.
+- `instance ls` gains a Proxy column (masked) and lists instances that are pinned
+  but not yet created as `[not created]` — pinning before `instance create` is
+  supported, so the pairing itself comes from the final egress IP.
+- **`MiawClient.setProxy(proxy)`** — stages a proxy for the **next** `connect()`,
+  returning `{ success, proxy, reconnectRequired, error }`. It never touches a
+  live socket, validates eagerly, and is refused when the client was constructed
+  with a custom `agent`/`fetchAgent`.
+- `getProxyInfo()` gains `active` (is the open socket using this config?) and
+  `pending` (what it is using instead). The `{ url, protocol }` shape and the
+  `null`-for-custom-agent contract are unchanged.
+- New exported types `SetProxyResult` and `ProxyInfo`.
+- A complete, runnable dead-proxy failover recipe in docs/PROXY.md and
+  examples/10-proxy-rotation.ts, reusing a single client.
+- `docs/DEPLOYMENT_INSTANCE_PROXY.md` — operational notes for the new
+  persistent pin store, and `docs/FOLLOW_UPS.md` for deferred findings.
+
+### Behavior changes
+
+- **`ProxyRotator` now defaults to `deterministic`, not `round-robin`.** The docs
+  and CLAUDE.md have always said deterministic is the default; only the CLI
+  actually applied it. The mismatch was silent and severe: following the docs
+  (`new ProxyRotator(urls)` then `next(id)`) gave round-robin, which hands a
+  long-lived session a different egress IP on each call — read by WhatsApp as
+  account takeover. Code changed rather than docs, so the default fails safe.
+  `next()` with no `instanceId` on a defaulted rotator now throws a message
+  naming the fix; pass `{ strategy: "round-robin" }` explicitly to restore the
+  old behavior. Checked against the sibling `miaw-api`, which constructs with an
+  explicit strategy and always calls `next(instanceId)`: unaffected.
+
+### Fixed
+
+- **The CLI silently dropped the proxy.** `instance create`/`connect`/`disconnect`/
+  `logout` built clients from `{instanceId, sessionPath}` only, discarding both
+  `proxy` and `debug`. Since the client cache key ignored the proxy, REPL
+  `connect <id>` cached a proxy-less client that every later command reused —
+  traffic went direct with no indication.
+- **REPL `use <id>` carried the previous instance's proxy** to the next one: it
+  mutated `config.instanceId` in place without re-resolving.
+- **Proxy selection ignored the target instance.** `--proxy-file` was resolved once
+  per process against the *startup* instance id, so `instance connect bot-3` got
+  another instance's egress IP. Resolution is now per target.
+- `instance create` called `createClient()` directly, bypassing the cache, so the
+  freshly-paired live client was never registered and the next command built a
+  second `MiawClient` for the same account.
+- An explicit `disconnect()` emitted `disconnected` twice — once as `"unknown"`
+  from the `connection.update{close}` that Baileys' `end()` fires, then once as
+  `"intentional"`.
+- Console-filter reference leak: the filter was acquired only in the constructor
+  but released on every `disconnect()`/`logout()`, so a reconnect cycle lost this
+  client's reference and repeated cycles un-filtered other live clients' output.
+- Proxy transports leaked: `connect()` built fresh agents on every call, auto-
+  reconnects included, and never released the old ones.
+- `.cli_history` was written 0644 with every line verbatim, so an
+  `instance set-proxy` command turned it into a plaintext credential store. Now
+  redacted at entry and written 0600.
+- **Global boolean flags swallowed the command name.** The arg parser assumed
+  every `--flag` took a value, so `miaw-cli --json instance ls` parsed as
+  `json="instance"` and failed with "Unknown command: ls" — even though
+  `--json` is documented as a global option. Value-less flags (`--json`,
+  `--debug`, `--ip`, `--from-file`, `--help`, `--version`) are now recognised
+  as booleans in any position.
+- **`src/utils/proxy-rotator.ts` contained a literal NUL byte**, which made
+  `file(1)` classify the source as binary and caused `grep` to skip it in any
+  repo-wide search. Replaced with the equivalent escape sequence; verified
+  runtime-identical, so no instance is remapped to a different proxy.
+- **Docs: `fetchAgent` is an `http.Agent`, not an undici Dispatcher.** The JSDoc
+  and three doc sites claimed otherwise; the PROXY.md "Custom agents" snippet was
+  copy-pasteable and would silently break every media upload through the proxy.
+  Also corrects the `createProxyAgents` API-table row and two broken anchors.
+
+## [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.
@@ -328,6 +652,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