monacloud-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The MONA Group
+
+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

@@ -0,0 +1,176 @@
+# monacloud-mcp
+
+`monacloud-mcp` là MCP hợp nhất của MONA Cloud: cài một lần, đăng nhập một MONA ID và dùng chung ví VND để quản lý MONA Cloud, provision VibeCloud, tích hợp MONA Pay và đọc catalog MONA Agent ngay trong Claude Code, Codex hoặc Cursor.
+
+Human chỉ cần đăng ký, nạp tiền và cung cấp OTP/KYC khi bắt buộc. Các bước tạo tài nguyên, đọc trạng thái, cấu hình webhook, test và deploy được thiết kế để AI agent làm qua MCP.
+
+## Yêu cầu
+
+- Node.js 20 trở lên.
+- Một MONA ID có quyền dùng client `monacloud-mcp`.
+- MONA ID, Billing, VibeCloud và MONA Pay đã được cấu hình theo môi trường triển khai.
+
+## Cài và đăng nhập
+
+Đăng nhập lần đầu bằng OAuth Device Authorization Grant:
+
+```bash
+npx -y monacloud-mcp login
+```
+
+Lệnh in URL tại `id.monacloud.vn` và mã thiết bị. Sau khi xác nhận, offline refresh token được lưu tại `~/.config/monacloud/token.json`; thư mục có mode `0700`, file có mode `0600`. Server tự refresh access token và không in token ra log.
+
+Kiểm tra hoặc đăng xuất:
+
+```bash
+npx -y monacloud-mcp whoami
+npx -y monacloud-mcp logout
+```
+
+### Claude Code
+
+```bash
+claude mcp add monacloud -- npx -y monacloud-mcp
+```
+
+### Codex (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.monacloud]
+command = "npx"
+args = ["-y", "monacloud-mcp"]
+```
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "monacloud": {
+      "command": "npx",
+      "args": ["-y", "monacloud-mcp"]
+    }
+  }
+}
+```
+
+MCP client không cần giữ username/password sản phẩm. Có thể truyền PAT trực tiếp bằng `MONACLOUD_TOKEN` trong CI hoặc môi trường không dùng token store; không commit giá trị này.
+
+## Tool
+
+Tên tool dùng `snake_case` để giữ tương thích với prompt MONA Pay cũ.
+
+### MONA Cloud
+
+| Tool | Công dụng |
+|---|---|
+| `cloud_whoami` | Hồ sơ MONA ID hiện tại |
+| `cloud_balance` | Số dư ví VND chung |
+| `cloud_ledger` | Ledger nạp/trừ/hoàn tiền có cursor |
+| `cloud_topup(amount)` | Tạo yêu cầu nạp, trả `qr_data_url` và hướng dẫn VietQR |
+| `cloud_usage(period)` | Usage theo tháng, có thể lọc sản phẩm |
+| `cloud_services` | Gom service VibeCloud, VA và webhook MONA Pay |
+| `cloud_budget_set` / `cloud_budget_get` | Đặt và đọc budget theo product/project/token |
+| `cloud_token_limit` | Đặt spend limit cho PAT/token |
+| `cloud_open_console` | Trả URL console chung |
+
+### MONA Pay
+
+`monacloud-mcp` import `monapay-mcp` và re-export toàn bộ tool của package, không copy implementation. Dependency range là `^0.3.0`; bộ dependency offline tại lần verify này là 0.5.5 với 47 tool MONA Pay, gồm các nhóm:
+
+- hồ sơ và nối ACB/VA bằng hai lần OTP;
+- payment profile, checkout, VietQR, sandbox transaction và đối soát;
+- webhook, log, thống kê và retry;
+- email notification, verification, suppression và log;
+- xoay key, kiểm chữ ký HMAC và sinh code mẫu webhook.
+
+Các tên cũ như `monapay_create_qr`, `monapay_link_bank_start`, `monapay_create_webhook` được giữ nguyên. `monapay_link` là adapter chuyển tiếp: đổi MONA ID thành `client_id/client_secret` rồi cache kín ở `~/.config/monacloud/links.json`. Adapter này sẽ được bỏ khi MONA Pay nhận JWT MONA ID trực tiếp.
+
+### VibeCloud
+
+| Tool | Công dụng |
+|---|---|
+| `vibecloud_link` | Xác nhận direct MONA ID; chỉ đổi sang `vc_live_*` nếu upstream còn ở chế độ cũ |
+| `vibecloud_create_vps` | Tạo LXC theo `package_slug` hoặc CPU/RAM/đĩa |
+| `vibecloud_create_database` | Tạo MongoDB, PostgreSQL hoặc MySQL |
+| `vibecloud_job_status` | Poll job tới trạng thái cuối, có timeout |
+| `vibecloud_list_services` | Liệt kê VPS/database |
+| `vibecloud_start` / `vibecloud_stop` / `vibecloud_rebuild` | Quản lý vòng đời service |
+| `vibecloud_prices` / `vibecloud_packages` | Đơn giá và gói cấu hình |
+| `vibecloud_agent_deploy` | Stub có cấu trúc cho runtime MONA Agent wave sau |
+
+`vibecloud_stop` không bị chặn bởi số dư để người dùng luôn có thể hạn chế chi phí. Những lệnh tạo/start/rebuild đọc `GET /v1/balance` trước khi gọi VibeCloud.
+
+### MONA Agent
+
+- `agent_templates_list`: ưu tiên catalog local tại `~/monacloud/templates`, sau đó URL cấu hình, cuối cùng catalog wave 1 tích hợp.
+- `agent_templates_get(template)`: trả các file `README.md`, `AGENTS.md`, `tools.json`, `deploy.md`, `CHECKLIST.md` và skill text.
+- `agent_deploy(template)`: dùng cùng slot runtime với `vibecloud_agent_deploy`; hiện trả `agent_runtime_pending` theo yêu cầu stub của wave này.
+
+## Resource và prompt
+
+- `monacloud://llms`: mô tả máy đọc của toàn stack MONA Cloud.
+- `monacloud://status`: health tổng hợp MONA ID, Billing, VibeCloud và MONA Pay.
+- Prompt `dung-app-ban-hang-monacloud`: chuỗi VPS → database → VA/QR → webhook → deploy, chỉ dừng để hỏi nạp tiền hoặc OTP bắt buộc.
+
+## Spend guard và lỗi cho AI
+
+Trước lệnh VibeCloud có thể phát sinh tiền, MCP đọc ví chung. HTTP `402 insufficient_funds` và `402 budget_exceeded` được chuẩn hoá thành text JSON:
+
+```json
+{
+  "code": "budget_exceeded",
+  "message": "Ví thiếu 20.000 đ hoặc đã chạm giới hạn chi tiêu.",
+  "next_step": "Nạp ví hoặc tăng ngân sách tại https://monacloud.vn/console rồi gọi lại tool.",
+  "request_id": "req_..."
+}
+```
+
+Token và linked secret không nằm trong payload lỗi hoặc log. `request_id` được giữ khi API upstream trả về để agent tự đối chiếu.
+
+## Ví dụ một lượt: dựng app bán hàng
+
+Người dùng nói:
+
+> Dựng app bán hàng Node.js, có PostgreSQL và thu tiền VietQR, deploy lên MONA Cloud.
+
+Agent thực hiện:
+
+1. `cloud_whoami` → `cloud_balance` → `vibecloud_packages`.
+2. Nếu ví thiếu: `cloud_topup(200000)`, đưa QR cho người dùng và chờ xác nhận.
+3. `vibecloud_create_vps` + `vibecloud_create_database`, sau đó `vibecloud_job_status` cho từng job.
+4. `monapay_link` nếu adapter chuyển tiếp chưa có credential; `monapay_whoami` để kiểm tra VA.
+5. Nếu chưa có VA: bắt đầu nối ACB, hỏi người dùng OTP đúng hai điểm bắt buộc, không tự đoán.
+6. Agent viết endpoint webhook HMAC/idempotent, gọi `monapay_create_webhook`, `monapay_test_webhook`, `monapay_webhook_logs`.
+7. Agent cắm `monapay_create_checkout` hoặc `monapay_create_qr`, deploy code lên VPS và báo URL cuối.
+
+Chi tiết dành riêng cho agent: [`docs/ai-agent.md`](docs/ai-agent.md).
+
+## Biến môi trường
+
+| Biến | Mặc định | Ý nghĩa |
+|---|---|---|
+| `MONACLOUD_ISSUER` | `https://id.monacloud.vn/realms/mona` | OIDC issuer |
+| `MONACLOUD_BILLING_URL` | `https://billing.monacloud.vn` | Billing/ví API |
+| `MONAPAY_API` | `https://api.monapay.vn` | MONA Pay API |
+| `VIBECLOUD_API` | `https://api.vibecloud.vn` | VibeCloud API |
+| `MONACLOUD_CONSOLE_URL` | `https://monacloud.vn/console` | URL trả cho bước human |
+| `MONACLOUD_TOKEN` | — | PAT/access token ưu tiên token store |
+| `MONACLOUD_CONFIG_DIR` | `~/.config/monacloud` | Token và link cache |
+| `MONACLOUD_TEMPLATES_DIR` | `~/monacloud/templates` | Catalog agent local |
+| `MONACLOUD_TEMPLATES_URL` | — | Catalog JSON từ xa, chỉ dùng khi local không có |
+| `MONAPAY_LINK_PATH` | `/api/v1/client/oauth/mona-id/link` | Endpoint adapter chuyển tiếp |
+| `VIBECLOUD_LINK_PATH` | `/api/auth/monaid/link` | Endpoint adapter cũ, chỉ gọi khi direct MONA ID bị từ chối |
+
+`MONAPAY_CLIENT_ID` + `MONAPAY_CLIENT_SECRET` và `VIBECLOUD_API_TOKEN` chỉ là đường tương thích trong giai đoạn migrate. `logout` xoá cả token store lẫn linked credential cache; luồng đích là một MONA ID.
+
+## Phát triển offline
+
+Không chạy `npm install` trong workspace handoff; `node_modules` đã được chuẩn bị sẵn.
+
+```bash
+node_modules/.bin/tsc -p tsconfig.json
+node --test
+```
+
+Test dùng Node built-in, MCP transport thật qua stdio, process con và mock HTTP local. Trong sandbox cấm bind socket, test tự dùng fetch fixture tương đương. Bộ test không gọi Internet.

