unified-keys 0.1.0 → 0.3.0

package/README.md

@@ -51,8 +51,8 @@ const result = await verifyKey(
 ### `client.createKey({ appId, prefix?, credits?, maxUses?, meta?, externalId?, expiresAt?, count? })`
 创建 key。返回 `{ keys: [{ key, keyId }] }`，`key` 是完整明文。`appId` 首次自动注册。
 
-### `verifyKey({ baseUrl }, { key, decrement?, context? })`
-公开验证（无需 rootKey）。`decrement: true` 扣减额度并写 verify log；`false` 只查。
+### `verifyKey({ key, decrement?, autoDelete?, context? })`
+公开验证（无需 rootKey，baseUrl 内置默认）。`decrement: true` 扣减 + 写 verify log；`false` 只查。`autoDelete: true` 扣减后额度用尽（remaining=0）自动删 key（一次性 key，避免 DB 堆积）。SDK 前置 `isValidKeyFormat` 校验，格式不对直接返回不查 DB。
 返回 `{ valid, found, keyId, remaining, maxUses, meta, externalId, appId, enabled, expiresAt, createdAt }`。
 
 ### `client.listKeys({ appId, limit?, offset? })`

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: unified-keys
-description: 当项目需要管理 API key（创建、验证扣减额度、查询使用记录、管理端显示明文）时使用。自建通用 key 服务 keys.932324.xyz，明文存储 + 完整使用记录，npm 包 unified-keys。
+description: 当项目需要管理 API key（创建、验证扣减额度、查询使用记录、管理端显示明文、用尽自动删除）时使用。自建通用 key 服务 keys.932324.xyz，明文存储 + 完整使用记录，npm 包 unified-keys。
 ---
 
 # unified-keys
 
-自建通用 API key 管理 SDK（替代 Unkey）。**明文存储 + 明文返回 + 完整使用记录**。服务跑在 Cloudflare Worker（`keys.932324.xyz`），数据存 D1。
+自建通用 API key 管理 SDK（替代 Unkey）。**明文存储 + 明文返回 + 完整使用记录 + 用尽自动删除**。服务跑在 Cloudflare Worker（`keys.932324.xyz`），数据存 D1。
 
 ## 何时用
 
@@ -13,6 +13,7 @@ description: 当项目需要管理 API key（创建、验证扣减额度、查
 - 需要 verify key + 原子扣减额度（credits）
 - 想看每个 key 的使用历史（谁、何时、扣了几次、退了几次）
 - 想在管理端显示**完整 key 明文**（Unkey 做不到，只给前缀）
+- 一次性 key 用完自动删（避免 DB 堆积无用 key）
 - 多项目共用一个 key 服务（appId 命名空间隔离）
 
 ## 安装
@@ -22,24 +23,15 @@ pnpm add unified-keys
 # 或 npm i unified-keys
 ```
 
-## 服务端点
-
-- **公开 verify**：`POST https://keys.932324.xyz/v1/keys/verify`（无需鉴权，任何持有 key 的人可调）
-- **管理 API**：`https://keys.932324.xyz/v1/*`（需 `Authorization: Bearer <ROOT_KEY>`）
-- 健康检查：`GET https://keys.932324.xyz/v1/health`
-
-ROOT_KEY 联系服务管理员获取。
-
 ## 核心 API
 
+**baseUrl 内置默认**（`https://keys.932324.xyz`），无需传。
+
 ```ts
-import { createClient, verifyKey } from "unified-keys";
+import { createClient, isValidKeyFormat, verifyKey } from "unified-keys";
 
-// 管理客户端（需 rootKey）
-const client = createClient({
-  baseUrl: "https://keys.932324.xyz",
-  rootKey: process.env.KEYS_ROOT_KEY,
-});
+// 管理客户端（需 rootKey；baseUrl 内置）
+const client = createClient({ rootKey: process.env.KEYS_ROOT_KEY });
 
 // 创建 key（明文返回；appId = 项目 slug，首次自动注册）
 const { keys } = await client.createKey({
@@ -50,13 +42,15 @@ const { keys } = await client.createKey({
   meta: { plan: "pro" },   // 任意元数据（可选）
   count: 1,                // 批量创建数
 });
-// keys[0].key = 完整明文（仅创建时与 list/get 返回），keys[0].keyId
+// keys[0].key = 完整明文 `<prefix>_<8位base62>`
 
 // 验证 + 扣减（用户持有明文 key，服务端验证）
-const result = await verifyKey(
-  { baseUrl: "https://keys.932324.xyz" },
-  { key: userKey, decrement: true, context: { username: "alice", ip: "1.2.3.4" } }
-);
+const result = await verifyKey({
+  key: userKey,
+  decrement: true,         // 扣减（默认 true）
+  autoDelete: true,        // 扣减后用尽（remaining=0）自动删 key（一次性 key 用）
+  context: { username: "alice", ip: "1.2.3.4" },  // 写 usage_log
+});
 // { valid, found, keyId, remaining, maxUses, meta, externalId, appId, enabled, expiresAt, createdAt }
 // found=false: key 不存在；valid=false found=true: 存在但禁用/过期/额度耗尽
 
@@ -68,7 +62,7 @@ const { key, usageLogs } = await client.getKey(keyId);
 
 // 查使用记录（核心特性）
 const { logs } = await client.getKeyUsageLogs(keyId, { limit: 50 });
-// logs: [{ event: "verify"|"refund"|"create"|"delete"|"update", creditsBefore, creditsAfter, context, createdAt }]
+// logs: [{ event: "verify"|"refund"|"create"|"delete"|"update"|"disable", creditsBefore, creditsAfter, context, createdAt }]
 
 // 调整额度（refund 恢复）
 await client.updateCredits(keyId, {
@@ -83,35 +77,52 @@ await client.updateKey(keyId, { meta: { plan: "enterprise" }, enabled: false });
 // 删除
 await client.deleteKey(keyId);
 await client.deleteKeys([keyId1, keyId2]);
+
+// 手输校验（isValidKeyFormat 库内置，与 verify 前置校验同源）
+if (!isValidKeyFormat(inputKey)) return invalid();
 ```
 
 ## 特性（区别于 Unkey）
 
 | | unified-keys | Unkey |
 |---|---|---|
-| 明文显示 | ✅ 列表/详情返回完整明文 | ❌ 只给 start 前缀 |
+| 明文显示 | ✅ 列表/详情返回完整明文 | ❌ 只给前缀 |
 | 使用记录 | ✅ 每次 verify/refund/create/delete 写 usage_log | ❌ 只给当前 remaining |
 | verify 延迟 | <5ms（D1 binding 零网络跳） | 50-100ms（公网） |
+| 用尽自动删 | ✅ verify `autoDelete` 选项 | ❌ |
+| 前置格式校验 | ✅ SDK `isValidKeyFormat`，格式不对不查 DB | ❌ |
 | 自托管 | ✅ 自己的 D1 | ❌ SaaS |
 | 原子扣减 | ✅ `UPDATE ... WHERE credits>0 RETURNING` | ✅ |
 
+## verify 选项
+
+| 选项 | 默认 | 说明 |
+|---|---|---|
+| `decrement` | true | true 扣减 + 写 verify log；false 只查 |
+| `autoDelete` | false | 扣减后 remaining=0 自动删 key（一次性 key，避免 DB 堆积无用 key） |
+| `context` | - | 写入 usage_log（{username, ip, source, ...}） |
+
+**SDK 前置校验**：verify 前先 `isValidKeyFormat(key)`，格式不对直接返回 `{valid:false, found:false}`，不查 DB（省时间）。应用也可单独用 `isValidKeyFormat` 做手输校验。
+
 ## event 类型（usage_log）
 
 - `verify`：verify 扣减（含 creditsBefore/After + context）
 - `refund`：updateCredits increment 恢复额度
-- `create` / `delete` / `update` / `disable`
+- `create` / `delete`（含 autoDelete 触发的 exhausted_autodelete）/ `update` / `disable`
 
 ## 集成示例
 
-### Next.js Route Handler（服务端 verify 用户持有 key）
+### Next.js Route Handler（服务端 verify + 一次性 key 用尽自动删）
 ```ts
 import { verifyKey } from "unified-keys";
 export async function POST(req: Request) {
   const { key } = await req.json();
-  const r = await verifyKey(
-    { baseUrl: "https://keys.932324.xyz" },
-    { key, decrement: true, context: { ip: req.headers.get("x-forwarded-for") } }
-  );
+  const r = await verifyKey({
+    key,
+    decrement: true,
+    autoDelete: true,   // 用完自动删
+    context: { ip: req.headers.get("x-forwarded-for") },
+  });
   if (!r.valid) return Response.json({ error: "invalid key" }, { status: 403 });
   // ... 授权逻辑
 }
@@ -120,10 +131,7 @@ export async function POST(req: Request) {
 ### Next.js Server Component（只读查询，不扣减）
 ```ts
 import { verifyKey } from "unified-keys";
-const info = await verifyKey(
-  { baseUrl: "https://keys.932324.xyz" },
-  { key: params.key, decrement: false }
-);
+const info = await verifyKey({ key: params.key, decrement: false });
 if (!info.found || !info.valid) notFound();
 // info.remaining / info.meta / info.expiresAt
 ```
@@ -131,16 +139,21 @@ if (!info.found || !info.valid) notFound();
 ### Cloudflare Worker（管理端）
 ```ts
 import { createClient } from "unified-keys";
-const client = createClient({
-  baseUrl: c.env.KEY_SERVICE_URL,
-  rootKey: c.env.KEY_SERVICE_ROOT_KEY,
-});
+const client = createClient({ rootKey: c.env.KEY_SERVICE_ROOT_KEY });
 await client.createKey({ appId: "my-app", credits: 1 });
 ```
 
+## 服务端点
+
+- **公开 verify**：`POST https://keys.932324.xyz/v1/keys/verify`（无需鉴权，任何持有 key 的人可调）
+- **管理 API**：`https://keys.932324.xyz/v1/*`（需 `Authorization: Bearer <ROOT_KEY>`）
+- 健康检查：`GET https://keys.932324.xyz/v1/health`
+
+ROOT_KEY 联系服务管理员获取。
+
 ## 实现位置（本项目内）
 
 - 服务端：`apps/key-service`（Hono Worker → keys.932324.xyz）
-- SDK：`packages/keys`（发布名 unified-keys）
+- SDK：`packages/keys`（npm `unified-keys`）
 - schema：`packages/db/src/schemas/key-service.ts`（key_apps / key_records / key_usage_logs）
-- 已迁移：github-inviter / user-dashboard（shadcn-proxy / notify-me 仍用 Unkey，待后续）
+- 4 应用全迁移：github-inviter / user-dashboard / notify-me 完整迁移；shadcn-proxy 新用新服务 + Unkey 格式路由 fallback（旧 key 保持可用）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unified-keys",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "自建通用 API key 管理 SDK（明文存储 + 明文返回 + 完整使用记录），调用 keys.932324.xyz 服务",
   "type": "module",
   "main": "./src/index.ts",

package/src/client.ts

@@ -20,6 +20,8 @@ import type {
 	VerifyResult,
 } from "./types";
 
+const DEFAULT_BASE_URL = "https://keys.932324.xyz";
+
 const KEY_FORMAT = /^[a-zA-Z0-9_-]{8,128}$/;
 
 /**
@@ -31,7 +33,7 @@ export function isValidKeyFormat(key: string): boolean {
 }
 
 export function createClient(config: KeyServiceClientConfig): KeyServiceClient {
-	const baseUrl = config.baseUrl.replace(/\/$/, "");
+	const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
 	const rootKey = config.rootKey;
 
 	async function request<T>(
@@ -118,15 +120,12 @@ export function createClient(config: KeyServiceClientConfig): KeyServiceClient {
 }
 
 /**
- * 公开 verify 端点，无需 rootKey。
+ * 公开 verify 端点，无需 rootKey，baseUrl 内置默认。
  * 适合「用户持有明文 key、服务端验证并扣减」的场景。
  */
-export async function verifyKey(
-	config: { baseUrl: string },
-	input: VerifyInput
-): Promise<VerifyResult> {
+export async function verifyKey(input: VerifyInput): Promise<VerifyResult> {
 	if (!isValidKeyFormat(input.key)) return { valid: false, found: false };
-	const baseUrl = config.baseUrl.replace(/\/$/, "");
+	const baseUrl = DEFAULT_BASE_URL;
 	const res = await fetch(`${baseUrl}/v1/keys/verify`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },

package/src/types.ts

@@ -1,8 +1,10 @@
 /** unified-keys SDK 类型定义 */
 
 export interface KeyServiceClientConfig {
-	/** 服务端点，如 https://keys.932324.xyz */
-	baseUrl: string;
+	/**
+	 * 服务端点，默认 https://keys.932324.xyz（自建服务固定，通常无需传）
+	 */
+	baseUrl?: string;
 	/** 管理 API 需要；verify 端点不需要 */
 	rootKey?: string;
 }
@@ -122,6 +124,8 @@ export interface GetKeyResult {
 }
 
 export interface VerifyInput {
+	/** 扣减后额度用尽（remaining=0）时自动删除 key，避免 DB 堆积无用 key */
+	autoDelete?: boolean;
 	/** 上下文，写入 usage_log（如 {username, source, ip}） */
 	context?: Record<string, unknown>;
 	/** 默认 true；false 时只查不扣（写 verify log 但不扣减） */