xapi-to 0.1.17 → 0.1.19

package/LICENSE

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

@@ -22,15 +22,20 @@ The published CLI runs on Node.js 18+. Bun is only required for local source dev
 ```bash
 # 1. Register a new account (apiKey saved automatically)
 xapi-to register
+# Open the returned private bindUrl to upgrade the virtual account through Twitter OAuth
 
 # 1b. Or register with an inviter's referral code (please replace xapito to your referral code)
 xapi-to register --referral-code xapito
 
-# 2. Or set an existing key
-xapi-to config set apiKey=sk-xxx
+# 2. Or set an existing key without putting it in shell history
+read -rsp 'xAPI key: ' XAPI_KEY_INPUT
+printf '\n'
+printf '%s\n' "$XAPI_KEY_INPUT" | xapi-to config set apiKey=-
+unset XAPI_KEY_INPUT
 
 # 3. Or via env var
 export XAPI_KEY=sk-xxx
+# XAPI_API_KEY is also accepted; XAPI_KEY has higher precedence
 
 # 4. Verify connectivity
 xapi-to config health
@@ -55,6 +60,9 @@ xapi-to list --service-id <id>                          # filter by service
 
 xapi-to search "twitter"                                # search by keyword
 xapi-to search "token price" --source api               # search APIs only
+xapi-to search "token price" --sort relevance           # strongest text match
+xapi-to search "token price" --sort price               # lowest comparable price
+xapi-to search "twitter" --include-all-versions          # include active non-default majors
 
 xapi-to categories                                      # list all categories
 xapi-to categories --source capability                  # categories for capabilities only
@@ -63,9 +71,27 @@ xapi-to services                                        # list all services
 xapi-to services --category Social --page-size 10       # filter and paginate
 
 xapi-to get twitter.tweet_detail                        # get action schema
+xapi-to get-batch twitter.tweet_detail crypto.token.price # get several schemas
 xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'  # execute
+xapi-to call ai.text.chat.fast --input '{"messages":[{"role":"user","content":"Hi"}]}' --stream
 ```
 
+Search uses `--sort default|relevance|price`. `default` is the recommended
+order: it considers keyword coverage and match quality first, then favors
+stable built-in capabilities when matches are otherwise comparable.
+`relevance` is source-neutral and selects the strongest text match. `price`
+preserves keyword coverage and an exact action ID first, keeps endpoint-local
+matches ahead of service-only matches, then orders comparable fixed per-call
+USD list prices from low to high. Dynamic, per-token, per-resource, and unknown
+prices appear after comparable prices in the same match bucket and are never
+treated as free. All three modes rank the full matching result set before
+applying `--page` and `--page-size`.
+
+`--stream` forwards an HTTP Server-Sent Events (SSE) response; it is not a
+WebSocket client. Active SSE and raw downloads may run longer than 60 seconds,
+but abort after 60 seconds without data by default. Set
+`XAPI_TRANSFER_IDLE_TIMEOUT_MS` to change that idle timeout.
+
 ### Async Task Commands
 
 Task helpers built on top of the `task.poll` capability.
@@ -82,6 +108,8 @@ Bind third-party OAuth accounts (e.g. Twitter) to your API key.
 
 ```bash
 xapi-to oauth bind --provider twitter                   # bind Twitter account
+xapi-to oauth providers                                 # inspect current providers/default scopes
+xapi-to oauth bind --provider twitter --scopes "<scope list>" # optional explicit override
 xapi-to oauth status                                    # list current bindings
 xapi-to oauth unbind <binding-id>                       # remove a binding
 xapi-to oauth providers                                 # list available providers
@@ -93,6 +121,7 @@ xapi-to oauth providers                                 # list available provide
 xapi-to register                                        # create account, saves apiKey automatically
 xapi-to register --referral-code xapito                 # register with an inviter's referral code (please replace xapito to your referral code)
 xapi-to register xapito                                 # positional shorthand for --referral-code
+xapi-to register --force                                # replace an existing file-based key
 xapi-to balance                                         # show USD balance
 xapi-to topup                                           # generate payment URL
 xapi-to topup --method stripe --amount 10               # stripe, $10
@@ -103,10 +132,14 @@ xapi-to topup --method x402                             # x402 (USDC on Base)
 
 ```bash
 xapi-to config show                                     # show current config