package/STATUS.md

@@ -0,0 +1,48 @@
+# STATUS — monacloud-mcp 0.1.0
+
+Updated: 2026-09-03 (Asia/Ho_Chi_Minh)
+
+## Hoàn thành
+
+- [x] Package Node 20 + TypeScript, ESM, stdio MCP; bin `monacloud-mcp`, version `0.1.0`.
+- [x] OAuth device flow client `monacloud-mcp`, scope `offline_access`, token store private `0600`, refresh tự động; CLI `login`, `logout`, `whoami`.
+- [x] 10 tool `cloud_*`: identity, balance, ledger, topup VietQR, usage, services aggregation, budget, token limit và console URL.
+- [x] Import package `monapay-mcp` và re-export toàn bộ tool, không copy code. Dependency offline tại lần verify cuối là 0.5.5/47 tool (superset 24 tool yêu cầu); cộng `monapay_link` chuyển tiếp.
+- [x] 11 tool `vibecloud_*`: link, VPS, database, job poll, list, start/stop/rebuild, prices, packages và agent-deploy stub.
+- [x] 3 tool `agent_*`: list/get catalog local/remote/built-in và deploy qua cùng stub VibeCloud.
+- [x] Spend guard đọc billing balance trước create/start/rebuild; chuẩn hoá `402 insufficient_funds|budget_exceeded` thành `{code,message,next_step,request_id?}`. Stop luôn được phép.
+- [x] 2 resource đúng brief: `monacloud://llms`, `monacloud://status`.
+- [x] 1 prompt `dung-app-ban-hang-monacloud`: VPS → DB → VA/QR → webhook → deploy.
+- [x] Không log token; token và linked credential được lưu bằng atomic write, directory `0700`, file `0600`.
+- [x] README có cài Claude Code/Codex/Cursor, device flow, env, tool, spend guard và ví dụ một lượt dựng app bán hàng.
+- [x] `docs/ai-agent.md` mô tả zero-dashboard flow, OTP boundaries, idempotency, sandbox, deploy và definition of done.
+- [x] Test offline: stdio process thật + `tools/list` + `cloud_whoami` token giả; spend guard; 402; MONA Pay re-export; catalog/path validation.
+
+Tổng tool với dependency được chuẩn bị trong handoff tại lần verify cuối: **72**.
+
+## Gate đã chạy
+
+```text
+$ node_modules/.bin/tsc -p tsconfig.json
+exit 0, không có diagnostic
+
+$ node --test
+tests 7, pass 7, fail 0
+```
+
+Không chạy `npm install`; toàn bộ build/test dùng `node_modules` có sẵn và không gọi Internet.
+
+## Boundary chuyển tiếp đã ghi rõ
+
+- `monapay_link` mặc định gọi `/api/v1/client/oauth/mona-id/link`; đổi bằng `MONAPAY_LINK_PATH` nếu upstream chốt path khác. Adapter cache client credential và sẽ bị bỏ khi MONA Pay nhận JWT trực tiếp.
+- `vibecloud_link` thử Bearer MONA ID trực tiếp trước; chỉ khi upstream trả 401/403 mới gọi adapter `/api/auth/monaid/link` (đổi bằng `VIBECLOUD_LINK_PATH`). Tool nghiệp vụ luôn giữ nguyên tên.
+- `vibecloud_agent_deploy` và `agent_deploy` là stub được brief yêu cầu tới khi runtime MONA Agent được phát hành; response không báo thành công giả.
+- Chưa chạy smoke production vì phiên này offline và không được cấp token/endpoint production. Unit/integration local đã phủ wire contract chính.
+
+CODEX DONE
+
+## QC Claude (03/09 tối) — ZERO-DASHBOARD TEST LOCAL: PASS
+- Build tsc sạch · `node --test` 7/7 · stdio thật: **72 tool** (cloud 10 · monapay 48 · vibecloud 11 · agent 3), 2 resource, 1 prompt.
+- E2E thật với Keycloak local (`MONACLOUD_ISSUER=http://127.0.0.1:8180/realms/mona`) + billing (`MONACLOUD_BILLING_URL=http://127.0.0.1:8191`): `monacloud-mcp login` → mã thiết bị → đăng nhập + màn "Cấp quyền" của MONA ID → `token.json` 0600 → `cloud_whoami` (userinfo thật) → `cloud_balance` 0đ (ví JIT) → `cloud_ledger` → `cloud_budget_get`. **Một token, không chạm dashboard.**
+- Lưu ý test tự động: trang consent Keycloak có form action TƯƠNG ĐỐI (`/realms/mona/login-actions/consent?...`) → script phải ghép host; urllib Python rớt cookie ở hop 302 → dùng curl cookie jar.
+- Chưa: publish npm (`npm publish` — Claude làm khi deploy), `monapay_link`/`vibecloud_link` chờ endpoint link phía sản phẩm (gói E monapay, brief VIBECLOUD-MONAID đã có `/api/auth/monaid/link`).

