@chatu-ai/app-sdk 0.2.2 → 0.3.1

package/README.md

@@ -3,12 +3,16 @@
 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)
+import { kv, storage } 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:')
+
+await storage.put('avatars/u1.png', bytes, { contentType: 'image/png' })   // ≤5MB server-side
+const { url } = await storage.uploadUrl('uploads/big.mp4', { contentType: 'video/mp4' })  // hand to the browser: fetch(url, { method: 'PUT', body: file })
+const src = await storage.url('avatars/u1.png', { expiresIn: 3600 })         // temporary link for <img src>
 ```
 
 | Env | Driver | Notes |

package/dist/index.d.ts

@@ -3,3 +3,5 @@ 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';
+export { storage, getStorage } from './storage.js';
+export type { StorageClient, StorageObject, StorageListResult, UploadUrlResult } from './storage.js';

package/dist/index.js

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

package/dist/storage.d.ts

@@ -0,0 +1,44 @@
+export interface StorageObject {
+    key: string;
+    size: number;
+    lastModified?: string | null;
+}
+export interface StorageListResult {
+    items: StorageObject[];
+    nextCursor: string | null;
+}
+export interface UploadUrlResult {
+    url: string;
+    method: 'PUT';
+    expiresIn: number;
+    headers?: Record<string, string>;
+}
+export interface StorageClient {
+    /** 服务端小文件直传（≤5MB） */
+    put(key: string, data: Uint8Array | ArrayBuffer | string | Blob, opts?: {
+        contentType?: string;
+    }): Promise<{
+        key: string;
+        size: number;
+    }>;
+    /** 浏览器直传：返回预签名 PUT 地址（把它交给前端 fetch(url, { method:'PUT', body:file })） */
+    uploadUrl(key: string, opts?: {
+        contentType?: string;
+        size?: number;
+    }): Promise<UploadUrlResult>;
+    /** 读取对象内容（服务端） */
+    get(key: string): Promise<Uint8Array | null>;
+    /** 临时访问地址（默认 10 分钟；可指定秒数、下载文件名）—— 用于 <img src> / 下载链接 */
+    url(key: string, opts?: {
+        expiresIn?: number;
+        downloadName?: string;
+    }): Promise<string>;
+    head(key: string): Promise<StorageObject | null>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, opts?: {
+        cursor?: string | null;
+        limit?: number;
+    }): Promise<StorageListResult>;
+}
+export declare function getStorage(): StorageClient;
+export declare const storage: StorageClient;

package/dist/storage.js

@@ -0,0 +1,112 @@
+import { resolveConfig } from './config.js';
+import { AppSdkError } from './errors.js';
+function toBytes(data) {
+    if (typeof data === 'string')
+        return Promise.resolve(new TextEncoder().encode(data));
+    if (data instanceof Uint8Array)
+        return Promise.resolve(data);
+    if (data instanceof ArrayBuffer)
+        return Promise.resolve(new Uint8Array(data));
+    return data.arrayBuffer().then(b => new Uint8Array(b));
+}
+// ---------- platform driver ----------
+function platformStorage(cfg) {
+    const base = { 'x-api-key': cfg.apiKey, 'x-chatu-env': cfg.env };
+    const enc = (key) => key.split('/').map(encodeURIComponent).join('/');
+    async function json(method, path, body) {
+        const res = await cfg.fetchImpl(`${cfg.baseUrl}/storage${path}`, { method, headers: { ...base, 'content-type': 'application/json' }, body: body === undefined ? undefined : JSON.stringify(body) });
+        let j = null;
+        try {
+            j = await res.json();
+        }
+        catch { /* ignore */ }
+        if (!res.ok || j?.ok === false)
+            throw new AppSdkError(j?.error ?? `HTTP_${res.status}`, j?.message ?? `storage ${method} ${path} failed (${res.status})`, res.status);
+        return j;
+    }
+    return {
+        async put(key, data, opts) {
+            const bytes = await toBytes(data);
+            const res = await cfg.fetchImpl(`${cfg.baseUrl}/storage/${enc(key)}`, { method: 'PUT', headers: { ...base, 'content-type': opts?.contentType ?? 'application/octet-stream' }, body: bytes });
+            let j = null;
+            try {
+                j = await res.json();
+            }
+            catch { /* ignore */ }
+            if (!res.ok || j?.ok === false)
+                throw new AppSdkError(j?.error ?? `HTTP_${res.status}`, j?.message ?? `storage put failed (${res.status})`, res.status);
+            return { key, size: j.size ?? bytes.byteLength };
+        },
+        async uploadUrl(key, opts) {
+            const r = await json('POST', '/upload-url', { key, contentType: opts?.contentType, size: opts?.size });
+            return { url: r.url, method: 'PUT', expiresIn: r.expiresIn, headers: r.headers?.contentType ? { 'content-type': r.headers.contentType } : undefined };
+        },
+        async get(key) {
+            const r = await json('POST', '/sign', { key });
+            const res = await cfg.fetchImpl(r.url);
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new AppSdkError(`HTTP_${res.status}`, `storage get failed (${res.status})`, res.status);
+            return new Uint8Array(await res.arrayBuffer());
+        },
+        async url(key, opts) {
+            const r = await json('POST', '/sign', { key, expiresIn: opts?.expiresIn, downloadName: opts?.downloadName });
+            return r.url;
+        },
+        async head(key) {
+            const res = await cfg.fetchImpl(`${cfg.baseUrl}/storage/${enc(key)}?meta=1`, { headers: base });
+            if (res.status === 404)
+                return null;
+            const j = await res.json().catch(() => null);
+            if (!res.ok || j?.ok === false)
+                throw new AppSdkError(j?.error ?? `HTTP_${res.status}`, j?.message ?? 'storage head failed', res.status);
+            return { key, size: j.size, lastModified: j.lastModified ?? null };
+        },
+        async delete(key) { await json('DELETE', `/${enc(key)}`); },
+        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 json('GET', `?${q.toString()}`);
+            return { items: r.items, nextCursor: r.nextCursor ?? null };
+        },
+    };
+}
+// ---------- memory driver ----------
+function memoryStorage() {
+    const store = new Map();
+    return {
+        async put(key, data, opts) { const bytes = await toBytes(data); store.set(key, { bytes, contentType: opts?.contentType, at: new Date().toISOString() }); return { key, size: bytes.byteLength }; },
+        async uploadUrl(key) { return { url: `memory://${key}`, method: 'PUT', expiresIn: 0 }; },
+        async get(key) { return store.get(key)?.bytes ?? null; },
+        async url(key) { const e = store.get(key); if (!e)
+            return `memory://${key}`; const b64 = btoa(String.fromCharCode(...e.bytes)); return `data:${e.contentType ?? 'application/octet-stream'};base64,${b64}`; },
+        async head(key) { const e = store.get(key); return e ? { key, size: e.bytes.byteLength, lastModified: e.at } : null; },
+        async delete(key) { store.delete(key); },
+        async list(prefix = '', opts) {
+            const all = [...store.entries()].filter(([k]) => k.startsWith(prefix)).sort(([a], [b]) => a.localeCompare(b));
+            const start = opts?.cursor ? Number(opts.cursor) : 0;
+            const limit = opts?.limit ?? 100;
+            const page = all.slice(start, start + limit).map(([key, e]) => ({ key, size: e.bytes.byteLength, lastModified: e.at }));
+            return { items: page, nextCursor: start + limit < all.length ? String(start + limit) : null };
+        },
+    };
+}
+let cached = null;
+export function getStorage() {
+    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' ? platformStorage(cfg) : memoryStorage() };
+    return cached.client;
+}
+export const storage = {
+    put: (k, d, o) => getStorage().put(k, d, o),
+    uploadUrl: (k, o) => getStorage().uploadUrl(k, o),
+    get: (k) => getStorage().get(k),
+    url: (k, o) => getStorage().url(k, o),
+    head: (k) => getStorage().head(k),
+    delete: (k) => getStorage().delete(k),
+    list: (p, o) => getStorage().list(p, o),
+};

