# @deutschlandgpt/beacon-sdk 中文文档

规范地址：https://npmcn.com/package/%40deutschlandgpt/beacon-sdk/

版本：0\.1\.8
npm 元数据更新时间：2026-11-11T14:34:56.927Z
中文译文更新时间：2026-11-12T01:45:32.278Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deutschlandgpt/beacon-sdk
原文对照：https://npmcn.com/package/%40deutschlandgpt/beacon-sdk/?lang=original
项目主页：https://github.com/deutschlandgpt/beacon-sdk#readme
源码仓库：https://github.com/deutschlandgpt/beacon-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：84.4 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-02-19T13:20:17.991Z
- 最新版本发布：2026-11-11T14:34:56.510Z
- 近 30 天下载量：37893（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

DGPT 灯塔 API 的 SDK 脚本

## 安装

```sh
npm install @deutschlandgpt/beacon-sdk
```

也可以使用：`pnpm add @deutschlandgpt/beacon-sdk`、`yarn add @deutschlandgpt/beacon-sdk`、`bun add @deutschlandgpt/beacon-sdk`

## README

# 灯塔SDK

TypeScript SDK 对于灯塔状态页面 API. 与更改日志,监视器,事件等互动.

## 安装

```bash
pnpm add @deutschlandgpt/beacon-sdk
```

## 所需资源

-   节点.js 18或以上
-   类型脚本 5.0+(用于类型脚本项目)

## 快速启动

```typescript
import { BeaconClient } from "@deutschlandgpt/beacon-sdk";

// Initialize the client
const beacon = new BeaconClient({
  baseUrl: "https://your-beacon-instance.com",
  apiKey: "your-api-key", // Optional, required for authenticated endpoints
});

// Fetch changelogs
const changelogs = await beacon.changelogs.list();
console.log(changelogs);
```

## 配置

这个 `BeaconClient` 接受以下配置选项:

```typescript
const beacon = new BeaconClient({
  baseUrl: string;        // Your Beacon instance URL (required)
  apiKey?: string;        // API key for authenticated endpoints (optional)
  fetch?: typeof fetch;   // Custom fetch implementation (optional)
});
```

## API 参考

### 更改日志

从灯塔实例中列出并检索更改日志 .

```typescript
// List all changelogs
const changelogs = await beacon.changelogs.list();

// List with filters
const filtered = await beacon.changelogs.list({
  tag: "api", // Filter by tag: 'api' | 'chat' | 'workflows'
  since: "2024-01-01", // Only changelogs after this date
  breaking: true, // Only breaking changes
  limit: 10, // Limit results
  offset: 0, // Pagination offset
});

// Get a specific changelog by ID
const changelog = await beacon.changelogs.get("changelog-id");
```

### 监视器

检查监测服务的状况.

```typescript
// Get status of all monitors
const monitors = await beacon.monitors.status();

// Each monitor includes:
// - id, name, description
// - currentStatus: 'operational' | 'degraded' | 'outage' | 'unknown'
// - responseTime, statusCode, lastChecked
// - uptimePercent: 90-day uptime as a string (e.g. "99.95"), or null
// - dailySummaries: per-day check summaries (up to 90 days)
```

### 事件

检索事件信息.

```typescript
// List all incidents
const incidents = await beacon.incidents.list();

// Get active incidents (requires API key)
const activeIncidents = await beacon.incidents.active();

// Incidents for display inside the host app (requires API key). Includes internal and
// audience-targeted incidents plus client scopes; filter per user on YOUR server and
// never forward `audience` to a browser.
const inApp = await beacon.incidents.inApp({ locale: 'de' });

// Incident properties include:
// - status: 'investigating' | 'identified' | 'monitoring' | 'resolved'
// - severity: 'minor' | 'major' | 'critical'
// - affectedMonitorIds: array of affected monitor IDs
```

### 订阅者

管理电子邮件订阅 .

