![\"fresh-squeezy](\"public/fresh-squeezy-hero.png\")
\n \n\n \n \n \n
\n 你的 Lemon Squeezy 配置体检工具 —— 在上线前捕获计费与 webhook 配置错误。\n
\n\n\n\n ![\"npm](\"https://img.shields.io/npm/v/fresh-squeezy?logo=npm&color=cb3837\")
![\"npm](\"https://img.shields.io/npm/dm/fresh-squeezy?logo=npm&color=cb3837\")
![\"CI](\"https://img.shields.io/github/actions/workflow/status/YosefHayim/fresh-squeezy/ci.yml?branch=main&logo=github&label=CI\")
![\"MIT](\"https://img.shields.io/npm/l/fresh-squeezy?color=3fb950\")
![\"Node.js](\"https://img.shields.io/node/v/fresh-squeezy?logo=node.js&logoColor=white&color=339933\")
![\"TypeScript](\"https://img.shields.io/npm/types/fresh-squeezy?logo=typescript&logoColor=white\")
\n
![\"154](\"https://img.shields.io/badge/tests-154%20passing-3fb950?logo=vitest&logoColor=white\"){kind=icon}
\n English ·\n 简体中文 ·\n 日本語 ·\n Español ·\n Português\n
\n\n> 翻译可能落后于最新版本，以 [English README](./README.md) 为准。\n\n\n 快速上手 ·\n 它能捕获什么 ·\n 对比 ·\n CLI ·\n 库 ·\n 问题代码 ·\n FAQ\n
\n\n---\n\n**fresh-squeezy** 是一个 CLI 和 TypeScript 库，用于验证你的 [Lemon Squeezy](https://www.lemonsqueezy.com/) 计费集成 —— 店铺、产品、webhook、折扣、许可证密钥和订阅计划 —— 并在上线前捕获配置错误。你可以将它作为一条命令的 `doctor` 在本地或 CI 中运行：它会返回稳定的[退出码](#30-秒上手)和机器可读的 JSON，并跟踪官方 SDK 尚未实现的 [Lemon Squeezy API 更新日志](https://docs.lemonsqueezy.com/api/getting-started/changelog)漂移。需要 Node 20+。\n\n## 30 秒上手\n\n```bash\nnpx fresh-squeezy\n```\n\n首次运行时，如果 `fresh-squeezy` 不在 devDependencies 中，会自动添加，然后启动引导式配置。无需从控制台复制店铺 ID —— CLI 会自行发现可访问的店铺。使用 `npx fresh-squeezy --no-install` 可在不修改 `package.json` 的情况下运行配置。\n\n| 退出码 | 含义 |\n|------|---------|\n| `0` | 所有验证器均通过 |\n| `1` | 一个或多个验证器报告了 `error` 级别的问题 |\n| `2` | 致命错误（缺少密钥、标志无效、网络故障） |\n| `130` | 用户取消了交互流程 |\n\n## 它能捕获哪些 Postman 和官方 SDK 发现不了的问题\n\n- **生产密钥指向了测试环境。** 当密钥真实的 `meta.test_mode`（API 更新日志 2024-01-05）与声明的模式不一致时，会触发 `MODE_MISMATCH`。Doctor 以 1 退出。SDK 和手写封装默认都无法捕获这一点。\n- **店铺归属静默不匹配。** 产品、折扣、许可证密钥和订阅计划的 `store_id` 与你为本次运行指定的店铺不匹配。稳定代码：`PRODUCT_WRONG_STORE`、`DISCOUNT_STORE_MISMATCH`、`LICENSE_KEY_STORE_MISMATCH`、`PLAN_STORE_MISMATCH`。\n- **Webhook 订阅了错误的事件。** 与推荐事件清单（订单/订阅生命周期、退款）以及 SDK 尚未实现的较新但可选的事件进行差异比对。\n- **平台漂移。** 每周运行的 GitHub Action 会将 [Lemon Squeezy API 更新日志](https://docs.lemonsqueezy.com/api/getting-started/changelog)与 `src/support/changelog-snapshot.json` 进行哈希比对，刷新由文档派生的 API 类型，并在需要做出策略决策时开启后续工作。已跟踪的新增项包括 `customer_updated`（2026-02-25）、Subscription 上的 `payment_processor`（2025-06-11）、Affiliates + `affiliate_activated`（2025-01-21）、订单项 `quantity`（2024-12-06）、结账样式 / `skip_trial` / `variant_quantities`、订阅发票退款字段，以及 `/v1/users/me` 上的 `test_mode`（2024-01-05）。\n- **Postman + 控制台来回折腾。** 一次 `doctor` 调用即可替代从界面复制 ID、粘贴到环境文件、再逐个手动核验的循环。\n\n## fresh-squeezy 与替代方案对比\n\n下面比较了一次典型的 Lemon Squeezy 上线前检查在开发者本来会选用的各类工具上的表现：\n\n| 能力 | fresh-squeezy | 官方 SDK | Postman | 手写封装 |\n|---|:---:|:---:|:---:|:---:|\n| 模式 / 密钥不匹配检测（`MODE_MISMATCH`） | ✅ | ❌ | ❌ | ❌ |\n| 店铺归属交叉核验 | ✅ | ❌ | ❌ | ⚠️ 手动 |\n| Webhook 事件覆盖差异比对 | ✅ | ❌ | ⚠️ 手动 | ⚠️ 手动 |\n| 折扣 / 许可证密钥 / 计划验证 | ✅ | ❌ | ❌ | ⚠️ 手动 |\n| 更新日志漂移跟踪 | ✅ | ❌ | ❌ | ❌ |\n| 稳定的、可用于 CI 的退出码 + JSON | ✅ | ❌ | ❌ | ⚠️ 手动 |\n| 一条命令完成全面扫描（`doctor`） | ✅ | ❌ | ❌ | ❌ |\n| 带类型的 API 响应 | ✅ | ✅ | ❌ | ⚠️ 视情况 |\n\nfresh-squeezy **不是**官方 SDK 的替代品 —— 它是你*配合* SDK 一起运行的预检工具。用 SDK 来发起 API 调用；用 fresh-squeezy 在这些调用进入生产环境之前证明你的配置是正确的。\n\n## CLI\n\n```bash\n# First run: install as a dev dependency, then start guided setup\nnpx fresh-squeezy\n\n# Guided setup only: reuse env values, pick a store, choose resource checks\nnpx fresh-squeezy init\n\n# TTY: multi-select stores interactively, run doctor on each\nnpx fresh-squeezy doctor\n\n# Full sweep across every reachable store and resource\nnpx fresh-squeezy doctor --all-stores --all-resources\n\n# Machine-readable full sweep for CI\nnpx fresh-squeezy doctor --all-stores --all-resources --json\n\n# Single validator, scoped to specific stores\nnpx fresh-squeezy validate webhook \\\n --store-ids 12,34 \\\n --webhook-url https://app.example.com/api/webhooks/lemon-squeezy\n```\n\n对于每个以店铺为作用域的命令，店铺按以下顺序解析：显式的 `--store-ids`，然后是 `--all-stores`，然后是在 TTY 上的交互式多选，最后是在没有 TTY 且没有标志时仅做连接的运行（可作为 CI 冒烟检查）。`doctor` 会验证连接、店铺访问权限以及任何显式的资源标志；加上 `--all-resources` 可在所选店铺中发现并验证每一种受支持的资源。\n\n**→ 完整的命令、标志和店铺解析参考：[docs/cli-reference.md](./docs/cli-reference.md)**\n\n## 库\n\n```ts\nimport { createFreshSqueezy } from \"fresh-squeezy\";\n\nconst lemon = createFreshSqueezy(); // reads LEMON_SQUEEZY_API_KEY, LEMON_SQUEEZY_MODE\n\nconst report = await lemon.doctor({\n storeId: 12, // library is single-store per call\n productId: 987,\n webhookUrl: \"https://app.example.com/api/webhooks/lemon-squeezy\",\n});\n\nif (!report.ok) {\n for (const result of report.results) {\n for (const issue of result.issues) {\n console.error(`[${issue.severity}] ${issue.code}: ${issue.message}`);\n }\n }\n process.exit(1);\n}\n```\n\n如需在库层进行多店铺运行，请在循环中调用 `doctor()` —— CLI 正是这样做的。在 CI 逻辑中对 `issue.code` 进行分支判断；这些代码在次版本之间保持稳定。\n\n公共类型：[`FreshSqueezyClient`](src/createFreshSqueezy.ts)、[`ValidationResult