Skip to content

The Open Standard for Generative UI

Add `@openuidev/server` (#1149)

AB41226425b7a1
diff --git a/.github/workflows/publish-npm-package.yml b/.github/workflows/publish-npm-package.yml
index 3d4ebedc9..821310588 100644
--- a/.github/workflows/publish-npm-package.yml
+++ b/.github/workflows/publish-npm-package.yml
@@ -31,6 +31,7 @@ on:
- observability
- observability-cloud
- devtools
+ - server
jobs:
publish:
diff --git a/packages/server/README.md b/packages/server/README.md
new file mode 100644
index 000000000..10cd058d3
--- /dev/null
+++ b/packages/server/README.md
@@ -0,0 +1,33 @@
+# `@openuidev/server`
+
+Server utilities for OpenUI & OpenUI Gateway.
+
+```bash
+npm install @openuidev/server
+```
+
+Persist a Chat Completions turn as Conversations API items. Chat Completions has no `conversation` + `store: true`. Use the master API key (Cloud rejects frontend tokens on create). Pass only the new turn — last user message plus the assembled assistant reply — not the client’s full `messages` array.
+
+```ts
+import { storeChatCompletionHistory } from "@openuidev/server";
+
+await storeChatCompletionHistory({
+ apiKey: process.env.THESYS_API_KEY!,
+ conversationId: threadId,
+ messages: [
+ { role: "user", content: lastUserText },
+ { role: "assistant", content: assistantText },
+ ],
+});
+```
+
+Convert without posting:
+
+```ts
+import { chatCompletionMessagesToItems } from "@openuidev/server";
+
+chatCompletionMessagesToItems([
+ { role: "user", content: "hello" },
+ { role: "assistant", content: "hi" },
+]);
+```
diff --git a/packages/server/eslint.config.cjs b/packages/server/eslint.config.cjs
new file mode 100644
index 000000000..413c49627
--- /dev/null
+++ b/packages/server/eslint.config.cjs
@@ -0,0 +1,73 @@
+const tseslint = require("@typescript-eslint/eslint-plugin");
+const typescript = require("@typescript-eslint/parser");
+const prettier = require("eslint-config-prettier");
+const unusedImports = require("eslint-plugin-unused-imports");
+const eslintPluginPrettier = require("eslint-plugin-prettier");
+
+module.exports = [
+ {
+ files: ["**/__tests__/**/*.{ts,tsx}", "**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
+ languageOptions: {
+ parser: typescript,
+ parserOptions: {
+ project: "./tsconfig.test.json",
+ sourceType: "module",
+ },
+ },
+ },
+ {
+ files: ["**/*.{ts,tsx}"],
+ ignores: [
+ "**/*.stories.tsx",
+ "**/__tests__/**/*.{ts,tsx}",
+ "**/*.test.{ts,tsx}",
+ "**/*.spec.{ts,tsx}",
+ "*.config.ts",
+ ],
+ languageOptions: {
+ parser: typescript,
+ parserOptions: {
+ project: "./tsconfig.json",
+ sourceType: "module",
+ },
+ },
+ plugins: {
+ "@typescript-eslint": tseslint,
+ "unused-imports": unusedImports,
+ prettier: eslintPluginPrettier,
+ },
+ rules: {
+ "@typescript-eslint/interface-name-prefix": "off",
+ "@typescript-eslint/explicit-function-return-type": "off",
+ "@typescript-eslint/explicit-module-boundary-types": "off",
+ "@typescript-eslint/no-explicit-any": "off",
+ "no-undefined": "off",
+ "@typescript-eslint/no-unused-vars": [
+ "error",
+ {
+ vars: "all",
+ varsIgnorePattern: "^_",
+ args: "after-used",
+ argsIgnorePattern: "^_",
+ },
+ ],
+ "@typescript-eslint/no-use-before-define": [
+ "error",
+ {
+ functions: false,
+ classes: false,
+ variables: false,
+ },
+ ],
+ "unused-imports/no-unused-imports": "error",
+ "no-console": [
+ "error",
+ {
+ allow: ["error", "warn", "info"],
+ },
+ ],
+ ...eslintPluginPrettier.configs.recommended.rules,
+ },
+ },
+ prettier,
+];
diff --git a/packages/server/package.json b/packages/server/package.json
new file mode 100644
index 000000000..78474c25c
--- /dev/null
+++ b/packages/server/package.json
@@ -0,0 +1,64 @@
+{
+ "name": "@openuidev/server",
+ "version": "0.0.1",
+ "description": "Server utilities for OpenUI & OpenUI Gateway",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "type": "module",
+ "main": "dist/index.cjs",
+ "module": "dist/index.mjs",
+ "types": "dist/index.d.cts",
+ "sideEffects": false,
+ "files": [
+ "dist",
+ "README.md"
+ ],
+ "exports": {
+ ".": {
+ "import": {
+ "types": "./dist/index.d.mts",
+ "default": "./dist/index.mjs"
+ },
+ "require": {
+ "types": "./dist/index.d.cts",
+ "default": "./dist/index.cjs"
+ }
+ }
+ },
+ "scripts": {
+ "test": "vitest run",
+ "build": "tsdown",
+ "watch": "tsdown --watch",
+ "typecheck": "tsc --noEmit",
+ "lint:check": "eslint ./src",
+ "lint:fix": "eslint ./src --fix",
+ "format:fix": "prettier --write ./src README.md",
+ "format:check": "prettier --check ./src README.md",
+ "check:publint": "publint",
+ "check:attw": "attw --pack .",
+ "prepare": "pnpm run build",
+ "prepublishOnly": "pnpm run check:publint && pnpm run check:attw",
+ "ci": "pnpm run typecheck && pnpm run test && pnpm run lint:check && pnpm run format:check"
+ },
+ "keywords": [
+ "openui",
+ "server"
+ ],
+ "homepage": "https://openui.com",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/thesysdev/openui.git",
+ "directory": "packages/server"
+ },
+ "bugs": {
+ "url": "https://github.com/thesysdev/openui/issues"
+ },
+ "author": "[email protected]",
+ "devDependencies": {
+ "openai": "^6.22.0",
+ "tsdown": "^0.21.7",
+ "vitest": "^4.1.0"
+ }
+}
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
new file mode 100644
index 000000000..872127586
--- /dev/null
+++ b/packages/server/src/index.ts
@@ -0,0 +1,5 @@
+export {
+ chatCompletionMessagesToItems,
+ storeChatCompletionHistory,
+} from "./store-chat-completion-history";
+export type { StoreChatCompletionHistoryOptions } from "./types";
diff --git a/packages/server/src/store-chat-completion-history.test.ts b/packages/server/src/store-chat-completion-history.test.ts
new file mode 100644
index 000000000..0c0a7ef1b
--- /dev/null
+++ b/packages/server/src/store-chat-completion-history.test.ts
@@ -0,0 +1,243 @@
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+import { describe, expect, it, vi } from "vitest";
+import {
+ chatCompletionMessagesToItems,
+ storeChatCompletionHistory,
+} from "./store-chat-completion-history";
+
+describe("chatCompletionMessagesToItems", () => {
+ it("maps user and assistant text into Conversations message items", () => {
+ expect(
+ chatCompletionMessagesToItems([
+ { role: "user", content: "hello" },
+ { role: "assistant", content: "hi there" },
+ ]),
+ ).toEqual([
+ {
+ type: "message",
+ role: "user",
+ content: [{ type: "input_text", text: "hello" }],
+ },
+ {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: "hi there" }],
+ },
+ ]);
+ });
+
+ it("skips system and developer messages", () => {
+ expect(
+ chatCompletionMessagesToItems([
+ { role: "system", content: "you are a bot" },
+ { role: "developer", content: "internal" },
+ { role: "user", content: "ping" },
+ ]),
+ ).toEqual([
+ {
+ type: "message",
+ role: "user",
+ content: [{ type: "input_text", text: "ping" }],
+ },
+ ]);
+ });
+
+ it("flattens assistant tool_calls into sibling function_call items", () => {
+ const messages: ChatCompletionMessageParam[] = [
+ { role: "user", content: "weather?" },
+ {
+ role: "assistant",
+ content: null,
+ tool_calls: [
+ {
+ id: "call_1",
+ type: "function",
+ function: { name: "get_weather", arguments: '{"city":"nyc"}' },
+ },
+ ],
+ },
+ { role: "tool", tool_call_id: "call_1", content: '{"temp":72}' },
+ { role: "assistant", content: "72 and sunny" },
+ ];
+
+ expect(chatCompletionMessagesToItems(messages)).toEqual([
+ {
+ type: "message",
+ role: "user",
+ content: [{ type: "input_text", text: "weather?" }],
+ },
+ {
+ type: "function_call",
+ call_id: "call_1",
+ name: "get_weather",
+ arguments: '{"city":"nyc"}',
+ },
+ {
+ type: "function_call_output",
+ call_id: "call_1",
+ output: '{"temp":72}',
+ },
+ {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: "72 and sunny" }],
+ },
+ ]);
+ });
+
+ it("maps image_url parts to input_image", () => {
+ expect(
+ chatCompletionMessagesToItems([
+ {
+ role: "user",
+ content: [
+ { type: "text", text: "what is this?" },
+ { type: "image_url", image_url: { url: "https://cdn.example/a.png" } },
+ ],
+ },
+ ]),
+ ).toEqual([
+ {
+ type: "message",
+ role: "user",
+ content: [
+ { type: "input_text", text: "what is this?" },
+ {
+ type: "input_image",
+ image_url: "https://cdn.example/a.png",
+ detail: "auto",
+ },
+ ],
+ },
+ ]);
+ });
+
+ it("skips empty user messages", () => {
+ expect(chatCompletionMessagesToItems([{ role: "user", content: "" }])).toEqual([]);
+ });
+
+ it("defaults empty tool arguments and outputs so Cloud create does not 400", () => {
+ expect(
+ chatCompletionMessagesToItems([
+ {
+ role: "assistant",
+ content: null,
+ tool_calls: [
+ { id: "call_1", type: "function", function: { name: "web_search", arguments: "" } },
+ ],
+ },
+ { role: "tool", tool_call_id: "call_1", content: "" },
+ ]),
+ ).toEqual([
+ {
+ type: "function_call",
+ call_id: "call_1",
+ name: "web_search",
+ arguments: "{}",
+ },
+ {
+ type: "function_call_output",
+ call_id: "call_1",
+ output: "{}",
+ },
+ ]);
+ });
+});
+
+describe("storeChatCompletionHistory", () => {
+ it("POSTs converted items to the Conversations API", async () => {
+ const fetch = vi.fn().mockResolvedValue({
+ ok: true,
+ json: async () => ({ object: "list", data: [{ id: "item_1" }] }),
+ });
+
+ const result = await storeChatCompletionHistory({
+ apiKey: "sk-test",
+ conversationId: "conv 1",
+ messages: [
+ { role: "user", content: "hello" },
+ { role: "assistant", content: "hi" },
+ ],
+ fetch,
+ });
+
+ expect(fetch).toHaveBeenCalledTimes(1);
+ const [url, init] = fetch.mock.calls[0] as [
+ string,
+ { method?: string; headers?: Record<string, string>; body?: string },
+ ];
+ expect(url).toBe("https://api.thesys.dev/v1/conversations/conv%201/items");
+ expect(init.method).toBe("POST");
+ expect(init.headers).toEqual({
+ Authorization: "Bearer sk-test",
+ "Content-Type": "application/json",
+ });
+ expect(JSON.parse(init.body as string)).toEqual({
+ items: [
+ {
+ type: "message",
+ role: "user",
+ content: [{ type: "input_text", text: "hello" }],
+ },
+ {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: "hi" }],
+ },
+ ],
+ });
+ expect(result).toEqual({ object: "list", data: [{ id: "item_1" }] });
+ });
+
+ it("does not fetch when there is nothing to store", async () => {
+ const fetch = vi.fn();
+ const result = await storeChatCompletionHistory({
+ apiKey: "sk-test",
+ conversationId: "conv_1",
+ messages: [{ role: "system", content: "skip me" }],
+ fetch,
+ });
+ expect(fetch).not.toHaveBeenCalled();
+ expect(result).toEqual({
+ object: "list",
+ data: [],
+ first_id: "",
+ last_id: "",
+ has_more: false,
+ });
+ });
+
+ it("throws with the response body when the API rejects the write", async () => {
+ const fetch = vi.fn().mockResolvedValue({
+ ok: false,
+ status: 404,
+ text: async () => "conversation not found",
+ });
+
+ await expect(
+ storeChatCompletionHistory({
+ apiKey: "sk-test",
+ conversationId: "missing",
+ messages: [{ role: "user", content: "hello" }],
+ fetch,
+ }),
+ ).rejects.toThrow("store chat completion history failed: 404 conversation not found");
+ });
+
+ it("honors apiBaseUrl and strips a trailing slash", async () => {
+ const fetch = vi.fn().mockResolvedValue({
+ ok: true,
+ json: async () => ({ object: "list", data: [] }),
+ });
+
+ await storeChatCompletionHistory({
+ apiKey: "sk-test",
+ conversationId: "conv_1",
+ messages: [{ role: "user", content: "hello" }],
+ apiBaseUrl: "http://localhost:3000/",
+ fetch,
+ });
+
+ expect(fetch.mock.calls[0]?.[0]).toBe("http://localhost:3000/v1/conversations/conv_1/items");
+ });
+});
diff --git a/packages/server/src/store-chat-completion-history.ts b/packages/server/src/store-chat-completion-history.ts
new file mode 100644
index 000000000..0f963e4f1
--- /dev/null
+++ b/packages/server/src/store-chat-completion-history.ts
@@ -0,0 +1,161 @@
+import type {
+ ChatCompletionAssistantMessageParam,
+ ChatCompletionMessageParam,
+ ChatCompletionToolMessageParam,
+ ChatCompletionUserMessageParam,
+} from "openai/resources/chat/completions";
+import type { ConversationItemList } from "openai/resources/conversations/items";
+import type {
+ EasyInputMessage,
+ ResponseFunctionToolCall,
+ ResponseInputItem,
+ ResponseInputMessageContentList,
+} from "openai/resources/responses/responses";
+import type { StoreChatCompletionHistoryOptions } from "./types";
+
+const THESYS_API_BASE_URL = "https://api.thesys.dev";
+
+function userContentOf(
+ content: ChatCompletionUserMessageParam["content"],
+): ResponseInputMessageContentList {
+ if (typeof content === "string") {
+ return content ? [{ type: "input_text", text: content }] : [];
+ }
+
+ const parts: ResponseInputMessageContentList = [];
+ for (const part of content) {
+ if (part.type === "text" && part.text) {
+ parts.push({ type: "input_text", text: part.text });
+ continue;
+ }
+ if (part.type === "image_url" && part.image_url.url) {
+ parts.push({
+ type: "input_image",
+ image_url: part.image_url.url,
+ detail: part.image_url.detail ?? "auto",
+ });
+ }
+ }
+ return parts;
+}
+
+function assistantTextOf(content: ChatCompletionAssistantMessageParam["content"]): string {
+ if (typeof content === "string") return content;
+ if (!Array.isArray(content)) return "";
+ return content
+ .map((part) => (part.type === "text" ? part.text : ""))
+ .filter(Boolean)
+ .join("");
+}
+
+function toolOutputOf(content: ChatCompletionToolMessageParam["content"]): string {
+ if (typeof content === "string") return content;
+ return content.map((part) => part.text).join("");
+}
+
+/**
+ * Break Chat Completions messages into Conversations API items.
+ * Pass the new turn, not the full replay, or items will be duplicated.
+ * System / developer messages are skipped (instructions, not history).
+ */
+export function chatCompletionMessagesToItems(
+ messages: ChatCompletionMessageParam[],
+): ResponseInputItem[] {
+ const items: ResponseInputItem[] = [];
+
+ for (const message of messages) {
+ if (message.role === "system" || message.role === "developer") continue;
+
+ if (message.role === "user") {
+ const content = userContentOf(message.content);
+ if (content.length === 0) continue;
+ items.push({
+ type: "message",
+ role: "user",
+ content,
+ } satisfies EasyInputMessage);
+ continue;
+ }
+
+ if (message.role === "assistant") {
+ const text = assistantTextOf(message.content);
+ if (text) {
+ items.push({
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text }],
+ } as ResponseInputItem);
+ }
+ for (const call of message.tool_calls ?? []) {
+ if (call.type !== "function") continue;
+ if (!call.id || !call.function.name) continue;
+ items.push({
+ type: "function_call",
+ call_id: call.id,
+ name: call.function.name,
+ arguments: call.function.arguments?.trim() ? call.function.arguments : "{}",
+ } satisfies ResponseFunctionToolCall);
+ }
+ continue;
+ }
+
+ if (message.role === "tool") {
+ if (!message.tool_call_id) continue;
+ items.push({
+ type: "function_call_output",
+ call_id: message.tool_call_id,
+ output: toolOutputOf(message.content) || "{}",
+ } satisfies ResponseInputItem.FunctionCallOutput);
+ }
+ }
+
+ return items;
+}
+
+const EMPTY_ITEM_LIST: ConversationItemList = {
+ object: "list",
+ data: [],
+ first_id: "",
+ last_id: "",
+ has_more: false,
+};
+
+/**
+ * POST Chat Completions messages as Conversations API items.
+ *
+ * Call this after a turn (typically the new user message plus
+ * the assembled assistant reply) so OpenUI Cloud storage can
+ * reload the thread.
+ *
+ * The conversation must already exist — AgentInterface's Cloud storage
+ * creates it via `POST /v1/conversations`. Pass only the new turn, not the
+ * full replay, or items will be duplicated.
+ */
+export async function storeChatCompletionHistory(
+ options: StoreChatCompletionHistoryOptions,
+): Promise<ConversationItemList> {
+ const items = chatCompletionMessagesToItems(options.messages);
+ if (items.length === 0) {
+ return EMPTY_ITEM_LIST;
+ }
+
+ const base = (options.apiBaseUrl ?? THESYS_API_BASE_URL).replace(/\/+$/, "");
+ const fetchFn = options.fetch ?? (globalThis.fetch as typeof fetch);
+ const res = await fetchFn(
+ `${base}/v1/conversations/${encodeURIComponent(options.conversationId)}/items`,
+ {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${options.apiKey}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({ items }),
+ },
+ );
+
+ if (!res.ok) {
+ throw new Error(`store chat completion history failed: ${res.status} ${await res.text()}`);
+ }
+
+ return (await res.json()) as ConversationItemList;
+}
diff --git a/packages/server/src/types.ts b/packages/server/src/types.ts
new file mode 100644
index 000000000..ed580e349
--- /dev/null
+++ b/packages/server/src/types.ts
@@ -0,0 +1,23 @@
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+
+export type StoreChatCompletionHistoryOptions = {
+ apiKey: string;
+ conversationId: string;
+ /** Chat Completions messages for the new turn. */
+ messages: ChatCompletionMessageParam[];
+ /** Defaults to `https://api.thesys.dev`. */
+ apiBaseUrl?: string;
+ fetch?: (
+ input: string,
+ init?: {
+ method?: string;
+ headers?: Record<string, string>;
+ body?: string;
+ },
+ ) => Promise<{
+ ok: boolean;
+ status: number;
+ text: () => Promise<string>;
+ json: () => Promise<unknown>;
+ }>;
+};
diff --git a/packages/server/tsconfig.json b/packages/server/tsconfig.json
new file mode 100644
index 000000000..050ddeb9a
--- /dev/null
+++ b/packages/server/tsconfig.json
@@ -0,0 +1,13 @@
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "extends": "../../tsconfig.json",
+ "include": ["src/**/*"],
+ "exclude": ["src/**/__tests__/**", "src/**/*.test.ts"],
+ "compilerOptions": {
+ "moduleResolution": "bundler",
+ "module": "ESNext",
+ "outDir": "./dist",
+ "rootDir": "./src",
+ "noEmit": true
+ }
+}
diff --git a/packages/server/tsconfig.test.json b/packages/server/tsconfig.test.json
new file mode 100644
index 000000000..60b3001d5
--- /dev/null
+++ b/packages/server/tsconfig.test.json
@@ -0,0 +1,9 @@
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "noEmit": true
+ },
+ "include": ["src/**/*"],
+ "exclude": ["dist", "node_modules"]
+}
diff --git a/packages/server/tsdown.config.ts b/packages/server/tsdown.config.ts
new file mode 100644
index 000000000..bd5f1a3e1
--- /dev/null
+++ b/packages/server/tsdown.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+ entry: ["src/index.ts"],
+ format: ["esm", "cjs"],
+ dts: true,
+ sourcemap: true,
+ target: "es2022",
+ outDir: "dist",
+ clean: true,
+ deps: {
+ neverBundle: [/^(?![./]|[A-Za-z]:[/\\])/],
+ },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9abb627d0..a8000500e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -787,6 +787,18 @@ importers:
specifier: ^5.104.1
+ packages/server:
+ devDependencies:
+ openai:
+ specifier: ^6.22.0
+ tsdown:
+ specifier: ^0.21.7
+ vitest:
+ specifier: ^4.1.0
+
packages/svelte-lang:
dependencies:
'@openuidev/lang-core':
@@ -10427,7 +10439,7 @@ snapshots:
dependencies:
package-manager-detector: 1.8.0
- tinyexec: 1.2.4
+ tinyexec: 1.3.1
'@arethetypeswrong/[email protected]':
dependencies:
@@ -10793,7 +10805,7 @@ snapshots:
dependencies:
'@babel/helper-string-parser': 8.0.0
- '@babel/helper-validator-identifier': 8.0.0-rc.3
+ '@babel/helper-validator-identifier': 8.0.4
dependencies:
@@ -20267,7 +20279,7 @@ snapshots:
rolldown: 1.0.0-rc.17
rolldown-plugin-dts: 0.23.2(@typescript/[email protected])([email protected])([email protected])([email protected])
semver: 7.8.5
- tinyexec: 1.2.4
+ tinyexec: 1.3.1
tinyglobby: 0.2.17
tree-kill: 1.2.2
unconfig-core: 7.5.0
@@ -20683,7 +20695,7 @@ snapshots:
picomatch: 4.0.5
std-env: 4.2.0
tinybench: 2.9.0
- tinyexec: 1.2.4
+ tinyexec: 1.3.1
tinyglobby: 0.2.17
tinyrainbow: 3.1.1
@@ -20712,7 +20724,7 @@ snapshots:
picomatch: 4.0.5
std-env: 4.2.0
tinybench: 2.9.0
- tinyexec: 1.2.4
+ tinyexec: 1.3.1
tinyglobby: 0.2.17
tinyrainbow: 3.1.1
@@ -20741,7 +20753,7 @@ snapshots:
picomatch: 4.0.5
std-env: 4.2.0
tinybench: 2.9.0
- tinyexec: 1.2.4
+ tinyexec: 1.3.1
tinyglobby: 0.2.17
tinyrainbow: 3.1.1
@@ -20770,7 +20782,7 @@ snapshots:
picomatch: 4.0.5
std-env: 4.2.0
tinybench: 2.9.0
- tinyexec: 1.2.4
+ tinyexec: 1.3.1
tinyglobby: 0.2.17
tinyrainbow: 3.1.1
@@ -20799,7 +20811,7 @@ snapshots:
picomatch: 4.0.5
std-env: 4.2.0
tinybench: 2.9.0
- tinyexec: 1.2.4
+ tinyexec: 1.3.1
tinyglobby: 0.2.17
tinyrainbow: 3.1.1