keyapi-cli 0.0.0-stage → 1.0.2

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# KeyAPI CLI
 
-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.
+---
+
+[Chinese](https://github.com/EchoSell/keyapi-cli/blob/main/README.zh.md) | [English](https://github.com/EchoSell/keyapi-cli/blob/main/README.md)
+
+KeyAPI CLI is a lightweight command line client for the [KeyAPI](https://keyapi.ai) platform. It helps you configure authentication, discover supported API platforms, inspect endpoint schemas, and call APIs without writing request code.
+
+## Why KeyAPI CLI?
+
+KeyAPI provides many APIs across platforms such as Google, TikTok, Instagram, and more. When a project uses many endpoints, manually writing and maintaining request code can become repetitive.
+
+KeyAPI CLI provides one consistent entry point:
+
+- configure your API token once
+- list supported platforms
+- list endpoints under each platform
+- inspect endpoint methods, paths, descriptions, parameters, and request body fields
+- execute API requests from the terminal
+- save large responses to files
+
+The CLI reads the latest KeyAPI OpenAPI documentation when endpoint details are requested, so endpoint descriptions and schemas stay aligned with the current KeyAPI API documentation.
+
+## Features
+
+- Simple configuration commands: `keyapi set`, `keyapi get`, `keyapi show`, `keyapi clear`
+- API discovery commands: `keyapi spec list-platforms`, `keyapi spec list-endpoints`, `keyapi schema`
+- One request command: `keyapi call`
+- JSON output by default for `spec` and `call`
+- Built-in `--help` output designed for humans, scripts, and agents
+- `--dry-run` support before sending requests
+- `--output "path"` support for large responses
+
+## Installation
+
+Requires Node.js 18 or later:
+
+```bash
+npm install -g keyapi-cli
+keyapi --help
+keyapi --version
+```
+
+The npm package installs a small JavaScript launcher plus the matching native
+KeyAPI binary package for your operating system. If you already have a custom
+KeyAPI binary, set `KEYAPI_CLI_BINARY` to its path before running `keyapi`.
+
+## Quick Start
+
+Configure your KeyAPI token:
+
+```powershell
+keyapi set token sk_xxx
+```
+
+Check the current configuration:
+
+```powershell
+keyapi show
+```
+
+List supported platforms:
+
+```powershell
+keyapi spec list-platforms
+```
+
+List endpoints for a platform:
+
+```powershell
+keyapi spec list-endpoints google
+```
+
+Inspect an endpoint before calling it:
+
+```powershell
+keyapi schema google/search
+```
+
+Dry-run a request:
+
+```powershell
+keyapi call "/v1/google/search?q=openai&gl=us&hl=en" --dry-run
+```
+
+Execute the request:
+
+```powershell
+keyapi call "/v1/google/search?q=openai&gl=us&hl=en"
+```
+
+Save a large response:
+
+```powershell
+keyapi call "/v1/google/search?q=openai&gl=us&hl=en" --output "google-search.json"
+```
+
+Clear the saved token when needed:
+
+```powershell
+keyapi clear token
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `keyapi --help` | Show the main help, recommended order, and command help entry points. |
+| `keyapi set token <value>` | Save the API token locally. |
+| `keyapi set language <en\|zh>` | Set OpenAPI documentation language for endpoint descriptions. |
+| `keyapi get <key>` | Read one local configuration value. |
+| `keyapi show` | Show current local configuration. |
+| `keyapi clear <key>` | Clear one local configuration value. |
+| `keyapi spec list-platforms` | Return a JSON array of supported platforms. |
+| `keyapi spec list-endpoints <platform...\|all>` | Return endpoint summaries for one or more platforms. |
+| `keyapi spec get-endpoint <endpoint-or-path>` | Return method, path, description, parameters, and body fields for one endpoint. |
+| `keyapi schema <endpoint-or-path>` | Short alias for `keyapi spec get-endpoint`. |
+| `keyapi call <endpoint-or-path>` | Execute a KeyAPI request. |
+
+Every command supports `--help`:
+
+```powershell
+keyapi --help
+keyapi set --help
+keyapi spec --help
+keyapi spec list-platforms --help
+keyapi spec list-endpoints --help
+keyapi spec get-endpoint --help
+keyapi schema --help
+keyapi call --help
+```
+
+## Advanced Usage
+
+### JSON Output
+
+`spec` and `call` commands return JSON by default.
+
+`keyapi spec list-platforms`:
+
+```json
+["google", "tiktok"]
+```
+
+`keyapi spec list-endpoints tiktok`:
+
+```json
+{
+  "tiktok": [
+    {
+      "method": "GET",
+      "path": "/v1/tiktok/influencer/detail",
+      "summary": "User detail",
+      "description": "Get TikTok user detail."
+    }
+  ]
+}
+```
+
+### Save Large Responses
+
+Some endpoints return large JSON responses, such as product details, images, SKU lists, or description fields. Use `--output "path"` to write the full response body to a file instead of printing it in the terminal:
+
+```powershell
+keyapi call "/v1/google/search?q=openai&gl=us" --output "outputs/google-search.json"
+```
+
+Relative output paths are resolved from the current working directory.
+
+### Dry Run
+
+Use `--dry-run` to print the request without sending it:
+
+```powershell
+keyapi call "/v1/google/search?q=openai&gl=us" --dry-run
+```
+
+### Request Body
+
+Use `--body-json` for JSON request bodies:
+
+```powershell
+keyapi call "/v1/example/post-endpoint" --method POST --body-json '{"page":1,"verified":true}'
+```
+
+Use `--body-raw` for raw text request bodies:
+
+```powershell
+keyapi call "/v1/example/text-endpoint" --method POST --body-raw "plain text"
+```
+
+For GET endpoints, prefer putting query parameters directly in the endpoint path:
+
+```powershell
+keyapi call "/v1/google/search?q=openai&gl=us"
+```
+
+Use `--params "k=v"` or `--query "k=v"` when query parameters are easier to append programmatically.
+
+## Documentation
+
+`docs/` contains usage documentation for installing, configuring, and using the CLI. The CLI help output is the primary built-in reference for command usage.
+
+| File | Purpose |
+| --- | --- |
+| [docs/index.md](docs/index.md) | Documentation entry point. |
+| [docs/commands.md](docs/commands.md) | Full command and parameter reference. |
+| [docs/config.md](docs/config.md) | Config file and environment variables. |
+| [README.zh.md](README.zh.md) | Chinese README. |
+| [docs/zh/index.md](docs/zh/index.md) | Chinese documentation entry point. |

package/README.zh.md

@@ -0,0 +1,118 @@
+# KeyAPI CLI
+
+[中文](https://github.com/EchoSell/keyapi-cli/blob/main/README.zh.md) | [English](https://github.com/EchoSell/keyapi-cli/blob/main/README.md)
+
+KeyAPI CLI 是用于 [KeyAPI](https://keyapi.ai) 的轻量级命令行工具。它可以配置认证信息、发现支持的平台、查看接口 schema，并直接从终端调用 API。
+
+## 功能
+
+- 配置命令：`keyapi set`、`keyapi get`、`keyapi show`、`keyapi clear`
+- 接口发现：`keyapi spec list-platforms`、`keyapi spec list-endpoints`
+- schema 查看：`keyapi schema`
+- 请求执行：`keyapi call`
+- 默认 JSON 输出，适合脚本和 Agent 使用
+- 支持 `--dry-run` 预览请求
+- 支持 `--output "path"` 保存大响应
+
+## 安装
+
+需要 Node.js 18 或更高版本：
+
+```bash
+npm install -g keyapi-cli
+keyapi --help
+keyapi --version
+```
+
+npm 包会安装一个 JavaScript 启动器，并自动安装当前系统对应的 KeyAPI 原生二进制包。如果你已经有自定义 KeyAPI 二进制文件，可以在运行 `keyapi` 前设置 `KEYAPI_CLI_BINARY` 指向该文件路径。
+
+## 快速开始
+
+配置 KeyAPI token：
+
+```powershell
+keyapi set token sk_xxx
+```
+
+查看当前配置：
+
+```powershell
+keyapi show
+```
+
+列出支持的平台：
+
+```powershell
+keyapi spec list-platforms
+```
+
+列出某个平台的接口：
+
+```powershell
+keyapi spec list-endpoints google
+```
+
+调用前查看接口 schema：
+
+```powershell
+keyapi schema google/search
+```
+
+预览请求：
+
+```powershell
+keyapi call "/v1/google/search?q=openai&gl=us&hl=en" --dry-run
+```
+
+执行请求：
+
+```powershell
+keyapi call "/v1/google/search?q=openai&gl=us&hl=en"
+```
+
+保存大响应：
+
+```powershell
+keyapi call "/v1/google/search?q=openai&gl=us&hl=en" --output "google-search.json"
+```
+
+清除 token：
+
+```powershell
+keyapi clear token
+```
+
+## 常用命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `keyapi --help` | 查看帮助 |
+| `keyapi set token <value>` | 保存 API token |
+| `keyapi set language <en|zh>` | 设置 OpenAPI 文档语言 |
+| `keyapi show` | 查看当前配置 |
+| `keyapi spec list-platforms` | 列出支持的平台 |
+| `keyapi spec list-endpoints <platform...|all>` | 列出平台接口 |
+| `keyapi schema <endpoint-or-path>` | 查看接口 schema |
+| `keyapi call <endpoint-or-path>` | 调用接口 |
+
+每个命令都支持 `--help`：
+
+```powershell
+keyapi --help
+keyapi spec --help
+keyapi schema --help
+keyapi call --help
+```
+
+## 使用建议
+
+推荐流程：
+
+1. `keyapi set token sk_xxx`
+2. `keyapi spec list-platforms`
+3. `keyapi spec list-endpoints <platform>`
+4. `keyapi schema <endpoint-or-path>`
+5. `keyapi call <endpoint-or-path> --dry-run`
+6. `keyapi call <endpoint-or-path>`
+
+对于较大的 JSON 响应，使用 `--output "path"` 保存到文件。

package/npm/keyapi.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const {
+  binaryNameForPlatform,
+  packageNameForPlatform,
+} = require('../scripts/platform');
+
+function resolveBinaryPath(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const resolve = options.resolve || require.resolve;
+
+  if (env.KEYAPI_CLI_BINARY) {
+    return env.KEYAPI_CLI_BINARY;
+  }
+
+  const packageName = packageNameForPlatform({ platform, arch });
+  return resolve(path.join(packageName, 'bin', binaryNameForPlatform({ platform })));
+}
+
+function main() {
+  const binaryPath = resolveBinaryPath();
+  const result = spawnSync(binaryPath, process.argv.slice(2), {
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    console.error(`Failed to start KeyAPI CLI: ${result.error.message}`);
+    console.error('Try reinstalling keyapi-cli, or set KEYAPI_CLI_BINARY.');
+    process.exit(1);
+  }
+
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    return;
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  resolveBinaryPath,
+};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "keyapi-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "KeyAPI CLI for discovering endpoint schemas and calling KeyAPI APIs.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EchoSell/keyapi-cli.git"
+  },
+  "bin": {
+    "keyapi": "npm/keyapi.js"
+  },
+  "files": [
+    "npm",
+    "scripts",
+    "README.md",
+    "README.zh.md"
+  ],
+  "scripts": {
+    "prepare-platform-packages": "node scripts/prepare-platform-packages.js",
+    "test": "node --test test/*.test.js"
+  },
+  "optionalDependencies": {
+    "keyapi-cli-darwin-arm64": "1.0.2",
+    "keyapi-cli-darwin-x64": "1.0.2",
+    "keyapi-cli-linux-arm64": "1.0.2",
+    "keyapi-cli-linux-x64": "1.0.2",
+    "keyapi-cli-win32-x64": "1.0.2"
+  },
+  "keywords": [
+    "keyapi",
+    "cli",
+    "api",
+    "openapi"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/platform.js

@@ -0,0 +1,62 @@
+const osByPlatform = {
+  win32: 'windows',
+  darwin: 'darwin',
+  linux: 'linux',
+};
+
+const archByArch = {
+  x64: 'amd64',
+  arm64: 'arm64',
+};
+
+const npmArchByArch = {
+  x64: 'x64',
+  arm64: 'arm64',
+};
+
+function targetForPlatform(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const os = osByPlatform[platform];
+  const goarch = archByArch[arch];
+
+  if (!os || !goarch) {
+    throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  }
+
+  return { os, arch: goarch };
+}
+
+function assetNameForPlatform(options = {}) {
+  if (!options.version) {
+    throw new Error('version is required');
+  }
+
+  const target = targetForPlatform(options);
+  const suffix = target.os === 'windows' ? '.exe' : '';
+  return `keyapi_${options.version}_${target.os}_${target.arch}${suffix}`;
+}
+
+function binaryNameForPlatform(options = {}) {
+  const platform = options.platform || process.platform;
+  return platform === 'win32' ? 'keyapi.exe' : 'keyapi';
+}
+
+function packageNameForPlatform(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const npmArch = npmArchByArch[arch];
+
+  if (!npmArch || !osByPlatform[platform]) {
+    throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  }
+
+  return `keyapi-cli-${platform}-${npmArch}`;
+}
+
+module.exports = {
+  assetNameForPlatform,
+  binaryNameForPlatform,
+  packageNameForPlatform,
+  targetForPlatform,
+};

package/scripts/prepare-platform-packages.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+
+const targets = [
+  { goos: 'windows', goarch: 'amd64', packageName: 'keyapi-cli-win32-x64', binaryName: 'keyapi.exe' },
+  { goos: 'linux', goarch: 'amd64', packageName: 'keyapi-cli-linux-x64', binaryName: 'keyapi' },
+  { goos: 'linux', goarch: 'arm64', packageName: 'keyapi-cli-linux-arm64', binaryName: 'keyapi' },
+  { goos: 'darwin', goarch: 'amd64', packageName: 'keyapi-cli-darwin-x64', binaryName: 'keyapi' },
+  { goos: 'darwin', goarch: 'arm64', packageName: 'keyapi-cli-darwin-arm64', binaryName: 'keyapi' },
+];
+
+function preparePlatformPackages(options = {}) {
+  const rootDir = options.rootDir || path.resolve(__dirname, '..');
+  const version = options.version || require(path.join(rootDir, 'package.json')).version;
+  const distDir = options.distDir || path.join(rootDir, 'dist');
+  const packagesDir = options.packagesDir || path.join(rootDir, 'npm-packages');
+
+  for (const target of targets) {
+    const source = path.join(
+      distDir,
+      `keyapi_${version}_${target.goos}_${target.goarch}${target.binaryName.endsWith('.exe') ? '.exe' : ''}`,
+    );
+    const binDir = path.join(packagesDir, target.packageName, 'bin');
+    const destination = path.join(binDir, target.binaryName);
+
+    if (!fs.existsSync(source)) {
+      throw new Error(`missing built binary: ${source}`);
+    }
+
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.copyFileSync(source, destination);
+    fs.chmodSync(destination, 0o755);
+  }
+}
+
+if (require.main === module) {
+  preparePlatformPackages();
+}
+
+module.exports = {
+  preparePlatformPackages,
+  targets,
+};