# 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 `.env` (test/iOS prod/Android prod) | 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 `.env` en la raíz (fuente de verdad) y reflejadas en `.vscode/launch.json` + `Makefile`. Todos en `.gitignore` — nunca van al repositorio.

### ¿Qué clave usar?

La CLI pregunta **tres claves opcionales** (al menos una es obligatoria):

| Variable | Prefijo | Uso |
|---|---|---|
| `RC_TEST_KEY` | `test_` | Test Store. **Una sola clave**, sirve para iOS+Android. Usada automáticamente en simulador/emulador. |
| `RC_IOS_PROD_KEY` | `appl_` | App Store (Sandbox + Producción). Usada automáticamente en iPhone físico. |
| `RC_ANDROID_PROD_KEY` | `goog_` | Google Play (Sandbox + Producción). Usada automáticamente en Android físico. |

`kasy run` elige la clave correcta según el dispositivo. Forzar manualmente: `kasy run --rc=test` o `kasy run --rc=prod`.

---

## 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`.

Pégala en el `.env` de la raíz:

```env
RC_IOS_PROD_KEY=appl_xxxxxxxxxxxxxxx
```

`kasy run` usa esta clave automáticamente en iPhone físico (el simulador sigue con `RC_TEST_KEY`).

**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`.

Pégala en el `.env` de la raíz:

```env
RC_ANDROID_PROD_KEY=goog_xxxxxxxxxxxxxxx
```

`kasy run` usa esta clave automáticamente en Android físico (el emulador sigue con `RC_TEST_KEY`).

**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.
