SDK Overview

@flapjack/sdk is the TypeScript SDK for embedding Flapjack agents in your product. It includes a client for programmatic access and React hooks for building chat UIs.

Installation

npm install @flapjack/sdk

📋 Copy as prompt

Install the Flapjack SDK: npm install @flapjack/sdk

Package Exports

Import Path	What It Provides
@flapjack/sdk	FlapjackClient, all TypeScript types
@flapjack/sdk/react	FlapjackProvider, useChat, usePlan hooks
@flapjack/sdk/components	Pre-built UI: ChatPanel, FloatingChat, PlanPanel, and more

Configuration

import { FlapjackClient } from '@flapjack/sdk';

const client = new FlapjackClient({
  apiKey: process.env.FLAPJACK_API_KEY!,
  baseUrl: process.env.FLAPJACK_BASE_URL, // optional
});

📋 Copy as prompt

Create a FlapjackClient instance using my API key from the FLAPJACK_API_KEY environment variable.

FlapjackConfig

Field	Type	Required	Default	Description
apiKey	string	Yes	—	Your API key (fj_live_...)
baseUrl	string	No	https://api.flapjack.dev	API base URL

type FlapjackConfig = {
  apiKey: string;
  baseUrl?: string;
};

Error Handling

SDK methods throw standard Error objects on failure. The error message contains the error code from the API:

try {
  const agents = await client.listAgents();
} catch (error) {
  console.error('Failed:', error.message);
  // e.g., "UNAUTHORIZED", "NOT_FOUND", "HTTP 500"
}

For streaming (sendMessage), errors are yielded as events instead of thrown:

for await (const event of client.sendMessage(threadId, 'Hello')) {
  if (event.type === 'error') {
    console.error('Stream error:', event.code, event.detail);
  }
}

📋 Copy as prompt

Add error handling to my Flapjack SDK calls. Wrap non-streaming methods in try/catch, and check for error events in the sendMessage stream.

TypeScript Types

All types are exported from @flapjack/sdk:

import type {
  Agent,
  Thread,
  Message,
  ChatEvent,
  KnowledgeDoc,
  FlapjackConfig,
  // Tool types
  ToolDef,
  ToolCall,
  ToolResult,
  // Feature configs
  WebConfig,
  MemoryConfig,
  PlanConfig,
  ComputerConfig,
  // Plans
  Plan,
  PlanTodo,
  // MCP & Integrations
  McpServer,
  Integration,
  AgentMcp,
  AgentIntegration,
  // Analytics
  AnalyticsResult,
  // Multiplayer
  MultiplayerConfig,
  ThreadParticipant,
  // Marketplace
  MarketplaceProfile,
  MarketplaceCapability,
  // Runners
  Runner,
  RunnerStep,
  RunnerTrigger,
  RunnerRun,
  RunnerAnalytics,
} from '@flapjack/sdk';

See SDK: Client for full type definitions.

Sections

• Client Reference — all FlapjackClient methods
• React Hooks — FlapjackProvider, useChat, usePlan, and pre-built components
• Server Proxy — production security pattern
• Examples — end-to-end use cases