### Get Stream Setup Response

Source: https://developer.velora.tv/developer/docs/guides/streaming-software

Example response containing the stream key, RTMP, SRT, and WHIP URLs, and the ingest server hostname.

```json
{
  "streamKey": "live_abc123xyz789",
  "rtmpUrl": "rtmp://ingest.velora.tv:1935/live",
  "srtUrl": "srt://ingest.velora.tv:9999",
  "whipUrl": "https://ingest.velora.tv:3334/live/live_abc123xyz789/whip",
  "ingestServer": "ingest.velora.tv"
}
```

--------------------------------

### Get Stream Setup (curl)

Source: https://developer.velora.tv/developer/docs/guides/streaming-software

Retrieve the user's stream key and available ingest server URLs. Requires the `stream:key` scope.

```curl
curl https://api.velora.tv/api/integrations/oauth/stream/setup \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

--------------------------------

### Get Stream Info Response

Source: https://developer.velora.tv/developer/docs/guides/streaming-software

Example response showing the stream's title, category, live status, viewer count, and start time.

```json
{
  "title": "Building an awesome project!",
  "categoryName": "Software & Game Development",
  "categorySlug": "software-and-game-development",
  "isLive": true,
  "viewerCount": 142,
  "startedAt": "2026-01-19T02:30:00.000Z"
}
```

--------------------------------

### Live Streams Response Example

Source: https://developer.velora.tv/developer/docs/getting-started

This is an example of the response structure when fetching live streams. It includes stream details and pagination information.

```json
{
  "streams": [
    {
      "id": "abc123",
      "userId": "user_123",
      "username": "coolstreamer",
      "title": "Playing Velora Games!",
      "viewerCount": 1234,
      "startedAt": "2026-01-18T10:30:00Z",
      "thumbnailUrl": "https://cdn.velora.tv/..."
    }
  ],
  "pagination": {
    "cursor": "eyJsYXN0X2lkIjoi..."
  }
}
```

--------------------------------

### Get Stream Setup

Source: https://developer.velora.tv/developer/docs/guides/streaming-software

Retrieves the user's stream key and all available ingest server URLs (RTMP, SRT, WHIP). Requires the `stream:key` scope.

```APIDOC
## Get Stream Setup
GET /stream/setup

### Description
Retrieve the user's stream key and all available ingest server URLs. This endpoint requires the `stream:key` scope.

### Method
GET

### Endpoint
/stream/setup

### Request Example
```bash
curl https://api.velora.tv/api/integrations/oauth/stream/setup \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response
#### Success Response (200)
- **streamKey** (string) - The user's unique stream key.
- **rtmpUrl** (string) - The RTMP ingest server URL.
- **srtUrl** (string) - The SRT ingest server URL.
- **whipUrl** (string) - The WHIP ingest server URL.
- **ingestServer** (string) - The primary ingest server hostname.

### Response Example
```json
{
  "streamKey": "live_abc123xyz789",
  "rtmpUrl": "rtmp://ingest.velora.tv:1935/live",
  "srtUrl": "srt://ingest.velora.tv:9999",
  "whipUrl": "https://ingest.velora.tv:3334/live/live_abc123xyz789/whip",
  "ingestServer": "ingest.velora.tv"
}
```
```

--------------------------------

### Token Response Example

Source: https://developer.velora.tv/developer/docs/getting-started

This is an example of a successful response when requesting an access token. The access token is used for authenticating subsequent API requests.

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

--------------------------------

### Token Response Example

Source: https://developer.velora.tv/developer/docs/authentication

Example of a successful response when exchanging an authorization code for an access token. This includes the access token, refresh token, and their validity.

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "user:read stream:read"
}
```

--------------------------------

### List Categories Response

Source: https://developer.velora.tv/developer/docs/guides/streaming-software

Example response containing a list of categories, each with a slug, name, and image URL.

```json
{
  "categories": [
    {
      "slug": "just-chatting",
      "name": "Just Chatting",
      "imageUrl": "https://assets.velora.tv/categories/just-chatting.jpg"
    },
    {
      "slug": "software-and-game-development",
      "name": "Software & Game Development",
      "imageUrl": "https://assets.velora.tv/categories/dev.jpg"
    },
    {
      "slug": "music",
      "name": "Music",
      "imageUrl": null
    }
  ]
}
```

--------------------------------

### Example API Response Headers

Source: https://developer.velora.tv/developer/docs/rate-limits

These headers indicate the maximum requests allowed, the remaining requests in the current window, and the timestamp when the limit resets.

```http
HTTP/1.1 200 OK
X-RateLimit-Limit: 800
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1737213600
```

--------------------------------

### Pagination Example

Source: https://developer.velora.tv/developer/docs/api-reference

List endpoints support cursor-based pagination. Use the 'limit' parameter to specify the number of items per page and the 'cursor' parameter to retrieve subsequent pages of results.

```http
GET /api/streams?limit=25&cursor=eyJsYXN0X2lkIjoi...
```

--------------------------------

### Webhook Payload Example

Source: https://developer.velora.tv/developer/docs/webhooks

This is an example of the JSON payload structure received by your webhook endpoint when an event occurs. It includes event details like ID, type, timestamp, and specific data related to the event.

```json
{
  "id": "evt_abc123",
  "type": "stream.online",
  "timestamp": "2026-01-18T15:30:00Z",
  "data": {
    "streamId": "stream_xyz",
    "userId": "user_123",
    "username": "coolstreamer",
    "title": "Playing Velora Games!",
    "startedAt": "2026-01-18T15:30:00Z"
  }
}
```

--------------------------------

### Connect to Events API via Server-Sent Events (curl)

Source: https://developer.velora.tv/developer/docs/events-api

Demonstrates how to connect to the Events API using Server-Sent Events (SSE) via curl. This command-line example shows the necessary headers for authentication and content type.

```bash
curl -N -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Accept: text/event-stream" \
     "https://api.velora.tv/api/events/stream"
