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.ymlindex 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+ - serverjobs:publish:diff --git a/packages/server/README.md b/packages/server/README.mdnew file mode 100644index 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.cjsnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.yamlindex 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+ version: 6.49.0(@aws-sdk/[email protected])(@smithy/[email protected])([email protected])([email protected])+ tsdown:+ specifier: ^0.21.7+ version: 0.21.10(@arethetypeswrong/[email protected])(@typescript/[email protected])([email protected])([email protected])([email protected])([email protected])+ vitest:+ specifier: ^4.1.0+ version: 4.1.10(@opentelemetry/[email protected])(@types/[email protected])([email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]))+packages/svelte-lang:dependencies:'@openuidev/lang-core':@@ -10427,7 +10439,7 @@ snapshots:'@antfu/[email protected]':dependencies:package-manager-detector: 1.8.0- tinyexec: 1.2.4+ tinyexec: 1.3.1'@arethetypeswrong/[email protected]':dependencies:@@ -10793,7 +10805,7 @@ snapshots:'@babel/[email protected]':dependencies:'@babel/helper-string-parser': 8.0.0- '@babel/helper-validator-identifier': 8.0.0-rc.3+ '@babel/helper-validator-identifier': 8.0.4'@babel/[email protected]':dependencies:@@ -20267,7 +20279,7 @@ snapshots:rolldown: 1.0.0-rc.17rolldown-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.1tinyglobby: 0.2.17tree-kill: 1.2.2unconfig-core: 7.5.0@@ -20683,7 +20695,7 @@ snapshots:picomatch: 4.0.5std-env: 4.2.0tinybench: 2.9.0- tinyexec: 1.2.4+ tinyexec: 1.3.1tinyglobby: 0.2.17tinyrainbow: 3.1.1vite: 7.3.6(@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected])@@ -20712,7 +20724,7 @@ snapshots:picomatch: 4.0.5std-env: 4.2.0tinybench: 2.9.0- tinyexec: 1.2.4+ tinyexec: 1.3.1tinyglobby: 0.2.17tinyrainbow: 3.1.1vite: 6.4.3(@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected])@@ -20741,7 +20753,7 @@ snapshots:picomatch: 4.0.5std-env: 4.2.0tinybench: 2.9.0- tinyexec: 1.2.4+ tinyexec: 1.3.1tinyglobby: 0.2.17tinyrainbow: 3.1.1vite: 7.3.6(@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected])@@ -20770,7 +20782,7 @@ snapshots:picomatch: 4.0.5std-env: 4.2.0tinybench: 2.9.0- tinyexec: 1.2.4+ tinyexec: 1.3.1tinyglobby: 0.2.17tinyrainbow: 3.1.1vite: 6.4.3(@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected])@@ -20799,7 +20811,7 @@ snapshots:picomatch: 4.0.5std-env: 4.2.0tinybench: 2.9.0- tinyexec: 1.2.4+ tinyexec: 1.3.1tinyglobby: 0.2.17tinyrainbow: 3.1.1vite: 7.3.6(@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected])