talo-hub 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talo Partner Hub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# talo-hub
+
+**Cobrá con transferencias bancarias en Argentina, con acreditación y conciliación automáticas.** Desde la terminal, tu código o tu agente de IA, con [Talo Pay](https://talo.com.ar).
+
+Cada cobro tiene su propio **CVU y alias**. Tu cliente transfiere desde cualquier banco o billetera, Talo lo acredita y vos sabés al instante qué pedido se pagó: sin comprobantes, sin revisar el home banking y sin conciliar a mano.
+
+```bash
+npx talo-hub login                              # conectá tu cuenta Talo (sandbox, sin plata real)
+npx talo-hub payments create --amount 15000     # → CVU y alias para que te transfieran
+npx talo-hub sandbox pay <payment_id>           # simulá la transferencia del cliente
+npx talo-hub events listen                      # → payment.paid (muestra los últimos y espera los nuevos)
+```
+
+Sin instalar nada: alcanza con Node 20 o más nuevo. Documentación: **https://talopartnerhub.vercel.app/docs**
+
+## Por qué talo-hub
+
+- **Un CVU por cobro:** cada pago se identifica solo. Se acabó el "mandame el comprobante".
+- **Confirmación automática:** te enterás cuando la plata entra, por terminal, webhook firmado o tu agente.
+- **Sandbox real:** simulás transferencias exactas, de menos (UNDERPAID) o de más (OVERPAID) y probás todo el flujo sin mover plata.
+- **Hecho para agentes de IA:** servidor MCP con OAuth, skills listas y docs en Markdown. Tu agente integra, prueba y lleva a producción.
+- **Seguro:** keys separadas para sandbox y producción, con permisos `read`, `charge` (cobra, no reembolsa) o `full`.
+
+## Para agentes de IA
+
+Conectá Claude Code, Cursor o Claude Desktop a tu cuenta Talo. Con OAuth, la key nunca pasa por el chat:
+
+```bash
+claude mcp add --transport http talo https://talopartnerhub.vercel.app/api/mcp
+# después, en Claude Code: /mcp → talo → Authenticate
+```
+
+```bash
+npx talo-hub mcp --client cursor     # o --client desktop; --with-key para usar tu key
+npx talo-hub skills install          # skills de Talo en .claude/skills
+```
+
+El agente puede crear cobros, simular transferencias, registrar y probar su webhook, correr el checklist de producción (`check_go_live`) y leer la documentación (`read_docs`).
+
+### Instructions for AI agents
+
+- Purpose: accept ARS bank-transfer payments in Argentina on the user's Talo Pay account. Each payment returns a `cvu` and `alias`; status goes `PENDING` → `SUCCESS` (or `UNDERPAID` / `OVERPAID` / `EXPIRED`).
+- Connect: MCP at `https://talopartnerhub.vercel.app/api/mcp` (OAuth), or this CLI after the user runs `npx talo-hub login`. A person must authorize Talo once per environment; everything else you can do.
+- Keys: `tph_test_…` sandbox (test money: test freely), `tph_live_…` production (real money: confirm refunds and amount changes with the user). Scopes `read` < `charge` < `full`; give servers `charge`. Store project keys in the server's env (`TALO_HUB_API_KEY`), never in code or chat; exporting it in your own shell replaces the login key. `login --production` does not make production the default: pass `--production` or run `use production`.
+- Machine-readable: every command takes `--json` (JSON on stdout, human messages on stderr) and exits non-zero on failure, `doctor` and `webhooks test` included. Errors with `--json`: `{"error":{"code","message","status"}}`, with stable codes such as `not_logged_in`, `invalid_amount`, `invalid_hub`, `env_key_mismatch`, `insufficient_scope` (plus `key_scope` and `required_scope`), `talo_reconnect_required`, `network_error`, `invalid_response`. `status` is the hub's HTTP status, or null when the CLI found the error itself or couldn't reach the hub. `events listen --json` prints one event per line; the last few existing events come first with `"replayed": true`. Docs as Markdown: https://talopartnerhub.vercel.app/llms.txt, `/docs/<page>.md`, OpenAPI at `/openapi.json`.
+- Amounts: pass `--amount 15000` or `15000.50`. Don't use thousands separators unquoted: PowerShell turns `15.000,50` into `15,50`.
+- Payments always include `paid` and `refunded` as numbers (0 when none) and `refunds: [{ id, status, type, amount, currency, created_at }]`. Filter events with `events list --payment <id>`.
+- Test plan: `payments create --amount 15000` → `sandbox pay <id> --amount 14999` (UNDERPAID, don't fulfil) → `sandbox pay <id> --amount 1` (SUCCESS) → `webhooks add <https url>` → `webhooks test <id>` → `doctor` until it exits 0.
+
+## Comandos
+
+| Comando | |
+|---|---|
+| `login [--production]` | Conecta tu cuenta Talo desde el navegador |
+| `status` | Cuenta, estado en Talo y permisos de la key |
+| `doctor` | Checklist para pasar a producción, con lo que falta |
+| `payments create --amount <ARS> [--external-id <id>] [--motive <texto>]` | Crea un cobro y muestra CVU y alias |
+| `payments get <id>` | Estado de un cobro |
+| `payments list [--from AAAA-MM-DD] [--to AAAA-MM-DD]` | Cobros de un período (30 días por defecto) |
+| `payments refund <id> [--amount <ARS>]` | Reembolso total o parcial |
+| `sandbox pay <id> [--amount <ARS>]` | Simula la transferencia del cliente |
+| `balance`, `transactions [--from] [--to] [--limit <n>] [--cursor]` | Saldo y movimientos |
+| `events list [--payment <id>] [--type <tipo>] [--after <id>] [--limit <n>]` | Eventos recientes, filtrables por cobro o tipo |
+| `events listen [--forward-to <url\|puerto>]` | Recibe eventos en vivo y los reenvía a localhost sin túneles (sin firma, con `talo-hub-forwarded: 1`: solo para desarrollo) |
+| `webhooks list \| add <url> \| remove <id> \| test <id>` | Webhooks firmados con HMAC-SHA256 |
+| `keys list \| create [--name] [--scope read\|charge\|full] \| revoke <id>` | Keys para tus proyectos (`charge` por defecto) |
+| `mcp [--client claude\|cursor\|desktop] [--with-key]` | Configuración del MCP para tu agente |
+| `skills install [--global]` | Instala las skills de Talo |
+| `use <sandbox\|production>` | Entorno activo de los próximos comandos |
+| `logout [--production \| --all]` | Revoca la key en el hub y la borra de esta máquina |
+
+Opciones: `--sandbox`, `--production`, `--json`, `--version`, `--hub <url>`.
+
+Montos: `15000` o `15000.50`. También entiende `15000,50` y `15.000,50`, pero en PowerShell escribilos entre comillas (`"15.000,50"`): sin comillas, PowerShell los convierte en otro número antes de que lleguen al CLI. Fechas: `AAAA-MM-DD` o ISO 8601, en hora de Argentina.
+
+## De sandbox a producción
+
+```bash
+npx talo-hub doctor                                         # sandbox listo
+npx talo-hub login --production
+npx talo-hub keys create --production --name mi-tienda --scope charge
+npx talo-hub webhooks add https://tu-sitio.com/api/webhooks/talo --production
+npx talo-hub webhooks test <id> --production
+npx talo-hub doctor --production
+```
+
+## Seguridad
+
+- `login` muestra un código para confirmar en el navegador. La key queda en `~/.config/talo-hub/config.json` (en Windows, `%APPDATA%\talo-hub`), legible solo por tu usuario.
+- `TALO_HUB_API_KEY` usa una key sin login, para CI y agentes. Si no coincide con `--sandbox` o `--production`, el CLI frena en vez de operar en el entorno equivocado.
+- Cada key guardada recuerda el hub que la emitió y no se manda a ningún otro.
+- `mcp` usa OAuth por defecto: tu key no queda en el historial de la terminal ni en archivos del proyecto.
+- Tus keys solo viajan por https (o a un hub en tu propia máquina, para desarrollo).
+
+## Links
+
+- Docs: https://talopartnerhub.vercel.app/docs
+- Para agentes: https://talopartnerhub.vercel.app/docs/agents · https://talopartnerhub.vercel.app/llms.txt
+- API: https://talopartnerhub.vercel.app/docs/api · OpenAPI: https://talopartnerhub.vercel.app/openapi.json
+- Dashboard: https://talopartnerhub.vercel.app/dashboard
+
+---
+
+talo-hub es parte de Talo Partner Hub, una integración de un partner de Talo Pay; no es un producto oficial de Talo. Los cobros los procesa Talo en tu cuenta.

package/dist/cli.js

@@ -0,0 +1,786 @@
+#!/usr/bin/env node
+// talo-hub: Talo Pay from the terminal, through the Talo Partner Hub.
+// Every command answers JSON with --json (human messages then go to stderr), errors included as
+// { error: { code, message, status } }, and exits non-zero on failure, so scripts and agents can
+// rely on it.
+import { spawn } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { configPath, environmentOfKey, loadConfig, requestedHub, resolveKey, saveConfig, DEFAULT_HUB, } from "./config.js";
+import { Hub, HubRequestError, networkReason } from "./hub.js";
+import { parseAmount, parseCount, parseDate, parseForwardUrl } from "./parse.js";
+const VERSION = createRequire(import.meta.url)("../package.json").version;
+/** How to tell people to run us again: through npx when that's how they ran us. */
+const CMD = process.env.npm_command === "exec" ? "npx talo-hub" : "talo-hub";
+const jsonMode = process.argv.some((arg) => /^--json(=|$)/.test(arg));
+const HELP = `talo-hub ${VERSION}: transferencias bancarias automáticas en Argentina con Talo Pay.
+
+Cuenta
+  login [--production]              Conecta tu cuenta Talo (sandbox por defecto)
+  logout [--production | --all]     Revoca y borra la key guardada
+  use <sandbox|production>          Elige el entorno de los próximos comandos
+  status                            Cuenta conectada, estado en Talo y permisos de la key
+  doctor                            Checklist para pasar a producción
+
+Cobros
+  payments create --amount <ARS> [--external-id <id>] [--motive <texto>]
+  payments get <payment_id>
+  payments list [--from AAAA-MM-DD] [--to AAAA-MM-DD]
+  payments refund <payment_id> [--amount <ARS>]   Sin --amount, reembolso total
+  sandbox pay <payment_id> [--amount <ARS>]       Simula la transferencia (sandbox)
+  balance
+  transactions [--from …] [--to …] [--limit <1-200>] [--cursor <next_cursor>]
+
+Eventos y webhooks
+  events list [--payment <id>] [--type <tipo>] [--after <id>] [--limit <1-200>]
+                                                 Sin --after, los más recientes
+  events listen [--forward-to <url|puerto>]      Muestra los últimos y escucha los nuevos
+                                                 (los reenviados no van firmados: solo para desarrollo)
+  webhooks list | add <url> | remove <id> | test <id>
+
+Keys y agentes
+  keys list | create [--name <nombre>] [--scope read|charge|full] | revoke <id>   (charge por defecto)
+  mcp [--client claude|cursor|desktop] [--with-key]   Configuración del MCP para tu agente
+  skills install [--global]                           Instala las skills de Talo en .claude/skills
+
+Montos: 15000 o 15000.50 (en PowerShell, con separador de miles, entre comillas: "15.000,50").
+Fechas: AAAA-MM-DD o ISO 8601; sin zona horaria, hora de Argentina.
+Opciones: --sandbox, --production, --json, --hub <url>, --version
+Variables: TALO_HUB_API_KEY (usa esa key en vez de la guardada), TALO_HUB_URL`;
+/** Prints the error (as JSON with --json, with a stable code) and exits 1. */
+function fail(message, code = "usage", extra = {}) {
+    const error = { code, message, ...extra, status: extra.status || null };
+    if (jsonMode)
+        console.log(JSON.stringify({ error }));
+    else
+        console.error(`✗ ${message}`);
+    process.exit(1);
+}
+/** A message for people: stdout normally, stderr with --json so stdout stays parseable. */
+function say(message = "") {
+    if (jsonMode)
+        console.error(message);
+    else
+        console.log(message);
+}
+function emit(value, human) {
+    if (jsonMode || !human)
+        console.log(JSON.stringify(value, null, 2));
+    else
+        human();
+}
+const GLOBAL_OPTIONS = ["sandbox", "production", "json", "hub", "help", "version"];
+function parseCommandLine() {
+    try {
+        return parseArgs({
+            allowPositionals: true,
+            options: {
+                sandbox: { type: "boolean" },
+                production: { type: "boolean" },
+                all: { type: "boolean" },
+                json: { type: "boolean" },
+                hub: { type: "string" },
+                amount: { type: "string" },
+                "external-id": { type: "string" },
+                motive: { type: "string" },
+                from: { type: "string" },
+                to: { type: "string" },
+                after: { type: "string" },
+                limit: { type: "string" },
+                cursor: { type: "string" },
+                payment: { type: "string" },
+                type: { type: "string" },
+                name: { type: "string" },
+                scope: { type: "string" },
+                "forward-to": { type: "string" },
+                client: { type: "string" },
+                "with-key": { type: "boolean" },
+                global: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+            },
+        });
+    }
+    catch (error) {
+        const { code, message } = error;
+        const option = message.match(/'(-[^' ]+)/)?.[1] ?? "la opción";
+        if (code === "ERR_PARSE_ARGS_UNKNOWN_OPTION")
+            return fail(`No existe la opción ${option}. Mirá ${CMD} --help`, "invalid_option");
+        if (/does not take an argument/.test(message))
+            return fail(`${option} no lleva valor.`, "invalid_option");
+        if (code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE") {
+            return fail(`A ${option} le falta el valor, o el valor empieza con "-": usá ${option}=valor.`, "invalid_option");
+        }
+        return fail(`${message.split("\n")[0].replace(/\.$/, "")}. Mirá ${CMD} --help`, "invalid_option");
+    }
+}
+const { values: flags, positionals } = parseCommandLine();
+/** The options each command takes besides the global ones; anything else is a mistake to report. */
+const COMMAND_OPTIONS = {
+    login: [],
+    logout: ["all"],
+    use: [],
+    status: [],
+    doctor: [],
+    "payments create": ["amount", "external-id", "motive"],
+    "payments get": [],
+    "payments list": ["from", "to"],
+    "payments refund": ["amount"],
+    "sandbox pay": ["amount"],
+    balance: [],
+    transactions: ["from", "to", "limit", "cursor"],
+    "events list": ["after", "limit", "payment", "type"],
+    "events listen": ["forward-to"],
+    webhooks: [],
+    keys: ["name", "scope"],
+    mcp: ["client", "with-key"],
+    skills: ["global"],
+};
+function checkOptions(command, sub) {
+    const key = COMMAND_OPTIONS[`${command} ${sub ?? "list"}`] ? `${command} ${sub ?? "list"}` : command;
+    const allowed = new Set([...GLOBAL_OPTIONS, ...(COMMAND_OPTIONS[key] ?? [])]);
+    const extra = Object.keys(flags).filter((option) => !allowed.has(option));
+    if (extra.length)
+        fail(`${extra.map((o) => `--${o}`).join(", ")} no aplica a "${key}". Mirá ${CMD} --help`, "invalid_option");
+}
+const money = new Intl.NumberFormat("es-AR", { style: "currency", currency: "ARS" });
+// Argentine time, 24 h: toLocaleString("es-AR") prints 12-hour times without a.m./p.m. on some ICUs.
+const AR_TIME = { timeZone: "America/Argentina/Buenos_Aires", hourCycle: "h23" };
+const dateTime = new Intl.DateTimeFormat("es-AR", { ...AR_TIME, dateStyle: "short", timeStyle: "short" });
+const timeOnly = new Intl.DateTimeFormat("es-AR", { ...AR_TIME, timeStyle: "medium" });
+function chosenEnvironment(config) {
+    if (flags.production && flags.sandbox)
+        fail("Elegí --sandbox o --production, no los dos.");
+    if (flags.production)
+        return "production";
+    if (flags.sandbox)
+        return "sandbox";
+    return config.current;
+}
+const loginHint = (environment) => `${CMD} login${environment === "production" ? " --production" : ""}`;
+function amountFlag(required) {
+    if (flags.amount === undefined) {
+        if (required)
+            fail("Falta --amount (en ARS).", "invalid_amount");
+        return undefined;
+    }
+    return parseAmount(flags.amount) ?? fail(`--amount no es un monto válido: "${flags.amount}". Usá 15000 o 15000.50.`, "invalid_amount");
+}
+function limitFlag(fallback) {
+    if (flags.limit === undefined)
+        return fallback;
+    return parseCount(flags.limit, 200) ?? fail(`--limit tiene que ser un número entero de 1 a 200 (recibimos "${flags.limit}").`, "invalid_limit");
+}
+function dateFlag(name) {
+    const raw = flags[name];
+    if (raw === undefined)
+        return undefined;
+    return parseDate(raw, name === "from" ? "start" : "end") ?? fail(`--${name}: usá AAAA-MM-DD (p. ej. 2026-10-28) o ISO 8601.`, "invalid_date");
+}
+/** Opens the URL without a shell, and never lets a missing opener crash the CLI. */
+function openBrowser(url) {
+    let command;
+    let args;
+    if (process.platform === "win32")
+        [command, args] = ["rundll32", ["url.dll,FileProtocolHandler", url]];
+    else if (process.platform === "darwin")
+        [command, args] = ["open", [url]];
+    else if (process.env.DISPLAY || process.env.WAYLAND_DISPLAY)
+        [command, args] = ["xdg-open", [url]];
+    else
+        return;
+    try {
+        const child = spawn(command, args, { stdio: "ignore", detached: true, windowsHide: true });
+        child.on("error", () => undefined);
+        child.unref();
+    }
+    catch {
+        // The URL is printed anyway.
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Runs a request, retrying network errors and 5xx with backoff; other errors go up. */
+async function resilient(task, onRetry) {
+    let wait = 2000;
+    for (;;) {
+        try {
+            return await task();
+        }
+        catch (error) {
+            if (!(error instanceof HubRequestError) || !error.transient)
+                throw error;
+            onRetry(error, wait);
+            await sleep(wait);
+            wait = Math.min(wait * 2, 30_000);
+        }
+    }
+}
+/** The hub answers in English for API clients; the CLI says the usual ones in Spanish. */
+const HUB_MESSAGES = {
+    unauthorized: "La key no es válida o fue revocada.",
+    insufficient_scope: "Esta key no tiene permiso para eso.",
+    sandbox_only: "Eso solo funciona con una key de sandbox (tph_test_…).",
+    talo_reconnect_required: "Talo ya no acepta la autorización de esta cuenta.",
+    payment_not_found: "No hay un cobro con ese ID en esta cuenta.",
+    invalid_amount: "El monto no es válido.",
+    invalid_url: "La URL del webhook no es válida: tiene que ser https.",
+    environment_disabled: "El hub todavía no está conectado a ese entorno de Talo.",
+    talo_partner_unsupported: "Talo todavía no habilita el saldo y los movimientos para integraciones de partner: consultalos en el panel de Talo.",
+};
+/** A hub error in words for this CLI: transient failures read the same whatever the hub said. */
+function hubMessage(error) {
+    if (error.code && HUB_MESSAGES[error.code])
+        return HUB_MESSAGES[error.code];
+    if (error.status === 0)
+        return error.message;
+    if (error.status >= 500)
+        return `El hub tuvo un error (HTTP ${error.status}).`;
+    return error.message;
+}
+function showPayment(payment) {
+    console.log(`${payment.id}  ${payment.status}`);
+    if (payment.amount !== undefined)
+        console.log(`  Monto:     ${money.format(payment.amount)}`);
+    if (payment.cvu)
+        console.log(`  CVU:       ${payment.cvu}`);
+    if (payment.alias)
+        console.log(`  Alias:     ${payment.alias}`);
+    if (payment.paid)
+        console.log(`  Pagado:    ${money.format(payment.paid)}`);
+    if (payment.refunded)
+        console.log(`  Reembolso: ${money.format(payment.refunded)}`);
+    if (payment.expires_at)
+        console.log(`  Vence:     ${dateTime.format(new Date(payment.expires_at))} (hora de Argentina)`);
+}
+/**
+ * Revokes a key on the hub that issued it, using the key itself. Best effort: says whether the key
+ * no longer works (revoked now, or already invalid), so the person finishes it in the dashboard
+ * only when it really is still active.
+ */
+async function revokeOwnKey(hubUrl, key) {
+    const hub = new Hub(hubUrl, key);
+    const prefix = `${key.slice(0, 13)}…`;
+    try {
+        const { api_keys } = await hub.get("/api/v1/api-keys");
+        const matches = api_keys.filter((k) => !k.revoked_at && key.startsWith(k.prefix.replace("…", "")));
+        if (matches.length === 1) {
+            await hub.request("DELETE", `/api/v1/api-keys/${encodeURIComponent(matches[0].id)}`);
+            return { prefix: matches[0].prefix, revoked: true, already_invalid: false };
+        }
+    }
+    catch (error) {
+        if (error instanceof HubRequestError && error.status === 401)
+            return { prefix, revoked: true, already_invalid: true };
+        // Offline, or a key without permission to manage keys: it may still be active.
+    }
+    return { prefix, revoked: false, already_invalid: false };
+}
+function revokedText(r) {
+    if (r.already_invalid)
+        return `ya no era válida (${r.prefix})`;
+    return r.revoked ? `revocada (${r.prefix})` : `sigue activa (${r.prefix}): revocala desde el dashboard`;
+}
+const LOGIN_ERRORS = {
+    expired: "El login venció.",
+    already_claimed: "Este login ya se completó.",
+    not_found: "El hub no reconoce este login.",
+    environment_disabled: "El hub todavía no está conectado a ese entorno de Talo.",
+};
+function loginError(error) {
+    return (error.code && LOGIN_ERRORS[error.code]) ?? (error.transient ? hubMessage(error) : "El hub rechazó el login.");
+}
+async function login(config) {
+    if (flags.sandbox && flags.production)
+        fail("Elegí --sandbox o --production, no los dos.");
+    const environment = flags.production ? "production" : "sandbox";
+    if (process.env.TALO_HUB_API_KEY)
+        say("! TALO_HUB_API_KEY está definida: mientras exista, los comandos usan esa key y no la de este login.");
+    let hubUrl;
+    try {
+        hubUrl = requestedHub(flags.hub) ?? DEFAULT_HUB;
+    }
+    catch (error) {
+        fail(error.message, "invalid_hub");
+    }
+    const hub = new Hub(hubUrl);
+    let session;
+    try {
+        session = await hub.post("/api/cli/sessions", { environment });
+    }
+    catch (error) {
+        if (error instanceof HubRequestError)
+            fail(loginError(error), error.code ?? "login_failed", { status: error.status });
+        throw error;
+    }
+    // The link is built here, not taken from the answer, so a hub can't point the browser elsewhere.
+    const loginUrl = `${hubUrl}/cli/login/${encodeURIComponent(session.id)}`;
+    say(`Conectando tu cuenta Talo ${environment === "sandbox" ? "sandbox" : "de producción"}.`);
+    say(`\n  Código: ${session.user_code}\n`);
+    say(`Abrí este link (si no se abrió solo) y confirmá que ves el mismo código:\n  ${loginUrl}\n`);
+    openBrowser(loginUrl);
+    const deadline = Date.now() + session.expires_in * 1000;
+    let warned = false;
+    while (Date.now() < deadline) {
+        await sleep(Math.max(session.interval, 1) * 1000);
+        let result;
+        try {
+            result = await hub.post(`/api/cli/sessions/${encodeURIComponent(session.id)}/token`, { poll_token: session.poll_token });
+        }
+        catch (error) {
+            if (error instanceof HubRequestError && error.transient) {
+                if (!warned)
+                    say(`! ${hubMessage(error)} Seguimos intentando…`);
+                warned = true;
+                continue;
+            }
+            if (error instanceof HubRequestError)
+                fail(`${loginError(error)} Volvé a correr ${loginHint(environment)}.`, error.code ?? "login_failed", { status: error.status });
+            throw error;
+        }
+        if (result.status === "complete" && result.api_key) {
+            const previous = config.keys[environment];
+            const previousHub = config.hubs[environment] ?? DEFAULT_HUB;
+            config.keys[environment] = result.api_key;
+            if (hubUrl === DEFAULT_HUB)
+                delete config.hubs[environment];
+            else
+                config.hubs[environment] = hubUrl;
+            // A production login never makes production the default: later commands only touch real
+            // money with --production or after `use production`.
+            if (environment === "sandbox" && !config.keys[config.current])
+                config.current = "sandbox";
+            await saveConfig(config);
+            // The key this login replaces would otherwise stay valid forever. It goes only to its own hub.
+            const replaced = previous && previous !== result.api_key ? await revokeOwnKey(previousHub, previous) : undefined;
+            const account = result.talo_user_id;
+            emit({ environment, talo_user_id: account ?? null, current: config.current, hub: hubUrl, config_path: configPath(), replaced_key: replaced ?? null }, () => {
+                console.log(`✓ Conectada la cuenta Talo${account ? ` ${account}` : ""} (${environment}).`);
+                if (!account)
+                    console.log(`! No pudimos confirmar qué cuenta quedó conectada: revisala con ${CMD} status.`);
+                console.log(`  Key guardada en ${configPath()}`);
+                if (replaced)
+                    console.log(`  Key anterior: ${revokedText(replaced)}.`);
+                console.log(`  Entorno activo: ${config.current}${config.current === environment ? "" : ` (para usar esta cuenta: --${environment} o ${CMD} use ${environment})`}`);
+                console.log(environment === "sandbox" ? `  Probá: ${CMD} payments create --amount 15000` : "  Ojo: en producción los cobros son con plata real.");
+            });
+            return;
+        }
+    }
+    fail(`El login venció. Volvé a correr ${loginHint(environment)}.`, "expired");
+}
+function showEvent(event, replayed = false) {
+    const payment = event.data?.payment;
+    if (jsonMode)
+        console.log(JSON.stringify(replayed ? { ...event, replayed: true } : event));
+    else
+        console.log(`${timeOnly.format(new Date(event.created_at))}  ${event.type}${payment ? `  ${payment.id} ${payment.status}` : ""}${replayed ? "  (anterior)" : ""}`);
+}
+async function listen(hub) {
+    let forward;
+    if (flags["forward-to"]) {
+        forward =
+            parseForwardUrl(flags["forward-to"]) ??
+                fail("--forward-to tiene que ser una URL http(s) o un puerto, p. ej. http://localhost:3000/api/webhooks/talo o 3000.", "invalid_url");
+    }
+    const retry = (error, waitMs) => console.error(`! ${hubMessage(error)} Reintentando en ${Math.round(waitMs / 1000)} s…`);
+    // The last few events give context (a payment that just got paid); only new ones are relayed.
+    const recent = await resilient(() => hub.get("/api/v1/events?recent=5"), retry);
+    const shown = [...recent.events].reverse();
+    for (const event of shown)
+        showEvent(event, true);
+    let after = shown.at(-1)?.id ?? 0;
+    console.error(`Escuchando eventos${forward ? ` y reenviando a ${forward}` : ""}. Ctrl+C para salir.`);
+    if (forward)
+        console.error("Los eventos reenviados no van firmados (traen el header talo-hub-forwarded: 1): aceptalos solo en desarrollo.");
+    let hinted = false;
+    for (;;) {
+        const page = await resilient(() => hub.get(`/api/v1/events?after=${after}&limit=200`), retry);
+        for (const event of page.events) {
+            showEvent(event);
+            if (forward) {
+                try {
+                    const response = await fetch(forward, {
+                        method: "POST",
+                        headers: { "content-type": "application/json", "talo-hub-event": event.type, "talo-hub-forwarded": "1" },
+                        body: JSON.stringify(event),
+                        signal: AbortSignal.timeout(10_000),
+                    });
+                    console.error(`  → ${forward} ${response.status}`);
+                    if ((response.status === 401 || response.status === 403) && !hinted) {
+                        console.error("  Tu endpoint rechazó el evento: los reenviados no traen firma. En desarrollo, aceptá los que traen talo-hub-forwarded: 1.");
+                        hinted = true;
+                    }
+                }
+                catch (error) {
+                    console.error(`  → ${forward} falló: ${networkReason(error)}`);
+                }
+            }
+        }
+        after = page.next_after;
+        await sleep(2000);
+    }
+}
+const SKILLS = ["talo-payments", "talo-go-live", "talo-operations"];
+/** Downloads the skills into ./.claude/skills (or ~/.claude/skills with --global). */
+async function installSkills(hubUrl) {
+    const root = join(flags.global ? homedir() : process.cwd(), ".claude", "skills");
+    const installed = [];
+    for (const skill of SKILLS) {
+        let text = "";
+        let status = 0;
+        try {
+            const response = await fetch(`${hubUrl}/skills/${skill}/SKILL.md`, { signal: AbortSignal.timeout(30_000) });
+            status = response.status;
+            if (response.ok)
+                text = await response.text();
+        }
+        catch (error) {
+            fail(`No pudimos conectar con ${hubUrl} (${networkReason(error)}).`, "network_error");
+        }
+        if (!text.startsWith("---") || !text.includes(`name: ${skill}`))
+            fail(`No pudimos descargar la skill ${skill} (HTTP ${status}).`, "download_failed");
+        const path = join(root, skill, "SKILL.md");
+        await mkdir(join(root, skill), { recursive: true });
+        await writeFile(path, text);
+        installed.push(path);
+        say(`✓ ${path}`);
+    }
+    emit({ installed }, () => console.log(`Tu agente ya puede integrar y operar Talo. Sumale el MCP: ${CMD} mcp`));
+}
+/** Which shell will run a printed command: PowerShell spells environment variables differently. */
+function shellSyntax() {
+    if (process.platform !== "win32")
+        return "bash";
+    if (process.env.MSYSTEM || process.env.SHELL)
+        return "bash";
+    return "powershell";
+}
+/**
+ * Prints the MCP setup. By default it is the OAuth form: the client signs the person in and the key
+ * never lands in a shell history or a project file. --with-key prints a key-based setup instead.
+ */
+function mcpConfig(hubUrl, key) {
+    const url = `${hubUrl}/api/mcp`;
+    const client = flags.client ?? "claude";
+    if (!["claude", "cursor", "desktop"].includes(client))
+        fail("--client tiene que ser claude, cursor o desktop.", "invalid_option");
+    const withKey = Boolean(flags["with-key"]);
+    if (client === "claude") {
+        if (!withKey) {
+            const command = `claude mcp add --transport http talo ${url}`;
+            emit({ client, oauth: true, command }, () => console.log(command));
+            say("\nDespués, en Claude Code: /mcp → talo → Authenticate. Elegís sandbox o producción y los permisos en el navegador.");
+            return;
+        }
+        // A reference to the variable, not the key, so it never lands in shell history. Each shell
+        // spells it differently, and from here we can't tell PowerShell from cmd.
+        const forShell = (variable) => `claude mcp add --transport http talo ${url} --header "Authorization: Bearer ${variable}"`;
+        const commands = shellSyntax() === "bash" ? { bash: forShell("$TALO_HUB_API_KEY") } : { powershell: forShell("$env:TALO_HUB_API_KEY"), cmd: forShell("%TALO_HUB_API_KEY%") };
+        emit({ client, oauth: false, commands, needs_env: "TALO_HUB_API_KEY" }, () => {
+            for (const [shell, command] of Object.entries(commands))
+                console.log(Object.keys(commands).length > 1 ? `# ${shell}\n${command}` : command);
+        });
+        if (!process.env.TALO_HUB_API_KEY) {
+            say(`\n! Definí antes TALO_HUB_API_KEY con una key, mejor de scope charge: ${CMD} keys create --scope charge`);
+        }
+        return;
+    }
+    if (withKey && !key)
+        fail(`No hay key para usar. Corré ${CMD} login o definí TALO_HUB_API_KEY.`, "not_logged_in");
+    let server;
+    if (client === "cursor") {
+        server = withKey ? { url, headers: { Authorization: `Bearer ${key}` } } : { url };
+    }
+    else {
+        // mcp-remote runs the OAuth flow itself. With a key, the space of "Bearer <key>" lives in env:
+        // Claude Desktop on Windows splits args at spaces.
+        server = withKey
+            ? { command: "npx", args: ["-y", "mcp-remote", url, "--header", "Authorization:${TALO_AUTH}"], env: { TALO_AUTH: `Bearer ${key}` } }
+            : { command: "npx", args: ["-y", "mcp-remote", url] };
+    }
+    console.log(JSON.stringify({ mcpServers: { talo: server } }, null, 2));
+    if (client === "cursor") {
+        console.error(withKey ? "\nPegalo en ~/.cursor/mcp.json (global, no en el proyecto: tiene tu key)." : "\nPegalo en .cursor/mcp.json; Cursor te pide autenticar al conectarse.");
+    }
+    else {
+        console.error(withKey ? "\nPegalo en claude_desktop_config.json (tiene tu key: no lo compartas)." : "\nPegalo en claude_desktop_config.json; se abre el navegador para autorizar.");
+    }
+}
+const KEYED_COMMANDS = new Set(["status", "doctor", "payments", "sandbox", "balance", "transactions", "events", "webhooks", "keys"]);
+const ALL_COMMANDS = new Set([...KEYED_COMMANDS, "login", "logout", "use", "mcp", "skills"]);
+async function main() {
+    const [command, sub, arg] = positionals;
+    if (flags.version)
+        return emit({ version: VERSION }, () => console.log(VERSION));
+    if (!command || flags.help || command === "help")
+        return emit({ version: VERSION, help: HELP }, () => console.log(HELP));
+    if (!ALL_COMMANDS.has(command))
+        fail(`Comando desconocido: ${command}. Mirá ${CMD} --help`, "unknown_command");
+    checkOptions(command, sub);
+    const config = await loadConfig();
+    if (command === "login")
+        return login(config);
+    if (command === "skills") {
+        if (sub !== "install")
+            fail(`Usá: ${CMD} skills install [--global]`);
+        let hubUrl;
+        try {
+            hubUrl = requestedHub(flags.hub) ?? DEFAULT_HUB;
+        }
+        catch (error) {
+            fail(error.message, "invalid_hub");
+        }
+        return installSkills(hubUrl);
+    }
+    if (command === "logout") {
+        const environments = flags.all ? ["sandbox", "production"] : [chosenEnvironment(config)];
+        const removed = [];
+        for (const environment of environments) {
+            const key = config.keys[environment];
+            if (!key)
+                continue;
+            removed.push({ environment, ...(await revokeOwnKey(config.hubs[environment] ?? DEFAULT_HUB, key)) });
+            delete config.keys[environment];
+            delete config.hubs[environment];
+        }
+        await saveConfig(config);
+        return emit({ removed }, () => {
+            if (removed.length === 0)
+                console.log("No había ninguna key guardada.");
+            for (const r of removed) {
+                console.log(`✓ Key de ${r.environment} borrada de esta máquina; en el hub, ${revokedText(r)}.`);
+            }
+        });
+    }
+    if (command === "use") {
+        if (sub !== "sandbox" && sub !== "production")
+            fail(`Usá: ${CMD} use sandbox | production`);
+        config.current = sub;
+        await saveConfig(config);
+        if (process.env.TALO_HUB_API_KEY)
+            say("! TALO_HUB_API_KEY está definida y tiene prioridad sobre el entorno elegido.");
+        return emit({ environment: sub, logged_in: Boolean(config.keys[sub]) }, () => console.log(`✓ Entorno: ${sub}${config.keys[sub] ? "" : ` (todavía no hiciste login: ${loginHint(sub)})`}`));
+    }
+    // `sandbox pay` always means the sandbox account, whatever the current environment is.
+    if (command === "sandbox" && flags.production)
+        fail("sandbox pay solo funciona en sandbox.");
+    const environment = command === "sandbox" ? "sandbox" : chosenEnvironment(config);
+    let asked;
+    try {
+        asked = requestedHub(flags.hub);
+    }
+    catch (error) {
+        fail(error.message, "invalid_hub");
+    }
+    // These MCP setups need no key, only the hub's URL: OAuth, and Claude Code reading the variable.
+    if (command === "mcp" && (!flags["with-key"] || (flags.client ?? "claude") === "claude")) {
+        return mcpConfig(asked ?? config.hubs[environment] ?? DEFAULT_HUB, undefined);
+    }
+    let resolved;
+    try {
+        resolved = resolveKey(config, environment, asked);
+    }
+    catch (error) {
+        fail(error.message, "hub_mismatch");
+    }
+    const { key, hub: hubUrl, fromEnv } = resolved;
+    const keyEnvironment = key ? environmentOfKey(key) : undefined;
+    if (fromEnv && keyEnvironment && keyEnvironment !== environment && (flags.production || flags.sandbox || command === "sandbox")) {
+        fail(`TALO_HUB_API_KEY es una key de ${keyEnvironment}, pero pediste ${environment}. Sacá la variable o usá la key de ${environment}.`, "env_key_mismatch");
+    }
+    if (command === "mcp")
+        return mcpConfig(hubUrl, key);
+    if (!key)
+        fail(`No hay sesión en ${environment}. Corré: ${loginHint(environment)}`, "not_logged_in");
+    if (fromEnv && !jsonMode)
+        console.error("(usando TALO_HUB_API_KEY)");
+    const hub = new Hub(hubUrl, key);
+    try {
+        await run(hub, { command, sub, arg, key, keyEnvironment, fromEnv, hubUrl });
+    }
+    catch (error) {
+        if (!(error instanceof HubRequestError))
+            throw error;
+        let message = hubMessage(error);
+        const scopes = error.code === "insufficient_scope" ? error.message.match(/scope is "(\w+)"; this needs "(\w+)"/) : null;
+        if (scopes)
+            message = `Esta key tiene scope ${scopes[1]} y esto necesita ${scopes[2]}.`;
+        if (error.status === 401)
+            message = fromEnv ? "La key de TALO_HUB_API_KEY no es válida o fue revocada." : `${message} Volvé a correr ${loginHint(environment)}.`;
+        if (error.code === "talo_reconnect_required")
+            message += ` Volvé a correr ${loginHint(environment)}.`;
+        if (error.code === "insufficient_scope" && fromEnv && config.keys[environment])
+            message += " Es la key de TALO_HUB_API_KEY: sacá la variable para usar la de tu login.";
+        if (error.code === "talo_rejected" && !jsonMode)
+            message = `Talo rechazó el pedido: ${error.message}`;
+        fail(message, error.code ?? "hub_error", {
+            status: error.status,
+            ...(scopes ? { key_scope: scopes[1], required_scope: scopes[2] } : {}),
+            ...(error.details ? { details: error.details } : {}),
+        });
+    }
+}
+async function run(hub, ctx) {
+    const { command, sub, arg, key, keyEnvironment, fromEnv, hubUrl } = ctx;
+    switch (command) {
+        case "status": {
+            const account = await hub.get("/api/v1/account");
+            const keys = await hub.get("/api/v1/api-keys").catch(() => null);
+            const scope = keys?.api_keys.find((k) => key.startsWith(k.prefix.replace("…", "")))?.scope;
+            return emit({ ...account, key_scope: scope ?? null, key_source: fromEnv ? "TALO_HUB_API_KEY" : "config", hub: hubUrl }, () => {
+                console.log(`Cuenta Talo ${account.talo_user_id} (${account.environment})`);
+                console.log(`  Estado: ${account.account_status ?? "desconocido"}`);
+                if (scope)
+                    console.log(`  Permisos de la key: ${scope}`);
+                if (account.alias_prefix)
+                    console.log(`  Prefijo de alias: ${account.alias_prefix}`);
+                console.log(`  Key: ${fromEnv ? "TALO_HUB_API_KEY" : configPath()}`);
+                console.log(`  Hub: ${hubUrl}`);
+            });
+        }
+        case "payments": {
+            if (sub === "create") {
+                const payment = await hub.post("/api/v1/payments", { amount: amountFlag(true), external_id: flags["external-id"], motive: flags.motive });
+                return emit(payment, () => {
+                    showPayment(payment);
+                    if (keyEnvironment === "sandbox")
+                        console.log(`\nPara pagarlo: ${CMD} sandbox pay ${payment.id}`);
+                });
+            }
+            if (sub === "get") {
+                if (!arg)
+                    fail(`Usá: ${CMD} payments get <payment_id>`);
+                const payment = await hub.get(`/api/v1/payments/${encodeURIComponent(arg)}`);
+                return emit(payment, () => showPayment(payment));
+            }
+            if (sub === "list") {
+                const query = new URLSearchParams();
+                const from = dateFlag("from");
+                const to = dateFlag("to");
+                if (from)
+                    query.set("from", from);
+                if (to)
+                    query.set("to", to);
+                const result = await hub.get(`/api/v1/payments?${query}`);
+                return emit(result, () => {
+                    if (result.payments.length === 0)
+                        console.log("Sin cobros en el período.");
+                    for (const p of result.payments)
+                        console.log(`${p.status.padEnd(10)} ${money.format(p.amount ?? 0).padStart(14)}  ${p.id}`);
+                });
+            }
+            if (sub === "refund") {
+                if (!arg)
+                    fail(`Usá: ${CMD} payments refund <payment_id> [--amount <ARS>]`);
+                const amount = amountFlag(false);
+                const payment = await hub.post(`/api/v1/payments/${encodeURIComponent(arg)}/refunds`, amount === undefined ? {} : { amount });
+                return emit(payment, () => console.log(`✓ Reembolso pedido (${amount === undefined ? "total" : money.format(amount)}). Talo lo procesa en unos minutos.`));
+            }
+            return fail(`Usá: ${CMD} payments create | get <id> | list | refund <id>`);
+        }
+        case "sandbox": {
+            if (sub !== "pay" || !arg)
+                return fail(`Usá: ${CMD} sandbox pay <payment_id> [--amount <ARS>]`);
+            const result = await hub.post("/api/v1/sandbox/transfers", { payment_id: arg, amount: amountFlag(false) });
+            return emit(result, () => console.log(`✓ Transferencia simulada de ${money.format(result.amount)} al CVU ${result.cvu}. Mirá el estado con: ${CMD} payments get ${arg}`));
+        }
+        case "doctor": {
+            const report = await hub.get("/api/v1/readiness");
+            if (!report.ready)
+                process.exitCode = 1;
+            return emit(report, () => {
+                console.log(`Checklist de ${report.environment === "sandbox" ? "sandbox" : "producción"}\n`);
+                for (const check of report.checks) {
+                    console.log(`${check.ok ? "✓" : "✗"} ${check.title}`);
+                    if (!check.ok && check.fix)
+                        console.log(`    → ${check.fix}`);
+                }
+                for (const tip of report.recommendations)
+                    console.log(`\n! ${tip}`);
+                console.log(`\n${report.ready ? "✓" : "…"} ${report.summary}`);
+            });
+        }
+        case "balance":
+            return emit(await hub.get("/api/v1/balance"));
+        case "transactions": {
+            const query = new URLSearchParams({ limit: String(limitFlag(20)) });
+            const from = dateFlag("from");
+            const to = dateFlag("to");
+            if (from)
+                query.set("from", from);
+            if (to)
+                query.set("to", to);
+            if (flags.cursor)
+                query.set("cursor", flags.cursor);
+            return emit(await hub.get(`/api/v1/transactions?${query}`));
+        }
+        case "events": {
+            if (sub === "listen")
+                return listen(hub);
+            if (sub !== undefined && sub !== "list")
+                fail(`Usá: ${CMD} events list [--after <id>] | listen [--forward-to <url>]`);
+            const query = new URLSearchParams({ limit: String(limitFlag(20)) });
+            if (flags.payment)
+                query.set("payment_id", flags.payment);
+            if (flags.type)
+                query.set("type", flags.type);
+            if (flags.after === undefined) {
+                query.set("recent", query.get("limit"));
+                return emit(await hub.get(`/api/v1/events?${query}`));
+            }
+            if (!/^\d+$/.test(flags.after) || !Number.isSafeInteger(Number(flags.after))) {
+                fail(`--after tiene que ser el número de un evento (recibimos "${flags.after}").`, "invalid_option");
+            }
+            query.set("after", flags.after);
+            return emit(await hub.get(`/api/v1/events?${query}`));
+        }
+        case "webhooks": {
+            if (sub === undefined || sub === "list")
+                return emit(await hub.get("/api/v1/webhook-endpoints"));
+            if (sub !== "add" && sub !== "remove" && sub !== "test")
+                fail(`Usá: ${CMD} webhooks list | add <url> | remove <id> | test <id>`);
+            if (!arg)
+                fail(`Usá: ${CMD} webhooks ${sub === "add" ? "add <url>" : `${sub} <id>`}`);
+            if (sub === "add") {
+                const endpoint = await hub.post("/api/v1/webhook-endpoints", { url: arg });
+                return emit(endpoint, () => console.log(`✓ Webhook ${endpoint.id}\n  Secreto para verificar la firma (guardalo en el .env de tu servidor como TALO_HUB_WEBHOOK_SECRET; no se vuelve a mostrar):\n  ${endpoint.secret}`));
+            }
+            if (sub === "remove")
+                return emit(await hub.request("DELETE", `/api/v1/webhook-endpoints/${encodeURIComponent(arg)}`));
+            const result = await hub.post(`/api/v1/webhook-endpoints/${encodeURIComponent(arg)}/test`);
+            if (!result.delivered)
+                process.exitCode = 1;
+            return emit(result, () => console.log(result.delivered
+                ? `✓ ${result.url} recibió el evento de prueba (HTTP ${result.status_code}).`
+                : `✗ ${result.url} no lo aceptó: ${result.error ?? `HTTP ${result.status_code}`}. Revisá que verifique la firma y responda 2xx.`));
+        }
+        case "keys": {
+            if (sub === undefined || sub === "list")
+                return emit(await hub.get("/api/v1/api-keys"));
+            if (sub === "create") {
+                if (flags.scope && !["read", "charge", "full"].includes(flags.scope))
+                    fail("--scope tiene que ser read, charge o full.", "invalid_option");
+                const created = await hub.post("/api/v1/api-keys", {
+                    name: flags.name ?? "CLI",
+                    scope: flags.scope ?? "charge",
+                });
+                return emit(created, () => console.log(`✓ ${created.api_key}\n  ${created.environment} · scope ${created.scope}. Guardala ahora en el .env o los secretos de tu servidor (TALO_HUB_API_KEY): no se vuelve a mostrar.\n  En esta terminal, exportarla reemplaza a la key de tu login.`));
+            }
+            if (sub === "revoke") {
+                if (!arg)
+                    fail(`Usá: ${CMD} keys revoke <id>`);
+                const result = await hub.request("DELETE", `/api/v1/api-keys/${encodeURIComponent(arg)}`);
+                return emit(result, () => console.log(`✓ Key ${arg} revocada. Si era la de este login, corré ${CMD} login de nuevo.`));
+            }
+            return fail(`Usá: ${CMD} keys list | create [--name <nombre>] [--scope read|charge|full] | revoke <id>`);
+        }
+    }
+}
+main().catch((error) => {
+    if (error instanceof HubRequestError)
+        fail(hubMessage(error), error.code ?? "hub_error", { status: error.status });
+    fail(error instanceof Error ? error.message : String(error), "internal_error");
+});

package/dist/config.js

@@ -0,0 +1,88 @@
+// Where the CLI keeps its API keys: ~/.config/talo-hub/config.json (or %APPDATA%\talo-hub), readable
+// only by the user. Each key remembers the hub that issued it, so it is never sent anywhere else.
+// TALO_HUB_API_KEY and TALO_HUB_URL override them for one run (CI, agents) and are never saved.
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const DEFAULT_HUB = "https://talopartnerhub.vercel.app";
+function configDir() {
+    if (process.platform === "win32" && process.env.APPDATA)
+        return join(process.env.APPDATA, "talo-hub");
+    return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "talo-hub");
+}
+export const configPath = () => join(configDir(), "config.json");
+export async function loadConfig() {
+    let stored = {};
+    try {
+        stored = JSON.parse(await readFile(configPath(), "utf8"));
+    }
+    catch {
+        // No config yet.
+    }
+    const keys = { ...(stored.keys ?? {}) };
+    const hubs = {};
+    for (const environment of ["sandbox", "production"]) {
+        // Configs from before per-key hubs had one `hub` for every key.
+        const hub = stored.hubs?.[environment] ?? (typeof stored.hub === "string" ? stored.hub : undefined);
+        if (!hub || !keys[environment])
+            continue;
+        try {
+            hubs[environment] = normalizeHub(hub);
+        }
+        catch {
+            // A key saved for a hub we wouldn't talk to now (plain http…): forget it, the person logs in again.
+            delete keys[environment];
+        }
+    }
+    return { current: stored.current === "production" ? "production" : "sandbox", keys, hubs };
+}
+export async function saveConfig(config) {
+    await mkdir(configDir(), { recursive: true, mode: 0o700 });
+    const hubs = Object.fromEntries(Object.entries(config.hubs).filter(([environment, hub]) => hub && config.keys[environment]));
+    const stored = { current: config.current, keys: config.keys, ...(Object.keys(hubs).length ? { hubs } : {}) };
+    await writeFile(configPath(), `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600 });
+    await chmod(configPath(), 0o600).catch(() => undefined);
+}
+/** Keys only travel over https, except to a hub on this machine (development). */
+export function normalizeHub(value) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        throw new Error(`La URL del hub no es válida: "${value}".`);
+    }
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if (url.protocol !== "https:" && !(local && url.protocol === "http:")) {
+        throw new Error(`El hub tiene que usar https (recibimos "${value}"). Tus keys no viajan sin cifrar.`);
+    }
+    return url.origin + url.pathname.replace(/\/+$/, "");
+}
+/** A hub asked for on this run: --hub, else TALO_HUB_URL. Empty values count as unset. */
+export function requestedHub(flag) {
+    const value = flag?.trim() || process.env.TALO_HUB_URL?.trim();
+    return value ? normalizeHub(value) : undefined;
+}
+export function environmentOfKey(key) {
+    if (key.startsWith("tph_test_"))
+        return "sandbox";
+    if (key.startsWith("tph_live_"))
+        return "production";
+    return undefined;
+}
+/**
+ * The key and hub for a command, given the hub asked for (already normalized, see requestedHub).
+ * TALO_HUB_API_KEY wins over the stored key. A stored key is only sent to the hub that issued it:
+ * asking for another hub with it is an error.
+ */
+export function resolveKey(config, environment, asked) {
+    const envKey = process.env.TALO_HUB_API_KEY?.trim();
+    if (envKey)
+        return { key: envKey, hub: asked ?? DEFAULT_HUB, fromEnv: true };
+    const key = config.keys[environment];
+    const issuer = config.hubs[environment] ?? DEFAULT_HUB;
+    if (key && asked && asked !== issuer) {
+        throw new Error(`La key de ${environment} guardada es de ${issuer}, no de ${asked}. Hacé login en ese hub o usá TALO_HUB_API_KEY.`);
+    }
+    return { key, hub: asked ?? issuer, fromEnv: false };
+}

package/dist/hub.js

@@ -0,0 +1,82 @@
+// A small client for the hub's /api/v1.
+const TIMEOUT_MS = 30_000;
+export class HubRequestError extends Error {
+    status;
+    code;
+    details;
+    constructor(message, status, code, 
+    /** Talo's own reason when the hub passes one on (talo_message, talo_code). */
+    details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = "HubRequestError";
+    }
+    /** Worth retrying: the network failed, or the hub is overloaded or broken for a moment. */
+    get transient() {
+        return this.status === 0 || this.status === 429 || this.status >= 500;
+    }
+}
+/** The root cause of a failed fetch, in words ("ECONNREFUSED", "terminated"…). */
+export function networkReason(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = error.cause;
+    return cause?.message ?? error.message;
+}
+function proxyHint() {
+    return process.env.HTTPS_PROXY || process.env.HTTP_PROXY ? " Si usás un proxy, corré con NODE_USE_ENV_PROXY=1 (Node 22.21+ o 24.5+)." : "";
+}
+export class Hub {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    async request(method, path, body) {
+        const headers = { accept: "application/json", "talo-hub-client": "cli" };
+        if (this.apiKey)
+            headers.authorization = `Bearer ${this.apiKey}`;
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        let response;
+        let text;
+        try {
+            response = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            // Reading the body can fail too (a reset mid-response): it counts as a network error.
+            text = await response.text();
+        }
+        catch (error) {
+            throw new HubRequestError(`No pudimos conectar con ${this.baseUrl} (${networkReason(error)}).${proxyHint()}`, 0, "network_error");
+        }
+        let data;
+        try {
+            data = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            data = text;
+        }
+        if (!response.ok && response.status !== 202) {
+            const error = data?.error;
+            throw new HubRequestError(error?.message ?? `El hub respondió ${response.status}.`, response.status, error?.code, error?.details);
+        }
+        // Every hub answer is a JSON object: anything else is a wrong URL, a proxy or a captive portal.
+        if (typeof data !== "object" || data === null) {
+            throw new HubRequestError(`${this.baseUrl} no respondió como el hub (no es JSON). Revisá --hub o TALO_HUB_URL.`, response.status, "invalid_response");
+        }
+        return data;
+    }
+    get(path) {
+        return this.request("GET", path);
+    }
+    post(path, body = {}) {
+        return this.request("POST", path, body);
+    }
+}

package/dist/parse.js

@@ -0,0 +1,85 @@
+// Parsing what people type (amounts, dates, limits, URLs), kept apart from cli.ts so it can be tested.
+/**
+ * ARS amounts as people type them: 15000, 15000.50, 15000,50, or with thousands dots (15.000,50).
+ * Anything ambiguous is refused instead of guessed, so 15.000 means fifteen thousand and 15,000
+ * (an English thousands comma) is rejected. PowerShell rewrites an unquoted 15.000,50 to 15,50
+ * before we see it, which is why the help recommends 15000.50 or quotes.
+ */
+export function parseAmount(raw) {
+    const value = raw.trim();
+    let normalized;
+    if (/^\d+([.,]\d{1,2})?$/.test(value))
+        normalized = value.replace(",", ".");
+    else if (/^\d{1,3}(\.\d{3})+(,\d{1,2})?$/.test(value))
+        normalized = value.replace(/\./g, "").replace(",", ".");
+    const amount = normalized === undefined ? NaN : Number(normalized);
+    return Number.isFinite(amount) && amount > 0 ? amount : undefined;
+}
+const AR_OFFSET = "-03:00";
+/** Whether the calendar day written in `value` is the day of `time` at `offset` (catches 02-31). */
+function sameDay(value, time, offsetMinutes) {
+    return new Date(time + offsetMinutes * 60_000).toISOString().slice(0, 10) === value.slice(0, 10);
+}
+function offsetMinutesOf(iso) {
+    if (/Z$/i.test(iso))
+        return 0;
+    const match = iso.match(/([+-])(\d{2}):?(\d{2})$/);
+    return match ? (match[1] === "-" ? -1 : 1) * (Number(match[2]) * 60 + Number(match[3])) : -180;
+}
+/**
+ * AAAA-MM-DD as an Argentine day (its first or last instant), or an ISO 8601 date-time. A date-time
+ * without Z or an offset is taken as Argentine time too, so the result doesn't depend on the machine.
+ */
+export function parseDate(raw, edge) {
+    let value = raw.trim();
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value))
+        value = `${value}T${edge === "start" ? "00:00:00.000" : "23:59:59.999"}${AR_OFFSET}`;
+    else if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(value))
+        return undefined;
+    else if (!/(Z|[+-]\d{2}:?\d{2})$/i.test(value))
+        value += AR_OFFSET;
+    const time = Date.parse(value);
+    if (Number.isNaN(time) || !sameDay(value, time, offsetMinutesOf(value)))
+        return undefined;
+    return new Date(time).toISOString();
+}
+/** A whole number from 1 to `max`, or undefined. */
+export function parseCount(raw, max) {
+    if (!/^\d+$/.test(raw.trim()))
+        return undefined;
+    const n = Number(raw);
+    return n >= 1 && n <= max ? n : undefined;
+}
+/**
+ * Where `events listen` relays events: an http(s) URL, a host:port (http assumed), or a bare port
+ * meaning localhost.
+ */
+export function parseForwardUrl(raw) {
+    const value = raw.trim();
+    let candidate;
+    if (/^\d+$/.test(value)) {
+        const port = Number(value);
+        if (port < 1 || port > 65535)
+            return undefined;
+        candidate = `http://localhost:${port}/`;
+    }
+    else if (/^https?:\/\//i.test(value)) {
+        candidate = value;
+    }
+    else if (/^[a-z][a-z0-9+.-]*:(?!\d)/i.test(value)) {
+        // Another scheme (ftp:, file:, mailto:…), with or without slashes: never guess http for it.
+        return undefined;
+    }
+    else {
+        candidate = `http://${value}`;
+    }
+    try {
+        const url = new URL(candidate);
+        if ((url.protocol !== "http:" && url.protocol !== "https:") || !url.hostname)
+            return undefined;
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "talo-hub",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Transferencias bancarias automáticas en Argentina con Talo Pay: un CVU por cobro, acreditación y conciliación automáticas, webhooks firmados, sandbox y MCP para agentes de IA (Claude, Cursor).",
+  "keywords": [
+    "talo",
+    "talo-pay",
+    "transferencias",
+    "transferencia-bancaria",
+    "cobros",
+    "pagos",
+    "argentina",
+    "cvu",
+    "cbu",
+    "alias",
+    "ars",
+    "payments",
+    "bank-transfer",
+    "payments-argentina",
+    "webhooks",
+    "sandbox",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "claude",
+    "cursor",
+    "cli"
+  ],
+  "homepage": "https://talopartnerhub.vercel.app/docs/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matiasbarrigadev/talo-partner-hub.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "author": "Talo Partner Hub",
+  "type": "module",
+  "bin": {
+    "talo-hub": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm test",
+    "test": "npm run build && node --test \"test/**/*.test.mjs\""
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "5.9.3"
+  }
+}