@usethink/cf-core 0.3.0

package/dist/src/db/schema.js

@@ -0,0 +1,76 @@
+/**
+ * @usethink/cf-core — 公共数据库 Schema
+ *
+ * 所有项目共享的 Drizzle ORM 表定义。
+ * 各项目在此基础上添加自己的业务表。
+ *
+ * 公共表清单：
+ * 1. systemConfig — 系统配置（KV 存储，热生效）
+ * 2. adminAuditLogs — 管理员审计日志
+ * 3. rateLimitWindows — 限流计数窗口（DB 版限流）
+ * 4. idempotencyKeys — 幂等键（防重复提交）
+ * 5. apiKeys — API Key 认证（可选启用）
+ *
+ * 来源：eshop/xtools/vcode 三项目 schema.ts 中公共部分提取
+ */
+import { integer, primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
+// ═══════════════════════════════════════════════════════════════════════════════
+// 1. 系统配置表（KV 存储，热生效）
+// ═══════════════════════════════════════════════════════════════════════════════
+export const systemConfig = sqliteTable("system_config", {
+    key: text("key").primaryKey(),
+    value: text("value").default("").notNull(),
+    updatedAt: text("updated_at").default("").notNull(),
+});
+// ═══════════════════════════════════════════════════════════════════════════════
+// 2. 管理员审计日志表
+// ═══════════════════════════════════════════════════════════════════════════════
+export const adminAuditLogs = sqliteTable("admin_audit_logs", {
+    id: text("id").primaryKey(),
+    action: text("action").notNull(),
+    targetType: text("target_type").default("").notNull(),
+    targetId: text("target_id").default("").notNull(),
+    metadataJson: text("metadata_json").default("{}").notNull(),
+    ipHash: text("ip_hash").default("").notNull(),
+    createdAt: text("created_at").default("").notNull(),
+});
+// ═══════════════════════════════════════════════════════════════════════════════
+// 3. 限流窗口表（DB 版限流 — 原子 upsert）
+// ═══════════════════════════════════════════════════════════════════════════════
+export const rateLimitWindows = sqliteTable("rate_limit_windows", {
+    action: text("action").notNull(),
+    ipHash: text("ip_hash").notNull(),
+    windowStart: integer("window_start").notNull(),
+    requestCount: integer("request_count").default(0).notNull(),
+}, (table) => ({
+    pk: primaryKey({ columns: [table.action, table.ipHash, table.windowStart] }),
+}));
+// ═══════════════════════════════════════════════════════════════════════════════
+// 4. 幂等键表（防重复提交）
+// ═══════════════════════════════════════════════════════════════════════════════
+export const idempotencyKeys = sqliteTable("idempotency_keys", {
+    key: text("key").notNull(),
+    action: text("action").notNull(),
+    resourceId: text("resource_id").notNull(),
+    responseJson: text("response_json").notNull(),
+    createdAt: text("created_at").default("").notNull(),
+});
+// ═══════════════════════════════════════════════════════════════════════════════
+// 5. API Key 表（可选启用）
+// ═══════════════════════════════════════════════════════════════════════════════
+export const apiKeys = sqliteTable("api_keys", {
+    id: text("id").primaryKey(),
+    name: text("name").notNull(),
+    keyHash: text("key_hash").notNull(),
+    userId: text("user_id").default("").notNull(),
+    tier: text("tier").default("free").notNull(),
+    enabled: integer("enabled").default(1).notNull(),
+    monthlyQuota: integer("monthly_quota").default(0).notNull(),
+    monthlyUsage: integer("monthly_usage").default(0).notNull(),
+    monthlyResetAt: text("monthly_reset_at"),
+    lastUsedAt: text("last_used_at"),
+    createdAt: text("created_at").default("").notNull(),
+    updatedAt: text("updated_at").default("").notNull(),
+    expiresAt: text("expires_at"),
+});
+//# sourceMappingURL=schema.js.map

package/dist/src/db/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/db/schema.ts"],"names":[],"mappings":"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"}

package/dist/src/error.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 错误分类与指数退避重试
+ *
+ * 区分可重试 / 不可重试 / 需延迟重试的错误类型，
+ * 配合指数退避（exponential backoff + jitter）减少无效重试。
+ *
+ * 来源：xtools src/lib/error-classifier.ts
+ */
+export declare enum ErrorType {
+    /** 网络超时、5xx 服务器错误 → 可重试 */
+    TRANSIENT = "transient",
+    /** 4xx 认证失败、invalid_grant → 不可重试 */
+    PERMANENT = "permanent",
+    /** 429 Too Many Requests → 延迟重试 */
+    RATE_LIMIT = "rate_limit"
+}
+/**
+ * 分类错误类型
+ */
+export declare function classifyError(error: unknown): ErrorType;
+export interface RetryOptions {
+    /** 最大重试次数（默认 3） */
+    maxRetries?: number;
+    /** 基础延迟毫秒（默认 1000） */
+    baseDelayMs?: number;
+    /** 限流延迟倍数（默认 5） */
+    rateLimitMultiplier?: number;
+    /** 最大延迟毫秒（默认 30000） */
+    maxDelayMs?: number;
+    /** 重试回调（用于日志） */
+    onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+}
+/**
+ * 带指数退避的重试执行器
+ *
+ * - TRANSIENT: 指数退避（1s → 2s → 4s）
+ * - RATE_LIMIT: 更长延迟（5s → 10s → 20s）
+ * - PERMANENT: 立即抛出，不重试
+ *
+ * @example
+ * const result = await retryWithBackoff(
+ *   () => fetchExternalApi(),
+ *   { maxRetries: 3, onRetry: (n, err, ms) => console.warn(`重试 #${n}: ${err.message} (${ms}ms)`) }
+ * );
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=error.d.ts.map

package/dist/src/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oBAAY,SAAS;IACnB,2BAA2B;IAC3B,SAAS,cAAc;IACvB,oCAAoC;IACpC,SAAS,cAAc;IACvB,mCAAmC;IACnC,UAAU,eAAe;CAC1B;AAsBD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAUvD;AAED,MAAM,WAAW,YAAY;IAC3B,mBAAmB;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB;IACjB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CA0CZ"}

package/dist/src/error.js

@@ -0,0 +1,94 @@
+/**
+ * 错误分类与指数退避重试
+ *
+ * 区分可重试 / 不可重试 / 需延迟重试的错误类型，
+ * 配合指数退避（exponential backoff + jitter）减少无效重试。
+ *
+ * 来源：xtools src/lib/error-classifier.ts
+ */
+export var ErrorType;
+(function (ErrorType) {
+    /** 网络超时、5xx 服务器错误 → 可重试 */
+    ErrorType["TRANSIENT"] = "transient";
+    /** 4xx 认证失败、invalid_grant → 不可重试 */
+    ErrorType["PERMANENT"] = "permanent";
+    /** 429 Too Many Requests → 延迟重试 */
+    ErrorType["RATE_LIMIT"] = "rate_limit";
+})(ErrorType || (ErrorType = {}));
+const PERMANENT_KEYWORDS = [
+    "invalid_grant",
+    "invalid_client",
+    "unauthorized",
+    "interaction_required",
+    "access_denied",
+    "invalid_token",
+    "401",
+    "403",
+    "account_disabled",
+    "consent_required",
+];
+const RATE_LIMIT_KEYWORDS = [
+    "429",
+    "too many requests",
+    "rate limit",
+    "throttl",
+];
+/**
+ * 分类错误类型
+ */
+export function classifyError(error) {
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    if (RATE_LIMIT_KEYWORDS.some((kw) => message.includes(kw))) {
+        return ErrorType.RATE_LIMIT;
+    }
+    if (PERMANENT_KEYWORDS.some((kw) => message.includes(kw))) {
+        return ErrorType.PERMANENT;
+    }
+    return ErrorType.TRANSIENT;
+}
+/**
+ * 带指数退避的重试执行器
+ *
+ * - TRANSIENT: 指数退避（1s → 2s → 4s）
+ * - RATE_LIMIT: 更长延迟（5s → 10s → 20s）
+ * - PERMANENT: 立即抛出，不重试
+ *
+ * @example
+ * const result = await retryWithBackoff(
+ *   () => fetchExternalApi(),
+ *   { maxRetries: 3, onRetry: (n, err, ms) => console.warn(`重试 #${n}: ${err.message} (${ms}ms)`) }
+ * );
+ */
+export async function retryWithBackoff(fn, options = {}) {
+    const { maxRetries = 3, baseDelayMs = 1000, rateLimitMultiplier = 5, maxDelayMs = 30_000, onRetry, } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            const errorType = classifyError(error);
+            if (errorType === ErrorType.PERMANENT) {
+                throw error;
+            }
+            if (attempt >= maxRetries) {
+                break;
+            }
+            let delayMs;
+            if (errorType === ErrorType.RATE_LIMIT) {
+                delayMs = Math.min(baseDelayMs * rateLimitMultiplier * Math.pow(2, attempt), maxDelayMs);
+            }
+            else {
+                delayMs = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+            }
+            // 随机抖动（±20%），避免雷群效应
+            const jitter = delayMs * 0.2 * (Math.random() * 2 - 1);
+            delayMs = Math.round(delayMs + jitter);
+            onRetry?.(attempt + 1, error, delayMs);
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=error.js.map

package/dist/src/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/error.ts"],"names":[],"mappings":"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"}

package/dist/src/http.d.ts

@@ -0,0 +1,83 @@
+/**
+ * HTTP 响应工具模块
+ *
+ * 提供统一的 ok/fail 响应格式，以及常用的请求解析工具。
+ * 泛型设计：兼容任意 Hono AppEnv 类型，无需绑定特定项目。
+ *
+ * 来源：eshop/xtools/vcode 三项目 lib/http.ts 合并
+ */
+import type { Context } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { RateLimitResult } from "./types";
+/**
+ * 成功响应 — 统一格式 { ok: true, ...data }
+ */
+export declare function ok(c: Context<any>, data: Record<string, unknown>, status?: ContentfulStatusCode): Response & import("hono").TypedResponse<{
+    [x: string]: import("hono/utils/types").JSONValue;
+}, 500 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | -1, "json">;
+/**
+ * 失败响应 — 统一格式 { ok: false, error: message }
+ */
+export declare function fail(c: Context<any>, message: string, status?: number, details?: unknown): Response & import("hono").TypedResponse<{
+    [x: string]: import("hono/utils/types").JSONValue;
+}, 500 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | -1, "json">;
+/**
+ * 限流失败响应 — 429 + 标准 RateLimit 头
+ *
+ * 返回标准 HTTP 429 响应，包含以下头信息：
+ * - Retry-After: 秒数（建议客户端等待时间）
+ * - X-RateLimit-Limit: 窗口内允许的最大请求数
+ * - X-RateLimit-Remaining: 窗口内剩余请求数（0）
+ * - X-RateLimit-Reset: 窗口重置的 Unix 时间戳
+ *
+ * @example
+ * ```ts
+ * const result = await rateLimiter.check(key, limit, windowMs);
+ * if (!result.ok) {
+ *   return failRateLimit(c, result, limit);
+ * }
+ * ```
+ */
+export declare function failRateLimit(c: Context<any>, result: RateLimitResult, limit: number): Response & import("hono").TypedResponse<{
+    ok: false;
+    error: string;
+}, 429, "json">;
+/**
+ * 获取站点域名 — 优先使用环境变量 APP_ORIGIN，降级使用请求 URL
+ */
+export declare function getOrigin<E extends {
+    Bindings: {
+        APP_ORIGIN?: string;
+    };
+}>(c: Context<E>): string;
+/**
+ * 安全读取 JSON body — 解析失败返回 undefined（避免非 JSON 请求体导致 400）
+ *
+ * 支持泛型，让调用方可以明确 JSON 形状，避免下游 zod safeParse 的 unknown 类型报错。
+ * 默认类型为 unknown，保持向后兼容。
+ */
+export declare function safeJsonBody<T = unknown>(c: Context<any>): Promise<T>;
+/**
+ * 联系方式脱敏 — 用于管理端展示
+ *
+ * - 邮箱：ab***@example.com
+ * - 手机/其他：ab***cd
+ * - 长度 ≤ 4：***
+ */
+export declare function maskContact(value: string): string;
+/**
+ * 标准化编码 — trim + lowercase（用于优惠码/折扣码等）
+ */
+export declare function normalizeCode(value?: string): string;
+/**
+ * CSV 注入防护 — 对导出值做安全转义
+ *
+ * 如果值以 = + - @ \t \n 开头，前置制表符阻止公式注入。
+ * 来源：eshop admin 订单导出
+ */
+export declare function csvEscape(value: unknown): string;
+/**
+ * 将对象数组导出为 CSV 字符串
+ */
+export declare function toCsv(rows: Record<string, unknown>[], columns: string[]): string;
+//# sourceMappingURL=http.d.ts.map

package/dist/src/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;GAEG;AAEH,wBAAgB,EAAE,CAChB,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,GAAE,oBAA0B;;iXAGnC;AAED;;GAEG;AAEH,wBAAgB,IAAI,CAClB,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,EACf,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAY,EACpB,OAAO,CAAC,EAAE,OAAO;;iXAMlB;AAED;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAgB,aAAa,CAC3B,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,EACf,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM;;;gBAed;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS;IAAE,QAAQ,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAEhG;AAED;;;;;GAKG;AAEH,wBAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMhD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAWhF"}

package/dist/src/http.js

@@ -0,0 +1,116 @@
+/**
+ * HTTP 响应工具模块
+ *
+ * 提供统一的 ok/fail 响应格式，以及常用的请求解析工具。
+ * 泛型设计：兼容任意 Hono AppEnv 类型，无需绑定特定项目。
+ *
+ * 来源：eshop/xtools/vcode 三项目 lib/http.ts 合并
+ */
+/**
+ * 成功响应 — 统一格式 { ok: true, ...data }
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function ok(c, data, status = 200) {
+    return c.json({ ok: true, ...data }, status);
+}
+/**
+ * 失败响应 — 统一格式 { ok: false, error: message }
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function fail(c, message, status = 400, details) {
+    return c.json({ ok: false, error: message, ...(details ? { details } : {}) }, status);
+}
+/**
+ * 限流失败响应 — 429 + 标准 RateLimit 头
+ *
+ * 返回标准 HTTP 429 响应，包含以下头信息：
+ * - Retry-After: 秒数（建议客户端等待时间）
+ * - X-RateLimit-Limit: 窗口内允许的最大请求数
+ * - X-RateLimit-Remaining: 窗口内剩余请求数（0）
+ * - X-RateLimit-Reset: 窗口重置的 Unix 时间戳
+ *
+ * @example
+ * ```ts
+ * const result = await rateLimiter.check(key, limit, windowMs);
+ * if (!result.ok) {
+ *   return failRateLimit(c, result, limit);
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function failRateLimit(c, result, limit) {
+    const retryAfterSeconds = Math.ceil((result.resetMs || 0) / 1000);
+    const resetTimestamp = Math.ceil((Date.now() + (result.resetMs || 0)) / 1000);
+    return c.json({ ok: false, error: result.message || "请求过于频繁，请稍后再试" }, 429, {
+        "Retry-After": String(retryAfterSeconds),
+        "X-RateLimit-Limit": String(limit),
+        "X-RateLimit-Remaining": "0",
+        "X-RateLimit-Reset": String(resetTimestamp),
+    });
+}
+/**
+ * 获取站点域名 — 优先使用环境变量 APP_ORIGIN，降级使用请求 URL
+ */
+export function getOrigin(c) {
+    return c.env.APP_ORIGIN || new URL(c.req.url).origin;
+}
+/**
+ * 安全读取 JSON body — 解析失败返回 undefined（避免非 JSON 请求体导致 400）
+ *
+ * 支持泛型，让调用方可以明确 JSON 形状，避免下游 zod safeParse 的 unknown 类型报错。
+ * 默认类型为 unknown，保持向后兼容。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function safeJsonBody(c) {
+    return c.req.json().catch(() => undefined);
+}
+/**
+ * 联系方式脱敏 — 用于管理端展示
+ *
+ * - 邮箱：ab***@example.com
+ * - 手机/其他：ab***cd
+ * - 长度 ≤ 4：***
+ */
+export function maskContact(value) {
+    const text = value.trim();
+    if (text.length <= 4)
+        return "***";
+    if (text.includes("@") && !text.startsWith("@")) {
+        const [name, domain] = text.split("@");
+        return `${name.slice(0, 2)}***@${domain}`;
+    }
+    return `${text.slice(0, 2)}***${text.slice(-2)}`;
+}
+/**
+ * 标准化编码 — trim + lowercase（用于优惠码/折扣码等）
+ */
+export function normalizeCode(value) {
+    return (value || "").trim().toLowerCase();
+}
+/**
+ * CSV 注入防护 — 对导出值做安全转义
+ *
+ * 如果值以 = + - @ \t \n 开头，前置制表符阻止公式注入。
+ * 来源：eshop admin 订单导出
+ */
+export function csvEscape(value) {
+    const str = String(value ?? "");
+    if (/^[=+\-@\t\n]/.test(str)) {
+        return `\t${str}`;
+    }
+    return str;
+}
+/**
+ * 将对象数组导出为 CSV 字符串
+ */
+export function toCsv(rows, columns) {
+    const header = columns.join(",");
+    const body = rows.map((row) => columns.map((col) => {
+        const val = csvEscape(row[col]);
+        return val.includes(",") || val.includes('"') || val.includes("\n")
+            ? `"${val.replace(/"/g, '""')}"`
+            : val;
+    }).join(",")).join("\n");
+    return `${header}\n${body}`;
+}
+//# sourceMappingURL=http.js.map

package/dist/src/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"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"}

package/dist/src/idempotency.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 幂等性模块 — 防止同一请求被重复处理
+ *
+ * 使用 (key, action) 复合键作为幂等标识。
+ * 核心设计：原子 UPSERT + 非空哨兵值，消除 TOCTOU 竞态。
+ *
+ * 流程：
+ * 1. checkIdempotency() — 原子 UPSERT，返回 shouldProceed
+ * 2. shouldProceed === false → 返回缓存响应
+ * 3. shouldProceed === true → 执行业务逻辑 → saveIdempotentResponse()
+ *
+ * 来源：eshop src/lib/idempotency.ts（三项目中唯一实现）
+ */
+import { idempotencyKeys } from "./db/schema";
+/**
+ * 通用 Drizzle 数据库接口（仅约束幂等模块需要的方法）
+ */
+interface DbLike {
+    insert: (table: typeof idempotencyKeys) => {
+        values: (data: {
+            key: string;
+            action: string;
+            resourceId: string;
+            responseJson: string;
+            createdAt: string;
+        }) => {
+            onConflictDoUpdate: (opts: {
+                target: [typeof idempotencyKeys.key, typeof idempotencyKeys.action];
+                set: Record<string, unknown>;
+            }) => {
+                returning: (cols: {
+                    responseJson: typeof idempotencyKeys.responseJson;
+                }) => Promise<{
+                    responseJson: string;
+                }[]>;
+            };
+        };
+    };
+    select: (cols: {
+        responseJson: typeof idempotencyKeys.responseJson;
+    }) => {
+        from: (table: typeof idempotencyKeys) => {
+            where: (cond: unknown) => {
+                limit: (n: number) => Promise<{
+                    responseJson: string;
+                }[]>;
+            };
+        };
+    };
+}
+/**
+ * 原子检查幂等性
+ *
+ * INSERT ON CONFLICT UPDATE RETURNING 是 SQLite 原子操作。
+ * 并发请求中只有一个获得 shouldProceed=true。
+ *
+ * @returns shouldProceed=true 时应执行业务逻辑；false 时 cachedResponse 含之前缓存的响应
+ */
+export declare function checkIdempotency(db: DbLike, key: string, action: string): Promise<{
+    shouldProceed: boolean;
+    cachedResponse: string | null;
+}>;
+/**
+ * 保存幂等响应
+ *
+ * 在 checkIdempotency 返回 shouldProceed=true 并执行业务逻辑后调用。
+ */
+export declare function saveIdempotentResponse(db: DbLike, key: string, action: string, resourceId: string, response: unknown): Promise<void>;
+/**
+ * 查询已缓存的幂等响应（只读，不创建记录）
+ *
+ * @deprecated 使用 checkIdempotency() 替代
+ */
+export declare function getIdempotentResponse(db: DbLike, key: string, action: string): Promise<{
+    responseJson: string;
+} | null>;
+export {};
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/src/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAK9C;;GAEG;AACH,UAAU,MAAM;IACd,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,eAAe,KAAK;QACzC,MAAM,EAAE,CAAC,IAAI,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,KAAK;YAC9G,kBAAkB,EAAE,CAAC,IAAI,EAAE;gBACzB,MAAM,EAAE,CAAC,OAAO,eAAe,CAAC,GAAG,EAAE,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;gBACpE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;aAC9B,KAAK;gBACJ,SAAS,EAAE,CAAC,IAAI,EAAE;oBAAE,YAAY,EAAE,OAAO,eAAe,CAAC,YAAY,CAAA;iBAAE,KAAK,OAAO,CAAC;oBAAE,YAAY,EAAE,MAAM,CAAA;iBAAE,EAAE,CAAC,CAAC;aACjH,CAAC;SACH,CAAC;KACH,CAAC;IACF,MAAM,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,OAAO,eAAe,CAAC,YAAY,CAAA;KAAE,KAAK;QACvE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,eAAe,KAAK;YACvC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK;gBACxB,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;oBAAE,YAAY,EAAE,MAAM,CAAA;iBAAE,EAAE,CAAC,CAAC;aAC3D,CAAC;SACH,CAAC;KACH,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAwBpE;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAO1C"}

package/dist/src/idempotency.js

@@ -0,0 +1,84 @@
+/**
+ * 幂等性模块 — 防止同一请求被重复处理
+ *
+ * 使用 (key, action) 复合键作为幂等标识。
+ * 核心设计：原子 UPSERT + 非空哨兵值，消除 TOCTOU 竞态。
+ *
+ * 流程：
+ * 1. checkIdempotency() — 原子 UPSERT，返回 shouldProceed
+ * 2. shouldProceed === false → 返回缓存响应
+ * 3. shouldProceed === true → 执行业务逻辑 → saveIdempotentResponse()
+ *
+ * 来源：eshop src/lib/idempotency.ts（三项目中唯一实现）
+ */
+import { idempotencyKeys } from "./db/schema";
+import { eq, and, sql } from "drizzle-orm";
+const PENDING_SENTINEL = "__pending__";
+/**
+ * 原子检查幂等性
+ *
+ * INSERT ON CONFLICT UPDATE RETURNING 是 SQLite 原子操作。
+ * 并发请求中只有一个获得 shouldProceed=true。
+ *
+ * @returns shouldProceed=true 时应执行业务逻辑；false 时 cachedResponse 含之前缓存的响应
+ */
+export async function checkIdempotency(db, key, action) {
+    const [row] = await db
+        .insert(idempotencyKeys)
+        .values({
+        key,
+        action,
+        resourceId: "",
+        responseJson: PENDING_SENTINEL,
+        createdAt: new Date().toISOString(),
+    })
+        .onConflictDoUpdate({
+        target: [idempotencyKeys.key, idempotencyKeys.action],
+        set: { responseJson: sql `idempotency_keys.response_json` },
+    })
+        .returning({ responseJson: idempotencyKeys.responseJson });
+    const shouldProceed = row?.responseJson === PENDING_SENTINEL;
+    const cachedResponse = shouldProceed
+        ? null
+        : row?.responseJson === PENDING_SENTINEL
+            ? null
+            : row?.responseJson ?? null;
+    return { shouldProceed, cachedResponse };
+}
+/**
+ * 保存幂等响应
+ *
+ * 在 checkIdempotency 返回 shouldProceed=true 并执行业务逻辑后调用。
+ */
+export async function saveIdempotentResponse(db, key, action, resourceId, response) {
+    await db
+        .insert(idempotencyKeys)
+        .values({
+        key,
+        action,
+        resourceId,
+        responseJson: JSON.stringify(response),
+        createdAt: new Date().toISOString(),
+    })
+        .onConflictDoUpdate({
+        target: [idempotencyKeys.key, idempotencyKeys.action],
+        set: {
+            responseJson: JSON.stringify(response),
+            resourceId,
+        },
+    });
+}
+/**
+ * 查询已缓存的幂等响应（只读，不创建记录）
+ *
+ * @deprecated 使用 checkIdempotency() 替代
+ */
+export async function getIdempotentResponse(db, key, action) {
+    const [row] = await db
+        .select({ responseJson: idempotencyKeys.responseJson })
+        .from(idempotencyKeys)
+        .where(and(eq(idempotencyKeys.key, key), eq(idempotencyKeys.action, action)))
+        .limit(1);
+    return row || null;
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/src/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAyBvC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,EAAU,EACV,GAAW,EACX,MAAc;IAEd,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE;SACnB,MAAM,CAAC,eAAe,CAAC;SACvB,MAAM,CAAC;QACN,GAAG;QACH,MAAM;QACN,UAAU,EAAE,EAAE;QACd,YAAY,EAAE,gBAAgB;QAC9B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;SACD,kBAAkB,CAAC;QAClB,MAAM,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,eAAe,CAAC,MAAM,CAAC;QACrD,GAAG,EAAE,EAAE,YAAY,EAAE,GAAG,CAAA,gCAAgC,EAAE;KAC3D,CAAC;SACD,SAAS,CAAC,EAAE,YAAY,EAAE,eAAe,CAAC,YAAY,EAAE,CAAC,CAAC;IAE7D,MAAM,aAAa,GAAG,GAAG,EAAE,YAAY,KAAK,gBAAgB,CAAC;IAC7D,MAAM,cAAc,GAAG,aAAa;QAClC,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,GAAG,EAAE,YAAY,KAAK,gBAAgB;YACtC,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,GAAG,EAAE,YAAY,IAAI,IAAI,CAAC;IAEhC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,EAAU,EACV,GAAW,EACX,MAAc,EACd,UAAkB,EAClB,QAAiB;IAEjB,MAAM,EAAE;SACL,MAAM,CAAC,eAAe,CAAC;SACvB,MAAM,CAAC;QACN,GAAG;QACH,MAAM;QACN,UAAU;QACV,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;QACtC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;SACD,kBAAkB,CAAC;QAClB,MAAM,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,eAAe,CAAC,MAAM,CAAC;QACrD,GAAG,EAAE;YACH,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;YACtC,UAAU;SACX;KACF,CAAC,CAAC;AACP,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,EAAU,EACV,GAAW,EACX,MAAc;IAEd,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE;SACnB,MAAM,CAAC,EAAE,YAAY,EAAE,eAAe,CAAC,YAAY,EAAE,CAAC;SACtD,IAAI,CAAC,eAAe,CAAC;SACrB,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;SAC5E,KAAK,CAAC,CAAC,CAAC,CAAC;IACZ,OAAO,GAAG,IAAI,IAAI,CAAC;AACrB,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @usethink/cf-core — Cloudflare Workers 共享内核
+ *
+ * 统一导出所有模块，支持两种导入方式：
+ *
+ * 1. 从根导入（适合小项目）：
+ *    import { ok, fail, sha256, verifyTurnstile } from "@usethink/cf-core";
+ *
+ * 2. 按子路径导入（推荐，tree-shakeable）：
+ *    import { ok, fail } from "@usethink/cf-core/http";
+ *    import { sha256 } from "@usethink/cf-core/security";
+ */
+export { ok, fail, failRateLimit, getOrigin, safeJsonBody, maskContact, normalizeCode, csvEscape, toCsv } from "./http";
+export { sha256, constantTimeEqual, getIpHash, getClientIp, getBearerToken, verifyTurnstile, buildSecurityHeaders, type SecurityHeadersOptions, } from "./security";
+export { createCache, cache } from "./cache";
+export { MemoryRateLimiter, KvRateLimiter, DbRateLimiter, type RateLimiter } from "./rate-limit";
+export { checkIdempotency, saveIdempotentResponse, getIdempotentResponse } from "./idempotency";
+export { writeAdminAudit, type AuditInput } from "./audit";
+export { SystemConfig, type SystemConfigOptions } from "./config";
+export { classifyError, retryWithBackoff, ErrorType, type RetryOptions } from "./error";
+export { logger, type LogLevel, type LogEntry } from "./logger";
+export { encrypt, decrypt, isEncryptionAvailable, generateUUID } from "./crypto";
+export { initDatabase, initDatabaseWithHealthCheck, getOrCreateClient, createDrizzle, type DrizzleInstance } from "./db/connection";
+export { systemConfig, adminAuditLogs, rateLimitWindows, idempotencyKeys, apiKeys, } from "./db/schema";
+export { signJwt, verifyJwt, extractJwt, type JwtPayload } from "./auth/jwt";
+export { hashPassword, verifyPassword } from "./auth/password";
+export { createAdminAuth, type AdminAuthOptions } from "./middleware/admin-auth";
+export { createApiKeyAuth, extractApiKey, type ApiKeyAuthOptions, type ApiKeyContext } from "./middleware/api-key-auth";
+export { bootstrap, type BootstrapOptions } from "./bootstrap";
+export type { CoreBindings, CoreVariables, CoreEnv, OkResponse, FailResponse, TurnstileResult, RateLimitResult, } from "./types";
+//# sourceMappingURL=index.d.ts.map