openany-cli-dev 0.0.0-stage → 0.1.1
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.
- package/README.md +472 -2
- package/bin/openany.js +3 -0
- package/package.json +27 -4
- package/skills/openany/SKILL.md +353 -0
- package/skills/openany/SKILL.zh-CN.md +496 -0
- package/skills/openany-provider/SKILL.md +26 -0
- package/skills/openany-provider/SKILL.zh-CN.md +26 -0
- package/skills/openany-provider/references/apis.md +60 -0
- package/skills/openany-provider/references/apis.zh-CN.md +55 -0
- package/skills/openany-provider/references/application.md +49 -0
- package/skills/openany-provider/references/application.zh-CN.md +51 -0
- package/skills/openany-provider/references/auth.md +3 -0
- package/skills/openany-provider/references/auth.zh-CN.md +3 -0
- package/skills/openany-provider/references/connections.md +36 -0
- package/skills/openany-provider/references/connections.zh-CN.md +36 -0
- package/skills/openany-provider/references/imports.md +57 -0
- package/skills/openany-provider/references/imports.zh-CN.md +57 -0
- package/skills/openany-provider/references/listing.md +29 -0
- package/skills/openany-provider/references/listing.zh-CN.md +11 -0
- package/skills/openany-provider/references/login.md +57 -0
- package/skills/openany-provider/references/login.zh-CN.md +57 -0
- package/skills/openany-provider/references/model-import.md +11 -0
- package/skills/openany-provider/references/model-import.zh-CN.md +11 -0
- package/skills/openany-provider/references/models.md +107 -0
- package/skills/openany-provider/references/models.zh-CN.md +68 -0
- package/skills/openany-provider/references/publishing.md +40 -0
- package/skills/openany-provider/references/publishing.zh-CN.md +40 -0
- package/skills/openany-provider/references/reviews.md +22 -0
- package/skills/openany-provider/references/reviews.zh-CN.md +20 -0
- package/skills/openany-provider/templates/api-metadata.json +27 -0
- package/skills/openany-provider/templates/bindings.json +1 -0
- package/skills/openany-provider/templates/models-v2.json +545 -0
- package/skills/openany-provider/templates/models.json +10 -0
- package/skills/openany-provider/templates/provider-agent-api-template.json +697 -0
- package/skills/openany-provider/templates/seller-agent-api-import-template.json +822 -0
- package/skills/openany-provider/templates/seller-registration.json +26 -0
- package/src/auth-recovery.js +179 -0
- package/src/auth.js +1001 -0
- package/src/catalog.js +306 -0
- package/src/cli.js +605 -0
- package/src/config.js +260 -0
- package/src/errors.js +53 -0
- package/src/http.js +238 -0
- package/src/model-curl.js +359 -0
- package/src/model-materials.js +58 -0
- package/src/model-request.js +402 -0
- package/src/model-validation.js +56 -0
- package/src/models.js +188 -0
- package/src/native/config-acl.ps1 +34 -0
- package/src/native/connection-macos.js +109 -0
- package/src/native/connection-windows.ps1 +98 -0
- package/src/native/setup-macos.js +72 -0
- package/src/native/setup-windows.ps1 +83 -0
- package/src/native-prompt.js +85 -0
- package/src/payment-signing.js +362 -0
- package/src/prompt.js +69 -0
- package/src/provider-api-import-v2.js +72 -0
- package/src/provider-apis.js +3 -0
- package/src/provider-client.js +153 -0
- package/src/provider-connections.js +152 -0
- package/src/provider-import-format.js +289 -0
- package/src/provider-imports.js +402 -0
- package/src/provider-json.js +49 -0
- package/src/provider-model-import-v2.js +61 -0
- package/src/provider-models.js +253 -0
- package/src/provider-profile.js +65 -0
- package/src/provider-reviews.js +61 -0
- package/src/provider-state.js +176 -0
- package/src/provider.js +75 -0
- package/src/setup.js +201 -0
- package/src/tasks.js +53 -0
- package/src/topups.js +845 -0
- package/src/vendor/provider-apply/market-taxonomy.mjs +22 -0
- package/src/vendor/provider-apply/provenance.json +8 -0
- package/src/vendor/provider-apply/registration.mjs +151 -0
- package/src/vendor/provider-import/api-categories.json +29 -0
- package/src/vendor/provider-import/api-fields.json +33 -0
- package/src/vendor/provider-import/model-fields.json +44 -0
- package/src/wallet.js +213 -0
- package/src/windows-permissions.js +22 -0
package/README.md
CHANGED
|
@@ -1,3 +1,473 @@
|
|
|
1
|
-
#
|
|
1
|
+
# OpenAny CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
OpenAny CLI is a standalone Node.js CLI that provides access to OpenAny models, aggregated data and tools, identity, API key management, and top-ups through a single `openany-dev` command. Standard calls require only an API key. If the key is missing, the CLI fails locally before sending an HTTP request.
|
|
4
|
+
|
|
5
|
+
The backend and signing origin are fixed at `https://dev.openany.si`. Model calls use the `https://api-dev.openany.si` gateway and take their paths and query parameters from the public catalog's `curlExample`.
|
|
6
|
+
|
|
7
|
+
The skill is available in [Chinese](skills/openany/SKILL.zh-CN.md) and [English](skills/openany/SKILL.md). Both files ship with the npm package.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
Node.js 22 or later is required. Install from npm to make the `openany-dev` command available globally:
|
|
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
|
+
The npm package is `openany-cli-dev`, and the command is `openany-dev`. The package includes `skills/openany/SKILL.md`. Run `npm root -g` to locate the global installation directory, then install `openany-cli-dev/skills/openany` from that directory into your agent's skill directory. Update the skill whenever you update the CLI.
|
|
20
|
+
|
|
21
|
+
To develop from source or build a local installation package, run:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm ci
|
|
25
|
+
npm test
|
|
26
|
+
npm pack
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Native credential setup dialogs
|
|
30
|
+
|
|
31
|
+
On macOS and Windows desktops, choose one of these commands to open the API key or wallet dialog:
|
|
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
|
+
In the API key dialog, enter a label and key, then choose whether to activate it. In the wallet dialog, enter the agent ID and private key. The CLI derives the address locally and asks the user to confirm it. The dialog sends input to the CLI through a subprocess pipe, and stdout contains only the setup result. Agents must avoid reading or taking screenshots of the input fields while the user fills them in.
|
|
39
|
+
|
|
40
|
+
Canceling or reaching the five-minute timeout discards the input. Saving uses the existing configuration lock and atomic writes. Environment variables still take precedence over local settings. macOS uses the system AppKit, and Windows uses PowerShell and WinForms. Both work without a browser or compiler. Windows uses a directory ACL restricted to the current user. macOS uses mode 0700 for the directory and 0600 for the file. Programs running under the same account can still read local files if they have read access.
|
|
41
|
+
|
|
42
|
+
`--gui` supports `-j` and invocation without a TTY for API key and wallet setup. If the desktop is unavailable or system policy blocks scripts, remove `--gui` and let the user configure credentials in their own interactive terminal. Email and top-up setup, `--prepare`, and `--non-interactive` are unavailable in native dialogs. CLI checks behave as before when `--gui` is omitted.
|
|
43
|
+
|
|
44
|
+
## Making API calls
|
|
45
|
+
|
|
46
|
+
On first use, run interactive setup in your terminal:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
openany-dev setup
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Select the API calls option, enter a key label and the API key using masked input, then choose whether to make it the active key. Run `openany-dev setup --api_key api_key` to open this option directly. When updating an existing configuration, press Enter to keep the current value or enter a new value to replace it. The prompt indicates when a sensitive value is already configured without displaying it. Setup reads and writes local files only. Canceling discards the changes.
|
|
53
|
+
|
|
54
|
+
Set `OPENANY_DEV_API_KEY` in the agent's secure credential environment. You can also run `openany-dev keys add --label main --activate` in a terminal and enter an existing key using masked input. If the key is already set in the environment, the command saves it directly. For unattended setup, pass the key through secure standard input with `--stdin` and keep it out of command arguments and logs.
|
|
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
|
+
Use the API ID and parameters from the live catalog. `status` checks local configuration and reports `configured/missing` without testing network access or key validity. Configure a key before proceeding with authenticated discovery or inspection. Use `discover --public` when the user explicitly requests public catalog browsing only.
|
|
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
|
+
Balance checks use `GET /api/v1/agent-api-account` with a Bearer API key. This works with both wallet and email account keys. `run` reads the API contract, validates parameters, checks the balance, and calls the gateway. `calls list/get` retrieves model, data, and tool API usage records for the current key and requires a backend version that includes this fix. Status filters accept only `--status success` or `--status failed`. Passing `--review-required` produces a local error.
|
|
73
|
+
|
|
74
|
+
## Retrieving asynchronous API results
|
|
75
|
+
|
|
76
|
+
When `run -j` returns HTTP 202, read `body.task_id` from its JSON output. Use the same API key and environment as the submission.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
openany-dev tasks get --id TASK_ID -j
|
|
80
|
+
openany-dev tasks wait --id TASK_ID --timeout-seconds 120 -j
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`tasks get` reads the task once. `tasks wait` polls until `status` is `completed`, `failed`, or `timed_out`, then prints the task record, including any available `result` or `artifacts` metadata. Check `status` for the task outcome. The wait defaults to 120 seconds and accepts 1–600 seconds. If the local wait expires, the command returns the latest available snapshot with `timedOut: true`. Run it again with the same task ID to resume reading. Both commands only query the existing task, with no balance check or repeat submission. In Dev, use `openany-dev`.
|
|
84
|
+
|
|
85
|
+
## Viewing calls and costs
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
openany-dev calls list --status success --limit 20 -j
|
|
89
|
+
openany-dev calls list --status failed --limit 20 -j
|
|
90
|
+
openany-dev calls get --id 3535549d4364136631ff21dd06516e0a -j
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Replace the example ID with the actual request ID. Lookups accept model trace IDs and UUIDs. A 32-character hexadecimal UUID is equivalent to its hyphenated form. Other IDs require an exact match. `usageType` distinguishes `model` from `api`. Model records include `model` and `provider`, with `apiId` set to null. `chargedCostMicroUsd` gives the cost of the individual usage record in microdollars. `monthlyUsageMicroUsd` is cumulative and cannot be used to infer the cost of an individual request.
|
|
94
|
+
|
|
95
|
+
The list defaults to the past seven days. `--from` and `--to` use UTC timestamps in milliseconds, with a maximum span of 31 days. Detail lookups are independent of the list's time window. All queries are scoped to the current account and key. After upgrading, restart pagination from the first page to get a new cursor. Missing metadata such as review and settlement stages remains unknown. Status aliases such as `succeeded/ok/pending/error/unknown` are unsupported. Model records become available only after the backend update is deployed.
|
|
96
|
+
|
|
97
|
+
## Calling models
|
|
98
|
+
|
|
99
|
+
**Upgrading to 0.2.0.** Model calls now use curl examples from the catalog. The legacy `models run --protocol/--mode` options are unsupported. After upgrading, run `models examples` to find providers and example IDs, then select a request with `--provider` and `--example`. Audio transcription is currently unsupported.
|
|
100
|
+
|
|
101
|
+
Model examples prefer active playground `curlExample` records for the selected
|
|
102
|
+
model and provider. Price examples supplement missing method/path pairs; a
|
|
103
|
+
malformed playground example is reported and does not trigger price fallback.
|
|
104
|
+
Example output includes `source` and, when applicable, `playgroundId`.
|
|
105
|
+
|
|
106
|
+
Identity placeholders in JSON and multipart `model` / `route.provider` fields
|
|
107
|
+
are resolved from the selected model and provider: `{model}`, `<model>`,
|
|
108
|
+
`YOUR_MODEL`, `<model-for-this-model>`, and the corresponding provider forms.
|
|
109
|
+
URL path parameters `{model}` and `{provider}` are bound automatically.
|
|
110
|
+
Concrete conflicting identities still fail validation; ordinary text fields
|
|
111
|
+
are never rewritten. Refresh example IDs after upgrading.
|
|
112
|
+
|
|
113
|
+
First, fetch the curl examples for the model and provider:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
openany-dev models examples --model doubao-seedance-2-0-fast --public -j
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
The output includes each request's `id`, `provider`, request template, path variables, and parsing errors. Save the selected creation request's `request.json` template as `input.json` and fill in the complete body. Use that file as input and leave the rest of the example list out of the request.
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
openany-dev models run --model doubao-seedance-2-0-fast --provider ByteDance --example CREATE_EXAMPLE_ID -f input.json --dry-run
|
|
123
|
+
openany-dev models run --model doubao-seedance-2-0-fast --provider ByteDance --example CREATE_EXAMPLE_ID -f input.json
|
|
124
|
+
openany-dev models run --model doubao-seedance-2-0-fast --provider ByteDance --example QUERY_EXAMPLE_ID --path '{"task_id":"ACTUAL_TASK_ID"}'
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Replace `CREATE_EXAMPLE_ID` and `QUERY_EXAMPLE_ID` with IDs from the current `models examples` output. Query examples must use the explicit `{task_id}` variable. The CLI rejects `YOUR_TASK_ID`. Retrieve the task ID from the service response and pass it explicitly. The caller handles ID extraction, polling, retries, and video downloads.
|
|
128
|
+
|
|
129
|
+
- `--provider` is optional. Multiple examples require `--example`; `--endpoint` only checks the selected path. Refresh IDs after example changes.
|
|
130
|
+
- `--input` / `--file` supplies the complete JSON request body. Include the matching `model` unless the URL explicitly contains `{model}`. The CLI sends the supplied body without merging the example's prompt, messages, or other defaults. 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.
|
|
131
|
+
- `--dry-run` uses the public catalog and prints the redacted final request without requiring an API key, checking the balance, or calling the model. Live calls require an API key. The CLI checks the balance before POST creation requests and skips that check for GET queries.
|
|
132
|
+
- Multipart requests currently support `/v1/images/edit` and `/v1/images/edits`. Specify each local file explicitly with `--attach FIELD=FILE` and repeat the option as needed for the same field. The CLI never reads file paths from examples. Supply scalar form fields as JSON, use arrays for repeated fields, and provide `route` as a JSON object. Audio transcription is unsupported.
|
|
133
|
+
- Model calls can run without `operations` or `parameters`. You can still query `models parameters` independently. `models run` rejects the legacy `--protocol` and `--mode` options and the `--method`, `--query`, and `--headers` overrides.
|
|
134
|
+
- The parser supports GET, JSON POST, and multipart POST for image edits, including quotes, line continuations, comments, and repeated form fields. It reports invalid JSON, dangling line continuations, model or provider conflicts, and unknown curl options as errors. It neither attempts repairs nor executes shell commands. When it encounters `--location`, it explains that the CLI does not automatically follow redirects.
|
|
135
|
+
|
|
136
|
+
See the [skill documentation](skills/openany/SKILL.md) for detailed instructions.
|
|
137
|
+
|
|
138
|
+
## Configuring advanced features
|
|
139
|
+
|
|
140
|
+
| Feature | Required configuration |
|
|
141
|
+
| --- | --- |
|
|
142
|
+
| Standard model and API calls | `OPENANY_DEV_API_KEY` or a saved active key |
|
|
143
|
+
| Wallet login, key creation, and key rotation | `OPENANY_DEV_WALLET_ADDRESS`, either `OPENANY_DEV_WALLET_PRIVATE_KEY` or an external signer, and a stable `OPENANY_DEV_AGENT_ID` |
|
|
144
|
+
| Email login and key management | `OPENANY_DEV_EMAIL`, authorized mailbox access for the agent, and a workspace selection when required |
|
|
145
|
+
| Top-ups | The target account's API key, the corresponding wallet or email session, a payment wallet and signing capability, and explicit authorization for the network, per-payment and cumulative limits, scope, and expiration |
|
|
146
|
+
|
|
147
|
+
`openany-dev setup` offers three setup options in an interactive terminal. You can also select one directly with a flag:
|
|
148
|
+
|
|
149
|
+
- `--api_key api_key` prompts for a key label, the API key using masked input, and whether to activate it. Updating a key with the same label replaces its value.
|
|
150
|
+
- `--wallet_connect wallet` prompts for the wallet private key using masked input, derives the address, and asks for a stable agent ID. Press Enter to keep existing values. This setup option accepts local keys only. After saving, follow the wallet workflow in [SKILL.md](skills/openany/SKILL.md). For first-time use, run `openany-dev keys create --identity wallet --label agent-main -j` to register the account automatically, confirm the key was saved, then run `openany-dev auth wallet -j`. If you already have a key for the wallet, log in directly.
|
|
151
|
+
- `--email_login email` prompts for an email address. After saving it, run `openany-dev auth email send` to send a verification code, then run `openany-dev auth email verify --code SIX_DIGITS` to log in.
|
|
152
|
+
|
|
153
|
+
`openany-dev status_check wallet|email|api_key|payment` checks local configuration only. Use the literal names `wallet`, `email`, and `api_key` where applicable. The legacy `setup --scenario …` and `status --scenario …` forms still work, and the JSON `scenario` field retains its original value. `setup -j`, `setup --non-interactive`, non-terminal input, `setup --prepare`, and `setup --scenario payment` continue to check configuration without waiting for input or saving changes. Add `--prepare` to check an existing external-signing command. For top-up checks, specify `--identity wallet|email`. Configuration status reports only whether local settings are present. Login, key validity, and payment authorization require separate checks.
|
|
154
|
+
|
|
155
|
+
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.
|
|
156
|
+
|
|
157
|
+
Use `setup` to save the private key in the existing restricted credentials file, or supply it through a secure environment variable. Subsequent commands load the local wallet, agent ID, and email settings automatically. Nonempty environment variables take precedence. The `environmentOverrides` field in the setup result lists the names of variables that override local settings. The CLI leaves mailbox access to the agent. Use the agent's authorized mailbox tool to read the verification code, then pass it to `auth email verify --code SIX_DIGITS`.
|
|
158
|
+
|
|
159
|
+
Wallet commands include `auth wallet` and `keys create|rotate --identity wallet --label LABEL`. For external signing, first run the command with `--prepare`, then repeat it with `--challenge-id ID --signature-file FILE`. The identity signature file contains the raw signature as text.
|
|
160
|
+
|
|
161
|
+
Use `auth email send|verify|refresh|workspace` for email authentication and `keys remote list|get|create|revoke` to manage remote keys. To rotate an email account key, create a new key, switch callers to it, verify it works, and revoke the old key manually. The `OPENANY_DEV_API_KEY` environment variable takes precedence over the local key. Update the environment secret after rotation.
|
|
162
|
+
|
|
163
|
+
Top-ups use `topups authorize → create → pay → get`. See [SKILL.md](skills/openany/SKILL.md) for the complete commands and external signature formats. Limits apply to the actual payment amount, including fees. Orders awaiting payment also count against the reserved amount. Each intent fixes the amount, destination, and network. If creation has an uncertain outcome, rerun with the original arguments and `--resume`. If payment submission has an uncertain outcome, query its status only. The CLI leaves repeat top-ups and increases to authorization limits to the caller.
|
|
164
|
+
|
|
165
|
+
## Output, persistence, and recovery
|
|
166
|
+
|
|
167
|
+
- `-j` prints compact JSON. `-o FILE` saves the result and refuses to overwrite an existing file. Supply the request body with `-i JSON` or `-f FILE` and use JSON arguments for path parameters, query parameters, and additional headers.
|
|
168
|
+
- Critical errors go to stderr and exit with status 1. They include an error code, a description, and the `requestId` and `status` when available. HTTP requests are never retried automatically. Stdout excludes API keys and private keys.
|
|
169
|
+
- The default local configuration path is `~/.config/openany-dev/credentials.json`. Set `OPENANY_DEV_CONFIG_DIR` to use an isolated directory. The existing permissions remain mode 0600 for files and 0700 for directories, with no additional permission options. Keep the file private and out of version control. It contains keys, any saved wallet private key and address, the agent ID, email, sessions, payment policies, and intents. The file has no additional encryption. Writes hold a lock. If a crash leaves a stale lock, confirm the process has exited before removing it manually.
|
|
170
|
+
- If the service completes an identity change and local saving fails, the CLI keeps a recovery file. Run `auth recover --file PATH` with the exact path returned by the CLI. Avoid resubmitting the creation or rotation request.
|
|
171
|
+
- Payment signature files use JSON. Use `{ "signature": "..." }` for EVM and `{ "transaction": "BASE64..." }` for Solana. The signing tool must sign exactly what the CLI exports.
|
|
172
|
+
- SSE returns after the CLI receives the complete stream and validates the end event. Live token display is currently unavailable. Asynchronous data and tool APIs can return a task receipt. For asynchronous model requests, use the published GET example. Task cancellation is unavailable.
|
|
173
|
+
- Audio generation requires `-o`. For other binary responses without an output path, the CLI writes to a temporary file with restricted permissions and returns its path.
|
|
174
|
+
|
|
175
|
+
## Verification and deployment
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
npm test
|
|
179
|
+
npm run check
|
|
180
|
+
npm pack --dry-run
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Tests use an injected HTTP transport and fixed, unfunded test keys. They cover zero network requests when the API key is missing, contracts, identity isolation, real local signing, top-up limits, and recovery from uncertain outcomes. They run without making real payments, modifying databases, or calling paid APIs.
|
|
184
|
+
|
|
185
|
+
The backend signing origin must be `https://dev.openany.si`. Deploy the service for changes to Dockerfile defaults to take effect. Orders locked to the previous origin remain subject to signature verification against that origin. Reconcile existing orders and environment overrides before deployment.
|
|
186
|
+
|
|
187
|
+
## Skill documentation maintenance
|
|
188
|
+
|
|
189
|
+
`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:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
npm run sync:skill -- ../openany-interface/openany-interface
|
|
193
|
+
npm run sync:skill -- ../openany-interface/openany-interface --check
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
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.
|
|
197
|
+
|
|
198
|
+
### New email registration
|
|
199
|
+
|
|
200
|
+
`openany-dev auth email send -j` reads the configured email and sends the code first.
|
|
201
|
+
For a new email, `registrationRequired: true` and `verificationUrl` identify the
|
|
202
|
+
browser step. Show the full URL (including its fragment) to the user and have them
|
|
203
|
+
complete Turnstile. The link is also printed to stderr in JSON mode. Then verify
|
|
204
|
+
the current six-digit email code with `openany-dev auth email verify --code SIX_DIGITS -j`
|
|
205
|
+
in the user's terminal or using an authorized mailbox tool. Never ask for the code
|
|
206
|
+
in chat. Existing accounts proceed directly to code verification without Turnstile.
|
|
207
|
+
|
|
208
|
+
Both proofs are required to create a new account. A confirmed
|
|
209
|
+
`HUMAN_VERIFICATION_REQUIRED` response allows retrying the same code after browser
|
|
210
|
+
approval. Expiry or resending invalidates the old challenge and browser link.
|
|
211
|
+
|
|
212
|
+
## Provider onboarding and direct publication
|
|
213
|
+
|
|
214
|
+
Provider management shares the existing CLI binary and email login, under the
|
|
215
|
+
`seller` command group. The old `openany-dev provider` command is no longer supported. It requires an account email session, not a consumer API
|
|
216
|
+
key or workspace. Existing consumer commands and the `openany-dev` consumer Skill are
|
|
217
|
+
unchanged. The new Skill is `skills/openany-provider/SKILL.md`.
|
|
218
|
+
|
|
219
|
+
```sh
|
|
220
|
+
openany-dev auth email send --email provider@example.test -j
|
|
221
|
+
# Read the fresh verification email using an already authorized mailbox connector.
|
|
222
|
+
openany-dev auth email verify --code SIX_DIGITS -j
|
|
223
|
+
openany-dev seller applications list -j
|
|
224
|
+
openany-dev seller status --application APPLICATION_ID -j
|
|
225
|
+
openany-dev seller schema --type model --application APPLICATION_ID -j
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Always select the supplier explicitly. The CLI never chooses the newest account
|
|
229
|
+
or supplier, installs a mailbox connector, or grants mailbox access. Capability
|
|
230
|
+
checks require `seller-resource-reviews-v1`; regional or unavailable API support
|
|
231
|
+
is reported rather than falling back to anonymous registration.
|
|
232
|
+
|
|
233
|
+
To apply as a new supplier, prepare registration JSON matching the website's
|
|
234
|
+
supplier application form, then submit it with the same account:
|
|
235
|
+
|
|
236
|
+
```sh
|
|
237
|
+
openany-dev seller applications create --file registration.json --operation supplier-apply-1 -j
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
The registration file uses `seller`, `seller_types`, `resource`, `connection`,
|
|
241
|
+
`endpoints`, and `consents`. Enter a unique `seller.slug` (for example,
|
|
242
|
+
`hong3seller`) along with the supplier name and email. The CLI validates the
|
|
243
|
+
slug and maps `seller`/`seller_types` to the backend's
|
|
244
|
+
`provider`/`provider_types` fields before calling
|
|
245
|
+
`POST /api/v1/provider/account/registrations`. Use your real details and
|
|
246
|
+
explicit consents; never include credentials.
|
|
247
|
+
The backend applies the website's validation and application approval workflow.
|
|
248
|
+
The returned `reg_...` ID identifies a registration, not an `--application` UUID.
|
|
249
|
+
Check its review status on the website; after administrator approval, run
|
|
250
|
+
`seller applications list` and select the resulting supplier UUID.
|
|
251
|
+
Submission does not admit the supplier or authorize resource publication.
|
|
252
|
+
If submission times out, check the website before any further submission.
|
|
253
|
+
Registration creation is non-idempotent: the CLI blocks replay of an uncertain
|
|
254
|
+
operation even with `--resume`. Do not use a new operation to bypass this check.
|
|
255
|
+
|
|
256
|
+
To create a connection with a native macOS or Windows dialog, run:
|
|
257
|
+
|
|
258
|
+
```sh
|
|
259
|
+
openany-dev seller connections create --application APPLICATION_ID --operation connection-create --gui -j
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
The dialog collects the label, base URL, authentication type, optional query/path
|
|
263
|
+
parameter name, and a masked API key. It uses the key entered in the dialog,
|
|
264
|
+
not `OPENANY_DEV_UPSTREAM_API_KEY`. The key is submitted to OpenAny without being
|
|
265
|
+
saved locally or printed. Cancellation or a five-minute timeout submits nothing.
|
|
266
|
+
Invalid fields display a safe error and reopen the form for correction.
|
|
267
|
+
`--gui` supports non-terminal invocation and JSON output on a desktop, but cannot
|
|
268
|
+
be combined with `--file`, `--input`, `--stdin`, `--prepare`, or `--non-interactive`.
|
|
269
|
+
Both `--application` and `--operation` remain required. Linux/headless environments
|
|
270
|
+
must use terminal or scripted creation; GUI failures do not silently fall back.
|
|
271
|
+
|
|
272
|
+
To create a connection interactively in your terminal, run:
|
|
273
|
+
|
|
274
|
+
```sh
|
|
275
|
+
openany-dev seller connections create --application APPLICATION_ID --operation connection-create
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Enter the connection label, base URL and authentication type (number or name).
|
|
279
|
+
Query/path authentication also asks for the parameter name. If authentication
|
|
280
|
+
requires a key, the CLI uses `OPENANY_DEV_UPSTREAM_API_KEY` when set, otherwise it
|
|
281
|
+
prompts with hidden input. Ctrl-C or EOF cancels without creating a connection.
|
|
282
|
+
`--application` and `--operation` remain required command-line parameters.
|
|
283
|
+
Explicit `--file`/`--input`, `--stdin`, `-j`, `--non-interactive` and non-terminal
|
|
284
|
+
input do not start the interactive form; supply JSON configuration in those modes.
|
|
285
|
+
|
|
286
|
+
For scripted creation, create a non-secret connection configuration file containing `label`, `baseUrl`,
|
|
287
|
+
`authType` and, where required, `authParamName`. Supply the upstream key using
|
|
288
|
+
`OPENANY_DEV_UPSTREAM_API_KEY` or `--stdin`, never JSON or a command argument:
|
|
289
|
+
|
|
290
|
+
```sh
|
|
291
|
+
openany-dev seller connections create --application APPLICATION_ID --file connection.json --stdin --operation connection-create -j
|
|
292
|
+
openany-dev seller models create --application APPLICATION_ID --file model.json --operation model-create -j
|
|
293
|
+
openany-dev seller models verify --application APPLICATION_ID --id MODEL_ID --file verification.json --operation model-route-test -j
|
|
294
|
+
openany-dev seller models publish --application APPLICATION_ID --id MODEL_ID --file publication.json --operation model-publish -j
|
|
295
|
+
openany-dev seller models get --application APPLICATION_ID --id MODEL_ID -j
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
Provider JSON writes accept either `--file PATH` or `--input JSON`, never both.
|
|
299
|
+
`SECRET_IN_DOCUMENT` may be raised by the CLI locally before any backend call;
|
|
300
|
+
its `field` identifies the offending value and `stage: "local"` identifies the scan.
|
|
301
|
+
Omit authentication headers from `curlExample`, including Bearer placeholders;
|
|
302
|
+
configure authentication through the connection. Do not replace placeholders with real keys.
|
|
303
|
+
|
|
304
|
+
For `models verify`, `request.path` must be an empty object `{}` when supplied,
|
|
305
|
+
never a URL string such as `"/v1/chat/completions"` or a nonempty parameter map.
|
|
306
|
+
The CLI rejects invalid values locally with `INVALID_INPUT` and
|
|
307
|
+
`field: "request.path"`. The actual request path comes from the saved
|
|
308
|
+
`price.upstreamPath[endpointIndex]`; `endpointIndex` is zero-based. Read the saved
|
|
309
|
+
model first and use its current version, route ID and upstream revision:
|
|
310
|
+
|
|
311
|
+
```json
|
|
312
|
+
{
|
|
313
|
+
"expectedVersion": "SAVED_MODEL_VERSION",
|
|
314
|
+
"routeId": "SAVED_ROUTE_ID",
|
|
315
|
+
"expectedUpstreamRevision": 1,
|
|
316
|
+
"endpointIndex": 0,
|
|
317
|
+
"request": {
|
|
318
|
+
"path": {},
|
|
319
|
+
"query": {},
|
|
320
|
+
"headers": { "Content-Type": "application/json" },
|
|
321
|
+
"body": {
|
|
322
|
+
"messages": [{ "role": "user", "content": "Ping test" }],
|
|
323
|
+
"max_tokens": 5
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Replace the version, route ID, revision, endpoint index and test body with the
|
|
330
|
+
saved configuration and authorized test inputs. Model verification uses the saved
|
|
331
|
+
upstream model identity. This empty-path restriction applies only to models;
|
|
332
|
+
`apis verify` can use a path parameter object required by its saved API template.
|
|
333
|
+
|
|
334
|
+
Use `apis` instead of `models` for API resources. Every write requires a stable
|
|
335
|
+
`--operation NAME` (1–128 letters, digits, dots, underscores or hyphens). Local
|
|
336
|
+
operation records retain its idempotency key, account, supplier and non-secret
|
|
337
|
+
receipt. The name is bound to the request method, target path and JSON payload.
|
|
338
|
+
Reusing it for changed input produces `IDEMPOTENCY_CONFLICT`; reconcile the original
|
|
339
|
+
outcome first. An identical completed operation returns its locally saved result
|
|
340
|
+
without another write, so it does not run a fresh test. Do not change names on every retry.
|
|
341
|
+
For an uncertain resource create, repeat the exact command with the same operation
|
|
342
|
+
and `--resume`. Changed payloads require a new operation after the old result is
|
|
343
|
+
known. An uncertain PUT or verification is never automatically repeated; read
|
|
344
|
+
and reconcile it. Known verification IDs can be queried with `models|apis get
|
|
345
|
+
--verification-id ID`. A session change stops in-flight work. New runs must still
|
|
346
|
+
use the correct account and supplier.
|
|
347
|
+
|
|
348
|
+
Supplier admission remains required. Once admitted, configure and verify each
|
|
349
|
+
resource, then publish directly without a separate human review. Model publication
|
|
350
|
+
uses `expectedVersion` and `verificationIds`; API publication uses `expectedRevision`,
|
|
351
|
+
`expectedUpstreamRevision`, and `verificationId`. Authorized edits use current
|
|
352
|
+
versions and no longer require review withdrawal. Read activation and runtime
|
|
353
|
+
synchronization separately. Historical review queries remain available.
|
|
354
|
+
|
|
355
|
+
### Batch JSON imports
|
|
356
|
+
|
|
357
|
+
API inputs can use the website `provider-agent-api-v2` template directly or
|
|
358
|
+
OpenAPI 3.x JSON with metadata. For skills, bots and services, fill both
|
|
359
|
+
`includedContentHtml` and `usageInstructionsHtml`; ordinary APIs may omit them.
|
|
360
|
+
OpenAPI conversion reuses the existing pinned
|
|
361
|
+
`@openany/provider-apply` converter per operation, avoiding its historical 20-item
|
|
362
|
+
truncation. Unsupported methods and references are reported explicitly. Model
|
|
363
|
+
inputs use `{schemaVersion:1,items:[{itemId,configuration:{price,routes}}]}`. Both
|
|
364
|
+
support 1–100 items and files up to 8 MiB. Decimal prices are strings; numeric
|
|
365
|
+
JSON literals that would lose precision are rejected before parsing.
|
|
366
|
+
|
|
367
|
+
```sh
|
|
368
|
+
openany-dev seller imports preview --type api --file openapi.json --metadata-file metadata.json --bindings-file bindings.json --application APPLICATION_ID -j
|
|
369
|
+
openany-dev seller imports preview --type api --file seller-agent-api-import-template.json --bindings-file bindings.json --application APPLICATION_ID -j
|
|
370
|
+
openany-dev seller imports preview --type model --file models.json --bindings-file bindings.json --application APPLICATION_ID -j
|
|
371
|
+
openany-dev seller imports run --batch BATCH_ID --application APPLICATION_ID -j
|
|
372
|
+
openany-dev seller imports status --batch BATCH_ID --application APPLICATION_ID -j
|
|
373
|
+
openany-dev seller imports resume --batch BATCH_ID --bindings-file bindings.json --application APPLICATION_ID -j
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
API item IDs are `METHOD /path`. OpenAPI metadata uses
|
|
377
|
+
`{schemaVersion:1,items:[{itemId,configuration:{requestContentType,config,...}}]}`.
|
|
378
|
+
It supplies the complete execution config (including inputs, mappings, billing
|
|
379
|
+
and explicit charge_condition). Name/description can come from OpenAPI;
|
|
380
|
+
method/path cannot be silently overridden. OpenAPI parameters are not guessed
|
|
381
|
+
into gateway mappings or pricing. `charge_condition:null` explicitly accepts the
|
|
382
|
+
server's HTTP-success default.
|
|
383
|
+
|
|
384
|
+
Bindings use `{schemaVersion:1,items:[{itemId,upstreamKeyId}]}` for APIs or
|
|
385
|
+
`{schemaVersion:1,items:[{itemId,routes:[{index,upstreamKeyId}]}]}` for models. Files
|
|
386
|
+
must contain only items in that batch. Templates under
|
|
387
|
+
`skills/openany-provider/templates/` are intentionally incomplete, not quotes or
|
|
388
|
+
production defaults. Ask for actual pricing and authorization before use.
|
|
389
|
+
|
|
390
|
+
Preview does not create resources or call upstreams. Run/resume only creates
|
|
391
|
+
drafts. Missing connections are local `waiting_connection` items; other items
|
|
392
|
+
continue. Prepare or select an owned connection, then resume with its binding.
|
|
393
|
+
Missing credentials never imply `authType=none`. Summaries distinguish readiness,
|
|
394
|
+
missing information, created, conflict, failure and unknown results. Created
|
|
395
|
+
items are not repeated, unknown writes retain their exact original request, and
|
|
396
|
+
changed known failed inputs get new keys. No name-based adoption or overwriting
|
|
397
|
+
of existing resources is performed. After draft creation, verification and
|
|
398
|
+
submission remain separate, authorized, per-resource steps.
|
|
399
|
+
|
|
400
|
+
The local batch binds the account and supplier and uses the existing restricted
|
|
401
|
+
credentials file (0600). Secret-bearing documents are rejected before storage.
|
|
402
|
+
CLI tests use synthetic credentials and mocked HTTP; they do not prove deployment
|
|
403
|
+
readiness, mailbox delivery, real upstream compatibility or administrator review.
|
|
404
|
+
|
|
405
|
+
Sync the complete Provider Skill into the website with:
|
|
406
|
+
|
|
407
|
+
```sh
|
|
408
|
+
npm run sync:provider-skill -- ../openany-interface/openany-interface
|
|
409
|
+
npm run sync:provider-skill -- ../openany-interface/openany-interface --check
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
This writes `public/skills/openany-provider/` and preserves the consumer
|
|
413
|
+
`public/SKILL.md`. Publishing an npm package or deploying the website is a separate
|
|
414
|
+
release action.
|
|
415
|
+
|
|
416
|
+
### Provider contract checks
|
|
417
|
+
|
|
418
|
+
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.
|
|
419
|
+
|
|
420
|
+
`test/fixtures/provider-resource-reviews.json` is copied from the backend's
|
|
421
|
+
versioned contract fixture. `test/fixtures/provider-schemas.json` is generated by
|
|
422
|
+
calling the backend's `providerreviews.Schema` for all six schema kinds (the
|
|
423
|
+
initial export used a temporary Go overlay and did not modify backend sources).
|
|
424
|
+
The contract tests exercise CLI submissions against those actual field names and
|
|
425
|
+
version constraints, preserve source/target publication versions, and reject
|
|
426
|
+
silent rebasing after a stale submission. They also cover nullable local
|
|
427
|
+
connections, explicit default charge conditions, and server auth-type spellings.
|
|
428
|
+
|
|
429
|
+
After changing backend contracts, regenerate the schema export and compare it:
|
|
430
|
+
|
|
431
|
+
```sh
|
|
432
|
+
node scripts/check-provider-contract.mjs ../openany-backend/openany-backend --schemas-file /path/to/exported-provider-schemas.json
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
The check reads both repositories; it does not deploy, connect to production, or
|
|
436
|
+
rewrite fixtures. Schema snapshots do not substitute for backend validation or
|
|
437
|
+
cross-repository end-to-end tests.
|
|
438
|
+
|
|
439
|
+
### Exact balance display
|
|
440
|
+
|
|
441
|
+
`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.
|
|
442
|
+
|
|
443
|
+
### Model request materials and validation
|
|
444
|
+
|
|
445
|
+
`models examples` and `models run` resolve materials for the selected supplier:
|
|
446
|
+
Verified/Direct use imported candidate formats, then compatible Playground records;
|
|
447
|
+
Community uses compatible Playground records, then that supplier's ModelPrice.
|
|
448
|
+
Embedded Playgrounds are preferred. Older catalog responses without supplier metadata
|
|
449
|
+
retain legacy source selection. A supplier's own ModelPrice cURL defines its public
|
|
450
|
+
endpoint even if its upstream path differs; a schema for that other path is not reused.
|
|
451
|
+
|
|
452
|
+
Supply the complete request with `--input` or `--file`. Requests are not merged with
|
|
453
|
+
example bodies. JSON Schema validates business parameters without coercion, default
|
|
454
|
+
insertion, or removal of unknown fields. Explicit field constraints are used when no
|
|
455
|
+
JSON Schema exists. With only an example, validation is basic: example values do not
|
|
456
|
+
make fields required or restrict values. JSON Schema format annotations are not checked.
|
|
457
|
+
Invalid schemas fail explicitly. Gateway fields (`model`, `route`, `route_mode`) are
|
|
458
|
+
handled separately from business schemas. Responses and response examples never define
|
|
459
|
+
request constraints.
|
|
460
|
+
|
|
461
|
+
`models run --dry-run` reports `source`, `validation.level`, validation notices and the
|
|
462
|
+
final request, without querying balance or executing a model. Parameter failures use
|
|
463
|
+
`PARAMETER_VALIDATION_FAILED` with JSON-pointer paths. `--endpoint` filters before
|
|
464
|
+
ambiguity is checked; use `--example` when more than one request still matches.
|
|
465
|
+
GET query examples accept `--path` only, not creation bodies or uploads. Multipart
|
|
466
|
+
example files are never read automatically, and appearing in an example does not make
|
|
467
|
+
an attachment required; explicit constraints establish requirements.
|
|
468
|
+
|
|
469
|
+
## Log out or switch accounts
|
|
470
|
+
|
|
471
|
+
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.
|
|
472
|
+
|
|
473
|
+
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
package/package.json
CHANGED
|
@@ -1,6 +1,29 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "openany-cli-dev",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
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
|
+
}
|