openany-cli-dev 0.0.0-stage → 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.
Files changed (73) hide show
  1. package/README.md +461 -2
  2. package/bin/openany.js +3 -0
  3. package/package.json +27 -4
  4. package/skills/openany/SKILL.md +347 -0
  5. package/skills/openany/SKILL.zh-CN.md +496 -0
  6. package/skills/openany-provider/SKILL.md +26 -0
  7. package/skills/openany-provider/SKILL.zh-CN.md +26 -0
  8. package/skills/openany-provider/references/apis.md +60 -0
  9. package/skills/openany-provider/references/application.md +49 -0
  10. package/skills/openany-provider/references/application.zh-CN.md +51 -0
  11. package/skills/openany-provider/references/auth.md +59 -0
  12. package/skills/openany-provider/references/connections.md +38 -0
  13. package/skills/openany-provider/references/connections.zh-CN.md +33 -0
  14. package/skills/openany-provider/references/imports.md +38 -0
  15. package/skills/openany-provider/references/imports.zh-CN.md +55 -0
  16. package/skills/openany-provider/references/listing.md +29 -0
  17. package/skills/openany-provider/references/login.md +58 -0
  18. package/skills/openany-provider/references/login.zh-CN.md +59 -0
  19. package/skills/openany-provider/references/model-import.zh-CN.md +12 -0
  20. package/skills/openany-provider/references/models.md +107 -0
  21. package/skills/openany-provider/references/publishing.md +83 -0
  22. package/skills/openany-provider/references/publishing.zh-CN.md +81 -0
  23. package/skills/openany-provider/references/reviews.md +22 -0
  24. package/skills/openany-provider/templates/api-metadata.json +27 -0
  25. package/skills/openany-provider/templates/bindings.json +1 -0
  26. package/skills/openany-provider/templates/models-v2.json +545 -0
  27. package/skills/openany-provider/templates/models.json +10 -0
  28. package/skills/openany-provider/templates/provider-agent-api-template.json +697 -0
  29. package/skills/openany-provider/templates/seller-agent-api-import-template.json +839 -0
  30. package/skills/openany-provider/templates/seller-registration.json +26 -0
  31. package/src/auth-recovery.js +179 -0
  32. package/src/auth.js +1001 -0
  33. package/src/catalog.js +306 -0
  34. package/src/cli.js +601 -0
  35. package/src/config.js +260 -0
  36. package/src/errors.js +53 -0
  37. package/src/http.js +237 -0
  38. package/src/model-curl.js +359 -0
  39. package/src/model-materials.js +58 -0
  40. package/src/model-request.js +402 -0
  41. package/src/model-validation.js +56 -0
  42. package/src/models.js +188 -0
  43. package/src/native/config-acl.ps1 +34 -0
  44. package/src/native/connection-macos.js +109 -0
  45. package/src/native/connection-windows.ps1 +98 -0
  46. package/src/native/setup-macos.js +72 -0
  47. package/src/native/setup-windows.ps1 +83 -0
  48. package/src/native-prompt.js +85 -0
  49. package/src/payment-signing.js +362 -0
  50. package/src/prompt.js +69 -0
  51. package/src/provider-api-import-v2.js +72 -0
  52. package/src/provider-apis.js +3 -0
  53. package/src/provider-client.js +153 -0
  54. package/src/provider-connections.js +152 -0
  55. package/src/provider-import-format.js +289 -0
  56. package/src/provider-imports.js +402 -0
  57. package/src/provider-json.js +49 -0
  58. package/src/provider-model-import-v2.js +61 -0
  59. package/src/provider-models.js +253 -0
  60. package/src/provider-profile.js +65 -0
  61. package/src/provider-reviews.js +61 -0
  62. package/src/provider-state.js +176 -0
  63. package/src/provider.js +75 -0
  64. package/src/setup.js +201 -0
  65. package/src/topups.js +845 -0
  66. package/src/vendor/provider-apply/market-taxonomy.mjs +22 -0
  67. package/src/vendor/provider-apply/provenance.json +8 -0
  68. package/src/vendor/provider-apply/registration.mjs +151 -0
  69. package/src/vendor/provider-import/api-categories.json +29 -0
  70. package/src/vendor/provider-import/api-fields.json +33 -0
  71. package/src/vendor/provider-import/model-fields.json +44 -0
  72. package/src/wallet.js +213 -0
  73. package/src/windows-permissions.js +22 -0
package/README.md CHANGED
@@ -1,3 +1,462 @@
1
- # Temporary Holding Version
1
+ # OpenAny CLI
2
2
 
