vybit-sdk

# Vybit SDK

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

[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)).

[![npm version](https://badge.fury.io/js/%40vybit%2Fapi-sdk.svg)](https://www.npmjs.com/package/@vybit/api-sdk)
[![npm version](https://badge.fury.io/js/%40vybit%2Foauth2-sdk.svg)](https://www.npmjs.com/package/@vybit/oauth2-sdk)
[![npm version](https://badge.fury.io/js/%40vybit%2Fcli.svg)](https://www.npmjs.com/package/@vybit/cli)
[![npm version](https://badge.fury.io/js/%40vybit%2Fmcp-server.svg)](https://www.npmjs.com/package/@vybit/mcp-server)
[![npm version](https://badge.fury.io/js/%40vybit%2Fn8n-nodes-vybit.svg)](https://www.npmjs.com/package/@vybit/n8n-nodes-vybit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

Vybit provides multiple integration options for different use cases:

| Package | Use Case | Authentication | Best For |
|---------|----------|----------------|----------|
| **[@vybit/api-sdk](./packages/api)** | Backend/automation | API Key or OAuth2 Token | Server-to-server integrations, automation, monitoring systems |
| **[@vybit/oauth2-sdk](./packages/oauth2)** | User-facing applications | OAuth 2.0 (user authorization) | Web apps where users connect their Vybit accounts (auth flow only) |
| **[@vybit/cli](./packages/cli)** | Command line | API Key | Shell scripting, CI/CD, agent tooling, quick operations |
| **[@vybit/mcp-server](./packages/mcp-server)** | AI assistants | API Key or OAuth2 Token | Claude Desktop, Claude Code, and other MCP-compatible AI tools |
| **[@vybit/n8n-nodes-vybit](./packages/n8n-nodes)** | Workflow automation | API Key or OAuth2 | n8n workflows, no-code/low-code automation, integration platforms |

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

---

## Developer API SDK

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

### Installation

```bash
npm install @vybit/api-sdk
```

### Getting Started

1. **Get Your API Key**
   - Sign up at [developer.vybit.net](https://developer.vybit.net)
   - Navigate to the Developer API section
   - Copy your API key

2. **Initialize the Client**

```typescript
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

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

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

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

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

```typescript
// 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](https://developer.vybit.net/api-reference)
- **📋 OpenAPI Spec**: [docs/openapi/developer-api.yaml](./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

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

### Getting Started

1. **Register Your Application**
   - Sign up at [developer.vybit.net](https://developer.vybit.net)
   - Navigate to the OAuth Configuration section
   - Enter your OAuth Client ID and Redirect URI
   - Copy your Client ID and Client Secret

2. **Initialize the OAuth2 Client**

```typescript
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

```typescript
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

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

```typescript
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

```typescript
// 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](https://developer.vybit.net/oauth-reference)
- **📋 OpenAPI Spec**: [docs/openapi/oauth2.yaml](./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

```bash
npm install -g @vybit/cli
```

### Authentication

```bash
# 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

```bash
# 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
```

### Available Commands

| Command | Operations |
|---------|-----------|
| `vybit vybits` | `list`, `get`, `create`, `update`, `delete` |
| `vybit trigger` | Trigger a vybit notification |
| `vybit reminders` | `list`, `create`, `update`, `delete` |
| `vybit sounds` | `list`, `get` |
| `vybit subscriptions` | `list`, `get`, `create`, `update`, `delete` |
| `vybit browse` | `list`, `get` (public vybits) |
| `vybit logs` | `list`, `get`, `vybit`, `subscription` |
| `vybit peeps` | `list`, `get`, `create`, `delete`, `vybit` |
| `vybit meter` | API usage metrics |
| `vybit status` | API health check |
| `vybit profile` | User profile info |
| `vybit auth` | `setup`, `status`, `logout` |

### 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)](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