@chatu-ai/app-sdk 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chatu-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @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.
+
+```ts
+import { kv } from '@chatu-ai/app-sdk'   // server-side only (Route Handlers / Server Components / Server Actions)
+
+await kv.set('todos:1', { title: 'hi' }, { ex: 3600 })
+const todo = await kv.get<{ title: string }>('todos:1')
+await kv.incr('views')
+const { keys } = await kv.list('todos:')
+```
+
+| Env | Driver | Notes |
+| --- | --- | --- |
+| `CHATU_DATA_URL` + `CHATU_APP_KEY` (+ `CHATU_DATA_ENV=dev\|prod`) | **platform** — ChatU hosted Data API, metered | set automatically in the Builder preview; copy from the publish panel for your own server |
+| none | **memory** — in-process, lost on restart | local dev / fallback |
+
+Never expose `CHATU_APP_KEY` to the browser. MIT.

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 驱动选择（技术方案 15 §1）：
+ * - CHATU_DATA_URL + CHATU_APP_KEY（或 CHATU_CUSTOMER_API_KEY）→ platform（平台托管 Data API，开发期/线上都可用，按用量计费）
+ * - 都没有 → memory（进程内存，重启即丢；本地开发/无配置降级）
+ * 只在服务端使用（Route Handler / Server Component / Server Action）；密钥不得暴露给浏览器。
+ */
+export type DriverKind = 'platform' | 'memory';
+export interface PlatformConfig {
+    kind: 'platform';
+    baseUrl: string;
+    apiKey: string;
+    env: 'dev' | 'prod';
+    fetchImpl: typeof fetch;
+}
+export interface MemoryConfig {
+    kind: 'memory';
+}
+export type ResolvedConfig = PlatformConfig | MemoryConfig;
+export interface ConfigureOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    env?: 'dev' | 'prod';
+    driver?: DriverKind;
+    fetchImpl?: typeof fetch;
+}
+/** 显式配置（测试或非 env 场景）；不调用则完全由环境变量决定 */
+export declare function configure(options: ConfigureOptions): void;
+export declare function resolveConfig(): ResolvedConfig;
+/** 当前生效的驱动与环境（诊断用，不含密钥） */
+export declare function describe(): {
+    driver: DriverKind;
+    env?: 'dev' | 'prod';
+    baseUrl?: string;
+};

package/dist/config.js

@@ -0,0 +1,25 @@
+let override = {};
+/** 显式配置（测试或非 env 场景）；不调用则完全由环境变量决定 */
+export function configure(options) {
+    override = { ...options };
+}
+export function resolveConfig() {
+    // 不依赖 @types/node：通过 globalThis 读取 process.env
+    const proc = globalThis.process;
+    const env = proc?.env ?? {};
+    const baseUrl = override.baseUrl ?? env.CHATU_DATA_URL;
+    const apiKey = override.apiKey ?? env.CHATU_APP_KEY ?? env.CHATU_CUSTOMER_API_KEY;
+    const driver = override.driver ?? (baseUrl && apiKey ? 'platform' : 'memory');
+    if (driver === 'platform') {
+        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 };
+    }
+    return { kind: 'memory' };
+}
+/** 当前生效的驱动与环境（诊断用，不含密钥） */
+export function describe() {
+    const c = resolveConfig();
+    return c.kind === 'platform' ? { driver: 'platform', env: c.env, baseUrl: c.baseUrl } : { driver: 'memory' };
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class AppSdkError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+export class AppSdkError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'AppSdkError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { kv, getKv } from './kv.js';
+export type { KvClient, KvSetOptions, KvListResult } from './kv.js';
+export { configure, describe } from './config.js';
+export type { ConfigureOptions, DriverKind } from './config.js';
+export { AppSdkError } from './errors.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { kv, getKv } from './kv.js';
+export { configure, describe } from './config.js';
+export { AppSdkError } from './errors.js';

package/dist/kv.d.ts

@@ -0,0 +1,23 @@
+export interface KvSetOptions {
+    ex?: number;
+}
+export interface KvListResult {
+    keys: string[];
+    nextCursor: string | null;
+}
+export interface KvClient {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, opts?: KvSetOptions): Promise<void>;
+    del(key: string): Promise<boolean>;
+    incr(key: string, by?: number): Promise<number>;
+    expire(key: string, seconds: number): Promise<boolean>;
+    mget<T = unknown>(keys: string[]): Promise<Array<T | null>>;
+    list(prefix?: string, opts?: {
+        cursor?: string | null;
+        limit?: number;
+    }): Promise<KvListResult>;
+}
+/** 按当前配置取 KV 客户端（惰性、缓存；configure() 后自动重建） */
+export declare function getKv(): KvClient;
+/** 便捷单例：`import { kv } from '@chatu-ai/app-sdk'` */
+export declare const kv: KvClient;

