灯塔SDK

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

安装

pnpm add @deutschlandgpt/beacon-sdk

所需资源

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

快速启动

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 接受以下配置选项:

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 参考

更改日志

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

// 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");

监视器

检查监测服务的状况.

// 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)

事件

检索事件信息.

// 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

订阅者

管理电子邮件订阅 .

// Subscribe to updates
const response = await beacon.subscribers.subscribe({
  email: "[email protected]",
  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 }。 。 。 .

// 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: "[email protected]",
  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: "[email protected]",
});

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

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

// 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为不同的出错情况提供打入错误分类:

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 响应和参数均输入:

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];

实例

显示系统状态

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}`);
  });
}

获取最近的更改日志

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");
  }
});

用户反馈收藏

// 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: "[email protected]",
  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 对出版内容没有任何影响.

git tag 0.1.0
git push origin 0.1.0

许可证

麻省理工学院

作者

德国GPT