Vybit Push Notifications

Vybit SDK

Vybit 通知プラットフォームと連携するための公式 TypeScript/JavaScript SDK です。

Vybit は、録音した音や、検索可能な数千種類のライブラリから選んだ音（freesound.org 経由）をパーソナライズして使えるプッシュ通知サービスです。

概要

Vybit は、さまざまな用途に対応する複数の連携方法を提供しています。

パッケージ	用途	認証	最適な用途
@vybit/api-sdk	バックエンド／自動化	API キーまたは OAuth2 トークン	サーバー間連携、自動化、監視システム
@vybit/oauth2-sdk	ユーザー向けアプリケーション	OAuth 2.0（ユーザー認証）	ユーザーが Vybit アカウントを接続する Web アプリ（認証フローのみ）
@vybit/cli	コマンドライン	API キー	シェルスクリプト、CI/CD、エージェントツール、簡単な操作
@vybit/mcp-server	AI アシスタント	API キーまたは OAuth2 トークン	Claude Desktop、Claude Code、その他の MCP 対応 AI ツール
@vybit/n8n-nodes-vybit	ワークフロー自動化	API キーまたは OAuth2	n8n ワークフロー、ノーコード／ローコード自動化、連携プラットフォーム

すべてのパッケージで @vybit/core の共通ユーティリティを使用します。

---

Developer API SDK

バックエンドサービス、自動化、サーバー間連携向け

インストール

npm install @vybit/api-sdk

はじめに

1. API キーを取得する

   • developer.vybit.net で登録します
   • Developer API セクションに移動します
   • API キーをコピーします

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 は認証フローのみを処理します。アクセストークンを取得したら、すべての API 操作に @vybit/api-sdk の VybitAPIClient を使用してください。

インストール

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

コマンドラインからのアクセス、シェルスクリプト、CI/CD パイプライン、AI エージェントのツール向け

Vybit CLI は MCP サーバーと完全な同等性を備えています。AI アシスタントから利用できるすべての操作を、コマンドラインからも実行できます。出力はすべて stdout に構造化 JSON で出力されるため、人間、シェルスクリプト、AI エージェントのいずれにも便利です。

インストール

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（公開されている vybit）
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

エージェント向けの設計

• stdout に JSON を出力 — すべてのデータ出力は解析可能な 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 は https://api.vybit.net/v1/mcp でホスト型リモート MCP サーバーを提供しています。インストールは不要です。Claude または ChatGPT から直接接続できます（有料プランが必要な場合があります）。

Claude Desktop / Claude Web (claude.ai)：

1. Settings → Connectors を開きます
2. Add Custom Connector をクリックします
3. MCP URL に https://api.vybit.net/v1/mcp を入力します
4. Vybit アカウントで OAuth 認証するためのページにリダイレクトされます

ChatGPT Desktop / ChatGPT Web (chatgpt.com)：

1. Settings → Apps → Advanced Settings を開きます
2. ON に切り替えて Developer Mode を有効にし、「Create app」をクリックします
3. 新しい App のフォームに入力して送信し、MCP Server URL に https://api.vybit.net/v1/mcp を設定します
4. Vybit アカウントで OAuth 認証するためのページにリダイレクトされます

ローカル 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 はシェルのプロファイルを読み込まないため、node／npx が正しくないバージョンを参照することがあります。which node と npm root -g を使ってパスを確認し、npx の代わりに node を直接使用してください。詳しくは MCP サーバーの README をご覧ください。

できること

設定が完了すると、AI アシスタントに次のことを依頼できます。

• Vybit の管理：通知用 Vybit の作成、更新、削除、一覧表示
• 通知の送信：カスタムメッセージとコンテンツを指定して通知をトリガー
• 公開 Vybit の検索：他のユーザーが作成した公開 Vybit の閲覧と検索
• サブスクリプションの管理：公開 Vybit の購読とサブスクリプションの管理
• サウンドの閲覧：利用可能な通知サウンドの検索
• ログの表示：Vybit とサブスクリプションの通知履歴の確認
• アクセス権の管理：プライベート Vybit へのユーザーの招待と権限の管理
• リマインダーの管理：Vybit に設定したスケジュール済みリマインダーの作成、更新、削除
• 使用状況の監視：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 サーバーは、Vybit API の全機能にわたる 31 個のツールを提供します。

• 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 Server 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