@groundcover/api-client

中文文档
0.82.0发布于 2026/11/16Apache-2.0TypeScriptES Module近 30 天下载 8603

groundcover TypeScript API Client

原始使用文档
文档目录9 节
  1. Requirements
  2. Installation
  3. Quick Start
  4. Configuration
  5. Monitors (YAML)
  6. Error Handling
  7. Retry Behavior
  8. Development
  9. License

groundcover TypeScript SDK

Official TypeScript/JavaScript SDK for the groundcover API.

Requirements

  • Node.js (>= 18.0.0)
  • Bun (>= 1.0.0)
  • Deno (>= 1.37.0)
  • A groundcover API key and Backend ID

Installation

# npm
npm install @groundcover/api-client

# yarn
yarn add @groundcover/api-client

# pnpm
pnpm add @groundcover/api-client

# bun
bun add @groundcover/api-client

# deno
deno add npm:@groundcover/api-client

Quick Start

import { initClient } from '@groundcover/api-client';
import { metricsQuery } from '@groundcover/api-client';

// Initialize the client
// Uses GC_API_KEY and GC_BACKEND_ID from environment by default
const client = initClient();

async function run() {
  const now = new Date();
  const start = new Date(now.getTime() - 60 * 60 * 1000);

  const result = await metricsQuery({
    client,
    body: {
      Promql: 'up',
      QueryType: 'instant',
      Start: start.toISOString(),
      End: now.toISOString(),
      Step: '1m',
    },
  });

  console.log(result.data);
}

run();

The SDK provides typed API functions as the primary interface. Import the operation module and call it with the client:

import { searchLogs } from '@groundcover/api-client';

const result = await searchLogs({
  client,
  body: {
    start: start.toISOString(),
    end: now.toISOString(),
    query: '* | stats count(*)',
  },
});

Raw HTTP methods (client.get(), client.post(), etc.) remain available for advanced use cases or endpoints not yet available as typed functions.

Configuration

The SDK reads from environment variables by default:

VariableDescriptionRequired
GC_API_KEYYour groundcover API keyYes
GC_BACKEND_IDYour groundcover Backend IDYes
GC_BASE_URLAPI base URL (default: https://api.groundcover.com)No
GC_TRACEPARENTDefault traceparent header for tracingNo

You can also pass configuration explicitly:

const client = initClient({
  apiKey: 'your-api-key',
  backendId: 'your-backend-id',
  baseUrl: 'https://api.groundcover.com',
  timeout: 60000,
  maxRetries: 5,
});

Monitors (YAML)

Monitor endpoints return YAML content-type. The SDK provides a convenience wrapper getMonitorParsed to automatically parse the YAML response into a JavaScript object:

import { getMonitorParsed, createMonitor, updateMonitor } from '@groundcover/api-client';

// Fetch and automatically parse YAML to a JS object
const { data: monitorObj, error } = await getMonitorParsed({ client, path: { id: 'monitor-id' } });

// Create or update using standard JS objects
// (Since JSON is a valid subset of YAML, the standard client correctly serializes your object)
await createMonitor({ 
  client, 
  body: { name: 'My Monitor', type: 'logs' } 
});

await updateMonitor({ 
  client, 
  path: { id: 'monitor-id' }, 
  body: updatedMonitorObj 
});

Error Handling

All requests — both typed API calls and raw HTTP methods — return an error object inside the result if the request fails:

import { getDashboard } from '@groundcover/api-client';

const result = await getDashboard({
  client,
  path: { id: 'nonexistent' }
});

if (result.error) {
  console.error(`API error:`, result.error);
} else {
  console.log(result.data);
}

Retry Behavior

By default, the SDK retries idempotent requests (GET, HEAD, OPTIONS, TRACE) on HTTP 429 and 503 with exponential backoff and jitter:

  • Default retries: 3
  • Default retry statuses: 429, 503
  • Backoff: Exponential with jitter, 1s min, 30s max

Development

The published client still runs on Node.js 18+. The Vitest/Vite toolchain used for pnpm test:unit needs Node.js 20.19+ or 22.12+ (Vite 8 / Vitest 4).

cd sdk-typescript
pnpm install

# Run unit tests
pnpm test:unit

# Run e2e tests
pnpm test:e2e

# Run linting
pnpm lint

# Format code
pnpm format

License

Apache 2.0 — see LICENSE.

版本与发布记录

@groundcover/api-client 共发布 79 个版本,首次发布于 2026/08/10;过去 12 个月发布了 79 个版本。

版本发布日期距今
0.82.0latest2026/11/16今天
0.81.02026/11/16今天
0.80.02026/11/134 天前
0.79.02026/11/124 天前
0.78.02026/11/115 天前
0.77.02026/11/106 天前

关于 @groundcover/api-client 的常见问题

@groundcover/api-client 是什么?

groundcover TypeScript API Client

如何安装 @groundcover/api-client?

在项目目录运行 npm install @groundcover/api-client,或使用 pnpm add / yarn add / bun add。

@groundcover/api-client 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@groundcover/api-client 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@groundcover/api-client 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@groundcover/api-client 可以商用吗?

@groundcover/api-client 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@groundcover/api-client 的下载量有多少?

根据 npm 官方下载统计,@groundcover/api-client 在 2026/10/17 – 2026/11/15 这 30 天内被下载 8,603 次,日均约 287 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@groundcover/api-client 还在维护吗?

最新版本 0.82.0 发布于 2026/11/16(今天);至今共发布 79 个版本,其中过去 12 个月发布了 79 个;首次发布于 2026/08/10。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。