fresh-squeezy 0.1.8 → 0.1.10

package/README.md

@@ -1,63 +1,116 @@
-# fresh-squeezy
-
-Validator-first Lemon Squeezy doctor. Catches misconfigurations before they ship. CLI + library, Node 20+.
+<!-- Canonical README. Translations (README.zh-CN.md, README.ja.md, README.es.md, README.pt-BR.md) are derived from this file; English is the source of truth. -->
+
+<p align="center">
+  <a href="https://github.com/YosefHayim/fresh-squeezy">
+    <img src="assets/fresh-squeezy-hero.png" alt="fresh-squeezy — the validator-first doctor for your Lemon Squeezy setup. Catch billing and webhook misconfigurations before they ship." width="640" />
+  </a>
+</p>
+
+<p align="center">
+  <strong>The doctor for your Lemon Squeezy setup — catch billing &amp; webhook misconfigurations before they ship.</strong>
+</p>
+
+<!-- Badges. tests count is static; bump it on major test-suite changes. -->
+<p align="center">
+  <a href="https://www.npmjs.com/package/fresh-squeezy"><img src="https://img.shields.io/npm/v/fresh-squeezy?logo=npm&amp;color=cb3837" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/fresh-squeezy"><img src="https://img.shields.io/npm/dm/fresh-squeezy?logo=npm&amp;color=cb3837" alt="npm downloads per month" /></a>
+  <a href="https://github.com/YosefHayim/fresh-squeezy/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/YosefHayim/fresh-squeezy/ci.yml?branch=main&amp;logo=github&amp;label=CI" alt="CI status" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/fresh-squeezy?color=3fb950" alt="MIT license" /></a>
+  <img src="https://img.shields.io/node/v/fresh-squeezy?logo=node.js&amp;logoColor=white&amp;color=339933" alt="Node.js 20 or newer" />
+  <img src="https://img.shields.io/npm/types/fresh-squeezy?logo=typescript&amp;logoColor=white" alt="TypeScript types included" />
+  <a href="https://packagephobia.com/result?p=fresh-squeezy"><img src="https://packagephobia.com/badge?p=fresh-squeezy" alt="install size" /></a>
+  <img src="https://img.shields.io/badge/tests-154%20passing-3fb950?logo=vitest&amp;logoColor=white" alt="154 tests passing" />
+</p>
+
+<p align="center">
+  <b>English</b> ·
+  <a href="./README.zh-CN.md">简体中文</a> ·
+  <a href="./README.ja.md">日本語</a> ·
+  <a href="./README.es.md">Español</a> ·
+  <a href="./README.pt-BR.md">Português</a>
+</p>
+
+<p align="center">
+  <a href="#30-second-start">Quick start</a> ·
+  <a href="#what-it-catches-that-postman-and-the-official-sdk-wont">What it catches</a> ·
+  <a href="#fresh-squeezy-vs-the-alternatives">Comparison</a> ·
+  <a href="#cli">CLI</a> ·
+  <a href="#library">Library</a> ·
+  <a href="#issue-codes">Issue codes</a> ·
+  <a href="#faq">FAQ</a>
+</p>
+
+---
+
+**fresh-squeezy** is a CLI and TypeScript library that validates your [Lemon Squeezy](https://www.lemonsqueezy.com/) billing integration — stores, products, webhooks, discounts, license keys, and subscription plans — and catches misconfigurations before they ship. Run it as a one-command `doctor` locally or in CI: it returns stable [exit codes](#30-second-start) and machine-readable JSON, and it tracks [Lemon Squeezy API changelog](https://docs.lemonsqueezy.com/api/getting-started/changelog) drift the official SDK hasn't shipped yet. Node 20+.
 
 ## 30-second start
 
 ```bash
-npm i -D fresh-squeezy
-cp .env.example .env.local                # fill in LEMON_SQUEEZY_API_KEY
-npx fresh-squeezy doctor --all-stores
+npx fresh-squeezy
 ```
 
-No store ID to copy from the dashboard — the CLI discovers reachable stores itself.
+The first run adds `fresh-squeezy` to devDependencies when it is missing, then starts the guided setup. No store ID to copy from the dashboard — the CLI discovers reachable stores itself. Use `npx fresh-squeezy --no-install` to run the setup without editing `package.json`.
 
 | Exit | Meaning |
 |------|---------|
 | `0`  | All validators passed |
 | `1`  | One or more validators reported `error`-level issues |
 | `2`  | Fatal (missing key, invalid flags, network failure) |
+| `130` | User cancelled an interactive flow |
 
 ## What it catches that Postman and the official SDK won't
 
 - **Prod key pointed at staging.** `MODE_MISMATCH` fires when the key's true `meta.test_mode` (API changelog 2024-01-05) disagrees with the declared mode. Doctor exits 1. Neither the SDK nor a hand-rolled wrapper catches this by default.
 - **Silent store-ownership mismatches.** Products, discounts, license keys, and subscription plans whose `store_id` doesn't match the store you scoped the run to. Stable codes: `PRODUCT_WRONG_STORE`, `DISCOUNT_STORE_MISMATCH`, `LICENSE_KEY_STORE_MISMATCH`, `PLAN_STORE_MISMATCH`.
 - **Webhook subscribed to the wrong events.** Diff against a manifest of recommended events (order/subscription lifecycle, refunds) and newer-but-optional events the SDK doesn't ship.
-- **Platform drift.** A weekly GitHub Action hashes the [Lemon Squeezy API changelog](https://docs.lemonsqueezy.com/api/getting-started/changelog) against `src/support/changelog-snapshot.json` and opens an issue when it moves. Tracked additions beyond the official SDK as of 2026-04-24: `customer_updated` (2026-02-25), `payment_processor` on Subscription (2025-06-11), Affiliates + `affiliate_activated` (2025-01-21), `test_mode` on `/v1/users/me` (2024-01-05).
+- **Platform drift.** A weekly GitHub Action hashes the [Lemon Squeezy API changelog](https://docs.lemonsqueezy.com/api/getting-started/changelog) against `src/support/changelog-snapshot.json`, refreshes docs-derived API types, and opens follow-up work when policy decisions are needed. Tracked additions include `customer_updated` (2026-02-25), `payment_processor` on Subscription (2025-06-11), Affiliates + `affiliate_activated` (2025-01-21), order item `quantity` (2024-12-06), checkout styling / `skip_trial` / `variant_quantities`, subscription invoice refund fields, and `test_mode` on `/v1/users/me` (2024-01-05).
 - **Postman + dashboard ping-pong.** One `doctor` call replaces the loop of copying IDs out of the UI, pasting them into env files, and verifying each one by hand.
 
+## fresh-squeezy vs the alternatives
+
+How a typical Lemon Squeezy pre-ship check compares across the tools a developer would otherwise reach for:
+
+| Capability | fresh-squeezy | Official SDK | Postman | Hand-rolled wrapper |
+|---|:---:|:---:|:---:|:---:|
+| Mode / key mismatch detection (`MODE_MISMATCH`) | ✅ | ❌ | ❌ | ❌ |
+| Store-ownership cross-checks | ✅ | ❌ | ❌ | ⚠️ manual |
+| Webhook event-coverage diff | ✅ | ❌ | ⚠️ manual | ⚠️ manual |
+| Discount / license-key / plan validation | ✅ | ❌ | ❌ | ⚠️ manual |
+| Changelog-drift tracking | ✅ | ❌ | ❌ | ❌ |
+| Stable, CI-ready exit codes + JSON | ✅ | ❌ | ❌ | ⚠️ manual |
+| One-command full sweep (`doctor`) | ✅ | ❌ | ❌ | ❌ |
+| Typed API responses | ✅ | ✅ | ❌ | ⚠️ depends |
+
+fresh-squeezy is **not** a replacement for the official SDK — it's the pre-flight check you run *alongside* it. Use the SDK to make API calls; use fresh-squeezy to prove your setup is correct before those calls hit production.
+
 ## CLI
 
 ```bash
+# First run: install as a dev dependency, then start guided setup
+npx fresh-squeezy
+
+# Guided setup only: reuse env values, pick a store, choose resource checks
+npx fresh-squeezy init
+
 # TTY: multi-select stores interactively, run doctor on each
 npx fresh-squeezy doctor
 
-# Non-interactive: every reachable store
-npx fresh-squeezy doctor --all-stores
+# Full sweep across every reachable store and resource
+npx fresh-squeezy doctor --all-stores --all-resources
 
-# Specific stores
-npx fresh-squeezy doctor --store-ids 12,34,56
+# Machine-readable full sweep for CI
+npx fresh-squeezy doctor --all-stores --all-resources --json
 
-# Scope to a product + webhook
-npx fresh-squeezy doctor --store-ids 12 \
-  --product-id 987 \
-  --webhook-url https://app.example.com/api/webhooks/lemon-squeezy
-
-# Single validator
+# Single validator, scoped to specific stores
 npx fresh-squeezy validate webhook \
   --store-ids 12,34 \
   --webhook-url https://app.example.com/api/webhooks/lemon-squeezy
-
-# Machine-readable output for CI
-npx fresh-squeezy doctor --all-stores --json
 ```
 
-Store resolution order, used by every store-scoped command:
+Stores resolve in this order for every store-scoped command: explicit `--store-ids`, then `--all-stores`, then an interactive multi-select on a TTY, then a connection-only run when there's no TTY and no flag (useful as a CI smoke check). `doctor` validates connection and store access plus any explicit resource flags; add `--all-resources` to discover and validate every supported resource in the selected store(s).
 
-1. `--store-ids 1,2,3` (comma-separated, explicit)
-2. `--all-stores` (every store reachable with the key)
-3. TTY: inquirer multi-select prompt
-4. No TTY + no flag: connection-only run (useful as a CI smoke check)
+**→ Full command, flag, and store-resolution reference: [docs/cli-reference.md](./docs/cli-reference.md)**
 
 ## Library
 
@@ -82,9 +135,15 @@ if (!report.ok) {
 }
 ```
 
-For multi-store runs at the library layer, call `doctor()` in a loop. The CLI does exactly this.
+For multi-store runs at the library layer, call `doctor()` in a loop — the CLI does exactly this. Switch on `issue.code` in CI logic; codes are stable across minor versions.
+
+Public types: [`FreshSqueezyClient`](src/createFreshSqueezy.ts), [`ValidationResult<T>`](src/core/types.ts), [`DoctorReport`](src/core/types.ts), resource attribute interfaces under [`src/resources`](src/resources), docs-generated Lemon Squeezy object types in [`src/generated/lemonSqueezyApiTypes.ts`](src/generated/lemonSqueezyApiTypes.ts), and changelog augmentation helpers in [`src/augmentations.ts`](src/augmentations.ts).
+
+For endpoints not yet wrapped, use the raw escape hatch:
 
-Public types: [`FreshSqueezyClient`](src/createFreshSqueezy.ts), [`ValidationResult<T>`](src/core/types.ts), [`DoctorReport`](src/core/types.ts). Switch on `issue.code` in CI logic — codes are stable across minor versions.
+```ts
+const user = await lemon.request({ path: "/v1/users/me" });
+```
 
 ## Sandbox vs live
 
@@ -97,63 +156,91 @@ result.mode;                 // "test" (declared)
 result.resource?.actualMode; // "live" — alarm bell
 ```
 
-The CLI default is `--mode test`. Override with `--mode live`. For nightly platform-drift checks in CI, run `npm run test:live` with `LEMON_SQUEEZY_LIVE_SMOKE=1` and a test-mode key.
+The CLI default is `--mode test`. Override with `--mode live`. Guided setup asks for explicit confirmation before continuing with a detected live-mode key. For nightly platform-drift checks in CI, run `npm run test:live` with `LEMON_SQUEEZY_LIVE_SMOKE=1` and a test-mode key.
+
+## Environment variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `LEMON_SQUEEZY_API_KEY` | yes | Bearer token (library + CLI) |
+| `LEMON_SQUEEZY_MODE` | no | `test` (default) or `live` |
+| `LEMON_SQUEEZY_STORE_ID` | no | Convenience default for `client.doctor()` — library only |
+
+The CLI does not read `LEMON_SQUEEZY_STORE_ID`; use `--store-ids` or `--all-stores` so store selection stays explicit per command.
 
 ## Issue codes
 
-Switch on `issue.code` in CI. All codes are stable across minor versions.
+Switch on `issue.code` in CI — all codes are stable across minor versions. The most common ones:
 
 | Code | Meaning |
 |------|---------|
 | `AUTH_FAILED` | Invalid or missing API key |
 | `MODE_MISMATCH` | Declared mode doesn't match key's `meta.test_mode` |
-| `NETWORK_ERROR` | Lemon Squeezy unreachable |
 | `STORE_NOT_FOUND` / `STORE_NOT_OWNED` | Store ID invalid or owned by another account |
 | `PRODUCT_UNPUBLISHED` / `PRODUCT_WRONG_STORE` / `PRODUCT_NO_BUY_URL` | Product can't accept checkout |
-| `VARIANT_MISSING` / `VARIANT_UNPUBLISHED` | Product has no live variants |
-| `WEBHOOK_NOT_FOUND` / `WEBHOOK_EVENTS_MISSING` / `WEBHOOK_OPTIONAL_EVENTS` | Webhook URL not registered or under-subscribed |
-| `DISCOUNT_DRAFT` / `DISCOUNT_EXPIRED` / `DISCOUNT_NOT_STARTED` / `DISCOUNT_INVALID_AMOUNT` / `DISCOUNT_REDEMPTIONS_EXHAUSTED` / `DISCOUNT_STORE_MISMATCH` | Discount won't apply at checkout |
-| `LICENSE_KEY_DISABLED` / `LICENSE_KEY_EXPIRED` / `LICENSE_KEY_AT_ACTIVATION_LIMIT` / `LICENSE_KEY_STORE_MISMATCH` | License key won't activate |
-| `PLAN_NOT_SUBSCRIPTION` / `PLAN_INVALID_INTERVAL` / `PLAN_FREE_PRICE` / `PLAN_TRIAL_INCONSISTENT` / `PLAN_DRAFT` / `PLAN_STORE_MISMATCH` | Subscription plan misconfigured |
+| `WEBHOOK_NOT_FOUND` / `WEBHOOK_EVENTS_MISSING` | Webhook URL not registered or under-subscribed |
 
-For endpoints not yet wrapped, use the raw escape hatch:
+**→ Full issue-code reference (discounts, license keys, plans, variants, network) with escape-hatch examples: [docs/issue-codes.md](./docs/issue-codes.md)**
 
-```ts
-const user = await lemon.request({ path: "/v1/users/me" });
+## Reference
+
+Validators — each returns a stable `ValidationResult`:
+
+- **`validateConnection`** — reachability, key validity, store presence, declared-vs-actual mode. [→ source](src/validate/connection.ts)
+- **`validateStore`** — store ID exists and is owned by the key's account. [→ source](src/validate/store.ts)
+- **`validateProduct`** — published, on the expected store, has live variants and a buy URL. [→ source](src/validate/product.ts)
+- **`validateWebhook`** — webhook URL registered and subscribed to recommended events. [→ source](src/validate/webhook.ts)
+- **`validateDiscount`** — active, in-window, valid amount, store ownership matches. [→ source](src/validate/discount.ts)
+- **`validateLicenseKey`** — enabled, not expired, activations available, store ownership matches. [→ source](src/validate/licenseKey.ts)
+- **`validateSubscriptionPlan`** — subscription type, valid interval, non-zero price, consistent trial. [→ source](src/validate/subscriptionPlan.ts)
+- **`doctor`** — composes the above into one `DoctorReport`. [→ source](src/validate/doctor.ts)
+
+Resource coverage is generated from Lemon Squeezy's object docs, so most newly documented fields don't need a hand edit:
+
+```bash
+npm run generate:api-types
+npm run check:api-types
 ```
 
-## Environment variables
+## FAQ
 
-| Variable | Required | Purpose |
-|----------|----------|---------|
-| `LEMON_SQUEEZY_API_KEY` | yes | Bearer token (library + CLI) |
-| `LEMON_SQUEEZY_MODE` | no | `test` (default) or `live` |
-| `LEMON_SQUEEZY_STORE_ID` | no | Convenience default for `client.doctor()` — library only |
+### How do I check if my Lemon Squeezy webhook is subscribed to the right events?
 
-The CLI does not read `LEMON_SQUEEZY_STORE_ID`; use `--store-ids` or `--all-stores` so store selection stays explicit per command.
+Run `npx fresh-squeezy validate webhook --store-ids <id> --webhook-url <url>`. fresh-squeezy diffs your webhook's subscribed events against a manifest of recommended order/subscription/refund events and reports `WEBHOOK_EVENTS_MISSING` for gaps, or `WEBHOOK_NOT_FOUND` if the URL isn't registered at all.
 
-## Reference
+### How do I catch a Lemon Squeezy production key pointed at a test (staging) store?
+
+That's the `MODE_MISMATCH` check. fresh-squeezy compares the mode you declared (`--mode` or `LEMON_SQUEEZY_MODE`) against the key's real `meta.test_mode` from `/v1/users/me`. When they disagree, `doctor` exits 1 — so a live key accidentally used in a staging deploy (or vice versa) fails the check before it reaches users.
+
+### Does fresh-squeezy work in CI?
+
+Yes. Run `npx fresh-squeezy doctor --all-stores --all-resources --json` for a machine-readable full sweep. It returns stable [exit codes](#30-second-start) (`0` pass, `1` validation errors, `2` fatal) and stable `issue.code` strings you can assert on. No TTY required — without store flags it falls back to a connection-only smoke check.
 
-### Validators
+### Is fresh-squeezy a replacement for the official Lemon Squeezy SDK?
 
-- **`validateConnection`** — Reachability, key validity, store presence, declared-vs-actual mode. [→ source](src/validate/connection.ts)
-- **`validateStore`** — Store ID exists and is owned by the key's account. [→ source](src/validate/store.ts)
-- **`validateProduct`** — Published, on the expected store, has live variants and a buy URL. [→ source](src/validate/product.ts)
-- **`validateWebhook`** — Webhook URL registered and subscribed to recommended events. [→ source](src/validate/webhook.ts)
-- **`validateDiscount`** — Active, in-window, valid amount, store ownership matches. [→ source](src/validate/discount.ts)
-- **`validateLicenseKey`** — Enabled, not expired, activations available, store ownership matches. [→ source](src/validate/licenseKey.ts)
-- **`validateSubscriptionPlan`** — Subscription type, valid interval, non-zero price, consistent trial. [→ source](src/validate/subscriptionPlan.ts)
-- **`doctor`** — Composes the above into one `DoctorReport`. [→ source](src/validate/doctor.ts)
+No. The [official SDK](https://github.com/lmsqueezy/lemonsqueezy.js) makes API calls; fresh-squeezy is the pre-flight check that proves your setup is correct *before* those calls hit production. They're complementary — see the [comparison table](#fresh-squeezy-vs-the-alternatives).
 
-### CLI commands
+### What is "changelog drift" and why should I care?
 
-- **`doctor`** — Run every configured validator and emit a report. [→ source](src/cli/commands/doctor.ts)
-- **`validate <name>`** — Run a single validator. [→ source](src/cli/commands/validate.ts)
-- **`init`** — Interactive setup: ask for credentials, pick a store, run doctor. [→ source](src/cli/commands/init.ts)
+Lemon Squeezy ships API changes (new events, new fields, new resources) faster than client SDKs adopt them. fresh-squeezy tracks the [official changelog](https://docs.lemonsqueezy.com/api/getting-started/changelog) against a committed snapshot via a weekly GitHub Action, so newly recommended webhook events or response fields surface as actionable work instead of silently going unvalidated.
+
+### Can I use fresh-squeezy as a library instead of the CLI?
+
+Yes. `import { createFreshSqueezy } from "fresh-squeezy"` and call `doctor()` or any individual validator. Every validator returns a typed, stable `ValidationResult` you can branch on — see [Library](#library).
+
+### Which Lemon Squeezy resources can it validate?
+
+Connection/auth, stores, products (and variants), webhooks, discounts, license keys, and subscription plans. Add `--all-resources` to discover and validate every supported resource in the selected store(s). Full list in the [reference](#reference).
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md). Clone, `npm install`, `npm test`.
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Clone, `npm install`, `npm test`. The project aims to stay small and boring — validator-first, one HTTP layer, stable `issue.code` contract.
+
+## Contributors
+
+<a href="https://github.com/YosefHayim/fresh-squeezy/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=YosefHayim/fresh-squeezy" alt="fresh-squeezy contributors" />
+</a>
 
 ## License
 

package/README.pt-BR.md

@@ -0,0 +1,249 @@
+<!-- Traduzido de README.md; a versão em inglês é a fonte da verdade. -->
+
+<p align="center">
+  <a href="https://github.com/YosefHayim/fresh-squeezy">
+    <img src="assets/fresh-squeezy-hero.png" alt="fresh-squeezy — o doctor validator-first para a sua configuração do Lemon Squeezy. Detecte erros de configuração de cobrança e webhooks antes de subir para produção." width="640" />
+  </a>
+</p>
+
+<p align="center">
+  <strong>O doctor para a sua configuração do Lemon Squeezy — detecte erros de configuração de cobrança e webhooks antes de subir para produção.</strong>
+</p>
+
+<!-- Badges. tests count is static; bump it on major test-suite changes. -->
+<p align="center">
+  <a href="https://www.npmjs.com/package/fresh-squeezy"><img src="https://img.shields.io/npm/v/fresh-squeezy?logo=npm&amp;color=cb3837" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/fresh-squeezy"><img src="https://img.shields.io/npm/dm/fresh-squeezy?logo=npm&amp;color=cb3837" alt="npm downloads per month" /></a>
+  <a href="https://github.com/YosefHayim/fresh-squeezy/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/YosefHayim/fresh-squeezy/ci.yml?branch=main&amp;logo=github&amp;label=CI" alt="CI status" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/fresh-squeezy?color=3fb950" alt="MIT license" /></a>
+  <img src="https://img.shields.io/node/v/fresh-squeezy?logo=node.js&amp;logoColor=white&amp;color=339933" alt="Node.js 20 or newer" />
+  <img src="https://img.shields.io/npm/types/fresh-squeezy?logo=typescript&amp;logoColor=white" alt="TypeScript types included" />
+  <a href="https://packagephobia.com/result?p=fresh-squeezy"><img src="https://packagephobia.com/badge?p=fresh-squeezy" alt="install size" /></a>
+  <img src="https://img.shields.io/badge/tests-154%20passing-3fb950?logo=vitest&amp;logoColor=white" alt="154 tests passing" />
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> ·
+  <a href="./README.zh-CN.md">简体中文</a> ·
+  <a href="./README.ja.md">日本語</a> ·
+  <a href="./README.es.md">Español</a> ·
+  <b>Português</b>
+</p>
+
+> As traduções podem estar desatualizadas. A versão canônica é o [README em inglês](./README.md).
+
+<p align="center">
+  <a href="#início-rápido-em-30-segundos">Início rápido</a> ·
+  <a href="#o-que-ele-detecta-que-o-postman-e-o-sdk-oficial-não-detectam">O que ele detecta</a> ·
+  <a href="#fresh-squeezy-vs-as-alternativas">Comparação</a> ·
+  <a href="#cli">CLI</a> ·
+  <a href="#biblioteca">Biblioteca</a> ·
+  <a href="#códigos-de-problema">Códigos de problema</a> ·
+  <a href="#faq">FAQ</a>
+</p>
+
+---
+
+O **fresh-squeezy** é uma CLI e uma biblioteca TypeScript que valida a sua integração de cobrança do [Lemon Squeezy](https://www.lemonsqueezy.com/) — lojas, produtos, webhooks, descontos, chaves de licença e planos de assinatura — e detecta erros de configuração antes de subir para produção. Execute-o como um `doctor` de um único comando localmente ou em CI: ele retorna [códigos de saída](#início-rápido-em-30-segundos) estáveis e JSON legível por máquina, e acompanha o drift do [changelog da API do Lemon Squeezy](https://docs.lemonsqueezy.com/api/getting-started/changelog) que o SDK oficial ainda não incorporou. Node 20+.
+
+## Início rápido em 30 segundos
+
+```bash
+npx fresh-squeezy
+```
+
+A primeira execução adiciona `fresh-squeezy` às devDependencies quando ele está ausente e, em seguida, inicia a configuração guiada. Nenhum ID de loja para copiar do dashboard — a CLI descobre por conta própria as lojas acessíveis. Use `npx fresh-squeezy --no-install` para executar a configuração sem editar o `package.json`.
+
+| Saída | Significado |
+|------|---------|
+| `0`  | Todos os validadores passaram |
+| `1`  | Um ou mais validadores reportaram problemas de nível `error` |
+| `2`  | Fatal (chave ausente, flags inválidas, falha de rede) |
+| `130` | O usuário cancelou um fluxo interativo |
+
+## O que ele detecta que o Postman e o SDK oficial não detectam
+
+- **Chave de produção apontando para staging.** `MODE_MISMATCH` dispara quando o `meta.test_mode` real da chave (changelog da API 2024-01-05) diverge do modo declarado. O doctor sai com 1. Nem o SDK nem um wrapper feito à mão detectam isso por padrão.
+- **Divergências silenciosas de propriedade de loja.** Produtos, descontos, chaves de licença e planos de assinatura cujo `store_id` não corresponde à loja para a qual você limitou a execução. Códigos estáveis: `PRODUCT_WRONG_STORE`, `DISCOUNT_STORE_MISMATCH`, `LICENSE_KEY_STORE_MISMATCH`, `PLAN_STORE_MISMATCH`.
+- **Webhook inscrito nos eventos errados.** Diff em relação a um manifesto de eventos recomendados (ciclo de vida de pedidos/assinaturas, reembolsos) e eventos mais novos, porém opcionais, que o SDK não incorpora.
+- **Drift da plataforma.** Uma GitHub Action semanal calcula o hash do [changelog da API do Lemon Squeezy](https://docs.lemonsqueezy.com/api/getting-started/changelog) em relação ao `src/support/changelog-snapshot.json`, atualiza os tipos de API derivados da documentação e abre trabalho de acompanhamento quando decisões de política são necessárias. As adições rastreadas incluem `customer_updated` (2026-02-25), `payment_processor` em Subscription (2025-06-11), Afiliados + `affiliate_activated` (2025-01-21), `quantity` em item de pedido (2024-12-06), estilização de checkout / `skip_trial` / `variant_quantities`, campos de reembolso de fatura de assinatura e `test_mode` em `/v1/users/me` (2024-01-05).
+- **Ping-pong entre Postman e dashboard.** Uma única chamada `doctor` substitui o loop de copiar IDs da interface, colá-los em arquivos de env e verificar cada um manualmente.
+
+## fresh-squeezy vs as alternativas
+
+Como uma verificação típica pré-deploy do Lemon Squeezy se compara entre as ferramentas que um desenvolvedor recorreria de outra forma:
+
+| Recurso | fresh-squeezy | SDK oficial | Postman | Wrapper feito à mão |
+|---|:---:|:---:|:---:|:---:|
+| Detecção de divergência de modo / chave (`MODE_MISMATCH`) | ✅ | ❌ | ❌ | ❌ |
+| Verificações cruzadas de propriedade de loja | ✅ | ❌ | ❌ | ⚠️ manual |
+| Diff de cobertura de eventos de webhook | ✅ | ❌ | ⚠️ manual | ⚠️ manual |
+| Validação de desconto / chave de licença / plano | ✅ | ❌ | ❌ | ⚠️ manual |
+| Rastreamento de drift do changelog | ✅ | ❌ | ❌ | ❌ |
+| Códigos de saída estáveis e prontos para CI + JSON | ✅ | ❌ | ❌ | ⚠️ manual |
+| Varredura completa em um único comando (`doctor`) | ✅ | ❌ | ❌ | ❌ |
+| Respostas de API tipadas | ✅ | ✅ | ❌ | ⚠️ depende |
+
+O fresh-squeezy **não** é um substituto para o SDK oficial — é a verificação pré-voo que você executa *junto* dele. Use o SDK para fazer chamadas de API; use o fresh-squeezy para comprovar que a sua configuração está correta antes que essas chamadas cheguem à produção.
+
+## CLI
+
+```bash
+# First run: install as a dev dependency, then start guided setup
+npx fresh-squeezy
+
+# Guided setup only: reuse env values, pick a store, choose resource checks
+npx fresh-squeezy init
+
+# TTY: multi-select stores interactively, run doctor on each
+npx fresh-squeezy doctor
+
+# Full sweep across every reachable store and resource
+npx fresh-squeezy doctor --all-stores --all-resources
+
+# Machine-readable full sweep for CI
+npx fresh-squeezy doctor --all-stores --all-resources --json
+
+# Single validator, scoped to specific stores
+npx fresh-squeezy validate webhook \
+  --store-ids 12,34 \
+  --webhook-url https://app.example.com/api/webhooks/lemon-squeezy
+```
+
+As lojas são resolvidas nesta ordem para todo comando com escopo de loja: `--store-ids` explícito, depois `--all-stores`, depois uma seleção múltipla interativa em um TTY e, por fim, uma execução somente de conexão quando não há TTY nem flag (útil como smoke check de CI). O `doctor` valida a conexão e o acesso à loja, além de quaisquer flags de recurso explícitas; adicione `--all-resources` para descobrir e validar todos os recursos suportados na(s) loja(s) selecionada(s).
+
+**→ Referência completa de comandos, flags e resolução de lojas: [docs/cli-reference.md](./docs/cli-reference.md)**
+
+## Biblioteca
+
+```ts
+import { createFreshSqueezy } from "fresh-squeezy";
+
+const lemon = createFreshSqueezy(); // reads LEMON_SQUEEZY_API_KEY, LEMON_SQUEEZY_MODE
+
+const report = await lemon.doctor({
+  storeId: 12,                      // library is single-store per call
+  productId: 987,
+  webhookUrl: "https://app.example.com/api/webhooks/lemon-squeezy",
+});
+
+if (!report.ok) {
+  for (const result of report.results) {
+    for (const issue of result.issues) {
+      console.error(`[${issue.severity}] ${issue.code}: ${issue.message}`);
+    }
+  }
+  process.exit(1);
+}
+```
+
+Para execuções multi-loja na camada de biblioteca, chame `doctor()` em um loop — a CLI faz exatamente isso. Faça o branch com base em `issue.code` na lógica de CI; os códigos são estáveis entre versões menores.
+
+Tipos públicos: [`FreshSqueezyClient`](src/createFreshSqueezy.ts), [`ValidationResult<T>`](src/core/types.ts), [`DoctorReport`](src/core/types.ts), interfaces de atributos de recurso em [`src/resources`](src/resources), tipos de objeto do Lemon Squeezy gerados a partir da documentação em [`src/generated/lemonSqueezyApiTypes.ts`](src/generated/lemonSqueezyApiTypes.ts) e helpers de augmentação do changelog em [`src/augmentations.ts`](src/augmentations.ts).
+
+Para endpoints ainda não encapsulados, use a saída de emergência bruta:
+
+```ts
+const user = await lemon.request({ path: "/v1/users/me" });
+```
+
+## Sandbox vs live
+
+O Lemon Squeezy atende os dois modos a partir do mesmo host de API; o modo é determinado pela chave. O `fresh-squeezy` faz a verificação cruzada do modo declarado contra o `meta.test_mode` de `/v1/users/me`. Divergência = `MODE_MISMATCH`, o doctor sai com 1 — a forma mais rápida de detectar uma chave de produção apontando para staging antes que ela cause danos.
+
+```ts
+const lemon = createFreshSqueezy({ mode: "test" });
+const result = await lemon.validateConnection();
+result.mode;                 // "test" (declared)
+result.resource?.actualMode; // "live" — alarm bell
+```
+
+O padrão da CLI é `--mode test`. Sobrescreva com `--mode live`. A configuração guiada pede confirmação explícita antes de continuar com uma chave em modo live detectada. Para verificações noturnas de drift da plataforma em CI, execute `npm run test:live` com `LEMON_SQUEEZY_LIVE_SMOKE=1` e uma chave em modo de teste.
+
+## Variáveis de ambiente
+
+| Variável | Obrigatória | Finalidade |
+|----------|----------|---------|
+| `LEMON_SQUEEZY_API_KEY` | sim | Bearer token (biblioteca + CLI) |
+| `LEMON_SQUEEZY_MODE` | não | `test` (padrão) ou `live` |
+| `LEMON_SQUEEZY_STORE_ID` | não | Padrão de conveniência para `client.doctor()` — somente biblioteca |
+
+A CLI não lê `LEMON_SQUEEZY_STORE_ID`; use `--store-ids` ou `--all-stores` para que a seleção de loja permaneça explícita em cada comando.
+
+## Códigos de problema
+
+Faça o branch com base em `issue.code` na CI — todos os códigos são estáveis entre versões menores. Os mais comuns:
+
+| Código | Significado |
+|------|---------|
+| `AUTH_FAILED` | Chave de API inválida ou ausente |
+| `MODE_MISMATCH` | O modo declarado não corresponde ao `meta.test_mode` da chave |
+| `STORE_NOT_FOUND` / `STORE_NOT_OWNED` | ID de loja inválido ou pertencente a outra conta |
+| `PRODUCT_UNPUBLISHED` / `PRODUCT_WRONG_STORE` / `PRODUCT_NO_BUY_URL` | O produto não pode aceitar checkout |
+| `WEBHOOK_NOT_FOUND` / `WEBHOOK_EVENTS_MISSING` | URL do webhook não registrada ou com inscrição insuficiente |
+
+**→ Referência completa de códigos de problema (descontos, chaves de licença, planos, variantes, rede) com exemplos de saída de emergência: [docs/issue-codes.md](./docs/issue-codes.md)**
+
+## Referência
+
+Validadores — cada um retorna um `ValidationResult` estável:
+
+- **`validateConnection`** — acessibilidade, validade da chave, presença da loja, modo declarado vs. real. [→ código-fonte](src/validate/connection.ts)
+- **`validateStore`** — o ID da loja existe e pertence à conta da chave. [→ código-fonte](src/validate/store.ts)
+- **`validateProduct`** — publicado, na loja esperada, com variantes live e uma URL de compra. [→ código-fonte](src/validate/product.ts)
+- **`validateWebhook`** — URL do webhook registrada e inscrita nos eventos recomendados. [→ código-fonte](src/validate/webhook.ts)
+- **`validateDiscount`** — ativo, dentro da janela, valor válido, propriedade de loja correspondente. [→ código-fonte](src/validate/discount.ts)
+- **`validateLicenseKey`** — habilitada, não expirada, ativações disponíveis, propriedade de loja correspondente. [→ código-fonte](src/validate/licenseKey.ts)
+- **`validateSubscriptionPlan`** — tipo de assinatura, intervalo válido, preço não nulo, trial consistente. [→ código-fonte](src/validate/subscriptionPlan.ts)
+- **`doctor`** — compõe os anteriores em um único `DoctorReport`. [→ código-fonte](src/validate/doctor.ts)
+
+A cobertura de recursos é gerada a partir da documentação de objetos do Lemon Squeezy, então a maioria dos campos recém-documentados não precisa de edição manual:
+
+```bash
+npm run generate:api-types
+npm run check:api-types
+```
+
+## FAQ
+
+### Como verifico se o meu webhook do Lemon Squeezy está inscrito nos eventos certos?
+
+Execute `npx fresh-squeezy validate webhook --store-ids <id> --webhook-url <url>`. O fresh-squeezy compara os eventos inscritos do seu webhook com um manifesto de eventos recomendados de pedido/assinatura/reembolso e reporta `WEBHOOK_EVENTS_MISSING` para as lacunas, ou `WEBHOOK_NOT_FOUND` se a URL não estiver registrada de forma alguma.
+
+### Como detecto uma chave de produção do Lemon Squeezy apontando para uma loja de teste (staging)?
+
+Essa é a verificação `MODE_MISMATCH`. O fresh-squeezy compara o modo que você declarou (`--mode` ou `LEMON_SQUEEZY_MODE`) com o `meta.test_mode` real da chave de `/v1/users/me`. Quando eles divergem, o `doctor` sai com 1 — então uma chave live usada acidentalmente em um deploy de staging (ou vice-versa) falha na verificação antes de chegar aos usuários.
+
+### O fresh-squeezy funciona em CI?
+
+Sim. Execute `npx fresh-squeezy doctor --all-stores --all-resources --json` para uma varredura completa legível por máquina. Ele retorna [códigos de saída](#início-rápido-em-30-segundos) estáveis (`0` passou, `1` erros de validação, `2` fatal) e strings `issue.code` estáveis nas quais você pode fazer asserções. Não requer TTY — sem flags de loja, ele recorre a um smoke check apenas de conexão.
+
+### O fresh-squeezy é um substituto para o SDK oficial do Lemon Squeezy?
+
+Não. O [SDK oficial](https://github.com/lmsqueezy/lemonsqueezy.js) faz chamadas de API; o fresh-squeezy é a verificação pré-voo que comprova que a sua configuração está correta *antes* que essas chamadas cheguem à produção. Eles são complementares — veja a [tabela de comparação](#fresh-squeezy-vs-as-alternativas).
+
+### O que é "drift do changelog" e por que devo me importar?
+
+O Lemon Squeezy lança mudanças de API (novos eventos, novos campos, novos recursos) mais rápido do que os SDKs clientes as adotam. O fresh-squeezy rastreia o [changelog oficial](https://docs.lemonsqueezy.com/api/getting-started/changelog) em relação a um snapshot versionado por meio de uma GitHub Action semanal, de modo que eventos de webhook ou campos de resposta recém-recomendados apareçam como trabalho acionável em vez de ficarem silenciosamente sem validação.
+
+### Posso usar o fresh-squeezy como biblioteca em vez da CLI?
+
+Sim. `import { createFreshSqueezy } from "fresh-squeezy"` e chame `doctor()` ou qualquer validador individual. Todo validador retorna um `ValidationResult` tipado e estável no qual você pode fazer o branch — veja [Biblioteca](#biblioteca).
+
+### Quais recursos do Lemon Squeezy ele consegue validar?
+
+Conexão/autenticação, lojas, produtos (e variantes), webhooks, descontos, chaves de licença e planos de assinatura. Adicione `--all-resources` para descobrir e validar todos os recursos suportados na(s) loja(s) selecionada(s). Lista completa na [referência](#referência).
+
+## Contribuindo
+
+Veja [CONTRIBUTING.md](./CONTRIBUTING.md). Clone, `npm install`, `npm test`. O projeto busca permanecer pequeno e sem firulas — validator-first, uma única camada HTTP, contrato `issue.code` estável.
+
+## Contribuidores
+
+<a href="https://github.com/YosefHayim/fresh-squeezy/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=YosefHayim/fresh-squeezy" alt="fresh-squeezy contributors" />
+</a>
+
+## Licença
+
+MIT — veja [LICENSE](./LICENSE).