unified-keys 0.7.0 → 0.8.0

package/SKILL.md

@@ -49,7 +49,7 @@ const { keys } = await client.createKey({
   externalId: "user-123",     // 应用层关联业务实体（可选）
   meta: { plan: "pro" },      // 任意元数据（可选）
   rateLimit: { max: 60, windowSec: 60 },  // 限流（max 不传 = 不限速）
-  autoBan: { threshold: 10, windowSec: 600, maxViolations: 3, durationSec: 3600 },
+  autoBan: { pause: { threshold: 10, windowSec: 600, durationSec: 3600 }, banAfter: 3 },
 });
 
 // 公开只读校验（无需 rootKey，不扣减不删）
@@ -108,20 +108,27 @@ if (!r.valid) return res.status(403).json({ error: "Key 无效" });
 | check/verify 拆分 | ✅ 公开只读 vs 管理扣减 | ❌ 单端点 |
 | 用尽自动删 | ✅ autoDelete（createKey 预设） | ❌ |
 | 永久痕迹 | ✅ soft delete 反查 | ❌ 真删丢痕迹 |
-| 限流 / 自动封禁 | ✅ DO 滑动窗口 / 渐进式·直接 | ❌ |
+| 限流 / 自动封禁 | ✅ DO SQLite 滑动窗口 / pause·ban·渐进 | ❌ |
 | 前置格式校验 | ✅ SDK isValidKeyFormat | ❌ |
 
-## 自动封禁（autoBan）
+## 自动处罚（autoBan）
 
-**渐进式**（默认）：违规累计达 maxViolations 永久 ban，前 N-1 次 pause。
+`pause` / `ban` 互斥，`banAfter` 渐进式升级。三种模式：
+
+**纯暂停**：窗口内 rate_limited 达 `pause.threshold` → 暂停（`pauseCount++`）。
+```jsonc
+{ "pause": { "threshold": 10, "windowSec": 600, "durationSec": 3600 } }
+```
+**直接封禁**：窗口内 rate_limited 达 `ban.threshold` → 永久 ban。
 ```jsonc
-{ "threshold": 10, "windowSec": 600, "maxViolations": 3, "durationSec": 3600 }
+{ "ban": { "threshold": 15, "windowSec": 600 } }
 ```
-**直接**（`mode: "direct"`）：单次达阈值即 action。
+**渐进**（先 pause，累计 N 次升级 ban）：`pause` + `banAfter`。
 ```jsonc
-{ "mode": "direct", "action": "ban", "threshold": 10, "windowSec": 600 }
+{ "pause": { "threshold": 10, "windowSec": 600, "durationSec": 3600 }, "banAfter": 3 }
 ```
-`unban` 重置违规计数；`unpause` 不重置。
+
+校验：`pause` 与 `ban` 互斥；`banAfter` 仅配 `pause` 时允许。`unban` 重置 `pauseCount`；`unpause` 不重置。
 
 ## event 类型（usage_log）
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unified-keys",
-  "version": "0.7.0",
-  "description": "自建通用 API key 管理 SDK（明文存储 + 明文返回 + 完整使用记录），调用 keys.932324.xyz 服务",
+  "version": "0.8.0",
+  "description": "通用 API key 管理 SDK（明文存储 + 明文返回 + 完整使用记录 + per-key 限流/自动处罚）",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/index.ts

@@ -3,6 +3,7 @@ export type {
 	AppRecord,
 	AutoBanConfig,
 	BanInput,
+	BanRule,
 	BatchDeleteResult,
 	CheckInput,
 	CheckResult,
@@ -24,6 +25,7 @@ export type {
 	LookupResult,
 	PauseInput,
 	PauseResult,
+	PauseRule,
 	RateLimitConfig,
 	UpdateCreditsInput,
 	UpdateCreditsResult,

package/src/types.ts

@@ -35,24 +35,44 @@ export interface RateLimitConfig {
 	windowSec?: number;
 }
 
-/** 自动封禁配置（meta.autoBan）*/
-export interface AutoBanConfig {
-	/** direct: 单次触发动作（pause/ban，默认 pause）*/
-	action?: "pause" | "ban";
-	/** pause 持续秒数，默认 3600（1h）*/
+/** 暂停触发规则（与 ban 互斥）：窗口内 rate_limited 达 threshold → 暂停 */
+export interface PauseRule {
+	/** 暂停时长秒数，默认 3600（1h） */
 	durationSec?: number;
-	/** progressive: 违规达此数 → 永久 ban（默认 3）；前 N-1 次 pause */
-	maxViolations?: number;
-	/** 模式：progressive（渐进式，默认）/ direct（直接，单次达阈值即 action）*/
-	mode?: "progressive" | "direct";
-	/** 触发阈值（窗口内 rate_limited 次数 = 一次违规）*/
+	/** 统计窗口内 rate_limited 达此数 → 触发一次 pause（pause_count +1） */
+	threshold: number;
+	/** 统计窗口秒数，默认 600（10min） */
+	windowSec?: number;
+}
+
+/** 封禁触发规则（与 pause 互斥）：窗口内 rate_limited 达 threshold → 永久 ban */
+export interface BanRule {
+	/** 统计窗口内 rate_limited 达此数 → 永久 ban */
 	threshold: number;
-	/** 统计窗口秒数，默认 600（10min）*/
+	/** 统计窗口秒数，默认 600（10min） */
 	windowSec?: number;
 }
 
+/**
+ * 自动处罚策略（存 meta.autoBan）。三种模式：
+ *   - 纯暂停：`{ pause: { threshold, durationSec } }`
+ *   - 直接封禁：`{ ban: { threshold } }`
+ *   - 渐进（先 pause，达 banAfter 后 ban）：`{ pause: {...}, banAfter: N }`
+ */
+export interface AutoBanConfig {
+	/** 封禁规则。与 pause 互斥。 */
+	ban?: BanRule;
+	/**
+	 * 渐进式升级（仅配 pause 时有效）：累计 pause 次数达此数 → 升级永久 ban。
+	 * 配 ban 时不能配；没配 pause 时不能配。
+	 */
+	banAfter?: number;
+	/** 暂停规则。与 ban 互斥。 */
+	pause?: PauseRule;
+}
+
 export interface CreateKeyInput {
-	/** 自动封禁配置（存 meta.autoBan）*/
+	/** 自动处罚策略（存 meta.autoBan）：pause/ban 互斥，banAfter 渐进式 */
 	autoBan?: AutoBanConfig;
 	/**
 	 * autoDelete（createKey 时预设为 key 属性，verify 扣减到 0 时执行；verify 端点不再接受调用方传参）：