skybridge 0.0.0-dev.d8b52a9 → 0.0.0-dev.d91f2cb

package/dist/{src/web → web}/types.d.ts

@@ -1,4 +1,20 @@
+import "react";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { WidgetHostType } from "../server/index.js";
+declare module "react" {
+    interface HTMLAttributes<T> {
+        "data-llm"?: string;
+    }
+}
 export type UnknownObject = Record<string, unknown>;
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type Objectify<T> = T & UnknownObject;
+type RequiredKeys<T> = {
+    [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
+}[keyof T];
+export type HasRequiredKeys<T> = RequiredKeys<T> extends never ? false : true;
 type WidgetState = UnknownObject;
 type FileMetadata = {
     fileId: string;
@@ -14,19 +30,24 @@ export declare class ToolResponseEvent extends CustomEvent<{
 }
 declare global {
     interface Window {
-        openai: API<WidgetState> & OpenAiGlobals;
+        skybridge: SkybridgeProperties;
+        openai: OpenAiMethods<WidgetState> & OpenAiProperties;
     }
     interface WindowEventMap {
         [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;
     }
 }
-export type OpenAiGlobals<ToolInput extends UnknownObject = {}, ToolOutput extends UnknownObject = UnknownObject, ToolResponseMetadata extends UnknownObject = UnknownObject, WidgetState extends UnknownObject = UnknownObject> = {
+export type SkybridgeProperties = {
+    hostType: WidgetHostType;
+};
+export type OpenAiProperties<ToolInput extends UnknownObject = Record<never, unknown>, ToolOutput extends UnknownObject = UnknownObject, ToolResponseMetadata extends UnknownObject = UnknownObject, WidgetState extends UnknownObject = UnknownObject> = {
     theme: Theme;
     userAgent: UserAgent;
     locale: string;
     maxHeight: number;
     displayMode: DisplayMode;
     safeArea: SafeArea;
+    view: View;
     toolInput: ToolInput;
     toolOutput: ToolOutput | {
         text: string;
@@ -36,16 +57,23 @@ export type OpenAiGlobals<ToolInput extends UnknownObject = {}, ToolOutput exten
 };
 export type CallToolArgs = Record<string, unknown> | null;
 export type CallToolResponse = {
-    content: {
-        type: "text";
-        text: string;
-    }[];
+    content: CallToolResult["content"];
     structuredContent: Record<string, unknown>;
     isError: boolean;
     result: string;
-    meta: Record<string, unknown>;
+    _meta?: CallToolResult["_meta"];
 };
-type API<WidgetState extends UnknownObject> = {
+export type RequestModalOptions = {
+    title?: string;
+    params?: Record<string, unknown>;
+    anchor?: {
+        top?: number;
+        left?: number;
+        width?: number;
+        height?: number;
+    };
+};
+export type OpenAiMethods<WidgetState extends UnknownObject = UnknownObject> = {
     /** Calls a tool on your MCP. Returns the full response. */
     callTool: <ToolArgs extends CallToolArgs = null, ToolResponse extends CallToolResponse = CallToolResponse>(name: string, args: ToolArgs) => Promise<ToolResponse>;
     /** Triggers a followup turn in the ChatGPT conversation */
@@ -75,9 +103,7 @@ type API<WidgetState extends UnknownObject> = {
      * Opens a modal portaled outside of the widget iFrame.
      * This ensures the modal is correctly displayed and not limited to the widget's area.
      */
-    requestModal: (args: {
-        title: string;
-    }) => Promise<void>;
+    requestModal: (args: RequestModalOptions) => Promise<void>;
     /** Uploads a new file to the host */
     uploadFile: (file: File) => Promise<FileMetadata>;
     /**
@@ -90,12 +116,16 @@ type API<WidgetState extends UnknownObject> = {
 };
 export declare const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
 export declare class SetGlobalsEvent extends CustomEvent<{
-    globals: Partial<OpenAiGlobals>;
+    globals: Partial<OpenAiProperties>;
 }> {
     readonly type = "openai:set_globals";
 }
 export type CallTool = (name: string, args: Record<string, unknown>) => Promise<CallToolResponse>;
-export type DisplayMode = "pip" | "inline" | "fullscreen";
+export type DisplayMode = "pip" | "inline" | "fullscreen" | "modal";
+export type View = {
+    mode: DisplayMode;
+    params?: Record<string, unknown>;
+};
 export type Theme = "light" | "dark";
 export type SafeAreaInsets = {
     top: number;

package/dist/{src/web → web}/types.js

@@ -1,3 +1,4 @@
+import "react";
 export const TOOL_RESPONSE_EVENT_TYPE = "openai:tool_response";
 export class ToolResponseEvent extends CustomEvent {
     type = TOOL_RESPONSE_EVENT_TYPE;

package/dist/web/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/web/types.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,CAAC;AAyBf,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAC/D,MAAM,OAAO,iBAAkB,SAAQ,WAErC;IACkB,IAAI,GAAG,wBAAwB,CAAC;CACnD;AAuGD,sDAAsD;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAC3D,MAAM,OAAO,eAAgB,SAAQ,WAEnC;IACkB,IAAI,GAAG,sBAAsB,CAAC;CACjD"}

package/package.json

@@ -1,31 +1,25 @@
 {
   "name": "skybridge",
-  "version": "0.0.0-dev.d8b52a9",
+  "version": "0.0.0-dev.d91f2cb",
   "description": "Skybridge is a framework for building ChatGPT apps",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alpic-ai/skybridge.git"
+  },
   "type": "module",
   "files": [
     "dist"
   ],
   "exports": {
     "./server": {
-      "types": "./dist/src/server/index.d.ts",
-      "default": "./dist/src/server/index.js"
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
     },
     "./web": {
-      "types": "./dist/src/web/index.d.ts",
-      "default": "./dist/src/web/index.js"
+      "types": "./dist/web/index.d.ts",
+      "default": "./dist/web/index.js"
     }
   },
-  "scripts": {
-    "build": "tsc && pnpm run build:templates",
-    "build:templates": "cp -r src/server/templates dist/src/server/",
-    "test": "pnpm run test:unit && pnpm run test:type",
-    "test:unit": "vitest run --silent",
-    "test:type": "tsc --noEmit",
-    "docs:dev": "pnpm --filter @skybridge/docs start",
-    "docs:build": "pnpm --filter @skybridge/docs build",
-    "docs:serve": "pnpm --filter @skybridge/docs serve"
-  },
   "keywords": [
     "chatgpt",
     "app",
@@ -35,31 +29,61 @@
   "author": "Frédéric Barthelet",
   "license": "ISC",
   "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.0",
+    "@babel/core": "^7.28.5",
+    "@oclif/core": "^4.8.0",
     "cors": "^2.8.5",
-    "express": "^5.1.0",
+    "dequal": "^2.0.3",
+    "es-toolkit": "^1.43.0",
+    "express": "^5.2.1",
     "handlebars": "^4.7.8",
-    "vite": "^7.1.11",
-    "zod": "^3.25.51"
+    "ink": "^6.6.0",
+    "superjson": "^2.2.6",
+    "vite": "^7.3.1",
+    "zustand": "^5.0.9"
   },
   "devDependencies": {
+    "@modelcontextprotocol/ext-apps": "^0.2.2",
+    "@modelcontextprotocol/sdk": "^1.25.2",
     "@testing-library/dom": "^10.4.1",
-    "@testing-library/react": "^16.3.0",
+    "@testing-library/react": "^16.3.1",
     "@total-typescript/tsconfig": "^1.0.4",
+    "@types/babel__core": "^7.20.5",
     "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.3",
-    "@types/jsdom": "^21.1.6",
-    "@types/node": "^22.15.30",
-    "@types/react": "^19.2.2",
-    "@types/react-dom": "^19.2.2",
-    "@vitest/ui": "^2.1.8",
-    "jsdom": "^25.0.1",
+    "@types/express": "^5.0.6",
+    "@types/jsdom": "^27.0.0",
+    "@types/node": "^24.10.4",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/ui": "^4.0.16",
+    "jsdom": "^27.4.0",
+    "shx": "^0.3.4",
+    "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.8"
+    "vitest": "^4.0.16",
+    "zod": "^4.3.5"
   },
-  "packageManager": "pnpm@10.17.1"
-}
+  "bin": {
+    "sb": "./bin/run.js",
+    "skybridge": "./bin/run.js"
+  },
+  "oclif": {
+    "bin": "skybridge",
+    "commands": "./dist/commands",
+    "dirname": "skybridge",
+    "topicSeparator": " "
+  },
+  "scripts": {
+    "build": "shx rm -rf dist && tsc && pnpm run build:templates",
+    "build:templates": "cp -r src/server/templates dist/server/",
+    "format": "biome check --write --error-on-warnings",
+    "test": "pnpm run test:unit && pnpm run test:type && pnpm run test:format",
+    "test:unit": "vitest run",
+    "test:type": "tsc --noEmit",
+    "test:format": "biome ci"
+  }
+}

package/README.md

@@ -1,323 +0,0 @@
-<div align="center">
-
-# Skybridge
-
-**Skybridge is the TypeScript framework for building ChatGPT apps**
-
-[![By Alpic](https://img.shields.io/badge/Made%20by%20Alpic-f6ffed?logo=alpic)](https://alpic.ai)
-
-![NPM Downloads](https://img.shields.io/npm/dm/skybridge?color=e90060)
-![NPM Version](https://img.shields.io/npm/v/skybridge?color=e90060)
-![GitHub License](https://img.shields.io/github/license/alpic-ai/skybridge?color=e90060)
-
-</div>
-
-Skybridge comes with 2 packages:
-
-- `skybridge/server`: A drop-in replacement of the `@modelcontextprotocol/sdk` official `McpServer` class with extra features for widget development.
-- `skybridge/web`: A react library with hooks and components to build widgets on the underlying _OpenAI iFrame skybridge_ runtime.
-
-## Quick start
-
-To get started in less than a minute, you can [create a new repository](https://github.com/new?template_name=apps-sdk-template&template_owner=alpic-ai) using our [ChatGPT SDK template](https://github.com/alpic-ai/apps-sdk-template). This template includes a basic setup for both the server and the widgets.
-
-## Installation
-
-```bash
-pnpm add skybridge
-```
-
-## Concepts
-
-### Widgets
-
-> A widget is a UI component that turns structured tool results into a human-friendly UI. Those are built using React components. They are rendered inside an iframe inline with the conversation on ChatGPT.
-
-Each widget in your app must have a unique name. The name is used to bridge the tool invocation result with the widget React component.
-
-For example, in order to register a new widget named `pokemon` on your ChatGPT app. You should have the following file structure and file contents:
-
-_Project structure_
-
-```
-server/
-└── src/
-    └── index.ts // Register the widget with McpServer.widget()
-web/
-└── src/
-    └── widgets/
-        └── pokemon.tsx // Use the same widget name as the file name
-```
-
-_server/src/index.ts_
-
-```ts
-import { McpServer } from "skybridge/server";
-
-const server = new McpServer();
-
-server.widget(
-  "pokemon"
-  // Remaining arguments...
-);
-```
-
-_web/src/widgets/pokemon.tsx_
-
-```ts
-import { mountWidget } from "skybridge/web";
-
-const Pokemon: React.FunctionComponent = () => {
-  // Your React component code goes here...
-};
-
-mountWidget(<Pokemon />);
-```
-
-## Packages
-
-### skybridge/server
-
-The `skybridge/server` package is a drop-in replacement of the `@modelcontextprotocol/sdk` official `McpServer` class with extra features for widget development. If you're already using the `@modelcontextprotocol/sdk`, you can simply replace your `McpServer` import with `skybridge/server` and you're good to go.
-
-### skybridge/web
-
-The `skybridge/web` package is a react library with hooks and components to build widgets on the underlying _OpenAI iFrame skybridge_ runtime.
-
-**Vite plugin**
-
-The `skybridge/web` package comes with a Vite plugin that allows you to build your widgets as regular Vite apps.
-
-```ts
-import { defineConfig } from "vite";
-import { skybridge } from "skybridge/web";
-
-export default defineConfig({
-  plugins: [skybridge()],
-});
-```
-
-**Typed Hooks**
-
-Skybridge provides fully typed hooks that give you autocomplete for tool names and type inference for inputs/outputs - similar to tRPC. This is opt-in and requires exporting your server type.
-
-> **Tip:** For the best TypeScript experience, use typed hooks throughout your application. They provide autocomplete, type safety, and better IDE support.
-
-_Server setup (server/src/index.ts)_
-
-```ts
-import { McpServer } from "skybridge/server";
-import { z } from "zod";
-
-const server = new McpServer({ name: "my-app", version: "1.0" }, {})
-  .widget("search-voyage", {}, {
-    description: "Search for trips",
-    inputSchema: {
-      destination: z.string(),
-      departureDate: z.string().optional(),
-    },
-    outputSchema: {
-      results: z.array(z.object({ id: z.string(), name: z.string() })),
-      totalCount: z.number(),
-    },
-  }, async ({ destination }) => {
-    // Your tool logic here...
-    return { content: [{ type: "text", text: `Found trips to ${destination}` }] };
-  })
-  .widget("get-details", {}, {
-    inputSchema: { tripId: z.string() },
-  }, async ({ tripId }) => {
-    return { content: [{ type: "text", text: `Details for ${tripId}` }] };
-  });
-
-// Export the server type for the client
-export type AppType = typeof server;
-```
-
-_One-time setup (web/src/skybridge.ts)_
-
-Create typed hooks once and export them for use across your app. This file acts as a bridge between your server types and your widgets:
-
-```ts
-import type { AppType } from "../server"; // type-only import
-import { createTypedHooks } from "skybridge/web";
-
-export const { useCallTool, useToolInfo } = createTypedHooks<AppType>();
-```
-
-_Usage in widgets (web/src/widgets/search.tsx)_
-
-```tsx
-import { useCallTool, useToolInfo } from "../skybridge"; // import typed hooks
-
-export function SearchWidget() {
-  const { callTool, data, isPending } = useCallTool("search-voyage");
-  //                                                 ^ autocomplete for tool names
-  const toolInfo = useToolInfo<"search-voyage">();
-  //                              ^ autocomplete for widget names
-
-  const handleSearch = () => {
-    callTool({ destination: "Spain" });
-    //         ^ autocomplete for input fields
-  };
-
-  return (
-    <div>
-      <button onClick={handleSearch} disabled={isPending}>
-        Search
-      </button>
-      {toolInfo.isSuccess && (
-        <div>Found {toolInfo.output.totalCount} results</div>
-        //                      ^ typed output
-      )}
-    </div>
-  );
-}
-```
-
-**Hooks**
-
-The `skybridge/web` package comes with a set of hooks to help you build your widgets :
-
-- `useOpenAiGlobal`: A generic hook to get any global data from the OpenAI iFrame skybridge runtime (in `window.openai`).
-- `useToolOutput`: A hook to get the initial tool `structuredContent` returned when rendering the widget for the first time. The data inside this hook is not updated when the tool is called again.
-- `useToolResponseMetadata`: A hook to get the initial tool `meta` returned when rendering the widget for the first time. The data inside this hook is not updated when the tool is called again.
-- `useToolInfo`: A hook to get the tool input, output, and response metadata with type inference. Provides a discriminated union based on status (pending/success).
-- `useCallTool`: A @tanstack/react-query inspired hook to send make additional tool calls inside a widget.
-- `createTypedHooks`: A factory that creates typed versions of `useCallTool` and `useToolInfo` with full type inference from your server type.
-
-_useOpenAiGlobal_
-
-```ts
-import { useOpenAiGlobal } from "skybridge/web";
-
-const theme = useOpenAiGlobal("theme");
-```
-
-_useToolOutput_
-
-```ts
-import { useToolOutput } from "skybridge/web";
-
-const toolOutput = useToolOutput();
-```
-
-_useToolResponseMetadata_
-
-```ts
-import { useToolResponseMetadata } from "skybridge/web";
-
-const toolResponseMetadata = useToolResponseMetadata();
-```
-
-_useToolInfo_
-
-```ts
-import { useToolInfo } from "skybridge/web";
-
-const toolInfo = useToolInfo<{
-  input: { query: string };
-  output: { results: string[] };
-  responseMetadata: { id: number };
-}>();
-
-// toolInfo.input is typed based on the input type
-// toolInfo.output is typed based on the output type (undefined when pending)
-// toolInfo.status narrows correctly: "pending" | "success"
-
-if (toolInfo.isPending) {
-  // toolInfo.output is undefined here
-  console.log(toolInfo.input.query);
-}
-
-if (toolInfo.isSuccess) {
-  // toolInfo.output is typed here
-  console.log(toolInfo.output.results);
-}
-```
-
-_useToolInfo_ with typed hooks (recommended)
-
-```tsx
-import { useToolInfo } from "../skybridge"; // import typed hooks
-
-export function SearchWidget() {
-  const toolInfo = useToolInfo<"search-voyage">();
-  //                              ^ autocomplete for widget names
-  // toolInfo.input is typed as { destination: string; departureDate?: string; ... }
-  // toolInfo.output is typed as { results: Array<...>; totalCount: number; } | undefined
-
-  if (toolInfo.isSuccess) {
-    return <div>Found {toolInfo.output.totalCount} results</div>;
-  }
-
-  return <div>Searching for {toolInfo.input.destination}...</div>;
-}
-```
-
-_useCallTool_ in synchronous mode
-
-```ts
-import { useCallTool } from "skybridge/web";
-
-export const TestTool: React.FunctionComponent = () => {
-  const { callTool, isPending } = useCallTool("myToolName");
-
-  return (
-    <div>
-      <button
-        disabled={isPending}
-        onClick={() => {
-          callTool({ input: "test input" }, {
-            onSuccess: (data) => {
-              alert("Tool returned: " + data);
-            },
-          });
-      >
-        Call Tool inside a widget
-      </button>
-    </div>
-  );
-};
-```
-
-_useCallTool_ in asynchronous mode
-
-```ts
-import { useCallTool } from "skybridge/web";
-
-export const TestTool: React.FunctionComponent = () => {
-  const { callToolAsync, isPending } = useCallTool("myToolName");
-
-  return (
-    <div>
-      <button
-        disabled={isPending}
-        onClick={async () => {
-          const data = await callToolAsync({ input: "test input" });
-          alert("Tool returned: " + data);
-        }}
-      >
-        Call Tool inside a widget
-      </button>
-    </div>
-  );
-};
-```
-
-## Migrate your existing MCP server to a ChatGPT app
-
-If you're already using the `@modelcontextprotocol/sdk` to build a MCP server, you can migrate to a ChatGPT app by following these steps:
-
-1. Replace your `McpServer` import from `@modelcontextprotocol/sdk` with the same import from `skybridge/server`
-2. Create a new vite project in a folder named `web` and install the `skybridge` package
-3. Replace the `vite.config.ts` file with the following:
-
-```ts
-import { defineConfig } from "vite";
-import { skybridge } from "skybridge/web";
-
-export default defineConfig({
-  plugins: [skybridge()],
-});
-```

package/dist/src/server/index.d.ts

@@ -1,4 +0,0 @@
-export { McpServer } from "./server.js";
-export { widgetsDevServer } from "./widgetsDevServer.js";
-export type { WidgetDef } from "./server.js";
-export type { InferWidgets, AnyWidgetRegistry, WidgetNames, WidgetInput, WidgetOutput, } from "./inferUtilityTypes.js";

package/dist/src/server/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/server/inferUtilityTypes.d.ts

@@ -1,44 +0,0 @@
-import type { McpServer, WidgetDef } from "./server.js";
-/**
- * Any widget registry shape.
- * Used as a constraint for type parameters that accept widget registries.
- */
-export type AnyWidgetRegistry = Record<string, WidgetDef>;
-/**
- * Extract the widget registry type from an McpServer instance.
- *
- * @example
- * ```ts
- * type MyWidgets = InferWidgets<MyServer>;
- * // { "search": WidgetDef<...>, "details": WidgetDef<...> }
- * ```
- */
-export type InferWidgets<T> = T extends McpServer<infer W extends AnyWidgetRegistry> ? W : T extends McpServer<any> ? never : never;
-/**
- * Get a union of all widget names from an McpServer instance.
- *
- * @example
- * ```ts
- * type Names = WidgetNames<MyServer>;
- * // "search" | "details" | "profile"
- * ```
- */
-export type WidgetNames<T> = keyof InferWidgets<T> & string;
-/**
- * Get the input type for a specific widget.
- *
- * @example
- * ```ts
- * type SearchInput = WidgetInput<MyServer, "search">;
- * ```
- */
-export type WidgetInput<T, K extends WidgetNames<T>> = InferWidgets<T>[K]["input"];
-/**
- * Get the output type for a specific widget.
- *
- * @example
- * ```ts
- * type SearchOutput = WidgetOutput<MyServer, "search">;
- * ```
- */
-export type WidgetOutput<T, K extends WidgetNames<T>> = InferWidgets<T>[K]["output"];

package/dist/src/server/inferUtilityTypes.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"inferUtilityTypes.js","sourceRoot":"","sources":["../../../src/server/inferUtilityTypes.ts"],"names":[],"mappings":""}

package/dist/src/server/server.d.ts

@@ -1,19 +0,0 @@
-import { McpServer as McpServerBase, type ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { Resource } from "@modelcontextprotocol/sdk/types.js";
-import type { ZodRawShape, ZodObject, infer as Infer } from "zod";
-export type WidgetDef<TInput = unknown, TOutput = unknown> = {
-    input: TInput;
-    output: TOutput;
-};
-type McpServerOriginalResourceConfig = Omit<Resource, "uri" | "name" | "mimeType">;
-type McpServerOriginalToolConfig = Omit<Parameters<McpServerBase["registerTool"]>[1], "inputSchema" | "outputSchema">;
-export declare class McpServer<TWidgets extends Record<string, WidgetDef> = {}> extends McpServerBase {
-    widget<TName extends string, TInput extends ZodRawShape, TOutput extends ZodRawShape = {}>(name: TName, resourceConfig: McpServerOriginalResourceConfig, toolConfig: McpServerOriginalToolConfig & {
-        inputSchema?: TInput;
-        outputSchema?: TOutput;
-    }, toolCallback: ToolCallback<TInput>): McpServer<TWidgets & {
-        [K in TName]: WidgetDef<Infer<ZodObject<TInput>>, Infer<ZodObject<TOutput>>>;
-    }>;
-    private lookupDistFile;
-}
-export {};