@liberseek/boft-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,125 @@
1
+ # BOFT Agent HTTP Contract Used by the CLI
2
+
3
+ This document records the shared contract expected by the BOFT CLI and MCP packages. The backend remains authoritative.
4
+
5
+ ## Authentication and transport
6
+
7
+ - Authentication: `Authorization: Bearer <dedicated Agent Token>`
8
+ - Content type: `application/json`
9
+ - Production transport: HTTPS
10
+ - Successful responses may be raw JSON or the BOFT envelope `{ "code": 0, "message": "success", "data": ... }`.
11
+ - Error responses may use the BOFT envelope, `{ code, message }`, `{ detail }`, or `{ error: { code, type, message } }`.
12
+
13
+ The token represents one user account. The endpoints do not expose administrator functions and do not authorize direct debits.
14
+
15
+ ## Endpoints
16
+
17
+ | CLI operation | HTTP contract |
18
+ | --- | --- |
19
+ | `balance`, `auth status` | `GET /api/v1/ee/agent/account` |
20
+ | `payment methods` | `GET /api/v1/ee/agent/payment-options` |
21
+ | `recharge create` | `POST /api/v1/ee/agent/payments` |
22
+ | `recharge status` | `GET /api/v1/ee/agent/payments/:id?wait_seconds=N` |
23
+ | `recharge cancel` | `POST /api/v1/ee/agent/payments/:id/cancel` |
24
+ | `group available` | `GET /api/v1/ee/agent/groups/available` + `GET /api/v1/ee/agent/groups/rates` |
25
+ | `key list` | `GET /api/v1/ee/agent/keys` |
26
+ | `key create` | `POST /api/v1/ee/agent/keys` |
27
+ | `key set-group` | `PUT /api/v1/ee/agent/keys/:id` |
28
+ | `auto-key list` | `GET /api/v1/ee/agent/auto-keys` |
29
+ | `auto-key create` | `POST /api/v1/ee/agent/auto-keys` |
30
+ | `auto-key set-routing` | `PUT /api/v1/ee/agent/auto-keys/:id` |
31
+ | `auto-key preview` | `GET /api/v1/ee/agent/auto-keys/:id/route-preview` |
32
+ | `setup codex --code` | `POST /api/v1/ee/agent/setup-grants/exchange` |
33
+
34
+ ## Codex setup grants
35
+
36
+ The website creates a short-lived, single-use grant bound to one user API Key, the `codex` target, and a transport variant. The CLI exchanges that code without an Agent Token:
37
+
38
+ ```http
39
+ POST /api/v1/ee/agent/setup-grants/exchange
40
+ Content-Type: application/json
41
+ X-BOFT-Agent-Client: cli
42
+ ```
43
+
44
+ ```json
45
+ {
46
+ "code": "BOFT-SETUP-CODE",
47
+ "target": "codex"
48
+ }
49
+ ```
50
+
51
+ The server atomically consumes a valid grant and returns:
52
+
53
+ ```json
54
+ {
55
+ "code": 0,
56
+ "data": {
57
+ "grant_id": "grant_123",
58
+ "target": "codex",
59
+ "variant": "responses",
60
+ "base_url": "https://supply.boft.ai/v1",
61
+ "model": "gpt-5.4",
62
+ "review_model": "gpt-5.4",
63
+ "api_key": "tk-sensitive",
64
+ "key_id": 42,
65
+ "provider_name": "BOFT"
66
+ }
67
+ }
68
+ ```
69
+
70
+ `variant` may be `responses` or `websocket`. The exchange endpoint must apply a short expiry, single-use semantics, rate limiting, and request-body redaction. It must never write the setup code or returned API Key to access, audit, or error logs. The returned key authorizes model requests only; it is not a BOFT Agent Token.
71
+
72
+ Create request:
73
+
74
+ ```http
75
+ Idempotency-Key: order-20260802-001
76
+ ```
77
+
78
+ ```json
79
+ {
80
+ "amount": "100.00",
81
+ "payment_method": "alipay"
82
+ }
83
+ ```
84
+
85
+ The CLI assumes `account.balance` is a string or number and accepts payment options as either an array or `{ "methods": [...] }`. A payment object must contain `status` and one of `order_id`, `id`, or `out_trade_no`; the following optional fields are rendered when present:
86
+
87
+ ```json
88
+ {
89
+ "id": "pay_123",
90
+ "status": "pending",
91
+ "amount": "100.00",
92
+ "currency": "CNY",
93
+ "payment_method": "alipay",
94
+ "qr_content": "https://payment-provider.example/qr/123",
95
+ "payment_url": "https://payment-provider.example/checkout/123",
96
+ "checkout_url": "https://payment-provider.example/checkout/123",
97
+ "expires_at": "2026-08-02T18:00:00Z"
98
+ }
99
+ ```
100
+
101
+ `payment_url` is preferred over `checkout_url`; when neither exists and `qr_content` itself is an HTTP(S) URL, the CLI preserves that value as the payment link in human output.
102
+
103
+ Key and AUTO Key operations use the same Agent Token transport and return ordinary BOFT user DTOs. The CLI depends on:
104
+
105
+ - paginated lists shaped like `{ items, total, page, page_size, pages }`
106
+ - regular key objects including at least `id`, `name`, `status`, and optional `group_id`
107
+ - AUTO Key objects using the same shape with optional `one_key_profile`
108
+ - group inspection using:
109
+
110
+ ```json
111
+ {
112
+ "groups": [{ "id": 12, "name": "GPT", "platform": "openai", "rate_multiplier": 1.0 }],
113
+ "user_rates": { "12": 0.8 }
114
+ }
115
+ ```
116
+
117
+ ## Status semantics
118
+
119
+ The CLI treats statuses as server-defined strings and does not infer payment success. `--wait` sends one long-poll request with `wait_seconds` from 1 to 25. It prints exactly the status object returned by the server.
120
+
121
+ Cancellation is a request, not proof of cancellation. The server response status is authoritative; the CLI does not claim success based only on HTTP completion.
122
+
123
+ ## Idempotency
124
+
125
+ The create endpoints for payments, regular API Keys, and AUTO Keys always receive an `Idempotency-Key` header. The CLI generates a UUID when omitted and returns the effective key as `Retry key` in human output or `idempotency_key` in JSON output. Reuse that key after an ambiguous timeout or network failure so the retry cannot create a second object. Agent integrations may instead supply and persist a stable key derived from the user's intent.
package/package.json ADDED
@@ -0,0 +1,46 @@
1
+ {
2
+ "name": "@liberseek/boft-cli",
3
+ "version": "0.1.0",
4
+ "description": "Secure BOFT CLI for Agent setup, balances, API Keys, and self-service recharge payments",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+ssh://git@github.com/LiberSeek/BOFT-CLI.git"
8
+ },
9
+ "publishConfig": {
10
+ "access": "public",
11
+ "registry": "https://registry.npmjs.org"
12
+ },
13
+ "type": "module",
14
+ "bin": {
15
+ "boft": "dist/index.js"
16
+ },
17
+ "files": [
18
+ "dist",
19
+ "docs",
20
+ "README.md"
21
+ ],
22
+ "engines": {
23
+ "node": ">=20"
24
+ },
25
+ "scripts": {
26
+ "build": "tsc -p tsconfig.build.json && node --input-type=module -e \"import { chmodSync } from 'node:fs'; chmodSync('dist/index.js', 0o755)\"",
27
+ "lint": "eslint .",
28
+ "typecheck": "tsc -p tsconfig.json --noEmit",
29
+ "test": "vitest run"
30
+ },
31
+ "dependencies": {
32
+ "@decimalturn/toml-patch": "^3.0.1",
33
+ "commander": "^14.0.0",
34
+ "qrcode-terminal": "^0.12.0"
35
+ },
36
+ "devDependencies": {
37
+ "@eslint/js": "9.32.0",
38
+ "@types/node": "20.19.9",
39
+ "@types/qrcode-terminal": "0.12.2",
40
+ "eslint": "9.32.0",
41
+ "typescript": "~5.6.3",
42
+ "typescript-eslint": "8.38.0",
43
+ "vitest": "^3.2.7"
44
+ },
45
+ "license": "AGPL-3.0-only"
46
+ }