@digitalsamba/embedded-api-mcp-server
Version:
Digital Samba Embedded API MCP Server - Model Context Protocol server for Digital Samba's Embedded API
726 lines • 24.1 kB
TypeScript
import { MemoryCache } from "./cache.js";
import type { PaginationParams, DateRangeParams, ApiResponse, Room, RoomCreateSettings, BreakoutRoom, BreakoutRoomCreateSettings, BreakoutRoomParticipantAssignment, Session, SessionStatistics, Participant, ParticipantDetail, TokenOptions, TokenResponse, Recording, RecordingDownloadLink, Poll, PollOption, PollCreateSettings, Library, LibraryFolder, LibraryFile, Webhook, WebhookCreateSettings, Role, RoleCreateSettings } from "./types/index.js";
export type { PaginationParams, DateRangeParams, ApiResponse, Room, RoomCreateSettings, BreakoutRoom, BreakoutRoomCreateSettings, BreakoutRoomParticipantAssignment, Session, SessionStatistics, Participant, ParticipantDetail, TokenOptions, TokenResponse, Recording, RecordingDownloadLink, Poll, PollOption, PollCreateSettings, Library, LibraryFolder, LibraryFile, Webhook, WebhookCreateSettings, Role, RoleCreateSettings };
export declare class DigitalSambaApiClient {
protected apiBaseUrl: string;
protected cache?: MemoryCache;
/**
* Creates an instance of the Digital Samba API Client
*
* @constructor
* @param {string} [apiKey] - Optional developer key for direct authentication. If not provided,
* the client will use the ApiKeyContext for session-based authentication
* @param {string} [apiBaseUrl='https://api.digitalsamba.com/api/v1'] - Base URL for the Digital Samba API
* @example
* // Create a client with the default API URL
* const client = new DigitalSambaApiClient('your-developer-key');
*
* // Create a client with a custom API URL
* const customClient = new DigitalSambaApiClient('your-developer-key', 'https://custom-api.example.com/v1');
*/
constructor(apiKey?: string, apiBaseUrl?: string, cache?: MemoryCache);
private _apiKey?;
/**
* Get the developer key from context or direct value
*
* This method retrieves the developer key using a prioritized approach:
* 1. First tries to get the developer key from the ApiKeyContext (for session-based auth)
* 2. If not found, falls back to using the direct developer key if provided during construction
* 3. If neither source provides a developer key, throws an AuthenticationError
*
* @protected
* @returns {string} The developer key to use for authentication
* @throws {AuthenticationError} If no developer key is available from any source
*/
protected getApiKey(): string;
/**
* Make an authenticated request to the Digital Samba API
*
* This method handles all API requests including authentication, error handling, and response parsing.
* It automatically adds the Authorization header with the API key, logs request details (excluding sensitive
* information), and processes the response. It also handles special cases like 204 No Content responses and
* adds array-like properties to ApiResponse objects for easier consumption.
*
* @protected
* @template T - The expected response type
* @param {string} endpoint - The API endpoint path (without the base URL)
* @param {RequestInit} [options={}] - Request options, including method, body, and additional headers
* @returns {Promise<T>} A promise resolving to the parsed response data
* @throws {AuthenticationError} If no API key is available for authentication
* @throws {ApiRequestError} If a network error occurs during the request
* @throws {ApiResponseError} If the API returns a non-2xx status code
* @throws {ValidationError} If the API returns a 400 Bad Request with validation errors
* @throws {ResourceNotFoundError} If the API returns a 404 Not Found response
* @example
* // Example internal usage
* const rooms = await this.request<ApiResponse<Room>>('/rooms');
*/
protected request<T>(endpoint: string, options?: RequestInit): Promise<T>;
/**
* Get default room settings
*/
getDefaultRoomSettings(): Promise<Record<string, any>>;
/**
* Update default room settings
*/
updateDefaultRoomSettings(settings: Record<string, any>): Promise<Record<string, any>>;
/**
* List all rooms
*
* Retrieves a paginated list of all rooms in your Digital Samba account.
* Supports pagination, filtering, and sorting options.
*
* @param {PaginationParams} [params] - Optional pagination parameters
* @param {number} [params.limit] - Number of items per page (default: 10)
* @param {number} [params.offset] - Number of items to skip
* @param {'asc'|'desc'} [params.order] - Sort order
* @param {string} [params.after] - Cursor for pagination
* @returns {Promise<ApiResponse<Room>>} Paginated list of rooms
*
* @example
* // Get first 20 rooms
* const rooms = await client.listRooms({ limit: 20 });
*
* @example
* // Get next page
* const nextPage = await client.listRooms({
* limit: 20,
* after: rooms.data[rooms.data.length - 1].id
* });
*/
listRooms(params?: PaginationParams): Promise<ApiResponse<Room>>;
/**
* Get details for a specific room
*/
getRoom(roomId: string): Promise<Room>;
/**
* Create a new room
*
* Creates a new video conferencing room with the specified settings.
* Only the 'name' field is required; all other settings are optional.
*
* @param {RoomCreateSettings} settings - Room configuration
* @param {string} settings.name - Room name (required)
* @param {string} [settings.description] - Room description
* @param {'public'|'private'} [settings.privacy] - Room privacy setting
* @param {number} [settings.max_participants] - Maximum participants (2-2000)
* @param {string} [settings.friendly_url] - Custom URL slug
* @returns {Promise<Room>} The created room object
* @throws {ValidationError} If required fields are missing or invalid
* @throws {ApiResponseError} If room creation fails
*
* @example
* // Create a basic room
* const room = await client.createRoom({
* name: 'Team Standup'
* });
*
* @example
* // Create a fully configured room
* const room = await client.createRoom({
* name: 'All Hands Meeting',
* description: 'Monthly company meeting',
* privacy: 'private',
* max_participants: 200,
* friendly_url: 'all-hands',
* recordings_enabled: true,
* chat_enabled: true
* });
*/
createRoom(settings: RoomCreateSettings): Promise<Room>;
/**
* Update an existing room
*/
updateRoom(roomId: string, settings: Partial<RoomCreateSettings>): Promise<Room>;
/**
* Delete a room
*/
deleteRoom(roomId: string, options?: {
delete_resources?: boolean;
}): Promise<any>;
/**
* Generate a token for joining a room
*
* Creates a secure access token that allows a user to join a specific room.
* Tokens can include user information, roles, and expiration settings.
*
* @param {string} roomId - The ID of the room to generate a token for
* @param {TokenOptions} options - Token configuration options
* @param {string} [options.u] - User name to display
* @param {string} [options.ud] - External user identifier
* @param {string} [options.role] - User role (e.g., 'moderator', 'participant')
* @param {string} [options.avatar] - URL to user's avatar image
* @param {string} [options.exp] - Token expiration in minutes
* @returns {Promise<TokenResponse>} Object containing token and join link
*
* @example
* // Generate a basic participant token
* const { token, link } = await client.generateRoomToken('room-123', {
* u: 'John Doe'
* });
*
* @example
* // Generate a moderator token with expiration
* const { token, link } = await client.generateRoomToken('room-123', {
* u: 'Jane Smith',
* ud: 'user-456',
* role: 'moderator',
* exp: '120' // Expires in 2 hours
* });
*/
generateRoomToken(roomId: string, options: TokenOptions): Promise<TokenResponse>;
/**
* Delete all resources for a room
*/
deleteRoomResources(roomId: string): Promise<void>;
/**
* Get rooms with live participants count
*/
getLiveRooms(params?: PaginationParams): Promise<ApiResponse<{
id: string;
external_id?: string;
start_time: string;
session_duration: number;
live_participants: number;
}>>;
/**
* Get rooms with live participants data
*/
getLiveRoomsWithParticipants(params?: PaginationParams): Promise<ApiResponse<{
id: string;
external_id?: string;
start_time: string;
session_duration: number;
live_participants: {
id: string;
external_id?: string;
name: string;
role: string;
join_time: string;
}[];
}>>;
/**
* Get single room with live participants count
*/
getRoomLiveParticipantsCount(roomId: string): Promise<{
id: string;
external_id?: string;
start_time: string;
session_duration: number;
live_participants: number;
}>;
/**
* Get single room with live participants data
*/
getRoomLiveParticipantsData(roomId: string): Promise<{
id: string;
external_id?: string;
start_time: string;
session_duration: number;
live_participants: {
id: string;
external_id?: string;
name: string;
role: string;
join_time: string;
}[];
}>;
/**
* List all participants
*/
listParticipants(params?: PaginationParams & DateRangeParams & {
live?: boolean;
room_id?: string;
session_id?: string;
}): Promise<ApiResponse<Participant>>;
/**
* Get details for a specific participant
*/
getParticipant(participantId: string): Promise<ParticipantDetail>;
/**
* List participants in a room
*/
listRoomParticipants(roomId: string, params?: PaginationParams & DateRangeParams & {
live?: boolean;
session_id?: string;
}): Promise<ApiResponse<Participant>>;
/**
* List participants in a session
*/
listSessionParticipants(sessionId: string, params?: PaginationParams & DateRangeParams & {
live?: boolean;
}): Promise<ApiResponse<Participant>>;
/**
* Phone participants joined
*/
phoneParticipantsJoined(roomId: string, participants: {
call_id: string;
name?: string;
caller_number?: string;
external_id?: string;
}[]): Promise<void>;
/**
* Phone participants left
*/
phoneParticipantsLeft(roomId: string, callIds: string[]): Promise<void>;
/**
* List all recordings
*/
listRecordings(params?: PaginationParams & {
room_id?: string;
session_id?: string;
status?: "IN_PROGRESS" | "PENDING_CONVERSION" | "READY";
}): Promise<ApiResponse<Recording>>;
/**
* List archived recordings
*/
listArchivedRecordings(params?: PaginationParams & {
room_id?: string;
}): Promise<ApiResponse<Recording>>;
/**
* Get a specific recording
*/
getRecording(recordingId: string): Promise<Recording>;
/**
* Delete a recording
*/
deleteRecording(recordingId: string): Promise<void>;
/**
* Get a download link for a recording
*/
getRecordingDownloadLink(recordingId: string, validForMinutes?: number): Promise<RecordingDownloadLink>;
/**
* Archive a recording
*/
archiveRecording(recordingId: string): Promise<void>;
/**
* Unarchive a recording
*/
unarchiveRecording(recordingId: string): Promise<void>;
/**
* Start recording in a room
*/
startRecording(roomId: string): Promise<void>;
/**
* Stop recording in a room
*/
stopRecording(roomId: string): Promise<void>;
/**
* Start transcription in a room
*/
startTranscription(roomId: string): Promise<void>;
/**
* Stop transcription in a room
*/
stopTranscription(roomId: string): Promise<void>;
/**
* List available event types for webhooks
*/
listWebhookEvents(): Promise<string[]>;
/**
* List all webhooks
*/
listWebhooks(params?: PaginationParams): Promise<ApiResponse<Webhook>>;
/**
* Create a new webhook
*/
createWebhook(settings: WebhookCreateSettings): Promise<Webhook>;
/**
* Get a specific webhook
*/
getWebhook(webhookId: string): Promise<Webhook>;
/**
* Update a webhook
*/
updateWebhook(webhookId: string, settings: Partial<WebhookCreateSettings>): Promise<Webhook>;
/**
* Delete a webhook
*/
deleteWebhook(webhookId: string): Promise<void>;
/**
* List all roles
*/
listRoles(params?: PaginationParams): Promise<ApiResponse<Role>>;
/**
* Create a new role
*/
createRole(settings: RoleCreateSettings): Promise<Role>;
/**
* Get a specific role
*/
getRole(roleId: string): Promise<Role>;
/**
* Update a role
*/
updateRole(roleId: string, settings: Partial<RoleCreateSettings>): Promise<Role>;
/**
* Delete a role
*/
deleteRole(roleId: string): Promise<void>;
/**
* List all available permissions
*/
listPermissions(): Promise<string[]>;
/**
* List all sessions
*/
listSessions(params?: PaginationParams & DateRangeParams & {
live?: boolean;
room_id?: string;
}): Promise<ApiResponse<Session>>;
/**
* List sessions for a specific room
*/
listRoomSessions(roomId: string, params?: PaginationParams & DateRangeParams & {
live?: boolean;
}): Promise<ApiResponse<Session>>;
/**
* Get session statistics
*/
getSessionStatistics(sessionId: string, metrics?: string): Promise<SessionStatistics>;
/**
* End a live session
*/
endSession(sessionId: string): Promise<void>;
/**
* Get session summary
*/
getSessionSummary(sessionId: string): Promise<{
job_id: string;
status: "IN_PROGRESS" | "READY";
summary: string;
}>;
/**
* Delete session data
*/
deleteSessionData(sessionId: string, dataType: "chat" | "questions" | "summaries" | "transcripts" | "polls" | "recordings" | "resources"): Promise<void>;
/**
* Get chat messages
*/
getChatMessages(roomId: string, params?: PaginationParams & {
session_id?: string;
}): Promise<ApiResponse<{
id: string;
message: string;
participant_id: string;
external_participant_id?: string;
participant_name: string;
breakout_id?: string;
created_at: string;
}>>;
/**
* Delete chat messages
*/
deleteChatMessages(roomId: string): Promise<void>;
/**
* Get Q&A
*/
getQuestionsAndAnswers(roomId: string, params?: PaginationParams & {
session_id?: string;
}): Promise<ApiResponse<{
id: string;
question: string;
participant_id: string;
external_participant_id?: string;
participant_name: string;
created_at: string;
answers: {
id: string;
answer: string;
participant_id: string;
external_participant_id?: string;
participant_name: string;
created_at: string;
}[];
}>>;
/**
* Delete Q&A
*/
deleteQA(roomId: string): Promise<void>;
/**
* Get polls
*/
getPolls(roomId: string, params?: PaginationParams): Promise<Poll[]>;
/**
* Create a poll
*/
createPoll(roomId: string, settings: PollCreateSettings): Promise<Poll>;
/**
* Get a specific poll
*/
getPoll(roomId: string, pollId: string): Promise<Poll>;
/**
* Update a poll
*/
updatePoll(roomId: string, pollId: string, settings: Partial<PollCreateSettings>): Promise<Poll>;
/**
* Delete a poll
*/
deletePoll(roomId: string, pollId: string): Promise<void>;
/**
* Get poll results
*/
getPollResults(roomId: string, pollId: string, sessionId?: string): Promise<{
id: string;
session_id: string;
question: string;
status: string;
started: string;
ended?: string;
votes: number;
options: {
id: string;
text: string;
voted: number;
voters: {
id: string;
name: string;
}[];
}[];
}[]>;
/**
* Export polls
*/
exportPolls(roomId: string, options?: {
session_id?: string;
format?: "txt" | "json";
}): Promise<string>;
/**
* Export chat messages
*/
exportChatMessages(roomId: string, options?: {
session_id?: string;
format?: "txt" | "json";
}): Promise<string>;
/**
* Export Q&A (questions and answers)
*/
exportQA(roomId: string, options?: {
session_id?: string;
format?: "txt" | "json";
}): Promise<string>;
/**
* Export session transcripts
*/
exportTranscripts(sessionId: string, options?: {
format?: "txt" | "json";
}): Promise<string>;
/**
* List all libraries
*/
listLibraries(params?: PaginationParams): Promise<ApiResponse<Library>>;
/**
* Create a new library
*/
createLibrary(settings: {
name?: string;
external_id: string;
}): Promise<Library>;
/**
* Get a specific library
*/
getLibrary(libraryId: string): Promise<Library>;
/**
* Update a library
*/
updateLibrary(libraryId: string, settings: {
name?: string;
external_id?: string;
}): Promise<Library>;
/**
* Delete a library
*/
deleteLibrary(libraryId: string): Promise<void>;
/**
* Get library hierarchy
*/
getLibraryHierarchy(libraryId: string): Promise<Record<string, any>>;
/**
* List library folders
*/
listLibraryFolders(libraryId: string, params?: PaginationParams): Promise<ApiResponse<LibraryFolder>>;
/**
* Create a library folder
*/
createLibraryFolder(libraryId: string, settings: {
name?: string;
parent_id?: string;
}): Promise<LibraryFolder>;
/**
* Get a specific library folder
*/
getLibraryFolder(libraryId: string, folderId: string): Promise<LibraryFolder>;
/**
* Update a library folder
*/
updateLibraryFolder(libraryId: string, folderId: string, settings: {
name?: string;
parent_id?: string;
}): Promise<LibraryFolder>;
/**
* Delete a library folder
*/
deleteLibraryFolder(libraryId: string, folderId: string): Promise<void>;
/**
* List library files
*/
listLibraryFiles(libraryId: string, params?: PaginationParams): Promise<LibraryFile[]>;
/**
* Create a new library file (get upload URL and token)
*/
createLibraryFile(libraryId: string, settings: {
name: string;
folder_id?: string;
}): Promise<{
file_id: string;
file_name: string;
external_storage_url: string;
token: string;
expiration_timestamp: number;
}>;
/**
* Get a specific library file
*/
getLibraryFile(libraryId: string, fileId: string): Promise<LibraryFile>;
/**
* Update a library file
*/
updateLibraryFile(libraryId: string, fileId: string, settings: {
name?: string;
folder_id?: string;
}): Promise<LibraryFile>;
/**
* Delete a library file
*/
deleteLibraryFile(libraryId: string, fileId: string): Promise<void>;
/**
* Get file links
*/
getFileLinks(libraryId: string, fileId: string): Promise<{
pages: {
url: string;
thumbnail_url: string;
}[];
}>;
/**
* Create a webapp in a library
*/
createWebapp(libraryId: string, settings: {
name: string;
folder_id?: string;
}): Promise<{
file_id: string;
file_name: string;
external_storage_url: string;
token: string;
expiration_timestamp: number;
}>;
/**
* Create a whiteboard in a library
*/
createWhiteboard(libraryId: string, settings: {
name: string;
folder_id?: string;
}): Promise<{
file_id: string;
file_name: string;
external_storage_url: string;
token: string;
expiration_timestamp: number;
}>;
/**
* Get team global statistics by period
*/
getTeamStatistics(params?: DateRangeParams & {
metrics?: string;
}): Promise<Record<string, any>>;
/**
* Get team global statistics by current period
*/
getTeamCurrentStatistics(metrics?: string): Promise<Record<string, any>>;
/**
* Get team statistics for current period (simplified)
*/
getSimplifiedTeamCurrentStatistics(): Promise<Record<string, any>>;
/**
* Get room statistics by period
*/
getRoomStatistics(roomId: string, params?: DateRangeParams & {
metrics?: string;
}): Promise<Record<string, any>>;
/**
* Get room statistics for current period
*/
getRoomCurrentStatistics(roomId: string, metrics?: string): Promise<Record<string, any>>;
/**
* Get participant statistics
*/
getParticipantStatistics(participantId: string): Promise<ParticipantDetail>;
/**
* List breakout rooms for a parent room
*/
listBreakoutRooms(roomId: string, params?: PaginationParams): Promise<ApiResponse<BreakoutRoom>>;
/**
* Get a specific breakout room
*/
getBreakoutRoom(roomId: string, breakoutRoomId: string): Promise<BreakoutRoom>;
/**
* Create breakout rooms
*/
createBreakoutRooms(roomId: string, settings: BreakoutRoomCreateSettings): Promise<ApiResponse<BreakoutRoom>>;
/**
* Delete a breakout room
*/
deleteBreakoutRoom(roomId: string, breakoutRoomId: string): Promise<void>;
/**
* Delete all breakout rooms
*/
deleteAllBreakoutRooms(roomId: string): Promise<void>;
/**
* List participants in a breakout room
*/
listBreakoutRoomParticipants(roomId: string, breakoutRoomId: string, params?: PaginationParams): Promise<ApiResponse<Participant>>;
/**
* Assign participants to breakout rooms
*/
assignParticipantsToBreakoutRooms(roomId: string, assignments: BreakoutRoomParticipantAssignment[]): Promise<void>;
/**
* Return all participants to the main room
*/
returnAllParticipantsToMainRoom(roomId: string): Promise<void>;
/**
* Broadcast message to all breakout rooms
*/
broadcastToBreakoutRooms(roomId: string, options: {
message: string;
}): Promise<void>;
/**
* Open breakout rooms (start breakout sessions)
*/
openBreakoutRooms(roomId: string): Promise<void>;
/**
* Close breakout rooms
*/
closeBreakoutRooms(roomId: string): Promise<void>;
/**
* Delete session chats
*/
deleteSessionChats(sessionId: string): Promise<void>;
/**
* Delete session Q&A
*/
deleteSessionQA(sessionId: string): Promise<void>;
/**
* Delete session summaries
*/
deleteSessionSummaries(sessionId: string): Promise<void>;
/**
* Delete session polls
*/
deleteSessionPolls(sessionId: string): Promise<void>;
/**
* Publish poll results
*/
publishPollResults(pollId: string, sessionId: string): Promise<void>;
}
//# sourceMappingURL=digital-samba-api.d.ts.map