---
name: rapibase
description: Desarrollar contra un proyecto de Rapibase — Postgres (con pgvector), REST, auth de usuarios, storage, realtime, functions TS (endpoints/cron/workers), push, hosting del frontend, servicios propios en cualquier lenguaje (Go, Rust, Zig, Python, Node, Bun) y MCP.
---

# Rapibase

> **ANTES DE TOCAR NADA: si lees esta guía como archivo del repo** (`.claude/skills/rapibase/SKILL.md`,
> `.opencode/skill/rapibase/SKILL.md`, `rapibase.md` o la carpeta de skills de tu usuario), es una copia
> descargada que no se actualiza sola. Hoy la reemplazan los cuatro skills del CLI de Rapibase
> (`rapibase-backend`, `rapibase-deploy`, `rapibase-functions` y `rapibase-observe`), que vienen con cada versión
> del CLI y nombran sus comandos. Con terminal y Node, pregúntale al usuario si quiere pasarse (cambia
> archivos del repo) y, si dice que sí, corre `npx rapibase@latest skill install --yes` (el `--yes` es ese sí; agrega
> `--scope user` si esta copia está en tu carpeta de usuario): instala los cuatro donde los lee tu agente y quita esta copia,
> además de la línea de `rapibase.md` en `AGENTS.md`. Desde entonces, `npx rapibase@latest skill update` los pone al día.
> Sin terminal o sin Node: `get_skill` del MCP devuelve siempre la guía vigente; úsalo en vez de esta copia.
> Si el usuario prefiere conservarla, esta es la versión `095384ba`: la vigente se ve en
> `https://rapibase.com/skill/version` y la guía completa está en `https://rapibase.com/skill.md`.
> Esta guía no contiene ninguna clave: se puede commitear.

**Regla fija: NUNCA publiques a producción (sección Deploy) sin una orden explícita del
usuario en ese momento.** Terminar una tarea o dejar algo "funcionando" no es una orden de deploy.
Publicar es subir el sitio, los servicios propios o empujar a la rama de la que publica un CI. Subir
functions (`deploy_functions`, `rapibase functions deploy`) NO es un deploy en este sentido: es parte de
construir el backend, como crear una tabla, y la forma de probarlas.

## Antes de diseñar: cómo se arma una app en Rapibase

**Elige lo que mejor resuelva lo que el usuario pidió, no lo más grande.** Esta guía describe opciones;
no te pide que uses ninguna en particular. Para la gran mayoría de las apps lo más simple es lo mejor:
la base de datos, auth y storage del proyecto, un frontend estático y **functions en TypeScript** para
la lógica de servidor. Todo eso entra en el plan gratis, es barato de operar y es lo que mejor conoce
cualquier modelo. No asumas que hace falta un plan pago ni varios servicios: arma la app con el plan
que tenga el proyecto y suma piezas solo cuando haya una razón concreta (más abajo, cuándo conviene
un servicio). Si algo no entra en el plan actual, díselo al usuario y que decida él.

Léelo ANTES de elegir rutas o la forma del backend. Todo vive en **un solo dominio** (el del proyecto,
o su dominio propio), sin CORS entre las partes:

| Ruta | Qué la atiende |
|---|---|
| `/api/v1`, `/api/dashboard`, `/api/realtime`, `/api/fn`, `/mcp`, `/_` | **la instancia de Rapibase (reservadas)** |
| la ruta de cada servicio propio (`/api`, `/ml`…) | ese servicio, en el lenguaje que sea |
| `/` | el sitio estático (frontend) o el servicio montado en `/` |

- **Nunca uses las rutas reservadas en tu código.** Todo lo demás de `/api` es tuyo: `/api/orders`,
  `/api/auth/...` propio o `/api/v2` sí; `/api/v1/...` no (es de la instancia).
- **Opción por defecto — functions TS** (`/api/fn/<nombre>`): endpoints, cron, webhooks y workers, sin
  nada que desplegar aparte. Cubren la mayoría de los backends.
- **Un servicio** (sección "Servicios propios") conviene cuando hay una razón concreta: el backend ya existe
  o el usuario lo quiere en otro lenguaje (Go, Python, Rust…), hace falta una librería que solo está en
  ese ecosistema o paquetes de npm, un framework con SSR (Next, Nuxt, SvelteKit), websockets o procesos
  largos propios. El plan gratis ya incluye uno. Un proyecto puede tener varios (Free 1, Pro 3, Team 4),
  cada uno en su lenguaje; se hablan entre ellos por
  `http://<servicio>:8080` y con la instancia por `RAPIBASE_INTERNAL_URL`, sin salir a internet.
- Ejemplos:
  - **SPA (Vite/React) + API en Go:** sitio en `/` + servicio `api` en `/api`. El frontend llama `fetch('/api/orders')`.
  - **SaaS con frontend TS + API Go + worker Python:** sitio en `/`, servicio `api` en `/api`, servicio `ml`
    en `/ml` (o solo interno: lo llama el Go por `http://ml:8080`).
  - **Next.js / Nuxt / SvelteKit con SSR:** servicio `web` en `/` (Node o Bun). Sus route handlers en `/api/...`
    funcionan, salvo bajo las reservadas.
  - **API pública aparte:** el servicio en su subdominio (`subdomain: true` → `api-<subdominio>.rapibase.com`),
    ahí no hay rutas reservadas.
- `get_services` (CLI: `rapibase services`) muestra el mapa de rutas actual del proyecto: míralo antes de elegir.

## Cómo trabajar: MCP o CLI, claves nunca en el chat

Hay dos vías y en ninguna tocas claves:

- **El MCP de Rapibase.** Si lo tienes conectado, es la vía principal (y la única en un chat sin terminal).
  OAuth: el usuario aprueba en el navegador, no hay claves que copiar. URL de cuenta: `https://rapibase.com/mcp` · con
  proyecto por defecto: `https://rapibase.com/mcp?project=<slug>` (las tools actúan sobre ese proyecto si no pasas
  `project`; los demás que el usuario autorizó siguen a tu alcance con `list_projects`, pero úsalos solo
  cuando te los pida por nombre).
- **El CLI de Rapibase**, en un repo con terminal y Node: sirve sin MCP y es lo más directo para subir
  archivos (sitio, functions, servicios). Se arranca con `npx rapibase@latest init`; cómo usarlo, en el
  tema `cli`.

Tools del MCP (su equivalente en el CLI: tema `cli`):

- `list_projects` / `get_project`: proyectos, su modo (read/write), su URL y la consola.
  Si hay varios y el usuario no dijo cuál, PREGUNTA antes de actuar.
- Datos: `list_tables`, `describe_table`, `query_rows`, `insert_row`, `update_row`, `delete_row`,
  `execute_sql` (SQL parametrizado $1,$2; tope de 60 s por llamada, hasta 600 con `timeout_seconds`; con varias sentencias separadas por ; no lleva params ni devuelve filas: el SELECT va en su propia llamada), `query_sql` (lo mismo pero solo lectura: una sentencia, como un usuario de la base que no puede escribir; sirve con conexión de solo lectura), `create_table`, `drop_table`, `list_extensions` (PostGIS, pg_trgm, pg_cron…). RLS: `list_rls`, `set_rls`, `disable_rls`.
  Storage: `list_buckets`, `create_bucket`, `update_bucket`, `delete_bucket`, `list_objects`, `download_object`,
  `upload_object`, `delete_object`, `create_signed_url`, reglas de acceso `list_storage_rules` / `set_storage_rule` / `delete_storage_rule`.
- La API de la instancia, una tool por tipo de operación: `api_get` (leer), `api_post` (crear o ejecutar), `api_update` (PATCH o PUT) y `api_delete`, sobre cualquier endpoint `/api/...` de esta guía; la service key
  la pone el servidor. `deploy_functions`, `get_config` / `set_config`, `restart_project`, `get_logs`,
  `list_deploys` / `create_site_upload` / `activate_deploy`.
- Servicios propios (cualquier lenguaje): `get_services` (mapa de rutas), `create_service_upload`, `update_service` (dónde responde), `activate_service_release`, `restart_service`, `delete_service`, y `get_logs` con `service`.
- Si una tool o un comando responde con `action_url` (falta permiso de escritura, proyecto pausado…), dale ese
  enlace al usuario y reintenta cuando confirme.
- Para DDL (create/drop) y cualquier cosa destructiva, pide confirmación.

Desde la terminal cada tool tiene su comando del CLI: sección "Desde la terminal: el CLI" (en `get_skill`,
el tema `cli`), con cómo probar como visitante o como usuario. **Las tools `api_*` (y `rapibase api`)
actúan con la service key: saltean el RLS.**

Si no hay MCP ni sesión del CLI, pídele al usuario que corra `npx rapibase@latest init` o que conecte el
MCP (pestaña Conectar del proyecto) en vez de pedirle claves. En un servidor o CI sin navegador, el OAuth
se reemplaza por un **token de servidor** que el usuario crea en la consola (Agentes → Tokens para
servidores y CI) y deja en la variable de entorno `RAPIBASE_TOKEN`: el CLI la lee, y la config del MCP lo
referencia como header `Authorization: Bearer ${RAPIBASE_TOKEN}`. Nunca le pidas que te pegue ese token.

### Credenciales: el .env y nada más

Cuando el código de la app o un script necesita claves:

1. **Con el CLI: `rapibase env pull`.** Escribe `.env` sin mostrar los valores, después de agregarlo
   al `.gitignore` (detalles en el tema `cli`).
2. **Sin el CLI (solo MCP), a mano.** Escribe `.env.example` (se commitea) con:
   ```
   # Copia los valores desde la consola: <console_url de get_project> → tarjeta "Archivo .env"
   RAPIBASE_URL=<api_url de get_project>
   RAPIBASE_PROJECT_ID=<id del final de console_url>
   RAPIBASE_ANON_KEY=
   RAPIBASE_SERVICE_KEY=
   RAPIBASE_DB_URL=
   ```
   Asegúrate de que `.env` esté en `.gitignore` y pídele al usuario que copie el bloque de la tarjeta
   "Archivo .env" de la consola y lo pegue en `.env`.
