Pixie Apps SDK


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

Installation

``bash
npm install pixie-apps-sdk
`

Quick Start

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

`typescript
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:

$3

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

`typescript
function MyWidget() {
// Tool data
const toolInput = window.pixie.useToolInput();
const toolOutput = window.pixie.useToolOutput();
const toolResponseMetadata = window.pixie.useToolResponseMetadata();

// UI state
const theme = window.pixie.useTheme(); // "light" | "dark"
const displayMode = window.pixie.useDisplayMode(); // "pip" | "inline" | "fullscreen"
const maxHeight = window.pixie.useMaxHeight();
const safeArea = window.pixie.useSafeArea();
const userAgent = window.pixie.useUserAgent();
const locale = window.pixie.useLocale();

// Widget state (persistent across renders)
const widgetState = window.pixie.getWidgetState();
window.pixie.setWidgetState({ myData: 'value' });

return

`typescript
// Call a tool
const result = await window.pixie.callTool('tool-name', { arg1: 'value' });

// Send a follow-up message
window.pixie.sendFollowupMessage('Can you show me more items?');

// Open external link
window.pixie.openExternal('https://example.com');

// Request display mode change
window.pixie.requestDisplayMode('fullscreen');

// Request modal
const modalResult = await window.pixie.requestModal({
title: 'My Modal',
params: { message: 'Hello' }
});

// Request to close widget
await window.pixie.requestClose();
`

TypeScript Support

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

`typescript
import type { Provider, WidgetState, Theme, DisplayMode } from 'pixie-apps-sdk';

declare global {
interface Window {
pixie: Provider;
}
}
`

Complete Example

`typescript
import { useEffect, useState } from 'react';
import 'pixie-apps-sdk';

type MyPayload = {
items?: Array<{ name: string; price: number }>;
};

function ShoppingWidget() {
const toolOutput = window.pixie.useToolOutput() as MyPayload | null;
const theme = window.pixie.useTheme();
const [cart, setCart] = useState([]);

useEffect(() => {
if (toolOutput?.items) {
// Process tool output
console.log('Received items:', toolOutput.items);
}
}, [toolOutput]);

const handleAddToCart = (itemName: string) => {
setCart([...cart, itemName]);
// Persist state
window.pixie.setWidgetState({ cart });
};

const handleCheckout = () => {
window.pixie.openExternal('https://checkout.example.com');
};

return (


- 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

$3

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

$3

- 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.