```

--------------------------------

### Example WebSocket Response for Channel Rewards

Source: https://developer.velora.tv/developer/docs/events-api

This JSON structure represents the data received via WebSocket on the 'channel:rewards' event, detailing configured channel point rewards.

```json
[
  {
    "id": "reward_abc123",
    "name": "Highlight My Message",
    "cost": 500,
    "description": "Make your message stand out!",
    "iconUrl": "https://...",
    "enabled": true,
    "isBuiltIn": false,
    "builtInType": null
  },
  {
    "id": "reward_xyz789",
    "name": "First",
    "cost": 1,
    "description": "Be the first to claim this each stream!",
    "iconUrl": null,
    "enabled": true,
    "isBuiltIn": true,
    "builtInType": "first"
  }
]
```

--------------------------------

### Get Webhook Details

Source: https://developer.velora.tv/developer/docs/api-reference

Retrieves detailed information about a specific webhook subscription.

```APIDOC
## Get Webhook Details

### Description
Get webhook details.

### Method
GET

### Endpoint
`/api/developer/apps/:clientId/webhooks/:id`
```

--------------------------------

### Joining a Channel

Source: https://developer.velora.tv/developer/docs/chat-websocket

Emit the `joinChannel` event to start receiving messages and events for a specific channel. The `channelId` can be the broadcaster's user ID or username.

```APIDOC
## Joining a Channel

### Description
To begin receiving messages and events for a specific channel, emit the `joinChannel` event. You can join multiple channels concurrently.

### Event
`joinChannel`

### Parameters
- **channelId** (string) - Required - The broadcaster's user ID (UUID) or username.

### Example
```javascript
socket.emit('joinChannel', { channelId: 'streamer_user_id_or_username' });
```

To leave a channel, emit `leaveChannel` with the same `channelId`.
```

--------------------------------

### Join a Channel

Source: https://developer.velora.tv/developer/docs/chat-websocket

Emit the 'joinChannel' event to start receiving messages and events for a specific channel. The channelId can be a user ID or username.

```javascript
socket.emit('joinChannel', { channelId: 'streamer_user_id_or_username' });
```

--------------------------------

### Get Stream Info

Source: https://developer.velora.tv/developer/docs/guides/streaming-software

Fetches the current stream information, including title, category, live status, and viewer count. Requires the `stream:read` scope.

```APIDOC
## Get Stream Info
GET /stream/info

### Description
Get the current stream information including title, category, and live status. Requires `stream:read` scope.

### Method
GET

### Endpoint
/stream/info

### Request Example
```bash
curl https://api.velora.tv/api/integrations/oauth/stream/info \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response
#### Success Response (200)
- **title** (string) - The current stream title.
- **categoryName** (string) - The name of the current stream category.
- **categorySlug** (string) - The slug identifier for the current category.
- **isLive** (boolean) - Indicates if the stream is currently live.
- **viewerCount** (integer) - The number of current viewers.
- **startedAt** (string) - The ISO 8601 timestamp when the stream started.

### Response Example
```json
{
  "title": "Building an awesome project!",
  "categoryName": "Software & Game Development",
  "categorySlug": "software-and-game-development",
  "isLive": true,
  "viewerCount": 142,
  "startedAt": "2026-01-19T02:30:00.000Z"
}
```
```

--------------------------------

### Get Live Streams

Source: https://developer.velora.tv/developer/docs/getting-started

Retrieve a list of currently live streams. This is a basic authenticated request to the API.

```APIDOC
## GET /api/streams

### Description
Retrieves a list of live streams.

### Method
GET

### Endpoint
https://api.velora.tv/api/streams

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - Used for pagination to fetch the next set of results.

### Request Example
```bash
curl https://api.velora.tv/api/streams \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response
#### Success Response (200)
- **streams** (array) - An array of live stream objects.
  - **id** (string) - The unique identifier for the stream.
  - **userId** (string) - The ID of the user streaming.
  - **username** (string) - The username of the streamer.
  - **title** (string) - The title of the stream.
  - **viewerCount** (integer) - The current number of viewers.
  - **startedAt** (string) - The timestamp when the stream started (ISO 8601 format).
  - **thumbnailUrl** (string) - The URL for the stream's thumbnail.
