@visiblebase/plugin-usage 0.1.4

package/README.md

@@ -0,0 +1,34 @@
+# @visiblebase/plugin-usage
+
+VisibleBase 官方 usage 记录插件。
+
+## 安装
+
+```bash
+pnpm add @visiblebase/plugin-usage
+```
+
+## 使用
+
+```ts
+import { Base } from "@visiblebase/base";
+import { usagePlugin } from "@visiblebase/plugin-usage";
+
+const base = new Base({
+  plugins: [
+    usagePlugin({
+      record_errors: true,
+    }),
+  ],
+});
+```
+
+插件会自动创建 `visiblebase_usage_events` 表，并通过 service hook 记录调用事件。
+
+## 路由
+
+- `GET /api/admin/plugins/usage/events`
+- `GET /api/admin/plugins/usage/summary`
+- `GET /v1/plugins/usage/me`
+
+`summary` 会按 product、service 和状态汇总调用次数。

package/bin/index.d.ts

@@ -0,0 +1,173 @@
+/**
+ * VisibleBase 官方 Usage 插件。
+ *
+ * 通过全局 hook 记录 service 调用事件。
+ * 兼容 Node.js 和 Cloudflare Workers（使用 Web Crypto API）。
+ */
+import type { BasePlugin } from "@visiblebase/core";
+export interface UsagePluginOptions {
+    /** 是否记录失败调用 */
+    record_errors?: boolean;
+}
+/** Usage 事件表 */
+export declare const usageEvents: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "visiblebase_usage_events";
+    schema: undefined;
+    columns: {
+        event_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "event_id";
+            tableName: "visiblebase_usage_events";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        product_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "product_id";
+            tableName: "visiblebase_usage_events";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        user_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "user_id";
+            tableName: "visiblebase_usage_events";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        service: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "service";
+            tableName: "visiblebase_usage_events";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        model_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "model_id";
+            tableName: "visiblebase_usage_events";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "status";
+            tableName: "visiblebase_usage_events";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        metadata_json: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "metadata_json";
+            tableName: "visiblebase_usage_events";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        created_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "visiblebase_usage_events";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+    };
+    dialect: "sqlite";
+}>;
+export declare function usagePlugin(options?: UsagePluginOptions): BasePlugin;
+//# sourceMappingURL=index.d.ts.map

package/bin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,mBAAmB,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,eAAe;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,gBAAgB;AAChB,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAStB,CAAC;AAEH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,UAAU,CAwDxE"}

package/bin/index.js

