API Reference

Complete API reference for PancakeJS packages.

Server API

createUniversalServerApp

Creates a new PancakeJS application instance.

import { createUniversalServerApp } from '@pancakeapps/server';

const app = createUniversalServerApp({
  name: string;          // App name
  version: string;       // Semantic version
  description?: string;  // Optional description
});

app.tool

app.tool(
  {
    name: string;                    // Unique tool identifier
    description: string;             // Description for AI
    inputSchema: ZodSchema;          // Zod schema for input validation
  },
  handler: (input: T) => Promise<ToolResult>
);

app.widget

app.widget(
  {
    name: string;
    description: string;
    inputSchema: ZodSchema;
    ui: {
      entry: string;               // Path to widget entry file
      csp?: {
        connectDomains?: string[]; // Allowed API domains
        imgDomains?: string[];     // Allowed image domains
        scriptDomains?: string[];  // Allowed script domains
        styleDomains?: string[];   // Allowed style domains
      };
    };
  },
  handler: (input: T) => Promise<WidgetResult>
);

app.adapter

app.adapter(adapter: Adapter);

app.listen

Start the server.

app.listen({
  port?: number;       // Default: 3000
  dev?: boolean;       // Enable development mode
  host?: string;       // Bind address
});

Result Builders

textResult

Create a text-only response.

import { textResult } from '@pancakeapps/server';

return textResult('Hello, world!');

htmlResult

Create an HTML response.

import { htmlResult } from '@pancakeapps/server';

return htmlResult('<strong>Hello!</strong>');

withData

Attach structured data to a result.

import { textResult, withData } from '@pancakeapps/server';

return withData(
  textResult('Found 10 items'),
  { items: [...], total: 10 }
);

result (Builder)

Fluent builder for complex results.

import { result } from '@pancakeapps/server';

return result()
  .text('Primary message')
  .html('<em>Rich content</em>')
  .data({ key: 'value' })
  .build();

renderWidget

Render a widget with initial data.

import { renderWidget } from '@pancakeapps/server';

return renderWidget('widgetName', {
  content?: Content[];  // Optional text/HTML content
  data: object;         // Data passed to widget
});

React Hooks

UniversalAppProvider

Root provider for widgets.

import { UniversalAppProvider } from '@pancakeapps/react';

<UniversalAppProvider
  fallback?: ReactNode;              // Loading state
  strict?: boolean;                  // Throw on unsupported features
  adapter?: () => UiAdapter;         // Override adapter detection
  errorFallback?: (error) => ReactNode;  // Error state
>
  {children}
</UniversalAppProvider>

useToolInvocation

Access the tool invocation data.

import { useToolInvocation } from '@pancakeapps/react';

function Widget() {
  const { data, input } = useToolInvocation<{
    data: MyDataType;
    input: MyInputType;
  }>();
  
  // data: Initial data from renderWidget
  // input: Original tool input
}

useWidgetState

Persist state across renders.

import { useWidgetState } from '@pancakeapps/react';

function Widget() {
  const [count, setCount] = useWidgetState<number>('count', 0);
  // Key 'count' is used for persistence
}

useCallTool

Call other tools from a widget.

import { useCallTool } from '@pancakeapps/react';

function Widget() {
  const fetchData = useCallTool('fetchData');
  
  const handleClick = async () => {
    const result = await fetchData({ query: 'test' });
  };
}

useHost

Access host information and capabilities.

import { useHost } from '@pancakeapps/react';

function Widget() {
  const host = useHost();
  
  // host.id: 'mcp-apps' | 'chatgpt'
  // host.capabilities: { followups, theme, locale, ... }
  // host.context: { theme, locale }
}

useFollowUp

Send follow-up prompts.

import { useFollowUp } from '@pancakeapps/react';

function Widget() {
  const followUp = useFollowUp();
  
  if (followUp.supported) {
    await followUp.send('Tell me more about this');
  }
}

useTheme

Get current theme.

import { useTheme } from '@pancakeapps/react';

function Widget() {
  const theme = useTheme('light'); // Default value
  // theme: 'light' | 'dark'
}

useLocale

Get user's locale.

import { useLocale } from '@pancakeapps/react';

function Widget() {
  const locale = useLocale('en'); // Default value
  // locale: string (e.g., 'en-US')
}

useCapability

Check if a capability is available.

import { useCapability } from '@pancakeapps/react';

function Widget() {
  const hasFollowups = useCapability('followups');
  // hasFollowups: boolean
}

Adapter APIs

MCP Apps Adapter

import { createMcpAppsServerAdapter } from '@pancakeapps/adapter-mcp-apps';

const adapter = createMcpAppsServerAdapter({
  debug?: boolean;    // Enable debug logging
});

import { createMcpAppsUiAdapter } from '@pancakeapps/adapter-mcp-apps';

const adapter = createMcpAppsUiAdapter({
  debug?: boolean;    // Enable debug logging
  timeout?: number;   // Request timeout (ms)
});

ChatGPT Apps Adapter

import { createChatGptServerAdapter } from '@pancakeapps/adapter-chatgpt-apps';

const adapter = createChatGptServerAdapter({
  debug?: boolean;    // Enable debug logging
});

import { createChatGptUiAdapter } from '@pancakeapps/adapter-chatgpt-apps';

const adapter = createChatGptUiAdapter({
  debug?: boolean;    // Enable debug logging
});

Type Definitions

ToolDefinition

interface ToolDefinition<T = unknown> {
  name: string;
  description: string;
  inputSchema: ZodSchema<T>;
}

WidgetDefinition

interface WidgetDefinition<T = unknown> extends ToolDefinition<T> {
  ui: {
    entry: string;
    csp?: CSPConfig;
  };
}

ToolResult

interface ToolResult {
  content: Content[];
  data?: unknown;
}

Content

type Content = 
  | { type: 'text'; text: string }
  | { type: 'html'; html: string };

Host

interface Host {
  id: string;
  capabilities: Capabilities;
  context: HostContext;
}

Capabilities

interface Capabilities {
  followups: boolean;
  modals: boolean;
  files: boolean;
  theme: boolean;
  locale: boolean;
  persistentState: boolean;
}

On this page