dsh-agora 0.2.0

package/assets/agora/references/rtm/web.md

@@ -0,0 +1,348 @@
+# Agora Signaling SDK — Web (RTM)
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [RTM v2 (Web)](#rtm-v2-web)
+- [RTM v1 (Legacy Web)](#rtm-v1-legacy-web)
+- [Common Use Cases with RTC](#common-use-cases-with-rtc)
+- [Stream Channels (Topics)](#stream-channels-topics)
+
+## Overview
+
+RTM provides signaling, text messaging, presence, and metadata capabilities alongside RTC audio/video. RTC and RTM are **independent systems** — RTC channels and RTM channels are separate namespaces.
+
+**When to use RTM alongside RTC:**
+
+- Text chat during video calls
+- Signaling (call invitations, control messages)
+- User presence/status tracking
+- Custom data exchange (VAD signals, resolution requests)
+- Sending text messages to AI agents (Conversational AI)
+
+Package: `agora-rtm` (v2.x) on npm.
+
+## Installation
+
+```bash
+npm install agora-rtm
+```
+
+## RTM v2 (Web)
+
+### Initialization and Login
+
+```typescript
+import AgoraRTM from "agora-rtm"
+
+let rtmClient: AgoraRTM.RTM;
+try {
+  rtmClient = new AgoraRTM.RTM("your-app-id", "user-id-string", {
+    logLevel: "debug", // "debug" | "info" | "warn" | "error"
+  });
+} catch (status) {
+  console.error("RTM init failed", status);
+}
+
+// Always login with a server-generated RTM token
+await rtmClient.login({ token: 'YOUR_RTM_TOKEN' })
+```
+
+### Channel Subscription
+
+```typescript
+// Subscribe to a channel to receive messages and presence
+await rtmClient.subscribe("channel-name", {
+  withMessage: true,
+  withPresence: true,
+})
+
+// Unsubscribe
+await rtmClient.unsubscribe("channel-name")
+```
+
+### Sending Messages
+
+```typescript
+// Publish to channel (all subscribers receive)
+await rtmClient.publish("channel-name", "Hello everyone!", {
+  customType: "chat.message",
+})
+
+// Publish JSON data
+await rtmClient.publish("channel-name", JSON.stringify({
+  type: "control",
+  action: "mute-all",
+}), {
+  customType: "control.message",
+})
+
+// Peer-to-peer (publish to user topic)
+await rtmClient.publish("target-user-id", JSON.stringify({
+  message: "Hello!",
+  priority: "APPEND",
+}), {
+  customType: "user.transcription",
+  channelType: "USER",
+})
+```
+
+### Receiving Messages
+
+```typescript
+rtmClient.addEventListener("message", (event) => {
+  console.log("Message from:", event.publisher)
+  console.log("Channel:", event.channelName)
+  console.log("Content:", event.message)      // string or Uint8Array
+  console.log("Type:", event.customType)
+
+  // Parse if JSON
+  if (typeof event.message === "string") {
+    try {
+      const data = JSON.parse(event.message)
+    } catch {}
+  }
+})
+```
+
+### Presence Events
+
+```typescript
+rtmClient.addEventListener("presence", (event) => {
+  // event.eventType: "SNAPSHOT" | "INTERVAL" | "JOIN" | "LEAVE" | "TIMEOUT" | "STATE_CHANGED"
+
+  switch (event.eventType) {
+    case "SNAPSHOT":
+      // Initial state on subscribe — event.snapshot is an array of {userId, states}
+      for (const user of event.snapshot) {
+        console.log("Online:", user.userId, user.states)
+      }
+      break
+    case "JOIN":
+      console.log("User joined:", event.publisher)
+      break
+    case "LEAVE":
+    case "TIMEOUT":
+      console.log("User left:", event.publisher)
+      break
+    case "INTERVAL":
+      // Periodic batch update — contains joinedUsers[], leftUsers[], timeoutUsers[]
+      for (const uid of event.joinedUsers ?? []) console.log("Joined:", uid)
+      for (const uid of event.leftUsers ?? []) console.log("Left:", uid)
+      break
+    case "STATE_CHANGED":
+      // User called setState — event.publisher, event.stateChanged (key-value pairs)
+      console.log("State changed:", event.publisher, event.stateChanged)
+      break
+  }
+})
+```
+
+### Connection Status
+
+```typescript
+rtmClient.addEventListener("status", (event) => {
+  // event.state: "CONNECTED" | "CONNECTING" | "RECONNECTING" | "DISCONNECTED"
+  console.log("RTM status:", event.state)
+})
+```
+
+### Cleanup
+
+```typescript
+async function cleanupRTM() {
+  await rtmClient.unsubscribe("channel-name")
+  await rtmClient.logout()
+}
+```
+
+
+## Common Use Cases with RTC
+
+### Text Chat During Video Call
+
+```typescript
+// RTM for chat alongside RTC video
+rtmClient.addEventListener("message", (event) => {
+  if (event.customType === "chat.message") {
+    displayChatMessage(event.publisher, event.message)
+  }
+})
+
+function sendChatMessage(text: string) {
+  rtmClient.publish(channelName, text, { customType: "chat.message" })
+}
+```
+
+### Voice Activity Detection (VAD) Signaling
+
+```typescript
+// Notify other users when speaking (for prioritized video)
+function notifyVAD(uid: number) {
+  rtmClient.publish(channelName, JSON.stringify({
+    type: "VAD",
+    uid: uid,
+  }), { customType: "signaling.vad" })
+}
+```
+
+### Control Messages
+
+```typescript
+// Request resolution change, stop screen share, etc.
+rtmClient.publish(channelName, JSON.stringify({
+  type: "INCREASE_RESOLUTION",
+  targetUid: uid,
+}), { customType: "signaling.control" })
+```
+
+### Sending Text to Conversational AI Agent
+
+```typescript
+// Send a text message to an AI agent via RTM
+async function sendMessageToAgent(message: string, agentUid: string) {
+  const publishTarget = `${agentUid}-${channel}`
+
+  await rtmClient.publish(publishTarget, JSON.stringify({
+    message: message.trim(),
+    priority: "APPEND", // or "REPLACE"
+  }), {
+    customType: "user.transcription",
+    channelType: "USER",
+  })
+}
+```
+
+## Stream Channels (Topics)
+
+Stream channels provide structured, topic-based messaging with lower latency than message channels. Users **join** a stream channel (rather than subscribing) and publish/subscribe to **topics** within it.
+
+```typescript
+// Create and join a stream channel
+const streamChannel = await rtmClient.createStreamChannel("channel-name")
+await streamChannel.join({
+  token: "your-rtm-token", // or null for testing
+  withPresence: true,
+})
+
+// Join a topic to publish messages
+await streamChannel.joinTopic("chat")
+
+// Publish to a topic
+await streamChannel.publishTopicMessage("chat", "Hello from stream channel!")
+
+// Subscribe to a topic to receive messages from specific publishers (or all)
+await streamChannel.subscribeTopic("chat", {
+  users: ["user-123", "user-456"], // optional: filter by publisher
+})
+
+// Receive messages (same "message" event as message channels)
+rtmClient.addEventListener("message", (event) => {
+  console.log("Topic:", event.topicName, "From:", event.publisher, ":", event.message)
+})
+
+// Leave topic and channel
+await streamChannel.leaveTopic("chat")
+await streamChannel.leave()
+```
+
+**When to use stream channels over message channels:**
+
+- Lower latency needed (0.5s heartbeat vs 5s for message channels)
+- Topic-based message routing within a channel
+- Fine-grained publisher filtering per topic
+- Max 64 users per stream channel, max 50 topics per channel
+
+## Presence State and Metadata
+
+### User State (setState / getState)
+
+Set temporary key-value metadata on the current user that is broadcast to all subscribers:
+
+```typescript
+// Set user state (visible to all channel subscribers)
+await rtmClient.presence.setState("channel-name", "MESSAGE", {
+  displayName: "Alice",
+  status: "available",
+  typing: "false",
+})
+
+// Get a specific user's state
+const result = await rtmClient.presence.getState("channel-name", "MESSAGE", "target-user-id")
+console.log(result.states) // { displayName: "Alice", status: "available", ... }
+
+// Remove state
+await rtmClient.presence.removeState("channel-name", "MESSAGE", ["typing"])
+```
+
+State is ephemeral — it is cleared when the user leaves or disconnects. Other users receive `STATE_CHANGED` presence events when state is updated.
+
+### Channel Metadata (Storage)
+
+Store persistent metadata on a channel (survives user disconnect):
+
+```typescript
+// Set channel metadata
+const metadata = new AgoraRTM.Metadata()
+metadata.setMetadataItem({ key: "roomTitle", value: "Team Standup" })
+metadata.setMetadataItem({ key: "maxParticipants", value: "10" })
+await rtmClient.storage.setChannelMetadata("channel-name", "MESSAGE", metadata, {})
+
+// Get channel metadata
+const result = await rtmClient.storage.getChannelMetadata("channel-name", "MESSAGE")
+for (const item of result.metadata.items) {
+  console.log(item.key, item.value)
+}
+
+// Subscribe to metadata updates
+await rtmClient.storage.subscribeChannelMetadata("channel-name", "MESSAGE")
+rtmClient.addEventListener("storage", (event) => {
+  console.log("Metadata updated:", event.data)
+})
+```
+
+### Important Notes
+
+- RTM does **not** echo published messages back to the sender. Your chat UI must add sent messages locally.
+- RTM uses **string UIDs** while RTC uses numeric UIDs. A common mapping strategy: use `String(rtcUid)` as the RTM userId, or maintain a lookup table if usernames differ.
+- `presenceTimeout` can be configured during RTM initialization:
+
+```typescript
+try {
+  const rtmClient = new AgoraRTM.RTM(appId, userId, {
+    presenceTimeout: 30, // seconds (5-1800), default 5
+  });
+} catch (status) {
+  console.error("RTM init failed", status);
+}
+```
+
+## Connection Management
+
+### Heartbeat Configuration
+
+- **MESSAGE channels**: Heartbeat interval defaults to **5 seconds**, customizable from 5–1800 seconds via `presenceTimeout` config.
+- **STREAM channels**: Fixed heartbeat interval of **0.5 seconds** (not configurable).
+- Set `presenceTimeout` appropriately to prevent excessive presence event floods during brief network reconnections.
+
+### Connection Cleanup
+
+- Always call `logout()` for MESSAGE channel connections.
+- Always call `leave()` for STREAM channel connections before disconnecting.
+- Failure to clean up properly causes ghost presence entries until heartbeat timeout.
+
+### REST API Rate Limiting
+
+When using RTM REST APIs, implement exponential back-off on rate limit responses:
+
+- 1st retry: wait **1 second**
+- 2nd retry: wait **3 seconds**
+- 3rd retry: wait **6 seconds**
+
+## Official Documentation
+
+For APIs or features not covered above:
+
+- API Reference: <https://docs.agora.io/en/signaling/reference/api?platform=web>
+- Guides: <https://docs.agora.io/en/signaling/overview/product-overview>

package/assets/agora/references/server/README.md

@@ -0,0 +1,22 @@
+# Agora Server-Side: Token Generation
+
+Server-side token generation for Agora authentication.
+
+## When Tokens Are Needed
+
+- **Production**: Always. Tokens authenticate users before they join channels.
+- **Testing/Development**: Technically optional — token auth can be disabled in [Agora Console](https://console.agora.io), allowing `null` to be passed as the token. **Warn the user if they attempt this**: any channel can be joined by anyone without authentication. This is never acceptable for production and should be avoided even in development unless strictly necessary.
+- **No App Certificate provided**: If the user has no App Certificate, they cannot generate tokens. Warn them explicitly that their project has no token security enabled, advise them to enable it in [Agora Console](https://console.agora.io) → Project Management → Edit → App Certificate, and do not proceed to generate code that omits token auth without this warning.
+- **Never expose App Certificate on client**. Token generation must happen server-side.
+
+## Token Types
+
+- **RTC Token**: Grants access to join a specific RTC channel with a specific UID. Required for Video/Voice SDK.
+- **RTM Token**: Grants access to RTM services for a specific user ID.
+- **AccessToken2**: Current token format. Supports privilege expiration per service and can bundle RTC + RTM privileges in a single token.
+
+## Reference Files
+
+- **[tokens.md](tokens.md)** — Token generation for Node.js, Python, and Go. Express server example, security best practices.
+- **Full token auth guide** — <https://docs-md.agora.io/en/video-calling/token-authentication/deploy-token-server.md>
+- **Local credential export** — for development setup, use [../cli/env.md](../cli/env.md) to export or write App ID/App Certificate values with the Agora CLI. Never expose the App Certificate to client code.

package/assets/agora/references/server/tokens.md

@@ -0,0 +1,74 @@
+# Agora Server-Side: Token Generation
+
+## Overview
+
+Tokens authenticate users before joining channels. Generated server-side from App ID + App Certificate + channel + UID + expiration.
+
+## Quick Reference
+
+- `onTokenPrivilegeWillExpire` fires **30 seconds** before expiry — renew proactively
+- UID in token must match UID used to join
+- Max token validity: 24 hours
+- Use `RtcRole.SUBSCRIBER` for audience-only users (prevents stream bombing)
+
+## UID / Account-Name Constraints (Token Gotcha)
+
+- Numeric UID (`buildTokenWithUid` + RTC join with numeric uid): must be `0` to `2^32 - 1`.
+- String UID/account name (`buildTokenWithUserAccount` or `buildTokenWithRtm` account): ASCII only, max `255` characters.
+- **RTM / `buildTokenWithRtm` `account`**: the API expects a string. Prefer an integer user id encoded as a string of digits (for example `"12345"`), not an arbitrary alphanumeric handle, to avoid identity clashes with other services.
+- Here, `account` means the user's RTC identity string (account name), not your Agora customer account.
+- Identity and type must match end-to-end:
+  - If the token is minted for numeric UID `123`, join RTC with numeric `123`.
+  - If the token is minted for account `"12345"` (string carrying a numeric id — preferred), join with that exact same string identity on the client; do not substitute a different handle or assume it interchangeably maps to a numeric uid unless your SDK documents that.
+
+## Token Generation Guides
+
+- **[Deploy a Token Server](https://docs.agora.io/en/video-calling/token-authentication/deploy-token-server)** — Express/Flask/Go server examples
+- **[Use Tokens](https://docs.agora.io/en/video-calling/token-authentication/authentication-workflow)** — When and how tokens are used
+
+## Token Libraries
+
+All implementations are in [AgoraIO/Tools — DynamicKey/AgoraDynamicKey](https://github.com/AgoraIO/Tools/tree/master/DynamicKey/AgoraDynamicKey):
+
+| Language | Notes                                                                               |
+| -------- | ----------------------------------------------------------------------------------- |
+| Node.js  | Also available as [`agora-token`](https://www.npmjs.com/package/agora-token) on npm |
+| Python 3 | Use `python3/` directory                                                            |
+| Go       |                                                                                     |
+| Java     |                                                                                     |
+| C#       |                                                                                     |
+| Dart     |                                                                                     |
+| Deno     | Native implementation — do NOT use the `agora-token` npm package in Deno            |
+| Rust     |                                                                                     |
+| PHP      |                                                                                     |
+| Ruby     |                                                                                     |
+| Lua      |                                                                                     |
+| Perl     |                                                                                     |
+
+## Token Types
+
+- **RTC Token** — channel access for Video/Voice SDK
+- **RTM Token** — access for Real-Time Messaging
+- **Combined RTC + RTM Token** — bundles RTC + RTM privileges in one token via `buildTokenWithRtm`; also satisfies the `agora token=` auth header for ConvoAI REST API calls (see [conversational-ai/README.md](../conversational-ai/README.md#authentication))
+
+> **[AccessToken2 Guide](https://docs.agora.io/en/video-calling/token-authentication/deploy-token-server)** — AccessToken2 with multi-service privileges
+
+## buildTokenWithRtm (Node.js)
+
+Generates a combined RTC + RTM token using `AccessToken2`. Use this when you need a single token that covers both channel access and RTM messaging — or to authenticate ConvoAI REST API calls.
+
+```javascript
+import { RtcTokenBuilder, RtcRole } from 'agora-token';
+
+const token = RtcTokenBuilder.buildTokenWithRtm(
+  appId, // string — your Agora App ID
+  appCertificate, // string — your App Certificate
+  channelName, // string — channel the user will join
+  account, // string — prefer integer user id as a string of digits (e.g. "12345")
+  RtcRole.PUBLISHER,
+  tokenExpire, // number — seconds until token expires (e.g. 3600)
+  privilegeExpire, // number — seconds until privileges expire (0 = same as tokenExpire)
+);
+```
+
+> **`account` vs `uid`**: `buildTokenWithRtm` takes a string `account`, not an integer type. Prefer passing the user's numeric id as a numeric string, and have the client join with that exact same string identity. If the RTC client joins with a numeric uid type instead, use `buildTokenWithUid` for RTC-only tokens.

package/assets/agora/references/server-gateway/README.md

@@ -0,0 +1,80 @@
+# Agora Server Gateway SDK
+
+Self-hosted SDK for transmitting audio and video streams between server-side applications and Agora's Voice and Video SDKs via the Agora SDRTN®.
+
+## Critical Rules
+
+1. **Video SDK channel must use `LIVE_BROADCASTING` mode** — standard `COMMUNICATION` mode is not supported when the remote peer is a Server Gateway client.
+2. **PCM audio must be sent in 10 ms intervals** — the SDK only accepts PCM frames of exactly 10 ms length.
+3. **AAC audio cannot use 44.1 kHz sampling** — use 16 kHz or 48 kHz instead.
+4. **All SDK methods are async and non-blocking** — use event callbacks and observers; do not expect synchronous results.
+5. **Server requires internet access to `*.agora.io` and `*.agoralab.co`** — ensure firewall rules allow outbound connections to these domains.
+6. **This is a self-hosted SDK, not a REST API** — the SDK runs as a process on your Linux server, not as a cloud service you call.
+
+## Key Concepts
+
+- **IAgoraService** — root object. Create once per process, initialize with audio/video config before creating any connections.
+- **IRtcConnection** — represents a connection to one RTC channel. Create one per channel. Manages join/leave lifecycle.
+- **IMediaNodeFactory** — factory for creating senders and receivers (audio PCM sender, video YUV sender, encoded video sender, etc.).
+- **Local tracks** — wrap senders/receivers and get published/subscribed via the connection.
+- **Observers** — implement `ILocalUserObserver`, `IAudioFrameObserver`, `IVideoEncodedImageReceiver` to receive incoming media frames via callbacks.
+
+## Architecture
+
+```text
+Your Server App (Server Gateway SDK)
+    ↕  audio/video frames (PCM, YUV, encoded)
+Agora SDRTN® (global real-time network)
+    ↕
+Video SDK clients (Web, iOS, Android, etc.)
+```
+
+Typical flow:
+1. Initialize `IAgoraService` with audio/video support enabled
+2. Create `IRtcConnection` and join channel
+3. Create media senders via `IMediaNodeFactory`, wrap in local tracks, publish
+4. Register observers to receive incoming frames via callbacks
+5. On shutdown: unpublish → unregister observers → disconnect → release all objects (order matters)
+
+## Supported Platforms
+
+| Platform | Language | Min OS |
+|----------|----------|--------|
+| Linux x86-64 | C++ | Ubuntu 14.04+ / CentOS 7.0+ |
+| Linux x86-64 | Java | Ubuntu 14.04+ / CentOS 7.0+ |
+| Linux x86-64 | Go | Ubuntu 18.04+ / CentOS 7.0+ |
+| Linux x86-64 | Python | Ubuntu 18.04+ / CentOS 7.0+ |
+| arm64 | C++ | Ubuntu 14.04+ |
+
+Hardware minimum: 8-core CPU 1.8 GHz, 2 GB RAM (4 GB recommended).
+
+## Media Formats
+
+| Type | Formats supported |
+|------|------------------|
+| Audio send | PCM (10 ms frames) |
+| Audio receive | PCM |
+| Video send | YUV, encoded (H.264, etc.) |
+| Video receive | Encoded frames |
+
+## Use Cases
+
+- **Call centers** — server-side agent voice processing
+- **AI interactive classes** — server processes audio/video for AI analysis
+- **Network testing** — automated stream injection and validation
+- **aPaaS** — application platform integrations that need server-side media
+
+## Platform Reference Files
+
+- **[linux-cpp.md](linux-cpp.md)** — C++ full implementation: init, senders, receivers, video mixing, shutdown sequence
+- **Java, Go, Python** — Level 2 fetch required; use [../doc-fetching.md](../doc-fetching.md) or fetch directly from the links below
+
+## When to Fetch More
+
+Always use Level 2 fetch for Java, Go, and Python quick-starts, SDK download links, and any platform-specific method signatures. Direct fallback URLs:
+
+- **Java** — <https://docs-md.agora.io/en/server-gateway/get-started/integrate-sdk?platform=java.md>
+- **Go** — <https://docs-md.agora.io/en/server-gateway/get-started/integrate-sdk?platform=go.md>
+- **Python** — <https://docs-md.agora.io/en/server-gateway/get-started/integrate-sdk?platform=python.md>
+- **Product Overview** — <https://docs-md.agora.io/en/server-gateway/overview/product-overview.md>
+- **SDK Downloads** — <https://docs.agora.io/en/sdks>