- **pagination** (object) - Pagination information.
  - **cursor** (string) - A cursor for fetching the next page of results.
```

--------------------------------

### Get Access Token with Authorization Code Flow

Source: https://developer.velora.tv/developer/docs/getting-started

Use this cURL command to exchange an authorization code for an access token. Ensure you replace placeholders with your actual credentials and redirect URI.

```curl
curl -X POST https://api.velora.tv/api/developer/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE_FROM_CALLBACK",
    "redirect_uri": "YOUR_REDIRECT_URI",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code_verifier": "YOUR_PKCE_CODE_VERIFIER"
  }'
```

--------------------------------

### Get Stream Info (curl)

Source: https://developer.velora.tv/developer/docs/guides/streaming-software

Retrieve current stream information including title, category, and live status. Requires the `stream:read` scope.

```curl
curl https://api.velora.tv/api/integrations/oauth/stream/info \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

--------------------------------

### Example REST API Response for Channel Rewards

Source: https://developer.velora.tv/developer/docs/events-api

This JSON structure represents the response from the REST API endpoint for fetching channel point rewards, including custom and built-in reward types.

```json
{
  "items": [
    {
      "id": "reward_abc123",
      "name": "Highlight My Message",
      "cost": 500,
      "description": "Make your message stand out!",
      "iconUrl": "https://...",
      "builtInType": null,  // null = custom reward
      "enabled": true,
      "requiresModeratorApproval": false,
      "maxPerStream": null,
      "maxPerUserPerStream": 3
    },
    {
      "id": "reward_xyz789",
      "name": "First",
      "cost": 1,
      "description": "Be the first to claim this each stream!",
      "builtInType": "first",  // Built-in reward type
      "enabled": true
    }
  ]
}
```

--------------------------------

### Create a Webhook via API

Source: https://developer.velora.tv/developer/docs/webhooks

Use this cURL command to create a new webhook subscription via the Velora API. Replace placeholders with your client ID and access token. Specify the desired events to subscribe to.

```bash
curl -X POST https://api.velora.tv/api/developer/apps/{clientId}/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/velora",
    "events": ["stream.online", "stream.offline", "channel.follow"]
  }'
```

--------------------------------

### Redirect to Authorization URL

Source: https://developer.velora.tv/developer/docs/authentication

Construct the URL to redirect users for authorization, including client ID, redirect URI, scopes, and PKCE parameters.

```url
https://velora.tv/oauth/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=user:read stream:read
  &state=RANDOM_STATE_VALUE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
```

--------------------------------

### Connecting to the Chat WebSocket

Source: https://developer.velora.tv/developer/docs/chat-websocket

Connect to the Velora Chat WebSocket API. The recommended endpoint is `wss://api.velora.tv/chat`. Ensure you connect to the `/chat` namespace.

```APIDOC
## Connecting to the Chat WebSocket

### Description
Connect to the Velora Chat WebSocket API using Socket.IO. The recommended endpoint is `wss://api.velora.tv/chat`. It's crucial to connect to the `/chat` namespace, as connecting to the root URL will result in disconnection.

### Endpoint
`wss://api.velora.tv/chat`

### Transports
Socket.IO supports both `websocket` and `polling`. `websocket` is recommended for bots.

### Authentication Methods

#### 1. Socket.IO auth payload (Recommended)
```javascript
import { io } from 'socket.io-client';

const socket = io('wss://api.velora.tv/chat', {
  auth: { token: 'YOUR_JWT_OR_OAUTH_TOKEN' },
  transports: ['websocket'],
});
```

#### 2. Authorization header
```javascript
const socket = io('wss://api.velora.tv/chat', {
  extraHeaders: { Authorization: 'Bearer YOUR_TOKEN' },
  transports: ['websocket'],
});
```

#### 3. Query string
```javascript
const socket = io('wss://api.velora.tv/chat?token=YOUR_TOKEN', {
  transports: ['websocket'],
});
```

If no token is provided, you will connect as a guest (read-only).
```

--------------------------------

### Connect to Chat WebSocket with Query String Token

Source: https://developer.velora.tv/developer/docs/chat-websocket

Establish a WebSocket connection by including the authentication token in the query string. This method is simpler for basic token passing.

```javascript
const socket = io('wss://api.velora.tv/chat?token=YOUR_TOKEN', {
  transports: ['websocket'],
});
```

--------------------------------

### Generate PKCE Code Challenge (JavaScript)

Source: https://developer.velora.tv/developer/docs/authentication

Creates a SHA-256 hash of the code verifier, which is then base64 URL encoded. This is used in the authorization request.

```javascript
async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return base64URLEncode(new Uint8Array(hash));
}
```

--------------------------------

### Using Access Tokens

Source: https://developer.velora.tv/developer/docs/authentication

Include your access token in the `Authorization` header to authenticate API requests.

```APIDOC
## Authenticating API Requests