package/dist/kv.js

@@ -0,0 +1,84 @@
+import { resolveConfig } from './config.js';
+import { AppSdkError } from './errors.js';
+// ---------- platform driver ----------
+function platformKv(cfg) {
+    const headers = { 'x-api-key': cfg.apiKey, 'x-chatu-env': cfg.env, 'content-type': 'application/json' };
+    async function call(method, path, body) {
+        const res = await cfg.fetchImpl(`${cfg.baseUrl}/kv${path}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+        let json = null;
+        try {
+            json = await res.json();
+        }
+        catch { /* ignore */ }
+        if (!res.ok || json?.ok === false) {
+            throw new AppSdkError(json?.error ?? `HTTP_${res.status}`, json?.message ?? `kv ${method} ${path} failed (${res.status})`, res.status);
+        }
+        return json;
+    }
+    const enc = (key) => key.split('/').map(encodeURIComponent).join('/');
+    return {
+        async get(key) { const r = await call('GET', `/${enc(key)}`); return r.exists ? r.value : null; },
+        async set(key, value, opts) { await call('PUT', `/${enc(key)}`, { value, ex: opts?.ex }); },
+        async del(key) { const r = await call('DELETE', `/${enc(key)}`); return r.removed; },
+        async incr(key, by = 1) { const r = await call('POST', '/incr', { key, by }); return r.value; },
+        async expire(key, seconds) { const r = await call('POST', '/expire', { key, seconds }); return r.applied; },
+        async mget(keys) { const r = await call('POST', '/mget', { keys }); return r.items.map(i => (i.exists ? i.value : null)); },
+        async list(prefix = '', opts) {
+            const q = new URLSearchParams({ prefix, limit: String(opts?.limit ?? 100) });
+            if (opts?.cursor)
+                q.set('cursor', opts.cursor);
+            const r = await call('GET', `?${q.toString()}`);
+            return { keys: r.keys, nextCursor: r.nextCursor ?? null };
+        },
+    };
+}
+// ---------- memory driver ----------
+function memoryKv() {
+    const store = new Map();
+    const live = (key) => {
+        const e = store.get(key);
+        if (!e)
+            return null;
+        if (e.expiresAt !== undefined && Date.now() > e.expiresAt) {
+            store.delete(key);
+            return null;
+        }
+        return e;
+    };
+    return {
+        async get(key) { return live(key)?.value ?? null; },
+        async set(key, value, opts) { store.set(key, { value, expiresAt: opts?.ex ? Date.now() + opts.ex * 1000 : undefined }); },
+        async del(key) { return store.delete(key); },
+        async incr(key, by = 1) { const cur = Number(live(key)?.value ?? 0); if (!Number.isInteger(cur))
+            throw new AppSdkError('NOT_AN_INTEGER', 'value is not an integer'); const next = cur + by; store.set(key, { value: next }); return next; },
+        async expire(key, seconds) { const e = live(key); if (!e)
+            return false; e.expiresAt = Date.now() + seconds * 1000; return true; },
+        async mget(keys) { return keys.map(k => live(k)?.value ?? null); },
+        async list(prefix = '', opts) {
+            const all = [...store.keys()].filter(k => k.startsWith(prefix) && live(k)).sort();
+            const start = opts?.cursor ? Number(opts.cursor) : 0;
+            const limit = opts?.limit ?? 100;
+            const page = all.slice(start, start + limit);
+            return { keys: page, nextCursor: start + limit < all.length ? String(start + limit) : null };
+        },
+    };
+}
+let cached = null;
+/** 按当前配置取 KV 客户端（惰性、缓存；configure() 后自动重建） */
+export function getKv() {
+    const cfg = resolveConfig();
+    const key = cfg.kind === 'platform' ? `platform|${cfg.baseUrl}|${cfg.env}|${cfg.apiKey.slice(-4)}` : 'memory';
+    if (!cached || cached.key !== key)
+        cached = { key, client: cfg.kind === 'platform' ? platformKv(cfg) : memoryKv() };
+    return cached.client;
+}
+/** 便捷单例：`import { kv } from '@chatu-ai/app-sdk'` */
+export const kv = {
+    get: (k) => getKv().get(k),
+    set: (k, v, o) => getKv().set(k, v, o),
+    del: (k) => getKv().del(k),
+    incr: (k, b) => getKv().incr(k, b),
+    expire: (k, s) => getKv().expire(k, s),
+    mget: (ks) => getKv().mget(ks),
+    list: (p, o) => getKv().list(p, o),
+};

package/dist/kv.test.d.ts

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

package/dist/kv.test.js

@@ -0,0 +1,41 @@
+import { beforeEach, describe as d, expect, it } from 'vitest';
+import { configure, describe, getKv, kv } from './index';
+d('memory driver', () => {
+    beforeEach(() => configure({ driver: 'memory' }));
+    it('round-trips, ttl, incr, list', async () => {
+        expect(describe().driver).toBe('memory');
+        await kv.set('todos:1', { a: 1 });
+        expect(await kv.get('todos:1')).toEqual({ a: 1 });
+        expect(await kv.incr('views')).toBe(1);
+        expect(await kv.incr('views', 5)).toBe(6);
+        await kv.set('todos:2', 'x', { ex: 1 });
+        expect((await kv.list('todos:')).keys).toEqual(['todos:1', 'todos:2']);
+        expect(await kv.mget(['todos:1', 'nope'])).toEqual([{ a: 1 }, null]);
+        expect(await kv.del('todos:1')).toBe(true);
+    });
+});
+d('platform driver', () => {
+    it('sends x-api-key / x-chatu-env and unwraps responses', async () => {
+        const calls = [];
+        const fetchImpl = (async (url, init) => {
+            calls.push({ url, init });
+            if (init.method === 'GET' && url.endsWith('/kv/todos%3A1'))
+                return new Response(JSON.stringify({ ok: true, exists: true, value: { a: 1 } }), { status: 200 });
+            if (init.method === 'PUT')
+                return new Response(JSON.stringify({ ok: true }), { status: 200 });
+            if (url.endsWith('/kv/incr'))
+                return new Response(JSON.stringify({ ok: true, value: 7 }), { status: 200 });
+            return new Response(JSON.stringify({ ok: false, error: 'INVALID_KEY' }), { status: 400 });
+        });
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1/', apiKey: 'sk-conv-abc', env: 'prod', fetchImpl });
+        expect(describe()).toEqual({ driver: 'platform', env: 'prod', baseUrl: 'https://api.test/data/v1' });
+        await getKv().set('todos:1', { a: 1 }, { ex: 60 });
+        expect(await kv.get('todos:1')).toEqual({ a: 1 });
+        expect(await kv.incr('views', 7)).toBe(7);
+        const h = calls[0].init.headers;
+        expect(h['x-api-key']).toBe('sk-conv-abc');
+        expect(h['x-chatu-env']).toBe('prod');
+        expect(JSON.parse(String(calls[0].init.body))).toEqual({ value: { a: 1 }, ex: 60 });
+        await expect(kv.get('bad*')).rejects.toMatchObject({ code: 'INVALID_KEY', status: 400 });
+    });
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@chatu-ai/app-sdk",
+  "version": "0.2.1",
+  "description": "Runtime data SDK for apps generated by ChatU Builder: kv (and more) with platform / memory drivers selected by environment variables",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatu-ai/chatu-builder-sdk.git",
+    "directory": "packages/app-sdk"
+  },
+  "homepage": "https://github.com/chatu-ai/chatu-builder-sdk/tree/main/packages/app-sdk#readme",
+  "bugs": "https://github.com/chatu-ai/chatu-builder-sdk/issues",
+  "keywords": [
+    "chatu",
+    "builder",
+    "kv",
+    "storage",
+    "app-sdk",
+    "nextjs"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}