package/dist/auth.d.ts

@@ -0,0 +1,39 @@
+import type { Config } from './config.js';
+export type StoredToken = {
+    access_token: string;
+    refresh_token?: string;
+    id_token?: string;
+    token_type?: string;
+    scope?: string;
+    expires_in?: number;
+    expires_at: number;
+};
+export declare class AuthManager {
+    readonly config: Config;
+    readonly env: NodeJS.ProcessEnv;
+    readonly fetchImpl: typeof fetch;
+    constructor(config: Config, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch);
+    private discovery;
+    loadToken(): Promise<StoredToken | undefined>;
+    saveToken(token: StoredToken): Promise<void>;
+    logout(): Promise<boolean>;
+    refresh(token: StoredToken): Promise<StoredToken>;
+    accessToken(): Promise<string>;
+    userinfo(): Promise<Record<string, unknown>>;
+    login(output?: (line: string) => void): Promise<Record<string, unknown>>;
+    tokenId(token: string): string;
+}
+export type LinkedCredentials = {
+    monapay?: {
+        client_id: string;
+        client_secret: string;
+        linked_at: string;
+    };
+    vibecloud?: {
+        token: string;
+        expires_at?: number;
+        linked_at: string;
+    };
+};
+export declare function readLinks(config: Config): Promise<LinkedCredentials>;
+export declare function writeLinks(config: Config, links: LinkedCredentials): Promise<void>;

