kasy-cli 1.2.1

package/templates/firebase/docs/ios-release.pt.md

@@ -0,0 +1,54 @@
+# Publicar no iOS (App Store)
+
+## Pré-requisitos
+
+- Conta [Apple Developer](https://developer.apple.com) (paga)
+- App criado no [App Store Connect](https://appstoreconnect.apple.com) com o mesmo **Bundle ID** do projeto
+- Mac com Xcode e Flutter instalados
+
+## Configuração única
+
+```bash
+kasy ios configure
+```
+
+O comando abre os links da Apple, pede a chave API (`.p8`) e grava `.kasy/apple.env` (não vai para o Git).
+
+## Assinatura no Xcode (obrigatório uma vez)
+
+O Kasy remove o `DEVELOPMENT_TEAM` do template para você usar sua conta Apple.
+
+1. Abra `ios/Runner.xcworkspace` no Xcode.
+2. Target **Runner** → **Signing & Capabilities** → marque **Automatically manage signing** e escolha seu **Team**.
+
+Confira com `kasy doctor` (seção Release iOS).
+
+## Envio do IPA
+
+O comando usa **`xcrun altool`** com chave API (mesmo fluxo do CI do kit). Alternativa manual: app **Transporter** com o `.ipa` em `build/ios/ipa/`.
+
+## Enviar nova versão
+
+```bash
+kasy ios release
+```
+
+Isso incrementa o build no `pubspec.yaml`, gera o IPA e envia para a App Store Connect (sem Transporter).
+
+Atalho: `make release-ios`
+
+### Opções
+
+- `kasy ios build` — só gera o IPA, sem enviar
+- `kasy ios release --no-bump` — não incrementa o build
+- `kasy ios release --version-name 1.0.1` — altera a versão visível
+
+## Sem Mac?
+
+Use build na nuvem: [codemagic-release.md](./codemagic-release.md) e `kasy codemagic configure` / `kasy codemagic release`.
+
+## Verificar ambiente
+
+```bash
+kasy doctor
+```

package/templates/firebase/docs/navigation-transitions.md

@@ -0,0 +1,80 @@
+# Navigation transitions (Kasy Kit)
+
+## Overview
+
+Screen transitions are centralized under `lib/core/navigation/`.  
+**Android, iOS, and Web use the same animation** — not `Zoom` on Android and `Cupertino` on iOS.
+
+## Change the default for the whole app
+
+Edit [`lib/core/navigation/kasy_navigation_config.dart`](../lib/core/navigation/kasy_navigation_config.dart):
+
+```dart
+class KasyNavigationConfig {
+  static KasyTransitionKind push = KasyTransitionKind.fade; // change here
+  static const Duration duration = Duration(milliseconds: 250);
+  // ...
+}
+```
+
+| Config field | Used for |
+|--------------|----------|
+| `push` | Most GoRouter routes (`kasyTransitionPage` without override) |
+| `replace` | Reserved for replace-style navigation |
+| `authPeer` | Login ↔ signup |
+| `bottomTab` | Bottom menu tabs (Bart) |
+| `onboardingStep` | Onboarding inner navigator |
+
+## Add a new GoRouter route
+
+Use `pageBuilder`, not `builder`:
+
+```dart
+GoRoute(
+  path: '/my_feature',
+  pageBuilder: (context, state) => kasyTransitionPage(
+    key: state.pageKey,
+    child: const MyFeaturePage(),
+  ),
+),
+```
+
+### Override for one route
+
+```dart
+pageBuilder: (context, state) => kasyTransitionPage(
+  key: state.pageKey,
+  transition: KasyTransitionKind.none,
+  child: const MyFeaturePage(),
+),
+```
+
+## Legacy `Navigator.push`
+
+Use `KasyMaterialPageRoute` instead of `MaterialPageRoute`:
+
+```dart
+Navigator.of(context).push(
+  KasyMaterialPageRoute(builder: (_) => const MyPage()),
+);
+```
+
+## Transition kinds
+
+| Kind | Description |
+|------|-------------|
+| `fade` | Crossfade (default push) |
+| `fadeThrough` | Material fade-through |
+| `sharedAxisScaled` | Depth / scale |
+| `sharedAxisHorizontal` | Horizontal shared axis |
+| `none` | No animation |
+
+## What is NOT covered
+
+- Dialogs (`showAppDialog`, `showGeneralDialog`)
+- Bottom sheets (`showModalBottomSheet`)
+- In-widget animations (`AnimatedSwitcher`, etc.)
+
+## Fallback theme
+
+[`universal_theme.dart`](../lib/core/theme/universal_theme.dart) uses `kasyPageTransitionsTheme` so any remaining `MaterialPageRoute` still fades consistently. Prefer `kasyTransitionPage` / `KasyMaterialPageRoute` for new code.

package/templates/firebase/docs/revenuecat-setup.es.md

@@ -0,0 +1,341 @@
+# Configurar RevenueCat
+
+Guía para activar suscripciones y compras en la app después de que la CLI generó el proyecto.
+
+---
+
+## Lo que la CLI ya hizo por ti
+
+| Ya listo | Lo que falta |
+|----------|--------------|
+| Instaló `purchases_flutter` | Crear cuenta en RevenueCat |
+| Configuró las claves en `Makefile` y `.vscode/launch.json` | Crear Productos, Entitlements y Offerings en el panel RC |
+| Generó el código del paywall y del repositorio de suscripciones | Registrar la URL del webhook en el panel RC |
+| Firebase: desplegó la Cloud Function del webhook | — |
+| Supabase: desplegó la Edge Function del webhook | — |
+
+> Las claves quedan en `.vscode/launch.json` y `Makefile`. Ambos archivos están en `.gitignore` — las claves nunca van al repositorio.
+
+---
+
+## Paso 1 — Crear cuenta y proyecto en RevenueCat
+
+1. Accede a [app.revenuecat.com](https://app.revenuecat.com) → crea una cuenta gratuita
+2. Crea un proyecto → ponle un nombre (ej: nombre de tu app)
+
+---
+
+## Paso 2 — Crear la app en RevenueCat
+
+Dentro del proyecto:
+
+**Para empezar (Test Store — sin Apple/Google)**
+
+Project → Apps → **+ Add app** → selecciona **Test Store** → copia la clave `test_xxx`.
+
+Pega esa misma clave cuando la CLI la solicite tanto para iOS como para Android (o actualiza manualmente los archivos si el proyecto ya existía).
+
+**Para producción**
+
+Crea una app separada por plataforma:
+- **App Store** → clave empieza con `appl_`
+- **Google Play** → clave empieza con `goog_`
+
+> ⚠️ **Regla crítica:** el tipo de app y el prefijo de clave deben coincidir. `Test Store` → `test_`, `App Store` → `appl_`, `Google Play` → `goog_`. Usar la clave incorrecta causa `INVALID_CREDENTIALS`.
+
+---
+
+## Paso 3 — Crear Productos, Entitlements y Offerings
+
+Puedes hacerlo desde el panel o pedirle a Claude con el MCP de RevenueCat ("Crea un producto `premium_monthly`, entitlement `premium_access` y offering `default`").
+
+**Desde el panel RC** (misma URL para todos los proyectos):
+
+1. [app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Products** → `+ New`
+   - Crea los planes (ej: `premium_monthly`, `premium_annual`)
+   - Los IDs deben ser **idénticos** a los que crearás en App Store / Google Play
+
+2. **Entitlements** → `+ New`
+   - Crea `premium_access` → haz clic en el entitlement → **Attach** → selecciona los productos
+
+3. **Offerings** → `+ New`
+   - Crea `default` → entra al offering → `+ Add package` → selecciona los productos
+
+> **Sobre los IDs de productos:** deben ser idénticos carácter por carácter. `premium_monthly` en App Store y `premium_monthly` en RC — cualquier diferencia y el producto no aparece en el paywall.
+
+---
+
+## Paso 4 — Configurar el webhook
+
+El webhook mantiene la tabla `subscriptions` de tu base de datos actualizada en cada compra, renovación o cancelación.
+
+**La URL de la función ya fue desplegada por la CLI. Solo necesitas registrarla en RevenueCat.**
+
+Encuentra la URL de la función:
+
+| Backend | Dónde encontrar la URL |
+|---------|------------------------|
+| **Supabase** | `https://TU_PROJECT_REF.supabase.co/functions/v1/revenuecat-webhook` |
+| **Firebase** | [Firebase Console → Functions](https://console.firebase.google.com/project/_/functions) → `subscriptionsOnRcPremiumUpdate` → copia la URL |
+
+Regístrala en RevenueCat:
+
+1. [app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Integrations** → **Webhooks** → `+ Add webhook`
+2. Rellena:
+
+| Campo | Qué poner |
+|-------|-----------|
+| **Webhook name** | Cualquier nombre (ej: `firebase` o `supabase`) |
+| **Webhook URL** | La URL de la función de arriba |
+| **Authorization header value** | `Bearer ` + el valor de `REVENUECAT_WEBHOOK_KEY` (ej: `Bearer rc_wh_abc123`) |
+| **Environment** | `Both Production and Sandbox` |
+| **Events filter** | `All apps` / `All events` |
+
+3. Haz clic en **Send test event** — si devuelve `200 OK`, está funcionando.
+
+> ⚠️ **Header de autorización:** el campo debe contener `Bearer ` seguido de tu token — incluyendo el espacio. La función rechaza cualquier header que no siga ese formato.
+
+---
+
+## Paso 5 — iOS: configurar en App Store Connect
+
+Necesario cuando salgas del Test Store y quieras probar con compras reales en iPhone.
+
+**Costo:** USD $99/año (Apple Developer Program)
+
+Sigue exactamente este orden — omitir cualquier paso hace que los productos no aparezcan.
+
+**1. Crear la cuenta Apple Developer**
+
+[developer.apple.com](https://developer.apple.com) → crea la cuenta y paga los USD $99/año.
+
+**2. Configurar negocios — obligatorio para que el Sandbox funcione**
+
+> ⚠️ **Este es el paso más ignorado y el más bloqueante.** Sin él, el Sandbox devuelve lista vacía de productos aunque hayas hecho todo bien: cuenta RC, producto creado, Sandbox Tester configurado en el iPhone. Nada funciona.
+
+[appstoreconnect.apple.com](https://appstoreconnect.apple.com) → menú superior → **Agreements, Tax, and Banking**:
+
+- Acepta el **Paid Applications Agreement** (contrato de asociación con Apple)
+- Registra la **cuenta bancaria** donde recibirás los pagos
+- Completa los **formularios fiscales** (país, tipo de persona física o jurídica)
+- Acepta las **conformidades** requeridas
+- Si vas a vender en Europa: completa la información pública adicional exigida
+
+Después de completar todo, **espera de 4 a 6 horas** para que las configuraciones se propaguen. Solo después de ese tiempo el Sandbox funcionará correctamente. Intentar antes devuelve lista vacía o errores genéricos.
+
+**3. Crear la app en App Store Connect**
+
+[appstoreconnect.apple.com](https://appstoreconnect.apple.com) → **My Apps** → `+` → **New App** → usa el mismo Bundle ID del proyecto Flutter.
+
+**4. Crear las suscripciones**
+
+App Store Connect → tu app → **Monetización** → **Suscripciones**:
+
+a) **Crear el grupo de suscripciones** (ej: "Premium") — todas las suscripciones quedan dentro de un grupo.
+
+b) **Configurar el período de gracia** (opcional pero recomendado): haz clic en **Período de gracia** → **Editar** → elige la duración. Recomendado: **3 días** para la mayoría de los apps. Sirve para mantener el acceso del suscriptor durante fallas temporales de pago antes de cancelar.
+
+c) **Crear los productos** dentro del grupo:
+   - Agrega los productos con los mismos IDs de RevenueCat (ej: `subscription_monthly_01`)
+   - Completa: precio, duración, idioma de la suscripción y captura de pantalla
+
+d) **Configurar el idioma del grupo** — paso que mucha gente olvida:
+
+   Dentro del grupo → sección **Idioma** → `+` → selecciona el idioma (ej: Inglés EE.UU.) → completa **Nombre de visualización del grupo** (ej: `premium`) → guarda.
+
+   > ⚠️ **Sin este paso los productos quedan atascados en "Missing Metadata"** y nunca avanzan a "Preparar para envío" ni "Listo para enviar", incluso con precio, idioma y captura de pantalla de la suscripción completados. El idioma del **grupo** es distinto al idioma de cada suscripción individual.
+
+e) **Captura de pantalla de la suscripción** (obligatoria para envío a revisión):
+
+   Toma un screenshot del paywall de tu app corriendo en el simulador iOS o en el iPhone físico (`make run-ios` → abre la pantalla premium). Usa esa imagen en el campo **Captura de pantalla** de cada suscripción. El campo **Notas para el equipo de revisión** es opcional — puedes describir brevemente el producto.
+
+Después de completar todo y configurar el idioma del grupo, el estado sale de **Missing Metadata** → **Preparar para envío** → **Listo para enviar**. Cualquiera de los dos últimos ya está correcto.
+
+**5. Crear la app en RevenueCat como App Store**
+
+[app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Apps** → `+ Add app` → **App Store** → copia la clave `appl_xxx`.
+
+Actualiza en los archivos del proyecto:
+- `.vscode/launch.json` → reemplaza `RC_IOS_API_KEY`
+- `Makefile` → reemplaza la misma variable en el bloque `DEFINES`
+
+**6. Crear Sandbox Tester — obligatorio para probar en iPhone físico**
+
+[appstoreconnect.apple.com](https://appstoreconnect.apple.com) → **Users and Access** → pestaña **Sandbox** → **Testers** → `+`
+
+Crea un correo que **no tenga ninguna cuenta Apple asociada** (un Gmail nuevo funciona bien). El correo debe ser accesible — Apple envía un código de verificación para confirmar la cuenta.
+
+> El Sandbox Tester **no es** una cuenta Apple ID real. Es una cuenta exclusiva para pruebas que solo funciona en el entorno Sandbox. Sin ella, el iPhone pide el Apple ID normal y la compra va a producción.
+
+**7. Activar Developer Mode en el iPhone (iOS 16+)**
+
+Obligatorio para ejecutar apps directamente desde Xcode/terminal en el dispositivo físico.
+
+iPhone → **Ajustes** → **Privacidad y Seguridad** → desplázate hasta el final → **Modo Desarrollador** → actívalo → el iPhone reinicia para confirmar.
+
+> Si la opción no aparece, conecta el iPhone al Mac con Xcode abierto al menos una vez — eso desbloqueará el Modo Desarrollador.
+
+**8. Conectar la cuenta Sandbox en el iPhone**
+
+En iPhones modernos (iOS 16+), la cuenta Sandbox está dentro de la sección Desarrollador:
+
+iPhone → **Ajustes** → desplázate hasta el final → **Desarrollador** → desplázate hasta el final de la página → **Cuenta Sandbox** → **Iniciar sesión** → usa el correo y contraseña del Sandbox Tester creado.
+
+> En versiones anteriores de iOS, el camino era Ajustes → App Store → Cuenta Sandbox. En iPhones actuales el camino correcto es a través del menú Desarrollador como se indica arriba.
+
+**9. Configurar la clave P8 (recomendado para sandbox, obligatorio para producción)**
+
+[appstoreconnect.apple.com](https://appstoreconnect.apple.com) → **Users and Access** → **Integrations** → **In-App Purchase** → `+` → descarga el `.p8` → pégalo en RevenueCat en **App Settings** → **In-App Purchase Key**.
+
+> Solo puedes descargar la P8 una vez. Guárdala en un lugar seguro.
+
+**9. Ejecutar en iPhone físico**
+
+```bash
+make run-ios
+```
+
+Haz una compra — aparece el modal real de Apple. Con la cuenta Sandbox activa, la compra no genera ningún cargo.
+
+---
+
+## Paso 6 — Android: configurar en Google Play Console
+
+Necesario cuando salgas del Test Store y quieras probar con compras reales en Android.
+
+**Costo:** USD $25 (pago único)
+
+**1. Crear la cuenta Google Play Developer**
+
+[play.google.com/console](https://play.google.com/console) → crea la cuenta y paga los USD $25.
+
+**2. Configurar el perfil de pago**
+
+Google Play Console → **Configuración** (menú lateral principal) → **Cuenta de desarrollador** → **Perfil de pagos** → completa nombre legal, dirección y datos fiscales.
+
+**3. Crear la app**
+
+Google Play Console → **Crear app** → completa nombre, idioma y categoría.
+
+**4. Publicar en el track de Pruebas Internas — obligatorio para crear suscripciones**
+
+**Pruebas** → **Pruebas internas** → crea el release → sube un APK/AAB firmado → publica.
+
+> La app no necesita estar completa — una versión de desarrollo firmada es suficiente.
+
+**5. Crear las suscripciones**
+
+Google Play Console → tu app → **Monetizar** → **Suscripciones** → `+ Crear suscripción`:
+- Crea los productos con los mismos IDs de RevenueCat
+- Déjalos en estado `Activo`
+
+**6. Crear la Service Account (credencial de RevenueCat para Google)**
+
+a) [console.cloud.google.com](https://console.cloud.google.com) → selecciona el proyecto del app → **APIs y servicios** → **Biblioteca** → activa:
+   - **Google Play Android Developer API**
+   - **Google Play Developer Reporting API**
+
+b) **IAM y administración** → **Cuentas de servicio** → **+ Crear cuenta de servicio**:
+   - Nombre: `revenuecat-service` (o cualquier nombre)
+   - Roles: **Editor de Pub/Sub** + **Lector de supervisión**
+   - Haz clic en **Listo**
+
+c) Haz clic en la cuenta creada → pestaña **Claves** → **Agregar clave** → **Crear nueva clave** → **JSON** → descarga el archivo.
+
+d) Google Play Console → **Configuración** → **Usuarios y permisos** → **Invitar nuevos usuarios**:
+   - Correo: el correo de la Service Account (visible en Cloud Console)
+   - Permisos: **Gestionar pedidos y suscripciones** + **Gestionar informes financieros**
+   - Guarda
+
+> Después de configurar, espera hasta 36 horas para que las credenciales se propaguen. Errores 503/521 en RC durante ese período son normales.
+
+**7. Configurar en RevenueCat con credenciales de Google**
+
+[app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Apps** → `+ Add app` → **Google Play** → sube el archivo JSON → copia la clave `goog_xxx`.
+
+Actualiza en los archivos del proyecto:
+- `.vscode/launch.json` → reemplaza `RC_ANDROID_API_KEY`
+- `Makefile` → reemplaza la misma variable en el bloque `DEFINES`
+
+**8. Agregar License Tester — obligatorio para probar en el dispositivo**
+
+Google Play Console → **Configuración** → **License testing** → agrega el correo de la cuenta Google que está en el dispositivo Android de prueba.
+
+> Usa solo **una cuenta Google** en el dispositivo — varias cuentas causan fallas en las compras.
+
+**9. Ejecutar en dispositivo Android**
+
+```bash
+make run-android
+```
+
+Haz una compra — aparece el modal real de Google Play. En Sandbox, las suscripciones mensuales se renuevan cada 5 minutos.
+
+---
+
+## Checklist rápido
+
+### Test Store (sin Apple/Google)
+
+- [ ] Cuenta y proyecto creados en RevenueCat
+- [ ] App creada como **Test Store** — clave `test_xxx` pegada
+- [ ] Productos, Entitlements y Offerings configurados en RC
+- [ ] Webhook registrado en RC y probado (`200 OK`)
+- [ ] La compra de prueba activa el entitlement correctamente
+
+### iOS (App Store Connect)
+
+- [ ] Apple Developer Program activo (USD $99/año)
+- [ ] Paid Applications Agreement firmado
+- [ ] Cuenta bancaria validada en App Store Connect
+- [ ] App creada en App Store Connect con Bundle ID correcto
+- [ ] Grupo de suscripciones creado con idioma configurado (sin esto los productos quedan en "Missing Metadata")
+- [ ] Suscripciones creadas con IDs idénticos a RevenueCat, con precio, idioma y captura de pantalla completos
+- [ ] Estado de las suscripciones en **Listo para enviar**
+- [ ] App creada en RC como **App Store** — clave `appl_xxx` actualizada en los archivos
+- [ ] Sandbox Tester creado en App Store Connect → Users and Access → Sandbox (correo sin cuenta Apple)
+- [ ] Developer Mode activo en el iPhone (Ajustes → Privacidad y Seguridad → Modo Desarrollador)
+- [ ] Cuenta Sandbox conectada en iPhone (Ajustes → Desarrollador → Cuenta Sandbox)
+- [ ] Clave P8 configurada en RC
+- [ ] Compra probada en iPhone físico
+
+### Android (Google Play)
+
+- [ ] Google Play Developer activo (USD $25)
+- [ ] Perfil de pago configurado
+- [ ] App creada y publicada en el track de Pruebas Internas
+- [ ] Suscripciones creadas con IDs idénticos a RevenueCat
+- [ ] APIs activadas en Google Cloud Console
+- [ ] Service Account creada, JSON descargado e invitada en Google Play
+- [ ] JSON de la Service Account subido a RC — clave `goog_xxx` actualizada en los archivos
+- [ ] License Tester agregado en Google Play Console
+- [ ] Solo una cuenta Google en el dispositivo de prueba
+- [ ] Compra probada en dispositivo Android físico
+
+---
+
+## Errores comunes
+
+**`INVALID_CREDENTIALS`** — el tipo de app en RC y el prefijo de la clave no coinciden. `Test Store` requiere clave `test_`, `App Store` requiere `appl_`, `Google Play` requiere `goog_`.
+
+**Productos no aparecen en el paywall** — los IDs no son idénticos entre la tienda y RC, o el Paid Applications Agreement no está firmado (iOS), o la app no está publicada en el track interno (Android).
+
+**Sandbox devuelve lista vacía (iOS)** — configuración de negocios incompleta en App Store Connect → Agreements, Tax, and Banking. Verifica: Paid Applications Agreement aceptado, cuenta bancaria registrada, formularios fiscales completados, conformidades aceptadas. Después de completar todo, espera de 4 a 6 horas antes de probar.
+
+Verifica con:
+
+```bash
+kasy doctor
+```
+
+El `kasy doctor` muestra una sección **RevenueCat** automáticamente cuando el proyecto usa la feature. Ejemplo de salida:
+
+```
+RevenueCat
+  ✓ Claves de API configuradas (iOS + Android)
+  ⚠ Usando claves Test Store (test_) — reemplaza por appl_ y goog_ para producción
+  ✓ URL del webhook (pega en RevenueCat → Integrations → Webhooks):
+     https://TU_PROJECT_REF.supabase.co/functions/v1/revenuecat-webhook
+```
+
+> Para proyectos Firebase, el `kasy doctor` indica dónde encontrar la URL en Firebase Console en lugar de mostrarla directamente.