3. **Nunca leas, imprimas ni hagas echo de `.env` ni de sus variables**, y nunca le pidas al usuario
   que pegue una clave en el chat. Tus llamadas de admin van por el MCP o por `rapibase api` /
   `rapibase sql`. El código y los scripts cargan el archivo solos (`node --env-file=.env scripts/seed.js`) y,
   en la shell, los comandos usan las variables sin mostrarlas:
   `set -a; . ./.env; set +a; curl ... -H "apikey: $RAPIBASE_SERVICE_KEY"`

En esta guía, `{anon-key}` = `$RAPIBASE_ANON_KEY`, `{service-key}` = `$RAPIBASE_SERVICE_KEY` y `{base-url}` =
`$RAPIBASE_URL`. Los ejemplos con curl muestran lo que manda el código de la app o un script (método, ruta,
headers y cuerpo) y asumen el .env ya cargado. Para hacer lo mismo tú, usa la tool `api_*` del método o
`rapibase api <método> <ruta>`, sin headers: la service key la pone Rapibase.

- ANON_KEY: pública, va en el frontend.
- SERVICE_KEY: SECRETA, acceso total y bypassea RLS. Solo backend/scripts. Jamás en el frontend.

Reglas de auth en TODA la API /api/v1/*:
- Header `apikey: <key>` SIEMPRE obligatorio.
- Con ANON_KEY además se exige `Authorization: Bearer <jwt-del-usuario>`. Única excepción, los visitantes
  sin sesión (apps con navegación sin registro): con la ANON_KEY sola se puede hacer GET en `/api/v1/rest/{tabla}` de
  las tablas en modo RLS `public` o `read_only` y POST en `/api/v1/rpc/{fn}` de las funciones con `GRANT EXECUTE ON FUNCTION fn TO rapibase_anon`.
  Todo lo demás sin JWT da 401. Un token vencido o inválido da 401 (no se trata como visitante): renuévalo.
- Con SERVICE_KEY no hace falta JWT.
- Errores: `{"error":"mensaje"}`. Health: GET {base-url}/api/v1/health
- Tablas `_rapibase_*` son internas: nunca tocarlas (bloqueadas incluso en SQL crudo).

Flujo recomendado: listar las tablas → describir la tabla → operar (MCP: list_tables → describe_table;
CLI: `rapibase tables` → `rapibase tables <tabla>`).

## Desde la terminal: el CLI

Cada tool del MCP tiene su comando:

| Tool del MCP | Comando del CLI |
|---|---|
| `list_projects`, `get_project` | `rapibase projects`, `rapibase status` |
| `create_project` | `rapibase projects create --name <nombre>` (gratis, o uno que cubre el plan Team del usuario) o `rapibase init --name <nombre>` |
| `execute_sql`, `create_table`, `drop_table` | `rapibase sql '<SQL>'` · `rapibase sql --file schema.sql` |
| `query_sql` | `rapibase sql --read '<SELECT>'` (también con conexión de solo lectura) |
| `list_tables`, `describe_table` | `rapibase tables`, `rapibase tables <tabla>` (también con conexión de solo lectura) |
| `list_extensions` | `rapibase sql --read` sobre `pg_available_extensions` |
| `query_rows`, `insert_row`, `update_row`, `delete_row` | `rapibase api get` / `post` / `patch` / `delete` sobre `/api/v1/rest/{tabla}[/{id}]` |
| `api_get`, `api_post`, `api_update`, `api_delete` | `rapibase api get` / `post` / `patch` / `put` / `delete <ruta>` |
| `list_rls`, `set_rls`, `disable_rls` | `rapibase rls list [tabla]`, `rapibase rls set <tabla> <modo>`, `rapibase rls disable <tabla> --yes` (tras el sí del usuario) |
| tools de buckets, objetos y reglas de storage | `rapibase api` sobre `/api/v1/storage/…` (sección Storage) |
| `deploy_functions` | `rapibase functions deploy [carpeta]` |
| `get_config`, `set_config` | `rapibase config get`, `rapibase config set CLAVE=VALOR` |
| `restart_project` | `rapibase restart` |
| `get_logs` | `rapibase logs [--service <nombre> \| --container db\|storage] [--follow]` |
| `list_deploys`, `create_site_upload`, `activate_deploy` | `rapibase deploys`, `rapibase deploy [carpeta]`, `rapibase deploys activate <release_id>` |
| `get_services`, `create_service_upload`, `update_service` | `rapibase services`, `rapibase services deploy <nombre> [carpeta]`, `rapibase services update <nombre>` |
| `activate_service_release`, `restart_service`, `delete_service` | `rapibase services activate <nombre> <release_id>`, `rapibase services restart <nombre>`, `rapibase services rm <nombre> --yes` |
| — (solo CLI) | `rapibase api … --anon` (visitante), `rapibase api … --jwt <token>` (usuario logueado) |
| — (solo CLI) | `rapibase skill uninstall [--agent …]`, `rapibase mcp remove` (solo si el usuario lo pide) |

- `rapibase sql`: SQL entre comillas simples (así la shell no expande `$1`), `--params '<array JSON>'` para
  `$1`, `$2`… y `--timeout <segundos>` (60 por defecto, hasta 600). Mismas reglas que `execute_sql`.
  Sin `--read` pide permiso de escritura, aun para un SELECT. Para solo leer (y con una conexión de solo
  lectura): `rapibase sql --read '<SELECT>'` (MCP: `query_sql`), una sentencia como un usuario de la base que
  solo puede leer, en una transacción de solo lectura; ve todas las filas (no lo filtra el RLS).
- `rapibase api <método> <ruta>` llama a cualquier ruta bajo `/api/` de la instancia (entre comillas si lleva
  `?` o `&`): `--data '<json>'` o `--data @archivo.json` para el cuerpo, `-F campo=@archivo` para multipart y
  `-o archivo` para guardar la respuesta.
- **`rapibase api` y las tools `api_*` actúan con la service key: saltean el RLS.** Para comprobar lo que ve
  un visitante, `rapibase api get /api/v1/rest/<tabla> --anon` (solo la ANON_KEY); para un usuario logueado,
  inicia sesión con una cuenta de prueba (`rapibase api post /api/v1/auth/signin --anon -d '{"email":"…","password":"…"}'`),
  toma `token` de la respuesta y pásalo: `rapibase api get /api/v1/rest/<tabla> --jwt <token>`. El CLI pone la
  ANON_KEY del lado del servidor: nunca la imprime. El MCP no tiene este modo.

### Empezar y el .env

`npx rapibase@latest init` inicia sesión en el navegador (o crea la
cuenta), crea o elige el proyecto, vincula la carpeta (`.rapibase/project.json`, sin secretos), escribe el
`.env` y conecta tu agente (skills y MCP). Sin TTY: `npx rapibase@latest init --agent <agente> --json`
(`claude`, `cursor`, `opencode`, `codex`, `hermes` u `other`); si responde `login_pending`, dale al
usuario el enlace `verification_uri_complete` y el `user_code`, espera a que apruebe y corre el mismo
comando otra vez (`provisioning` también significa: córrelo otra vez). `rapibase whoami` confirma la
sesión y `rapibase status`, el proyecto vinculado. `rapibase <comando>` es `npx rapibase@latest <comando>` si
no está instalado. Con `--json` responde `{"ok":true,"data":…}` o `{"ok":false,"error":{"code","message",…}}`.
Actúa sobre el proyecto de la carpeta: no pases `--project` salvo que el usuario nombre otro.

`rapibase env pull` escribe o completa `.env` con `RAPIBASE_URL`, `RAPIBASE_ANON_KEY`,
`RAPIBASE_SERVICE_KEY`, `RAPIBASE_DB_URL` y `RAPIBASE_PROJECT_ID` (las demás variables quedan como estaban),
agrega `.env` al `.gitignore` antes de escribir, escribe `.env.example` con los nombres y nunca imprime
valores. Si git ya trackea `.env`, no escribe nada y explica cómo sacarlo del repo.
`--framework vite|next|astro|expo|sveltekit` suma las variables públicas con el prefijo del framework
(`VITE_RAPIBASE_URL`, `NEXT_PUBLIC_RAPIBASE_ANON_KEY`…; la service key y la URL de la base nunca llevan
prefijo público) y `--file .env.local` escribe otro archivo.

## Auth de usuarios de la app — /api/v1/auth/*

El registro público viene ABIERTO en los proyectos de Rapibase Cloud. Si aun así el signup
responde `403 {"error":"Public signup is disabled"}`, alguien puso
`AUTH_SIGNUP_ENABLED=false` en este proyecto: no lo reintentes ni montes un rodeo con
la SERVICE_KEY — arréglalo con `set_config` o `rapibase config set AUTH_SIGNUP_ENABLED=true` (ver "Configuración de la instancia").

```bash
# signup (los admins además pueden crear usuarios con api_post /api/v1/auth/users)
curl -X POST $RAPIBASE_URL/api/v1/auth/signup -H "apikey: $RAPIBASE_ANON_KEY" -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepass","full_name":"Ada"}'
# 201 → {"token":"...","refresh_token":"...","expires_in":3600,"user":{...}}   (el campo es "token", no "access_token")

# signin
curl -X POST $RAPIBASE_URL/api/v1/auth/signin -H "apikey: $RAPIBASE_ANON_KEY" -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepass"}'

# refresh (rotativo: invalida el refresh_token anterior)
curl -X POST $RAPIBASE_URL/api/v1/auth/token -H "apikey: $RAPIBASE_ANON_KEY" -H "Content-Type: application/json" \
  -d '{"refresh_token":"..."}'
```

Otros: /auth/signout, /auth/magiclink, /auth/resend, /auth/verify, /auth/forgot-password, /auth/reset-password.
Gestión de usuarios (service key → por MCP con api_get / api_post / api_update / api_delete, o con `rapibase api get|post|put|delete`): GET/POST /api/v1/auth/users, GET/PUT/DELETE /api/v1/auth/users/:id (GET → {"user":{...}}, 404 si no existe), POST /api/v1/auth/users/bulk.

### Login social web (Google, GitHub, Facebook)

1. El dueño crea la app OAuth en la consola del proveedor (paso a paso en "Crear las credenciales", más abajo) con esta callback URL: `{base-url}/api/v1/auth/oauth/{provider}/callback` (provider: google | github | facebook).
2. Pega las credenciales en la consola de Rapibase Cloud → Configuración → Login social (OAUTH_GOOGLE_CLIENT_ID/SECRET, etc.). Un proveedor queda activo al completar su par. Son credenciales de terceros: que las pegue el usuario en la consola, no en el chat.
3. En el frontend, el botón de login es un enlace simple (sin SDKs):

```html
<a href="/api/v1/auth/oauth/google?redirect_url=https://miapp.com/auth/callback">Entrar con Google</a>
```

4. Tras autorizar, la instancia crea (o encuentra por email, ya verificado) al usuario y redirige a redirect_url con `#access_token=...&refresh_token=...&expires_in=...&type=oauth&provider=google` — el MISMO formato del magic link, así el callback del frontend sirve para ambos.
- `GET /api/v1/auth/oauth/providers` → `{"providers":[...], "native":[...]}`: `providers` lista los de redirect configurados y `native` los que aceptan id_token (`google`, `apple`). Sirve para renderizar solo los botones que funcionan.
- redirect_url debe ser del dominio de la app (APP_URL, AUTH_REDIRECT_URL o un origen listado en CORS_ORIGINS; localhost siempre vale en desarrollo). Solo acepta http(s): en apps móviles usa el login nativo de abajo.
- El dueño ve el estado de cada proveedor (activo o no, variables que faltan, URLs exactas para copiar) en el dashboard de la instancia → Auth → Providers.

### Login nativo en apps móviles: Google y Sign in with Apple

En Flutter, iOS o Android la app NO usa el redirect: inicia sesión con el SDK del proveedor, obtiene un `id_token` y lo canjea por la sesión de Rapibase. Rapibase verifica la firma con las claves públicas del proveedor, el emisor y que el token se haya emitido para uno de los client IDs del proyecto. No hace falta ningún secret.

1. Configuración (la carga el usuario en Rapibase Cloud → Configuración → Login social):
   - Google: `OAUTH_GOOGLE_CLIENT_IDS` = client IDs de Android y/o iOS separados por comas. También se acepta `OAUTH_GOOGLE_CLIENT_ID` (el de web): en Android, `google_sign_in` emite el id_token para el `serverClientId`, que debe ser ese client ID de web.
   - Apple: `OAUTH_APPLE_CLIENT_IDS` = el bundle ID de la app (iOS/macOS) y, para web con Apple JS (`usePopup: true`), el Services ID, separados por comas. Hay que activar "Sign in with Apple" en el App ID.
2. Canje (`apikey: ANON_KEY`, sin JWT):

```
POST /api/v1/auth/oauth/google/token    (o /apple/token)
{"id_token": "<token del SDK>", "nonce": "<nonce crudo, solo si se lo pasaste al SDK>", "name": "<Apple: el nombre solo llega la primera vez>"}
```

3. Responde igual que `/auth/signin`: `{"token","refresh_token","expires_in","provider","user"}`. A partir de ahí todo funciona igual (REST, storage, push con ese JWT).

- Nonce: recomendado en Apple. Genera un nonce crudo, pásale al SDK su SHA-256 (Apple) o el valor tal cual (Google) y manda a Rapibase el CRUDO; se aceptan las dos formas. Si el token trae nonce y no lo mandas, o no coincide, responde 401.
- Vinculación: la identidad (proveedor + `sub`) queda ligada al usuario, así Apple sigue funcionando aunque oculte o cambie el email. En el primer login se vincula por email verificado a una cuenta existente o se crea una nueva. Un email no verificado por el proveedor es 401, y un token sin email en el primer login es 400 (pide el scope `email`).
- Errores: 401 con el motivo (firma, audiencia, expirado, nonce), 404 si el proveedor no está configurado, 502 si no se pudieron bajar las claves del proveedor.
- Apple en Android: el flujo de Apple para Android necesita un redirect web que todavía no está soportado. En Android ofrece Google y email.
- App Store: si la app de iOS ofrece login con Google (u otro proveedor social), Apple exige ofrecer también Sign in with Apple.

### Crear las credenciales: guía para acompañar al usuario

Las credenciales las crea el usuario (humano) en la consola de cada proveedor: tú no tienes acceso. Llévalo paso a paso, de a uno, y confirma cada paso antes de pasar al siguiente. Dale la callback URL exacta de su proyecto (está en el dashboard → Auth → Providers). Al final, que pegue los valores en Rapibase Cloud → Configuración → Login social, nunca en el chat.

**Google (web)**, en https://console.cloud.google.com:
1. Arriba a la izquierda, crea un proyecto nuevo (o elige uno) con el nombre de la app.
2. Menú → "Google Auth Platform" (antes "Pantalla de consentimiento de OAuth") → "Comenzar": nombre de la app, email de asistencia, público "Externo" y email de contacto → Crear.
3. "Público" (Audience): mientras la app esté en "Prueba" solo pueden entrar los usuarios de prueba que agregues ahí. Para que entre cualquiera, pulsa "Publicar app". Con los permisos básicos (email y perfil) Google no pide verificación.
4. "Clientes" → "Crear cliente" → tipo "Aplicación web" → en "URIs de redireccionamiento autorizados" agrega la callback URL ("{base-url}/api/v1/auth/oauth/google/callback"). No hace falta llenar "Orígenes de JavaScript".
5. Copia el "ID de cliente" y el "Secreto del cliente" en ese momento: Google muestra el secreto completo una sola vez (si se pierde, se crea otro). Van en OAUTH_GOOGLE_CLIENT_ID y OAUTH_GOOGLE_CLIENT_SECRET.
- Error típico: "redirect_uri_mismatch" = la URI no coincide carácter por carácter (https, subdominio, sin barra final).

**Google (app nativa)**, en el mismo proyecto → Google Auth Platform → Clientes:
1. Hace falta el cliente "Aplicación web" del paso anterior (aunque la app no tenga web): en Android, google_sign_in lo usa como serverClientId y el id_token sale para ese ID.
2. Android: "Crear cliente" → tipo "Android" → nombre del paquete (applicationId) + huella SHA-1. La SHA-1 de desarrollo sale de "cd android && ./gradlew signingReport"; para la app publicada, la de Play Console → Prueba y lanzamiento → Integridad de la app → "Firma de apps" (crea un cliente Android por cada SHA-1).
3. iOS: "Crear cliente" → tipo "iOS" → bundle ID. Agrega el "iOS URL scheme" que te muestra (el client ID invertido) en Info.plist.
4. Los client IDs de Android/iOS van en OAUTH_GOOGLE_CLIENT_IDS, separados por comas. Estos clientes no tienen secreto.

**Sign in with Apple**, en https://developer.apple.com/account (requiere la membresía paga del Apple Developer Program):
1. Certificates, Identifiers & Profiles → Identifiers → el App ID de la app → marca "Sign in with Apple" → Save.
2. En Xcode: target → Signing & Capabilities → "+ Capability" → "Sign in with Apple".
3. OAUTH_APPLE_CLIENT_IDS = el bundle ID. No hace falta clave privada ni Team ID.
4. Solo para web con Apple JS: Identifiers → "+" → "Services IDs" → crea uno, actívale Sign in with Apple, agrega el dominio y la URL de retorno de la web, y suma ese Services ID a OAUTH_APPLE_CLIENT_IDS.
- Apple manda el nombre y el email solo en el primer login (el usuario puede elegir ocultar su email: llega un @privaterelay.appleid.com).

**GitHub**, en https://github.com/settings/developers (o la organización → Settings → Developer settings):
1. "OAuth Apps" → "New OAuth App": nombre, Homepage URL (la web de la app) y "Authorization callback URL" = "{base-url}/api/v1/auth/oauth/github/callback" → Register application.
2. Copia el "Client ID"; pulsa "Generate a new client secret" y cópialo enseguida (se muestra una vez). Van en OAUTH_GITHUB_CLIENT_ID y OAUTH_GITHUB_CLIENT_SECRET.

**Facebook**, en https://developers.facebook.com/apps:
1. "Crear app" → caso de uso "Autenticar y solicitar datos de usuarios con el inicio de sesión con Facebook" → nombre y email → Crear.
2. Casos de uso → Inicio de sesión con Facebook → Personalizar → Configuración → en "URI de redireccionamiento de OAuth válidos" agrega "{base-url}/api/v1/auth/oauth/facebook/callback" → Guardar. En Permisos, que "email" esté agregado.
3. Configuración de la app → Básica: copia "Identificador de la app" y "Clave secreta" (botón Mostrar). Van en OAUTH_FACEBOOK_CLIENT_ID y OAUTH_FACEBOOK_CLIENT_SECRET.
4. Mientras la app esté en modo desarrollo solo entran los que tengan un rol en ella. Para publicarla (modo "Activo") Meta pide URL de política de privacidad y de eliminación de datos.

## REST CRUD — /api/v1/rest/{tabla}

Por MCP: la tool `api_*` del método (`api_get`, `api_post`…) con el mismo path; con el CLI,
`rapibase api get|post|patch|delete` con el mismo path (p. ej. `rapibase api get "/api/v1/rest/products?price.gt=100"`). Por curl:

```bash
# SELECT con filtros: <columna>.<op>=<valor>  (op: eq neq gt gte lt lte like ilike is in)
curl "$RAPIBASE_URL/api/v1/rest/products?page=1&page_size=50&order_by=created_at&order=desc&select=id,name,price&price.gt=100" \
  -H "apikey: $RAPIBASE_SERVICE_KEY"
# → {"data":[...],"page":1,"page_size":50,"total_rows":N,"total_pages":N}   (sin filas: "data":[])

# Visitante sin sesión: ANON_KEY sola, solo GET y solo tablas en modo RLS public o read_only
curl "$RAPIBASE_URL/api/v1/rest/products?page_size=20" -H "apikey: $RAPIBASE_ANON_KEY"

curl -X POST $RAPIBASE_URL/api/v1/rest/products -H "apikey: $RAPIBASE_SERVICE_KEY" -H "Content-Type: application/json" -d '{"name":"X","price":9.99}'
curl -X PATCH $RAPIBASE_URL/api/v1/rest/products/1 -H "apikey: $RAPIBASE_SERVICE_KEY" -H "Content-Type: application/json" -d '{"price":14.99}'
curl -X DELETE $RAPIBASE_URL/api/v1/rest/products/1 -H "apikey: $RAPIBASE_SERVICE_KEY"
```

IMPORTANTE: el formato de filtro es `columna.op=valor` (p. ej. `status.eq=active`) y el orden es `order=asc|desc`. NO uses `filter=col:op:val` ni `order_dir` aunque aparezcan en docs viejas. `page_size` máx 1000. Las vistas se leen igual.

## RPC — funciones Postgres

```bash
# el body JSON se mapea a argumentos nombrados de la función
curl -X POST $RAPIBASE_URL/api/v1/rpc/top_products -H "apikey: $RAPIBASE_SERVICE_KEY" -H "Content-Type: application/json" -d '{"p_limit":10}'
```

Crear la función con execute_sql del MCP, `rapibase sql` o el SQL editor del dashboard. Probarla desde la terminal: `rapibase api post /api/v1/rpc/top_products --data '{"p_limit":10}'`. Es la manera Rapibase de hacer "functions": lógica cerca de los datos, sin deploy.
Responde un array de filas; sin filas responde `[]`.
Si la función falla (RAISE EXCEPTION, constraint, permisos) responde JSON con las partes por separado:
```json
{"error":"saldo insuficiente","code":"P0001","message":"saldo insuficiente","detail":"...","hint":"..."}
```
`detail` y `hint` solo vienen si la función los puso (`RAISE EXCEPTION '...' USING DETAIL = '...', HINT = '...'`). Status: 403 sin permiso (42501), 404 función inexistente, 409 clave duplicada (23505), 504 timeout, 400 el resto (incluido RAISE). Para distinguir errores propios en la app, usa `USING ERRCODE = 'P0001'` o un código propio y lee `code`.

Desde la app: con ANON_KEY + JWT, la función corre como el usuario (con RLS). Para que la llame un visitante SIN sesión
hay que abrirla explícitamente; si no, da 401:
```sql
GRANT EXECUTE ON FUNCTION top_products(int) TO rapibase_anon;
```
Corre como `rapibase_anon`: solo ve las tablas en modo `public` o `read_only` (salvo que la declares `SECURITY DEFINER`, que corre con los permisos del dueño: entonces filtra tú lo que devuelve).

## Storage — /api/v1/storage/*

Archivos en buckets. Las reglas (bucket público o privado, límites, dueño de cada archivo) viven en el
Postgres de la instancia y es la propia instancia la que sirve los archivos: nunca hay una URL de S3 de por medio.

- **Bucket público**: cualquiera lee sus archivos en `{base-url}/api/v1/storage/public/{bucket}/{ruta}`, sin keys
  (lo que va en un `<img src>`). Subir, reemplazar y borrar siguen exigiendo permiso.
- **Bucket privado** (el default): se lee con la SERVICE_KEY, con ANON_KEY + JWT del usuario **dueño** del
  archivo, o con una **URL firmada** (temporal, sin keys).
- **Dueño**: lo que sube un usuario con ANON_KEY + JWT queda a su nombre; solo él puede leerlo (si el bucket es
  privado), reemplazarlo o borrarlo. Lo subido con la SERVICE_KEY no tiene dueño, salvo que pases `owner_id`.
- **Límites por bucket**: `file_size_limit` (bytes) y `allowed_mime_types` (`["image/*","application/pdf"]`).
  Una subida que no cumple responde 413 o 415 con el motivo.
- Las descargas soportan `Range` (video y audio se pueden adelantar), `ETag`/304 y caché. HTML y SVG se sirven
  aislados (CSP sandbox): un archivo subido nunca ejecuta scripts en el dominio de la instancia.

Por MCP: `create_bucket` / `update_bucket` / `delete_bucket` / `list_buckets`, `upload_object` / `list_objects` /
`download_object` (hasta 10 MB) / `delete_object` (una ruta terminada en `/` borra la carpeta entera) y
`create_signed_url`. Con el CLI, `rapibase api` sobre las mismas rutas, sin headers (la service key la pone
Rapibase). Buckets, solo con service key (nombres de ejemplo; por MCP, las tools de buckets de arriba):

```bash
# crear un bucket: público, máx 5 MB por archivo, solo imágenes
rapibase api post /api/v1/storage/buckets --data '{"name":"mi-bucket","public":true,"file_size_limit":5242880,"allowed_mime_types":["image/*"]}'
# cambiar ajustes (solo lo que mandas) / borrar (force=true borra también los archivos)
rapibase api patch /api/v1/storage/buckets/mi-bucket --data '{"public":false}'
rapibase api delete "/api/v1/storage/buckets/mi-bucket?force=true"
```

Archivos, por HTTP: lo que manda un backend o un script con la SERVICE_KEY. Desde tu terminal, lo mismo con
`rapibase api` (`-F file=@foto.png -F path=carpeta/` sube un archivo local y `-o foto.png` guarda una descarga):

```bash
# subir (multipart): path = carpeta, o key = ruta completa. upsert=false responde 409 si ya existe;
# cache_control = segundos de caché del navegador para buckets públicos (default 3600)
curl -X POST $RAPIBASE_URL/api/v1/storage/mi-bucket/upload -H "apikey: $RAPIBASE_SERVICE_KEY" \
  -F "file=@foto.png" -F "path=carpeta/" -F 'metadata={"k":"v"}'
# la respuesta trae url (con keys) y public_url si el bucket es público

# leer / listar / borrar / mover
curl "$RAPIBASE_URL/api/v1/storage/mi-bucket/carpeta/foto.png" -H "apikey: $RAPIBASE_SERVICE_KEY" -o foto.png
curl "$RAPIBASE_URL/api/v1/storage/mi-bucket/list?prefix=carpeta/" -H "apikey: $RAPIBASE_SERVICE_KEY"
curl -X DELETE "$RAPIBASE_URL/api/v1/storage/mi-bucket/carpeta/foto.png" -H "apikey: $RAPIBASE_SERVICE_KEY"
curl -X POST $RAPIBASE_URL/api/v1/storage/mi-bucket/remove -H "apikey: $RAPIBASE_SERVICE_KEY" -H "Content-Type: application/json" -d '{"paths":["a.png","b.png"]}'
curl -X POST $RAPIBASE_URL/api/v1/storage/mi-bucket/move -H "apikey: $RAPIBASE_SERVICE_KEY" -H "Content-Type: application/json" -d '{"from":"a.png","to":"viejos/a.png"}'   # o /copy

# URL firmada para leer sin keys (expires_in en segundos, máx 7 días; "download":true fuerza la descarga)
curl -X POST $RAPIBASE_URL/api/v1/storage/sign/mi-bucket/carpeta/foto.png -H "apikey: $RAPIBASE_SERVICE_KEY" -H "Content-Type: application/json" -d '{"expires_in":3600}'
# varias de una vez: POST /api/v1/storage/sign/mi-bucket con {"paths":[...],"expires_in":3600}
```

Subida directa desde el navegador sin pasar el archivo por tu backend: el usuario logueado pide una URL de
subida firmada (vale 2 horas y el archivo queda a su nombre) y hace PUT con el archivo:

```js
const r = await fetch(RAPIBASE_URL + '/api/v1/storage/upload/sign/mi-bucket/' + userId + '/avatar.png', {
  method: 'POST',
  headers: { apikey: ANON_KEY, Authorization: 'Bearer ' + jwt, 'Content-Type': 'application/json' },
  body: JSON.stringify({ upsert: true }),
})
const { signed_url } = await r.json()
await fetch(signed_url, { method: 'PUT', headers: { 'Content-Type': file.type }, body: file })
```

También: `/search?key=...&value=...`, `/metadata/*` (GET/PATCH), `/api/v1/storage/owner/:owner_id`. Con ANON_KEY + JWT,
listar o buscar devuelve solo lo que las reglas le dejan leer al usuario.

### Reglas de acceso (equipos, compartir, lo que la app necesite)

Más allá de "dueño o público" se agregan **reglas SQL por bucket**: Postgres las aplica como RLS sobre los
archivos, evaluadas como el usuario (ANON_KEY + JWT). La SERVICE_KEY nunca se filtra. Una regla es una condición
sobre la fila del archivo: columnas `bucket_id`, `name` (ruta completa), `owner`, `size`, `mime_type`, `metadata`;
funciones `auth.uid()`, `auth.email()`, `auth.jwt()`, `storage.foldername(name)` (carpetas como text[]),
`storage.filename(name)`, `storage.extension(name)`; y cualquier tabla que el usuario pueda leer (rige su propio RLS).

- Base que ya existe: buckets públicos legibles por todos y, con `owner_access` activo (default), cada usuario
  sube archivos que son suyos y lee/reemplaza/borra los propios.
- Regla **permisiva** (default): suma acceso. Regla **restrictiva** (`"restrictive": true`): requisito extra que
  todo acceso debe cumplir. `owner_access: false` en el bucket = solo valen tus reglas.
- `operation`: `read`, `upload`, `update` (reemplazar archivo o metadata), `delete` o `all`.
- Por MCP: `set_storage_rule` / `list_storage_rules` / `delete_storage_rule`. Con el CLI, `rapibase api` sobre
  `/api/v1/storage/rules` (abajo). Un SQL inválido vuelve con el error de Postgres.

```bash
# carpetas por equipo ("{team_id}/archivo"): los miembros leen y suben, solo quien subió borra
rapibase api patch /api/v1/storage/buckets/docs --data '{"owner_access":false}'
rapibase api post /api/v1/storage/rules --data '{
  "name":"team_read","bucket":"docs","operation":"read",
  "condition":"EXISTS (SELECT 1 FROM team_members m WHERE m.user_id = auth.uid() AND m.team_id::text = (storage.foldername(name))[1])"}'
rapibase api post /api/v1/storage/rules --data '{
  "name":"team_upload","bucket":"docs","operation":"upload",
  "condition":"owner = auth.uid() AND EXISTS (SELECT 1 FROM team_members m WHERE m.user_id = auth.uid() AND m.team_id::text = (storage.foldername(name))[1])"}'
rapibase api post /api/v1/storage/rules --data '{
  "name":"team_delete","bucket":"docs","operation":"delete","condition":"owner = auth.uid()"}'

# sobre el modelo de dueño: cada usuario solo puede subir dentro de su carpeta "{su id}/"
rapibase api post /api/v1/storage/rules --data '{
  "name":"own_folder","bucket":"avatars","operation":"upload","restrictive":true,
  "condition":"(storage.foldername(name))[1] = auth.uid()::text"}'

rapibase api get "/api/v1/storage/rules?bucket=docs"
rapibase api delete /api/v1/storage/rules/team_delete
```

Si la regla consulta una tabla, esa tabla tiene que ser legible por el usuario (p. ej. `team_members` con RLS
`owner` sobre `user_id`: cada uno ve sus membresías) — o usa una función `SECURITY DEFINER` creada con `execute_sql` o `rapibase sql`.

## Realtime — WebSocket

URL: `{base-url}/api/realtime/v1?apikey=<key>&token=<jwt-del-usuario>` (ws:// o wss:// según el esquema de la instancia; subprotocolo `rapibase-realtime.v1+json` OBLIGATORIO: `new WebSocket(url, ['rapibase-realtime.v1+json'])`). En el frontend la key es la ANON_KEY (de la variable de entorno del build, nunca escrita a mano en el código).

```json
{"type":"subscribe","ref":"s1","channel":"room:42","config":{
  "postgres_changes":[{"event":"INSERT","schema":"public","table":"messages",
    "filter":{"op":"and","conditions":[{"column":"room_id","op":"eq","value":42}]}}],
  "broadcast":{"self":false},"presence":{"key":"user_7"}}}
```

EL JWT NO ES OPCIONAL para escuchar cambios de tablas: con ANON_KEY rige la misma regla que en
el REST — la clave pública sola solo lee lo público. Sin token solo llegan las tablas en modo RLS
`public` o `read_only`, más broadcast, presence y rpc (que no tocan la base). Si te suscribes y no
llega NADA, mira esto antes que ninguna otra cosa. Con SERVICE_KEY llega todo, pero eso jamás
va en un frontend.

Eventos entrantes tipo `postgres_changes` traen el campo `db_event` (INSERT|UPDATE|DELETE), `new` y `old`. Otros frames: broadcast, presence_track/untrack, rpc, heartbeat, set_auth.

Presence: `config.presence.key` solo dice con qué clave te identificas en el canal; NO te marca como conectado. Para aparecer en la lista de presentes, después del subscribe manda `{"type":"presence_track","channel":"room:42","payload":{"nombre":"Ana"}}` (el payload es tu estado: lo reciben los demás). Llegan `presence_state` (lista completa al entrar) y `presence_diff` (joins/leaves). Para salir sin desconectar: `presence_untrack`; al cerrar el socket sales solo. Filtros: JSON estructurado (eq neq lt lte gt gte in nin is like ilike contains contained_by match), no DSL de PostgREST.

## RLS (seguridad por filas)

Modos por tabla: owner (cada usuario ve solo sus filas vía owner_column = auth.uid()), authenticated, public, read_only, custom. owner, authenticated y public SIEMPRE dejan escribir a los usuarios logueados (aplicarlos devuelve ese permiso aunque antes se haya quitado). Para datos que todos leen y solo escribe el servidor (catálogos, precios, configuración) usa read_only: lo escriben solo la SERVICE_KEY, el dashboard y las functions. Se configuran DESDE EL MCP con `list_rls` / `set_rls` / `disable_rls`, desde el CLI con `rapibase rls list [tabla]`, `rapibase rls set <tabla> <modo>` (`--owner-column <col>` en modo owner) y `rapibase rls disable <tabla> --yes` (pide confirmación al usuario antes y pasa `--yes` solo tras su sí: todas las keys vuelven a ver todas las filas), o en el dashboard de la instancia. Con SERVICE_KEY el RLS NO aplica — por eso nunca va en un frontend. En SQL de políticas está disponible `auth.uid()`.

El REST, el RPC y el realtime aplican el MISMO RLS (el realtime, evento por evento y por suscriptor):

| Modo de la tabla | anon (sin JWT) | usuario autenticado | SERVICE_KEY |
|---|---|---|---|
| *sin configurar* | ✗ | ✓ | ✓ |
| public | ✓ | ✓ | ✓ |
| read_only | ✓ solo leer | ✓ solo leer | ✓ |
| authenticated | ✗ | ✓ | ✓ |
| owner | ✗ | solo sus filas | ✓ |
| custom | ✗ | ✗ | ✓ |

- Una tabla recién creada NO es pública: llega a usuarios logueados, no a anónimos.
- `public` y `read_only` son la salida deliberada para feeds sin login (seguimiento de pedido, marcadores).
- `custom` NO se entrega por realtime salvo con SERVICE_KEY: sus políticas son SQL que evalúa
  Postgres y el realtime no puede ejecutarlas. Si necesitas una tabla así en vivo, usa una vista
  en modo owner/public, o manda el cambio tú con broadcast desde una function.
- Un cambio de RLS tarda hasta 30 s en llegar a los suscriptores ya conectados.

## Functions — TypeScript del lado servidor (endpoints, cron, workers)

Código TS que corre DENTRO de la instancia: endpoints custom, tareas
programadas y workers de cola. Las APIs son SÍNCRONAS (los handlers async
también funcionan; no hay I/O asíncrono real). Types completos de todas
las APIs: `api_get /api/v1/functions/types` (CLI: `rapibase api get /api/v1/functions/types`)

```ts
// functions/misfunctions.ts — un archivo puede registrar varias functions.
// Nombres y tablas son EJEMPLO: usa los del dominio de tu app.
fn.http("mi-endpoint", (req) => {
  const rows = db.query("SELECT count(*)::int AS total FROM tu_tabla WHERE col = $1", req.query["valor"])
  const r = fetch("https://api.de-un-tercero.com/recurso", {
    method: "POST",
    headers: { Authorization: "Bearer " + env.get("FN_API_KEY") },
    body: { total: rows[0].total },   // objeto → JSON automático
  })
  if (!r.ok) return { status: 502, json: { error: "el servicio externo falló" } }
  jobs.enqueue("mi-worker", { total: rows[0].total })  // trabajo en 2º plano
  return { total: rows[0].total, externo: r.json() }   // objeto → JSON 200
})
// Respuesta explícita: un objeto con SOLO status/headers/json/body y status numérico (100–599).
// Cualquier otro objeto sale tal cual como JSON 200, aunque tenga una clave "status" ({status:"activo", ...}).

fn.cron("mi-tarea-nocturna", "0 3 * * *", () => {   // cron estándar 5 campos
  db.exec("DELETE FROM tu_tabla WHERE created_at < now() - interval '30 days'")
})

fn.job("mi-worker", (payload) => {   // worker: reintentos automáticos
  log("procesando", payload)
})
```

- Deploy: tool `deploy_functions` con `[{name, content}]` (recarga al instante; los ERRORES DE COMPILACIÓN vuelven en `errors`: un archivo con error se OMITE y las demás functions siguen cargadas).
  Con el CLI: `rapibase functions deploy [carpeta]` (por defecto `functions/`): sube todos los .ts/.js de la carpeta (sin subcarpetas), recarga al instante y muestra los errores de compilación como `archivo:línea`, con la misma regla de omitir solo el archivo con error. `--prune` además borra del servidor los archivos que ya no están en la carpeta (con TTY pregunta; sin TTY necesita `--yes`: pídele confirmación al usuario antes). Por HTTP: `POST /api/v1/functions` multipart con el campo `file` repetible.
- Listar: `rapibase functions list` (MCP: `api_get /api/v1/functions`) · Leer el código subido: `GET /api/v1/functions/misfunctions.ts` (`api_get`, o `rapibase api get … -o <archivo>` fuera de `functions/`; texto tal cual + header `X-Content-SHA256` que el CLI no muestra: compara el archivo o su SHA-256 con `sha256sum functions/misfunctions.ts` del repo) · Borrar: `rapibase functions rm misfunctions.ts` (MCP: `api_delete /api/v1/functions/misfunctions.ts`).
- Invocar: cualquier método a `{base-url}/api/fn/mi-endpoint` — auth como el REST (SERVICE_KEY, o ANON_KEY+JWT → llega `req.user`). Con `{public:true}` en fn.http queda SIN auth (para recibir webhooks de terceros). Desde la terminal: `rapibase api post /api/fn/mi-endpoint --data '{"valor":"x"}'` (con `--jwt <token>` llega `req.user`; con `--anon`, como visitante).
- Encolar desde fuera: `POST /api/v1/jobs` `{"name":"mi-worker","payload":{...},"delay_seconds":0}` (`rapibase api post /api/v1/jobs --data '…'`). Inspeccionar la cola (estado, intentos, `last_error`): `GET /api/v1/jobs` (`rapibase api get /api/v1/jobs`).

### Credenciales y secrets dentro de una function

- Las claves de LA PROPIA instancia ya están integradas: `env.get("SERVICE_KEY")`, `env.get("ANON_KEY")` y `env.get("APP_URL")`. Úsalas para llamar con fetch a la API de la misma instancia (push, storage, auth admin…). NUNCA escribas una key hardcodeada en un archivo de functions ni dupliques la service key como secret FN_ — ya la tienes disponible:

```ts
fn.job("avisar-usuario", (p) => {
  const r = fetch(env.get("APP_URL") + "/api/v1/push/send", {
    method: "POST",
    headers: { apikey: env.get("SERVICE_KEY") },
    body: { user_id: (p as any).user_id, title: "Aviso", body: (p as any).texto },
  })
  if (!r.ok) throw new Error(r.body)
})
```

- Secrets `FN_*`: SOLO para credenciales de TERCEROS (Stripe, Resend, FCM…). Los crea el USUARIO en la consola de Rapibase Cloud (pestaña Secrets del proyecto), así la clave del tercero nunca pasa por el chat; tú solo le dices el nombre que espera tu código (p. ej. `FN_RESEND_KEY`). Se leen con `env.get("FN_X")`. Nunca los pongas en el frontend. (`set_config` y `rapibase config set` también los aceptan, pero una clave de un tercero la carga el usuario: nunca la escribas tú desde la conversación.)

### Límites y comportamiento del runtime (evita descubrirlos a golpes)

- Sin npm, sin imports: cada archivo es autocontenido y solo existen las APIs del host (db, fetch, env, jobs, console/log, sleep). No hay filesystem, require ni Node.
- Timeouts DUROS: 30 s por invocación HTTP; 5 min para cron y jobs. `fetch` es síncrono (15 s por defecto, `timeoutMs` máx 60000, respuesta cap 5 MB). `sleep(ms)` máx 10 s.
- Workers: 3 intentos con backoff (30 s × nº de intento); agotados, el job queda `failed` con `last_error` visible en GET /api/v1/jobs.
- Cron: spec estándar de 5 campos (sin segundos), en hora del SERVIDOR (UTC en Rapibase Cloud). Una spec inválida se reporta como error de carga, no falla en silencio.
- `console.log` y los errores de ejecución van a los logs de la instancia: tool `get_logs`, `rapibase logs` (`--follow` para seguirlos) o la pestaña Logs de la consola. Es tu herramienta de debug.
- Subida: máx 512 KB por archivo y 50 archivos por request; nombres de archivo `[a-zA-Z0-9._-]` con extensión .ts/.js; nombres de function/job/cron `[a-z0-9_-]` (máx 64, en minúsculas).
- No devuelvas promesas pendientes: no hay event loop. Un handler async funciona solo porque `await` sobre las APIs síncronas del host resuelve al instante.

## pgvector — embeddings y búsqueda semántica

La extensión `vector` viene activa en la instancia. Patrón completo:

```sql
CREATE TABLE docs (id bigserial PRIMARY KEY, content text, embedding vector(1536));
CREATE INDEX ON docs USING hnsw (embedding vector_cosine_ops);
-- insertar: pasa el embedding como '[0.12,-0.03,...]'::vector
-- top-5 más similares al vector $1:
SELECT id, content, 1 - (embedding <=> $1::vector) AS score
FROM docs ORDER BY embedding <=> $1::vector LIMIT 5;
```

Generar los embeddings le toca a quien llama (o a una function con fetch a
la API de embeddings de OpenAI/Voyage/etc. con un secret FN_). Expón la
búsqueda como función RPC o como function HTTP.

## Email (SMTP) — qué cubre y qué no

El SMTP que se configura en la consola (Configuración → Email) se usa SOLO para los emails de auth de los usuarios de la app: verificación de email, magic links y reset de contraseña. NO existe un endpoint genérico de "enviar email".

Para marketing, notificaciones por correo o cualquier email custom: escribe una FUNCTION que llame a la API HTTP de tu proveedor con `fetch` y la API key guardada como secret `FN_*` (pestaña Secrets de la consola de Rapibase Cloud). Sirve CUALQUIER proveedor con API HTTP — Resend, SendGrid, Mailgun, Postmark, Amazon SES, Brevo, Loops o el que el usuario ya use; el ejemplo usa Resend solo como muestra:

```ts
fn.job("enviar-email", (p) => {
  const r = fetch("https://api.resend.com/emails", {
    method: "POST",
    headers: { Authorization: "Bearer " + env.get("FN_RESEND_KEY") },
    body: { from: "hola@tuapp.com", to: (p as any).to, subject: (p as any).asunto, html: (p as any).html },
  })
  if (!r.ok) throw new Error(r.body)
})
```

## Webhooks (con condiciones)

- Webhooks (dashboard de la instancia → Webhooks): eventos `INSERT:tabla`/`UPDATE:tabla`/`DELETE:tabla` o `TIPO:*`, payload {id, event, table, timestamp, data, old_data}, firma HMAC-SHA256 del body en X-Webhook-Signature (`sha256=<hex>`). Disparan desde el REST, el dashboard y el MCP; los inserts hechos con SQL directo (db.query en functions, RPC, editor SQL, `execute_sql` / `rapibase sql`, import) NO disparan webhooks.
- Usuarios nuevos: el evento `INSERT:auth_users` llega con cada registro (email, Google, Apple, GitHub, Facebook, login nativo o creado por API). `data` es el usuario público (id, email, email_verified, full_name, provider, created_at…; `provider` es email, google, apple, github o facebook), nunca el hash ni tokens. `INSERT:*` NO lo incluye: hay que suscribirse a `INSERT:auth_users` explícitamente.
- Entrega y reintentos: el receptor debe responder 2xx. Si falla (sin conexión, timeout, 408, 429 o 5xx) se reintenta a 1 min, 5 min, 30 min, 2 h y 6 h (6 intentos, persistidos: sobreviven reinicios); otro 4xx se da por fallido sin reintentar. `X-Webhook-Id` (igual al `id` del payload) se repite en cada reintento y en el reenvío manual: guárdalo y descarta los que ya procesaste. `X-Webhook-Attempt` lleva el número de intento. El log del dashboard muestra el estado y tiene "Resend now".
- CONDICIONES por webhook: lista de {column, op, value} (ops: eq neq gt gte lt lte contains is_null not_null), AND entre sí, evaluadas contra el row — solo se entrega si TODAS se cumplen. Se configuran en el mismo modal (o vía POST /api/dashboard/webhooks con campo `filter`, que pide la sesión de admin del dashboard, no la service key: ni `api_post` ni `rapibase api` llegan ahí). Úsalas para recibir solo lo que interesa sin filtrar en el receptor.
- Lógica más compleja (OR, cálculos, consultar otras tablas, llamar a otra API): apunta la URL del webhook a una function propia (`fn.http('nombre', handler, { public: true })` → `{base-url}/api/fn/nombre`), verifica ahí la firma X-Webhook-Signature con el secret y escribe la lógica en TypeScript. No hay código dentro del webhook: las condiciones son solo un filtro.
- Push: ver la sección «Push notifications — contrato completo» (tema `push` de get_skill).

## Push notifications — contrato completo

Push NATIVO a Android (FCM HTTP v1), iOS (APNs) y web (Web Push/VAPID) con la misma API. Todos los errores son JSON `{"error", "field"?}`: un campo que falta o es inválido responde **400** y `field` dice cuál.

**Auth de los endpoints de cliente** (`subscribe`, `unsubscribe`, `subscriptions`, `notifications`):
- `apikey: ANON_KEY` + `Authorization: Bearer <access_token del usuario>` → actúa sobre el usuario del JWT (el `user_id` sale del token; mandar otro `user_id` da 403). Es lo que usa la app.
- `apikey: SERVICE_KEY` → actúa sobre el `user_id` (UUID de `auth_users`) que pases en el body o en `?user_id=`. Si el usuario no existe: 404.
- `POST /api/v1/push/send` es SOLO service key (el JWT de un usuario nunca puede notificar a otros) → desde una function, `api_post`, `rapibase api post` o tu backend.

### Registrar un dispositivo — `POST /api/v1/push/subscribe`

| platform | obligatorios | qué va en `token` |
|---|---|---|
| `android` | `platform`, `token` | el token de FCM: el registration token clásico (`getToken()`) **o** el Firebase Installation ID (`register()` → `onRegistered` en firebase_messaging 17 / Android FCM 25.1+). FCM HTTP v1 acepta los dos en el mismo campo `message.token`; manda el que te dé tu versión del SDK. |
| `ios` | `platform`, `token` | el que tengas: el device token de APNs en hex (se envía directo por APNs, configurando `/push/config/ios`) **o** el token de FCM / Installation ID que da Firebase en iOS (se detecta solo y se envía por FCM, que usa la config de `/push/config/android` y la APNs key cargada en Firebase). Con Flutter + firebase_messaging, manda el token de FCM con `platform:"ios"`. |
| `web` | `platform`, `endpoint`, `keys.p256dh`, `keys.auth` | opcional: por defecto es el `endpoint`. Manda `{platform:"web", ...subscription.toJSON()}`. |

Opcional en todas: `metadata` (objeto libre: modelo, versión de la app…), que se devuelve al listar. Con service key, `user_id`.

```json
POST /api/v1/push/subscribe
{"platform":"android","token":"<fcm token o FID>","metadata":{"app_version":"1.4.0"}}
```

Respuesta: **201** si el dispositivo es nuevo y **200** si ya estaba registrado para ese usuario (actualiza `endpoint`/`metadata`). Es idempotente: llamarlo en cada arranque y en cada refresh del token es lo correcto.
```json
{"message":"Subscribed successfully","created":true,"reassigned_from":0,
 "subscription":{"id":12,"user_id":"…","platform":"android","token":"…","metadata":{…},"created_at":"…"}}
```
**Un token pertenece a un solo usuario.** Si el mismo token ya estaba registrado para OTRO usuario (por ejemplo, dos cuentas en el mismo teléfono), pasa al usuario nuevo y se borra del anterior; `reassigned_from` dice cuántas filas se movieron. Un usuario puede tener hasta **20 dispositivos**: al registrar el 21.º se descarta el que hace más tiempo que no se refresca (`updated_at`), así los tokens abandonados no se acumulan.

### Darse de baja al cerrar sesión — `DELETE /api/v1/push/subscribe`

Body `{"token":"…"}` (en web, el token es el `endpoint`). Si tu cliente HTTP no manda body en un DELETE, usa `?token=…` o `POST /api/v1/push/unsubscribe` con el mismo body. Llámalo ANTES de cerrar la sesión, porque necesita el JWT todavía válido. Con service key, `user_id` es opcional: sin él borra ese token de quien lo tenga. Es idempotente: `{"message":"Unsubscribed","deleted":1}`; un token desconocido devuelve `deleted:0` y status 200.

### Ver los dispositivos registrados (para depurar) — `GET /api/v1/push/subscriptions`

Con service key: `?user_id=<uuid>` lista los de ese usuario; sin `user_id` lista los de todos (los más nuevos primero, `?limit=` hasta 500, 100 por defecto). Con anon key + JWT devuelve los del propio usuario. Respuesta: `{"subscriptions":[{id,user_id,platform,token,endpoint,metadata,created_at}],"count":N}`.

### Enviar — `POST /api/v1/push/send` (service key)

```jsonc
{
  "user_id": "<uuid>",                 // o "user_ids": [...], o "filter": {...}; sin ninguno = broadcast a todos
  "title": "Pedido listo",             // obligatorio
  "body": "Pasa a retirarlo",
  "data": {"order_id": 123, "screen": "orders"},
  "android": {"channel_id": "pedidos", "priority": "high", "icon": "ic_stat_notify",
              "color": "#ff6600", "sound": "default", "tag": "order-123",
              "image": "https://…/foto.png", "click_action": "FLUTTER_NOTIFICATION_CLICK", "ttl_seconds": 3600},
  "ios": {"sound": "default", "badge": 1, "thread_id": "orders", "category": "ORDER"},
  "web": {"icon": "/icon-192.png", "badge": "/badge.png", "image": "…", "url": "/orders/123"},
  "inbox": true                        // por defecto true; false = solo push, no queda en la bandeja
}
```
- Prioridad de destino: `filter` > `user_ids` (máx. 1000; para audiencias más grandes usa `filter`) > `user_id` > broadcast. `filter`: `{role, email_verified, created_after, created_before, metadata:{…}}` sobre `auth_users`. `title` es obligatorio, máx. 255 caracteres. Un `user_id` que no existe da 404.
- `inbox:false` es para avisos que no tienen sentido guardados (códigos, pings silenciosos, "tu pedido está llegando").
- `data` es un objeto JSON. **Android:** FCM exige que todos los valores sean strings, así que los strings van tal cual y el resto (números, booleanos, objetos) se manda serializado como JSON (`123` llega como `"123"`, `{"a":1}` como `"{\"a\":1}"`). **iOS:** las claves van al nivel raíz del payload APNs, junto a `aps`. **Web:** llega tal cual en `event.data.json().data`.
- `android`: `channel_id` es el canal de Android 8+ (lo crea la app, si no existe Android usa el de por defecto); `priority` es `"high"` o `"normal"` (si lo omites, decide FCM); `icon` es el nombre de un drawable de la app; `sound` es `"default"` o un archivo de `res/raw`; `tag` reemplaza a la notificación anterior que tenga el mismo tag. Todo es opcional.
- Web: el service worker recibe `{title, body, icon, badge, image, url, data}`.

Respuesta **201**:
```json
{"message":"Notification sent","target":"user_id","batch_id":"<uuid>","inbox":1,
 "devices":3,"sent":2,"failed":1,"removed":1,
 "errors":[{"subscription_id":9,"user_id":"…","platform":"android","error":"FCM device token unregistered: …","removed":true}],
 "push_warning":"…"}
```
`inbox` son las bandejas donde quedó guardada, `devices` son los dispositivos encontrados, `sent` los que el proveedor aceptó y `failed` los rechazados (`errors` lista hasta 50, con el motivo del proveedor). `devices:0` significa que ese usuario no tiene nada registrado: la notificación queda solo en su bandeja (si `inbox` no es false). **Limpieza automática:** solo se borran los tokens que el proveedor declara muertos (FCM `404`/`UNREGISTERED`, APNs `410`/`BadDeviceToken`, Web Push `404`/`410`); se cuentan en `removed` y aparecen con `removed:true`. Cualquier otro error (credenciales mal configuradas, payload inválido, red) NO borra el token: revisa el `error`.

### Bandeja in-app — `GET /api/v1/push/notifications`

`?unread=true` devuelve solo las no leídas y `?limit=` acepta hasta 100 (50 por defecto). Con service key, `?user_id=` es obligatorio.
```json
{"notifications":[{"id":45,"user_id":"…","title":"…","body":"…","data":{…},"sent_at":"…","read_at":null,"created_at":"…"}],
 "unread_count":3}
```
Para marcar como leída: `PUT /api/v1/push/notifications/{id}/read` (404 si no existe o ya estaba leída). Para marcar todas: `PUT /api/v1/push/notifications/read-all` → `{"count":N}`. Todo envío queda en la bandeja de cada destinatario, también por `filter` o broadcast (incluidos los usuarios sin dispositivo, que la ven al abrir la app), salvo con `inbox:false`. Cada usuario marca su propia copia como leída. En el historial del dashboard cada envío aparece una sola vez con su número de destinatarios.

### Configuración (service key, con `api_get` / `api_post`… o `rapibase api get|post|patch`) — el agente lo deja funcionando sin dashboard
- `POST /api/v1/push/config/web` `{}` genera las VAPID keys y habilita web push. Es IDEMPOTENTE: si ya existen, devuelve la pública sin regenerar; `{"force":true}` las regenera e invalida las suscripciones. La app web lee la clave pública con `GET /api/v1/push/vapid`.
- `POST /api/v1/push/config/ios` `{"key_id","team_id","bundle_id","private_key":"<.p8>","production":true}` (la APNs Auth Key sale de Apple Developer → Keys).
- `POST /api/v1/push/config/android` `{"project_id","client_email","private_key"}` (sale del JSON de service account de Firebase).
- iOS y Android llevan claves privadas de terceros. Si el usuario prefiere no pasarlas por el chat, que las cargue en el dashboard de la instancia, o que las guarde en un JSON fuera del repo y tú lo mandas con `rapibase api post /api/v1/push/config/android --data @<ruta>` (o `/ios`) sin abrirlo.
- `GET /api/v1/push/config` muestra el estado por plataforma (sin secretos) · `PATCH /api/v1/push/config/{platform}/toggle` `{"enabled":bool}` la habilita o deshabilita.
- Alternativa/complemento: una function con fetch a la API del proveedor que prefieras (FCM directo, OneSignal…) con un secret FN_. Sirve para lógicas de campaña que no encajen en /push/send.

### Errores generales de la API
Una ruta inexistente bajo `/api/…` responde **404** JSON `{"error":"route not found","method","path"}`, nunca el HTML del dashboard. Si ves HTML, la URL base está mal.

## Configuración de la instancia y reinicio

Tools `get_config` y `set_config`, o en el CLI `rapibase config get` y `rapibase config set CLAVE=VALOR [CLAVE=VALOR…]`
(las variables SE FUSIONAN con las que ya había; mandar "", o `CLAVE=` en el CLI, borra una).
Existen para que no tengas que frenar y pedirle al usuario que entre a la consola a tocar un flag.

Se aceptan las mismas variables que en la consola (SMTP_*, AUTH_*, CORS_ORIGINS,
JWT_EXPIRY, REFRESH_EXPIRY, OAUTH_*). Cualquier otra se descarta y te la
devuelve en `rejected`. Los secrets FN_* NO van por aquí: los carga el usuario en la consola.
Guardar recrea el contenedor de la app en segundos y los datos no se tocan. El admin del
dashboard NO se cambia por acá: eso sigue exigiendo sesión en la consola.

Sin MCP ni CLI, por HTTP con la service key del .env (sin mostrarla):
`curl -H "Authorization: Bearer $RAPIBASE_SERVICE_KEY" https://rapibase.com/api/projects/$RAPIBASE_PROJECT_ID/config`
(POST con `{"env":{...}}` para cambiar) y `curl -X POST ... https://rapibase.com/api/projects/$RAPIBASE_PROJECT_ID/restart`.

CUÁNDO reiniciar (`restart_project` o `rapibase restart`): casi nunca. Un reinicio no arregla código tuyo mal escrito, y si
algo sigue fallando después de reiniciar una vez, reiniciar de nuevo tampoco lo va a arreglar. Antes
de pedirlo, comprueba que el problema es de la instancia y no de lo que escribiste:

- ¿La instancia responde? `api_get /api/v1/health` (`rapibase api get /api/v1/health`)
- ¿El realtime está entregando eventos? `api_get /api/realtime/metrics` (`rapibase api get /api/realtime/metrics`)
  Si no aparece `realtime_wal_lag_bytes`, el replicador no arrancó: eso sí es la
  instancia. Si aparece y aun así no te llegan cambios, el problema es tu suscripción (empieza
  por el JWT, ver Realtime más arriba).
- ¿Qué dicen los logs? `get_logs` (`rapibase logs`).

Hay un límite de un reinicio cada 3 minutos: si te devuelve 429 con `retry_after_seconds` (en el CLI,
el error `rate_limited` con `retry_after`), espera ese tiempo en vez de reintentar en bucle.

Un servicio propio se reinicia por separado, sin tocar la instancia (mismo release y entorno):
`restart_service` o `rapibase services restart <servicio>`.

## Deploy — publicar el frontend en el proyecto (hosting integrado)

> **Deploy SOLO cuando el usuario lo pide de forma explícita** ("deploya", "publica", "súbelo a
> producción"). Terminar una tarea, arreglar un bug, que "ya funciona" o que el usuario quiera
> probar algo NO es una orden de deploy. Lo que publicas aquí lo ven los usuarios reales del
> proyecto al instante: cada deploy no pedido reemplaza producción con código que quizá nadie revisó.
>
> Cómo se deploya depende de cómo trabaje el usuario — mira el proyecto antes de elegir:
>
> - **Si el proyecto usa GitHub** (remoto en GitHub y/o el workflow de más abajo): el deploy va por
>   `git push` a la rama configurada y GitHub publica. No subas además el build a mano (duplicarías
>   releases) ni pushees a esa rama solo para deployar sin que te lo pidan. Con cambios sin commit
>   o sin push no hay nada publicado todavía: dilo, no lo "arregles" subiendo el build a mano (tampoco
>   con `rapibase deploy --force`).
> - **Si no usa GitHub** (sin repo, o git solo local): el deploy es `rapibase deploy` o la subida por el MCP
>   de abajo, cuando te lo pidan. No exijas un repo, ni GitHub, ni commits para publicar.
> - Probar no es deployar: para probar usa el entorno local del frontend (`npm run dev`, con el proxy
>   de Vite apuntando a $RAPIBASE_URL si hace falta).
> - Ante la duda, pregunta antes. Un "¿lo publico?" cuesta un segundo; un rollback en producción, no.

El proyecto sirve tu frontend en su URL — el MISMO origen que la API. En el código del frontend usa
rutas relativas (`fetch('/api/v1/rest/...')`): cero CORS, cero variables de entorno de URL.

Publicar un build (Vite/Next export/estático):

- **Con el CLI:** `npm run build && rapibase deploy` (o `rapibase deploy ./dist`). Imprime la URL del sitio y el id
  del release. Sin carpeta, la detecta (vite/astro → `dist`, Next con `output: 'export'` → `out`, CRA y
  SvelteKit estático → `build`, Nuxt generate → `.output/public`). Nunca publica secretos: si la carpeta
  tiene `.env*`, `*.pem`, `*.key`, `.git` o `node_modules`, o le falta `index.html`, se niega y nombra los
  archivos (`--exclude <glob>` deja archivos afuera). Sin TTY se frena con cambios sin commitear
  (`--allow-dirty` cuando el usuario pidió publicar lo que hay: no le exijas commits) o si el repo tiene
  el workflow de GitHub Actions de abajo (`--force` solo si el usuario quiere igual un deploy manual;
  nunca para saltarte la regla del `git push`).
- **Con el MCP:** pide `create_site_upload` y ejecuta el comando que devuelve (una URL de un solo uso que
  vence en 10 minutos):

```bash
npm run build && (cd dist && zip -r ../site.zip .) && curl --fail-with-body -F "site=@site.zip" <upload_url>
# 201 → {"release_id":"...","url":"..."}  — activa al instante
```

  En Windows no hay `zip`: usa `command_windows` de la respuesta (arma el zip con el `tar` que trae Windows).

- Cada subida crea una release y la activa (se retienen las últimas 10).
- Listar releases: `list_deploys` o `rapibase deploys`. Rollback en un paso, solo si el usuario lo pide:
  `activate_deploy` con el release_id, o `rapibase deploys activate <release_id>`.
- Fallback SPA: los paths sin extensión sirven index.html (React Router y similares funcionan).
- El dashboard admin de la instancia queda siempre disponible en {base-url}/_/ — no uses `/_` como ruta de tu app.

### Deploy automático con GitHub Actions (recomendado)

GitHub compila; Rapibase solo recibe el artefacto. Configúralo solo cuando el usuario lo pida; desde
entonces, deployar este repo es hacer `git push` a esa rama (ver arriba). Así:

1. Pídele al usuario que cree un **deploy token** en la consola (pestaña Deploys del proyecto) y que
   lo guarde él mismo como secret, sin pegarlo en el chat: `gh secret set RAPIBASE_DEPLOY_TOKEN`
   (gh pide el valor por teclado). El token solo sirve para publicar (el sitio con `rapibase deploy` y
   `rapibase deploys`, y los servicios con `rapibase services …`): NUNCA pongas la SERVICE_KEY en GitHub. Para
   cualquier otro paso en CI (`functions deploy`, `sql`, `api`…) hace falta `RAPIBASE_TOKEN`, el token
   de servidor que el usuario crea en Agentes → Tokens para servidores y CI.

2. La variable del proyecto (no es secreta, puedes ponerla tú):

```bash
gh variable set RAPIBASE_PROJECT --body "<project_id de .rapibase/project.json, o el id del final de console_url>"
```

3. Crea `.github/workflows/rapibase-deploy.yml` (el CLI reconoce ese nombre: un `rapibase deploy` manual en
   este repo avisa que el deploy va por `git push`):

```yaml
name: Deploy a Rapibase
on: { push: { branches: [main] } }
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm }
      - run: npm ci && npm run build
      - name: Publicar en Rapibase
        # en CI el CLI no aplica sus chequeos de "ya hay un workflow" ni de "cambios sin
        # commitear": este workflow es el deploy
        run: npx rapibase@latest deploy ./dist
        env:
          RAPIBASE_DEPLOY_TOKEN: ${{ secrets.RAPIBASE_DEPLOY_TOKEN }}
          RAPIBASE_PROJECT: ${{ vars.RAPIBASE_PROJECT }}
```

Desde entonces: `git push` a main → build en GitHub → deploy automático. Ajusta `./dist` si tu build sale a otra carpeta (p. ej. `build` en CRA, `out` en Next export). El workflow no necesita URL: el CLI sabe dónde está Rapibase, y el token más `RAPIBASE_PROJECT` dicen qué proyecto. Si el repo ya tiene un workflow anterior que sube el zip con curl a `/api/projects/<id>/deploys`, sigue funcionando: no lo cambies si no te lo piden.

## Servicios propios — cualquier lenguaje (Go, Rust, Zig, Python, Node, Bun)

Un servicio es un servidor tuyo que corre al lado de la instancia: un binario de Go/Rust/Zig, una API en
FastAPI, un Express, un Next con SSR… Úsalo cuando las functions TS no alcancen o el usuario lo pida (ver
"Antes de diseñar"); si no, no hace falta. **Las mismas reglas de deploy de arriba**: solo con orden explícita.

- **Varios por proyecto, cada uno en su lenguaje** (Free 1, Pro 3, Team 4). Nombre: minúsculas y números,
  sin guiones (`api`, `web`, `ml`, `worker`).
- **Dónde responde:** en una ruta del dominio del proyecto (por defecto `/<servicio>`; `/` para ser dueño de la
  raíz), en su subdominio `<servicio>-<subdominio del proyecto>`, en un dominio propio (`api.miapp.com`:
  el usuario crea un CNAME al subdominio del proyecto; si es un dominio raíz como `miapp.com`, un ALIAS/ANAME
  o un A, y borra la redirección o parking que traiga el registrador en @ — la respuesta trae la instrucción exacta) o en varios a la vez. Con ruta vacía y sin subdominio
  ni dominio queda **solo interno** (un worker que solo llaman los demás servicios por `http://<servicio>:8080`).
  Se cambia sin redesplegar con `update_service` o `rapibase services update <servicio> --path …` (también
  `--subdomain` y `--custom-domain`), solo cuando el usuario lo pida. El servicio recibe el path completo
  (montado en `/api`, le llega `/api/orders`, no `/orders`). Las rutas reservadas de la instancia nunca le llegan.
- **Debe escuchar en** `0.0.0.0:$PORT` (hoy 8080) y contestar HTTP.
- **Recibe en su entorno:** `DATABASE_URL` (el Postgres del proyecto por la red interna), `RAPIBASE_URL` (URL
  pública), `RAPIBASE_INTERNAL_URL` (la instancia sin salir a internet), `RAPIBASE_ANON_KEY`, `RAPIBASE_SERVICE_KEY`,
  `RAPIBASE_SERVICE` (su nombre), `RAPIBASE_BASE_PATH` (su ruta) y los secrets `FN_*` de la pestaña Secrets.
  **No hardcodees claves.** Para un secret de terceros nuevo, el usuario lo carga en Secrets y los servicios
  se recrean solos.
- **Compilados (Go, Rust, Zig, C):** compila en tu máquina para **Linux x86-64** y sube el binario (más los
  archivos que lea). No se compila nada del lado de Rapibase; si mandas un binario de macOS, Windows o
  arm64, la respuesta trae el comando correcto (el CLI lo comprueba antes de subir).
- **Interpretados (Python, Node, Bun):** sube el código con su lockfile, **sin** `node_modules` ni `.venv`; las
  dependencias se instalan allá (`uv`, `npm ci`, `pnpm`, `bun install`). TypeScript para Node: compílalo antes.
- **`rapibase.json` (opcional, en la raíz de lo que subes):**
  `{"runtime":"binary|python|node|bun","start":"...","path":"/api","subdomain":false}`.
  El runtime se detecta solo (binario Linux, `package.json` con script `start`, `bun.lock`, `requirements.txt`…).
  **Python siempre necesita** `start`, p. ej. `uvicorn main:app --host 0.0.0.0 --port $PORT`. En binarios, `start`
  corre sin shell (nada de `$VARS` ni pipes): el binario lee `PORT` del entorno.
- **Monorepo:** un deploy por servicio, desde la carpeta de cada uno.

Publicar, solo con orden explícita del usuario (el servicio se crea en su primer deploy):

- **Con el CLI:** `rapibase services deploy <servicio> [carpeta] [--binary <archivo>] [--path </prefijo>] [--subdomain]`.
  Python, Node o Bun: `rapibase services deploy api ./api` (la carpeta con el código y su lockfile). Ejemplo en Go:

```bash
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o server .
rapibase services deploy api --binary ./server --path /api
# un binario que lee otros archivos: ponlos en una carpeta con él y publica esa carpeta
```

- **Con el MCP:** `create_service_upload` con `service` (y `path` si no es `/<servicio>`); ejecuta el comando de tu
  lenguaje que devuelve. En Go es de este estilo:

```bash
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o server . && tar czf app.tgz server \
  && curl --fail-with-body -F "app=@app.tgz" <upload_url>
# 201 → {"service":"api","release_id":"...","status":"ready","url":"https://.../api"}
# 422 → {"phase":"build"|"start","error":"...","log":"..."}  ← lee el log, corrige y vuelve a subir
```

- La respuesta llega cuando el servicio ya contesta (instalar dependencias puede tardar unos minutos). Si
  falla, dice la fase (`build` o `start`) y trae el log; la versión anterior sigue sirviendo.
- El tope de servicios del plan vuelve como `plan_limit`: díselo al usuario y que decida él.
- `get_services` o `rapibase services`: mapa de rutas, estado de cada servicio (encendido, dormido, caído con
  exit code o sin memoria) e historial con logs (con los release ids). `get_logs` con `service` o
  `rapibase logs --service <servicio>` para lo que imprime en ejecución.
- Reiniciar sin redesplegar (mismo release y entorno): `restart_service` o `rapibase services restart <servicio>`.
- Rollback: `activate_service_release` o `rapibase services activate <servicio> <release_id>`. Quitar uno:
  `delete_service` o `rapibase services rm <servicio>` (su ruta vuelve a lo que haya debajo). Los dos, solo cuando
  el usuario lo pida.
- Se guardan las últimas 5 releases por servicio. Corren sin root, con RAM y CPU por plan (Free 128 MB,
  Pro 512 MB, Team 1 GB cada uno). En el plan gratis duermen tras 15 minutos sin requests y despiertan con
  el siguiente (Go/Rust/Zig al instante; Python o Node, 1–3 s).
- Desde CI (el workflow de GitHub Actions de "Deploy"): un paso por servicio, desde su carpeta, con el mismo
  deploy token. Un compilado necesita el binario Linux x86-64 de un paso anterior.

```yaml
      - name: Publicar el servicio api
        run: npx rapibase@latest services deploy api ./api
        env:
          RAPIBASE_DEPLOY_TOKEN: ${{ secrets.RAPIBASE_DEPLOY_TOKEN }}
          RAPIBASE_PROJECT: ${{ vars.RAPIBASE_PROJECT }}
```
