Vybit Push Notifications

Vybit SDK

用于集成 Vybit 通知平台的官方 TypeScript/JavaScript SDK。

Vybit 是一项推送通知服务，提供个性化音效，用户可以自行录制，也可以从数千种可搜索音效库中选择（通过 freesound.org）。

概览

Vybit 为不同使用场景提供多种集成方式：

Package	Use Case	Authentication	Best For
@vybit/api-sdk	后端/自动化	API Key 或 OAuth2 Token	服务器到服务器的集成、自动化、监控系统
@vybit/oauth2-sdk	面向用户的应用	OAuth 2.0（用户授权）	用户连接 Vybit 账户的 Web 应用（仅限认证流程）
@vybit/cli	命令行	API Key	Shell 脚本、CI/CD、Agent 工具、快速操作
@vybit/mcp-server	AI 助手	API Key 或 OAuth2 Token	Claude Desktop、Claude Code 和其他兼容 MCP 的 AI 工具
@vybit/n8n-nodes-vybit	工作流自动化	API Key 或 OAuth2	n8n 工作流、无代码/低代码自动化、集成平台

所有软件包共用 @vybit/core 中的通用工具。

---

开发者 API SDK

适用于后端服务、自动化和服务器到服务器的集成

安装

npm install @vybit/api-sdk

入门

1. 获取 API Key

   • 在 developer.vybit.net 注册
   • 前往 Developer API 部分
   • 复制 API Key

2. 初始化客户端

import { VybitAPIClient } from '@vybit/api-sdk';

// With API key
const client = new VybitAPIClient({
  apiKey: 'your-api-key-from-developer-portal'
});

// Or with an OAuth2 access token
const client = new VybitAPIClient({
  accessToken: 'your-oauth2-access-token'
});

常见操作

创建和管理 Vybit

// Create a vybit (only name is required)
const vybit = await client.createVybit({
  name: 'Server Alert'
});

// List vybits with search and pagination
const vybits = await client.listVybits({
  search: 'alert',
  limit: 10,
  offset: 0
});

// Get a specific vybit
const details = await client.getVybit('vybit-id');

// Update a vybit
await client.updateVybit('vybit-id', {
  name: 'Updated Server Alert',
  status: 'on'
});

// Delete a vybit
await client.deleteVybit('vybit-id');

触发通知

// Simple trigger
await client.triggerVybit('vybit-key');

// Trigger with custom content
await client.triggerVybit('vybit-key', {
  message: 'Server CPU usage at 95%',
  imageUrl: 'https://example.com/graph.png',  // Must be a direct link to a JPG, PNG, or GIF image
  linkUrl: 'https://dashboard.example.com',
  log: 'CPU spike detected on web-server-01'
});

管理音效

// List available sounds
const sounds = await client.listSounds({
  search: 'alert',
  limit: 20
});

// Get sound details
const sound = await client.getSound('sound-key');

发现并订阅公开 Vybit

// Browse public vybits (returns PublicVybit[])
const publicVybits = await client.listPublicVybits({
  search: 'weather',
  limit: 10
});

// Get details about a public vybit before subscribing
const vybitDetails = await client.getPublicVybit('subscription-key-abc123');

// Subscribe to a public vybit using its subscription key
const follow = await client.createVybitFollow({
  subscriptionKey: vybitDetails.key
});

// List your subscriptions
const subscriptions = await client.listVybitFollows();

// Unsubscribe from a vybit
await client.deleteVybitFollow(follow.followingKey);

监控用量

// Get current usage and limits
const meter = await client.getMeter();
console.log(`Daily: ${meter.count_daily} / ${meter.cap_daily}`);
console.log(`Monthly: ${meter.count_monthly} / ${meter.cap_monthly}`);
console.log(`Tier: ${meter.tier_id}`);

API 参考

• 📖 交互式文档：developer.vybit.net/api-reference
• 📋 OpenAPI 规范：docs/openapi/developer-api.yaml

---

OAuth2 SDK

适用于需要代表用户访问 Vybit 的面向用户的应用

OAuth2 SDK 仅处理授权流程。获取访问令牌后，请使用 @vybit/api-sdk 中的 VybitAPIClient 执行所有 API 操作。

安装

npm install @vybit/oauth2-sdk @vybit/api-sdk

入门

1. 注册应用

   • 在 developer.vybit.net 注册
   • 前往 OAuth Configuration 部分
   • 输入 OAuth Client ID 和 Redirect URI
   • 复制 Client ID 和 Client Secret

2. 初始化 OAuth2 客户端

import { VybitOAuth2Client } from '@vybit/oauth2-sdk';

