Vybit

Vybit SDK

Official TypeScript/JavaScript SDKs for integrating with the Vybit notification platform.

Vybit is a push notification service with personalized sounds that can be recorded or chosen from a library of thousands of searchable sounds (via freesound.org).

Overview

Vybit provides multiple integration options for different use cases:

All packages share common utilities from [@vybit/core](./packages/core).

---

Developer API SDK

For backend services, automation, and server-to-server integrations

Installation

npm install @vybit/api-sdk

Getting Started

1. Get Your API Key

• Sign up at developer.vybit.net
• Navigate to the Developer API section
• Copy your API key

1. Initialize the Client

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

Common Operations

Create and Manage Vybits

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

Trigger Notifications

// 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' });

Manage Sounds

// List available sounds

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

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

Discover and Subscribe to Public Vybits

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

Monitor Usage

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

• 📖 Interactive Documentation: developer.vybit.net/api-reference
• 📋 OpenAPI Spec: docs/openapi/developer-api.yaml

---

OAuth2 SDK

For user-facing applications that need to access Vybit on behalf of users

The OAuth2 SDK handles the authorization flow only. Once you have an access token, use VybitAPIClient from @vybit/api-sdk for all API operations.

Installation

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

Getting Started

1. Register Your Application

• Sign up at developer.vybit.net
• Navigate to the OAuth Configuration section
• Enter your OAuth Client ID and Redirect URI
• Copy your Client ID and Client Secret

1. Initialize the OAuth2 Client

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 Flow

Step 1: Redirect User to Authorization

const authUrl = oauthClient.getAuthorizationUrl({

state: 'random-state-string' });

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

Step 2: Exchange Authorization Code for Token

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

Step 3: Use the Token with the 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!' });

Token Management

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

• 📖 Interactive Documentation: developer.vybit.net/oauth-reference
• 📋 OpenAPI Spec: docs/openapi/oauth2.yaml

---

CLI

For command-line access, shell scripting, CI/CD pipelines, and AI agent tooling

The Vybit CLI provides full parity with the MCP server — every operation available to AI assistants is also available from the command line. All output is structured JSON to stdout, making it equally useful for humans, shell scripts, and AI agents.

Installation

npm install -g @vybit/cli

Authentication

# 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

Credentials are resolved in order: CLI flags > environment variables > config file (~/.config/vybit/config.json).

Common Operations

# List your vybits

vybit vybits list

Create a vybit

vybit vybits create --name "Deploy Alert" --trigger-type webhook

Trigger a notification

vybit trigger --message "Build passed"

Trigger in CI/CD (quiet mode returns just the key/ID)

vybit trigger --message "$(git log -1 --oneline)" -q

Search sounds

vybit sounds list --search "bell"

Check usage

vybit meter

Available Commands

Agent-Friendly Design

• JSON to stdout — all data output is parseable JSON
• Errors to stderr — structured {"error":"...","statusCode":404} format
• Exit codes — 0 success, 1 error, 2 auth error
• `--quiet` / `-q` — output only keys/IDs for chaining commands
• Never prompts — all input via flags, safe for non-interactive use

---

MCP Server

For AI assistants like Claude to interact with your Vybit notifications

The Model Context Protocol (MCP) server enables AI assistants to manage your Vybit notifications through natural conversation. It provides full parity with the Developer API, giving AI assistants access to all Vybit features.

Installation

npm install -g @vybit/mcp-server

Hosted Remote MCP Server (Easiest)

Vybit provides a hosted remote MCP server at https://api.vybit.net/v1/mcp — no installation required. Connect directly from Claude or ChatGPT (may require paid plans):

Claude Desktop / Claude Web (claude.ai):

1. Open Settings → Connectors
2. Click Add Custom Connector
3. Enter the MCP URL: https://api.vybit.net/v1/mcp
4. You'll be redirected to authorize with your Vybit account via OAuth

ChatGPT Desktop / ChatGPT Web (chatgpt.com):

1. Open Settings → Apps → Advanced Settings
2. Toggle ON Developer Mode, Click "Create app"
3. Fill out and submit the New App form setting the MCP Server URL as https://api.vybit.net/v1/mcp
4. You'll be redirected to authorize with your Vybit account via OAuth

Local MCP Server

If you prefer to run the MCP server locally (e.g., for Claude Code, Cline, or other MCP clients), install the npm package and configure with your API key:

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 in your project):

{

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

nvm users: Claude Desktop doesn't source your shell profile, so node/npx may resolve to the wrong version. Use which node and npm root -g to find your paths, then use node directly instead of npx. See the [MCP Server README](./packages/mcp-server/README.md#troubleshooting-nvm-use