### Description
To make authenticated requests to the Velora API, include your access token in the `Authorization` header.

### Method
Any HTTP Method (GET, POST, PUT, DELETE, etc.)

### Endpoint
Any API endpoint (e.g., `https://api.velora.tv/api/users/me`)

### Headers
- **Authorization**: `Bearer YOUR_ACCESS_TOKEN`

### Request Example
```bash
curl https://api.velora.tv/api/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
```

--------------------------------

### REST API Endpoint for Channel Point Rewards

Source: https://developer.velora.tv/developer/docs/events-api

Fetch channel point rewards using the public REST API endpoint. No authentication is required for this GET request.

```http
GET https://api.velora.tv/api/channel-points/{channelId}/items/with-built-in
```

--------------------------------

### Create a Webhook via API

Source: https://developer.velora.tv/developer/docs/webhooks

You can create webhooks by making a POST request to the API. This allows you to specify the endpoint URL and the events you want to subscribe to.

```APIDOC
## POST /api/developer/apps/{clientId}/webhooks

### Description
Creates a new webhook subscription for a given client ID.

### Method
POST

### Endpoint
/api/developer/apps/{clientId}/webhooks

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The unique identifier for the client application.

#### Request Body
- **url** (string) - Required - The URL where webhook events will be sent.
- **events** (array of strings) - Required - A list of event types to subscribe to (e.g., `["stream.online", "stream.offline", "channel.follow"]`).

### Request Example
```json
{
  "url": "https://yourapp.com/webhooks/velora",
  "events": ["stream.online", "stream.offline", "channel.follow"]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created webhook.
- **url** (string) - The URL of the webhook.
- **events** (array of strings) - The list of events the webhook is subscribed to.
- **secret** (string) - The secret used for signing webhook payloads.
```

--------------------------------

### Get Live Streams Request

Source: https://developer.velora.tv/developer/docs/getting-started

Make an authenticated request to the /api/streams endpoint to retrieve a list of currently live streams. Include your access token in the Authorization header.

```curl
curl https://api.velora.tv/api/streams \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

--------------------------------

### JavaScript Velora Chat Bot Implementation

Source: https://developer.velora.tv/developer/docs/guides/chat

Implement a chat bot class to send messages, welcome users, thank followers, celebrate subscriptions, and reply to messages. Requires an OAuth access token and channel ID for operation.

```javascript
// Velora Chat Bot Example

const VELORA_API = 'https://api.velora.tv/api/integrations/oauth';

class VeloraChatBot {
  constructor(accessToken) {
    this.accessToken = accessToken;
  }

  async sendMessage(channelId, message, options = {}) {
    const response = await fetch(
      `${VELORA_API}/chat/${channelId}/messages`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          message,
          effect: options.effect,
          effectColor: options.effectColor,
          replyTo: options.replyTo,
        }),
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'Failed to send message');
    }

    return response.json();
  }

  // Send a welcome message with glow effect
  async welcomeUser(channelId, username) {
    return this.sendMessage(
      channelId,
      `Welcome to the stream, @${username}! 🎉`,
      { effect: 'glow', effectColor: '#4ecdc4' }
    );
  }

  // Send a follow thank you with rainbow
  async thankFollower(channelId, username) {
    return this.sendMessage(
      channelId,
      `Thank you for the follow, @${username}! ❤️`,
      { effect: 'rainbow' }
    );
  }

  // Send a sub alert with gigantify
  async celebrateSub(channelId, username, months) {
    const emoji = months > 1 ? '🏆' : '🎊';
    return this.sendMessage(
      channelId,
      `${emoji} @${username} just subscribed for ${months} month(s)! ${emoji}`,
      { effect: 'gigantify' }
    );
  }

  // Reply to a message
  async replyTo(channelId, originalMessage, reply) {
    return this.sendMessage(channelId, reply, {
      replyTo: {
        messageId: originalMessage.id,
        username: originalMessage.username,
        snippet: originalMessage.content.substring(0, 100),
      },
    });
  }
}

// Usage Example
const bot = new VeloraChatBot('your_oauth_access_token');
const channelId = 'streamer-user-id';

// Welcome a new viewer
bot.welcomeUser(channelId, 'NewViewer123')
  .then(result => console.log('Message sent:', result.messageId))
  .catch(err => console.error('Error:', err.message));

// React to events from webhooks
async function handleWebhookEvent(event) {
  if (event.event === 'user.follow') {
    await bot.thankFollower(
      event.data.channel.id,
      event.data.follower.username
    );
  }

  if (event.event === 'channel.subscribe') {
    await bot.celebrateSub(
      event.data.channel.id,
      event.data.subscriber.username,
      event.data.months
    );
  }
}

```

--------------------------------

### Connect to Events API via Server-Sent Events (JavaScript)

Source: https://developer.velora.tv/developer/docs/events-api

Establishes a connection using Server-Sent Events (SSE) for receiving real-time events over HTTP. Authentication is provided via the 'Authorization' header. This method is simpler and suitable for environments without robust Socket.IO support.

```javascript
const eventSource = new EventSource(
  'https://api.velora.tv/api/events/stream',
  {
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  }
);

// Connection established
eventSource.addEventListener('connected', (e) => {
  const data = JSON.parse(e.data);
  console.log('Connected:', data.channelUsername);
});

// Listen for specific event types
eventSource.addEventListener('channel.follow', (e) => {
  const payload = JSON.parse(e.data);
  console.log('New follower:', payload.data.username);
});

eventSource.addEventListener('channel.subscribe', (e) => {
  const payload = JSON.parse(e.data);
  console.log('New sub:', payload.data.username);
});

// Or listen for all events
eventSource.onmessage = (e) => {
  const payload = JSON.parse(e.data);
  console.log('Event:', payload.event, payload.data);
};

eventSource.onerror = (e) => {
  console.error('SSE error:', e);
};
```

--------------------------------

### Verifying Webhook Signatures

Source: https://developer.velora.tv/developer/docs/webhooks

Always verify the signature of incoming webhook requests to ensure they originate from Velora and have not been tampered with. This involves using the `X-Velora-Signature`, `X-Velora-Timestamp`, and your webhook secret.

```APIDOC
## Verifying Signatures

Velora signs each webhook request with a signature to allow you to verify its authenticity. You should always verify the signature before processing the payload.

### Headers
- **X-Velora-Signature** (string) - The HMAC-SHA256 signature of the payload, prefixed with `sha256=`.
- **X-Velora-Timestamp** (string) - The Unix timestamp of when the request was generated.
- **X-Velora-Event** (string) - The type of the event.

### Verification Process
1. Retrieve the `X-Velora-Signature`, `X-Velora-Timestamp`, and the raw request payload.
2. Construct the string to sign by concatenating the timestamp and the payload: `${timestamp}.${payload}`.
3. Compute the HMAC-SHA256 hash of this string using your webhook's secret.
4. Compare the computed hash with the signature provided in the `X-Velora-Signature` header using a timing-safe comparison method.

### Verification Example (Node.js)
```javascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, timestamp, signature, secret) {
  const sig = signature.replace('sha256=', '');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

// Example usage within an Express.js route:
app.post('/webhooks/velora', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-velora-signature'];
  const timestamp = req.headers['x-velora-timestamp'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, timestamp, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Optional: Reject old timestamps to prevent replay attacks
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) { // 5 minute tolerance
    return res.status(401).send('Timestamp too old');
  }

  const event = JSON.parse(payload);
  console.log('Received event:', event.type);

  res.status(200).send('OK');
});
```
```