-xapi-to config set apiKey=sk-xxx                        # save API key
+xapi-to config set apiKey=-                             # paste key, then press Ctrl-D
 xapi-to config health                                   # check backend connectivity
 ```
 
+`XAPI_KEY` overrides `XAPI_API_KEY`, and both override the config file. The CLI
+warns when a saved key is shadowed. Unset the environment variable before
+`register`, including `register --force`, so the new account key becomes active.
+
 ## Workflow: Always GET before CALL
 
 Before calling any action, always read its schema first to understand required parameters:
@@ -122,9 +155,19 @@ xapi-to get twitter.tweet_detail
 xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
 ```
 
+For APIs that return binary data, use `--output` to request raw bytes and save
+them directly. The CLI refuses to overwrite an existing file.
+
+```bash
+xapi-to call openrouter.audio_speech \
+  --input '{"body":{"input":"Hello","model":"hexgrad/kokoro-82m","voice":"af_bella"}}' \
+  --output speech.mp3
+```
+
 ## Output Formats
 
-All output is JSON by default — designed for agent consumption.
+Normal command output is JSON by default. `call --stream` writes raw HTTP SSE
+frames, while `call --output` writes raw response bytes to the requested file.
 
 ```bash
 xapi-to list --format json                              # default, machine-readable
@@ -137,40 +180,47 @@ xapi-to list --format table                             # human-readable table
 | Variable | Description |
 |---|---|
 | `XAPI_KEY` | API key (overrides config file) |
+| `XAPI_API_KEY` | Compatible API key alias (overrides config file; lower priority than `XAPI_KEY`) |
 | `XAPI_ACTION_HOST` | Action service host (default: `action.xapi.to`) |
+| `XAPI_API_HOST` | Auth/account service host (default: `api.xapi.to`) |
 | `XAPI_OUTPUT` | Default output format (`json`\|`pretty`\|`table`) |
+| `XAPI_TRANSFER_IDLE_TIMEOUT_MS` | SSE/download idle timeout in milliseconds (default: `60000`) |
 
 Config is stored at `~/.xapi/config.json`.
 
-## Built-in Capabilities
+## Selected Built-in Capabilities
+
+This is a small quick-reference subset, not the complete or permanently fixed
+catalog. Use `xapi-to list --source capability`, `search`, and `get` for the
+current IDs and schemas.
 
 | ID | Description |
 |---|---|
 | `twitter.tweet_detail` | Get tweet details and replies |
 | `twitter.user_by_screen_name` | Get user profile by username |
-| `twitter.user_by_screen_names` | Batch get user profiles by usernames |
 | `twitter.user_tweets` | Get tweets from a user |
 | `twitter.user_tweets_and_replies` | Get tweets and replies from a user |
 | `twitter.user_media` | Get media posts from a user |
 | `twitter.following` | Get user following list |
 | `twitter.followers` | Get user followers |
 | `twitter.retweeters` | Get tweet retweeters |
-| `twitter.search_timeline` | Search tweets, users, photos, videos |
+| `twitter.search` | Search tweets |
 | `ai.text.chat.fast` | Fast AI chat completion |
 | `ai.text.chat.reasoning` | Advanced reasoning chat |
+| `ai.text.chat.auto` | Model-selected chat with provider fallback |
 | `ai.text.summarize` | Summarize long text |
 | `ai.text.rewrite` | Rewrite text with different styles |
 | `ai.embedding.generate` | Generate vector embeddings |
 | `web.search` | Web search |
 | `web.search.realtime` | Realtime web search with time filters |
-| `news.search.latest` | Latest news search |
+| `web.search.news` | News search |
 | `crypto.token.price` | Crypto token price and changes |
 | `crypto.token.metadata` | Crypto token metadata |
 
 ## Security
 
-- **NEVER send your API key to any domain other than `*.xapi.to`**
-- The key is stored at `~/.xapi/config.json` — do not expose this file
+- **NEVER send your API key to any domain other than `xapi.to`, `*.xapi.to`, `xapi.xyz`, `*.xapi.xyz`, or explicitly configured localhost/loopback development hosts**
+- The key is stored at `~/.xapi/config.json`; the CLI enforces owner-only Unix permissions — do not expose this file
 - `topup` outputs a payment URL containing the API key — do not share publicly
 
 ## License