afdian-kit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 laoer536
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# afdian-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+爱发电通用工具库：**价格算法 / 验签 / 下单跳转 / 配置查询**。零依赖、无数据库、Web Crypto 验签（Node 24 / Cloudflare Workers / 浏览器通用）。
+
+## 安装
+
+```bash
+pnpm add afdian-kit
+```
+
+## 配置：项目根创建 `afdian.config.ts`
+
+```ts
+import { defineConfig } from "afdian-kit";
+
+export default defineConfig({
+  plans: {                                      // 订阅方案（月费）
+    membership: {
+      plan_id: "cc9ba47ec47b11f1b1ea5254001e7c00",
+      name: "忍3作战室会员",
+      monthly: 1200,                            // 月单价（分）
+      discount: true,                           // 官方折扣开关
+    },
+  },
+  products: {                                   // 固定商品
+    starter_pack: { plan_id: "xxxx", name: "新手礼包", price: 9900 },
+  },
+  // publicKey?: "..."                          // 可选：覆盖内置官方公钥
+});
+```
+
+- **Node 环境**：方法首次调用时自动从 cwd 逐级向上发现该文件并加载（进程内缓存），无需任何初始化代码
+- **Workers/打包器环境**：入口处一次性 `configure(config)`（如 `configure((await import("./afdian.config")).default)`）
+
+## 方法
+
+```ts
+import {
+  price, listPlans, listProducts, getProduct,
+  verify, resolveOrder, buildUrl,
+  configure, defineConfig,
+} from "afdian-kit";
+
+// 价格（金额单位：分）
+await price("membership", { months: 6 });
+// → { kind:"plan", amount:6768, original:7200, rate:0.06, months:6, name:"忍3作战室会员", ... }
+await price("starter_pack");
+// → { kind:"product", amount:9900, fixed:true, ... }
+
+// 订阅列表（含六档价格表，可按区间过滤）
+await listPlans();                     // tiers: 1/3/6/12/24/36 六档
+await listPlans({ from: 6, to: 12 });  // 只要 6、12 两档
+
+// 商品查询
+await listProducts();                  // [{ key, plan_id, name, price }]
+await getProduct("starter_pack");      // 未配置 → null
+
+// 验签（async —— Web Crypto 仅异步 API；不依赖 config）
+await verify(rawBody);                 // → { valid:true, type, order } | { valid:false, reason }
+await verify(rawBody, { publicKey });  // 显式覆盖公钥（轮换/测试）
+
+// 订单辅助（金额核对 / 跳转）
+await resolveOrder(order);             // plan_id → { key, kind, expectedAmount } | null
+await buildUrl({ entry: "membership", userId: "<站内用户id>", months: 6 });
+// → https://afdian.com/order/create?plan_id=..&product_type=0&month=6&custom_order_id=..
+
+// 可插拔幂等编排（kit 不带存储，store 由应用实现注入）
+import { createWebhookHandler } from "afdian-kit";
+const handler = createWebhookHandler({
+  store,                                 // { begin(no)→"ok"|"inflight"|"completed", complete(no) }
+  onPaid: async ({ order, resolution, key, outTradeNo }) => { /* 应用只写履约 */ },
+  onRejected: (info) => { /* 留档：unknown plan / amount mismatch / unverifiable amount */ },
+  // checkAmount?: boolean  默认 true —— 签名金额 vs 配置应收核对
+  // publicKey?: string      透传给 verify
+});
+// 路由里：return Response.json(await handler(await request.text()))
+// 流程：验签 → 方案匹配 → 幂等拦截 → 金额核对 → onPaid → 终态
+// onPaid 抛错 → ec:500 借平台重推，begin 返回 "inflight" 允许重试；重复推送 → "completed" 拦截
+```
+
+### 价格规则（官方钉死）
+
+- 可购档位**仅** `1 / 3 / 6 / 12 / 24 / 36` 个月，档外抛 `RangeError`
+- 折扣率：`1:0, 3:0, 6:6%, 12:10%, 24:14%, 36:16%`；`discount: false` 时全部为 0
+- 金额 = `Math.round(monthly × months × (1 − rate))`，单位分
+- 固定商品按标价，不参与折扣
+
+## 验签说明
+
+- `sign_str = out_trade_no + user_id + plan_id + total_amount`（依次拼接，无分隔符）
+- RSA-SHA256，公钥默认内置官方 PEM，`data.sign` 为 base64
+- 未在签名内的字段（`month`、`custom_order_id` 等）**不可作为金额/时长依据** —— 用 `resolveOrder()` 拿 `expectedAmount` 做核对
+
+## 开发
+
+```bash
+pnpm install
+pnpm build        # tsdown 构建 → dist/（ESM + d.ts）
+pnpm dev          # tsdown --watch
+pnpm check        # 构建 + 自检（真实报文验签 / 六档价格断言 / 档外抛错 / handler 幂等编排 / 冒烟）
+pnpm check:pack   # 打包产物自检（pnpm pack 解包 → 结构断言 / 运行时全量用例 / 消费方 d.ts 类型检查）
+```
+
+### 参考 store 实现（应用侧，以 D1 为例）
+
+```ts
+const store = {
+  async begin(no) {
+    // 用状态表实现原子认领：none → inflight；返回既有状态
+    // INSERT INTO webhook_events(out_trade_no, status) VALUES (?1, 'inflight')
+    //   ON CONFLICT(out_trade_no) DO NOTHING → changes>0 即 "ok"
+    // 否则 SELECT status → 'inflight' | 'completed'
+  },
+  async complete(no) {
+    // UPDATE webhook_events SET status='completed' WHERE out_trade_no=?
+  },
+};
+```
+
+严格一次的重要副作用（如给用户叠时长），建议在 `onPaid` 内再加单语句原子闸
+（例如在用户表维护 `last_applied_out_trade_no`，单条 UPDATE 内比对并写入）——
+因为「onPaid 成功后、complete 前崩溃」的窗口里，平台重推会再次进入 `onPaid`。

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+//#region src/types.d.ts
+/** 订阅方案（月费模式）配置项 */
+interface PlanEntry {
+  /** 爱发电方案 ID */
+  plan_id: string;
+  /** 方案名称（用于站内展示） */
+  name: string;
+  /** 月单价，单位「分」 */
+  monthly: number;
+  /** 是否启用官方折扣（关闭时按 月单价×月数 原价） */
+  discount: boolean;
+}
+/** 固定商品配置项 */
+interface ProductEntry {
+  /** 爱发电方案 ID */
+  plan_id: string;
+  /** 商品名称（用于站内展示） */
+  name: string;
+  /** 固定售价，单位「分」 */
+  price: number;
+}
+/** afdian.config.ts 的导出结构 */
+interface AfdianConfig {
+  plans: Record<string, PlanEntry>;
+  products: Record<string, ProductEntry>;
+  /** 覆盖内置官方公钥（轮换/测试场景，PEM 格式） */
+  publicKey?: string;
+}
+/** 爱发电订单（验签后返回；4 个签名字段必填，其余随报文而定） */
+interface AfdianOrder {
+  /** 签名字段：爱发电订单号（幂等键） */
+  out_trade_no: string;
+  /** 签名字段：下单用户 ID */
+  user_id: string;
+  /** 签名字段：方案 ID */
+  plan_id: string;
+  /** 签名字段：实付金额（分字符串，如 "12.00"） */
+  total_amount: string;
+  show_amount?: string;
+  month?: number;
+  status?: number;
+  remark?: string;
+  redeem_id?: string;
+  /** 0 常规方案（订阅） 1 售卖方案（商品） */
+  product_type?: number;
+  discount?: string;
+  sku_detail?: unknown[];
+  create_time?: number;
+  remote_id?: string;
+  user_name?: string;
+  plan_title?: string;
+  user_private_id?: string;
+  title?: string;
+  address_person?: string;
+  address_phone?: string;
+  address_address?: string;
+  /** 站内自定义订单标识（下单 URL 传入，原样带回） */
+  custom_order_id?: string;
+}
+/** verify() 结果 */
+type VerifyResult = {
+  valid: false;
+  reason: "bad json" | "missing fields" | "bad sign";
+} | {
+  valid: true;
+  type: string;
+  order: AfdianOrder;
+};
+/** 单档价格计算结果 */
+interface TierPrice {
+  months: number;
+  /** 应收（分） */
+  amount: number;
+  /** 折扣前原价（分） */
+  original: number;
+  /** 折扣率 */
+  rate: number;
+}
+/** price() 订阅方案结果 */
+interface PlanPriceResult {
+  key: string;
+  kind: "plan";
+  name: string;
+  plan_id: string;
+  months: number;
+  amount: number;
+  original: number;
+  rate: number;
+}
+/** price() 固定商品结果 */
+interface ProductPriceResult {
+  key: string;
+  kind: "product";
+  name: string;
+  plan_id: string;
+  amount: number;
+  fixed: true;
+}
+type PriceResult = PlanPriceResult | ProductPriceResult;
+/** listPlans() 单项 */
+interface PlanInfo {
+  key: string;
+  plan_id: string;
+  name: string;
+  monthly: number;
+  discount: boolean;
+  tiers: TierPrice[];
+}
+/** listProducts()/getProduct() 单项 */
+interface ProductInfo {
+  key: string;
+  plan_id: string;
+  name: string;
+  price: number;
+}
+/** resolveOrder() 结果 */
+interface OrderResolution {
+  key: string;
+  kind: "plan" | "product";
+  entry: PlanEntry | ProductEntry;
+  /** 该单应收（分）；订阅按报文 month 反查，month 非法档位时为 null */
+  expectedAmount: number | null;
+}
+//#endregion
+//#region src/config.d.ts
+/** 配置文件类型标注（无运行时逻辑） */
+export declare function defineConfig(config: AfdianConfig): AfdianConfig;
+/** 程序化配置：调用后跳过自动发现（Workers/打包器环境用） */
+export declare function configure(config: AfdianConfig): void;
+/** 重置缓存（测试用） */
+export declare function resetConfig(): void;
+//#endregion
+//#region src/pricing.d.ts
+/** 官方可购档位（一次性购买仅此六档，钉死） */
+export declare const MONTH_TIERS: readonly [1, 3, 6, 12, 24, 36];
+/** 官方折扣表（钉死） */
+export declare const DISCOUNTS: Readonly<Record<number, number>>;
+/**
+ * 订阅方案价格计算（纯函数）
+ * 金额 = Math.round(monthly × months × (1 − rate))，单位分
+ */
+export declare function calcPlanPrice({ monthly, months, discount }: {
+  monthly: number;
+  months: number;
+  discount: boolean;
+}): {
+  amount: number;
+  original: number;
+  rate: number;
+};
+/** 计算某方案全部档位价格 */
+export declare function calcTiers({ monthly, discount }: {
+  monthly: number;
+  discount: boolean;
+}): {
+  amount: number;
+  original: number;
+  rate: number;
+  months: 1 | 3 | 6 | 12 | 24 | 36;
+}[];
+/** 订阅方案价格（key 未配置则抛错；product 忽略 months） */
+export declare function price(key: string, opts?: {
+  months?: number;
+}): Promise<PriceResult>;
+/** 订阅方案列表（含逐档价格表，可按档位区间过滤） */
+export declare function listPlans(opts?: {
+  from?: number;
+  to?: number;
+}): Promise<PlanInfo[]>;
+/** 固定商品列表 */
+export declare function listProducts(): Promise<ProductInfo[]>;
+/** 单个固定商品（未配置返回 null） */
+export declare function getProduct(key: string): Promise<ProductInfo | null>;
+//#endregion
+//#region src/verify.d.ts
+/**
+ * 爱发电 webhook 验签
+ * sign_str = out_trade_no + user_id + plan_id + total_amount 依次无分隔符拼接
+ * RSA-SHA256（RSASSA-PKCS1-v1_5），data.sign 为 base64 签名
+ *
+ * 注意：Web Crypto（crypto.subtle）仅有异步 API，任何环境都无法同步验签，
+ * 因此 verify 为 async。不依赖 config，公钥通过第二参显式传入（默认官方公钥）。
+ */
+/** 爱发电官方公钥（默认） */
+export declare const AFDIAN_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwwdaCg1Bt+UKZKs0R54y\nlYnuANma49IpgoOwNmk3a0rhg/PQuhUJ0EOZSowIC44l0K3+fqGns3Ygi4AfmEfS\n4EKbdk1ahSxu7Zkp2rHMt+R9GarQFQkwSS/5x1dYiHNVMiR8oIXDgjmvxuNes2Cr\n8fw9dEF0xNBKdkKgG2qAawcN1nZrdyaKWtPVT9m2Hl0ddOO9thZmVLFOb9NVzgYf\njEgI+KWX6aY19Ka/ghv/L4t1IXmz9pctablN5S0CRWpJW3Cn0k6zSXgjVdKm4uN7\njRlgSRaf/Ind46vMCm3N2sgwxu/g3bnooW+db0iLo13zzuvyn727Q3UDQ0MmZcEW\nMQIDAQAB\n-----END PUBLIC KEY-----";
+/** 组装签名串（与官方文档一致：四字段依次拼接，无分隔符） */
+export declare function buildSignStr(order: Pick<AfdianOrder, "out_trade_no" | "user_id" | "plan_id" | "total_amount">): string;
+/**
+ * 验证 webhook 报文签名，返回验证之后的数据
+ *
+ * @param payload 完整报文（字符串或已解析对象，需含 data.sign 与 data.order）
+ * @param opts.publicKey 覆盖公钥（PEM；轮换/测试用 —— 显式传参，不读 config，无隐式顺序）
+ */
+export declare function verify(payload: string | object, opts?: {
+  publicKey?: string;
+}): Promise<VerifyResult>;
+//#endregion
+//#region src/order.d.ts
+/**
+ * 按 order.plan_id 匹配配置并给出该单应收金额（应用做金额核对的辅助）
+ * 匹配不到返回 null（应用记 rejected）
+ */
+export declare function resolveOrder(order: Pick<AfdianOrder, "plan_id" | "month">): Promise<OrderResolution | null>;
+/**
+ * 生成爱发电下单跳转 URL
+ * - plans entry：product_type=0，months 默认 1（非法档位抛错）
+ * - products entry：product_type=1，不带 month
+ */
+export declare function buildUrl(opts: {
+  entry: string;
+  userId: string;
+  months?: number;
+}): Promise<string>;
+//#endregion
+//#region src/handler.d.ts
+/**
+ * 可插拔幂等编排（kit 依旧不带任何存储 —— store 由应用实现并注入）
+ *
+ * 流程：verify → resolveOrder(方案匹配) → store.begin(幂等拦截)
+ *      → 金额核对 → onPaid(应用履约) → store.complete
+ *
+ * 幂等语义（begin 的三种返回）：
+ *  - "ok"        首次见，进入处理
+ *  - "inflight"  上次处理中断（崩溃/失败后平台重推）→ 允许重试履约
+ *  - "completed" 已终态（履约成功或核对拒绝）→ 拦截，ec:200 不重推
+ *
+ * onPaid 抛错：不 complete，返回 ec:500 → 平台重推 → begin 得 "inflight" → 重试
+ * 崩溃窗口（onPaid 成功后、complete 前）：重推会再次调用 onPaid ——
+ *   对时效不敏感的履约天然安全；严格一次的副作用需应用侧自备幂等
+ *   （如用户表维护 last_applied_out_trade_no，单条 UPDATE 内比对并写入的原子闸）。
+ */
+/** 幂等存储接口：应用实现（D1/Redis/…），唯一键约束保证 begin 的原子性 */
+interface IdempotencyStore {
+  /** 认领订单号：首次 "ok"；已处理中 "inflight"；已终态 "completed" */
+  begin(outTradeNo: string): Promise<"ok" | "inflight" | "completed">;
+  /** 标记终态（履约成功，或核对类拒绝） */
+  complete(outTradeNo: string): Promise<void>;
+}
+/** 核对失败信息（供应用留档/人工处理） */
+interface RejectedInfo {
+  reason: "unknown plan" | "unverifiable amount" | "amount mismatch";
+  order: AfdianOrder;
+  expectedAmount: number | null;
+}
+interface WebhookHandlerDeps {
+  store: IdempotencyStore;
+  /** 履约回调（唯一必须实现的业务逻辑） */
+  onPaid: (ctx: {
+    order: AfdianOrder;
+    resolution: OrderResolution;
+    key: string;
+    outTradeNo: string;
+  }) => Promise<void>;
+  /** 核对失败钩子（留档；返回后 handler 一律 ec:200 不重推） */
+  onRejected?: (info: RejectedInfo) => Promise<void> | void;
+  /** 金额核对开关，默认开启（关闭后 expectedAmount 不再校验，仅高级场景使用） */
+  checkAmount?: boolean;
+  /** 覆盖公钥（透传给 verify） */
+  publicKey?: string;
+}
+interface WebhookEc {
+  ec: 200 | 500;
+  em: string;
+}
+/**
+ * 创建 webhook 处理器：入参报文（字符串/对象），返回爱发电契约的 ec 响应体。
+ * 应用侧自行包一层 HTTP：`return Response.json(await handler(await req.text()))`
+ */
+export declare function createWebhookHandler(deps: WebhookHandlerDeps): (payload: string | object) => Promise<WebhookEc>;
+//#endregion
+export type { AfdianConfig, AfdianOrder, IdempotencyStore, OrderResolution, PlanEntry, PlanInfo, PlanPriceResult, PriceResult, ProductEntry, ProductInfo, ProductPriceResult, RejectedInfo, TierPrice, VerifyResult, WebhookEc, WebhookHandlerDeps };

