@visiblebase/core 0.2.0

package/bin/utils/helpers.js

@@ -0,0 +1,192 @@
+/**
+ * 通用工具模块。
+ *
+ * 提供 HTTP 工具函数、SQL 标识符引用、env key 校验等通用辅助。
+ * 所有错误统一抛 ErrorWithStatus，由 router 顶层的 try/catch 转成 JSON Response。
+ *
+ * 零运行时依赖，使用 Web Crypto API 替代 node:crypto。
+ */
+// ===========================================================================
+// JSON / Request 工具
+// ===========================================================================
+/**
+ * 从 Request body 中读取 JSON。
+ */
+export async function readJSON(request) {
+    const text = await request.text();
+    return parseJSONText(text);
+}
+/**
+ * 从已读取的文本中解析 JSON。
+ */
+export function parseJSONText(text) {
+    if (!text) {
+        return {};
+    }
+    return JSON.parse(text);
+}
+/**
+ * 读取 Bearer token。
+ */
+export function bearerToken(request) {
+    const authorization = request.headers.get("authorization");
+    if (!authorization?.startsWith("Bearer ")) {
+        return undefined;
+    }
+    return authorization.slice("Bearer ".length);
+}
+/**
+ * 生成 JSON Response。
+ */
+export function json(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            "content-type": "application/json",
+        },
+    });
+}
+/**
+ * 创建带 HTTP 状态码的错误。
+ */
+export function httpError(statusCode, message) {
+    const error = new Error(message);
+    error.statusCode = statusCode;
+    return error;
+}
+/**
+ * 把 unknown 错误统一成 Error。
+ */
+export function normalizeCaughtError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(String(error));
+}
+// ===========================================================================
+// SQL 辅助
+// ===========================================================================
+/**
+ * SQL 标识符引用（双引号转义）。
+ *
+ * 用于动态拼接 SQL 时安全地引用表名、列名等标识符。
+ */
+export function quoteIdent(value) {
+    return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+// ===========================================================================
+// Env 辅助
+// ===========================================================================
+/**
+ * 标准化 env key。
+ *
+ * 规则：转大写、去首尾空格；只允许 A-Z、0-9、_，且不能以数字开头。
+ */
+export function normalizeEnvKey(value) {
+    const key = String(value || "").trim().toUpperCase();
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(key)) {
+        throw new Error(`invalid env key: ${String(value || "")}`);
+    }
+    return key;
+}
+// ===========================================================================
+// .env 文本解析
+// ===========================================================================
+/**
+ * 解析 .env 文本格式的环境变量（兼容 export 前缀）。
+ *
+ * 纯函数，零依赖，可在任何运行时使用。
+ *
+ * @param raw - .env 文本内容
+ * @returns 解析出的键值对数组
+ */
+export function parseDotenvEntries(raw) {
+    const text = String(raw || "").replace(/^\uFEFF/, "").trim();
+    if (!text)
+        return [];
+    const entries = [];
+    const lines = text.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        // 兼容用户从 shell 里复制 `export KEY=value` 的形式
+        const normalized = trimmed.replace(/^export\s+/, "");
+        const index = normalized.indexOf("=");
+        if (index < 1)
+            continue;
+        const key = normalizeEnvKey(normalized.slice(0, index));
+        const value = stripDotenvQuotes(normalized.slice(index + 1).trim());
+        entries.push({ key, value });
+    }
+    return entries;
+}
+/** 去掉 .env 值的引号包裹 */
+function stripDotenvQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+// ===========================================================================
+// 密钥生成
+// ===========================================================================
+/**
+ * 生成加密级随机字符串（base64url 编码）。
+ *
+ * 使用 Web Crypto API 的 crypto.getRandomValues，
+ * 兼容 Node.js、Cloudflare Workers、Deno、Bun、浏览器等所有现代运行时。
+ *
+ * @param size - 随机字节数，默认 32
+ */
+export function randomSecret(size = 32) {
+    const bytes = crypto.getRandomValues(new Uint8Array(size));
+    return base64UrlEncodeBytes(bytes);
+}
+/**
+ * 将 Uint8Array 编码为 base64url 字符串。
+ *
+ * 与 Buffer.toString("base64url") 行为一致。
+ */
+export function base64UrlEncodeBytes(bytes) {
+    const binary = Array.from(bytes, (b) => String.fromCharCode(b)).join("");
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+/**
+ * 将 base64url 字符串解码为 Uint8Array。
+ *
+ * 与 Buffer.from(str, "base64url") 行为一致。
+ */
+export function base64UrlDecodeBytes(str) {
+    const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(base64);
+    return Uint8Array.from(binary, (c) => c.charCodeAt(0));
+}
+/**
+ * 将字符串编码为 base64url。
+ */
+export function base64UrlEncode(data) {
+    return base64UrlEncodeBytes(new TextEncoder().encode(data));
+}
+/**
+ * 将 base64url 字符串解码为 UTF-8 字符串。
+ */
+export function base64UrlDecode(str) {
+    return new TextDecoder().decode(base64UrlDecodeBytes(str));
+}
+/**
+ * 时间安全的字节比较。
+ *
+ * 替代 node:crypto 的 timingSafeEqual，在所有运行时中行为一致。
+ */
+export function timingSafeEqualBytes(a, b) {
+    if (a.byteLength !== b.byteLength)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.byteLength; i++) {
+        result |= a[i] ^ b[i];
+    }
+    return result === 0;
+}
+//# sourceMappingURL=helpers.js.map