--------------------------------

### Connect to Events API via WebSocket (JavaScript)

Source: https://developer.velora.tv/developer/docs/events-api

Establishes a persistent WebSocket connection using Socket.IO to receive real-time events. Requires the socket.io-client library. Ensure your access token is valid.

```javascript
import { io } from 'socket.io-client';

const socket = io('wss://api.velora.tv/ws/events', {
  auth: {
    token: 'YOUR_ACCESS_TOKEN'
  },
  // Or pass token as query parameter:
  // query: { token: 'YOUR_ACCESS_TOKEN' }
});

// Connection established
socket.on('connected', (data) => {
  console.log('Connected to Events API');
  console.log('Channel:', data.channelUsername);
});

// Listen for all events
socket.on('event', (payload) => {
  console.log('Event received:', payload.event);
  console.log('Data:', payload.data);
  console.log('Timestamp:', payload.timestamp);
});

// Handle errors
socket.on('error', (err) => {
  console.error('Connection error:', err.message);
});

// Handle disconnection
socket.on('disconnect', (reason) => {
  console.log('Disconnected:', reason);
});
```

--------------------------------

### List Webhooks

Source: https://developer.velora.tv/developer/docs/api-reference

Retrieves a list of all configured webhook subscriptions for your application.

```APIDOC
## List Webhooks

### Description
List all webhooks for your app.

### Method
GET

### Endpoint
`/api/developer/apps/:clientId/webhooks`
```

--------------------------------

### Create Webhook Subscription

Source: https://developer.velora.tv/developer/docs/api-reference

Creates a new webhook subscription to receive event notifications. You can specify which events to subscribe to.

```APIDOC
## Create Webhook Subscription

### Description
Create webhook subscription.

### Method
POST

### Endpoint
`/api/developer/apps/:clientId/webhooks`

### Parameters
#### Query Parameters
- **events** (array) - Required - List of events to subscribe to (e.g., channel.follow, channel.subscribe, channel.gift, channel.raid, channel.volts, channel.points.redeem, stream.online, stream.offline, etc.)
```

--------------------------------

### Verify Webhook Signatures (Node.js)

