Documentation
Getting Started

Quickstart: SDK

Install @maats/flapjack and stream your first AI agent response in 10 lines of TypeScript.

Install the TypeScript SDK and send your first streaming message to a Flapjack agent.

Time: 5 minutes Prerequisites: Node.js 18+, a Flapjack account with an API key and agent

Step 1: Install

npm install @maats/flapjack
📋 Copy as prompt

Install the Flapjack SDK: npm install @maats/flapjack

Step 2: Set Environment Variables

# .env or .env.local
FLAPJACK_API_KEY=fj_live_...          # from flapjack.chat → Keys
FLAPJACK_BASE_URL=https://api.flapjack.dev

Step 3: Stream Your First Message

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

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

// List your agents
const agents = await client.listAgents();
console.log('Agents:', agents.map(a => a.name));

if (agents.length === 0) {
  console.error('No agents found. Create one at flapjack.chat');
  process.exit(1);
}

// Create a conversation thread
const thread = await client.createThread(agents[0].id);

// Send a message and stream the response
for await (const event of client.sendMessage(thread.id, 'Hello!')) {
  switch (event.type) {
    case 'token':
      process.stdout.write(event.delta);
      break;
    case 'tool_call':
      console.log('\n[Tool]', event.tool.name);
      break;
    case 'done':
      console.log('\n\nDone. Message ID:', event.messageId);
      break;
    case 'error':
      console.error('Error:', event.code, event.detail);
      break;
  }
}
📋 Copy as prompt

Create a TypeScript script that uses @maats/flapjack to list my agents, create a thread with the first agent, send "Hello!", and stream the response to stdout. Use FlapjackClient with my API key from the FLAPJACK_API_KEY environment variable.

Step 4: Add React (Optional)

If you're building a React app, use the built-in hooks:

Security warning: The example below uses NEXT_PUBLIC_ environment variables for simplicity. This exposes your API key in the client bundle. For production, use the server proxy pattern instead.

import { FlapjackProvider, useChat } from '@maats/flapjack/react';

function App() {
  return (
    <FlapjackProvider config={{
      apiKey: process.env.NEXT_PUBLIC_FLAPJACK_API_KEY!, // ⚠️ Dev only — use server proxy in production
      baseUrl: process.env.NEXT_PUBLIC_FLAPJACK_BASE_URL,
    }}>
      <Chat agentId="your-agent-id" />
    </FlapjackProvider>
  );
}

function Chat({ agentId }: { agentId: string }) {
  const { messages, sendMessage, isStreaming } = useChat(agentId);

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i}>{msg.role}: {msg.content}</div>
      ))}
      {isStreaming && <div>Thinking...</div>}
      <input
        onKeyDown={(e) => {
          if (e.key === 'Enter') {
            sendMessage(e.currentTarget.value);
            e.currentTarget.value = '';
          }
        }}
        disabled={isStreaming}
        placeholder="Type a message..."
      />
    </div>
  );
}
📋 Copy as prompt

Set up Flapjack React hooks in my app. Wrap the app with FlapjackProvider using my API key from environment variables, then create a Chat component using the useChat hook that shows messages, a streaming indicator, and an input field.

What's Happening

  1. FlapjackClient authenticates with your API key and sends requests to the Flapjack API
  2. createThread starts a new conversation session for the specified agent
  3. sendMessage sends a user message and returns an async generator of SSE events
  4. The agent processes the message, optionally calls tools, and streams text tokens back
  5. The done event contains the full final response and a persisted messageId

Next Steps

Docs last updated May 11, 2026