```typescript
// Subscribe to updates
const response = await beacon.subscribers.subscribe({
  email: "user@example.com",
  subscribeTo: ["changelogs", "status_updates", "newsletters"],
});

// Subscription types:
// - 'changelogs': Product changelog updates
// - 'status_updates': Service status updates
// - 'newsletters': General newsletters
```

### 反馈

提交用户反馈. `submit()` 需要 API 键并返回创建的 反馈加上类似的现有反馈; `submitPublic()` 未认证 (公共/嵌入式), **需求 `userEmail`**返回时 `{ success: true }`。 。 。 .

```typescript
// Submit feedback (requires API key)
const result = await beacon.feedback.submit({
  type: "bug_report", // 'bug_report' | 'feature_request' | 'improvement' | 'support' | 'security' | 'other'
  title: "Issue with login",
  description: "Detailed description of the issue",

  // Optional fields
  userEmail: "user@example.com",
  userName: "John Doe",
  featureOrService: "Authentication",
  planTier: "Pro",
  browserInfo: navigator.userAgent,
  deviceInfo: "Desktop",
  pageUrl: "https://app.example.com/dashboard", // URL where the feedback was submitted
  consentToNotify: true,
  tags: { source: "widget", region: "eu" }, // Arbitrary key/value metadata
  attachments: [file1, file2], // Array of File objects

  // Authenticated-only (see below): where the reporter's organisation stands
  // commercially, so support can prioritise a customer who is still evaluating.
  reporterStage: "trial_business", // 'customer' | 'trial_business' | 'trial_enterprise'
  reporterTrialEndsAt: "2026-08-24T00:00:00.000Z", // ISO 8601; snapshot at report time
});

// Response includes the created feedback and similar existing feedback
console.log(result.feedback);
console.log(result.similar);

// The returned feedback carries a lifecycle status and a server-assigned urgency:
// status:  'new' | 'investigating' | 'in_progress' | 'waiting_for_user' | 'planned' | 'resolved' | 'wont_fix'
// urgency: 'critical' | 'high' | 'medium' | 'low' | null  (classified automatically, read-only)

// Submit feedback from a public form (no API key required — userEmail is required)
await beacon.feedback.submitPublic({
  type: "feature_request",
  title: "Add dark mode",
  description: "Please add a dark theme",
  userEmail: "user@example.com",
});
```

`reporterStage` 财务报告和审定财务报表 `reporterTrialEndsAt` 已接受 **仅限** 以 `submit()`。 。 。 . `submitPublic()` 贴到一个未经证实的终点, 所以一个呼叫者决不能是 能够要求对自己的票进行优先审判——灯塔剥去两个字段 在这里。 因此,他们生活在 `SubmitFeedbackParams` 而不是共享的 `FeedbackParamsBase`,以及 `SubmitPublicFeedbackParams` 根本不接受它们.

当反馈与一个 `userEmail`,用户可以通过 由反馈确定的公共对话线索 `publicToken`数字 :

```typescript
// Fetch the message thread for a feedback item
const messages = await beacon.feedback.messages("public-token");

// Post a user reply to the thread
const message = await beacon.feedback.sendMessage({
  token: "public-token",
  body: "Any update on this?",
});
```

## 处理错误

SDK为不同的出错情况提供打入错误分类:

```typescript
import {
  BeaconError,
  BeaconValidationError,
  BeaconAuthError,
  BeaconNotFoundError,
} from "@deutschlandgpt/beacon-sdk";

try {
  const changelogs = await beacon.changelogs.list();
} catch (error) {
  if (error instanceof BeaconAuthError) {
    console.error("Authentication failed:", error.message);
  } else if (error instanceof BeaconNotFoundError) {
    console.error("Resource not found:", error.message);
  } else if (error instanceof BeaconValidationError) {
    console.error("Validation error:", error.message);
    console.error("Details:", error.details);
  } else if (error instanceof BeaconError) {
    console.error("API error:", error.message);
    console.error("Status:", error.status);
  }
}
```