Source: https://developer.velora.tv/developer/docs/webhooks/events

Use this Node.js function to verify incoming webhook signatures using HMAC-SHA256. Ensure the secret key matches the one configured in your Velora dashboard. This prevents spoofing and ensures request integrity.

```javascript
// Node.js signature verification
const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(body);
  const expectedSignature = hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
```

--------------------------------

### Streaming Integration (OAuth)

Source: https://developer.velora.tv/developer/docs/api-reference

Endpoints for integrating with the streaming service using OAuth.

```APIDOC
## GET /api/integrations/oauth/stream/setup

### Description
Get stream key and ingest URLs (requires stream:key)

### Method
GET

### Endpoint
/api/integrations/oauth/stream/setup
```

```APIDOC
## GET /api/integrations/oauth/stream/info

### Description
Get current stream info (requires stream:read)

### Method
GET

### Endpoint
/api/integrations/oauth/stream/info
```

```APIDOC
## PUT /api/integrations/oauth/stream/info

### Description
Update stream title/category (requires stream:write)

### Method
PUT

### Endpoint
/api/integrations/oauth/stream/info
```

```APIDOC
## GET /api/integrations/oauth/stream/categories

### Description
List available stream categories

### Method
GET

### Endpoint
/api/integrations/oauth/stream/categories
```

```APIDOC
## POST /api/integrations/oauth/stream/key/regenerate

### Description
Regenerate stream key (requires stream:key)

### Method
POST

### Endpoint
/api/integrations/oauth/stream/key/regenerate
```

--------------------------------

### Generate PKCE Code Verifier (JavaScript)

Source: https://developer.velora.tv/developer/docs/authentication

Generates a cryptographically random code verifier required for the PKCE flow. Ensure the verifier is between 43 and 128 characters.

```javascript
// JavaScript example
function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64URLEncode(array);
}

function base64URLEncode(buffer) {
  return btoa(String.fromCharCode(...buffer))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}
```

--------------------------------

### Available Event Types

Source: https://developer.velora.tv/developer/docs/webhooks/events

A list of all available webhook event types, categorized by their source.

```APIDOC
## Available Event Types

### Events
`stream.online`
`stream.offline`
`stream.update`

### Channel Events
`user.follow`
`channel.subscribe`
`channel.subscription.gift`
`channel.volts`
`channel.raid`
`channel.ban`
`channel.unban`
`channel.moderator.add`
`channel.moderator.remove`
`channel.channel_points_redemption`
```

--------------------------------

### Connect to Chat WebSocket with JWT/OAuth

Source: https://developer.velora.tv/developer/docs/chat-websocket

Use this method to establish a WebSocket connection with authentication using a JWT or OAuth token. Ensure the 'websocket' transport is specified.

```javascript
import { io } from 'socket.io-client';

const socket = io('wss://api.velora.tv/chat', {
  auth: { token: 'YOUR_JWT_OR_OAUTH_TOKEN' },
  transports: ['websocket'],
});
```

--------------------------------

### Connect to Events API via WebSocket (C# / Streamer.bot)

Source: https://developer.velora.tv/developer/docs/events-api

Connects to the Events API using Socket.IO in C#, suitable for applications like Streamer.bot. Requires the SocketIOClient library. Authentication is done via the 'token' property in the connection options.

```csharp
using SocketIOClient;

var socket = new SocketIO("wss://api.velora.tv/ws/events", new SocketIOOptions
{
    Auth = new { token = "YOUR_ACCESS_TOKEN" }
});

socket.On("connected", response =>
{
    var data = response.GetValue<ConnectedData>();
    Console.WriteLine($"Connected as {data.ChannelUsername}");
});

socket.On("event", response =>
{
    var payload = response.GetValue<EventPayload>();
    Console.WriteLine($"Event: {payload.Event}");
    // Handle the event...
});

await socket.ConnectAsync();
```

--------------------------------

### Regenerate Stream Key (curl)

Source: https://developer.velora.tv/developer/docs/guides/streaming-software

Generate a new stream key for the user. The old key will immediately stop working. Requires `stream:key` scope. This action is irreversible.

```curl
curl https://api.velora.tv/api/integrations/oauth/stream/key/regenerate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

--------------------------------

### Refresh Access Token (cURL)

Source: https://developer.velora.tv/developer/docs/authentication

Use this cURL command to obtain a new access token using a valid refresh token. This is necessary as access tokens expire after 1 hour.

```curl
curl -X POST https://api.velora.tv/api/developer/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'
```

--------------------------------

### OAuth & Authentication

Source: https://developer.velora.tv/developer/docs/api-reference

Endpoints for managing OAuth authorization and obtaining access tokens.

```APIDOC
## GET /api/developer/oauth/authorize

### Description
Preview authorization (get app info for consent page)

### Method
GET

### Endpoint
/api/developer/oauth/authorize
```

```APIDOC
## POST /api/developer/oauth/authorize

### Description
Complete authorization (exchange consent for code)

