@chatu-ai/app-sdk 0.6.2 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @chatu-ai/app-sdk
 
-Data SDK for apps generated by **ChatU Builder**. One API, driver picked from environment variables — works in the Builder preview, on your own server, or with no config at all.
+Data + AI SDK for apps generated by **ChatU Builder**. One API, driver picked from environment variables — works in the Builder preview, on your own server, or with no config at all.
 
 ```ts
 import { kv, storage } from '@chatu-ai/app-sdk'   // server-side only (Route Handlers / Server Components / Server Actions)
@@ -21,4 +21,49 @@ const src = await storage.url('avatars/u1.png', { expiresIn: 3600 })         //
 | `REDIS_URL` and/or `S3_BUCKET` (+ `S3_ENDPOINT` `S3_REGION` `S3_ACCESS_KEY` `S3_SECRET_KEY` `S3_PREFIX`) | **byo** — your own Redis / S3-compatible bucket (Tencent COS, MinIO, AWS) | install optional deps: `npm i ioredis @aws-sdk/client-s3 @aws-sdk/s3-request-presigner` |
 | none | **memory** — in-process, lost on restart | local dev / fallback |
 
+## AI (LLM relay)
+
+`ai` calls the platform's OpenAI-compatible endpoint (`{origin}/v1/chat/completions`) with the same app key used by the Data API. **Server-side only** — call it from a Route Handler / Server Action and let the browser `fetch` your own API; never ship the key to the client. Usage is metered and **billed to the app owner's ChatU points**.
+
+| Env | Notes |
+| --- | --- |
+| `CHATU_DATA_URL` + `CHATU_APP_KEY` | same as the Data API — the AI base URL is derived by replacing the trailing `/data/v1` with `/v1` |
+| `CHATU_AI_URL` (optional) | explicit override of the AI base URL, e.g. `https://api.chatuapi.com/v1` |
+| `CHATU_AI_MODEL` / `PRIMARY_MODEL` (optional) | default model id when the caller does not pass `model`; the Builder sandbox sets `PRIMARY_MODEL`; if neither is set the server default is used |
+
+```ts
+// app/api/summarize/route.ts — one-shot
+import { ai } from '@chatu-ai/app-sdk'
+
+export async function POST(req: Request) {
+  const { text } = await req.json()
+  const { content, usage } = await ai.chat([
+    { role: 'system', content: 'Summarize the user text in one sentence.' },
+    { role: 'user', content: text },
+  ], { temperature: 0.3, maxTokens: 200 })      // model optional; extra: { top_p, stop, response_format … } passes through
+  return Response.json({ summary: content, usage })
+}
+```
+
+```ts
+// app/api/chat/route.ts — streaming (text/plain chunks; consume in the browser with res.body.getReader())
+import { ai } from '@chatu-ai/app-sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()          // [{ role: 'user', content: '…' }, …]
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const enc = new TextEncoder()
+      try {
+        for await (const delta of ai.stream(messages, { signal: req.signal })) controller.enqueue(enc.encode(delta))
+        controller.close()
+      } catch (e) { controller.error(e) }
+    },
+  })
+  return new Response(stream, { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-cache' } })
+}
+```
+
+`ai.chat('hello')` accepts a plain string as a single user message; `ai.models()` lists available model ids. Without platform env vars (memory / byo drivers) every call rejects with `AppSdkError('AI_NOT_CONFIGURED')` — there is no local fallback for LLM calls.
+
 Never expose `CHATU_APP_KEY` to the browser. MIT.