@@ -0,0 +1,115 @@
+/**
+ * VisibleBase 官方 Usage 插件。
+ *
+ * 通过全局 hook 记录 service 调用事件。
+ * 兼容 Node.js 和 Cloudflare Workers（使用 Web Crypto API）。
+ */
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+/** Usage 事件表 */
+export const usageEvents = sqliteTable("visiblebase_usage_events", {
+    event_id: text("event_id").primaryKey(),
+    product_id: text("product_id").notNull(),
+    user_id: text("user_id").notNull(),
+    service: text("service").notNull(),
+    model_id: text("model_id").notNull(),
+    status: text("status").notNull(),
+    metadata_json: text("metadata_json").notNull(),
+    created_at: text("created_at").notNull(),
+});
+export function usagePlugin(options = {}) {
+    return {
+        id: "usage",
+        name: "Usage",
+        version: "0.1.0",
+        schema: { events: usageEvents },
+        install(ctx) {
+            const events = ctx.table("events");
+            ctx.hook.after(async (serviceCtx) => {
+                if (!shouldRecordUsage(serviceCtx))
+                    return;
+                await events.insert(createUsageEvent(serviceCtx, "success"));
+            });
+            if (options.record_errors) {
+                ctx.hook.onError(async (serviceCtx) => {
+                    if (!shouldRecordUsage(serviceCtx))
+                        return;
+                    await events.insert(createUsageEvent(serviceCtx, "error"));
+                });
+            }
+            ctx.route({
+                method: "GET",
+                path: "/events",
+                auth: "admin",
+                async handler(requestCtx) {
+                    return requestCtx.jsonResponse({ items: await events.select() });
+                },
+            });
+            ctx.route({
+                method: "GET",
+                path: "/summary",
+                auth: "admin",
+                async handler(requestCtx) {
+                    return requestCtx.jsonResponse({
+                        items: summarizeUsage(await events.select()),
+                    });
+                },
+            });
+            ctx.route({
+                method: "GET",
+                path: "/me",
+                auth: "user",
+                async handler(requestCtx) {
+                    return requestCtx.jsonResponse({
+                        items: await events.select({
+                            user_id: requestCtx.user?.user_id ?? "",
+                            product_id: requestCtx.product?.product_id ?? "",
+                        }),
+                    });
+                },
+            });
+        },
+    };
+}
+/**
+ * 只记录真实用户侧调用。
+ *
+ * 管理端操作没有 user/product 上下文，usage 插件自己的查询也不应反过来
+ * 产生 usage 事件，否则统计接口会污染自身结果。
+ */
+function shouldRecordUsage(ctx) {
+    return Boolean(ctx.user?.user_id && ctx.product?.product_id && ctx.service?.id !== "usage");
+}
+function createUsageEvent(ctx, status) {
+    return {
+        event_id: `usage_${randomId()}`,
+        product_id: ctx.product?.product_id ?? "",
+        user_id: ctx.user?.user_id ?? "",
+        service: ctx.service?.id ?? "",
+        model_id: ctx.variant?.id ?? "",
+        status,
+        metadata_json: JSON.stringify({
+            variant: ctx.variant?.id,
+            started_at: ctx.started_at?.toISOString(),
+            ended_at: ctx.ended_at?.toISOString(),
+            error: ctx.error?.message,
+        }),
+        created_at: new Date().toISOString(),
+    };
+}
+function summarizeUsage(rows) {
+    const byKey = new Map();
+    for (const row of rows) {
+        const key = `${row.product_id}\u0000${row.service}\u0000${row.status}`;
+        const current = byKey.get(key) ?? { product_id: row.product_id, service: row.service, status: row.status, count: 0 };
+        current.count += 1;
+        byKey.set(key, current);
+    }
+    return [...byKey.values()].sort((a, b) => `${a.product_id}:${a.service}:${a.status}`.localeCompare(`${b.product_id}:${b.service}:${b.status}`));
+}
+/** 生成随机 ID（兼容 Node 和 Workers） */
+function randomId() {
+    const buf = new Uint8Array(12);
+    crypto.getRandomValues(buf);
+    return btoa(String.fromCharCode(...buf)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+//# sourceMappingURL=index.js.map

package/bin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAQ5D,gBAAgB;AAChB,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC,0BAA0B,EAAE;IACjE,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,UAAU,EAAE;IACvC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IACxC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IAClC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IAClC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE;IACpC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE;IAChC,aAAa,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE;IAC9C,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;CACzC,CAAC,CAAC;AAEH,MAAM,UAAU,WAAW,CAAC,UAA8B,EAAE;IAC1D,OAAO;QACL,EAAE,EAAE,OAAO;QACX,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,OAAO;QAChB,MAAM,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE;QAC/B,OAAO,CAAC,GAAG;YACT,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAgB,QAAQ,CAAC,CAAC;YAElD,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;gBAClC,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC;oBAAE,OAAO;gBAC3C,MAAM,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;YAC/D,CAAC,CAAC,CAAC;YAEH,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;gBAC1B,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;oBACpC,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC;wBAAE,OAAO;oBAC3C,MAAM,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC7D,CAAC,CAAC,CAAC;YACL,CAAC;YAED,GAAG,CAAC,KAAK,CAAC;gBACR,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,OAAO;gBACb,KAAK,CAAC,OAAO,CAAC,UAAU;oBACtB,OAAO,UAAU,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBACnE,CAAC;aACF,CAAC,CAAC;YAEH,GAAG,CAAC,KAAK,CAAC;gBACR,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,OAAO;gBACb,KAAK,CAAC,OAAO,CAAC,UAAU;oBACtB,OAAO,UAAU,CAAC,YAAY,CAAC;wBAC7B,KAAK,EAAE,cAAc,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;qBAC7C,CAAC,CAAC;gBACL,CAAC;aACF,CAAC,CAAC;YAEH,GAAG,CAAC,KAAK,CAAC;gBACR,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,MAAM;gBACZ,KAAK,CAAC,OAAO,CAAC,UAAU;oBACtB,OAAO,UAAU,CAAC,YAAY,CAAC;wBAC7B,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC;4BACzB,OAAO,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE;4BACvC,UAAU,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,IAAI,EAAE;yBACjD,CAAC;qBACH,CAAC,CAAC;gBACL,CAAC;aACF,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAY;IACrC,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,GAAG,CAAC,OAAO,EAAE,UAAU,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC;AAC9F,CAAC;AAQD,SAAS,gBAAgB,CAAC,GAAY,EAAE,MAA2B;IACjE,OAAO;QACL,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAAE;QAC/B,UAAU,EAAE,GAAG,CAAC,OAAO,EAAE,UAAU,IAAI,EAAE;QACzC,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE;QAChC,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE;QAC9B,QAAQ,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE;QAC/B,MAAM;QACN,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC;YAC5B,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE;YACxB,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE;YACzC,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE;YACrC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,OAAO;SAC1B,CAAC;QACF,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACrC,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,IAAqB;IAC3C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkF,CAAC;IACxG,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,UAAU,SAAS,GAAG,CAAC,OAAO,SAAS,GAAG,CAAC,MAAM,EAAE,CAAC;QACvE,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACrH,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;QACnB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACvC,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CACrG,CAAC;AACJ,CAAC;AAED,iCAAiC;AACjC,SAAS,QAAQ;IACf,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IAC/B,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACtG,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@visiblebase/plugin-usage",
+  "version": "0.1.4",
+  "description": "VisibleBase usage plugin for recording service calls.",
+  "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/plugin-usage"
+  },
+  "homepage": "https://github.com/wangenius/visiblebase#readme",
+  "bugs": {
+    "url": "https://github.com/wangenius/visiblebase/issues"
+  },
+  "keywords": [
+    "visiblebase",
+    "usage",
+    "plugin",
+    "serverbase"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "@visiblebase/node": "0.1.2"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "@visiblebase/core": "0.2.2"
+  },
+  "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"
+  }
+}