@maptec/cli 1.0.0

package/LICENSE

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

@@ -0,0 +1,284 @@
+# @maptec/cli
+
+Maptec 地图服务命令行工具。面向开发者与 AI Agent，提供地理编码、地点检索与路线规划能力，并以结构化 JSON 输出结果。
+
+## 安装
+
+```bash
+npm install -g @maptec/cli
+```
+
+也可通过 `npx` 临时运行：
+
+```bash
+npx @maptec/cli --help
+```
+
+要求 Node.js ≥ 18。
+
+## 快速开始
+
+```bash
+maptec init
+maptec config get
+maptec geocode --address "Orchard Road" --region SG --format json
+```
+
+`maptec init` 将引导配置 API Key 与 Base URL，并写入 `~/.maptec/config.json`。
+
+## 配置
+
+### 配置文件
+
+路径：`~/.maptec/config.json`
+
+| 字段 | 说明 | 默认值 |
+|------|------|--------|
+| `apiKey` | Maptec API Key | 必填 |
+| `baseUrl` | WebAPI 根地址 | 必填 |
+| `defaultFormat` | 输出格式：`json` \| `table` | `json` |
+| `timeoutMs` | 请求超时（毫秒） | `30000` |
+
+```json
+{
+  "apiKey": "YOUR_API_KEY",
+  "baseUrl": "https://api.maptec.com",
+  "defaultFormat": "json",
+  "timeoutMs": 30000
+}
+```
+
+### 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `MAPTEC_API_KEY` | 覆盖配置文件中的 API Key |
+| `MAPTEC_BASE_URL` | 覆盖 Base URL |
+| `MAPTEC_API_URL` | `MAPTEC_BASE_URL` 的兼容别名 |
+
+Base URL 解析顺序：`MAPTEC_BASE_URL` → `MAPTEC_API_URL` → 配置文件 `baseUrl`。
+
+### 命令行配置
+
+```bash
+maptec config get
+maptec config set api-key YOUR_API_KEY
+maptec config set base-url https://api.maptec.com
+maptec config set default-format json
+maptec config set timeout 60000
+```
+
+`config set` 支持的键：`api-key`、`base-url`、`default-format`、`timeout`（及其驼峰别名）。
+
+---
+
+## 全局选项
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--format <json\|table>` | 输出格式 | `json` |
+| `--out <file>` | 将结果写入文件 | — |
+| `--quiet` | 减少 stderr 提示信息 | `false` |
+| `--timeout <ms>` | 覆盖请求超时 | 配置文件值 |
+| `--fields <list>` | 裁剪输出字段（逗号分隔） | — |
+| `-V, --version` | 显示版本号 | — |
+
+### 成功输出
+
+```json
+{
+  "ok": true,
+  "command": "geocode",
+  "data": {}
+}
+```
+
+### 退出码
+
+| 码 | 含义 |
+|----|------|
+| `0` | 成功 |
+| `1` | 参数错误 |
+| `2` | 未配置 `apiKey` 或 `baseUrl` |
+| `3` | API 业务错误 |
+| `4` | 网络错误或超时 |
+| `5` | 内部错误 |
+
+---
+
+## 命令
+
+### `maptec geocode`
+
+地址 → 坐标。
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--address <text>` | 是 | 地址 |
+| `--language <code>` | 否 | 语言，如 `en`、`zh-CN` |
+| `--region <code>` | 否 | 地区偏向，如 `SG`、`CN` |
+
+```bash
+maptec geocode --address "Orchard Road" --language en --region SG --format json
+```
+
+### `maptec reverse-geocode`
+
+坐标 → 地址。
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--lat <number>` | 是 | 纬度 |
+| `--lng <number>` | 是 | 经度 |
+| `--language <code>` | 否 | 语言 |
+| `--region <code>` | 否 | 地区偏向 |
+| `--result-type <types>` | 否 | 结果类型过滤（`|` 分隔） |
+| `--location-type <types>` | 否 | 精度类型过滤 |
+
+```bash
+maptec reverse-geocode --lat 1.3048 --lng 103.8318 --language en --format json
+```
+
+### `maptec search text`
+
+关键词检索。
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--query <text>` | 是 | 关键词 |
+| `--location <lng,lat>` | 否 | 位置偏向：`lng,lat` 或 `lng,lat,radius` |
+| `--language <code>` | 否 | 语言（默认 `en`） |
+| `--region <code>` | 否 | 地区 |
+| `--page-size <n>` | 否 | 每页条数（默认 `20`） |
+| `--type <category>` | 否 | POI 类别 |
+| `--rank <mode>` | 否 | `RELEVANCE` \| `DISTANCE` \| `POPULARITY` |
+
+```bash
+maptec search text \
+  --query "cafe" \
+  --location "103.83,1.30,3000" \
+  --language en \
+  --region SG \
+  --page-size 10 \
+  --format json
+```
+
+### `maptec search nearby`
+
+周边检索。
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--lat <number>` | 是 | 圆心纬度 |
+| `--lng <number>` | 是 | 圆心经度 |
+| `--radius <meters>` | 否 | 半径，米（默认 `500`） |
+| `--types <list>` | 否 | POI 类型，逗号分隔 |
+| `--limit <n>` | 否 | 结果数量上限（默认 `20`） |
+| `--language <code>` | 否 | 语言（默认 `en`） |
+| `--region <code>` | 否 | 地区 |
+| `--rank <mode>` | 否 | 排序（默认 `DISTANCE`） |
+
+```bash
+maptec search nearby \
+  --lat 1.3048 \
+  --lng 103.8318 \
+  --radius 1000 \
+  --types "restaurant,cafe" \
+  --limit 10 \
+  --format json
+```
+
+### `maptec search suggest`
+
+输入提示。
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--query <text>` | 是 | 输入文本 |
+| `--location <lng,lat>` | 否 | 位置偏向 |
+| `--language <code>` | 否 | 语言（默认 `en`） |
+| `--region <code>` | 否 | 地区 |
+| `--limit <n>` | 否 | 结果数量上限（默认 `20`） |
+
+```bash
+maptec search suggest --query "Orch" --location "103.83,1.30" --limit 5 --format json
+```
+
+### `maptec search place`
+
+地点详情。
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--id <placeId>` | 是 | 地点 ID |
+| `--language <code>` | 否 | 语言 |
+| `--region <code>` | 否 | 地区 |
+| `--session-token <token>` | 否 | 会话令牌 |
+
+```bash
+maptec search place --id "<placeId>" --language en --format json
+```
+
+### `maptec route driving` / `maptec route truck`
+
+路线规划。起终点任选一种写法：
+
+- `--from` / `--to`：地址、`lng,lat` 或 place ID
+- `--from-lat` + `--from-lng` / `--to-lat` + `--to-lng`：坐标分量
+
+文本地址会自动进行地理编码。
+
+| 选项 | 说明 |
+|------|------|
+| `--strategy <name>` | `fastest` \| `shortest` \| `eco` \| `balanced` |
+| `--language <code>` | 导航语言 |
+| `--height <meters>` | 车高（仅 `truck`） |
+| `--weight <tons>` | 总重（仅 `truck`） |
+| `--length <meters>` | 车长（仅 `truck`） |
+
+默认输出 `distance`、`duration`、`summary`。需要路径几何时增加 `--fields polyline`。
+
+可选字段：`distance`、`duration`、`summary`、`polyline`、`warnings`、`legs`。
+
+```bash
+maptec route driving \
+  --from "Orchard Road" \
+  --to "North Bridge Rd" \
+  --fields distance,duration,summary \
+  --format json
+
+maptec route driving \
+  --from-lat 1.2966 --from-lng 103.7764 \
+  --to-lat 1.3048 --to-lng 103.8318 \
+  --strategy fastest \
+  --format json
+
+maptec route truck \
+  --from "103.85,1.29" \
+  --to "103.83,1.30" \
+  --height 4.2 \
+  --weight 10 \
+  --length 12 \
+  --fields distance,duration,summary \
+  --format json
+```
+
+---
+
+## 示例
+
+```bash
+# 将结果写入文件
+maptec geocode --address "Orchard Road" --region SG --format json --out result.json
+
+# 检索后查询地点详情
+maptec search suggest --query "Orchard" --limit 1 --format json
+maptec search place --id "<placeId>" --format json
+
+# 人类可读配置
+maptec config get --format table
+```
+
+## License
+
+[MIT](./LICENSE) © 2026 Maptec

package/bin/maptec.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/chunk-K574OFFK.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+// src/config/store.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+
+// src/config/env.ts
+var DEFAULT_CONFIG = {
+  defaultFormat: "json",
+  timeoutMs: 3e4
+};
+var API_VERSION = "v1";
+function normalizeBaseUrl(value) {
+  const trimmed = value.trim().replace(/\/+$/, "");
+  if (!trimmed) {
+    throw new Error("baseUrl \u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (!/^https?:\/\//i.test(trimmed)) {
+    throw new Error(`\u65E0\u6548 baseUrl "${value}"\uFF0C\u9700\u4EE5 http:// \u6216 https:// \u5F00\u5934`);
+  }
+  return trimmed;
+}
+function resolveBaseUrl(config) {
+  const fromBase = process.env.MAPTEC_BASE_URL?.trim();
+  if (fromBase) {
+    return normalizeBaseUrl(fromBase);
+  }
+  const fromApiUrl = process.env.MAPTEC_API_URL?.trim();
+  if (fromApiUrl) {
+    return normalizeBaseUrl(fromApiUrl);
+  }
+  const fromConfig = config.baseUrl?.trim();
+  if (fromConfig) {
+    return normalizeBaseUrl(fromConfig);
+  }
+  return void 0;
+}
+function resolveApiKey(config) {
+  const fromEnv = process.env.MAPTEC_API_KEY?.trim();
+  if (fromEnv) return fromEnv;
+  return config.apiKey?.trim() || void 0;
+}
+function maskApiKey(key) {
+  if (key.length <= 8) return "****";
+  return `${key.slice(0, 3)}...${key.slice(-4)}`;
+}
+
+// src/config/store.ts
+var CONFIG_DIR = join(homedir(), ".maptec");
+var CONFIG_PATH = join(CONFIG_DIR, "config.json");
+function getConfigPath() {
+  return CONFIG_PATH;
+}
+async function loadConfig() {
+  try {
+    const raw = await readFile(CONFIG_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    const { env: _legacyEnv, ...rest } = parsed;
+    return {
+      ...DEFAULT_CONFIG,
+      ...rest
+    };
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { ...DEFAULT_CONFIG };
+    }
+    throw err;
+  }
+}
+async function saveConfig(config) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  const { env: _legacyEnv, ...rest } = config;
+  await writeFile(CONFIG_PATH, `${JSON.stringify(rest, null, 2)}
+`, "utf8");
+}
+async function setConfigValue(key, value) {
+  const config = await loadConfig();
+  switch (key) {
+    case "apiKey":
+      config.apiKey = String(value);
+      break;
+    case "baseUrl":
+      config.baseUrl = normalizeBaseUrl(String(value));
+      break;
+    case "defaultFormat":
+      if (value !== "json" && value !== "table") {
+        throw new Error("defaultFormat \u4EC5\u652F\u6301 json \u6216 table");
+      }
+      config.defaultFormat = value;
+      break;
+    case "timeoutMs":
+      config.timeoutMs = Number(value);
+      if (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0) {
+        throw new Error("timeoutMs \u5FC5\u987B\u4E3A\u6B63\u6574\u6570");
+      }
+      break;
+  }
+  await saveConfig(config);
+  return config;
+}
+async function setApiKey(value) {
+  return setConfigValue("apiKey", value);
+}
+async function setBaseUrl(value) {
+  return setConfigValue("baseUrl", value);
+}
+
+export {
+  API_VERSION,
+  normalizeBaseUrl,
+  resolveBaseUrl,
+  resolveApiKey,
+  maskApiKey,
+  getConfigPath,
+  loadConfig,
+  saveConfig,
+  setConfigValue,
+  setApiKey,
+  setBaseUrl
+};
+//# sourceMappingURL=chunk-K574OFFK.js.map