### Method
POST

### Endpoint
/api/developer/oauth/authorize
```

```APIDOC
## POST /api/developer/oauth/token

### Description
Exchange code for access token or refresh token

### Method
POST

### Endpoint
/api/developer/oauth/token
```

```APIDOC
## GET /api/developer/oauth/scopes

### Description
List all available OAuth scopes

### Method
GET

### Endpoint
/api/developer/oauth/scopes
```

--------------------------------

### JavaScript Velora Streaming API Client

Source: https://developer.velora.tv/developer/docs/guides/streaming-software

A complete JavaScript client for the Velora Streaming API. Use this to fetch stream keys, ingest URLs, update stream info, and manage categories. Ensure you have a valid access token.

```javascript
// Velora Streaming API Client Example

const VELORA_API = 'https://api.velora.tv/api/integrations/oauth';

class VeloraStreamClient {
  constructor(accessToken) {
    this.accessToken = accessToken;
  }

  async request(endpoint, options = {}) {
    const response = await fetch(`${VELORA_API}${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'API request failed');
    }

    return response.json();
  }

  // Get stream key and ingest URLs
  async getStreamSetup() {
    return this.request('/stream/setup');
  }

  // Get current stream info
  async getStreamInfo() {
    return this.request('/stream/info');
  }

  // Update stream title and category
  async updateStreamInfo({ title, categorySlug, tags }) {
    return this.request('/stream/info', {
      method: 'PUT',
      body: JSON.stringify({ title, categorySlug, tags }),
    });
  }

  // Get available categories
  async getCategories() {
    return this.request('/stream/categories');
  }

  // Regenerate stream key
  async regenerateStreamKey() {
    return this.request('/stream/key/regenerate');
  }
}

// Usage
const client = new VeloraStreamClient('your_access_token');

// Configure OBS with Velora credentials
async function configureOBS() {
  const setup = await client.getStreamSetup();

  console.log('Configure OBS with these settings:');
  console.log('Server:', setup.rtmpUrl);
  console.log('Stream Key:', setup.streamKey);

  return setup;
}

// Update stream before going live
async function prepareStream(title, category) {
  await client.updateStreamInfo({
    title,
    categorySlug: category,
  });

  console.log('Stream info updated!');
}

// Example: Set up a coding stream
configureOBS().then(setup => {
  prepareStream(
    'Building a Velora integration!',
    'software-and-game-development'
  );
});

```

--------------------------------

### Search

Source: https://developer.velora.tv/developer/docs/api-reference

Endpoints for global and user search.

```APIDOC
## GET /api/search/global

### Description
Search creators and categories (public, query: ?query=term&limit=8). Returns isLive status for each creator.

### Method
GET

### Endpoint
/api/search/global

### Parameters
#### Query Parameters
- **query** (string) - Required - Search term
- **limit** (integer) - Optional - Maximum number of results
```

```APIDOC
## GET /api/users/search

### Description
Search users for mentions/invites (requires auth, query: ?q=term&limit=10)

### Method
GET

### Endpoint
/api/users/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search term
- **limit** (integer) - Optional - Maximum number of results
```

--------------------------------

### Include Access Token in Authorization Header (cURL)

Source: https://developer.velora.tv/developer/docs/authentication

Demonstrates how to include the access token in the 'Authorization' header for API requests. Use 'Bearer YOUR_ACCESS_TOKEN' format.

```curl
curl https://api.velora.tv/api/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

--------------------------------

### WebSocket Connection

Source: https://developer.velora.tv/developer/docs/events-api

Establish a persistent bidirectional connection using Socket.IO to receive events in real-time. This is ideal for desktop applications and situations where hosting a webhook endpoint isn't practical.

```APIDOC
## WebSocket Connection

### Connection URL
`wss://api.velora.tv/ws/events`

### Connection Example (JavaScript)
```javascript
import { io } from 'socket.io-client';

const socket = io('wss://api.velora.tv/ws/events', {
  auth: {
    token: 'YOUR_ACCESS_TOKEN'
  }
  // Or pass token as query parameter:
  // query: { token: 'YOUR_ACCESS_TOKEN' }
});

// Connection established
socket.on('connected', (data) => {
  console.log('Connected to Events API');
  console.log('Channel:', data.channelUsername);
});

// Listen for all events
socket.on('event', (payload) => {
  console.log('Event received:', payload.event);
  console.log('Data:', payload.data);
  console.log('Timestamp:', payload.timestamp);
});

// Handle errors
socket.on('error', (err) => {
  console.error('Connection error:', err.message);
});

// Handle disconnection
socket.on('disconnect', (reason) => {
  console.log('Disconnected:', reason);
});
```

### Connection Example (C# / Streamer.bot)
```csharp
using SocketIOClient;

var socket = new SocketIO("wss://api.velora.tv/ws/events", new SocketIOOptions
{
    Auth = new { token = "YOUR_ACCESS_TOKEN" }
});

socket.On("connected", response =>
{
    var data = response.GetValue<ConnectedData>();
    Console.WriteLine($"Connected as {data.ChannelUsername}");
});

socket.On("event", response =>
{
    var payload = response.GetValue<EventPayload>();
    Console.WriteLine($"Event: {payload.Event}");
    // Handle the event...
});

await socket.ConnectAsync();
```
```

--------------------------------

### Exchange Code for Token (cURL)

Source: https://developer.velora.tv/developer/docs/authentication

Use this cURL command to exchange the authorization code for an access token after user consent. Ensure all parameters are correctly included.

```curl
curl -X POST https://api.velora.tv/api/developer/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://yourapp.com/callback",
    "code_verifier": "YOUR_CODE_VERIFIER"
  }'
```

--------------------------------

### Signature Verification

Source: https://developer.velora.tv/developer/docs/webhooks/events

Verify webhook signatures using the provided headers to ensure requests originate from Velora.

```APIDOC
## Signature Verification

Verify webhook signatures to ensure requests are from Velora:

| Header              | Description                                       |
|---------------------|---------------------------------------------------|
| `X-Velora-Signature`| HMAC-SHA256 signature of the request body         |
| `X-Velora-Timestamp`| Unix timestamp (milliseconds) when the event was sent |
| `X-Velora-Event`    | The event type (e.g., stream.online)              |

```javascript
// Node.js signature verification
const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(body);
  const expectedSignature = hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
```
```

--------------------------------

### Match Redemption Event to Rewards

Source: https://developer.velora.tv/developer/docs/events-api

When a channel points redemption event occurs, use the rewardId from the event payload to match against your fetched rewards list to trigger the correct action. The event may also include user input if the reward accepts it.

```json
// Redemption event payload
{
  "event": "channel.channel_points_redemption",
  "timestamp": "2026-02-10T12:00:00Z",
  "data": {
    "redemptionId": "red_abc123",
    "rewardId": "reward_abc123",     // Match this to your rewards list
    "rewardTitle": "Highlight My Message",
    "rewardCost": 500,
    "userId": "user_xyz",
    "username": "viewer123",
    "displayName": "Viewer123",
    "userInput": "Check out my message!",  // If reward accepts input
    "status": "unfulfilled",
    "redeemedAt": "2026-02-10T12:00:00Z"
  }
}
```

--------------------------------

### Sending a Message

Source: https://developer.velora.tv/developer/docs/chat-websocket

Use the `sendMessage` event to send a message to a channel. Supports optional fields for platform, message effects, and replies.

```APIDOC
## Sending Messages

### Description
Emit the `sendMessage` event to send a message to a specified channel. The server enforces various constraints such as message length, slow mode, and content filtering. You will receive a `commandResult` event indicating the success or failure of your message.

### Event
`sendMessage`

### Parameters
- **channelId** (string) - Required - The ID or username of the channel to send the message to.
- **message** (string) - Required - The content of the message.
- **platform** (string) - Optional - The platform for the message (e.g., 'velora', 'twitch', 'kick', 'youtube'). Defaults to 'velora'.
- **effect** (string) - Optional - An optional message effect (e.g., 'rainbow').
- **effectColor** (string) - Optional - An optional color override for the message effect.
- **replyTo** (object) - Optional - An object containing reply context:
  - **messageId** (string) - The ID of the message being replied to.
  - **username** (string) - The username of the message author being replied to.
  - **snippet** (string) - A preview snippet of the parent message.

### Example
```javascript
socket.emit('sendMessage', {
  channelId: 'streamer_user_id_or_username',
  message: 'Hello from my bot!',
  platform: 'velora',
  effect: 'rainbow',
  effectColor: '#ff00ff',
  replyTo: {
    messageId: 'parent_msg_id',
    username: 'parent_author',
    snippet: 'Parent message preview',
  },
});
```
```

--------------------------------

### Exchange Code for Token

Source: https://developer.velora.tv/developer/docs/authentication

After the user authorizes your application, exchange the authorization code for an access token and refresh token.

```APIDOC
## POST /api/developer/oauth/token

### Description
Exchanges an authorization code for an access token.

### Method
POST

### Endpoint
`https://api.velora.tv/api/developer/oauth/token`

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be `"authorization_code"`
- **client_id** (string) - Required - Your application's client ID
- **client_secret** (string) - Required - Your application's client secret
- **code** (string) - Required - The authorization code received from the user
- **redirect_uri** (string) - Required - The redirect URI registered with your application
- **code_verifier** (string) - Required - The PKCE code verifier generated in step 1

### Request Example
```json
{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "https://yourapp.com/callback",
  "code_verifier": "YOUR_CODE_VERIFIER"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token for API requests
- **refresh_token** (string) - The token used to obtain a new access token
- **token_type** (string) - The type of token, usually `"Bearer"`
- **expires_in** (integer) - The token's lifetime in seconds
- **scope** (string) - The scopes granted to this token

### Response Example
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "user:read stream:read"
}
```
```