package/dist/storage.test.d.ts

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

package/dist/storage.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { configure, getStorage, storage } from './index';
+describe('storage memory driver', () => {
+    it('put/get/head/list/delete', async () => {
+        configure({ driver: 'memory' });
+        await storage.put('img/a.txt', 'hello', { contentType: 'text/plain' });
+        expect(new TextDecoder().decode((await storage.get('img/a.txt')))).toBe('hello');
+        expect((await storage.head('img/a.txt'))?.size).toBe(5);
+        expect((await storage.url('img/a.txt')).startsWith('data:text/plain;base64,')).toBe(true);
+        expect((await storage.list('img/')).items.map(i => i.key)).toEqual(['img/a.txt']);
+        await storage.delete('img/a.txt');
+        expect(await storage.get('img/a.txt')).toBeNull();
+    });
+});
+describe('storage platform driver', () => {
+    it('put sends bytes with api key; url signs; list parses', async () => {
+        const calls = [];
+        const fetchImpl = (async (url, init) => {
+            calls.push({ url, init });
+            if (init?.method === 'PUT')
+                return new Response(JSON.stringify({ ok: true, key: 'a/b.png', size: 3 }), { status: 200 });
+            if (url.endsWith('/storage/sign'))
+                return new Response(JSON.stringify({ ok: true, url: 'https://cos/signed' }), { status: 200 });
+            if (url.includes('/storage?'))
+                return new Response(JSON.stringify({ ok: true, items: [{ key: 'a/b.png', size: 3 }], nextCursor: null }), { status: 200 });
+            if (url.endsWith('/storage/upload-url'))
+                return new Response(JSON.stringify({ ok: true, url: 'https://cos/put', expiresIn: 600, headers: { contentType: 'image/png' } }), { status: 200 });
+            return new Response(JSON.stringify({ ok: false, error: 'PAYMENT_REQUIRED' }), { status: 402 });
+        });
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-x', env: 'dev', fetchImpl });
+        const s = getStorage();
+        expect(await s.put('a/b.png', new Uint8Array([1, 2, 3]), { contentType: 'image/png' })).toEqual({ key: 'a/b.png', size: 3 });
+        expect(calls[0].url).toBe('https://api.test/data/v1/storage/a/b.png');
+        expect(calls[0].init.headers['x-api-key']).toBe('sk-conv-x');
+        expect(await s.url('a/b.png', { expiresIn: 60 })).toBe('https://cos/signed');
+        expect((await s.list('a/')).items[0].key).toBe('a/b.png');
+        expect((await s.uploadUrl('a/c.png', { contentType: 'image/png' })).headers).toEqual({ 'content-type': 'image/png' });
+        await expect(s.delete('zzz')).rejects.toMatchObject({ code: 'PAYMENT_REQUIRED', status: 402 });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatu-ai/app-sdk",
-  "version": "0.2.2",
+  "version": "0.3.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",