Pixie Apps SDK

SDK for building Pixie Apps that work with both OpenAI Apps and MCP Apps platforms.

Installation

npm install pixie-apps-sdk

Quick Start

Simply import the SDK in your widget code, and window.pixie will be automatically available:

import'pixie-apps-sdk';

That's it! The SDK automatically detects the platform (OpenAI Apps or MCP Apps) and initializes window.pixie accordingly.

Usage

Once imported, you can use window.pixie throughout your application:

React Hooks

The SDK provides React hooks for accessing tool data and UI state:

functionMyWidget(){// Tool dataconsttoolInput=window.pixie.useToolInput();consttoolOutput=window.pixie.useToolOutput();consttoolResponseMetadata=window.pixie.useToolResponseMetadata();// UI stateconsttheme=window.pixie.useTheme();// "light" | "dark"constdisplayMode=window.pixie.useDisplayMode();// "pip" | "inline" | "fullscreen"constmaxHeight=window.pixie.useMaxHeight();constsafeArea=window.pixie.useSafeArea();constuserAgent=window.pixie.useUserAgent();constlocale=window.pixie.useLocale();// Widget state (persistent across renders)constwidgetState=window.pixie.getWidgetState();window.pixie.setWidgetState({myData: 'value'});return<div>MyWidget</div>;}

Actions

// Call a toolconstresult=awaitwindow.pixie.callTool('tool-name',{arg1: 'value'});// Send a follow-up messagewindow.pixie.sendFollowupMessage('Can you show me more items?');// Open external linkwindow.pixie.openExternal('https://example.com');// Request display mode changewindow.pixie.requestDisplayMode('fullscreen');// Request modalconstmodalResult=awaitwindow.pixie.requestModal({title: 'My Modal',params: {message: 'Hello'}});// Request to close widgetawaitwindow.pixie.requestClose();

TypeScript Support

The SDK includes full TypeScript definitions. Import types as needed:

importtype{Provider,WidgetState,Theme,DisplayMode}from'pixie-apps-sdk';declare global {interfaceWindow{pixie: Provider;}}

Complete Example

import{useEffect,useState}from'react';import'pixie-apps-sdk';typeMyPayload={items?: Array<{name: string;price: number}>;};functionShoppingWidget(){consttoolOutput=window.pixie.useToolOutput()asMyPayload|null;consttheme=window.pixie.useTheme();const[cart,setCart]=useState<string[]>([]);useEffect(()=>{if(toolOutput?.items){// Process tool outputconsole.log('Received items:',toolOutput.items);}},[toolOutput]);consthandleAddToCart=(itemName: string)=>{setCart([...cart,itemName]);// Persist statewindow.pixie.setWidgetState({ cart });};consthandleCheckout=()=>{window.pixie.openExternal('https://checkout.example.com');};return(<divstyle={{background: theme==='dark' ? '#000' : '#fff',color: theme==='dark' ? '#fff' : '#000'}}><h1>MyShoppingWidget</h1>{toolOutput?.items?.map(item=>(<divkey={item.name}><span>{item.name}-${item.price}</span><buttononClick={()=>handleAddToCart(item.name)}>AddtoCart</button></div>))}<buttononClick={handleCheckout}>Checkout</button></div>);}

API Reference

Hooks

All hooks are React hooks that automatically re-render when values change.

• useToolInput() - Get the tool input data
• useToolOutput() - Get the tool output data
• useToolResponseMetadata() - Get tool response metadata
• useTheme() - Get current theme ("light" | "dark")
• useDisplayMode() - Get current display mode ("pip" | "inline" | "fullscreen")
• useMaxHeight() - Get maximum widget height
• useSafeArea() - Get safe area insets
• useUserAgent() - Get user agent information
• useLocale() - Get current locale string

State Management

• getWidgetState() - Get current widget state (persistent)
• setWidgetState(state) - Update widget state

Actions

• callTool(name, args?) - Call a tool and return result
• sendFollowupMessage(message) - Send a follow-up message to the assistant
• openExternal(href) - Open an external URL
• requestDisplayMode(mode) - Request a display mode change
• requestModal(args) - Request a modal dialog
• requestClose() - Request to close the widget

Platform Support

The SDK automatically detects and works with:

• OpenAI Apps - Uses window.openai API
• MCP Apps - Uses MCP Apps protocol

No configuration needed - just import and use!

Requirements

• React 18+ (peer dependency)
• React DOM 18+ (peer dependency)

License

See LICENSE file for details.