### 错误类型

-   `BeaconError`: 所有 SDK 错误的基准错误分类
-   `BeaconValidationError`: 校验错误( 400 状态)
-   `BeaconAuthError`: 认证错误( 401 状态)
-   `BeaconNotFoundError`: 资源未发现出错( 404 状态)

## 类型脚本支持

SDK被用TypeScript来写作并包括了完整的类型定义. 所有 API 响应和参数均输入:

```typescript
import type {
  Changelog,
  MonitorStatusEntry,
  Incident,
  Feedback,
  ChangelogListParams,
  SubmitFeedbackParams,
  FeedbackReporterStage,
} from "@deutschlandgpt/beacon-sdk";

// Types are automatically inferred
const changelogs: Changelog[] = await beacon.changelogs.list();
const monitor: MonitorStatusEntry = monitors[0];
```

## 实例

### 显示系统状态

```typescript
const monitors = await beacon.monitors.status();
const activeIncidents = await beacon.incidents.list();

monitors.forEach((monitor) => {
  console.log(`${monitor.name}: ${monitor.currentStatus}`);
  console.log(`Response time: ${monitor.responseTime}ms`);
});

if (activeIncidents.length > 0) {
  console.log("\nActive Incidents:");
  activeIncidents.forEach((incident) => {
    console.log(`[${incident.severity}] ${incident.title}`);
    console.log(`Status: ${incident.status}`);
  });
}
```

### 获取最近的更改日志

```typescript
const recentChanges = await beacon.changelogs.list({
  limit: 5,
  since: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
});

recentChanges.forEach((changelog) => {
  console.log(`v${changelog.version} - ${changelog.title}`);
  console.log(changelog.content);
  console.log(`Tags: ${changelog.tags.join(", ")}`);
  if (changelog.isBreakingChange) {
    console.log("⚠️ Breaking Change");
  }
});
```

### 用户反馈收藏

```typescript
// Collect feedback with file attachments
const fileInput = document.querySelector<HTMLInputElement>("#file-input");
const files = Array.from(fileInput?.files ?? []);

const feedback = await beacon.feedback.submit({
  type: "bug_report",
  title: "Cannot upload files",
  description: "Getting an error when uploading files larger than 10MB",
  userEmail: "user@example.com",
  featureOrService: "File Upload",
  attachments: files,
});

console.log("Feedback submitted:", feedback.feedback.id);

if (feedback.similar.length > 0) {
  console.log("Similar feedback found:");
  feedback.similar.forEach((item) => {
    console.log(`- ${item.title} (${item.status})`);
  });
}
```

## 释放

出版由git标签驱动,而不是由 `version` 输入 `package.json`。推动标签喜欢 `0.1.0` 从承诺 `master` 触发发布工作流程,该工作流程从标签和覆盖中获取已发布的版本 `package.json` 在建设时间。 手动将版本撞入 `package.json` 对出版内容没有任何影响.

```bash
git tag 0.1.0
git push origin 0.1.0
```

## 许可证

麻省理工学院

## 作者

德国GPT

## 常见问题

### @deutschlandgpt/beacon-sdk 是什么？

DGPT 灯塔 API 的 SDK 脚本

### 如何安装 @deutschlandgpt/beacon-sdk？

在项目目录运行 npm install @deutschlandgpt/beacon-sdk，或使用 pnpm add / yarn add / bun add。

### @deutschlandgpt/beacon-sdk 支持 TypeScript 吗？

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

### @deutschlandgpt/beacon-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @deutschlandgpt/beacon-sdk 需要什么版本的 Node\.js？

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

### @deutschlandgpt/beacon-sdk 可以商用吗？

@deutschlandgpt/beacon-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deutschlandgpt/beacon-sdk 的下载量有多少？

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

### @deutschlandgpt/beacon-sdk 还在维护吗？

最新版本 0\.1\.8 发布于 2026/11/11（今天）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/02/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。