Meeting BaaS SDK

Official SDK for interacting with the Meeting BaaS API - The unified API for Google Meet, Zoom, and Microsoft Teams.

Note: This package is automatically generated from the Meeting BaaS OpenAPI specification. For development and contribution guidelines, see DEVELOPMENT.md. For the official API reference, visit docs.meetingbaas.com.

🚀 New in v5.0.0: Complete architectural redesign with improved TypeScript support, better error handling, and enhanced developer experience. See MIGRATION.md for upgrade guide.

🆕 New in v6.0.0: Support for Meeting BaaS v2 API with type-safe version selection. Use api_version: "v2" to access the new API endpoints. See API Versioning section below.

Features

• BaaS API Client: Strongly typed functions for interacting with the Meeting BaaS API
• Bot Management: Create, join, and manage meeting bots across platforms
• Calendar Integration: Connect calendars and automatically schedule meeting recordings
• Complete API Coverage: Access to all Meeting BaaS API endpoints
• TypeScript Support: Full TypeScript definitions for all APIs
• Enhanced Error Handling: Discriminated union responses for type-safe error handling
• Parameter Validation: Automatic Zod schema validation for all API calls
• Tree-shakeable: Only import the methods you need
• Comprehensive Testing: Full test coverage with MSW mocking

System Requirements

• Node.js: Version 18.0.0 or higher.
• Package Managers: npm, yarn, or pnpm

Tested Node.js Versions: 18, 19, 20, 21, 22

Installation

# With npm
npm install @meeting-baas/sdk

# With yarn
yarn add @meeting-baas/sdk

# With pnpm
pnpm add @meeting-baas/sdk

Quick Start

v1 API (Default)

import { createBaasClient } from "@meeting-baas/sdk";

// Create a BaaS client (defaults to v1 API)
const client = createBaasClient({
  api_key: "your-api-key", // Get yours at https://meetingbaas.com
});

async function example() {
  // Join a meeting
  const { success, data, error } = await client.joinMeeting({
    bot_name: "Meeting Assistant",
    meeting_url: "https://meet.google.com/abc-def-ghi",
    reserved: true,
  });
  
  if (success) {
    console.log("Bot joined successfully:", data.bot_id);
  } else {
    console.error("Error joining meeting:", error);
  }
}

v2 API

import { createBaasClient } from "@meeting-baas/sdk";

// Create a v2 BaaS client
const client = createBaasClient({
  api_key: "your-api-key",
  api_version: "v2" // Use v2 API
});

async function example() {
  // Create a bot (v2 API method)
  const { success, data, error } = await client.createBot({
    meeting_url: "https://meet.google.com/abc-def-ghi",
    bot_name: "Meeting Assistant"
  });
  
  if (success) {
    console.log("Bot created successfully:", data.bot_id);
  } else {
    console.error("Error creating bot:", error);
  }
}

For MCP Servers

import { type JoinRequest, createBaasClient } from "@meeting-baas/sdk"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { z } from "zod"

// Create an MCP server
const server = new McpServer({
  name: "demo-server",
  version: "1.0.0"
})

// @modelcontextprotocol/sdk expects the input schema to be a ZodRawShape (plain object with zod types)
const joinToolInputSchema = {
  bot_name: z.string().default("Meeting BaaS Bot"),
  meeting_url: z.string(),
  reserved: z.boolean().default(false)
}

// Add a joinMeeting tool
server.registerTool(
  "joinMeeting",
  {
    title: "Send a Meeting BaaS bot to a meeting",
    description:
      "Send a Meeting BaaS bot to a Google Meet/Teams/Zoom meeting to automatically record and transcribe the meeting with speech diarization",
    inputSchema: joinToolInputSchema
  },
  async (args) => {
    const client = createBaasClient({
      api_key: "your-api-key"
    })

    const { success, data, error } = await client.joinMeeting(args as JoinRequest)

    if (success) {
      return {
        content: [{ type: "text", text: `Successfully joined meeting: ${JSON.stringify(data)}` }]
      }
    }

    return {
      content: [{ type: "text", text: `Failed to join meeting: ${error}` }]
    }
  }
)

Usage Examples

Basic Usage

import { createBaasClient } from "@meeting-baas/sdk";

// Create a BaaS client
const client = createBaasClient({
  api_key: "your-api-key",
});