const oauthClient = new VybitOAuth2Client({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  redirectUri: 'https://yourapp.com/oauth/callback'
});

OAuth 流程

第 1 步：将用户重定向到授权页面

const authUrl = oauthClient.getAuthorizationUrl({
  state: 'random-state-string'
});

// Redirect user to authUrl
// They will authorize your app and be redirected back to your redirectUri

第 2 步：将授权码兑换为令牌

// After redirect, extract the code from query params
const code = urlParams.get('code');

// Exchange code for access token
const token = await oauthClient.exchangeCodeForToken(code);

// Store token.access_token securely for future requests

第 3 步：通过 API SDK 使用令牌

import { VybitAPIClient } from '@vybit/api-sdk';

// Create an API client with the OAuth2 access token
const apiClient = new VybitAPIClient({
  accessToken: token.access_token
});

// Now use the full Developer API on behalf of the user
const vybits = await apiClient.listVybits();
await apiClient.triggerVybit('vybit-key', {
  message: 'Hello from your app!'
});

令牌管理

// Verify a token is still valid
const isValid = await oauthClient.verifyToken(token.access_token);

// Store and retrieve tokens
oauthClient.setAccessToken('existing-token');
const currentToken = oauthClient.getAccessToken();

API 参考

• 📖 交互式文档：developer.vybit.net/oauth-reference
• 📋 OpenAPI 规范：docs/openapi/oauth2.yaml

---

CLI

用于命令行访问、Shell 脚本、CI/CD 管道和 AI Agent 工具

Vybit CLI 与 MCP 服务完全对等——AI 助手可执行的每项操作也都能通过命令行执行。所有输出均为写入 stdout 的结构化 JSON，因此同样适用于人类、Shell 脚本和 AI Agent。

安装

npm install -g @vybit/cli

身份验证

# Option 1: Environment variable (recommended for CI/CD and agents)
export VYBIT_API_KEY='your-api-key'

# Option 2: Config file
vybit auth setup --api-key 'your-api-key'

# Option 3: Per-command flag
vybit --api-key 'your-api-key' vybits list

凭据按以下顺序解析：CLI 标志 > 环境变量 > 配置文件（~/.config/vybit/config.json）。

常见操作

# List your vybits
vybit vybits list

# Create a vybit
vybit vybits create --name "Deploy Alert" --trigger-type webhook

# Trigger a notification
vybit trigger <vybit-key> --message "Build passed"

# Trigger in CI/CD (quiet mode returns just the key/ID)
vybit trigger <vybit-key> --message "$(git log -1 --oneline)" -q

# Search sounds
vybit sounds list --search "bell"

# Check usage
vybit meter

可用命令

命令	操作
vybit vybits	list、get、create、update、delete
vybit trigger	触发 vybit 通知
vybit reminders	list、create、update、delete
vybit sounds	list、get
vybit subscriptions	list、get、create、update、delete
vybit browse	list、get（公开 vybits）
vybit logs	list、get、vybit、subscription
vybit peeps	list、get、create、delete、vybit
vybit meter	API 使用指标
vybit status	API 健康检查
vybit profile	用户资料信息
vybit auth	setup、status、logout

面向 Agent 的设计

• JSON 输出到 stdout — 所有数据输出均为可解析的 JSON
• 错误输出到 stderr — 结构化 {"error":"...","statusCode":404} 格式
• 退出码 — 0 表示成功，1 表示错误，2 表示身份验证错误
• --quiet / -q — 仅输出键/ID，便于串联命令
• 绝不提示输入 — 所有输入均通过标志提供，适用于非交互式使用

---

MCP 服务

供 Claude 等 AI 助手与您的 Vybit 通知交互使用

Model Context Protocol (MCP) 服务让 AI 助手能够通过自然对话管理您的 Vybit 通知。它与 Developer API 完全对等，让 AI 助手可以使用所有 Vybit 功能。

安装

npm install -g @vybit/mcp-server

托管远程 MCP 服务（最简单）

Vybit 提供托管的远程 MCP 服务，地址为 https://api.vybit.net/v1/mcp，无需安装。可直接从 Claude 或 ChatGPT 连接（可能需要付费套餐）：

Claude Desktop / Claude Web (claude.ai)：

1. 打开 设置 → 连接器
2. 点击 添加自定义连接器
3. 输入 MCP URL：https://api.vybit.net/v1/mcp
4. 您将被重定向，通过 OAuth 使用您的 Vybit 账户进行授权

ChatGPT Desktop / ChatGPT Web (chatgpt.com)：

