wazap-mcp 0.9.7 → 0.9.8

package/README.md

@@ -189,6 +189,7 @@ manifest, the icon and a fresh production `node_modules`, then packs them with
 | `get_contact` | read | Name, number, about text, profile picture. |
 | `get_group_info` | read | Participants, admins, announcement mode, invite link (when you are admin). |
 | `download_media` | read | Save an attachment to disk; small images also come back inline. |
+| `transcribe_audio` | read | Turn a voice note or audio message into text, with the local or the API provider. |
 | `send_message` | write | Send text, optionally as a reply, with @-mentions. |
 | `send_media` | write | Send an image, video, audio, voice note or document from a path or URL. |
 | `send_poll` | write | Send a poll with 2–12 options. |
@@ -202,10 +203,91 @@ manifest, the icon and a fresh production `node_modules`, then packs them with
 | `manage_group` | write | Add, remove, promote, demote, leave, rename, invite links. |
 
 Every message comes back with a non-empty `text`: media and system messages
-carry a placeholder such as `[image] caption`, `[voice message]`, `[deleted]` or
+carry a placeholder such as `[image] caption`, `[voice message · 0:42]`, `[deleted]` or
 `[poll] Pizza or pasta?`. Timestamps are ISO 8601 with the machine's UTC offset,
 alongside a human `age` like `2h ago`.
 