const joinMeeting = async () => {
  // Join a meeting
  const { success, data, error } = await client.joinMeeting({
    bot_name: "My Assistant",
    meeting_url: "https://meet.google.com/abc-def-ghi",
    reserved: true,
  });

  if (success) {
    console.log("Bot joined successfully:", data.bot_id);
  } else {
    console.error("Error joining meeting:", error);
  }
}

const leaveMeeting = async () => {
  // Leave a meeting
  const { success, data, error } = await client.leaveMeeting({
    uuid: "123e4567-e89b-12d3-a456-426614174000"
  });
  
  if (success) {
    console.log("Bot left the meeting successfully:", data.bot_id);
  } else {
    console.error("Error leaving meeting:", error);
  }
}

Calendar Integration

import { createBaasClient } from "@meeting-baas/sdk";

const client = createBaasClient({
  api_key: "your-api-key",
});

// Create a calendar integration
const calendarResult = await client.createCalendar({
  oauth_client_id: "your-oauth-client-id",
  oauth_client_secret: "your-oauth-client-secret",
  oauth_refresh_token: "your-oauth-refresh-token",
  platform: "Google",
});

if (calendarResult.success) {
  console.log("Calendar created:", calendarResult.data);

  // List all calendars
  const calendarsResult = await client.listCalendars();
  if (calendarsResult.success) {
    console.log("All calendars:", calendarsResult.data);
  }

  // List events from a calendar
  const eventsResult = await client.listCalendarEvents({
    calendar_id: calendarResult.data.calendar.uuid,
    start_date_gte: new Date().toISOString(),
    start_date_lte: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
  });
  
  if (eventsResult.success) {
    console.log("Events:", eventsResult.data);
  }
}

Advanced Usage with Error Handling

import { createBaasClient } from "@meeting-baas/sdk";

const client = createBaasClient({
  api_key: "your-api-key",
  timeout: 60000
});

async function comprehensiveExample() {
  try {
    // Join a meeting with all options
    const joinResult = await client.joinMeeting({
      meeting_url: "https://meet.google.com/abc-defg-hij",
      bot_name: "Advanced Test Bot",
      reserved: false,
      bot_image: "https://example.com/bot-image.jpg",
      enter_message: "Hello from the advanced test bot!",
      extra: { test_id: "advanced-example" },
      recording_mode: "speaker_view",
      speech_to_text: { provider: "Gladia" },
      webhook_url: "https://example.com/webhook"
    });

    if (joinResult.success) {
      const botId = joinResult.data.bot_id;
      console.log("Bot joined with ID:", botId);

      // Get meeting data with transcripts
      const meetingDataResult = await client.getMeetingData({
        bot_id: botId,
        include_transcripts: true
      });

      if (meetingDataResult.success) {
        console.log("Meeting duration:", meetingDataResult.data.duration);
        console.log("Has MP4:", !!meetingDataResult.data.mp4);
      }

      // Leave the meeting
      const leaveResult = await client.leaveMeeting({
        uuid: botId
      });

      if (leaveResult.success) {
        console.log("Bot left meeting successfully");
      }

      // Delete bot data
      const deleteResult = await client.deleteBotData({
        uuid: botId
      });

      if (deleteResult.success) {
        console.log("Bot data deleted successfully");
      }
    }
  } catch (error) {
    console.error("Unexpected error:", error);
  }
}

API Reference

The SDK provides a comprehensive interface for all Meeting BaaS API endpoints. For detailed documentation of all available methods, see:

• API Reference - v1: Complete documentation for all v1 API methods (default)
• API Reference - v2: Complete documentation for all v2 API methods

Response Types

v1 API: All methods return a discriminated union response:

type ApiResponse<T> = 
  | { success: true; data: T; error?: never }
  | { success: false; error: ZodError | Error; data?: never }

v2 API: All methods return a discriminated union response:

type ApiResponseV2<T> = 
  | { success: true; data: T; error?: never }
  | { success: false; error: string; code: string; statusCode: number; details: unknown | null; data?: never }

Batch Routes (v2): Special case returning { success: true, data: [...], errors: [...] } for partial success scenarios.

TypeScript Support

The SDK provides full TypeScript support with generated types from the OpenAPI specification:

import type { 
  JoinRequest, 
  JoinResponse, 
  Metadata, 
  CreateCalendarParams 
} from "@meeting-baas/sdk";

// All types are available for advanced usage
const joinParams: JoinRequest = {
  meeting_url: "https://meet.google.com/abc-def-ghi",
  bot_name: "My Bot",
  reserved: false
};

