@7ots/cli 0.1.0

package/server/contact.mjs

@@ -0,0 +1,151 @@
+/**
+ * Contactabilidad: Apumail (correo/tickets) y Apuchat (derivar a una persona).
+ *
+ * Todo lo sensible se queda aquí: API keys, buzón de destino, identidad del notificador
+ * y el enlace de operador de la videollamada. Al navegador solo vuelve lo mínimo.
+ *
+ * Idiomas: los errores llevan clave (se traducen al idioma del visitante al responder); el correo
+ * y el DM al equipo salen en el idioma del servidor (LOCALE, ver server/i18n.mjs).
+ */
+
+import { openHandoff } from './apuchat-relay.mjs';
+import { i18nError, teamT } from './i18n.mjs';
+
+const HUB = (env) => (env.APUCHAT_HUB || 'https://apuchat.com').replace(/\/$/, '');
+
+// ───────────────────────────── Apumail ─────────────────────────────
+
+/**
+ * Envía el ticket como un correo normal desde un buzón de apumail.com que es tuyo.
+ * (apumail no tiene endpoint de "tickets": se usa la API de envío del buzón.)
+ *
+ *   POST {APUMAIL_API}/api/v1/inbox/{APUMAIL_INBOX}/send
+ *   Authorization: Bearer {APUMAIL_INBOX_TOKEN}      (token del buzón o PAT acct_… de la cuenta dueña)
+ *   { to, subject (≤256), text (≤100k), reply_to }   → { ok, provider_id, message_id }
+ *
+ * El remitente siempre es el propio buzón. Usa un buzón permanente o de dominio propio:
+ * los buzones gratis caducan a las 24 h sin actividad y solo envían 5 destinatarios/día.
+ */
+export async function sendApumail(body, env = process.env) {
+  if (!env.APUMAIL_INBOX || !env.APUMAIL_INBOX_TOKEN || !env.APUMAIL_TO) {
+    throw i18nError(501, 'server.contact.mailNotConfigured');
+  }
+  const subject = clip(body.subject, 160);
+  const message = clip(body.message, 5000);
+  const replyTo = clip(body.replyTo, 200);
+  // apumail no valida reply_to: se valida aquí.
+  if (!subject || !message || !/^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/.test(replyTo)) throw i18nError(400, 'server.contact.mailMissing');
+
+  const api = (env.APUMAIL_API || 'https://api.apumail.com').replace(/\/$/, '');
+  const res = await fetch(`${api}/api/v1/inbox/${encodeURIComponent(env.APUMAIL_INBOX.toLowerCase())}/send`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${env.APUMAIL_INBOX_TOKEN}` },
+    body: JSON.stringify(buildApumailPayload({ ...body, subject, message, replyTo, to: env.APUMAIL_TO })),
+    signal: AbortSignal.timeout(15000),
+  });
+  const out = await res.json().catch(() => ({}));
+  if (res.status === 429) {
+    const wait = out.retry_after_seconds || Number(res.headers.get('Retry-After')) || null;
+    throw wait ? i18nError(429, 'server.contact.mailRateLimitedWait', { minutes: Math.ceil(wait / 60) }) : i18nError(429, 'server.contact.mailRateLimited');
+  }
+  if (!res.ok) {
+    console.error('[7ots] apumail', res.status, out.code || '', out.error || '');
+    throw i18nError(502, 'server.contact.mailFailed');
+  }
+  return { ok: true, ticketId: out.message_id || out.provider_id || null };
+}
+
+/** Cuerpo para /inbox/:address/send. Solo texto: el contenido viene del usuario y del LLM. */
+export function buildApumailPayload({ to, subject, message, replyTo, category, user, page, transcript = [] }) {
+  const t = teamT(); // lo lee el equipo: idioma del servidor
+  const cat = category || t('server.contact.mail.otherCategory');
+  const convo = transcript
+    .slice(-40)
+    .map((m) => `${m.from === 'user' ? t('server.contact.mail.user') : m.from === 'agent' ? t('server.contact.mail.agent') : m.name || t('server.contact.mail.team')}: ${clip(m.text, 1000)}`)
+    .join('\n');
+  const text = [
+    message,
+    '',
+    t('server.contact.mail.category', { category: cat }),
+    t('server.contact.mail.page', { url: clip(page?.url, 500) }),
+    user ? t('server.contact.mail.userLine', { user: clip(JSON.stringify(user), 500) }) : t('server.contact.mail.anonymous'),
+    '',
+    convo ? `${t('server.contact.mail.conversation')}\n${convo}` : '',
+  ].join('\n');
+  return {
+    to, // fijo en el servidor (APUMAIL_TO): el LLM nunca elige el destinatario
+    subject: clip(`[${cat}] ${subject}`, 256),
+    text: text.slice(0, 100000),
+    reply_to: replyTo, // responder al correo llega directamente al visitante
+  };
+}
+
+// ───────────────────────────── Apuchat ─────────────────────────────
+
+/**
+ * Crea una videollamada efímera en el hub, avisa al operador por DM y abre el relé
+ * (server/apuchat-relay.mjs) con la identidad "agent" de la llamada.
+ *
+ *   POST {hub}/api/video-call  {transcribe}           → {channel_id, channel_token, call_url, call_url_public, agent, phone}
+ *   POST {hub}/api/dm  x-identity-key  {to, text}      (handle SIN "@", ≤ 4096; 202 aunque el handle no exista)
+ *
+ * El operador entra con `call_url` (lleva claves y PIN: solo viaja en el DM).
+ * Al navegador vuelven un id/token opacos del relé y `call_url_public` (sin secretos: quien
+ * lo abre "llama a la puerta" y alguien de dentro le deja pasar).
+ *
+ * Ojo: el hub limita /api/video-call a 15/min por IP, y todas las peticiones salen de este
+ * servidor, así que ese límite es compartido por todos los visitantes.
+ */
+export async function startApuchat(body, env = process.env) {
+  const hub = HUB(env);
+  const res = await fetch(`${hub}/api/video-call`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    // Solo `false` explícito desactiva la transcripción en el hub.
+    body: JSON.stringify({ transcribe: env.APUCHAT_TRANSCRIBE === 'true' }),
+    signal: AbortSignal.timeout(15000),
+  });
+  if (res.status === 429) throw i18nError(429, 'server.contact.chatBusy');
+  if (!res.ok) throw i18nError(502, 'server.contact.chatHubError', { status: res.status });
+  const call = await res.json();
+
+  const relay = await openHandoff({
+    hub,
+    channel_id: call.channel_id,
+    channel_token: call.channel_token,
+    identity_key: call.agent?.identity_key,
+  });
+
+  let operatorNotified = false;
+  const operator = String(env.APUCHAT_OPERATOR_HANDLE || '').trim().replace(/^@/, '').toLowerCase();
+  if (env.APUCHAT_NOTIFIER_IDENTITY_KEY && operator) {
+    const t = teamT(); // aviso para el operador: idioma del servidor
+    const head = [
+      t('server.contact.dm.head', { urgency: clip(body.urgency, 10) || t('server.contact.dm.normal'), reason: clip(body.reason, 200) }),
+      body.user?.name ? t('server.contact.dm.user', { name: clip(body.user.name, 80) }) : t('server.contact.dm.visitor'),
+      t('server.contact.dm.page', { url: clip(body.page?.url, 300) }),
+    ].join('\n');
+    const link = t('server.contact.dm.link', { url: call.call_url });
+    // El enlace va al final y nunca se recorta: se recorta el resumen.
+    const room = 4096 - head.length - link.length - 20;
+    const text = `${head}\n\n${t('server.contact.dm.summary', { summary: clip(body.summary, Math.max(0, room)) })}\n\n${link}`;
+    const dm = await fetch(`${hub}/api/dm`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-identity-key': env.APUCHAT_NOTIFIER_IDENTITY_KEY },
+      body: JSON.stringify({ to: operator, text }),
+      signal: AbortSignal.timeout(15000),
+    }).catch(() => null);
+    operatorNotified = !!dm && dm.status < 300;
+    if (!operatorNotified) console.error('[7ots] apuchat: el DM al operador falló', dm?.status ?? 'sin respuesta');
+  } else {
+    console.warn('[7ots] apuchat: falta APUCHAT_NOTIFIER_IDENTITY_KEY/APUCHAT_OPERATOR_HANDLE; nadie recibe aviso de la derivación.');
+  }
+
+  return { ...relay, call_url_public: call.call_url_public || null, operatorNotified };
+}
+
+// ───────────────────────────── helpers ─────────────────────────────
+
+function clip(s, n) {
+  return String(s ?? '').slice(0, n).trim();
+}

package/server/demo.mjs

@@ -0,0 +1,154 @@
+/**
+ * Backend de DEMOSTRACIÓN del sitio anfitrión ("Nimbus", un SaaS ficticio).
+ * No es parte del framework: simula lo que ya tendría tu sitio para probar
+ * la integración de extremo a extremo:
+ *
+ *   POST /api/demo/login     {email}        → { token }  JWT HS256 de 1 h (sin contraseña: es demo)
+ *   GET  /api/demo/balance   Bearer JWT     → saldo del usuario (acción personalizada del ejemplo)
+ *   POST /mcp                Bearer JWT     → servidor MCP (Streamable HTTP, JSON) con tools de la cuenta
+ *
+ * En producción, tu backend verifica el JWT con su propia clave/JWKS; aquí el secreto
+ * es DEMO_JWT_SECRET o uno aleatorio por arranque.
+ * Los textos (errores, títulos de las tools MCP) salen en el idioma de Accept-Language.
+ */
+
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { reqT } from './i18n.mjs';
+
+const SECRET = process.env.DEMO_JWT_SECRET || randomBytes(32).toString('hex');
+const sessions = new Set();
+const accounts = new Map(); // email → { plan, balance, orders }
+
+const b64u = (b) => Buffer.from(b).toString('base64url');
+
+export function signJwt(payload, ttlSec = 3600) {
+  const now = Math.floor(Date.now() / 1000);
+  const head = b64u(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const body = b64u(JSON.stringify({ iat: now, exp: now + ttlSec, ...payload }));
+  const sig = createHmac('sha256', SECRET).update(`${head}.${body}`).digest('base64url');
+  return `${head}.${body}.${sig}`;
+}
+
+export function verifyJwt(token) {
+  const [head, body, sig] = String(token || '').split('.');
+  if (!sig) return null;
+  const expected = createHmac('sha256', SECRET).update(`${head}.${body}`).digest();
+  const got = Buffer.from(sig, 'base64url');
+  if (got.length !== expected.length || !timingSafeEqual(got, expected)) return null;
+  const claims = JSON.parse(Buffer.from(body, 'base64url').toString());
+  if (claims.exp && claims.exp * 1000 < Date.now()) return null;
+  return claims;
+}
+
+function account(email) {
+  if (!accounts.has(email)) {
+    accounts.set(email, {
+      plan: 'Starter',
+      balance: 42.5,
+      orders: [
+        { id: 'NB-1042', fecha: '2026-09-02', total: 19, estado: 'pagado' },
+        { id: 'NB-1077', fecha: '2026-09-21', total: 49, estado: 'pendiente' },
+      ],
+    });
+  }
+  return accounts.get(email);
+}
+
+const bearer = (req) => verifyJwt((req.headers.authorization || '').replace(/^Bearer\s+/i, ''));
+
+/** @returns {boolean} true si la ruta era de la demo */
+export async function handleDemo(req, res, url, { readJson, send }) {
+  const t = reqT(req);
+  if (url.pathname === '/api/demo/login' && req.method === 'POST') {
+    const { email } = await readJson(req, 4096);
+    const clean = String(email || '').trim().toLowerCase();
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/.test(clean)) return send(res, 400, { error: t('server.demo.badEmail') }), true;
+    const name = clean.split('@')[0].replace(/[._-]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+    return send(res, 200, { token: signJwt({ sub: clean, email: clean, name, plan: account(clean).plan }) }), true;
+  }
+
+  if (url.pathname === '/api/demo/balance' && req.method === 'GET') {
+    const user = bearer(req);
+    if (!user) return send(res, 401, { error: t('server.demo.unauthorized') }), true;
+    const a = account(user.email);
+    return send(res, 200, { email: user.email, plan: a.plan, saldo: a.balance, moneda: 'EUR', proximaFactura: '2026-10-01' }), true;
+  }
+
+  if (url.pathname === '/mcp') {
+    await handleMcp(req, res, { readJson, send, t });
+    return true;
+  }
+  return false;
+}
+
+// ───────────────────────────── MCP de demo ─────────────────────────────
+
+const mcpTools = (t) => [
+  {
+    name: 'listar_pedidos',
+    title: t('server.demo.tools.listTitle'),
+    description: t('server.demo.tools.listDescription'),
+    inputSchema: { type: 'object', properties: { estado: { type: 'string', enum: ['pagado', 'pendiente', 'todos'] } } },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: 'cambiar_plan',
+    title: t('server.demo.tools.planTitle'),
+    description: t('server.demo.tools.planDescription'),
+    inputSchema: { type: 'object', properties: { plan: { type: 'string', enum: ['Starter', 'Pro', 'Business'] } }, required: ['plan'] },
+    annotations: { readOnlyHint: false, destructiveHint: false },
+  },
+];
+
+async function handleMcp(req, res, { readJson, send, t }) {
+  if (req.method === 'DELETE') {
+    sessions.delete(req.headers['mcp-session-id']);
+    return send(res, 204);
+  }
+  if (req.method !== 'POST') return send(res, 405, { error: t('server.demo.postOnly') });
+  const user = bearer(req);
+  if (!user) {
+    res.setHeader('WWW-Authenticate', 'Bearer');
+    return send(res, 401, { error: t('server.demo.unauthorized') });
+  }
+  const msg = await readJson(req, 64 * 1024);
+  const sid = req.headers['mcp-session-id'];
+  // Como un servidor real: una sesión desconocida (p. ej. tras reiniciar) → 404 y el cliente re-inicializa.
+  if (msg.method !== 'initialize' && sid && !sessions.has(sid)) return send(res, 404, { error: t('server.demo.unknownSession') });
+  const reply = (result) => send(res, 200, { jsonrpc: '2.0', id: msg.id, result });
+  const fail = (code, message) => send(res, 200, { jsonrpc: '2.0', id: msg.id, error: { code, message } });
+
+  switch (msg.method) {
+    case 'initialize': {
+      const sid = randomUUID();
+      sessions.add(sid);
+      res.setHeader('Mcp-Session-Id', sid);
+      return reply({
+        protocolVersion: msg.params?.protocolVersion || '2025-06-18',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'nimbus-demo-mcp', version: '1.0.0' },
+      });
+    }
+    case 'notifications/initialized':
+      return send(res, 202);
+    case 'tools/list':
+      return reply({ tools: mcpTools(t) });
+    case 'tools/call': {
+      const a = account(user.email);
+      const { name, arguments: args = {} } = msg.params || {};
+      if (name === 'listar_pedidos') {
+        const list = !args.estado || args.estado === 'todos' ? a.orders : a.orders.filter((o) => o.estado === args.estado);
+        return reply({ content: [{ type: 'text', text: JSON.stringify(list) }], structuredContent: { pedidos: list } });
+      }
+      if (name === 'cambiar_plan') {
+        a.plan = args.plan;
+        return reply({ content: [{ type: 'text', text: t('server.demo.planChanged', { plan: args.plan }) }], structuredContent: { plan: a.plan } });
+      }
+      return reply({ content: [{ type: 'text', text: t('server.demo.unknownTool', { name }) }], isError: true });
+    }
+    case 'ping':
+      return reply({});
+    default:
+      return fail(-32601, t('server.demo.unsupported', { method: msg.method }));
+  }
+}

package/server/i18n.mjs

@@ -0,0 +1,54 @@
+/**
+ * i18n del proxy: qué idioma usar en cada respuesta.
+ *
+ *   - Visitante y backoffice → la cabecera Accept-Language de la petición (el widget manda su
+ *     idioma y el backoffice el que tenga elegido). Sin cabecera: español.
+ *   - Equipo (correo a APUMAIL_TO, DM al operador, avisos del relé) y consola → idioma del
+ *     servidor: LOCALE (backoffice o entorno); si no hay, el idioma de la identidad; si no, español.
+ *
+ * Los errores que salen de módulos sin acceso a la petición se crean con `i18nError()`: llevan
+ * la clave y se traducen al responder (server.mjs), así el log sigue en español.
+ */
+
+import { resolveLocale, translator } from '../src/i18n/index.js';
+import '../src/i18n/messages/server.js';
+import { getIdentity } from './identity.mjs';
+
+/** Traductor fijo en español (mensajes de Error y registros). */
+export const tEs = translator('es');
+
+/** Idioma pedido por el cliente (Accept-Language). */
+export function requestLocale(req) {
+  return resolveLocale(req?.headers?.['accept-language']);
+}
+
+/** Traductor para responder a esta petición. */
+export function reqT(req) {
+  return translator(requestLocale(req));
+}
+
+/** Idioma del servidor: LOCALE → idioma de la identidad → español. Se lee en cada uso (sin reinicio). */
+export function serverLocale() {
+  let lang;
+  try {
+    lang = getIdentity().language;
+  } catch {
+    /* sin identidad legible: se queda el de LOCALE o español */
+  }
+  return resolveLocale(process.env.LOCALE, lang);
+}
+
+/** Traductor para lo que lee el equipo (correos, avisos) y la consola. */
+export function teamT() {
+  return translator(serverLocale());
+}
+
+/** Error HTTP con texto traducible: `message` en español y la clave en `i18n`. */
+export function i18nError(status, key, vars) {
+  return Object.assign(new Error(tEs(key, vars)), { status, i18n: { key, vars } });
+}
+
+/** Texto de un error en el idioma de `t` (si trae clave) o su mensaje tal cual. */
+export function errorText(err, t) {
+  return err?.i18n ? t(err.i18n.key, err.i18n.vars) : String(err?.message || err);
+}

package/server/identity.mjs

@@ -0,0 +1,108 @@
+/**
+ * Identidad del agente: quién es, cómo se ve, cómo suena y cómo se le contacta.
+ *
+ * Una sola ficha declarativa que usan todas las piezas de 7ots:
+ *   - el widget web (nombre, colores, avatar 3D/2D, voz),
+ *   - los canales (persona en correo/chat/llamada, avatar de meet, firma),
+ *   - el TTS del proxy (proveedor, voz y estilo),
+ *   - la tarjeta pública (GET /api/agent/identity, vCard, /.well-known/7ots-agent.json).
+ *
+ * Orden de carga (lo de la derecha gana):  valores por defecto ← variables de entorno ← data/identity.json
+ * El backoffice escribe data/identity.json; IDENTITY_FILE cambia la ruta.
+ *
+ * La identidad NUNCA contiene secretos: las claves de apumail/apuchat/TTS siguen en el entorno.
+ * Aun así, publicIdentity() construye la tarjeta con una lista blanca de campos.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineIdentity } from '../src/identity/schema.js';
+
+export * from '../src/identity/schema.js';
+export * from '../src/identity/random.js';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** Identidad a partir de las variables de entorno de siempre (AGENT_*, APUCHAT_AGENT_*, TTS). */
+export function identityFromEnv(env = process.env) {
+  const provider = (env.TTS_PROVIDER || '').toLowerCase();
+  return defineIdentity({
+    name: env.AGENT_NAME || undefined,
+    role: env.AGENT_ROLE || undefined,
+    language: env.AGENT_LANG || undefined,
+    personality: { instructions: env.AGENT_INSTRUCTIONS || '' },
+    look: { meetAvatar: env.APUCHAT_AGENT_AVATAR || undefined, meetScene: env.APUCHAT_AGENT_SCENE || '' },
+    voice: {
+      voiceId:
+        {
+          apuchat: env.APUCHAT_VOICE_ID,
+          elevenlabs: env.ELEVENLABS_VOICE_ID,
+          grok: env.XAI_TTS_VOICE,
+          fish: env.FISH_VOICE_ID,
+          openai: env.OPENAI_TTS_VOICE,
+        }[provider] || '',
+    },
+    contact: { site: env.AGENT_SITE_URL || '', email: env.APUMAIL_AGENT_INBOX || '' },
+  });
+}
+
+// ───────────────────────────── almacén en disco ─────────────────────────────
+
+let current = null;
+const listeners = new Set();
+
+export function identityFile(env = process.env) {
+  return resolve(ROOT, env.IDENTITY_FILE || join('data', 'identity.json'));
+}
+
+/** Identidad vigente (entorno + fichero). Se cachea; setIdentity() la actualiza en caliente. */
+export function getIdentity() {
+  if (current) return current;
+  const base = identityFromEnv();
+  let file = {};
+  const path = identityFile();
+  if (existsSync(path)) {
+    try {
+      file = JSON.parse(readFileSync(path, 'utf8'));
+    } catch (e) {
+      console.warn('[7ots] identidad: no se pudo leer', path, e.message);
+    }
+  }
+  current = defineIdentity(file, base);
+  return current;
+}
+
+/**
+ * Mezcla un cambio (parcial o completo) con la identidad vigente, lo guarda en
+ * data/identity.json y lo aplica ya (los canales y el TTS leen siempre la vigente).
+ */
+export function setIdentity(patch) {
+  const next = defineIdentity(patch, getIdentity());
+  const path = identityFile();
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(next, null, 2));
+  renameSync(tmp, path); // escritura atómica
+  current = next;
+  for (const fn of listeners) fn(next);
+  return next;
+}
+
+/** Usa esta identidad en memoria (SDK sin fichero). */
+export function useIdentity(identity) {
+  current = Object.defineProperty(defineIdentity(identity), '__custom', { value: true });
+  for (const fn of listeners) fn(current);
+  return current;
+}
+
+/** ¿Hay identidad propia (fichero o AGENT_NAME)? Si no, el proxy no toca el prompt del widget. */
+export function identityConfigured(env = process.env) {
+  return !!current?.__custom || existsSync(identityFile(env)) || !!env.AGENT_NAME;
+}
+
+export function onIdentityChange(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+