package/dist/chunk-K574OFFK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config/store.ts","../src/config/env.ts"],"sourcesContent":["import { mkdir, readFile, writeFile } from 'node:fs/promises';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\nimport {\n  DEFAULT_CONFIG,\n  normalizeBaseUrl,\n  type MaptecConfig,\n} from './env.js';\n\nconst CONFIG_DIR = join(homedir(), '.maptec');\nconst CONFIG_PATH = join(CONFIG_DIR, 'config.json');\n\nexport function getConfigPath(): string {\n  return CONFIG_PATH;\n}\n\nexport async function loadConfig(): Promise<MaptecConfig> {\n  try {\n    const raw = await readFile(CONFIG_PATH, 'utf8');\n    const parsed = JSON.parse(raw) as Partial<MaptecConfig> & { env?: string };\n    const { env: _legacyEnv, ...rest } = parsed;\n    return {\n      ...DEFAULT_CONFIG,\n      ...rest,\n    };\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {\n      return { ...DEFAULT_CONFIG };\n    }\n    throw err;\n  }\n}\n\nexport async function saveConfig(config: MaptecConfig): Promise<void> {\n  await mkdir(CONFIG_DIR, { recursive: true });\n  const { env: _legacyEnv, ...rest } = config as MaptecConfig & { env?: string };\n  await writeFile(CONFIG_PATH, `${JSON.stringify(rest, null, 2)}\\n`, 'utf8');\n}\n\nexport async function setConfigValue(\n  key: 'apiKey' | 'baseUrl' | 'defaultFormat' | 'timeoutMs',\n  value: string | number,\n): Promise<MaptecConfig> {\n  const config = await loadConfig();\n  switch (key) {\n    case 'apiKey':\n      config.apiKey = String(value);\n      break;\n    case 'baseUrl':\n      config.baseUrl = normalizeBaseUrl(String(value));\n      break;\n    case 'defaultFormat':\n      if (value !== 'json' && value !== 'table') {\n        throw new Error('defaultFormat 仅支持 json 或 table');\n      }\n      config.defaultFormat = value;\n      break;\n    case 'timeoutMs':\n      config.timeoutMs = Number(value);\n      if (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0) {\n        throw new Error('timeoutMs 必须为正整数');\n      }\n      break;\n  }\n  await saveConfig(config);\n  return config;\n}\n\nexport async function setApiKey(value: string): Promise<MaptecConfig> {\n  return setConfigValue('apiKey', value);\n}\n\nexport async function setBaseUrl(value: string): Promise<MaptecConfig> {\n  return setConfigValue('baseUrl', value);\n}\n","export interface MaptecConfig {\n  apiKey?: string;\n  baseUrl?: string;\n  defaultFormat: 'json' | 'table';\n  timeoutMs: number;\n}\n\nexport const DEFAULT_CONFIG: MaptecConfig = {\n  defaultFormat: 'json',\n  timeoutMs: 30_000,\n};\n\nexport const API_VERSION = 'v1';\n\n/** 去掉尾部斜杠，校验非空 URL 形态 */\nexport function normalizeBaseUrl(value: string): string {\n  const trimmed = value.trim().replace(/\\/+$/, '');\n  if (!trimmed) {\n    throw new Error('baseUrl 不能为空');\n  }\n  if (!/^https?:\\/\\//i.test(trimmed)) {\n    throw new Error(`无效 baseUrl \"${value}\"，需以 http:// 或 https:// 开头`);\n  }\n  return trimmed;\n}\n\n/**\n * 解析 API 根地址。优先级：\n * 1. MAPTEC_BASE_URL\n * 2. MAPTEC_API_URL（兼容别名）\n * 3. 配置文件 baseUrl\n */\nexport function resolveBaseUrl(config: MaptecConfig): string | undefined {\n  const fromBase = process.env.MAPTEC_BASE_URL?.trim();\n  if (fromBase) {\n    return normalizeBaseUrl(fromBase);\n  }\n  const fromApiUrl = process.env.MAPTEC_API_URL?.trim();\n  if (fromApiUrl) {\n    return normalizeBaseUrl(fromApiUrl);\n  }\n  const fromConfig = config.baseUrl?.trim();\n  if (fromConfig) {\n    return normalizeBaseUrl(fromConfig);\n  }\n  return undefined;\n}\n\nexport function resolveApiKey(config: MaptecConfig): string | undefined {\n  const fromEnv = process.env.MAPTEC_API_KEY?.trim();\n  if (fromEnv) return fromEnv;\n  return config.apiKey?.trim() || undefined;\n}\n\nexport function maskApiKey(key: string): string {\n  if (key.length <= 8) return '****';\n  return `${key.slice(0, 3)}...${key.slice(-4)}`;\n}\n"],"mappings":"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","names":[]}