package/bin/utils/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAmB,OAAgB;IAC/D,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IAClC,OAAO,aAAa,CAAI,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAmB,IAAY;IAC1D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAO,CAAC;IACjB,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC3D,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,IAAI,CAAC,IAAa,EAAE,MAAM,GAAG,GAAG;IAC9C,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE;QACxC,MAAM;QACN,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;SACnC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,UAAkB,EAAE,OAAe;IAC3D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,OAAO,CAAoB,CAAC;IACpD,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC;IAC9B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAwB,CAAC;IAClC,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAoB,CAAC;AACrD,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC;AAC/C,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrD,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7D,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAErB,MAAM,OAAO,GAAqC,EAAE,CAAC;IACrD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAElD,yCAAyC;QACzC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,KAAK,GAAG,CAAC;YAAE,SAAS;QAExB,MAAM,GAAG,GAAG,eAAe,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,iBAAiB,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACpE,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,qBAAqB;AACrB,SAAS,iBAAiB,CAAC,KAAa;IACtC,IACE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC9C,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAC9C,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAI,GAAG,EAAE;IACpC,MAAM,KAAK,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3D,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAiB;IACpD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,oBAAoB,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAa,EAAE,CAAa;IAC/D,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,MAAM,KAAK,CAAC,CAAC;AACtB,CAAC"}

package/bin/utils/validation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Runtime 通用校验模块。
+ *
+ * 这个模块放只依赖 JavaScript 运行时的轻量校验函数，避免各业务模块互相复制。
+ */
+/**
+ * 校验非空字符串。
+ */
+export declare function assertName(value: unknown, label: string): asserts value is string;
+/**
+ * 校验函数值。
+ */
+export declare function assertFunction(value: unknown, label: string): asserts value is (...args: unknown[]) => unknown;
+/**
+ * 深拷贝配置对象，避免外部继续修改已注册配置。
+ */
+export declare function clone<T>(value: T): T;
+//# sourceMappingURL=validation.d.ts.map

package/bin/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAIjF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAI9G;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEpC"}

package/bin/utils/validation.js

@@ -0,0 +1,28 @@
+/**
+ * Runtime 通用校验模块。
+ *
+ * 这个模块放只依赖 JavaScript 运行时的轻量校验函数，避免各业务模块互相复制。
+ */
+/**
+ * 校验非空字符串。
+ */
+export function assertName(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new TypeError(`${label} must be a non-empty string`);
+    }
+}
+/**
+ * 校验函数值。
+ */
+export function assertFunction(value, label) {
+    if (typeof value !== "function") {
+        throw new TypeError(`${label} must be a function`);
+    }
+}
+/**
+ * 深拷贝配置对象，避免外部继续修改已注册配置。
+ */
+export function clone(value) {
+    return structuredClone(value);
+}
+//# sourceMappingURL=validation.js.map

package/bin/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc,EAAE,KAAa;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,6BAA6B,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,KAAa;IAC1D,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,qBAAqB,CAAC,CAAC;IACrD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,KAAK,CAAI,KAAQ;IAC/B,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@visiblebase/core",
+  "version": "0.2.0",
+  "description": "VisibleBase runtime-agnostic AI gateway core.",
+  "type": "module",
+  "main": "./bin/index.js",
+  "module": "./bin/index.js",
+  "exports": {
+    ".": {
+      "types": "./bin/index.d.ts",
+      "import": "./bin/index.js"
+    }
+  },
+  "types": "./bin/index.d.ts",
+  "files": [
+    "bin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wangenius/visiblebase.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/wangenius/visiblebase#readme",
+  "bugs": {
+    "url": "https://github.com/wangenius/visiblebase/issues"
+  },
+  "keywords": [
+    "visiblebase",
+    "ai",
+    "runtime",
+    "gateway"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "tsc && tsc -p tsconfig.test.json && node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "ai": "^6.0.168",
+    "drizzle-orm": "^0.45.2",
+    "hono": "^4.1.0"
+  }
+}