Release 0.22.0 (#195)

## Description

Describe your changes in detail

---------

Co-authored-by: Miłosz Filimowski <[email protected]>
Co-authored-by: Tomasz Mazur <[email protected]>

Author: 3 people

api/fishjam-server

@@ -1,6 +1,6 @@
 ## What is an Agent?
 
 An agent is a piece of software that allows your backend server to participate in a Fishjam room, similar to how the Fishjam client SDKs allow your client-side application to participate in a Fishjam room.
-They can be used to implement features such as real-time audio transcription, audio recording, real-time content moderation and more.
+They can be used to implement features such as real-time audio transcription, real-time content moderation, conversations with AI agents and more.
 
 You can simply think of an agent as a peer running within your backend application.

api/protos

@@ -0,0 +1,3 @@
+:::danger Remember to disconnect your agents!
+It's important to disconnect agents, because **every connected agent generates usage** just as a normal peer.
+:::

api/room-manager

@@ -7,6 +7,7 @@ sidebar_position: 5
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 import AgentDefinition from "../_common/agents/definition.mdx";
+import RememberToDisconnect from "../_common/agents/remember-to-disconnect.mdx";
 import Subscriptions from "../_common/agents/subscriptions.mdx";
 
 # Agent Internals
@@ -50,6 +51,8 @@ curl -XPOST -H "Authorization: Bearer $FISHJAM_MANAGEMENT_TOKEN" \
 ### Step 2. Connecting to the Room
 
 Agents connect to Fishjam by initiating a WebSocket connection on the `/socket/agent/websocket` REST API endpoint.
+All communication over the WebSocket between Agent the Fishjam is done using [Protobuf messages](https://protobuf.dev/).
+Check [Fishjam Protobuf reference](../api/reference#protobufs) for more info.  
 Once connected, the agent must authenticate with Fishjam by sending an [`AgentRequest.AuthRequest` protobuf message](../api/reference#protobufs).
 An example of initiating a connection using [websocat](https://github.com/vi/websocat) and [Buf CLI](https://buf.build/docs/cli/) would look like:
 
@@ -69,11 +72,21 @@ In a backend application, we suggest using the [Protobuf compiler](https://proto
 
 Once connected, an agent will receive chunks of audio as [`AgentRequest.TrackData` protobuf message](../api/reference#protobufs).
 
-### Step 4. Disconnecting from the Room
+### Step 4. Sending Audio
+
+All further steps are done via the WebSocket connection created in [Step 2](#step-2-connecting-to-the-room).
+
+To send audio to an agent, you need to create an audio track first.
+This is done by sending an [`AgentRequest.CreateTrack` protobuf message](../api/reference#protobufs).
+Once the track is created, you can send audio to it using [`AgentRequest.TrackData` protobuf message](../api/reference#protobufs).
+
+### Step 5. Disconnecting from the Room
 
 An agent disconnects from the room by closing the WebSocket connection created in [Step 2](#step-2-connecting-to-the-room).
 It may reconnect using the same token it provided in [Step 2](#step-2-connecting-to-the-room).
 
+<RememberToDisconnect />
+
 ## Peer subscriptions
 
 <Subscriptions />
@@ -90,4 +103,4 @@ Currently, only **16-bit PCM** (raw) audio output is supported.
 The output can have either a sample rate of **16kHz** or **24kHz**.
 
 The above values aim to be compatible with popular real-time AI audio APIs.
-If you require a different output format, then make sure to contact us at [email protected].
+If you require a different output format, then make sure to contact us at `[email protected]`.

docs/_common/agents/definition.mdx

@@ -60,7 +60,7 @@ sequenceDiagram
     FM->>BE: Return room ID
     BE->>FM: Create peer (Server SDK)
     FM->>BE: Return peer token
-    BE->>Client: Send peer token + Fishjam URL
+    BE->>Client: Send peer token + Fishjam ID
 ```
 
 ### 2. Media Streaming Flow

docs/_common/agents/remember-to-disconnect.mdx

@@ -40,13 +40,13 @@ import {
   RoomConfigRoomTypeEnum,
 } from "@fishjam-cloud/js-server-sdk";
 import express from "express";
-const fishjamUrl = "";
+const fishjamId = "";
 const managementToken = "";
 const app = express();
 
 // ---cut---
 // What Sandbox API does internally (simplified)
-const fishjamClient = new FishjamClient({ fishjamUrl, managementToken });
+const fishjamClient = new FishjamClient({ fishjamId, managementToken });
 
 app.get("/", async (req: express.Request, res: express.Response) => {
   const { roomName, peerName, roomType } = req.query;
@@ -59,7 +59,7 @@ app.get("/", async (req: express.Request, res: express.Response) => {
   // Create or get peer
   const { peer, peerToken } = await fishjamClient.createPeer(room.id);
 
-  res.json({ peerToken, url: fishjamUrl });
+  res.json({ peerToken });
 });
 ```
 

docs/explanation/agent-internals.mdx

@@ -71,10 +71,10 @@ Peer tokens give permission to:
 import { FishjamClient, RoomId } from "@fishjam-cloud/js-server-sdk";
 import express from "express";
 const res = {} as any;
-const fishjamUrl = "";
 const managementToken = "";
+const fishjamId = "";
 const roomId = "" as unknown as RoomId;
-const fishjamClient = new FishjamClient({ fishjamUrl, managementToken });
+const fishjamClient = new FishjamClient({ fishjamId, managementToken });
 
 // ---cut---
 // Backend generates peer token (using management token)
@@ -85,7 +85,6 @@ const { peer, peerToken } = await fishjamClient.createPeer(roomId, {
 // Backend sends peer token to client
 res.json({
   peerToken, // Client uses this to connect
-  fishjamUrl, // Fishjam server URL
   roomId, // Room information
 });
 ```
@@ -95,15 +94,11 @@ res.json({
 ```typescript
 import { useConnection } from "@fishjam-cloud/react-client";
 const joinRoom = {} as any;
-const fishjamUrl = "";
 const peerToken = "";
 
 // ---cut---
 // Client uses peer token to connect (safe to use in frontend)
-await joinRoom({
-  url: fishjamUrl,
-  peerToken: peerToken, // This is safe in client code
-});
+await joinRoom({ peerToken }); // This is safe in client code
 ```
 
 ## Next Steps

docs/explanation/architecture.mdx

@@ -11,7 +11,7 @@ If you wish to see more general info, visit [**Set up your server**](../../how-t
 ## Minimal setup
 
 The same way as in the [**FastAPI docs**](https://fastapi.tiangolo.com/tutorial/first-steps/), the code below can be copied and run immediately.
-Just make sure you set `FISHJAM_URL` and `FISHJAM_MANAGEMENT_TOKEN` environment variables.
+Just make sure you set `FISHJAM_ID` and `FISHJAM_MANAGEMENT_TOKEN` environment variables.
 The `Depends` function allows the `FishjamClient` to be provided to the route function as a dependency, which avoids code duplication and allows easy mocking.
 
 ```python
@@ -24,9 +24,9 @@ from fishjam import FishjamClient
 app = FastAPI()
 
 def fishjam_client():
-    fishjam_url = os.environ["FISHJAM_URL"]
+    fishjam_id = os.environ["FISHJAM_ID"]
     management_token = os.environ["FISHJAM_MANAGEMENT_TOKEN"]
-    return FishjamClient(fishjam_url=fishjam_url, management_token=management_token)
+    return FishjamClient(fishjam_id=fishjam_id, management_token=management_token)
 
 
 @app.get("/")
@@ -77,7 +77,7 @@ It doesn't interact with the FastAPI library per se, just start the event loop a
 import asyncio
 from fishjam import FishjamNotifier
 
-notifier = FishjamNotifier(server_address=fishjam_url, server_api_token=management_token)
+notifier = FishjamNotifier(server_address=fishjam_id, server_api_token=management_token)
 
 @notifier.on_server_notification
 def handle_notification(notification):