+## Voice messages
+
+A voice note is the one message an agent cannot read. Switch transcription on and
+it becomes text: `[voice message · 0:42] "sunt la notar, ajung în 20 de minute"`,
+with the bare words also in a `transcript` field. `get_recent_messages` and
+`search_messages` see that text, so a voice note becomes findable by what was
+said in it.
+
+Pick a provider once, in `wazap setup` or later:
+
+```bash
+wazap config transcribe local     # free and private, one 574 MB model on disk
+wazap config transcribe openai    # cheap and fast, the audio leaves this machine
+wazap config transcribe off
+```
+
+| | `local` | `openai` |
+| --- | --- | --- |
+| Runs | whisper.cpp, here | any OpenAI-compatible `/audio/transcriptions` |
+| Costs | nothing | per minute of audio, on your key |
+| Privacy | the audio never leaves this machine | **the audio leaves this machine** |
+| Needs | `whisper-cpp` and `ffmpeg`, plus a model | an API key |
+
+### Local, with whisper.cpp
+
+```bash
+brew install whisper-cpp ffmpeg      # macOS; elsewhere build whisper.cpp, install ffmpeg from your package manager
+wazap transcribe download            # fetch and verify the model
+wazap transcribe test recording.ogg  # prove it before you trust it
+```
+
+Models land in `<data-dir>/models/` and are checked against a SHA-256 pinned in
+the source; an interrupted download resumes where it stopped.
+
+| `WAZAP_WHISPER_MODEL` | File | Size |
+| --- | --- | --- |
+| `turbo` (default) | `ggml-large-v3-turbo-q5_0.bin` | 574 MB |
+| `large-v3` | `ggml-large-v3-q5_0.bin` | 1.08 GB |
+| `medium` | `ggml-medium-q5_0.bin` | 539 MB |
+
+`turbo` is the default because it is the smallest model that still gets Romanian
+right. `medium` and below drop diacritics and mangle names, which is worse than
+no transcript at all: a missing transcript is a question, a wrong name is a wrong
+answer. `large-v3` is the same accuracy for several times the wait.
+
+### An API, OpenAI-compatible
+
+`wazap config transcribe openai` asks for the key without echoing it and stores
+it in `<data-dir>/.env`. The default endpoint is OpenAI; Groq works unchanged:
+
+```bash
+WAZAP_TRANSCRIBE_URL=https://api.groq.com/openai/v1
+WAZAP_TRANSCRIBE_MODEL=whisper-large-v3-turbo
+```
+
+**With this provider the audio leaves your machine.** Every voice note wazap
+transcribes is uploaded to that endpoint. If that is not acceptable, use `local`,
+which uploads nothing.
+
+The key is treated as a secret rather than as a setting:
+
+- It is never accepted as a command-line argument, because an argument lands in
+  your shell history and in `ps`.
+- The prompt echoes nothing, not even asterisks.
+- It is stored only in `<data-dir>/.env`, mode `0600`.
+- `status`, `status --json`, `config` and `get_status` show at most
+  `api key: set (…abcd)`.
+- A provider's own error message has the key stripped out of it before wazap
+  prints it.
+- A plain-`http` `WAZAP_TRANSCRIBE_URL` is refused unless it points back at this
+  machine.
+
+### Without being asked
+
+With a provider configured, incoming voice notes of up to ten minutes are
+transcribed in the background as they arrive, one at a time, never holding up a
+message. The transcript is cached by message id and persisted, so a voice note is
+transcribed once and not again after a restart. Audio *files* are left alone,
+since one can be an hour long; call `transcribe_audio(message_id)` for those.
+`WAZAP_TRANSCRIBE_AUTO=0` keeps the tool and stops the background work.
+
 ## Skills
 
 wazap ships five [Agent Skills](https://agentskills.io) that teach an agent the workflows behind the tools, not just the tools:
@@ -277,6 +359,7 @@ created `0700` with credentials written `0600`:
   auth/         WhatsApp credentials — treat this like a password
   media/        downloads from download_media
   history/      per-chat message history, so a restart is not amnesia
+  models/       whisper.cpp models, when transcription runs locally
   store.json    chat-list snapshot
   server.lock   pid of the running server
   daemon.json   loopback endpoint a second wazap bridges to
@@ -382,6 +465,14 @@ Claude Code, Claude Desktop, Cursor, Codex, VS Code and any client with an "MCP
 | `WAZAP_HOST` / `WAZAP_PORT` | `127.0.0.1` / `8766` | HTTP bind address. |
 | `WAZAP_READ_TOKEN` / `WAZAP_WRITE_TOKEN` | unset | HTTP bearer tokens. |
 | `WAZAP_NO_UPDATE_CHECK` | `0` | `1` stops `status` asking npm for a newer version. |
+| `WAZAP_TRANSCRIBE` | `off` | `local`, `openai` or `off`. |
+| `WAZAP_TRANSCRIBE_AUTO` | `1` | Transcribe incoming voice notes in the background. |
+| `WAZAP_TRANSCRIBE_LANGUAGE` | `auto` | Spoken language, e.g. `ro`. |
+| `WAZAP_WHISPER_MODEL` | `turbo` | `turbo`, `large-v3` or `medium`. |
+| `WAZAP_WHISPER_BIN` | unset | Path to a whisper.cpp binary that is not on `PATH`. |
+| `WAZAP_TRANSCRIBE_API_KEY` | unset | API key; `OPENAI_API_KEY` is the fallback. Never a flag. |
+| `WAZAP_TRANSCRIBE_URL` | `https://api.openai.com/v1` | OpenAI-compatible base URL. |
+| `WAZAP_TRANSCRIBE_MODEL` | `gpt-4o-mini-transcribe` | Model at that URL. |
 
 Flags beat environment variables, which beat `<data-dir>/.env`.
 

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { once } from "node:events";
 import { mkdirSync, rmSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { setTimeout as sleep } from "node:timers/promises";
@@ -16,10 +17,11 @@ import { RELINK_FIX, WazapError, asWazapError } from "./errors.js";
 import { normalizePhone } from "./ids.js";
 import { lockHolder, releaseLock, writeLock } from "./lock.js";
 import { log, logError, say } from "./logger.js";
-import { formatAge } from "./messages.js";
+import { clockLabel, formatAge } from "./messages.js";
 import { RateLimiter } from "./ratelimit.js";
 import { runHttp, runStdio, startLoopbackEndpoint } from "./server.js";
 import { applyWrites } from "./settings.js";
+import { MODELS, downloadModel, maskKey, modelSpec, readTranscribeSettings, stripPasted, transcribeFile, transcribeReady, } from "./transcribe/index.js";
 import { bold, box, brand, humanLayout, dim, fail, fix, info, maskNumber, next, ok, shortPath, spinner, step, tilde, warn, } from "./ui.js";
 import { WA_BROWSER, WhatsAppService } from "./whatsapp.js";
 const LOGIN_TIMEOUT_MS = 120_000;
@@ -241,6 +243,75 @@ export async function runContacts(config) {
         releaseLock(p.lockFile);
     }
 }
+const MIB = 1024 * 1024;
+function mib(bytes) {
+    return Math.round(bytes / MIB);
+}
+/** `wazap transcribe download` and `wazap transcribe test <audio file>`. */
+export async function runTranscribe(config) {
+    const [verb, file] = config.args;
+    const settings = readTranscribeSettings(process.env, config.dataDir);
+    if (verb === "download" && file === undefined) {
+        await downloadTranscribeModel(settings, modelSpec(config.modelName ?? settings.model));
+        return;
+    }
+    if (verb === "test" && file !== undefined) {
+        await testTranscribe(settings, file);
+        return;
+    }
+    throw new WazapError("INVALID_ID", `Cannot run \`wazap transcribe ${config.args.join(" ")}\`.`, "Run `wazap transcribe download` or `wazap transcribe test <audio file>`");
+}
+/**
+ * Also `setup`'s download step. A model already on disk is re-hashed rather than
+ * trusted, which is why the line starts as a check and only then becomes a fetch.
+ */
+export async function downloadTranscribeModel(settings, spec) {
+    const spin = spinner(`Checking ${spec.file}…`);
+    try {
+        const result = await downloadModel(settings.modelsDir, spec, (progress) => {
+            const percent = Math.floor((progress.received / progress.total) * 100);
+            spin.update(`Downloading ${spec.file} — ${mib(progress.received)} / ${mib(progress.total)} MiB (${percent}%)`);
+        });
+        spin.stop(ok(`${spec.file} (${mib(spec.bytes)} MiB) ${result.alreadyPresent ? "already present" : "verified"}`));
+    }
+    catch (err) {
+        spin.stop();
+        throw err;
+    }
+}
+/** What identifies each provider on screen. Keyed like PROVIDERS, never branched on. */
+const PROVIDER_ROWS = {
+    local: (settings) => [
+        ["provider", "local (whisper.cpp)"],
+        ["model", MODELS[settings.model].file],
+    ],
+    openai: (settings) => [
+        ["provider", `openai (${new URL(settings.baseUrl).host})`],
+        ["model", settings.apiModel],
+        ["key", maskKey(settings.apiKey)],
+    ],
+};
+async function testTranscribe(settings, file) {
+    const readiness = await transcribeReady(settings);
+    const provider = settings.provider;
+    if (provider === null || !readiness.ok) {
+        throw new WazapError("TRANSCRIBE_UNAVAILABLE", readiness.detail, readiness.fix);
+    }
+    for (const [label, value] of PROVIDER_ROWS[provider](settings))
+        say(row(label, value));
+    say(row("language", settings.language));
+    say("");
+    const started = Date.now();
+    const spin = spinner(`Transcribing ${shortPath(file)}…`);
+    const transcript = await transcribeFile(settings, file).finally(() => spin.stop());
+    const facts = [
+        `transcribed in ${((Date.now() - started) / 1000).toFixed(1)}s`,
+        transcript.language,
+        transcript.duration_seconds === undefined ? undefined : clockLabel(transcript.duration_seconds),
+    ];
+    say(ok(facts.filter((fact) => fact !== undefined).join(" · ")));
+    say(`"${transcript.text}"`);
+}
 /** Bare `wazap` at a terminal: where you stand, and the one command to run next. */
 export async function runGreet(config) {
     say(banner());
@@ -594,6 +665,27 @@ export async function ask(question) {
         rl.close();
     }
 }
+/**
+ * A secret typed at the prompt, echoed nowhere: not as characters, not as stars.
+ * readline is given no output stream at all, which is the only mute that holds
+ * on current Node — overriding `_writeToOutput` no longer reaches the interface's
+ * own writer. `terminal` still follows the real stdin, so a TTY goes into raw
+ * mode (the kernel stops echoing too) and a pipe reads one line for a script.
+ */
+export async function askSecret(question) {
+    const rl = createInterface({ input: process.stdin, output: undefined, terminal: process.stdin.isTTY === true });
+    process.stderr.write(question);
+    try {
+        // End of input answers nothing rather than hanging the command, and the
+        // caller refuses an empty secret.
+        const answered = rl.question("").catch(() => "");
+        return stripPasted(await Promise.race([answered, once(rl, "close").then(() => "")]));
+    }
+    finally {
+        rl.close();
+        process.stderr.write("\n");
+    }
+}
 const PHONE_ATTEMPTS = 3;
 /** A typo costs another prompt, not the whole login. */
 async function askPhone() {

package/dist/config.js

@@ -28,9 +28,13 @@ const COMMAND_ARGS = {
     status: [0],
     logout: [0],
     connect: [1],
-    config: [0, 2],
+    // A third positional is only ever someone typing the API key after
+    // `config transcribe openai`. It is accepted here so runConfig can refuse it
+    // with the reason, rather than with a generic arity complaint.
+    config: [0, 2, 3],
     contacts: [1],
     skills: [2],
+    transcribe: [1, 2],
 };
 const COMMANDS = Object.keys(COMMAND_ARGS);
 export function defaultDataDir() {
@@ -86,6 +90,8 @@ export function parseCli(argv = process.argv.slice(2)) {
                 "no-writes": { type: "boolean" },
                 agent: { type: "boolean" },
                 client: { type: "string", multiple: true },
+                model: { type: "string" },
+                transcribe: { type: "string" },
                 yes: { type: "boolean", short: "y" },
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
@@ -142,6 +148,7 @@ export function parseCli(argv = process.argv.slice(2)) {
                 readOnly: sourceOf("WAZAP_READ_ONLY", values["read-only"] === true),
                 transport: sourceOf("WAZAP_TRANSPORT", values.http === true),
                 rateLimit: sourceOf("WAZAP_RATE_LIMIT", false),
+                transcribe: sourceOf("WAZAP_TRANSCRIBE", false),
             },
             command,
             explicitCommand: first !== undefined,
@@ -155,6 +162,8 @@ export function parseCli(argv = process.argv.slice(2)) {
             agent: values.agent === true,
             clients: values.client ?? [],
             assumeYes: values.yes === true,
+            modelName: values.model,
+            transcribeChoice: values.transcribe,
         },
     };
 }

package/dist/doctor.js

@@ -1,18 +1,28 @@
 import { accessSync, constants, statSync } from "node:fs";
 import { readLinkedAccount } from "./auth-state.js";
 import { WAZAP_VERSION, paths } from "./config.js";
+import { asWazapError } from "./errors.js";
 import { lockHolder, lockPid } from "./lock.js";
+import { MODELS, findWhisper, localProvider, maskKey, modelPath, readTranscribeSettings, which, } from "./transcribe/index.js";
 import { dim, fail, fix, green, info, ok, red } from "./ui.js";
 export const MARK = { ok: "✓", fail: "✗", info: "–" };
 const GLYPH = { ok, fail, info };
 const TINT = { ok: green, fail: red, info: dim };
 const UPDATE_TIMEOUT_MS = 2_000;
 const MIN_NODE_MAJOR = 20;
-const CHECKS = [checkNode, checkDataDir, checkLock, checkCredentials, checkWrites, checkUpdate];
+const CHECKS = [
+    checkNode,
+    checkDataDir,
+    checkLock,
+    checkCredentials,
+    checkWrites,
+    checkTranscribe,
+    checkUpdate,
+];
 export async function runChecks(config) {
     const checks = [];
     for (const check of CHECKS)
-        checks.push(await check(config));
+        checks.push(...[await check(config)].flat());
     return checks;
 }
 /**
@@ -97,6 +107,68 @@ function checkWrites(config) {
         detail: `${config.readOnly ? "off" : "on"} (${config.sources.readOnly})`,
     };
 }
+const TRANSCRIBE_OFF_FIX = "run `wazap config transcribe local` to transcribe voice messages";
+const DOWNLOAD_FIX = "run `wazap transcribe download`";
+const KEY_FIX = "run `wazap config transcribe openai`";
+const MIB = 1024 * 1024;
+/** What each provider needs before it can run. Keyed like PROVIDERS. */
+const TRANSCRIBE_CHECKS = {
+    local: localChecks,
+    openai: openaiChecks,
+};
+async function checkTranscribe(config) {
+    let settings;
+    try {
+        settings = readTranscribeSettings(process.env, config.dataDir);
+    }
+    catch (err) {
+        // A stale WAZAP_TRANSCRIBE_URL or provider name in someone's .env is exactly
+        // what status is for, so the refusal is reported rather than thrown.
+        const failure = asWazapError(err);
+        return { name: "transcribe", state: "fail", detail: failure.message, fix: failure.fix };
+    }
+    if (settings.provider === null)
+        return { name: "transcribe", state: "info", detail: "off", fix: TRANSCRIBE_OFF_FIX };
+    return TRANSCRIBE_CHECKS[settings.provider](settings);
+}
+function fileSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return null;
+    }
+}
+async function localChecks(settings) {
+    const whisper = findWhisper(settings);
+    const ffmpeg = which("ffmpeg");
+    const spec = MODELS[settings.model];
+    const size = fileSize(modelPath(settings.modelsDir, spec));
+    // ready() reports only the first problem and looks at the binaries before the
+    // model, so its fix is the platform's install hint whenever one is missing.
+    const install = (await localProvider.ready(settings)).fix;
+    return [
+        { name: "transcribe", state: "ok", detail: "local (whisper.cpp)" },
+        whisper === null
+            ? { name: "whisper", state: "fail", detail: "not found", fix: install }
+            : { name: "whisper", state: "ok", detail: whisper },
+        ffmpeg === null
+            ? { name: "ffmpeg", state: "fail", detail: "not found", fix: install }
+            : { name: "ffmpeg", state: "ok", detail: "found" },
+        size === null
+            ? { name: "model", state: "fail", detail: `${spec.file} is not downloaded`, fix: DOWNLOAD_FIX }
+            : { name: "model", state: "ok", detail: `${spec.file} (${Math.round(size / MIB)} MiB)` },
+    ];
+}
+/** maskKey is the only thing that ever renders the key, here and everywhere else. */
+function openaiChecks(settings) {
+    return [
+        { name: "transcribe", state: "ok", detail: `openai (${settings.apiModel} at ${new URL(settings.baseUrl).host})` },
+        settings.apiKey === null
+            ? { name: "api key", state: "fail", detail: maskKey(null), fix: KEY_FIX }
+            : { name: "api key", state: "ok", detail: maskKey(settings.apiKey) },
+    ];
+}
 /** Version comparison over the numeric release fields; prereleases sort as their release. */
 export function isNewer(candidate, current) {
     const parts = (version) => version.split(/[.\-+]/, 3).map((piece) => Number.parseInt(piece, 10) || 0);

package/dist/errors.js

@@ -37,6 +37,8 @@ export const ERROR_GUIDE = {
     NOT_OWN_MESSAGE: "This action only works on messages the linked account sent. Do not retry.",
     READ_ONLY: "wazap runs read-only, so writes are refused. Tell the user to restart without WAZAP_READ_ONLY.",
     RATE_LIMITED: "Too many writes too fast. Wait the number of seconds in the fix, then retry once.",
+    TRANSCRIBE_UNAVAILABLE: "Transcription is off, or its binaries or model are missing. Tell the user to run the command in the fix; do not retry.",
+    TRANSCRIBE_FAILED: "The transcription provider ran and failed. Read the message; retry once at most.",
     TIMEOUT: "WhatsApp did not answer in time. Retry once; if it fails again, call get_status.",
     WHATSAPP_ERROR: "WhatsApp rejected the operation. Read the message; do not blindly retry.",
 };

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { BANNER } from "./banner.js";
-import { runContacts, runGreet, runLogin, runLogout, runServe, runStatus } from "./cli.js";
+import { runContacts, runGreet, runLogin, runLogout, runServe, runStatus, runTranscribe } from "./cli.js";
 import { WAZAP_VERSION, parseCli, pickDefaultAction } from "./config.js";
 import { CLIENT_NAMES, runConnect } from "./connect.js";
 import { SKILL_TARGET_NAMES, runSkills } from "./skills.js";
@@ -17,7 +17,10 @@ Usage:
   wazap setup [--agent] [--client <name>]                  Link, connect your client and finish, in one command
   wazap connect <client> [--dry-run]                       Register wazap with an MCP client
   wazap skills install <harness> [--dry-run]               Copy the five skills into a harness
-  wazap config [writes on|off]                             Show the effective settings, or allow/refuse writes
+  wazap config [writes on|off] [transcribe local|openai|off]
+                                                           Show the effective settings, or change one
+  wazap transcribe download [--model <alias>]              Fetch the whisper.cpp model into the data dir
+  wazap transcribe test <audio file>                       Transcribe a local file with the configured provider
   wazap contacts resync                                    Fetch the phone's address book from WhatsApp again
   wazap status [--live] [--json]                           Check the install, the session and the server
   wazap logout                                             Unlink and delete local credentials
@@ -35,6 +38,8 @@ Options:
   --phone <number>    Your number in international format; implies --code
   --agent             With setup: print the procedure for an AI agent on stdout, then exit
   --client <name>     With setup: connect this client instead of the detected ones (repeatable)
+  --transcribe <how>  With setup: answer the transcription question (local, openai or off)
+  --model <alias>     With transcribe download: turbo (default), large-v3 or medium
   --dry-run           With connect or skills install: print what would be written, and write nothing
   --live              With status: reach WhatsApp for real, then close the connection
   --json              With status: print the whole report as one JSON object on stdout
@@ -46,7 +51,9 @@ Options:
 
 Environment: WAZAP_DATA_DIR, WAZAP_READ_ONLY, WAZAP_SYNC_FULL_HISTORY, WAZAP_PERSIST_HISTORY,
 WAZAP_TRANSPORT, WAZAP_HOST, WAZAP_PORT, WAZAP_READ_TOKEN, WAZAP_WRITE_TOKEN, WAZAP_RATE_LIMIT,
-WAZAP_NO_SHARE, WAZAP_NO_UPDATE_CHECK.
+WAZAP_NO_SHARE, WAZAP_NO_UPDATE_CHECK, WAZAP_TRANSCRIBE, WAZAP_TRANSCRIBE_AUTO,
+WAZAP_TRANSCRIBE_LANGUAGE, WAZAP_TRANSCRIBE_API_KEY, WAZAP_TRANSCRIBE_URL, WAZAP_TRANSCRIBE_MODEL,
+WAZAP_WHISPER_MODEL, WAZAP_WHISPER_BIN.
 An optional <data-dir>/.env is loaded if present.`;
 async function main() {
     const invocation = parseCli();
@@ -80,7 +87,10 @@ async function main() {
             runSkills(config);
             return;
         case "config":
-            runConfig(config);
+            await runConfig(config);
+            return;
+        case "transcribe":
+            await runTranscribe(config);
             return;
         case "contacts":
             await runContacts(config);

package/dist/messages.js

@@ -85,7 +85,13 @@ const RULES = {
     ptvMessage: { type: "video", tag: "[video]", caption: (m) => m.ptvMessage?.caption },
     audioMessage: {
         type: (m) => (m.audioMessage?.ptt ? "voice" : "audio"),
-        tag: (m) => (m.audioMessage?.ptt ? "[voice message]" : "[audio]"),
+        // The duration goes inside the brackets, the way a call's does: everything
+        // after the tag is caption territory, and this is not a caption.
+        tag: (m) => {
+            const kind = m.audioMessage?.ptt ? "voice message" : "audio";
+            const seconds = audioSeconds(m);
+            return seconds === undefined ? `[${kind}]` : `[${kind} · ${clockLabel(seconds)}]`;
+        },
     },
     documentMessage: {
         type: "document",
@@ -223,6 +229,25 @@ export function isCallPlaceholder(raw) {
     const content = unwrapEnvelopes(raw.message);
     return content?.call != null && content.callLogMesssage == null;
 }
+/** A duration WhatsApp attached to a recording. Zero means it said nothing. */
+function audioSeconds(content) {
+    const seconds = protoNumber(content.audioMessage?.seconds);
+    return seconds === undefined || seconds <= 0 ? undefined : seconds;
+}
+/** How long a voice note or audio message runs, when WhatsApp said so. */
+export function voiceSeconds(raw) {
+    const content = unwrapEnvelopes(raw.message);
+    return content === undefined ? undefined : audioSeconds(content);
+}
+/** 0:06, 3:05, 1:02:03 — a recording reads as a clock, unlike a call's "6 min". */
+export function clockLabel(seconds) {
+    const total = Math.max(0, Math.round(seconds));
+    const pad = (value) => String(value).padStart(2, "0");
+    const minutes = Math.floor(total / 60) % 60;
+    const hours = Math.floor(total / 3600);
+    const rest = pad(total % 60);
+    return hours > 0 ? `${hours}:${pad(minutes)}:${rest}` : `${minutes}:${rest}`;
+}
 function durationLabel(seconds) {
     if (seconds < 60)
         return `${seconds}s`;
@@ -313,6 +338,22 @@ export function messageText(raw) {
     const detail = rule.detail?.(node)?.trim();
     return detail ? `${tag} ${detail}` : tag;
 }
+/** A transcript belongs to a recording and to nothing else. */
+function spokenTranscript(raw, transcript) {
+    if (!transcript?.text)
+        return undefined;
+    const type = messageType(raw);
+    return type === "voice" || type === "audio" ? transcript.text : undefined;
+}
+/**
+ * What a reader sees. searchMessages matches on this rather than on the bare
+ * placeholder, so a transcript is findable by the words it puts on the screen.
+ */
+export function viewText(raw, transcript) {
+    const text = messageText(raw);
+    const spoken = spokenTranscript(raw, transcript);
+    return spoken === undefined ? text : `${text} "${spoken}"`;
+}
 export function mediaInfo(raw) {
     const outer = unwrapEnvelopes(raw.message);
     const content = outer ? (viewOnceInner(outer) ?? outer) : undefined;
@@ -390,7 +431,7 @@ export function buildMessageView(raw, ctx) {
             ...(phoneOf(sender) ? { phone: phoneOf(sender) } : {}),
         },
         type: messageType(raw),
-        text: messageText(raw),
+        text: viewText(raw, ctx.transcript),
         timestamp: isoWithOffset(timestamp),
         age: formatAge(timestamp, ctx.now),
         has_media: media !== undefined,
@@ -401,6 +442,9 @@ export function buildMessageView(raw, ctx) {
         view.media = media;
     if (quoted)
         view.quoted = quoted;
+    const spoken = spokenTranscript(raw, ctx.transcript);
+    if (spoken !== undefined)
+        view.transcript = spoken;
     if (call) {
         view.call = call.participants
             ? { ...call, participants: call.participants.map((jid) => ctx.canonical(jid)) }

package/dist/ratelimit.js

@@ -7,11 +7,15 @@ import { WazapError } from "./errors.js";
 export class RateLimiter {
     perMinute;
     now;
+    what;
     tokens;
     last;
-    constructor(perMinute, now = Date.now) {
+    constructor(perMinute, now = Date.now, 
+    /** What ran out, so a tool with a bucket of its own does not blame the writes. */
+    what = "Write") {
         this.perMinute = perMinute;
         this.now = now;
+        this.what = what;
         this.tokens = perMinute;
         this.last = now();
     }
@@ -30,6 +34,6 @@ export class RateLimiter {
             return;
         }
         const seconds = Math.max(1, Math.ceil(((1 - this.tokens) * 60_000) / this.perMinute / 1000));
-        throw new WazapError("RATE_LIMITED", `Write rate limit reached (${this.perMinute}/minute).`, `Wait ${seconds} seconds`);
+        throw new WazapError("RATE_LIMITED", `${this.what} rate limit reached (${this.perMinute}/minute).`, `Wait ${seconds} seconds`);
     }
 }