@meeting-baas/sdk - v1 API Reference / v1-getting-started

Getting Started with v1 API

This guide will help you get started with the Meeting BaaS v1 API using the SDK.

Installation

npm install @meeting-baas/sdk

Quick Start

Creating a Client

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

// v1 is the default API version
const client = createBaasClient({
  api_key: "your-api-key"
});

// Or explicitly specify v1
const client = createBaasClient({
  api_key: "your-api-key",
  api_version: "v1"
});

Joining Your First Meeting

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

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

Core Concepts

Response Structure

All v1 API methods return a discriminated union:

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

This enables type-safe error handling:

const result = await client.joinMeeting({ ... });

if (result.success) {
  // TypeScript knows result.data exists
  console.log(result.data.bot_id);
} else {
  // TypeScript knows result.error exists
  console.error(result.error);
}

Parameter Validation

All parameters are automatically validated using Zod schemas:

const result = await client.joinMeeting({
  meeting_url: "invalid-url", // Will fail validation
  bot_name: "Test Bot",
  reserved: false
});

if (!result.success) {
  if (result.error instanceof ZodError) {
    console.error("Validation errors:", result.error.errors);
  }
}

Common Operations

Bot Lifecycle

// 1. Join a meeting
const joinResult = await client.joinMeeting({
  meeting_url: "https://meet.google.com/abc-def-ghi",
  bot_name: "Meeting Bot",
  reserved: true
});

if (!joinResult.success) return;
const botId = joinResult.data.bot_id;

// 2. Check bot status
const statusResult = await client.getMeetingData({
  bot_id: botId
});

if (statusResult.success) {
  console.log("Status:", statusResult.data.status_changes);
}

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

// 4. Delete bot data (optional)
await client.deleteBotData({
  uuid: botId
});

Advanced Bot Configuration

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

  // Optional: Custom bot image
  bot_image: "https://example.com/bot-avatar.jpg",

  // Optional: Entry message
  enter_message: "Hello! I'm recording this meeting.",

  // Optional: Recording preferences
  recording_mode: "speaker_view",

  // Optional: Transcription provider
  speech_to_text: {
    provider: "Gladia"
  },

  // Optional: Webhook for notifications
  webhook_url: "https://your-server.com/webhooks",

  // Optional: Custom metadata
  extra: {
    meeting_id: "internal-123",
    user_id: "user-456"
  }
});

Calendar Integration

Connecting a Calendar

const result = 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 (result.success) {
  console.log("Calendar connected:", result.data.calendar.uuid);
}

Listing Calendar Events

const calendarsResult = await client.listCalendars();

if (calendarsResult.success) {
  for (const calendar of calendarsResult.data.calendars) {
    const eventsResult = await client.listCalendarEvents({
      calendar_id: 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 for ${calendar.uuid}:`, eventsResult.data.events);
    }
  }
}

Error Handling

Validation Errors

import { ZodError } from "zod";

const result = await client.joinMeeting({
  meeting_url: "invalid",
  bot_name: "Test",
  reserved: false
});

if (!result.success && result.error instanceof ZodError) {
  console.error("Validation failed:");
  result.error.errors.forEach(err => {
    console.error(`  ${err.path.join(".")}: ${err.message}`);
  });
}

API Errors

const result = await client.joinMeeting({ ... });

if (!result.success && !(result.error instanceof ZodError)) {
  // Regular Error from API
  console.error("API error:", result.error.message);

  // Check for specific error messages
  if (result.error.message.includes("rate limit")) {
    console.log("Rate limited, please retry later");
  }
}

Best Practices

Always check success first: Leverage TypeScript's type narrowing
Handle both validation and API errors: Check if error is ZodError
Reuse the client: Create one instance and reuse it
Set appropriate timeouts: Some operations may take time
Clean up resources: Delete bot data when no longer needed

Complete Example

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

const client = createBaasClient({
  api_key: process.env.MEETING_BAAS_API_KEY!,
  timeout: 60000
});

async function recordMeeting(meetingUrl: string) {
  try {
    // Join meeting
    const joinResult = await client.joinMeeting({
      meeting_url: meetingUrl,
      bot_name: "Recording Bot",
      reserved: true,
      recording_mode: "gallery_view",
      speech_to_text: { provider: "Gladia" }
    });

    if (!joinResult.success) {
      if (joinResult.error instanceof ZodError) {
        console.error("Invalid parameters:", joinResult.error.errors);
      } else {
        console.error("Failed to join:", joinResult.error.message);
      }
      return;
    }

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

    // Wait for meeting to complete (in production, use webhooks)
    await new Promise(resolve => setTimeout(resolve, 3600000)); // 1 hour

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

    if (dataResult.success) {
      console.log("Recording URL:", dataResult.data.mp4);
      console.log("Transcript available:", !!dataResult.data.transcript);

      // Process transcript
      if (dataResult.data.transcript) {
        console.log("Transcript segments:", dataResult.data.transcript.length);
      }
    }

  } catch (error) {
    console.error("Unexpected error:", error);
  }
}

recordMeeting("https://meet.google.com/abc-def-ghi");

Next Steps

Learn about Error Handling
Understand Best Practices
Consider Migrating to v2

Getting Started with v1 API

On this page