@chatu-ai/app-sdk 0.4.1 → 0.5.0

package/README.md

@@ -18,6 +18,7 @@ const src = await storage.url('avatars/u1.png', { expiresIn: 3600 })         //
 | 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 |
+| `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 |
 
 Never expose `CHATU_APP_KEY` to the browser. MIT.

package/dist/byo.d.ts

@@ -0,0 +1,11 @@
+import type { ByoConfig } from './config.js';
+import type { KvClient } from './kv.js';
+import type { StorageClient } from './storage.js';
+/**
+ * 模式 A（自带云资源）驱动：
+ * - KV：ioredis（`npm i ioredis`），REDIS_URL；键前缀 CHATU_KV_PREFIX（默认 app:）
+ * - 对象存储：@aws-sdk/client-s3 + @aws-sdk/s3-request-presigner（`npm i @aws-sdk/client-s3 @aws-sdk/s3-request-presigner`），
+ *   S3_ENDPOINT / S3_REGION / S3_BUCKET / S3_ACCESS_KEY / S3_SECRET_KEY / S3_PREFIX / S3_FORCE_PATH_STYLE（腾讯云 COS：endpoint https://cos.<region>.myqcloud.com）
+ */
+export declare function byoKv(cfg: ByoConfig, fallback: KvClient): KvClient;
+export declare function byoStorage(cfg: ByoConfig, fallback: StorageClient): StorageClient;

package/dist/byo.js

@@ -0,0 +1,117 @@
+import { optionalImport } from './config.js';
+import { AppSdkError } from './errors.js';
+/**
+ * 模式 A（自带云资源）驱动：
+ * - KV：ioredis（`npm i ioredis`），REDIS_URL；键前缀 CHATU_KV_PREFIX（默认 app:）
+ * - 对象存储：@aws-sdk/client-s3 + @aws-sdk/s3-request-presigner（`npm i @aws-sdk/client-s3 @aws-sdk/s3-request-presigner`），
+ *   S3_ENDPOINT / S3_REGION / S3_BUCKET / S3_ACCESS_KEY / S3_SECRET_KEY / S3_PREFIX / S3_FORCE_PATH_STYLE（腾讯云 COS：endpoint https://cos.<region>.myqcloud.com）
+ */
+export function byoKv(cfg, fallback) {
+    if (!cfg.redisUrl)
+        return fallback;
+    let clientPromise = null;
+    const client = () => (clientPromise ??= optionalImport('ioredis', 'run `npm i ioredis`').then(m => new (m.default ?? m.Redis ?? m)(cfg.redisUrl, { lazyConnect: false, maxRetriesPerRequest: 2 })));
+    const k = (key) => cfg.kvPrefix + key;
+    const parse = (v) => { if (v === null)
+        return null; try {
+        return JSON.parse(v);
+    }
+    catch {
+        return v;
+    } };
+    return {
+        async get(key) { return parse(await (await client()).get(k(key))); },
+        async set(key, value, opts) { const c = await client(); const v = JSON.stringify(value); if (opts?.ex)
+            await c.set(k(key), v, 'EX', opts.ex);
+        else
+            await c.set(k(key), v); },
+        async del(key) { return (await (await client()).del(k(key))) > 0; },
+        async incr(key, by = 1) { try {
+            return Number(await (await client()).incrby(k(key), by));
+        }
+        catch (e) {
+            throw new AppSdkError('NOT_AN_INTEGER', e?.message ?? 'incr failed');
+        } },
+        async expire(key, seconds) { return (await (await client()).expire(k(key), seconds)) === 1; },
+        async mget(keys) { const vals = await (await client()).mget(keys.map(k)); return vals.map(parse); },
+        async list(prefix = '', opts) {
+            const c = await client();
+            const [next, keys] = await c.scan(opts?.cursor ?? '0', 'MATCH', escapeGlob(k(prefix)) + '*', 'COUNT', opts?.limit ?? 100);
+            return { keys: keys.map((x) => x.slice(cfg.kvPrefix.length)), nextCursor: next === '0' ? null : next };
+        },
+    };
+}
+export function byoStorage(cfg, fallback) {
+    const s3cfg = cfg.s3;
+    if (!s3cfg)
+        return fallback;
+    let mods = null;
+    const load = () => (mods ??= Promise.all([
+        optionalImport('@aws-sdk/client-s3', 'run `npm i @aws-sdk/client-s3 @aws-sdk/s3-request-presigner`'),
+        optionalImport('@aws-sdk/s3-request-presigner', 'run `npm i @aws-sdk/client-s3 @aws-sdk/s3-request-presigner`'),
+    ]).then(([s3, presign]) => ({ s3, presign })));
+    let clientInst = null;
+    const client = async () => {
+        const { s3 } = await load();
+        return (clientInst ??= new s3.S3Client({
+            region: s3cfg.region,
+            endpoint: s3cfg.endpoint,
+            forcePathStyle: s3cfg.forcePathStyle,
+            credentials: { accessKeyId: s3cfg.accessKey, secretAccessKey: s3cfg.secretKey },
+        }));
+    };
+    const K = (key) => s3cfg.prefix + key;
+    return {
+        async put(key, data, opts) {
+            const { s3 } = await load();
+            const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data instanceof Blob ? new Uint8Array(await data.arrayBuffer()) : data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+            await (await client()).send(new s3.PutObjectCommand({ Bucket: s3cfg.bucket, Key: K(key), Body: bytes, ContentType: opts?.contentType }));
+            return { key, size: bytes.byteLength };
+        },
+        async uploadUrl(key, opts) {
+            const { s3, presign } = await load();
+            const url = await presign.getSignedUrl(await client(), new s3.PutObjectCommand({ Bucket: s3cfg.bucket, Key: K(key), ContentType: opts?.contentType }), { expiresIn: 600 });
+            return { url, method: 'PUT', expiresIn: 600, headers: opts?.contentType ? { 'content-type': opts.contentType } : undefined };
+        },
+        async get(key) {
+            const { s3 } = await load();
+            try {
+                const res = await (await client()).send(new s3.GetObjectCommand({ Bucket: s3cfg.bucket, Key: K(key) }));
+                return new Uint8Array(await res.Body.transformToByteArray());
+            }
+            catch (e) {
+                if (e?.name === 'NoSuchKey' || e?.$metadata?.httpStatusCode === 404)
+                    return null;
+                throw e;
+            }
+        },
+        async url(key, opts) {
+            const { s3, presign } = await load();
+            return presign.getSignedUrl(await client(), new s3.GetObjectCommand({ Bucket: s3cfg.bucket, Key: K(key), ResponseContentDisposition: opts?.downloadName ? `attachment; filename="${encodeURIComponent(opts.downloadName)}"` : undefined }), { expiresIn: opts?.expiresIn ?? 600 });
+        },
+        async head(key) {
+            const { s3 } = await load();
+            try {
+                const res = await (await client()).send(new s3.HeadObjectCommand({ Bucket: s3cfg.bucket, Key: K(key) }));
+                return { key, size: Number(res.ContentLength ?? 0), lastModified: res.LastModified ? new Date(res.LastModified).toISOString() : null };
+            }
+            catch (e) {
+                if (e?.name === 'NotFound' || e?.$metadata?.httpStatusCode === 404)
+                    return null;
+                throw e;
+            }
+        },
+        async delete(key) { const { s3 } = await load(); await (await client()).send(new s3.DeleteObjectCommand({ Bucket: s3cfg.bucket, Key: K(key) })); },
+        async list(prefix = '', opts) {
+            const { s3 } = await load();
+            const res = await (await client()).send(new s3.ListObjectsV2Command({ Bucket: s3cfg.bucket, Prefix: K(prefix), MaxKeys: opts?.limit ?? 100, ContinuationToken: opts?.cursor ?? undefined }));
+            return {
+                items: (res.Contents ?? []).map((o) => ({ key: String(o.Key).slice(s3cfg.prefix.length), size: Number(o.Size ?? 0), lastModified: o.LastModified ? new Date(o.LastModified).toISOString() : null })),
+                nextCursor: res.IsTruncated ? (res.NextContinuationToken ?? null) : null,
+            };
+        },
+    };
+}
+function escapeGlob(s) {
+    return s.replace(/[\\*?[\]]/g, m => '\\' + m);
+}

package/dist/config.d.ts

@@ -4,7 +4,7 @@
  * - 都没有 → memory（进程内存，重启即丢；本地开发/无配置降级）
  * 只在服务端使用（Route Handler / Server Component / Server Action）；密钥不得暴露给浏览器。
  */
-export type DriverKind = 'platform' | 'memory';
+export type DriverKind = 'platform' | 'byo' | 'memory';
 export interface PlatformConfig {
     kind: 'platform';
     baseUrl: string;
@@ -15,7 +15,22 @@ export interface PlatformConfig {
 export interface MemoryConfig {
     kind: 'memory';
 }
-export type ResolvedConfig = PlatformConfig | MemoryConfig;
+/** 自带云资源（模式 A）：REDIS_URL → KV；S3_* → 对象存储（腾讯云 COS / MinIO / AWS 等 S3 兼容） */
+export interface ByoConfig {
+    kind: 'byo';
+    redisUrl?: string;
+    kvPrefix: string;
+    s3?: {
+        endpoint?: string;
+        region: string;
+        bucket: string;
+        accessKey: string;
+        secretKey: string;
+        prefix: string;
+        forcePathStyle: boolean;
+    };
+}
+export type ResolvedConfig = PlatformConfig | ByoConfig | MemoryConfig;
 export interface ConfigureOptions {
     baseUrl?: string;
     apiKey?: string;
@@ -31,4 +46,8 @@ export declare function describe(): {
     driver: DriverKind;
     env?: 'dev' | 'prod';
     baseUrl?: string;
+    kv?: string;
+    storage?: string;
 };
+/** 动态加载可选依赖（ioredis / @aws-sdk/*），不参与打包静态分析；缺失时给出可操作的错误 */
+export declare function optionalImport<T = any>(name: string, hint: string): Promise<T>;

package/dist/config.js

@@ -9,7 +9,27 @@ export function resolveConfig() {
     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');
+    const redisUrl = env.REDIS_URL;
+    const s3Bucket = env.S3_BUCKET;
+    const driver = override.driver ?? (baseUrl && apiKey ? 'platform' : redisUrl || s3Bucket ? 'byo' : 'memory');
+    if (driver === 'byo') {
+        return {
+            kind: 'byo',
+            redisUrl,
+            kvPrefix: env.CHATU_KV_PREFIX ?? 'app:',
+            s3: s3Bucket
+                ? {
+                    endpoint: env.S3_ENDPOINT,
+                    region: env.S3_REGION ?? 'us-east-1',
+                    bucket: s3Bucket,
+                    accessKey: env.S3_ACCESS_KEY ?? '',
+                    secretKey: env.S3_SECRET_KEY ?? '',
+                    prefix: env.S3_PREFIX ?? '',
+                    forcePathStyle: (env.S3_FORCE_PATH_STYLE ?? '').toLowerCase() === 'true',
+                }
+                : undefined,
+        };
+    }
     if (driver === 'platform') {
         if (!baseUrl || !apiKey)
             throw new Error('@chatu-ai/app-sdk: platform driver requires CHATU_DATA_URL and CHATU_APP_KEY');
@@ -21,5 +41,19 @@ export function resolveConfig() {
 /** 当前生效的驱动与环境（诊断用，不含密钥） */
 export function describe() {
     const c = resolveConfig();
-    return c.kind === 'platform' ? { driver: 'platform', env: c.env, baseUrl: c.baseUrl } : { driver: 'memory' };
+    if (c.kind === 'platform')
+        return { driver: 'platform', env: c.env, baseUrl: c.baseUrl };
+    if (c.kind === 'byo')
+        return { driver: 'byo', kv: c.redisUrl ? 'redis' : 'memory', storage: c.s3 ? 's3' : 'memory' };
+    return { driver: 'memory' };
+}
+/** 动态加载可选依赖（ioredis / @aws-sdk/*），不参与打包静态分析；缺失时给出可操作的错误 */
+export async function optionalImport(name, hint) {
+    try {
+        const dyn = new Function('m', 'return import(m)');
+        return await dyn(name);
+    }
+    catch {
+        throw new Error(`@chatu-ai/app-sdk: byo driver requires "${name}" — ${hint}`);
+    }
 }

package/dist/kv.js

@@ -1,5 +1,6 @@
 import { resolveConfig } from './config.js';
 import { AppSdkError } from './errors.js';
+import { byoKv } from './byo.js';
 // ---------- platform driver ----------
 function platformKv(cfg) {
     const headers = { 'x-api-key': cfg.apiKey, 'x-chatu-env': cfg.env, 'content-type': 'application/json' };
@@ -67,9 +68,9 @@ 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';
+    const key = cfg.kind === 'platform' ? `platform|${cfg.baseUrl}|${cfg.env}|${cfg.apiKey.slice(-4)}` : cfg.kind === 'byo' ? `byo|${cfg.redisUrl ?? ''}|${cfg.kvPrefix}` : 'memory';
     if (!cached || cached.key !== key)
-        cached = { key, client: cfg.kind === 'platform' ? platformKv(cfg) : memoryKv() };
+        cached = { key, client: cfg.kind === 'platform' ? platformKv(cfg) : cfg.kind === 'byo' ? byoKv(cfg, memoryKv()) : memoryKv() };
     return cached.client;
 }
 /** 便捷单例：`import { kv } from '@chatu-ai/app-sdk'` */

package/dist/kv.test.js

@@ -39,3 +39,16 @@ d('platform driver', () => {
         await expect(kv.get('bad*')).rejects.toMatchObject({ code: 'INVALID_KEY', status: 400 });
     });
 });
+d('byo driver', () => {
+    it('resolves from REDIS_URL / S3_BUCKET and reports missing optional deps clearly', async () => {
+        const proc = globalThis.process;
+        proc.env.REDIS_URL = 'redis://127.0.0.1:1';
+        proc.env.S3_BUCKET = 'b';
+        configure({});
+        expect(describe()).toEqual({ driver: 'byo', kv: 'redis', storage: 's3' });
+        await expect(kv.get('x')).rejects.toThrow(/ioredis|ECONNREFUSED|connect/i);
+        delete proc.env.REDIS_URL;
+        delete proc.env.S3_BUCKET;
+        configure({ driver: 'memory' });
+    });
+});

package/dist/storage.js

@@ -1,5 +1,6 @@
 import { resolveConfig } from './config.js';
 import { AppSdkError } from './errors.js';
+import { byoStorage } from './byo.js';
 function toBytes(data) {
     if (typeof data === 'string')
         return Promise.resolve(new TextEncoder().encode(data));
@@ -96,9 +97,9 @@ function memoryStorage() {
 let cached = null;
 export function getStorage() {
     const cfg = resolveConfig();
-    const key = cfg.kind === 'platform' ? `platform|${cfg.baseUrl}|${cfg.env}|${cfg.apiKey.slice(-4)}` : 'memory';
+    const key = cfg.kind === 'platform' ? `platform|${cfg.baseUrl}|${cfg.env}|${cfg.apiKey.slice(-4)}` : cfg.kind === 'byo' ? `byo|${cfg.s3?.bucket ?? ''}|${cfg.s3?.prefix ?? ''}` : 'memory';
     if (!cached || cached.key !== key)
-        cached = { key, client: cfg.kind === 'platform' ? platformStorage(cfg) : memoryStorage() };
+        cached = { key, client: cfg.kind === 'platform' ? platformStorage(cfg) : cfg.kind === 'byo' ? byoStorage(cfg, memoryStorage()) : memoryStorage() };
     return cached.client;
 }
 export const storage = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatu-ai/app-sdk",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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",
@@ -43,6 +43,22 @@
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
+  "peerDependencies": {
+    "ioredis": ">=5",
+    "@aws-sdk/client-s3": ">=3",
+    "@aws-sdk/s3-request-presigner": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",