package/dist/auth.js

@@ -0,0 +1,211 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { CloudError } from './errors.js';
+import { requestJson } from './http.js';
+const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const asObject = (value) => (value && typeof value === 'object' ? value : {});
+async function readJsonFile(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new CloudError('invalid_token_store', `Không đọc được token store: ${error instanceof Error ? error.message : String(error)}`, 'Chạy `monacloud-mcp logout`, sau đó đăng nhập lại.');
+    }
+}
+async function writePrivateJson(path, directory, value) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    await chmod(temporaryPath, 0o600);
+    await rename(temporaryPath, path);
+    await chmod(path, 0o600);
+}
+function tokenFromResponse(value, previousRefreshToken) {
+    const body = asObject(value);
+    if (typeof body.access_token !== 'string' || !body.access_token) {
+        throw new CloudError('invalid_token_response', 'MONA ID không trả access_token.', 'Kiểm tra cấu hình client `monacloud-mcp` trên MONA ID rồi đăng nhập lại.');
+    }
+    const expiresIn = typeof body.expires_in === 'number' ? body.expires_in : 300;
+    return {
+        access_token: body.access_token,
+        ...(typeof body.refresh_token === 'string'
+            ? { refresh_token: body.refresh_token }
+            : previousRefreshToken ? { refresh_token: previousRefreshToken } : {}),
+        ...(typeof body.id_token === 'string' ? { id_token: body.id_token } : {}),
+        ...(typeof body.token_type === 'string' ? { token_type: body.token_type } : {}),
+        ...(typeof body.scope === 'string' ? { scope: body.scope } : {}),
+        expires_in: expiresIn,
+        expires_at: Date.now() + Math.max(0, expiresIn) * 1000,
+    };
+}
+async function postForm(url, form, fetchImpl) {
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams(form),
+        });
+    }
+    catch (error) {
+        throw new CloudError('network_error', `Không kết nối được MONA ID: ${error instanceof Error ? error.message : String(error)}`, 'Kiểm tra MONACLOUD_ISSUER và kết nối mạng rồi thử lại.');
+    }
+    const body = asObject(await response.json().catch(() => ({})));
+    return { response, body };
+}
+export class AuthManager {
+    config;
+    env;
+    fetchImpl;
+    constructor(config, env = process.env, fetchImpl = fetch) {
+        this.config = config;
+        this.env = env;
+        this.fetchImpl = fetchImpl;
+    }
+    async discovery() {
+        try {
+            return await requestJson(`${this.config.issuer}/.well-known/openid-configuration`, {
+                fetchImpl: this.fetchImpl,
+            });
+        }
+        catch {
+            return {};
+        }
+    }
+    async loadToken() {
+        return readJsonFile(this.config.tokenFile);
+    }
+    async saveToken(token) {
+        await writePrivateJson(this.config.tokenFile, this.config.configDir, token);
+    }
+    async logout() {
+        let removed = false;
+        for (const path of [this.config.tokenFile, this.config.linksFile]) {
+            try {
+                await rm(path);
+                removed = true;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        return removed;
+    }
+    async refresh(token) {
+        if (!token.refresh_token) {
+            throw new CloudError('login_required', 'Token đã hết hạn và không có offline refresh token.', 'Chạy `monacloud-mcp login` để đăng nhập lại.');
+        }
+        const discovery = await this.discovery();
+        const endpoint = discovery.token_endpoint
+            || `${this.config.issuer}/protocol/openid-connect/token`;
+        const { response, body } = await postForm(endpoint, {
+            grant_type: 'refresh_token',
+            client_id: this.config.clientId,
+            refresh_token: token.refresh_token,
+        }, this.fetchImpl);
+        if (!response.ok) {
+            throw new CloudError('refresh_failed', typeof body.error_description === 'string' ? body.error_description : 'Không refresh được token MONA ID.', 'Chạy `monacloud-mcp login` để đăng nhập lại.', { status: response.status });
+        }
+        const refreshed = tokenFromResponse(body, token.refresh_token);
+        await this.saveToken(refreshed);
+        return refreshed;
+    }
+    async accessToken() {
+        if (this.env.MONACLOUD_TOKEN)
+            return this.env.MONACLOUD_TOKEN;
+        const stored = await this.loadToken();
+        if (!stored) {
+            throw new CloudError('login_required', 'Chưa có token MONA ID trên máy.', 'Chạy `monacloud-mcp login`, hoàn tất mã thiết bị rồi gọi lại tool.');
+        }
+        if (stored.expires_at > Date.now() + 30_000)
+            return stored.access_token;
+        return (await this.refresh(stored)).access_token;
+    }
+    async userinfo() {
+        const discovery = await this.discovery();
+        const endpoint = discovery.userinfo_endpoint
+            || `${this.config.issuer}/protocol/openid-connect/userinfo`;
+        return requestJson(endpoint, {
+            token: await this.accessToken(),
+            fetchImpl: this.fetchImpl,
+        });
+    }
+    async login(output = console.log) {
+        const discovery = await this.discovery();
+        const deviceEndpoint = discovery.device_authorization_endpoint
+            || `${this.config.issuer}/protocol/openid-connect/auth/device`;
+        const tokenEndpoint = discovery.token_endpoint
+            || `${this.config.issuer}/protocol/openid-connect/token`;
+        const started = await postForm(deviceEndpoint, {
+            client_id: this.config.clientId,
+            scope: this.config.scope,
+        }, this.fetchImpl);
+        if (!started.response.ok) {
+            throw new CloudError('device_flow_unavailable', typeof started.body.error_description === 'string'
+                ? started.body.error_description
+                : 'MONA ID không khởi tạo được device flow.', 'Kiểm tra client `monacloud-mcp` đã bật OAuth 2.0 Device Authorization Grant.', { status: started.response.status });
+        }
+        const device = started.body;
+        if (!device.device_code || !device.user_code || !device.verification_uri) {
+            throw new CloudError('invalid_device_response', 'MONA ID trả device-flow response không hợp lệ.', 'Kiểm tra cấu hình MONA ID rồi thử lại.');
+        }
+        output('Đăng nhập MONA Cloud');
+        output(`Mở: ${device.verification_uri_complete || device.verification_uri}`);
+        output(`Mã: ${device.user_code}`);
+        output('Đang chờ xác nhận…');
+        let intervalSeconds = Math.max(1, device.interval || 5);
+        const deadline = Date.now() + Math.max(1, device.expires_in) * 1000;
+        while (Date.now() < deadline) {
+            await sleep(intervalSeconds * 1000);
+            const polled = await postForm(tokenEndpoint, {
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                device_code: device.device_code,
+                client_id: this.config.clientId,
+            }, this.fetchImpl);
+            if (polled.response.ok) {
+                const token = tokenFromResponse(polled.body);
+                await this.saveToken(token);
+                const identity = await this.userinfo().catch(() => ({}));
+                output(`Đăng nhập xong${identity.email ? `: ${String(identity.email)}` : '.'}`);
+                return identity;
+            }
+            const error = polled.body.error;
+            if (error === 'authorization_pending')
+                continue;
+            if (error === 'slow_down') {
+                intervalSeconds += 5;
+                continue;
+            }
+            if (error === 'access_denied') {
+                throw new CloudError('access_denied', 'Người dùng đã từ chối đăng nhập.', 'Chạy lại `monacloud-mcp login` khi sẵn sàng.');
+            }
+            if (error === 'expired_token')
+                break;
+            throw new CloudError(typeof error === 'string' ? error : 'login_failed', typeof polled.body.error_description === 'string' ? polled.body.error_description : 'Đăng nhập thất bại.', 'Chạy lại `monacloud-mcp login`.', { status: polled.response.status });
+        }
+        throw new CloudError('device_code_expired', 'Mã đăng nhập đã hết hạn.', 'Chạy lại `monacloud-mcp login` để lấy mã mới.');
+    }
+    tokenId(token) {
+        try {
+            const payload = JSON.parse(Buffer.from(token.split('.')[1] || '', 'base64url').toString('utf8'));
+            if (typeof payload.jti === 'string' && payload.jti)
+                return payload.jti;
+            if (typeof payload.sub === 'string' && payload.sub)
+                return payload.sub;
+        }
+        catch {
+            // Opaque PATs intentionally fall through to the stable client identifier.
+        }
+        return this.config.clientId;
+    }
+}
+export async function readLinks(config) {
+    return (await readJsonFile(config.linksFile)) || {};
+}
+export async function writeLinks(config, links) {
+    await writePrivateJson(config.linksFile, config.configDir, links);
+}

package/dist/clients.d.ts

@@ -0,0 +1,33 @@
+import type { Config } from './config.js';
+import { AuthManager } from './auth.js';
+type JsonObject = Record<string, unknown>;
+export declare class CloudClients {
+    readonly config: Config;
+    readonly auth: AuthManager;
+    readonly fetchImpl: typeof fetch;
+    constructor(config: Config, auth: AuthManager, fetchImpl?: typeof fetch);
+    private billing;
+    balance(): Promise<unknown>;
+    ledger(cursor?: string, limit?: number): Promise<unknown>;
+    usage(period: string, product?: string): Promise<unknown>;
+    topup(amount: number, idempotencyKey?: string): Promise<unknown>;
+    budgetSet(body: {
+        scope: string;
+        scope_id: string;
+        limit_vnd: number;
+        period: string;
+    }): Promise<unknown>;
+    budgetGet(): Promise<unknown>;
+    tokenLimit(spendLimitVnd: number, period: string, tokenId?: string): Promise<unknown>;
+    spendGuard(): Promise<JsonObject>;
+    private vibecloudToken;
+    vibecloud<T = unknown>(path: string, options?: {
+        method?: string;
+        body?: unknown;
+    }): Promise<T>;
+    vibecloudLink(): Promise<JsonObject>;
+    monapayLink(): Promise<JsonObject>;
+    prices(): Promise<unknown>;
+    packages(): Promise<unknown>;
+}
+export {};