3
- 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.
3
+ 独立的 Node.js CLI,以一个 `openany-dev` 命令封装 OpenAny 的模型、聚合数据/工具、身份、Key 管理和充值接口。普通调用只需 API Key;缺少时在本地失败,不发起 HTTP 请求。
4
+
5
+ 后端及签名服务域固定为 `https://dev.openany.si`,模型调用统一使用网关 `https://api-dev.openany.si`,路径和查询参数取自公开目录的 `curlExample`。
6
+
7
+ 中文 skill 见 [SKILL.zh-CN.md](skills/openany/SKILL.zh-CN.md),英文版见 [SKILL.md](skills/openany/SKILL.md)。两份文件随 npm 包一起发布。
8
+
9
+ ## 安装
10
+
11
+ 需要 Node.js >=22。从 npm 安装即可获得全局 `openany-dev` 命令:
12
+
13
+ ```bash
14
+ npm install -g openany-cli-dev@latest --registry=https://registry.npmjs.org/
15
+ openany-dev --version
16
+ openany-dev --help
17
+ ```
18
+
19
+ 包名为 `openany-cli-dev`,命令名为 `openany-dev`。发行包附带 `skills/openany/SKILL.md`;全局安装目录可通过 `npm root -g` 查询,再将其中 `openany-cli-dev/skills/openany` 目录安装到 Agent 的 skill 目录。更新 CLI 时同步更新配套 skill。
20
+
21
+ 从源码开发或构建本地安装包:
22
+
23
+ ```bash
24
+ npm ci
25
+ npm test
26
+ npm pack
27
+ ```
28
+
29
+ ## 原生凭据配置窗口
30
+
31
+ macOS 和 Windows 桌面可分别打开 API Key 或钱包窗口,每次选择一条:
32
+
33
+ ```bash
34
+ openany-dev setup --api_key api_key --gui -j
35
+ openany-dev setup --wallet_connect wallet --gui -j
36
+ ```
37
+
38
+ API Key 窗口填写名称、密钥及是否启用;钱包窗口填写 Agent ID 和私钥,本地推导地址后由用户再次确认。输入通过子进程管道交给 CLI,标准输出只返回配置结果。Agent 不应读取或截图用户填写中的输入框。
39
+
40
+ 五分钟超时或取消时不保存。保存复用配置锁和原子写入,环境变量仍优先于本地设置。macOS 使用系统 AppKit,Windows 使用系统 PowerShell 和 WinForms,无需浏览器或编译器。Windows 使用当前用户专属目录 ACL,macOS 使用目录 0700、文件 0600。本地文件仍可能被同一账户下有读取权限的程序访问。
41
+
42
+ `--gui` 支持 `-j` 和无 TTY 调用,仅适用于 API Key、钱包配置。桌面不可用或系统策略阻止脚本时,移除 `--gui` 并让用户在自己的交互终端配置。邮箱、充值、`--prepare` 和 `--non-interactive` 不支持原生弹窗。未加 `--gui` 的检查行为保持不变。
43
+
44
+ ## 仅调用接口
45
+
46
+ 首次使用可以在终端运行交互配置:
47
+
48
+ ```bash
49
+ openany-dev setup
50
+ ```
51
+
52
+ 选择「API 调用」,填写 Key 名称、隐藏输入 API Key,并选择是否设为当前使用的 Key。也可使用 `openany-dev setup --api_key api_key` 直接进入。再次配置时,回车保留已有值,输入新值则更新;敏感值只提示「已配置」,不会回显。配置过程只读写本地文件,不发送请求。取消输入不会保存本次变更。
53
+
54
+ 将 `OPENANY_DEV_API_KEY` 注入 Agent 的安全凭证环境即可。也可以在终端执行 `openany-dev keys add --label main --activate`,隐藏输入已有 Key;如果环境已注入 Key,该命令直接保存它。无人值守可使用安全 stdin 和 `--stdin`,不要把 Key 放入命令行或日志。
55
+
56
+ ```bash
57
+ openany-dev status_check api_key -j
58
+ openany-dev balance -j
59
+ openany-dev discover -q "Get hot search data" -l 10 -j
60
+ openany-dev inspect --id API_ID -j
61
+ openany-dev run --id API_ID --query '{"limit":"10"}' -j
62
+ ```
63
+
64
+ API_ID 和参数必须依据实时目录。`status` 只检查本地配置,读取 `configured/missing`;它不会测试网络或 Key 有效性。缺少 Key 时先配置,不能继续发现或探测。用户明确只浏览公开目录时可以 `discover --public`。
65
+
66
+ `run --headers` accepts `Accept` and `Accept-Language` even when they are absent from the published inputs. Header names are case-insensitive. Published constraints still apply when these headers are declared; other unknown headers and reserved headers remain rejected.
67
+
68
+ ```bash
69
+ openany-dev run --id API_ID --headers '{"Accept":"application/json;version=20230203","Accept-Language":"zh-CN"}' -j
70
+ ```
71
+
72
+ 余额统一由 `GET /api/v1/agent-api-account` + Bearer API Key 查询,钱包及邮箱 Key 都适用。`run` 自动读取契约、验证参数、查余额并调用网关。`calls list/get` 查询当前 Key 的模型及数据/工具 API 用量记录(需要包含此修复的后端版本)。状态筛选只支持 `--status success` 或 `--status failed`;`--review-required` 不再支持,会在本地明确报错。
73
+
74
+ ## 查询调用与费用
75
+
76
+ ```bash
77
+ openany-dev calls list --status success --limit 20 -j
78
+ openany-dev calls list --status failed --limit 20 -j
79
+ openany-dev calls get --id 3535549d4364136631ff21dd06516e0a -j
80
+ ```
81
+
82
+ 替换为真实请求 ID。模型追踪 ID 与 UUID 可查询;32 位十六进制 UUID 与带连字符形式等价,其他 ID 精确匹配。`usageType` 区分 `model` / `api`;模型记录返回 `model`、`provider`,`apiId` 为 null。`chargedCostMicroUsd` 为该条用量的微美元金额,`monthlyUsageMicroUsd` 是累计值,不能据此推断某条请求的费用。
83
+
84
+ 列表默认最近 7 天,`--from` / `--to` 使用 UTC 毫秒时间格式,最大跨度 31 天;详情不受列表时间窗口限制。查询范围始终受当前账号和 Key 限制。更新后旧游标需从第一页重取。不存在的审核、结算阶段等元数据保持未知;不支持 `succeeded/ok/pending/error/unknown` 等状态别名。后端发布前,模型记录仍无法通过旧接口查询。
85
+
86
+ ## 调用模型
87
+
88
+ **0.2.0 升级说明:** 模型调用改为选择目录中的 curl 示例,旧的 `models run --protocol/--mode` 参数不再接受。升级后先用 `models examples` 读取供应商与示例 ID,再用 `--provider`、`--example` 选择请求。音频转写暂不支持。
89
+
90
+ Model examples prefer active playground `curlExample` records for the selected
91
+ model and provider. Price examples supplement missing method/path pairs; a
92
+ malformed playground example is reported and does not trigger price fallback.
93
+ Example output includes `source` and, when applicable, `playgroundId`.
94
+
95
+ Identity placeholders in JSON and multipart `model` / `route.provider` fields
96
+ are resolved from the selected model and provider: `{model}`, `<model>`,
97
+ `YOUR_MODEL`, `<model-for-this-model>`, and the corresponding provider forms.
98
+ URL path parameters `{model}` and `{provider}` are bound automatically.
99
+ Concrete conflicting identities still fail validation; ordinary text fields
100
+ are never rewritten. Refresh example IDs after upgrading.
101
+
102
+ 先读取模型和供应商对应的 curl 示例:
103
+
104
+ ```bash
105
+ openany-dev models examples --model doubao-seedance-2-0-fast --public -j
106
+ ```
107
+
108
+ 输出包含每条请求的 `id`、`provider`、请求模板、路径变量和解析错误。将选择的创建请求模板 `request.json` 保存为 `input.json`,按需求填写完整正文;不要把整个示例列表作为输入。
109
+
110
+ ```bash
111
+ openany-dev models run --model doubao-seedance-2-0-fast --provider ByteDance --example CREATE_EXAMPLE_ID -f input.json --dry-run
112
+ openany-dev models run --model doubao-seedance-2-0-fast --provider ByteDance --example CREATE_EXAMPLE_ID -f input.json
113
+ openany-dev models run --model doubao-seedance-2-0-fast --provider ByteDance --example QUERY_EXAMPLE_ID --path '{"task_id":"ACTUAL_TASK_ID"}'
114
+ ```
115
+
116
+ 从实时 `models examples` 输出复制示例 ID,不能把 `CREATE_EXAMPLE_ID` / `QUERY_EXAMPLE_ID` 原样提交。查询示例必须显式使用 `{task_id}` 变量;`YOUR_TASK_ID` 会报错,不自动猜测替换。任务 ID 由调用者根据服务响应取得;CLI 不自动提取 ID、轮询、重试或下载视频。
117
+
118
+ - `--provider` is optional. Multiple examples require `--example`; `--endpoint` only checks the selected path. Refresh IDs after example changes.
119
+ - `--input` / `--file` 提供完整 JSON 请求体,必须包含匹配的 `model`(URL 明确包含 `{model}` 时可省略)。不合并示例中的 prompt、messages 或其他默认值。Omit `route.provider` for server-side automatic routing. An explicit `--provider` binds routing; a concrete input provider is preserved and validated against the selected example. Unresolved provider placeholders are removed when no provider is selected.
120
+ - `--dry-run` 不需要 Key,仅查询公开目录并输出脱敏后的最终请求,不查询余额或执行模型。正式调用必须配置 API Key。GET 查询不检查余额;POST 创建请求发送前检查余额。
121
+ - multipart 目前支持 `/v1/images/edit` 和 `/v1/images/edits`,用 `--attach FIELD=FILE` 明确指定本地文件,可以重复同名字段;示例文件路径不会被读取。标量表单字段用 JSON 输入,数组表示重复字段;`route` 用 JSON 对象。音频转写明确不支持。
122
+ - `operations` 和 `parameters` 不再是执行前置条件;`models parameters` 仍可独立查询。`models run` 不接受旧的 `--protocol` / `--mode` 或额外的 `--method` / `--query` / `--headers` 覆盖。
123
+ - 解析支持现有 GET、JSON POST、图片编辑 multipart POST,以及引号、续行、注释和重复表单字段。非法 JSON、悬空续行、模型或供应商冲突、未知 curl 选项明确报错,不修正、不执行 shell。`--location` 会显示说明,CLI 仍不自动跟随重定向。
124
+
125
+ 详细操作见 [SKILL.md](skills/openany/SKILL.md)。
126
+
127
+ ## 按需启用高级能力
128
+
129
+ | 能力 | 必需配置 |
130
+ | ------------------------ | --------------------------------------------------------------------------------------------------- |
131
+ | 普通模型/API 调用 | `OPENANY_DEV_API_KEY` 或已保存的当前 Key |
132
+ | 钱包登录、创建/轮换 Key | `OPENANY_DEV_WALLET_ADDRESS`、`OPENANY_DEV_WALLET_PRIVATE_KEY` 或外部签名工具、稳定的 `OPENANY_DEV_AGENT_ID` |
133
+ | 邮箱登录、管理 Key | `OPENANY_DEV_EMAIL`、Agent 的邮箱访问权限,必要时选择 workspace |
134
+ | 充值 | 目标账户 API Key、对应钱包/邮箱会话、付款钱包和签名能力、明确的网络/单笔与累计额度/scope/有效期 |
135
+
136
+ `openany-dev setup` 在交互终端中提供三个配置场景,也可用以下参数直接选择:
137
+
138
+ - `--api_key api_key`:Key 名称、隐藏输入 API Key、是否激活;更新同名 Key 时替换原值。
139
+ - `--wallet_connect wallet`:隐藏输入钱包私钥,自动推导地址,再填写稳定的 Agent ID;已有值可回车保留。不提供外部签名配置选项。保存后按 [SKILL.md](skills/openany/SKILL.md) 的钱包流程继续:首次使用先执行 `openany-dev keys create --identity wallet --label agent-main -j` 自动注册账号,确认 Key 保存成功后再执行 `openany-dev auth wallet -j`;已有对应钱包 Key 时直接登录。
140
+ - `--email_login email`:填写邮箱地址;保存后使用 `openany-dev auth email send` 发送验证码,再用 `openany-dev auth email verify --code SIX_DIGITS` 登录。
141
+
142
+ `openany-dev status_check wallet|email|api_key|payment` 只检查本地配置。参数后的 wallet、email 和 api_key 是固定名称。旧版 `setup --scenario …` 和 `status --scenario …` 均可继续使用,JSON 中的 `scenario` 保留原值。`setup -j`、`setup --non-interactive`、非终端输入、`setup --prepare` 和 `setup --scenario payment` 保留原有只检查行为,不等待输入或保存。外部签名的现有命令检查可加 `--prepare`;充值检查指定 `--identity wallet|email`。配置状态不代表已登录、Key 有效或取得付款授权。
143
+
144
+ EVM private keys use 64 hexadecimal characters (32 bytes), with or without a `0x` prefix. MetaMask exports can be pasted directly into `setup`; environment-based keys accept both formats too. Solana requires a Base58-encoded 64-byte secret key.
145
+
146
+ 私钥可通过 `setup` 保存到现有受限凭据文件,也可从 Secret 环境读取。后续命令自动读取本地钱包、Agent ID 和邮箱配置;非空环境变量优先,`setup` 结果中的 `environmentOverrides` 列出覆盖本地配置的变量名。CLI 不连接邮箱:验证码由 Agent 的已授权邮箱工具读取,再交给 `auth email verify --code SIX_DIGITS`。
147
+
148
+ 钱包命令:`auth wallet`、`keys create|rotate --identity wallet --label LABEL`。外部签名先 `--prepare`,然后以相同命令加 `--challenge-id ID --signature-file FILE`;身份签名文件是原始签名文本。
149
+
150
+ 邮箱命令:`auth email send|verify|refresh|workspace`;远端 Key 使用 `keys remote list|get|create|revoke`。邮箱轮换是创建新 Key、切换调用方、验证、撤销旧 Key,CLI 不自动撤销旧 Key。环境 `OPENANY_DEV_API_KEY` 优先于本地 Key,轮换后须同步更新环境 Secret。
151
+
152
+ 充值使用 `topups authorize → create → pay → get`,完整命令和外部签名格式见 [SKILL.md](skills/openany/SKILL.md)。额度以实际付款金额含手续费计;待付款订单也占用预留额度。同一 intent 不能更换金额、目标或网络;创建不明用原参数加 `--resume`,付款提交不明只查询。CLI 不执行自动充值循环,也不自动提高授权额度。
153
+
154
+ ## 输出、持久化与恢复
155
+
156
+ - `-j` 输出紧凑 JSON;`-o FILE` 保存结果,拒绝覆盖现有文件。正文 `-i JSON` 或 `-f FILE`,路径/查询/附加头用 JSON 参数。
157
+ - 关键错误写入 stderr 并退出 1,包含错误码、说明以及可用的 requestId/status;无自动 HTTP 重试。stdout 不打印 Key 或私钥。
158
+ - 本地配置默认 `~/.config/openany-dev/credentials.json`,可由 `OPENANY_DEV_CONFIG_DIR` 指定隔离目录;沿用文件 0600、目录 0700 的权限机制,无新增权限选项。包含 Key、保存的钱包私钥和地址、Agent ID、邮箱、会话、付款策略和 intent,不能提交或分享。文件不额外加密;写入持锁,崩溃遗留锁需确认进程结束后人工清理。
159
+ - 服务已完成身份变更但本地保存失败时,会保留恢复文件。仅使用 CLI 返回的路径执行 `auth recover --file PATH`,不要重新发起创建/轮换。
160
+ - 支付签名文件为 JSON:EVM `{ "signature": "..." }`,Solana `{ "transaction": "BASE64..." }`。签名工具负责签署 CLI 导出的确切内容。
161
+ - SSE 完整接收并验证结束事件后返回,暂不实时显示 token。聚合调用是同步流程,不提供停止任务或通用异步模型轮询。
162
+ - 音频生成要求 `-o`;其他二进制响应未指定输出时,保存为受限临时文件并返回路径。
163
+
164
+ ## 验证与部署边界
165
+
166
+ ```bash
167
+ npm test
168
+ npm run check
169
+ npm pack --dry-run
170
+ ```
171
+
172
+ 测试使用注入的 HTTP transport 和无资金的固定测试密钥,覆盖缺 Key 零网络请求、契约、身份隔离、真实本地签名、充值额度及不确定结果恢复。不进行实际付款、数据库修改或收费 API 测试。
173
+
174
+ 后端签名域必须配置为 `https://dev.openany.si`。仓库 Dockerfile 默认值同步修改不等于在线服务已部署;旧域冻结订单不能由 CLI 改签名域绕过验证。部署前应处理原有订单和环境覆盖项。
175
+
176
+ ## Skill documentation maintenance
177
+
178
+ `skills/openany/SKILL.md` is the source for the packaged skill and the website copies. After updating it, synchronize the website checkout and verify the result:
179
+
180
+ ```bash
181
+ npm run sync:skill -- ../openany-interface/openany-interface
182
+ npm run sync:skill -- ../openany-interface/openany-interface --check
183
+ ```
184
+
185
+ The path must point to the `openany-web` project. The command validates that the skill uses the latest CLI release channel and updates `public/SKILL.md` and `docs/skills/openany/SKILL.md`. In the website checkout, run `npm run check:agent-docs` to verify that guides and client recipes also use the latest release channel without pinning a CLI version. Website builds run that check automatically. Commit both repositories together for a documentation release; these commands do not publish packages or deploy the website.
186
+
187
+ ### New email registration
188
+
189
+ `openany-dev auth email send -j` reads the configured email and sends the code first.
190
+ For a new email, `registrationRequired: true` and `verificationUrl` identify the
191
+ browser step. Show the full URL (including its fragment) to the user and have them
192
+ complete Turnstile. The link is also printed to stderr in JSON mode. Then verify
193
+ the current six-digit email code with `openany-dev auth email verify --code SIX_DIGITS -j`
194
+ in the user's terminal or using an authorized mailbox tool. Never ask for the code
195
+ in chat. Existing accounts proceed directly to code verification without Turnstile.
196
+
197
+ Both proofs are required to create a new account. A confirmed
198
+ `HUMAN_VERIFICATION_REQUIRED` response allows retrying the same code after browser
199
+ approval. Expiry or resending invalidates the old challenge and browser link.
200
+
201
+ ## Provider onboarding and direct publication
202
+
203
+ Provider management shares the existing CLI binary and email login, under the
204
+ `seller` command group. The old `openany-dev provider` command is no longer supported. It requires an account email session, not a consumer API
205
+ key or workspace. Existing consumer commands and the `openany-dev` consumer Skill are
206
+ unchanged. The new Skill is `skills/openany-provider/SKILL.md`.
207
+
208
+ ```sh
209
+ openany-dev auth email send --email provider@example.test -j
210
+ # Read the fresh verification email using an already authorized mailbox connector.
211
+ openany-dev auth email verify --code SIX_DIGITS -j
212
+ openany-dev seller applications list -j
213
+ openany-dev seller status --application APPLICATION_ID -j
214
+ openany-dev seller schema --type model --application APPLICATION_ID -j
215
+ ```
216
+
217
+ Always select the supplier explicitly. The CLI never chooses the newest account
218
+ or supplier, installs a mailbox connector, or grants mailbox access. Capability
219
+ checks require `seller-resource-reviews-v1`; regional or unavailable API support
220
+ is reported rather than falling back to anonymous registration.
221
+
222
+ To apply as a new supplier, prepare registration JSON matching the website's
223
+ supplier application form, then submit it with the same account:
224
+
225
+ ```sh
226
+ openany-dev seller applications create --file registration.json --operation supplier-apply-1 -j
227
+ ```
228
+
229
+ The registration file uses `seller`, `seller_types`, `resource`, `connection`,
230
+ `endpoints`, and `consents`. Enter a unique `seller.slug` (for example,
231
+ `hong3seller`) along with the supplier name and email. The CLI validates the
232
+ slug and maps `seller`/`seller_types` to the backend's
233
+ `provider`/`provider_types` fields before calling
234
+ `POST /api/v1/provider/account/registrations`. Use your real details and
235
+ explicit consents; never include credentials.
236
+ The backend applies the website's validation and application approval workflow.
237
+ The returned `reg_...` ID identifies a registration, not an `--application` UUID.
238
+ Check its review status on the website; after administrator approval, run
239
+ `seller applications list` and select the resulting supplier UUID.
240
+ Submission does not admit the supplier or authorize resource publication.
241
+ If submission times out, check the website before any further submission.
242
+ Registration creation is non-idempotent: the CLI blocks replay of an uncertain
243
+ operation even with `--resume`. Do not use a new operation to bypass this check.
244
+
245
+ To create a connection with a native macOS or Windows dialog, run:
246
+
247
+ ```sh
248
+ openany-dev seller connections create --application APPLICATION_ID --operation connection-create --gui -j
249
+ ```
250
+
251
+ The dialog collects the label, base URL, authentication type, optional query/path
252
+ parameter name, and a masked API key. It uses the key entered in the dialog,
253
+ not `OPENANY_DEV_UPSTREAM_API_KEY`. The key is submitted to OpenAny without being
254
+ saved locally or printed. Cancellation or a five-minute timeout submits nothing.
255
+ Invalid fields display a safe error and reopen the form for correction.
256
+ `--gui` supports non-terminal invocation and JSON output on a desktop, but cannot
257
+ be combined with `--file`, `--input`, `--stdin`, `--prepare`, or `--non-interactive`.
258
+ Both `--application` and `--operation` remain required. Linux/headless environments
259
+ must use terminal or scripted creation; GUI failures do not silently fall back.
260
+
261
+ To create a connection interactively in your terminal, run:
262
+
263
+ ```sh
264
+ openany-dev seller connections create --application APPLICATION_ID --operation connection-create
265
+ ```
266
+
267
+ Enter the connection label, base URL and authentication type (number or name).
268
+ Query/path authentication also asks for the parameter name. If authentication
269
+ requires a key, the CLI uses `OPENANY_DEV_UPSTREAM_API_KEY` when set, otherwise it
270
+ prompts with hidden input. Ctrl-C or EOF cancels without creating a connection.
271
+ `--application` and `--operation` remain required command-line parameters.
272
+ Explicit `--file`/`--input`, `--stdin`, `-j`, `--non-interactive` and non-terminal
273
+ input do not start the interactive form; supply JSON configuration in those modes.
274
+
275
+ For scripted creation, create a non-secret connection configuration file containing `label`, `baseUrl`,
276
+ `authType` and, where required, `authParamName`. Supply the upstream key using
277
+ `OPENANY_DEV_UPSTREAM_API_KEY` or `--stdin`, never JSON or a command argument:
278
+
279
+ ```sh
280
+ openany-dev seller connections create --application APPLICATION_ID --file connection.json --stdin --operation connection-create -j
281
+ openany-dev seller models create --application APPLICATION_ID --file model.json --operation model-create -j
282
+ openany-dev seller models verify --application APPLICATION_ID --id MODEL_ID --file verification.json --operation model-route-test -j
283
+ openany-dev seller models publish --application APPLICATION_ID --id MODEL_ID --file publication.json --operation model-publish -j
284
+ openany-dev seller models get --application APPLICATION_ID --id MODEL_ID -j
285
+ ```
286
+
287
+ Provider JSON writes accept either `--file PATH` or `--input JSON`, never both.
288
+ `SECRET_IN_DOCUMENT` may be raised by the CLI locally before any backend call;
289
+ its `field` identifies the offending value and `stage: "local"` identifies the scan.
290
+ Omit authentication headers from `curlExample`, including Bearer placeholders;
291
+ configure authentication through the connection. Do not replace placeholders with real keys.
292
+
293
+ For `models verify`, `request.path` must be an empty object `{}` when supplied,
294
+ never a URL string such as `"/v1/chat/completions"` or a nonempty parameter map.
295
+ The CLI rejects invalid values locally with `INVALID_INPUT` and
296
+ `field: "request.path"`. The actual request path comes from the saved
297
+ `price.upstreamPath[endpointIndex]`; `endpointIndex` is zero-based. Read the saved
298
+ model first and use its current version, route ID and upstream revision:
299
+
300
+ ```json
301
+ {
302
+ "expectedVersion": "SAVED_MODEL_VERSION",
303
+ "routeId": "SAVED_ROUTE_ID",
304
+ "expectedUpstreamRevision": 1,
305
+ "endpointIndex": 0,
306
+ "request": {
307
+ "path": {},
308
+ "query": {},
309
+ "headers": { "Content-Type": "application/json" },
310
+ "body": {
311
+ "messages": [{ "role": "user", "content": "Ping test" }],
312
+ "max_tokens": 5
313
+ }
314
+ }
315
+ }
316
+ ```
317
+
318
+ Replace the version, route ID, revision, endpoint index and test body with the
319
+ saved configuration and authorized test inputs. Model verification uses the saved
320
+ upstream model identity. This empty-path restriction applies only to models;
321
+ `apis verify` can use a path parameter object required by its saved API template.
322
+
323
+ Use `apis` instead of `models` for API resources. Every write requires a stable
324
+ `--operation NAME` (1–128 letters, digits, dots, underscores or hyphens). Local
325
+ operation records retain its idempotency key, account, supplier and non-secret
326
+ receipt. The name is bound to the request method, target path and JSON payload.
327
+ Reusing it for changed input produces `IDEMPOTENCY_CONFLICT`; reconcile the original
328
+ outcome first. An identical completed operation returns its locally saved result
329
+ without another write, so it does not run a fresh test. Do not change names on every retry.
330
+ For an uncertain resource create, repeat the exact command with the same operation
331
+ and `--resume`. Changed payloads require a new operation after the old result is
332
+ known. An uncertain PUT or verification is never automatically repeated; read
333
+ and reconcile it. Known verification IDs can be queried with `models|apis get
334
+ --verification-id ID`. A session change stops in-flight work. New runs must still
335
+ use the correct account and supplier.
336
+
337
+ Supplier admission remains required. Once admitted, configure and verify each
338
+ resource, then publish directly without a separate human review. Model publication
339
+ uses `expectedVersion` and `verificationIds`; API publication uses `expectedRevision`,
340
+ `expectedUpstreamRevision`, and `verificationId`. Authorized edits use current
341
+ versions and no longer require review withdrawal. Read activation and runtime
342
+ synchronization separately. Historical review queries remain available.
343
+
344
+ ### Batch JSON imports
345
+
346
+ API inputs can use the website `provider-agent-api-v2` template directly or
347
+ OpenAPI 3.x JSON with metadata. For skills, bots and services, fill both
348
+ `includedContentHtml` and `usageInstructionsHtml`; ordinary APIs may omit them.
349
+ OpenAPI conversion reuses the existing pinned
350
+ `@openany/provider-apply` converter per operation, avoiding its historical 20-item
351
+ truncation. Unsupported methods and references are reported explicitly. Model
352
+ inputs use `{schemaVersion:1,items:[{itemId,configuration:{price,routes}}]}`. Both
353
+ support 1–100 items and files up to 8 MiB. Decimal prices are strings; numeric
354
+ JSON literals that would lose precision are rejected before parsing.
355
+
356
+ ```sh
357
+ openany-dev seller imports preview --type api --file openapi.json --metadata-file metadata.json --bindings-file bindings.json --application APPLICATION_ID -j
358
+ openany-dev seller imports preview --type api --file seller-agent-api-import-template.json --bindings-file bindings.json --application APPLICATION_ID -j
359
+ openany-dev seller imports preview --type model --file models.json --bindings-file bindings.json --application APPLICATION_ID -j
360
+ openany-dev seller imports run --batch BATCH_ID --application APPLICATION_ID -j
361
+ openany-dev seller imports status --batch BATCH_ID --application APPLICATION_ID -j
362
+ openany-dev seller imports resume --batch BATCH_ID --bindings-file bindings.json --application APPLICATION_ID -j
363
+ ```
364
+
365
+ API item IDs are `METHOD /path`. OpenAPI metadata uses
366
+ `{schemaVersion:1,items:[{itemId,configuration:{requestContentType,config,...}}]}`.
367
+ It supplies the complete execution config (including inputs, mappings, billing
368
+ and explicit charge_condition). Name/description can come from OpenAPI;
369
+ method/path cannot be silently overridden. OpenAPI parameters are not guessed
370
+ into gateway mappings or pricing. `charge_condition:null` explicitly accepts the
371
+ server's HTTP-success default.
372
+
373
+ Bindings use `{schemaVersion:1,items:[{itemId,upstreamKeyId}]}` for APIs or
374
+ `{schemaVersion:1,items:[{itemId,routes:[{index,upstreamKeyId}]}]}` for models. Files
375
+ must contain only items in that batch. Templates under
376
+ `skills/openany-provider/templates/` are intentionally incomplete, not quotes or
377
+ production defaults. Ask for actual pricing and authorization before use.
378
+
379
+ Preview does not create resources or call upstreams. Run/resume only creates
380
+ drafts. Missing connections are local `waiting_connection` items; other items
381
+ continue. Prepare or select an owned connection, then resume with its binding.
382
+ Missing credentials never imply `authType=none`. Summaries distinguish readiness,
383
+ missing information, created, conflict, failure and unknown results. Created
384
+ items are not repeated, unknown writes retain their exact original request, and
385
+ changed known failed inputs get new keys. No name-based adoption or overwriting
386
+ of existing resources is performed. After draft creation, verification and
387
+ submission remain separate, authorized, per-resource steps.
388
+
389
+ The local batch binds the account and supplier and uses the existing restricted
390
+ credentials file (0600). Secret-bearing documents are rejected before storage.
391
+ CLI tests use synthetic credentials and mocked HTTP; they do not prove deployment
392
+ readiness, mailbox delivery, real upstream compatibility or administrator review.
393
+
394
+ Sync the complete Provider Skill into the website with:
395
+
396
+ ```sh
397
+ npm run sync:provider-skill -- ../openany-interface/openany-interface
398
+ npm run sync:provider-skill -- ../openany-interface/openany-interface --check
399
+ ```
400
+
401
+ This writes `public/skills/openany-provider/` and preserves the consumer
402
+ `public/SKILL.md`. Publishing an npm package or deploying the website is a separate
403
+ release action.
404
+
405
+ ### Provider contract checks
406
+
407
+ The CLI includes the two required provider contract modules under `src/vendor/provider-apply/`, so public installation does not require GitHub credentials. `provenance.json` records upstream commit `a46aae4a821b6ebe268e35376755b62769389b3a` and SHA-256 hashes. When updating these modules, copy both files from the same reviewed upstream commit, update the provenance, and rerun the import tests. Provider server code is not included.
408
+
409
+ `test/fixtures/provider-resource-reviews.json` is copied from the backend's
410
+ versioned contract fixture. `test/fixtures/provider-schemas.json` is generated by
411
+ calling the backend's `providerreviews.Schema` for all six schema kinds (the
412
+ initial export used a temporary Go overlay and did not modify backend sources).
413
+ The contract tests exercise CLI submissions against those actual field names and
414
+ version constraints, preserve source/target publication versions, and reject
415
+ silent rebasing after a stale submission. They also cover nullable local
416
+ connections, explicit default charge conditions, and server auth-type spellings.
417
+
418
+ After changing backend contracts, regenerate the schema export and compare it:
419
+
420
+ ```sh
421
+ node scripts/check-provider-contract.mjs ../openany-backend/openany-backend --schemas-file /path/to/exported-provider-schemas.json
422
+ ```
423
+
424
+ The check reads both repositories; it does not deploy, connect to production, or
425
+ rewrite fixtures. Schema snapshots do not substitute for backend validation or
426
+ cross-repository end-to-end tests.
427
+
428
+ ### Exact balance display
429
+
430
+ `openany-dev balance -j` preserves the backend's `availableMicroUsd` integer string and adds `availableUsd` and `availableUsdFormatted`. These are exact USD strings calculated with integer arithmetic (1 USD = 1,000,000 microUSD), with two to six decimal places. Display `availableUsdFormatted` directly; use the raw microUSD value for balance and budget comparisons. Invalid raw amounts fail with `INVALID_RESPONSE` on stderr instead of emitting a fabricated dollar amount.
431
+
432
+ ### Model request materials and validation
433
+
434
+ `models examples` and `models run` resolve materials for the selected supplier:
435
+ Verified/Direct use imported candidate formats, then compatible Playground records;
436
+ Community uses compatible Playground records, then that supplier's ModelPrice.
437
+ Embedded Playgrounds are preferred. Older catalog responses without supplier metadata
438
+ retain legacy source selection. A supplier's own ModelPrice cURL defines its public
439
+ endpoint even if its upstream path differs; a schema for that other path is not reused.
440
+
441
+ Supply the complete request with `--input` or `--file`. Requests are not merged with
442
+ example bodies. JSON Schema validates business parameters without coercion, default
443
+ insertion, or removal of unknown fields. Explicit field constraints are used when no
444
+ JSON Schema exists. With only an example, validation is basic: example values do not
445
+ make fields required or restrict values. JSON Schema format annotations are not checked.
446
+ Invalid schemas fail explicitly. Gateway fields (`model`, `route`, `route_mode`) are
447
+ handled separately from business schemas. Responses and response examples never define
448
+ request constraints.
449
+
450
+ `models run --dry-run` reports `source`, `validation.level`, validation notices and the
451
+ final request, without querying balance or executing a model. Parameter failures use
452
+ `PARAMETER_VALIDATION_FAILED` with JSON-pointer paths. `--endpoint` filters before
453
+ ambiguity is checked; use `--example` when more than one request still matches.
454
+ GET query examples accept `--path` only, not creation bodies or uploads. Multipart
455
+ example files are never read automatically, and appearing in an example does not make
456
+ an attachment required; explicit constraints establish requirements.
457
+
458
+ ## Log out or switch accounts
459
+
460
+ When the user requests logout or account switching, explain that this clears **all accounts in the current local configuration**, then run `openany-dev logout -j`. First let any ongoing login, registration, or payment command finish or cancel it safely; do not start concurrent account operations. The CLI moves the complete credentials file to a uniquely named backup in the same configuration directory, retaining restricted permissions. It does not revoke server-side keys, sessions, or accounts, or cancel payments. Always show the returned `backupPath`; if null, report that no local configuration file existed. The backup contains credentials: never read it into chat, upload it, or display its contents.
461
+
462
+ Check `environmentOverrides`: if nonempty, show variable names only and ask the user to remove them from the actual calling environment before switching accounts. Do not claim complete logout while they remain. Once logout is complete, offer API Key, wallet, and email setup using a selection form when available, with text choices as fallback; use the existing setup flow for the selected method. If the user requested logout only, stop after reporting the result. Check CLI help for `logout` support and update if needed; never substitute unbacked file deletion.
package/bin/openany.js ADDED
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ import { main } from "../src/cli.js";
3
+ process.exitCode = await main(process.argv.slice(2));
package/package.json CHANGED
@@ -1,6 +1,29 @@
1
1
  {
2
2
  "name": "openany-cli-dev",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "OpenAny command-line client for internal dev testing",
5
+ "type": "module",
6
+ "engines": {
7
+ "node": ">=22"
8
+ },
9
+ "bin": {
10
+ "openany-dev": "bin/openany.js"
11
+ },
12
+ "files": [
13
+ "bin",
14
+ "src",
15
+ "README.md",
16
+ "skills"
17
+ ],
18
+ "dependencies": {
19
+ "@solana/web3.js": "1.98.4",
20
+ "ajv": "8.17.1",
21
+ "bs58": "6.0.0",
22
+ "ethers": "6.17.0"
23
+ },
24
+ "license": "UNLICENSED",
25
+ "publishConfig": {
26
+ "access": "public",
27
+ "registry": "https://registry.npmjs.org/"
28
+ }
29
+ }