💡 Feature Request: Export ChatGPT Apps SDK Type Definitions

[JakeLin]

Description

Every developer using AINativeKit for ChatGPT Apps must manually define the Window.openai interface. This should be exported by the library.

Current Developer Experience

Developers must copy-paste this in every project:

// Every project needs this boilerplate
declare global {
  interface Window {
    openai?: {
      toolOutput?: string;
      theme?: 'light' | 'dark';
      displayMode?: 'inline' | 'pip' | 'fullscreen';
      widgetState?: any;
      setWidgetState?: (state: any) => void;
      callTool?: (name: string, args: any) => Promise<any>;
      sendFollowUpMessage?: (message: { prompt: string }) => void;
    };
  }
}

Proposed Solution

Create: packages/ui/src/types/global.d.ts

/**
 * Global type definitions for ChatGPT Apps SDK
 * Auto-loaded when importing @ainativekit/ui
 */

export interface OpenAIGlobal {
  /**
   * Tool output data from MCP response
   * Parse with JSON.parse(window.openai.toolOutput)
   */
  toolOutput?: string;

  /**
   * Current theme mode
   */
  theme?: 'light' | 'dark';

  /**
   * Current display mode
   */
  displayMode?: 'inline' | 'pip' | 'fullscreen';

  /**
   * Persistent widget state
   */
  widgetState?: Record<string, any>;

  /**
   * Update widget state
   */
  setWidgetState?: (state: Record<string, any>) => void;

  /**
   * Call an MCP tool
   */
  callTool?: (name: string, args: Record<string, any>) => Promise<any>;

  /**
   * Send follow-up message
   */
  sendFollowUpMessage?: (message: { prompt: string }) => void;
}

declare global {
  interface Window {
    /**
     * ChatGPT Apps SDK global
     */
    openai?: OpenAIGlobal;
  }
}

export {};

Update: packages/ui/src/index.ts

// Export types
export * from './types/global';
export type { OpenAIGlobal } from './types/global';

Developer Experience After Fix

// Just import the package
import '@ainativekit/ui';

// TypeScript automatically knows about window.openai
const data = window.openai?.toolOutput; // ✅ Fully typed!
const theme = window.openai?.theme; // ✅ 'light' | 'dark' | undefined

Benefits

• ✅ Zero boilerplate for developers
• ✅ Full TypeScript autocomplete
• ✅ Centralized maintenance
• ✅ Consistent types across all ChatGPT apps
• ✅ Auto-syncs with OpenAI SDK updates

Files to Create/Modify

• Create: packages/ui/src/types/global.d.ts
• Update: packages/ui/src/index.ts
• Update: packages/ui/package.json (exports field)

Testing

// Test autocomplete works
import '@ainativekit/ui';

window.openai?.theme // Should show: 'light' | 'dark' | undefined
window.openai?.callTool // Should show function signature

Priority

🟡 Medium - Significant DX improvement

Labels

enhancement, types, dx, chatgpt-apps

[JakeLin]

Feature Request #3 - Complete! I've documented the ChatGPT Apps SDK TypeScript type definitions that AINativeKit UI already exports. The library was already providing comprehensive types - developers just didn't know about them.

What Was Done

Documentation Added:

• Added "📘 TypeScript Support" section to both README.md and packages/ui/README.md
• Documented zero-boilerplate usage with clear examples
• Listed all exported types with descriptions
• Showed autocomplete examples for window.openai

Developer Experience Now

import '@ainativekit/ui';

// Full TypeScript autocomplete! ✨
const theme = window.openai?.theme; // 'light' | 'dark' | undefined
window.openai?.callTool('get_weather', { location: 'SF' });