@yujinapp/yuemail 0.4.1 → 0.6.1

package/server-dist/routes/voice.js

@@ -0,0 +1,125 @@
+/**
+ * /api/voice/* routes (v0.6.0 -- camino 1 for hearing + speaking).
+ *
+ *  GET  /api/voice/config  -> { config, has_key }
+ *  PUT  /api/voice/config  -> body partial -> { config, has_key }
+ *  POST /api/voice/stt     -> raw audio bytes (header X-Audio-Format) ->
+ *                             { ok:true, transcript } | { ok:false, reason }
+ *  POST /api/voice/tts     -> body { text, ... } -> binary audio
+ *                             | { ok:false, reason } when camino 1 unavailable
+ *
+ * A { ok:false, reason } body (HTTP 200) is NOT an error: it tells the
+ * client to fall back to the browser's Web Speech API. has_key is a boolean
+ * only -- the decrypted Google key never leaves the server.
+ *
+ * ASCII-only.
+ */
+import express from 'express';
+import { readVoiceConfig, patchVoiceConfig, } from '../voice/config.js';
+import { transcribe, synthesize } from '../voice/router.js';
+import { googleVoiceReady, SPEECH_VAULT_SLOT } from '../voice/google.js';
+import { getKey } from '../vault.js';
+const STT_MAX_BYTES = 25 * 1024 * 1024;
+const SUPPORTED_STT = new Set(['webm', 'ogg', 'wav', 'mp3', 'flac']);
+const TTS_MIME = {
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+};
+async function hasSpeechKey() {
+    try {
+        const k = await getKey(SPEECH_VAULT_SLOT);
+        return typeof k === 'string' && k.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function publicConfig(cfg) {
+    return {
+        enabled: cfg.enabled,
+        language: cfg.language,
+        voice: cfg.voice,
+        speed: cfg.speed,
+        format: cfg.format,
+    };
+}
+export function registerVoiceRoutes(app) {
+    app.get('/api/voice/config', async (_req, res) => {
+        const cfg = await readVoiceConfig();
+        res.json({ ok: true, config: publicConfig(cfg), has_key: await hasSpeechKey() });
+    });
+    app.put('/api/voice/config', async (req, res) => {
+        const body = (req.body ?? {});
+        const patch = {};
+        if (typeof body['enabled'] === 'boolean')
+            patch.enabled = body['enabled'];
+        if (typeof body['language'] === 'string')
+            patch.language = body['language'];
+        if (typeof body['voice'] === 'string')
+            patch.voice = body['voice'];
+        if (typeof body['speed'] === 'number')
+            patch.speed = body['speed'];
+        if (body['format'] === 'mp3' || body['format'] === 'wav' || body['format'] === 'ogg') {
+            patch.format = body['format'];
+        }
+        const cfg = await patchVoiceConfig(patch);
+        res.json({ ok: true, config: publicConfig(cfg), has_key: await hasSpeechKey() });
+    });
+    /* Hearing. Raw audio in the body; the container is declared in the
+     * X-Audio-Format header (the browser sends 'webm'; the test harness
+     * sends the format it synthesised). */
+    app.post('/api/voice/stt', express.raw({ type: '*/*', limit: STT_MAX_BYTES }), async (req, res) => {
+        const fmt = String(req.header('x-audio-format') ?? '').toLowerCase().trim();
+        if (!SUPPORTED_STT.has(fmt)) {
+            res.status(400).json({ ok: false, reason: 'bad_format', detail: fmt || '(none)' });
+            return;
+        }
+        const audio = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+        if (audio.length === 0) {
+            res.status(400).json({ ok: false, reason: 'empty_audio' });
+            return;
+        }
+        const langHeader = String(req.header('x-audio-language') ?? '').trim();
+        const outcome = await transcribe({
+            audio,
+            format: fmt,
+            languageHint: langHeader || undefined,
+        });
+        if (!outcome.ok) {
+            res.json({ ok: false, reason: outcome.reason, detail: outcome.detail });
+            return;
+        }
+        res.json({ ok: true, transcript: outcome.result });
+    });
+    /* Speaking. JSON in, binary audio out. A miss returns JSON so the client
+     * knows to use the browser voice instead. */
+    app.post('/api/voice/tts', async (req, res) => {
+        const body = (req.body ?? {});
+        const text = typeof body['text'] === 'string' ? body['text'] : '';
+        if (text.trim().length === 0) {
+            res.status(400).json({ ok: false, reason: 'empty_text' });
+            return;
+        }
+        const outcome = await synthesize({
+            text,
+            language: typeof body['language'] === 'string' ? body['language'] : undefined,
+            voice: typeof body['voice'] === 'string' ? body['voice'] : undefined,
+            speed: typeof body['speed'] === 'number' ? body['speed'] : undefined,
+            format: body['format'] === 'mp3' || body['format'] === 'wav' || body['format'] === 'ogg'
+                ? body['format'] : undefined,
+        });
+        if (!outcome.ok) {
+            res.json({ ok: false, reason: outcome.reason, detail: outcome.detail });
+            return;
+        }
+        res.setHeader('content-type', TTS_MIME[outcome.result.format]);
+        res.setHeader('x-voice-provider', outcome.result.provider);
+        res.setHeader('x-voice-voice', outcome.result.voice);
+        res.setHeader('x-voice-latency-ms', String(outcome.result.latency_ms));
+        res.send(outcome.result.audio);
+    });
+}
+/** Tiny helper so unit tests can read whether camino 1 is reachable without
+ *  a real round-trip. */
+export { googleVoiceReady };

package/server-dist/vault.js

@@ -65,6 +65,23 @@ export const VAULT_KEYS = [
     'smtp.secure',
     'identity.from',
     'identity.name',
+    /* Brain provider API keys (v0.5.0). One slot per provider; the router
+     * reads them server-side and they never reach the browser, exactly like
+     * the mail credentials above. Ollama is local + keyless but kept in the
+     * allowlist for symmetry. */
+    'brain.google_ai',
+    'brain.anthropic',
+    'brain.openai',
+    'brain.deepseek',
+    'brain.xai',
+    'brain.mistral',
+    'brain.qwen',
+    'brain.zai',
+    'brain.ollama',
+    /* Voice (v0.6.0). One Google Cloud key powers both Speech-to-Text
+     * (hearing) and Text-to-Speech (speaking); the voice router reads it
+     * server-side and it never reaches the browser, like every slot above. */
+    'speech.google',
 ];
 export function isValidVaultKey(name) {
     return VAULT_KEYS.includes(name);

package/server-dist/voice/config.js

@@ -0,0 +1,88 @@
+/**
+ * Voice config -- how Yuemail hears and speaks (v0.6.0). Mirrors the Brain
+ * config shape (server-side, single-user, honours YUEMAIL_HOME).
+ *
+ * Storage:
+ *   ~/.yuemail/voice.json
+ *
+ * Camino 1 (default): Google Cloud for both hearing (STT) and speaking
+ * (TTS) -- the more accurate ear and the more natural voice for an audience
+ * that depends on them. The browser's Web Speech API stays as camino 2, the
+ * safety net the CLIENT falls back to when 'enabled' is false, no key is
+ * stored, or a Google round-trip fails. A person who depends on this app is
+ * never left without it.
+ *
+ * ASCII-only.
+ */
+import { promises as fs, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export function defaultVoiceConfig() {
+    return {
+        version: 1,
+        enabled: true,
+        language: 'es-AR',
+        voice: '',
+        speed: 1.0,
+        format: 'mp3',
+    };
+}
+function homeDir() {
+    const env = process.env['YUEMAIL_HOME'];
+    return env ? path.resolve(env) : path.join(os.homedir(), '.yuemail');
+}
+function voiceConfigPath() { return path.join(homeDir(), 'voice.json'); }
+function ensureHomeDir() {
+    if (!existsSync(homeDir()))
+        mkdirSync(homeDir(), { recursive: true, mode: 0o700 });
+}
+function clampSpeed(v, fallback) {
+    if (typeof v !== 'number' || Number.isNaN(v))
+        return fallback;
+    if (v < 0.25)
+        return 0.25;
+    if (v > 4.0)
+        return 4.0;
+    return v;
+}
+function normaliseFormat(v, fallback) {
+    return v === 'mp3' || v === 'wav' || v === 'ogg' ? v : fallback;
+}
+export async function readVoiceConfig() {
+    const def = defaultVoiceConfig();
+    try {
+        const raw = await fs.readFile(voiceConfigPath(), 'utf-8');
+        const j = JSON.parse(raw);
+        return {
+            version: 1,
+            enabled: j.enabled !== false,
+            language: typeof j.language === 'string' && j.language.trim() !== '' ? j.language.trim() : def.language,
+            voice: typeof j.voice === 'string' ? j.voice.trim() : def.voice,
+            speed: clampSpeed(j.speed, def.speed),
+            format: normaliseFormat(j.format, def.format),
+        };
+    }
+    catch {
+        return def;
+    }
+}
+export async function writeVoiceConfig(cfg) {
+    ensureHomeDir();
+    const p = voiceConfigPath();
+    const tmp = p + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    await fs.rename(tmp, p);
+}
+export async function patchVoiceConfig(patch) {
+    const cur = await readVoiceConfig();
+    const next = {
+        version: 1,
+        enabled: typeof patch.enabled === 'boolean' ? patch.enabled : cur.enabled,
+        language: typeof patch.language === 'string' && patch.language.trim() !== '' ? patch.language.trim() : cur.language,
+        voice: typeof patch.voice === 'string' ? patch.voice.trim() : cur.voice,
+        speed: patch.speed === undefined ? cur.speed : clampSpeed(patch.speed, cur.speed),
+        format: patch.format === undefined ? cur.format : normaliseFormat(patch.format, cur.format),
+    };
+    await writeVoiceConfig(next);
+    return next;
+}

package/server-dist/voice/google.js

@@ -0,0 +1,222 @@
+/**
+ * Google Cloud voice provider -- Speech-to-Text (hearing) + Text-to-Speech
+ * (speaking). Raw fetch, no SDK (the Forge lesson: SDKs blow the bundle
+ * budget). The API key travels in the 'x-goog-api-key' header, never a
+ * query string, and is never logged.
+ *
+ * Ported from c:/yujin-forge/src/voice/providers/google.ts and adapted to
+ * read the key from Yuemail's vault (slot 'speech.google') and to use the
+ * camino-1 raw-fetch style of server/brain/providers.ts.
+ *
+ * ASCII-only.
+ */
+import { getKey } from '../vault.js';
+/** The single vault slot the Google voice key lives under. The same key
+ *  powers both Cloud Speech-to-Text and Cloud Text-to-Speech. */
+export const SPEECH_VAULT_SLOT = 'speech.google';
+const STT_ENDPOINT = 'https://speech.googleapis.com/v1/speech:recognize';
+const TTS_ENDPOINT = 'https://texttospeech.googleapis.com/v1/text:synthesize';
+/** Container -> Google STT encoding enum. */
+function sttEncoding(format) {
+    switch (format) {
+        case 'webm': return 'WEBM_OPUS';
+        case 'ogg': return 'OGG_OPUS';
+        case 'wav': return 'LINEAR16';
+        case 'mp3': return 'MP3';
+        case 'flac': return 'FLAC';
+    }
+}
+/** Container -> Google TTS audioEncoding enum. */
+function ttsEncoding(format) {
+    switch (format) {
+        case 'mp3': return 'MP3';
+        case 'wav': return 'LINEAR16';
+        case 'ogg': return 'OGG_OPUS';
+    }
+}
+/**
+ * Google's enhanced Spanish STT models are certified for es-US / es-ES /
+ * es-419 only. Map the regional variants Yuemail uses (es-AR is the client
+ * default) onto es-US so the request always lands on an enhanced model that
+ * handles accent + aspirated-s. Non-Spanish locales pass through unchanged.
+ */
+function normaliseSpanishLocale(bcp47) {
+    const lc = (bcp47 ?? 'es-US').trim();
+    if (/^es(-|$)/i.test(lc))
+        return 'es-US';
+    return lc;
+}
+/* Locale -> a concrete Neural2 voice. Strip the region as a fallback so an
+ * unmapped es-XX still gets the Spanish voice. */
+const LOCALE_TO_VOICE = {
+    es: 'es-US-Neural2-A',
+    'es-us': 'es-US-Neural2-A',
+    'es-ar': 'es-US-Neural2-A',
+    'es-mx': 'es-US-Neural2-A',
+    'es-es': 'es-ES-Neural2-A',
+    en: 'en-US-Neural2-C',
+    'en-us': 'en-US-Neural2-C',
+    'en-gb': 'en-GB-Neural2-A',
+    'pt-br': 'pt-BR-Neural2-A',
+    'fr-fr': 'fr-FR-Neural2-A',
+    'it-it': 'it-IT-Neural2-A',
+    'de-de': 'de-DE-Neural2-B',
+};
+function voiceForLocale(bcp47) {
+    const lc = (bcp47 ?? 'es-US').toLowerCase().trim();
+    if (LOCALE_TO_VOICE[lc])
+        return LOCALE_TO_VOICE[lc];
+    const lang = lc.split('-')[0];
+    if (lang && LOCALE_TO_VOICE[lang])
+        return LOCALE_TO_VOICE[lang];
+    return 'es-US-Neural2-A';
+}
+/** A Google voice name embeds its own languageCode (the first two segments,
+ *  e.g. 'es-US-Neural2-A' -> 'es-US'). Google rejects a synth request when
+ *  the voice's language disagrees with the supplied languageCode, so the
+ *  voice's own language always wins. */
+function languageFromVoice(voice) {
+    const parts = voice.split('-');
+    return parts.length >= 2 ? parts[0] + '-' + parts[1] : 'es-US';
+}
+function clampSpeed(v) {
+    if (typeof v !== 'number' || Number.isNaN(v))
+        return 1.0;
+    if (v < 0.25)
+        return 0.25;
+    if (v > 4.0)
+        return 4.0;
+    return v;
+}
+async function readSpeechKey(apiKeyOverride) {
+    if (apiKeyOverride !== undefined)
+        return apiKeyOverride;
+    try {
+        return (await getKey(SPEECH_VAULT_SLOT)) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function withTimeout(timeoutMs, run) {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await run(controller.signal);
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+/** True when the Google voice key is present, so the router can decide
+ *  whether camino 1 is even reachable before attempting a round-trip. */
+export async function googleVoiceReady(apiKeyOverride) {
+    const key = await readSpeechKey(apiKeyOverride);
+    return typeof key === 'string' && key.length > 0;
+}
+/**
+ * Transcribe audio with Google Cloud Speech-to-Text. Throws on missing key,
+ * transport error, non-2xx, or empty result so the caller can fall back.
+ */
+export async function googleTranscribe(req, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const key = await readSpeechKey(opts.apiKeyOverride);
+    if (!key)
+        throw new Error('no_key');
+    const languageCode = normaliseSpanishLocale(req.languageHint);
+    const isSpanish = /^es-/i.test(languageCode);
+    const body = {
+        config: {
+            encoding: sttEncoding(req.format),
+            languageCode,
+            enableAutomaticPunctuation: true,
+            /* Spanish gets the long enhanced model: better with accent + the
+             * slower, less articulated speech this audience often produces. */
+            ...(isSpanish ? { model: 'latest_long', useEnhanced: true } : {}),
+        },
+        audio: { content: req.audio.toString('base64') },
+    };
+    const started = Date.now();
+    const j = await withTimeout(opts.timeoutMs ?? 15000, async (signal) => {
+        const r = await fetchImpl(STT_ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-goog-api-key': key },
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (!r.ok) {
+            let detail = '';
+            try {
+                detail = (await r.text()).slice(0, 160).replace(/\s+/g, ' ');
+            }
+            catch { /* ignore */ }
+            throw new Error('stt http ' + r.status + (detail ? ' ' + detail : ''));
+        }
+        return await r.json();
+    });
+    const top = j.results?.[0]?.alternatives?.[0];
+    const text = (top?.transcript ?? '').trim();
+    if (!text)
+        throw new Error('empty_transcript');
+    const result = {
+        text,
+        latency_ms: Date.now() - started,
+        provider: 'google',
+        model: isSpanish ? 'latest_long' : undefined,
+    };
+    if (typeof top?.confidence === 'number')
+        result.confidence = top.confidence;
+    if (j.results?.[0]?.languageCode)
+        result.language = j.results[0].languageCode;
+    return result;
+}
+/**
+ * Synthesise speech with Google Cloud Text-to-Speech. Throws on missing key,
+ * transport error, non-2xx, or empty audio so the caller can fall back to
+ * the browser's speechSynthesis.
+ */
+export async function googleSynthesize(req, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const key = await readSpeechKey(opts.apiKeyOverride);
+    if (!key)
+        throw new Error('no_key');
+    const text = (req.text ?? '').trim();
+    if (!text)
+        throw new Error('empty_text');
+    const voice = req.voice && req.voice.trim().length > 0 ? req.voice.trim() : voiceForLocale(req.language);
+    const languageCode = languageFromVoice(voice);
+    const format = req.format ?? 'mp3';
+    const body = {
+        input: { text },
+        voice: { languageCode, name: voice },
+        audioConfig: { audioEncoding: ttsEncoding(format), speakingRate: clampSpeed(req.speed) },
+    };
+    const started = Date.now();
+    const j = await withTimeout(opts.timeoutMs ?? 15000, async (signal) => {
+        const r = await fetchImpl(TTS_ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-goog-api-key': key },
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (!r.ok) {
+            let detail = '';
+            try {
+                detail = (await r.text()).slice(0, 160).replace(/\s+/g, ' ');
+            }
+            catch { /* ignore */ }
+            throw new Error('tts http ' + r.status + (detail ? ' ' + detail : ''));
+        }
+        return await r.json();
+    });
+    const b64 = j.audioContent ?? '';
+    if (!b64)
+        throw new Error('empty_audio');
+    return {
+        audio: Buffer.from(b64, 'base64'),
+        format,
+        voice,
+        latency_ms: Date.now() - started,
+        provider: 'google',
+    };
+}

package/server-dist/voice/router.js

@@ -0,0 +1,54 @@
+/**
+ * Voice router -- the single server-side surface the HTTP routes call to
+ * hear and speak (v0.6.0). It reads the voice config, and when camino 1 is
+ * enabled and reachable, delegates to the Google provider. On a clean miss
+ * (disabled / no key) or a hard failure (transport, timeout, empty result)
+ * it returns a structured miss so the CLIENT falls back to the browser.
+ *
+ * The router never throws for an expected miss: the caller turns a miss into
+ * a 'use the browser' signal, never a 500.
+ *
+ * ASCII-only.
+ */
+import { readVoiceConfig } from './config.js';
+import { googleTranscribe, googleSynthesize, googleVoiceReady } from './google.js';
+export async function transcribe(req, opts = {}) {
+    const cfg = await readVoiceConfig();
+    if (!cfg.enabled)
+        return { ok: false, reason: 'disabled' };
+    if (!(await googleVoiceReady(opts.apiKeyOverride)))
+        return { ok: false, reason: 'no_key' };
+    try {
+        const result = await googleTranscribe({ ...req, languageHint: req.languageHint ?? cfg.language }, { fetchImpl: opts.fetchImpl, apiKeyOverride: opts.apiKeyOverride });
+        return { ok: true, result };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message.slice(0, 160) : String(err);
+        if (detail === 'no_key')
+            return { ok: false, reason: 'no_key' };
+        return { ok: false, reason: 'error', detail };
+    }
+}
+export async function synthesize(req, opts = {}) {
+    const cfg = await readVoiceConfig();
+    if (!cfg.enabled)
+        return { ok: false, reason: 'disabled' };
+    if (!(await googleVoiceReady(opts.apiKeyOverride)))
+        return { ok: false, reason: 'no_key' };
+    try {
+        const result = await googleSynthesize({
+            text: req.text,
+            language: req.language ?? cfg.language,
+            voice: req.voice ?? (cfg.voice || undefined),
+            speed: req.speed ?? cfg.speed,
+            format: req.format ?? cfg.format,
+        }, { fetchImpl: opts.fetchImpl, apiKeyOverride: opts.apiKeyOverride });
+        return { ok: true, result };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message.slice(0, 160) : String(err);
+        if (detail === 'no_key')
+            return { ok: false, reason: 'no_key' };
+        return { ok: false, reason: 'error', detail };
+    }
+}

package/server-dist/voice/types.js

@@ -0,0 +1,17 @@
+/**
+ * Voice subsystem types (v0.6.0 -- camino 1 for hearing + speaking).
+ *
+ * Ported from the Yujin-Forge voice subsystem (src/voice) and trimmed to
+ * Yuemail's single-user, server-side, BYOK shape. Google Cloud is camino 1
+ * for both directions; the browser (Web Speech API) stays as camino 2, the
+ * safety net resolved on the client when the server path is unavailable.
+ *
+ *   STT (hearing): browser-captured audio bytes -> Google Speech-to-Text.
+ *   TTS (speaking): Yuemail text -> Google Text-to-Speech audio bytes.
+ *
+ * The Google API key lives in the SAME encrypted vault as the mail
+ * credentials (slot 'speech.google'); it never reaches the browser.
+ *
+ * ASCII-only.
+ */
+export {};