Error Handling

The SDK provides type-safe error handling with discriminated union responses:

const result = await client.joinMeeting({
  meeting_url: "https://meet.google.com/abc-def-ghi",
  bot_name: "My Bot",
  reserved: false
});

if (result.success) {
  // TypeScript knows result.data is JoinResponse
  console.log("Bot ID:", result.data.bot_id);
} else {
  // TypeScript knows result.error is ZodError | Error
  if (result.error instanceof ZodError) {
    console.error("Validation error:", result.error.errors);
  } else {
    console.error("API error:", result.error.message);
  }
}

Webhook Types (v2)

The v2 API includes comprehensive TypeScript types for all webhook events, enabling you to build type-safe webhook handlers. All webhook types are available through the V2 namespace:

import type { V2 } from "@meeting-baas/sdk";

// Type-safe webhook handler
async function handleWebhook(payload: V2.BotWebhookCompleted) {
  if (payload.event === "bot.completed") {
    console.log("Bot completed:", payload.data.bot_id);
    console.log("Transcription:", payload.data.transcription);
  }
}

Available webhook types include:

• Bot webhooks: BotWebhookCompleted, BotWebhookFailed, BotWebhookStatusChange
• Calendar webhooks: CalendarWebhookConnectionCreated, CalendarWebhookConnectionUpdated, CalendarWebhookConnectionDeleted, CalendarWebhookEventCreated, CalendarWebhookEventUpdated, CalendarWebhookEventCancelled, CalendarWebhookEventsSynced
• Callback payloads: CallbackCompleted, CallbackFailed (for bot-specific callbacks)

See API Reference - v2 for more details and examples.

API Versioning

The SDK supports both Meeting BaaS v1 and v2 APIs. You can select which API version to use when creating the client:

// v1 API (default, for backward compatibility)
const v1Client = createBaasClient({
  api_key: "your-api-key"
  // api_version defaults to "v1"
});

// v2 API
const v2Client = createBaasClient({
  api_key: "your-api-key",
  api_version: "v2"
});

Type-Safe Version Selection

TypeScript automatically infers the available methods based on the api_version you specify:

// v1 client - only v1 methods available
const v1Client = createBaasClient({ api_key: "key" });
v1Client.joinMeeting({ ... }); // ✅ Available
v1Client.createBot({ ... }); // ❌ Not available

// v2 client - only v2 methods available
const v2Client = createBaasClient({ api_key: "key", api_version: "v2" });
v2Client.createBot({ ... }); // ✅ Available
v2Client.joinMeeting({ ... }); // ❌ Not available

Response Format Differences

v1 API: SDK wraps responses in { success: true, data: T } or { success: false, error: ZodError | Error }

v2 API: API already returns { success: true, data: T } or { success: false, error: string, code: string, statusCode: number, details: unknown | null }. The SDK passes these through without transformation.

Batch Routes (v2): Special case returning { success: true, data: [...], errors: [...] } for partial success scenarios.

Migration from v1 to v2

To migrate from v1 to v2, simply change the api_version in your client configuration:

// Before (v1)
const client = createBaasClient({
  api_key: "your-api-key"
});

// After (v2)
const client = createBaasClient({
  api_key: "your-api-key",
  api_version: "v2"
});

TypeScript will automatically show only v2 methods, making migration straightforward. See MIGRATION.md for detailed migration guide.

Configuration

The client accepts the following configuration options:

interface BaasClientConfig {
  api_key: string;           // Required: Your Meeting BaaS API key
  api_version?: "v1" | "v2"; // Optional: API version (default: "v1")
  base_url?: string;         // Optional: Base URL (internal use)
  timeout?: number;          // Optional: Request timeout in ms (default: 30000)
}

Configuration Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | api_key | string | ✅ Yes | - | Your Meeting BaaS API key. Get yours at meetingbaas.com | | api_version | "v1" \| "v2" | ❌ No | "v1" | API version to use. Use "v2" for the new Meeting BaaS v2 API | | timeout | number | ❌ No | 30000 | Request timeout in milliseconds. Some requests may take longer, so we recommend setting a longer timeout if you notice timeouts |

Migration from v4.x

If you're upgrading from v4.x, see MIGRATION.md for detailed migration instructions.

Contributing

We welcome contributions! Please see DEVELOPMENT.md for development guidelines.

License

MIT