package/dist/ai.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 应用内 AI 能力（LLM 中继）：走平台的 OpenAI 兼容端点 `POST {aiBaseUrl}/chat/completions`，
+ * 用与 Data API 相同的应用密钥（sk-conv-…）鉴权，用量由平台按 api-key 计入应用所有者的 ChatU 点数。
+ * 只在服务端使用（Route Handler / Server Action）；密钥不得暴露给浏览器。
+ */
+export interface AiMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface AiChatOptions {
+    /** 模型 id；缺省用 CHATU_AI_MODEL / PRIMARY_MODEL，都没有则不传由服务端决定 */
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    /** 透传到请求体的其它 OpenAI 兼容字段（如 top_p、stop、response_format） */
+    extra?: Record<string, unknown>;
+}
+export interface AiUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+}
+export interface AiChatResult {
+    content: string;
+    model?: string;
+    usage?: AiUsage;
+}
+export interface AiClient {
+    /** 一次性对话，返回完整回复 */
+    chat(messages: AiMessage[] | string, opts?: AiChatOptions): Promise<AiChatResult>;
+    /** 流式对话，逐段产出文本增量 */
+    stream(messages: AiMessage[] | string, opts?: AiChatOptions): AsyncIterable<string>;
+    /** 可用模型 id 列表 */
+    models(): Promise<string[]>;
+}
+/** 解析 OpenAI 风格 SSE：`data: {...}` 行，`[DONE]` 结束；产出 choices[0].delta.content */
+export declare function parseSseDeltas(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
+/** 按当前配置取 AI 客户端（惰性、缓存；configure() 后自动重建） */
+export declare function getAi(): AiClient;
+/** 便捷单例：`import { ai } from '@chatu-ai/app-sdk'` */
+export declare const ai: AiClient;

package/dist/ai.js

@@ -0,0 +1,145 @@
+import { resolveConfig } from './config.js';
+import { AppSdkError } from './errors.js';
+const toMessages = (input) => (typeof input === 'string' ? [{ role: 'user', content: input }] : input);
+function buildBody(cfg, messages, opts, stream) {
+    const model = opts?.model ?? cfg.aiModel;
+    const body = { ...(opts?.extra ?? {}), messages: toMessages(messages) };
+    if (model)
+        body.model = model;
+    if (opts?.temperature !== undefined)
+        body.temperature = opts.temperature;
+    if (opts?.maxTokens !== undefined)
+        body.max_tokens = opts.maxTokens;
+    if (stream)
+        body.stream = true;
+    return body;
+}
+async function throwHttpError(res, what) {
+    let json = null;
+    let text = '';
+    try {
+        text = await res.text();
+        json = JSON.parse(text);
+    }
+    catch { /* not json */ }
+    const err = json?.error;
+    const code = (typeof err === 'object' && err?.code) || (typeof err === 'string' && err) || json?.code || `HTTP_${res.status}`;
+    const message = (typeof err === 'object' && err?.message) || json?.message || (text ? text.slice(0, 300) : `${what} failed (${res.status})`);
+    throw new AppSdkError(String(code), String(message), res.status);
+}
+/** 解析 OpenAI 风格 SSE：`data: {...}` 行，`[DONE]` 结束；产出 choices[0].delta.content */
+export async function* parseSseDeltas(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    const handle = (line) => {
+        const t = line.trim();
+        if (!t.startsWith('data:'))
+            return undefined;
+        const payload = t.slice(5).trim();
+        if (!payload || payload === '[DONE]')
+            return payload === '[DONE]' ? null : undefined;
+        try {
+            const json = JSON.parse(payload);
+            const delta = json?.choices?.[0]?.delta?.content ?? json?.choices?.[0]?.text;
+            return typeof delta === 'string' && delta.length ? delta : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, idx);
+                buf = buf.slice(idx + 1);
+                const r = handle(line);
+                if (r === null)
+                    return;
+                if (r !== undefined)
+                    yield r;
+            }
+        }
+        if (buf.trim()) {
+            const r = handle(buf);
+            if (r)
+                yield r;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+// ---------- platform driver ----------
+function platformAi(cfg) {
+    const headers = { authorization: `Bearer ${cfg.apiKey}`, 'content-type': 'application/json' };
+    return {
+        async chat(messages, opts) {
+            const res = await cfg.fetchImpl(`${cfg.aiBaseUrl}/chat/completions`, {
+                method: 'POST', headers, body: JSON.stringify(buildBody(cfg, messages, opts, false)), signal: opts?.signal,
+            });
+            if (!res.ok)
+                await throwHttpError(res, 'ai.chat');
+            const json = await res.json();
+            const msg = json?.choices?.[0]?.message;
+            const content = typeof msg?.content === 'string' ? msg.content : Array.isArray(msg?.content) ? msg.content.map((p) => (typeof p?.text === 'string' ? p.text : '')).join('') : '';
+            const u = json?.usage;
+            return {
+                content,
+                model: typeof json?.model === 'string' ? json.model : undefined,
+                usage: u ? { promptTokens: u.prompt_tokens, completionTokens: u.completion_tokens, totalTokens: u.total_tokens } : undefined,
+            };
+        },
+        stream(messages, opts) {
+            const start = async () => {
+                const res = await cfg.fetchImpl(`${cfg.aiBaseUrl}/chat/completions`, {
+                    method: 'POST', headers: { ...headers, accept: 'text/event-stream' }, body: JSON.stringify(buildBody(cfg, messages, opts, true)), signal: opts?.signal,
+                });
+                if (!res.ok)
+                    await throwHttpError(res, 'ai.stream');
+                if (!res.body)
+                    throw new AppSdkError('EMPTY_BODY', 'ai.stream: response has no body');
+                return res.body;
+            };
+            return { [Symbol.asyncIterator]: async function* () { yield* parseSseDeltas(await start()); } };
+        },
+        async models() {
+            const res = await cfg.fetchImpl(`${cfg.aiBaseUrl}/models`, { method: 'GET', headers: { authorization: headers.authorization } });
+            if (!res.ok)
+                await throwHttpError(res, 'ai.models');
+            const json = await res.json();
+            const list = Array.isArray(json?.data) ? json.data : Array.isArray(json) ? json : [];
+            return list.map(m => (typeof m === 'string' ? m : m?.id)).filter((id) => typeof id === 'string');
+        },
+    };
+}
+const NOT_CONFIGURED = 'AI is only available with the platform driver: set CHATU_DATA_URL/CHATU_APP_KEY (or CHATU_AI_URL) — copied from the Builder publish panel; there is no memory/byo fallback for LLM calls';
+function notConfigured() {
+    const fail = () => { throw new AppSdkError('AI_NOT_CONFIGURED', NOT_CONFIGURED); };
+    return {
+        chat: async () => fail(),
+        stream: () => ({ [Symbol.asyncIterator]: async function* () { fail(); } }),
+        models: async () => fail(),
+    };
+}
+let cached = null;
+/** 按当前配置取 AI 客户端（惰性、缓存；configure() 后自动重建） */
+export function getAi() {
+    const cfg = resolveConfig();
+    const key = cfg.kind === 'platform' ? `platform|${cfg.aiBaseUrl}|${cfg.aiModel ?? ''}|${cfg.apiKey.slice(-4)}` : cfg.kind;
+    const fetchImpl = cfg.kind === 'platform' ? cfg.fetchImpl : undefined;
+    if (!cached || cached.key !== key || cached.fetchImpl !== fetchImpl)
+        cached = { key, fetchImpl, client: cfg.kind === 'platform' ? platformAi(cfg) : notConfigured() };
+    return cached.client;
+}
+/** 便捷单例：`import { ai } from '@chatu-ai/app-sdk'` */
+export const ai = {
+    chat: (m, o) => getAi().chat(m, o),
+    stream: (m, o) => getAi().stream(m, o),
+    models: () => getAi().models(),
+};

package/dist/ai.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ai.test.js

@@ -0,0 +1,82 @@
+import { describe as d, expect, it } from 'vitest';
+import { ai, configure, getAi } from './index';
+import { deriveAiBaseUrl } from './config';
+const sse = (lines) => new ReadableStream({
+    start(c) {
+        const enc = new TextEncoder();
+        // 故意把行切开成不规则的 chunk，验证跨 chunk 拼接
+        const text = lines.map(l => `${l}\n\n`).join('');
+        for (let i = 0; i < text.length; i += 7)
+            c.enqueue(enc.encode(text.slice(i, i + 7)));
+        c.close();
+    },
+});
+d('deriveAiBaseUrl', () => {
+    it('maps /data/v1 to /v1 and falls back to origin', () => {
+        expect(deriveAiBaseUrl('https://api.chatuapi.com/data/v1')).toBe('https://api.chatuapi.com/v1');
+        expect(deriveAiBaseUrl('http://chatu-function.chatu.svc.cluster.local/data/v1/')).toBe('http://chatu-function.chatu.svc.cluster.local/v1');
+        expect(deriveAiBaseUrl('https://api.test/other')).toBe('https://api.test/v1');
+    });
+});
+d('ai platform driver', () => {
+    it('chat: posts OpenAI-compatible body with Bearer auth and parses content/usage', async () => {
+        const calls = [];
+        const fetchImpl = (async (url, init) => {
+            calls.push({ url, init });
+            return new Response(JSON.stringify({ id: 'x', model: 'gpt-x', choices: [{ index: 0, message: { role: 'assistant', content: 'hello' } }], usage: { prompt_tokens: 3, completion_tokens: 2, total_tokens: 5 } }), { status: 200 });
+        });
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1/', apiKey: 'sk-conv-abc', model: 'default-m', fetchImpl });
+        const r = await ai.chat('hi', { temperature: 0.2, maxTokens: 10, extra: { top_p: 0.9 } });
+        expect(r).toEqual({ content: 'hello', model: 'gpt-x', usage: { promptTokens: 3, completionTokens: 2, totalTokens: 5 } });
+        expect(calls[0].url).toBe('https://api.test/v1/chat/completions');
+        const h = calls[0].init.headers;
+        expect(h.authorization).toBe('Bearer sk-conv-abc');
+        expect(h['content-type']).toBe('application/json');
+        expect(JSON.parse(String(calls[0].init.body))).toEqual({ top_p: 0.9, model: 'default-m', messages: [{ role: 'user', content: 'hi' }], temperature: 0.2, max_tokens: 10 });
+        // 显式 model 覆盖默认；aiBaseUrl 显式覆盖推导
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', aiBaseUrl: 'https://ai.test/v1/', apiKey: 'sk-conv-abc', fetchImpl });
+        await getAi().chat([{ role: 'system', content: 's' }, { role: 'user', content: 'u' }], { model: 'm2' });
+        expect(calls[1].url).toBe('https://ai.test/v1/chat/completions');
+        expect(JSON.parse(String(calls[1].init.body))).toEqual({ model: 'm2', messages: [{ role: 'system', content: 's' }, { role: 'user', content: 'u' }] });
+    });
+    it('chat: non-2xx becomes AppSdkError with server code/status', async () => {
+        const fetchImpl = (async () => new Response(JSON.stringify({ error: { code: 'INSUFFICIENT_POINTS', message: 'no points' } }), { status: 402 }));
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-abc', fetchImpl });
+        await expect(ai.chat('hi')).rejects.toMatchObject({ name: 'AppSdkError', code: 'INSUFFICIENT_POINTS', message: 'no points', status: 402 });
+    });
+    it('stream: yields delta text from SSE and stops at [DONE]', async () => {
+        let body;
+        const fetchImpl = (async (_url, init) => {
+            body = JSON.parse(String(init.body));
+            return new Response(sse([
+                'data: {"choices":[{"delta":{"role":"assistant"}}]}',
+                'data: {"choices":[{"delta":{"content":"Hel"}}]}',
+                ': keep-alive',
+                'data: {"choices":[{"delta":{"content":"lo, "}}]}',
+                'data: {"choices":[{"delta":{"content":"世界"}}]}',
+                'data: [DONE]',
+                'data: {"choices":[{"delta":{"content":"IGNORED"}}]}',
+            ]), { status: 200, headers: { 'content-type': 'text/event-stream' } });
+        });
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-abc', fetchImpl });
+        const parts = [];
+        for await (const t of ai.stream('hi'))
+            parts.push(t);
+        expect(parts).toEqual(['Hel', 'lo, ', '世界']);
+        expect(body).toMatchObject({ stream: true, messages: [{ role: 'user', content: 'hi' }] });
+        expect(body.model).toBeUndefined();
+    });
+    it('models: lists ids', async () => {
+        const fetchImpl = (async () => new Response(JSON.stringify({ object: 'list', data: [{ id: 'a' }, { id: 'b' }] }), { status: 200 }));
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-abc', fetchImpl });
+        expect(await ai.models()).toEqual(['a', 'b']);
+    });
+});
+d('ai without platform config', () => {
+    it('throws AI_NOT_CONFIGURED for memory driver', async () => {
+        configure({ driver: 'memory' });
+        await expect(ai.chat('hi')).rejects.toMatchObject({ code: 'AI_NOT_CONFIGURED' });
+        await expect(ai.models()).rejects.toMatchObject({ code: 'AI_NOT_CONFIGURED' });
+        await expect((async () => { for await (const _ of ai.stream('hi')) { /* noop */ } })()).rejects.toMatchObject({ code: 'AI_NOT_CONFIGURED' });
+    });
+});

package/dist/config.d.ts

@@ -11,6 +11,10 @@ export interface PlatformConfig {
     apiKey: string;
     env: 'dev' | 'prod';
     fetchImpl: typeof fetch;
+    /** OpenAI 兼容的 LLM 中继地址（`{origin}/v1`）：CHATU_AI_URL 显式指定，否则由 CHATU_DATA_URL 去掉 `/data/v1` 推导 */
+    aiBaseUrl: string;
+    /** 默认模型：CHATU_AI_MODEL → PRIMARY_MODEL（沙箱注入的平台默认模型）；都没有则不传，由服务端决定 */
+    aiModel?: string;
 }
 export interface MemoryConfig {
     kind: 'memory';
@@ -37,10 +41,16 @@ export interface ConfigureOptions {
     env?: 'dev' | 'prod';
     driver?: DriverKind;
     fetchImpl?: typeof fetch;
+    /** LLM 中继地址（默认由 baseUrl 推导） */
+    aiBaseUrl?: string;
+    /** LLM 默认模型 */
+    model?: string;
 }
 /** 显式配置（测试或非 env 场景）；不调用则完全由环境变量决定 */
 export declare function configure(options: ConfigureOptions): void;
 export declare function resolveConfig(): ResolvedConfig;
+/** `https://api.chatuapi.com/data/v1` → `https://api.chatuapi.com/v1`（Data API 与 LLM 中继同源） */
+export declare function deriveAiBaseUrl(dataBaseUrl: string): string;
 /** 当前生效的驱动与环境（诊断用，不含密钥） */
 export declare function describe(): {
     driver: DriverKind;

package/dist/config.js

@@ -34,10 +34,31 @@ export function resolveConfig() {
         if (!baseUrl || !apiKey)
             throw new Error('@chatu-ai/app-sdk: platform driver requires CHATU_DATA_URL and CHATU_APP_KEY');
         const dataEnv = (override.env ?? env.CHATU_DATA_ENV ?? 'dev').toLowerCase() === 'prod' ? 'prod' : 'dev';
-        return { kind: 'platform', baseUrl: baseUrl.replace(/\/+$/, ''), apiKey, env: dataEnv, fetchImpl: override.fetchImpl ?? fetch };
+        const normalizedBase = baseUrl.replace(/\/+$/, '');
+        return {
+            kind: 'platform',
+            baseUrl: normalizedBase,
+            apiKey,
+            env: dataEnv,
+            fetchImpl: override.fetchImpl ?? fetch,
+            aiBaseUrl: (override.aiBaseUrl ?? env.CHATU_AI_URL ?? deriveAiBaseUrl(normalizedBase)).replace(/\/+$/, ''),
+            aiModel: override.model ?? env.CHATU_AI_MODEL ?? env.PRIMARY_MODEL,
+        };
     }
     return { kind: 'memory' };
 }
+/** `https://api.chatuapi.com/data/v1` → `https://api.chatuapi.com/v1`（Data API 与 LLM 中继同源） */
+export function deriveAiBaseUrl(dataBaseUrl) {
+    const trimmed = dataBaseUrl.replace(/\/+$/, '');
+    if (/\/data\/v1$/.test(trimmed))
+        return trimmed.replace(/\/data\/v1$/, '/v1');
+    try {
+        return `${new URL(trimmed).origin}/v1`;
+    }
+    catch {
+        return `${trimmed}/v1`;
+    }
+}
 /** 当前生效的驱动与环境（诊断用，不含密钥） */
 export function describe() {
     const c = resolveConfig();

package/dist/index.d.ts

@@ -5,3 +5,5 @@ export type { ConfigureOptions, DriverKind } from './config.js';
 export { AppSdkError } from './errors.js';
 export { storage, getStorage } from './storage.js';
 export type { StorageClient, StorageObject, StorageListResult, UploadUrlResult } from './storage.js';
+export { ai, getAi } from './ai.js';
+export type { AiClient, AiMessage, AiChatOptions, AiChatResult, AiUsage } from './ai.js';

package/dist/index.js

@@ -2,3 +2,4 @@ export { kv, getKv } from './kv.js';
 export { configure, describe } from './config.js';
 export { AppSdkError } from './errors.js';
 export { storage, getStorage } from './storage.js';
+export { ai, getAi } from './ai.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chatu-ai/app-sdk",
-  "version": "0.6.2",
-  "description": "Runtime data SDK for apps generated by ChatU Builder: kv (and more) with platform / memory drivers selected by environment variables",
+  "version": "0.7.0",
+  "description": "Runtime SDK for apps generated by ChatU Builder: kv, storage and ai (OpenAI-compatible LLM relay) with platform / byo / memory drivers selected by environment variables",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,6 +30,8 @@
     "kv",
     "storage",
     "app-sdk",
+    "ai",
+    "llm",
     "nextjs"
   ],
   "publishConfig": {