package/dist/index.js

@@ -0,0 +1,424 @@
+//#region src/config.ts
+/**
+* 配置加载：
+*  - configure(config)      程序化一次配置（Workers/打包器环境入口）
+*  - 自动发现               Node 下从 cwd 逐级向上找 afdian.config.*，import 执行取 default，进程内缓存
+*  - 依赖 config 的方法为 async；verify 不依赖 config（见 spec §7）
+*/
+const CONFIG_FILENAMES = [
+	"afdian.config.ts",
+	"afdian.config.mts",
+	"afdian.config.mjs",
+	"afdian.config.js"
+];
+let cached = null;
+let loading = null;
+/** 配置文件类型标注（无运行时逻辑） */
+function defineConfig(config) {
+	return config;
+}
+/** 程序化配置：调用后跳过自动发现（Workers/打包器环境用） */
+function configure(config) {
+	cached = validate(config);
+}
+/** 重置缓存（测试用） */
+function resetConfig() {
+	cached = null;
+	loading = null;
+}
+function validate(raw) {
+	const cfg = raw;
+	if (!cfg || typeof cfg !== "object") throw new Error("afdian.config 必须导出配置对象（export default defineConfig({...})）");
+	if (!cfg.plans || typeof cfg.plans !== "object") throw new Error("afdian.config 缺少 plans 配置（订阅方案）");
+	if (!cfg.products || typeof cfg.products !== "object") throw new Error("afdian.config 缺少 products 配置（固定商品）");
+	return cfg;
+}
+function isNode() {
+	return typeof globalThis.process?.versions?.node === "string";
+}
+/** 拼接的动态 import：绕过打包器静态分析（Workers 构建不会解析 node 内置模块） */
+async function importNodeBuiltin(name) {
+	return await import("node:" + name);
+}
+/** 获取配置（内部统一入口）：已配置直接返回，否则自动发现 */
+async function getConfig() {
+	if (cached) return cached;
+	if (loading) return loading;
+	loading = discover().finally(() => {
+		loading = null;
+	});
+	return loading;
+}
+async function discover() {
+	if (!isNode()) throw new Error("自动发现 afdian.config 仅支持 Node 环境；Workers/打包器环境请先调用 configure(config)");
+	const fs = await importNodeBuiltin("fs");
+	const path = await importNodeBuiltin("path");
+	const url = await importNodeBuiltin("url");
+	let dir = globalThis.process.cwd();
+	for (;;) {
+		for (const name of CONFIG_FILENAMES) {
+			const full = path.join(dir, name);
+			if (fs.existsSync(full)) {
+				const cfg = validate((await import(url.pathToFileURL(full).href)).default);
+				cached = cfg;
+				return cfg;
+			}
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	throw new Error("未找到 afdian.config.ts（从当前目录逐级向上查找）。请在项目根创建它，或调用 configure(config)");
+}
+//#endregion
+//#region src/pricing.ts
+/** 官方可购档位（一次性购买仅此六档，钉死） */
+const MONTH_TIERS = [
+	1,
+	3,
+	6,
+	12,
+	24,
+	36
+];
+/** 官方折扣表（钉死） */
+const DISCOUNTS = {
+	1: 0,
+	3: 0,
+	6: .06,
+	12: .1,
+	24: .14,
+	36: .16
+};
+const TIER_HINT = "1/3/6/12/24/36";
+/**
+* 订阅方案价格计算（纯函数）
+* 金额 = Math.round(monthly × months × (1 − rate))，单位分
+*/
+function calcPlanPrice({ monthly, months, discount }) {
+	if (!Number.isInteger(months) || months <= 0) throw new RangeError(`months 必须为正整数，收到: ${months}`);
+	if (!(months in DISCOUNTS)) throw new RangeError(`官方仅支持 ${TIER_HINT} 个月档位，收到: ${months}`);
+	const rate = discount ? DISCOUNTS[months] : 0;
+	const original = monthly * months;
+	return {
+		amount: Math.round(original * (1 - rate)),
+		original,
+		rate
+	};
+}
+/** 计算某方案全部档位价格 */
+function calcTiers({ monthly, discount }) {
+	return MONTH_TIERS.map((months) => ({
+		months,
+		...calcPlanPrice({
+			monthly,
+			months,
+			discount
+		})
+	}));
+}
+/** 订阅方案价格（key 未配置则抛错；product 忽略 months） */
+async function price(key, opts) {
+	const cfg = await getConfig();
+	const plan = cfg.plans[key];
+	if (plan) {
+		const months = opts?.months ?? 1;
+		const { amount, original, rate } = calcPlanPrice({
+			monthly: plan.monthly,
+			months,
+			discount: plan.discount
+		});
+		return {
+			key,
+			kind: "plan",
+			name: plan.name,
+			plan_id: plan.plan_id,
+			months,
+			amount,
+			original,
+			rate
+		};
+	}
+	const product = cfg.products[key];
+	if (product) return {
+		key,
+		kind: "product",
+		name: product.name,
+		plan_id: product.plan_id,
+		amount: product.price,
+		fixed: true
+	};
+	throw new Error(`未找到配置项: ${key}（检查 afdian.config 的 plans/products）`);
+}
+/** 订阅方案列表（含逐档价格表，可按档位区间过滤） */
+async function listPlans(opts) {
+	const cfg = await getConfig();
+	return Object.entries(cfg.plans).map(([key, plan]) => ({
+		key,
+		plan_id: plan.plan_id,
+		name: plan.name,
+		monthly: plan.monthly,
+		discount: plan.discount,
+		tiers: calcTiers(plan).filter((t) => (opts?.from === void 0 || t.months >= opts.from) && (opts?.to === void 0 || t.months <= opts.to))
+	}));
+}
+/** 固定商品列表 */
+async function listProducts() {
+	const cfg = await getConfig();
+	return Object.entries(cfg.products).map(([key, product]) => ({
+		key,
+		plan_id: product.plan_id,
+		name: product.name,
+		price: product.price
+	}));
+}
+/** 单个固定商品（未配置返回 null） */
+async function getProduct(key) {
+	const product = (await getConfig()).products[key];
+	if (!product) return null;
+	return {
+		key,
+		plan_id: product.plan_id,
+		name: product.name,
+		price: product.price
+	};
+}
+//#endregion
+//#region src/verify.ts
+/**
+* 爱发电 webhook 验签
+* sign_str = out_trade_no + user_id + plan_id + total_amount 依次无分隔符拼接
+* RSA-SHA256（RSASSA-PKCS1-v1_5），data.sign 为 base64 签名
+*
+* 注意：Web Crypto（crypto.subtle）仅有异步 API，任何环境都无法同步验签，
+* 因此 verify 为 async。不依赖 config，公钥通过第二参显式传入（默认官方公钥）。
+*/
+/** 爱发电官方公钥（默认） */
+const AFDIAN_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwwdaCg1Bt+UKZKs0R54y
+lYnuANma49IpgoOwNmk3a0rhg/PQuhUJ0EOZSowIC44l0K3+fqGns3Ygi4AfmEfS
+4EKbdk1ahSxu7Zkp2rHMt+R9GarQFQkwSS/5x1dYiHNVMiR8oIXDgjmvxuNes2Cr
+8fw9dEF0xNBKdkKgG2qAawcN1nZrdyaKWtPVT9m2Hl0ddOO9thZmVLFOb9NVzgYf
+jEgI+KWX6aY19Ka/ghv/L4t1IXmz9pctablN5S0CRWpJW3Cn0k6zSXgjVdKm4uN7
+jRlgSRaf/Ind46vMCm3N2sgwxu/g3bnooW+db0iLo13zzuvyn727Q3UDQ0MmZcEW
+MQIDAQAB
+-----END PUBLIC KEY-----`;
+/** 组装签名串（与官方文档一致：四字段依次拼接，无分隔符） */
+function buildSignStr(order) {
+	return `${order.out_trade_no}${order.user_id}${order.plan_id}${order.total_amount}`;
+}
+function pemToDer(pem) {
+	const body = pem.replace(/-----BEGIN PUBLIC KEY-----/g, "").replace(/-----END PUBLIC KEY-----/g, "").replace(/\s+/g, "");
+	const raw = atob(body);
+	const bytes = new Uint8Array(raw.length);
+	for (let i = 0; i < raw.length; i++) bytes[i] = raw.charCodeAt(i);
+	return bytes.buffer;
+}
+/**
+* 验证 webhook 报文签名，返回验证之后的数据
+*
+* @param payload 完整报文（字符串或已解析对象，需含 data.sign 与 data.order）
+* @param opts.publicKey 覆盖公钥（PEM；轮换/测试用 —— 显式传参，不读 config，无隐式顺序）
+*/
+async function verify(payload, opts) {
+	let parsed;
+	if (typeof payload === "string") try {
+		parsed = JSON.parse(payload);
+	} catch {
+		return {
+			valid: false,
+			reason: "bad json"
+		};
+	}
+	else parsed = payload;
+	const order = parsed.data?.order;
+	const sign = parsed.data?.sign;
+	if (!order || !sign) return {
+		valid: false,
+		reason: "missing fields"
+	};
+	if (![
+		"out_trade_no",
+		"user_id",
+		"plan_id",
+		"total_amount"
+	].every((f) => typeof order[f] === "string")) return {
+		valid: false,
+		reason: "missing fields"
+	};
+	try {
+		const key = await crypto.subtle.importKey("spki", pemToDer(opts?.publicKey ?? AFDIAN_PUBLIC_KEY), {
+			name: "RSASSA-PKCS1-v1_5",
+			hash: "SHA-256"
+		}, false, ["verify"]);
+		const sigRaw = atob(sign);
+		const sig = new Uint8Array(sigRaw.length);
+		for (let i = 0; i < sigRaw.length; i++) sig[i] = sigRaw.charCodeAt(i);
+		const data = new TextEncoder().encode(buildSignStr(order));
+		if (!await crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, sig, data)) return {
+			valid: false,
+			reason: "bad sign"
+		};
+	} catch {
+		return {
+			valid: false,
+			reason: "bad sign"
+		};
+	}
+	return {
+		valid: true,
+		type: parsed.data?.type ?? "order",
+		order
+	};
+}
+//#endregion
+//#region src/order.ts
+/**
+* 按 order.plan_id 匹配配置并给出该单应收金额（应用做金额核对的辅助）
+* 匹配不到返回 null（应用记 rejected）
+*/
+async function resolveOrder(order) {
+	const cfg = await getConfig();
+	const planHit = Object.entries(cfg.plans).find(([, entry]) => entry.plan_id === order.plan_id);
+	if (planHit) {
+		const [key, entry] = planHit;
+		let expectedAmount;
+		try {
+			expectedAmount = calcPlanPrice({
+				monthly: entry.monthly,
+				months: order.month ?? 1,
+				discount: entry.discount
+			}).amount;
+		} catch {
+			expectedAmount = null;
+		}
+		return {
+			key,
+			kind: "plan",
+			entry,
+			expectedAmount
+		};
+	}
+	const productHit = Object.entries(cfg.products).find(([, entry]) => entry.plan_id === order.plan_id);
+	if (productHit) {
+		const [key, entry] = productHit;
+		return {
+			key,
+			kind: "product",
+			entry,
+			expectedAmount: entry.price
+		};
+	}
+	return null;
+}
+/**
+* 生成爱发电下单跳转 URL
+* - plans entry：product_type=0，months 默认 1（非法档位抛错）
+* - products entry：product_type=1，不带 month
+*/
+async function buildUrl(opts) {
+	const cfg = await getConfig();
+	const plan = cfg.plans[opts.entry];
+	if (plan) {
+		const months = opts.months ?? 1;
+		calcPlanPrice({
+			monthly: plan.monthly,
+			months,
+			discount: plan.discount
+		});
+		return `https://afdian.com/order/create?${new URLSearchParams({
+			plan_id: plan.plan_id,
+			product_type: "0",
+			month: String(months),
+			custom_order_id: opts.userId
+		})}`;
+	}
+	const product = cfg.products[opts.entry];
+	if (product) return `https://afdian.com/order/create?${new URLSearchParams({
+		plan_id: product.plan_id,
+		product_type: "1",
+		custom_order_id: opts.userId
+	})}`;
+	throw new Error(`未找到配置项: ${opts.entry}`);
+}
+//#endregion
+//#region src/handler.ts
+/**
+* 创建 webhook 处理器：入参报文（字符串/对象），返回爱发电契约的 ec 响应体。
+* 应用侧自行包一层 HTTP：`return Response.json(await handler(await req.text()))`
+*/
+function createWebhookHandler(deps) {
+	return async (payload) => {
+		const verified = await verify(payload, deps.publicKey ? { publicKey: deps.publicKey } : void 0);
+		if (!verified.valid) return {
+			ec: 500,
+			em: verified.reason
+		};
+		const order = verified.order;
+		const outTradeNo = order.out_trade_no;
+		const resolution = await resolveOrder(order);
+		if (!resolution) {
+			await deps.onRejected?.({
+				reason: "unknown plan",
+				order,
+				expectedAmount: null
+			});
+			return {
+				ec: 200,
+				em: "unknown plan"
+			};
+		}
+		if (await deps.store.begin(outTradeNo) === "completed") return {
+			ec: 200,
+			em: "duplicate"
+		};
+		if (deps.checkAmount !== false) {
+			const actual = Math.round(parseFloat(order.total_amount) * 100);
+			const expected = resolution.expectedAmount;
+			if (expected === null) {
+				await deps.store.complete(outTradeNo);
+				await deps.onRejected?.({
+					reason: "unverifiable amount",
+					order,
+					expectedAmount: expected
+				});
+				return {
+					ec: 200,
+					em: "unverifiable amount"
+				};
+			}
+			if (Number.isNaN(actual) || actual !== expected) {
+				await deps.store.complete(outTradeNo);
+				await deps.onRejected?.({
+					reason: "amount mismatch",
+					order,
+					expectedAmount: expected
+				});
+				return {
+					ec: 200,
+					em: "amount mismatch"
+				};
+			}
+		}
+		try {
+			await deps.onPaid({
+				order,
+				resolution,
+				key: resolution.key,
+				outTradeNo
+			});
+		} catch {
+			return {
+				ec: 500,
+				em: "onPaid failed"
+			};
+		}
+		await deps.store.complete(outTradeNo);
+		return {
+			ec: 200,
+			em: ""
+		};
+	};
+}
+//#endregion
+export { AFDIAN_PUBLIC_KEY, DISCOUNTS, MONTH_TIERS, buildSignStr, buildUrl, calcPlanPrice, calcTiers, configure, createWebhookHandler, defineConfig, getProduct, listPlans, listProducts, price, resetConfig, resolveOrder, verify };

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "afdian-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "爱发电通用工具库：价格算法 / 验签 / 下单跳转 / 配置查询（零依赖 · 无数据库）",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check": "tsdown && node scripts/check.mjs",
+    "check:pack": "node scripts/check-pack.mjs",
+    "dev": "tsdown --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laoer536/afdian-kit.git"
+  },
+  "author": "laoer536",
+  "homepage": "https://github.com/laoer536/afdian-kit#readme",
+  "bugs": {
+    "url": "https://github.com/laoer536/afdian-kit/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "afdian",
+    "ifdian",
+    "webhook",
+    "payment",
+    "subscription"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsdown": "^0.23.1",
+    "typescript": "^5.9.0"
+  }
+}