@huddle01/server-sdk/README.md

The Huddle01 Server SDK allows you to perform protected admin actions on your server side, like generating peer access tokens and starting and stopping meeting recordings and livestreams.

# Huddle01 Server SDK

![https://huddle01.app/room/images/small_logo.png](https://huddle01.app/room/images/small_logo.png)

<p align="center">
  <strong>People-powered
Communication</strong>
</p>

<h3 align="center">
  <a href="https://discord.com/invite/AZ5TRMMP55">Community</a>
  <span> · </span>
  <a href="https://huddle01.com/docs">Documentation</a>
</h3>

The Huddle01 Server SDK allows you to perform protected admin actions on your server side, like generating peer access tokens and starting and stopping meeting recordings and livestreams.

## Installation

```bash
npm install @huddle01/server-sdk
```

```bash
bun add @huddle01/server-sdk
```

```bash
pnpm i @huddle01/server-sdk
```

```bash
bun install @huddle01/server-sdk
```

## Auth

To enable client apps to establish connections with Huddle01 rooms, they require a token that is produced by your backend server. This guide will lead you through the process of configuring a server to create tokens for your clients.

```ts
import { AccessToken, Role } from "@huddle01/server-sdk/auth";

const accessToken = new AccessToken({
  apiKey: "YOUR_API_KEY",
  roomId: "YOUR_ROOM_ID",
  //available roles: Role.HOST, Role.CO_HOST, Role.SPEAKER, Role.LISTENER, Role.GUEST - depending on the privileges you want to give to the user
  role: Role.HOST,
  //custom permissions give you more flexibility in terms of the user privileges than a pre-defined role
  permissions: {
    admin: true,
    canConsume: true,
    canProduce: true,
    canProduceSources: {
      cam: true,
      mic: true,
      screen: true,
    },
    canRecvData: true,
    canSendData: true,
    canUpdateMetadata: true,
  },
  options: {
    metadata: {
      // you can add any custom attributes here which you want to associate with the user
      walletAddress: "mizanxali.eth",
    },
  },
});

const token = accessToken.toJwt();
```

## Recording/ Livestreaming

Server side helpers to start/stop recording and livestreaming

```ts
import { Recorder } from "@huddle01/server-sdk/recorder";

const recorder = new Recorder("PROJECT_ID", "API_KEY");
```

### 1. Start recording

```ts
/**
 * @returns {
 *  msg: string,
 * }
 */
const { msg } = recorder.startRecording({
  roomId: "YOUR_ROOM_ID",
  token,
});

console.log({ msg });
```

### 2. Start Livestream

Start a livestream and we can stream it to multiple RTMP endpoints.

```ts
/**
 * @returns {
 *  msg: string,
 * }
 */
const { msg } = await recorder.startLivestream({
  roomId: "ROOM_ID",
  token: "TOKEN_FOR_RECORDER" ,
  rtmpUrls: ["rtmp://example.com/live"],
  recordLivestream: true; // false by default
});

console.log({ msg });
```

### 3. Stop recording/livestream

```ts
/**
 * @returns {
 *  msg: string,
 * }
 */
recorder.stop({
  roomId: "YOUR_ROOM_ID",
});
```

## Webhooks

The `WebhookReceiver` is securely receiving and verifying Huddle01 webhooks.
It provides functionality to validate webhook signatures, extract webhook data, and ensure timing-safe comparisons.
The crypto libraries are environment independent allowing use across Node.JS, Cloudflare Worker etc

### 1. Initialization

First, import and initialize the WebhookReceiver with your API key:

```ts
import { WebhookReceiver } from "webhook-receiver";

const receiver = new WebhookReceiver({ apiKey: "YOUR_API_KEY" });
```

### 2. Receiving Webhooks

To receive and verify a webhook:

```ts
try {
  const webhookData = await receiver.receiveAsync(requestBody, signatureHeader);
  console.log("Verified webhook data:", webhookData);
} catch (error) {
  console.error("Webhook verification failed:", error.message);
}
```