1. 打开 设置 → 应用 → 高级设置
2. 将开发者模式切换为 开启，然后点击“创建应用”
3. 填写并提交“新建应用”表单，将 MCP 服务 URL 设为 https://api.vybit.net/v1/mcp
4. 您将被重定向，通过 OAuth 使用您的 Vybit 账户进行授权

本地 MCP 服务

如果您更倾向于在本地运行 MCP 服务（例如，用于 Claude Code、Cline 或其他 MCP 客户端），请安装 npm 包并使用您的 API 密钥进行配置：

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "vybit": {
      "command": "npx",
      "args": ["-y", "@vybit/mcp-server"],
      "env": {
        "VYBIT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code（项目中的 .claude/mcp.json）：

{
  "mcpServers": {
    "vybit": {
      "command": "npx",
      "args": ["-y", "@vybit/mcp-server"],
      "env": {
        "VYBIT_API_KEY": "your-api-key-here"
      }
    }
  }
}

**nvm 用户：**Claude Desktop 不会加载您的 Shell 配置文件，因此 node/npx 可能会解析到错误的版本。使用 which node 和 npm root -g 查找路径，然后直接使用 node，而非 npx。详情请参阅 MCP Server README。

你可以做什么

完成配置后，你可以让 AI 助手：

• 管理 Vybits：创建、更新、删除和列出你的通知 vybits
• 发送通知：使用自定义消息和内容触发通知
• 发现公开 Vybits：浏览并搜索他人创建的公开 vybits
• 管理订阅：订阅公开 vybits 并管理你的订阅
• 浏览声音：搜索可用的通知声音
• 查看日志：查看你的 vybits 和订阅的通知历史记录
• 管理访问权限：邀请他人使用私有 vybits 并控制权限
• 管理提醒：在 vybits 上创建、更新和删除定时提醒
• 监控使用情况：查看你的 API 用量和配额限制

对话示例

You: Create a vybit called "Server Alert" for webhooks with an alarm sound
Claude: [Creates the vybit and shows details including trigger URL]

You: Trigger my Server Alert vybit with message "CPU at 95%"
Claude: [Sends the notification]

You: What public vybits are available about weather?
Claude: [Shows matching public vybits]

You: Subscribe me to the "Daily Weather" vybit
Claude: [Subscribes and confirms]

You: Show me recent notifications for my Server Alert
Claude: [Lists notification logs]

功能

MCP 服务提供 31 个工具，涵盖 Vybit API 的所有功能：

• Vybit 管理（6 个工具）
• 提醒管理（4 个工具）
• 公开 vybit 发现（2 个工具）
• 订阅管理（5 个工具）
• 声音浏览（2 个工具）
• 通知日志（4 个工具）
• 访问控制 / peeps（5 个工具）
• 使用情况监控（1 个工具）

兼容性

适用于任何兼容 MCP 的客户端：

• ✅ Claude Desktop
• ✅ Claude Code
• ✅ Cline（VS Code 扩展）
• ✅ Zed Editor
• ✅ Continue.dev
• ✅ 任何其他兼容 MCP 的 AI 工具

文档

完整文档请参阅 MCP 服务 README。

---

n8n 社区节点

用于工作流自动化和无代码 / 低代码集成

安装

可自托管的 n8n：

npm install @vybit/n8n-nodes-vybit

然后重启你的 n8n 实例。

n8n Cloud： 验证通过后，可在 n8n 节点面板中搜索 “Vybit” 进行安装。目前验证仍在审核中。

开始使用

Vybit n8n 节点支持两种身份验证方式：

选项 1：API 密钥（推荐用于个人自动化）

1. 从 developer.vybit.net 获取你的 API 密钥
2. 在 n8n 中添加一个 Vybit 节点
3. 选择 “API Key” 身份验证
4. 创建新的凭据并粘贴你的 API 密钥

选项 2：OAuth2（适用于多用户服务）

1. 在 developer.vybit.net 配置 OAuth2
2. 在 n8n 中选择 “Vybit OAuth2 API” 身份验证
3. 连接并授权你的 Vybit 账户

可用操作

n8n 节点通过 7 种资源提供 34 项操作：

Profile（3 项操作）

• 获取个人资料、获取使用情况指标、检查 API 状态

Vybits（6 项操作）

• 列出、获取、创建、更新、删除、触发

Logs（4 项操作）

• 列出全部、获取、按 Vybit 列出、按订阅列出

Sounds（3 项操作）

• 搜索、获取、播放

Peeps（5 项操作）

• 列出全部、按 Vybit 列出、邀请、获取、删除

Subscriptions（9 项操作）

• 列出公开项、获取公开项、订阅、列出我的订阅、获取订阅、更新订阅、取消订阅、发送给所有者、发送给群组

Reminders（4 项操作）

• 列出、创建、更新、删除

工作流示例

服务器错误时发出警报：

HTTP Request (check API)
  → IF (status != 200)
  → Vybit (Trigger notification)
  → Email (alert team)

每日报告：

Schedule (daily 9am)
  → Database Query (get metrics)
  → Vybit (Trigger with summary)
  → Slack (post to channel)

自动创建 Vybit：

Airtable Trigger (new record)
  → Vybit (Create vybit)
  → Airtable (update record with trigger URL)

文档

• 📖 节点文档：packages/n8n-nodes/README.md
• 🚀 部署指南：packages/n8n-nodes/DEPLOYMENT.md
• 📋 集成指南：docs/n8n-integration-guide.md
• 💡 工作流示例：examples/n8n/

---

环境管理

两个 SDK 均连接到 Vybit 生产环境端点：

• OAuth 授权：https://app.vybit.net
• API 端点：https://api.vybit.net/v1

管理多个环境

对于开发、预发布和生产环境，请分别创建 Vybit 开发者账户：

开发者 API 方式：

• 每个环境使用自己的 API 密钥
• 在应用中为不同环境配置不同的密钥

const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.VYBIT_PROD_API_KEY
  : process.env.VYBIT_DEV_API_KEY;

const client = new VybitAPIClient({ apiKey });

OAuth2 方式：

• 每个环境使用自己的 OAuth 客户端凭据
• 为不同环境配置不同的重定向 URI

const config = process.env.NODE_ENV === 'production'
  ? {
      clientId: process.env.VYBIT_PROD_CLIENT_ID,
      clientSecret: process.env.VYBIT_PROD_CLIENT_SECRET,
      redirectUri: 'https://yourapp.com/oauth/callback'
    }
  : {
      clientId: process.env.VYBIT_DEV_CLIENT_ID,
      clientSecret: process.env.VYBIT_DEV_CLIENT_SECRET,
      redirectUri: 'http://localhost:3000/oauth/callback'
    };

const client = new VybitOAuth2Client(config);

---

错误处理

两个 SDK 都使用来自 @vybit/core 的一致错误类：

import {
  VybitAPIError,      // API request failures
  VybitAuthError,     // Authentication/authorization failures
  VybitValidationError // Invalid parameters
} from '@vybit/core';

try {
  await client.triggerVybit('invalid-key');
} catch (error) {
  if (error instanceof VybitAPIError) {
    console.error(`API Error: ${error.message} (${error.statusCode})`);
  } else if (error instanceof VybitAuthError) {
    console.error(`Auth Error: ${error.message}`);
  } else if (error instanceof VybitValidationError) {
    console.error(`Validation Error: ${error.message}`);
  }
}

---

示例

examples/ 目录包含完整的可运行示例：

开发者 API 示例

• developer-api-notifications.js - 创建并触发 vybit
• simple-notifications.js - 使用各种选项发送通知

OAuth2 示例

• oauth2-simple.js - 基本 OAuth 2.0 流程
• oauth2-complete-flow.js - 包含错误处理的完整 OAuth 实现
• oauth2-express-server.js - 集成会话管理的完整 Express.js 集成

n8n 工作流示例

• n8n/server-monitoring.json - 监控服务器运行状况并在发生错误时告警
• n8n/daily-summary.json - 发送每日摘要通知
• n8n/airtable-integration.json - 根据 Airtable 记录创建 vybit
• n8n/webhook-to-notification.json - 将 Webhook 事件转换为通知

---

TypeScript 支持

所有软件包均使用 TypeScript 编写，并包含完整的类型定义：

import {
  VybitAPIClient,
  Vybit,
  PublicVybit,
  VybitCreateParams,
  VybitFollow,
  Reminder
} from '@vybit/api-sdk';
import { VybitOAuth2Client, TokenResponse } from '@vybit/oauth2-sdk';

// Full IntelliSense and type checking
const client: VybitAPIClient = new VybitAPIClient({ apiKey: 'key' });

// Owned vybits return full Vybit type with triggerKey, etc.
const vybit: Vybit = await client.getVybit('id');

// Public discovery returns simplified PublicVybit type
const publicVybits: PublicVybit[] = await client.listPublicVybits();

---

贡献

有兴趣参与贡献？请查看我们的贡献指南，了解：

• 开发环境设置和测试
• 代码风格指南
• 拉取请求流程
• 如何报告问题

---

支持

• 文档：developer.vybit.net
• 问题：GitHub Issues
• 电子邮件：[email protected]

---

许可证

MIT