botdojo-sdk-types

Shared TypeScript type definitions for BotDojo SDK and Canvas Client.

Purpose

This package contains pure TypeScript type definitions with no JSX or React dependencies. It provides common types used across:

• @botdojo/sdk - BotDojo SDK for running flows via API
• botdojo-canvas-client - Canvas client with React components
• Other BotDojo packages

Why a Separate Package?

By separating types into their own package, we avoid requiring JSX configuration in projects that only need type definitions. This makes it easier to use BotDojo types in any TypeScript project.

Installation

npm install botdojo-sdk-types
# or
pnpm add botdojo-sdk-types

Usage

import type { ModelContext, ToolDefinition, ToolResponse } from 'botdojo-sdk-types';

const myContext: ModelContext = {
  name: 'my-tools',
  description: 'My custom tools',
  tools: [
    {
      name: 'getThing',
      description: 'Gets a thing',
      inputSchema: {
        type: 'object',
        properties: {
          id: { type: 'string' }
        }
      }
    }
  ]
};

Exported Types

Core Types

• ModelContext - Model context definition
• ToolDefinition - Tool definition with parameters
• ToolResponse - Rich tool response with actions
• ToolResponseAction - Actions that can be performed
• ConnectorToolCalls - Tool handler functions

Legacy/Deprecated Types

• CanvasModelContext - Use ModelContext instead
• CanvasModelContextTool - Use ToolDefinition instead
• MCPModelContext - Use ModelContext instead
• MCPToolHandlers - Use ConnectorToolCalls instead

Flow Types

• FlowRequestOptions - Options for flow requests
• FlowRequestBody - Flow request body
• FlowResponse - Flow response data

Build-Time Sync Mechanism

This package uses a build-time sync approach to avoid circular dependencies while keeping implementations in sync with botdojo-core.

What Gets Synced

1. Backend Type Validation (backend-types-snapshot.ts)

   • Synced from botdojo-sdk-backend-types
   • Used for type validation only
   • No runtime dependency

2. Tool Response Mapper (toolResponseMapper-snapshot.ts)

   • Synced from botdojo-core/src/utils/toolResponseMapper.ts
   • Converts SDK ToolResponse format to backend IToolResponse format
   • Single source of truth in botdojo-core

How It Works

During Build:

# prebuild hook automatically runs before build
pnpm build  # Internally: sync-backend-types → sync-tool-response-mapper → tsc

During Development:

# dev mode syncs once, then watches for changes
pnpm dev  # Internally: sync → (watch-tool-response-mapper & tsc --watch)

The file watcher automatically re-syncs when botdojo-core/src/utils/toolResponseMapper.ts changes during development.

Manual Sync

If you need to manually sync:

pnpm sync-backend-types          # Sync backend types
pnpm sync-tool-response-mapper   # Sync tool response mapper

Build Order Requirements

For CI/CD or fresh builds:

# Correct order:
pnpm --filter botdojo-core build              # 1. Core types and utils
pnpm --filter botdojo-sdk-backend-types build # 2. Backend type exports
pnpm --filter @botdojo/sdk-types build        # 3. SDK types (syncs during prebuild)

The workspace build system (Turbo) handles this automatically via dependency order.

Why This Approach?

• ✅ Avoids circular dependencies - No runtime dependency on botdojo-core
• ✅ Single source of truth - Logic lives in botdojo-core
• ✅ Type safety - Still validates against backend types
• ✅ Dev experience - Auto-syncs during development
• ✅ Simple - Just build scripts, no complex tooling

See BACKEND_TYPES.md for more details on the architecture.

License

MIT