{
  "markdown": "# Vybit SDK\n\nOfficial TypeScript/JavaScript SDKs for integrating with the Vybit notification platform.\n\n[Vybit](https://www.vybit.net) 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](https://freesound.org)).\n\n[![npm version](https://badge.fury.io/js/%40vybit%2Fapi-sdk.svg)](https://www.npmjs.com/package/@vybit/api-sdk)\n[![npm version](https://badge.fury.io/js/%40vybit%2Foauth2-sdk.svg)](https://www.npmjs.com/package/@vybit/oauth2-sdk)\n[![npm version](https://badge.fury.io/js/%40vybit%2Fcli.svg)](https://www.npmjs.com/package/@vybit/cli)\n[![npm version](https://badge.fury.io/js/%40vybit%2Fmcp-server.svg)](https://www.npmjs.com/package/@vybit/mcp-server)\n[![npm version](https://badge.fury.io/js/%40vybit%2Fn8n-nodes-vybit.svg)](https://www.npmjs.com/package/@vybit/n8n-nodes-vybit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Overview\n\nVybit provides multiple integration options for different use cases:\n\n| Package | Use Case | Authentication | Best For |\n|---------|----------|----------------|----------|\n| **[@vybit/api-sdk](./packages/api)** | Backend/automation | API Key or OAuth2 Token | Server-to-server integrations, automation, monitoring systems |\n| **[@vybit/oauth2-sdk](./packages/oauth2)** | User-facing applications | OAuth 2.0 (user authorization) | Web apps where users connect their Vybit accounts (auth flow only) |\n| **[@vybit/cli](./packages/cli)** | Command line | API Key | Shell scripting, CI/CD, agent tooling, quick operations |\n| **[@vybit/mcp-server](./packages/mcp-server)** | AI assistants | API Key or OAuth2 Token | Claude Desktop, Claude Code, and other MCP-compatible AI tools |\n| **[@vybit/n8n-nodes-vybit](./packages/n8n-nodes)** | Workflow automation | API Key or OAuth2 | n8n workflows, no-code/low-code automation, integration platforms |\n\nAll packages share common utilities from **[@vybit/core](./packages/core)**.\n\n---\n\n## Developer API SDK\n\n**For backend services, automation, and server-to-server integrations**\n\n### Installation\n\n```bash\nnpm install @vybit/api-sdk\n```\n\n### Getting Started\n\n1. **Get Your API Key**\n   - Sign up at [developer.vybit.net](https://developer.vybit.net)\n   - Navigate to the Developer API section\n   - Copy your API key\n\n2. **Initialize the Client**\n\n```typescript\nimport { VybitAPIClient } from '@vybit/api-sdk';\n\n// With API key\nconst client = new VybitAPIClient({\n  apiKey: 'your-api-key-from-developer-portal'\n});\n\n// Or with an OAuth2 access token\nconst client = new VybitAPIClient({\n  accessToken: 'your-oauth2-access-token'\n});\n```\n\n### Common Operations\n\n#### Create and Manage Vybits\n\n```typescript\n// Create a vybit (only name is required)\nconst vybit = await client.createVybit({\n  name: 'Server Alert'\n});\n\n// List vybits with search and pagination\nconst vybits = await client.listVybits({\n  search: 'alert',\n  limit: 10,\n  offset: 0\n});\n\n// Get a specific vybit\nconst details = await client.getVybit('vybit-id');\n\n// Update a vybit\nawait client.updateVybit('vybit-id', {\n  name: 'Updated Server Alert',\n  status: 'on'\n});\n\n// Delete a vybit\nawait client.deleteVybit('vybit-id');\n```\n\n#### Trigger Notifications\n\n```typescript\n// Simple trigger\nawait client.triggerVybit('vybit-key');\n\n// Trigger with custom content\nawait client.triggerVybit('vybit-key', {\n  message: 'Server CPU usage at 95%',\n  imageUrl: 'https://example.com/graph.png',  // Must be a direct link to a JPG, PNG, or GIF image\n  linkUrl: 'https://dashboard.example.com',\n  log: 'CPU spike detected on web-server-01'\n});\n```\n\n#### Manage Sounds\n\n```typescript\n// List available sounds\nconst sounds = await client.listSounds({\n  search: 'alert',\n  limit: 20\n});\n\n// Get sound details\nconst sound = await client.getSound('sound-key');\n```\n\n#### Discover and Subscribe to Public Vybits\n\n```typescript\n// Browse public vybits (returns PublicVybit[])\nconst publicVybits = await client.listPublicVybits({\n  search: 'weather',\n  limit: 10\n});\n\n// Get details about a public vybit before subscribing\nconst vybitDetails = await client.getPublicVybit('subscription-key-abc123');\n\n// Subscribe to a public vybit using its subscription key\nconst follow = await client.createVybitFollow({\n  subscriptionKey: vybitDetails.key\n});\n\n// List your subscriptions\nconst subscriptions = await client.listVybitFollows();\n\n// Unsubscribe from a vybit\nawait client.deleteVybitFollow(follow.followingKey);\n```\n\n#### Monitor Usage\n\n```typescript\n// Get current usage and limits\nconst meter = await client.getMeter();\nconsole.log(`Daily: ${meter.count_daily} / ${meter.cap_daily}`);\nconsole.log(`Monthly: ${meter.count_monthly} / ${meter.cap_monthly}`);\nconsole.log(`Tier: ${meter.tier_id}`);\n```\n\n### API Reference\n\n- **📖 Interactive Documentation**: [developer.vybit.net/api-reference](https://developer.vybit.net/api-reference)\n- **📋 OpenAPI Spec**: [docs/openapi/developer-api.yaml](./docs/openapi/developer-api.yaml)\n\n---\n\n## OAuth2 SDK\n\n**For user-facing applications that need to access Vybit on behalf of users**\n\nThe OAuth2 SDK handles the authorization flow only. Once you have an access token, use `VybitAPIClient` from `@vybit/api-sdk` for all API operations.\n\n### Installation\n\n```bash\nnpm install @vybit/oauth2-sdk @vybit/api-sdk\n```\n\n### Getting Started\n\n1. **Register Your Application**\n   - Sign up at [developer.vybit.net](https://developer.vybit.net)\n   - Navigate to the OAuth Configuration section\n   - Enter your OAuth Client ID and Redirect URI\n   - Copy your Client ID and Client Secret\n\n2. **Initialize the OAuth2 Client**\n\n```typescript\nimport { VybitOAuth2Client } from '@vybit/oauth2-sdk';\n\nconst oauthClient = new VybitOAuth2Client({\n  clientId: 'your-client-id',\n  clientSecret: 'your-client-secret',\n  redirectUri: 'https://yourapp.com/oauth/callback'\n});\n```\n\n### OAuth Flow\n\n#### Step 1: Redirect User to Authorization\n\n```typescript\nconst authUrl = oauthClient.getAuthorizationUrl({\n  state: 'random-state-string'\n});\n\n// Redirect user to authUrl\n// They will authorize your app and be redirected back to your redirectUri\n```\n\n#### Step 2: Exchange Authorization Code for Token\n\n```typescript\n// After redirect, extract the code from query params\nconst code = urlParams.get('code');\n\n// Exchange code for access token\nconst token = await oauthClient.exchangeCodeForToken(code);\n\n// Store token.access_token securely for future requests\n```\n\n#### Step 3: Use the Token with the API SDK\n\n```typescript\nimport { VybitAPIClient } from '@vybit/api-sdk';\n\n// Create an API client with the OAuth2 access token\nconst apiClient = new VybitAPIClient({\n  accessToken: token.access_token\n});\n\n// Now use the full Developer API on behalf of the user\nconst vybits = await apiClient.listVybits();\nawait apiClient.triggerVybit('vybit-key', {\n  message: 'Hello from your app!'\n});\n```\n\n### Token Management\n\n```typescript\n// Verify a token is still valid\nconst isValid = await oauthClient.verifyToken(token.access_token);\n\n// Store and retrieve tokens\noauthClient.setAccessToken('existing-token');\nconst currentToken = oauthClient.getAccessToken();\n```\n\n### API Reference\n\n- **📖 Interactive Documentation**: [developer.vybit.net/oauth-reference](https://developer.vybit.net/oauth-reference)\n- **📋 OpenAPI Spec**: [docs/openapi/oauth2.yaml](./docs/openapi/oauth2.yaml)\n\n---\n\n## CLI\n\n**For command-line access, shell scripting, CI/CD pipelines, and AI agent tooling**\n\nThe 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.\n\n### Installation\n\n```bash\nnpm install -g @vybit/cli\n```\n\n### Authentication\n\n```bash\n# Option 1: Environment variable (recommended for CI/CD and agents)\nexport VYBIT_API_KEY='your-api-key'\n\n# Option 2: Config file\nvybit auth setup --api-key 'your-api-key'\n\n# Option 3: Per-command flag\nvybit --api-key 'your-api-key' vybits list\n```\n\nCredentials are resolved in order: CLI flags > environment variables > config file (`~/.config/vybit/config.json`).\n\n### Common Operations\n\n```bash\n# List your vybits\nvybit vybits list\n\n# Create a vybit\nvybit vybits create --name \"Deploy Alert\" --trigger-type webhook\n\n# Trigger a notification\nvybit trigger <vybit-key> --message \"Build passed\"\n\n# Trigger in CI/CD (quiet mode returns just the key/ID)\nvybit trigger <vybit-key> --message \"$(git log -1 --oneline)\" -q\n\n# Search sounds\nvybit sounds list --search \"bell\"\n\n# Check usage\nvybit meter\n```\n\n### Available Commands\n\n| Command | Operations |\n|---------|-----------|\n| `vybit vybits` | `list`, `get`, `create`, `update`, `delete` |\n| `vybit trigger` | Trigger a vybit notification |\n| `vybit reminders` | `list`, `create`, `update`, `delete` |\n| `vybit sounds` | `list`, `get` |\n| `vybit subscriptions` | `list`, `get`, `create`, `update`, `delete` |\n| `vybit browse` | `list`, `get` (public vybits) |\n| `vybit logs` | `list`, `get`, `vybit`, `subscription` |\n| `vybit peeps` | `list`, `get`, `create`, `delete`, `vybit` |\n| `vybit meter` | API usage metrics |\n| `vybit status` | API health check |\n| `vybit profile` | User profile info |\n| `vybit auth` | `setup`, `status`, `logout` |\n\n### Agent-Friendly Design\n\n- **JSON to stdout** — all data output is parseable JSON\n- **Errors to stderr** — structured `{\"error\":\"...\",\"statusCode\":404}` format\n- **Exit codes** — 0 success, 1 error, 2 auth error\n- **`--quiet` / `-q`** — output only keys/IDs for chaining commands\n- **Never prompts** — all input via flags, safe for non-interactive use\n\n---\n\n## MCP Server\n\n**For AI assistants like Claude to interact with your Vybit notifications**\n\nThe [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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.\n\n### Installation\n\n```bash\nnpm install -g @vybit/mcp-server\n```\n\n### Hosted Remote MCP Server (Easiest)\n\nVybit 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):\n\n**Claude Desktop / Claude Web (claude.ai)**:\n1. Open **Settings → Connectors**\n2. Click **Add Custom Connector** \n3. Enter the MCP URL: `https://api.vybit.net/v1/mcp`\n4. You'll be redirected to authorize with your Vybit account via OAuth\n\n**ChatGPT Desktop / ChatGPT Web (chatgpt.com)**:\n1. Open **Settings → Apps → Advanced Settings**\n2. Toggle **ON** Developer Mode, Click \"Create app\"\n3. Fill out and submit the New App form setting the MCP Server URL as `https://api.vybit.net/v1/mcp`\n4. You'll be redirected to authorize with your Vybit account via OAuth\n\n### Local MCP Server\n\nIf 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:\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"vybit\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vybit/mcp-server\"],\n      \"env\": {\n        \"VYBIT_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code** (`.claude/mcp.json` in your project):\n```json\n{\n  \"mcpServers\": {\n    \"vybit\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vybit/mcp-server\"],\n      \"env\": {\n        \"VYBIT_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n> **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-users) for details.\n\n### What You Can Do\n\nOnce configured, you can ask your AI assistant to:\n\n- **Manage Vybits**: Create, update, delete, and list your notification vybits\n- **Send Notifications**: Trigger notifications with custom messages and content\n- **Discover Public Vybits**: Browse and search public vybits created by others\n- **Manage Subscriptions**: Subscribe to public vybits and manage your subscriptions\n- **Browse Sounds**: Search available notification sounds\n- **View Logs**: See notification history for your vybits and subscriptions\n- **Manage Access**: Invite people to private vybits and control permissions\n- **Manage Reminders**: Create, update, and delete scheduled reminders on vybits\n- **Monitor Usage**: Check your API usage and quota limits\n\n### Example Conversations\n\n```\nYou: Create a vybit called \"Server Alert\" for webhooks with an alarm sound\nClaude: [Creates the vybit and shows details including trigger URL]\n\nYou: Trigger my Server Alert vybit with message \"CPU at 95%\"\nClaude: [Sends the notification]\n\nYou: What public vybits are available about weather?\nClaude: [Shows matching public vybits]\n\nYou: Subscribe me to the \"Daily Weather\" vybit\nClaude: [Subscribes and confirms]\n\nYou: Show me recent notifications for my Server Alert\nClaude: [Lists notification logs]\n```\n\n### Features\n\nThe MCP server provides **30 tools** across all Vybit API features:\n- Vybit management (6 tools)\n- Reminder management (4 tools)\n- Public vybit discovery (2 tools)\n- Subscription management (5 tools)\n- Sound browsing (2 tools)\n- Notification logs (4 tools)\n- Access control / peeps (5 tools)\n- Usage monitoring (1 tool)\n\n### Compatibility\n\nWorks with any MCP-compatible client:\n- ✅ Claude Desktop\n- ✅ Claude Code\n- ✅ Cline (VS Code extension)\n- ✅ Zed Editor\n- ✅ Continue.dev\n- ✅ Any other MCP-compatible AI tool\n\n### Documentation\n\nSee the [MCP Server README](./packages/mcp-server/README.md) for complete documentation.\n\n---\n\n## n8n Community Nodes\n\n**For workflow automation and no-code/low-code integrations**\n\n### Installation\n\n**Self-Hosted n8n:**\n```bash\nnpm install @vybit/n8n-nodes-vybit\n```\nThen restart your n8n instance.\n\n**n8n Cloud:**\nOnce verified, search for \"Vybit\" in the n8n nodes panel to install. Verification is currently under review.\n\n### Getting Started\n\nThe Vybit n8n node supports both authentication methods:\n\n**Option 1: API Key (Recommended for Personal Automation)**\n1. Get your API key from [developer.vybit.net](https://developer.vybit.net)\n2. In n8n, add a Vybit node\n3. Select \"API Key\" authentication\n4. Create a new credential and paste your API key\n\n**Option 2: OAuth2 (For Multi-User Services)**\n1. Configure OAuth2 at [developer.vybit.net](https://developer.vybit.net)\n2. In n8n, select \"Vybit OAuth2 API\" authentication\n3. Connect and authorize your Vybit account\n\n### Available Operations\n\nThe n8n node provides access to **34 operations** across 7 resources:\n\n**Profile** (3 operations)\n- Get Profile, Get Usage Metrics, Check API Status\n\n**Vybits** (6 operations)\n- List, Get, Create, Update, Delete, Trigger\n\n**Logs** (4 operations)\n- List All, Get, List by Vybit, List by Subscription\n\n**Sounds** (3 operations)\n- Search, Get, Play\n\n**Peeps** (5 operations)\n- List All, List by Vybit, Invite, Get, Delete\n\n**Subscriptions** (9 operations)\n- List Public, Get Public, Subscribe, List My Subscriptions, Get Subscription, Update Subscription, Unsubscribe, Send to Owner, Send to Group\n\n**Reminders** (4 operations)\n- List, Create, Update, Delete\n\n### Example Workflows\n\n**Alert on Server Error:**\n```\nHTTP Request (check API)\n  → IF (status != 200)\n  → Vybit (Trigger notification)\n  → Email (alert team)\n```\n\n**Daily Report:**\n```\nSchedule (daily 9am)\n  → Database Query (get metrics)\n  → Vybit (Trigger with summary)\n  → Slack (post to channel)\n```\n\n**Automated Vybit Creation:**\n```\nAirtable Trigger (new record)\n  → Vybit (Create vybit)\n  → Airtable (update record with trigger URL)\n```\n\n### Documentation\n\n- **📖 Node Documentation**: [packages/n8n-nodes/README.md](./packages/n8n-nodes/README.md)\n- **🚀 Deployment Guide**: [packages/n8n-nodes/DEPLOYMENT.md](./packages/n8n-nodes/DEPLOYMENT.md)\n- **📋 Integration Guide**: [docs/n8n-integration-guide.md](./docs/n8n-integration-guide.md)\n- **💡 Example Workflows**: [examples/n8n/](./examples/n8n/)\n\n---\n\n## Environment Management\n\nBoth SDKs connect to Vybit production endpoints:\n- **OAuth Authorization**: `https://app.vybit.net`\n- **API Endpoints**: `https://api.vybit.net/v1`\n\n### Managing Multiple Environments\n\nFor development, staging, and production environments, create separate Vybit developer accounts:\n\n**Developer API Approach:**\n- Each environment gets its own API key\n- Configure different keys per environment in your app\n\n```typescript\nconst apiKey = process.env.NODE_ENV === 'production'\n  ? process.env.VYBIT_PROD_API_KEY\n  : process.env.VYBIT_DEV_API_KEY;\n\nconst client = new VybitAPIClient({ apiKey });\n```\n\n**OAuth2 Approach:**\n- Each environment gets its own OAuth client credentials\n- Configure different redirect URIs per environment\n\n```typescript\nconst config = process.env.NODE_ENV === 'production'\n  ? {\n      clientId: process.env.VYBIT_PROD_CLIENT_ID,\n      clientSecret: process.env.VYBIT_PROD_CLIENT_SECRET,\n      redirectUri: 'https://yourapp.com/oauth/callback'\n    }\n  : {\n      clientId: process.env.VYBIT_DEV_CLIENT_ID,\n      clientSecret: process.env.VYBIT_DEV_CLIENT_SECRET,\n      redirectUri: 'http://localhost:3000/oauth/callback'\n    };\n\nconst client = new VybitOAuth2Client(config);\n```\n\n---\n\n## Error Handling\n\nBoth SDKs use consistent error classes from `@vybit/core`:\n\n```typescript\nimport {\n  VybitAPIError,      // API request failures\n  VybitAuthError,     // Authentication/authorization failures\n  VybitValidationError // Invalid parameters\n} from '@vybit/core';\n\ntry {\n  await client.triggerVybit('invalid-key');\n} catch (error) {\n  if (error instanceof VybitAPIError) {\n    console.error(`API Error: ${error.message} (${error.statusCode})`);\n  } else if (error instanceof VybitAuthError) {\n    console.error(`Auth Error: ${error.message}`);\n  } else if (error instanceof VybitValidationError) {\n    console.error(`Validation Error: ${error.message}`);\n  }\n}\n```\n\n---\n\n## Examples\n\nThe `examples/` directory contains complete working examples:\n\n### Developer API Examples\n- **developer-api-notifications.js** - Creating and triggering vybits\n- **simple-notifications.js** - Sending notifications with various options\n\n### OAuth2 Examples\n- **oauth2-simple.js** - Basic OAuth 2.0 flow\n- **oauth2-complete-flow.js** - Complete OAuth implementation with error handling\n- **oauth2-express-server.js** - Full Express.js integration with session management\n\n### n8n Workflow Examples\n- **n8n/server-monitoring.json** - Monitor server health and alert on errors\n- **n8n/daily-summary.json** - Send daily summary notifications\n- **n8n/airtable-integration.json** - Create vybits from Airtable records\n- **n8n/webhook-to-notification.json** - Convert webhook events to notifications\n\n---\n\n## TypeScript Support\n\nAll packages are written in TypeScript and include full type definitions:\n\n```typescript\nimport {\n  VybitAPIClient,\n  Vybit,\n  PublicVybit,\n  VybitCreateParams,\n  VybitFollow,\n  Reminder\n} from '@vybit/api-sdk';\nimport { VybitOAuth2Client, TokenResponse } from '@vybit/oauth2-sdk';\n\n// Full IntelliSense and type checking\nconst client: VybitAPIClient = new VybitAPIClient({ apiKey: 'key' });\n\n// Owned vybits return full Vybit type with triggerKey, etc.\nconst vybit: Vybit = await client.getVybit('id');\n\n// Public discovery returns simplified PublicVybit type\nconst publicVybits: PublicVybit[] = await client.listPublicVybits();\n```\n\n---\n\n## Contributing\n\nInterested in contributing? Check out our [Contributing Guide](./CONTRIBUTING.md) for:\n- Development setup and testing\n- Code style guidelines\n- Pull request process\n- How to report issues\n\n---\n\n## Support\n\n- **Documentation**: [developer.vybit.net](https://developer.vybit.net)\n- **Issues**: [GitHub Issues](https://github.com/flatirontek/vybit-sdk/issues)\n- **Email**: developer@vybit.net\n\n---\n\n## License\n\nMIT\n",
  "bytes": 20030,
  "sha": "244a7c0a8cf39852b118a3943eebf590536526e0d6bbeb4817f06475243009d8",
  "repo_slug": "flatirontek/vybit-sdk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_net_vybit_mcp_server_c944b189/readme"
}