unified-keys 0.3.0 → 0.5.0

package/README.md

@@ -48,11 +48,11 @@ const result = await verifyKey(
 ### `createClient({ baseUrl, rootKey })` → client
 管理客户端。`rootKey` 用于管理 API（verify 端点不需要）。
 
-### `client.createKey({ appId, prefix?, credits?, maxUses?, meta?, externalId?, expiresAt?, count? })`
-创建 key。返回 `{ keys: [{ key, keyId }] }`，`key` 是完整明文。`appId` 首次自动注册。
+### `client.createKey({ appId, prefix?, length?, credits?, maxUses?, meta?, externalId?, expiresAt?, count? })`
+创建 key。返回 `{ keys: [{ key, keyId }] }`，`key` 是完整明文（`<prefix>_<base62 length>`）。`appId` 首次自动注册。`length` 默认 8（短期邀请码等）；**长期付费 key 传 16**（≈95 bit 防爆破）。
 
 ### `verifyKey({ key, decrement?, autoDelete?, context? })`
-公开验证（无需 rootKey，baseUrl 内置默认）。`decrement: true` 扣减 + 写 verify log；`false` 只查。`autoDelete: true` 扣减后额度用尽（remaining=0）自动删 key（一次性 key，避免 DB 堆积）。SDK 前置 `isValidKeyFormat` 校验，格式不对直接返回不查 DB。
+公开验证（无需 rootKey，baseUrl 内置默认）。`decrement: true` 扣减 + 写 verify log；`false` 只查。`autoDelete`：扣减后额度用尽（remaining=0）自动删——`true` 立即删；`"3m"`/`"2h"`/`"3d"` 延迟删（set deleteAt，Cron 每 10min 清理过期 key，保留记录供 admin 查看一段时间）。SDK 前置 `isValidKeyFormat` 校验，格式不对直接返回不查 DB。
 返回 `{ valid, found, keyId, remaining, maxUses, meta, externalId, appId, enabled, expiresAt, createdAt }`。
 
 ### `client.listKeys({ appId, limit?, offset? })`

package/SKILL.md

@@ -38,6 +38,7 @@ const { keys } = await client.createKey({
   appId: "my-app",
   credits: 5,              // 初始剩余次数
   maxUses: 5,              // 总额度（0 = 无限）
+  length: 8,               // body 位数（默认 8；长期付费 key 用 16 防爆破）
   externalId: "user-123",  // 应用层关联业务实体（可选）
   meta: { plan: "pro" },   // 任意元数据（可选）
   count: 1,                // 批量创建数
@@ -99,7 +100,7 @@ if (!isValidKeyFormat(inputKey)) return invalid();
 | 选项 | 默认 | 说明 |
 |---|---|---|
 | `decrement` | true | true 扣减 + 写 verify log；false 只查 |
-| `autoDelete` | false | 扣减后 remaining=0 自动删 key（一次性 key，避免 DB 堆积无用 key） |
+| `autoDelete` | false | 扣减后 remaining=0 自动删：`true` 立即删；`"3m"`/`"2h"`/`"3d"` 延迟删（set deleteAt，Cron 每 10min 清理过期 key，保留记录供 admin 查看一段时间） |
 | `context` | - | 写入 usage_log（{username, ip, source, ...}） |
 
 **SDK 前置校验**：verify 前先 `isValidKeyFormat(key)`，格式不对直接返回 `{valid:false, found:false}`，不查 DB（省时间）。应用也可单独用 `isValidKeyFormat` 做手输校验。

package/package.json

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

package/src/types.ts

@@ -37,6 +37,8 @@ export interface CreateKeyInput {
 	expiresAt?: string;
 	/** 应用层关联业务实体（如 github-inviter 的 configSlug） */
 	externalId?: string;
+	/** key body 长度（base62 位数），默认 8；长期付费 key 建议 16（防爆破） */
+	length?: number;
 	/** 总额度（0=无限），默认等于 credits */
 	maxUses?: number;
 	/** 应用层任意元数据 */
@@ -124,8 +126,11 @@ export interface GetKeyResult {
 }
 
 export interface VerifyInput {
-	/** 扣减后额度用尽（remaining=0）时自动删除 key，避免 DB 堆积无用 key */
-	autoDelete?: boolean;
+	/**
+	 * 扣减后额度用尽（remaining=0）自动删除：true 立即删；
+	 * "3m"/"2h"/"3d" 等延迟删（set deleteAt，Cron 定期清理，保留记录一段时间）
+	 */
+	autoDelete?: boolean | string;
 	/** 上下文，写入 usage_log（如 {username, source, ip}） */
 	context?: Record<string, unknown>;
 	/** 默认 true；false 时只查不扣（写 verify log 但不扣减） */